/secured/phpDocumentor/phpDocumentor/Converter.inc

Large files files are truncated, but you can click here to view the full file

<?php
/**
 * Base class for all Converters
 *
 * phpDocumentor :: automatic documentation generator
 * 
 * PHP versions 4 and 5
 *
 * Copyright (c) 2001-2006 Gregory Beaver
 * 
 * LICENSE:
 * 
 * This library is free software; you can redistribute it
 * and/or modify it under the terms of the GNU Lesser General
 * Public License as published by the Free Software Foundation;
 * either version 2.1 of the License, or (at your option) any
 * later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * @package    Converters
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2001-2006 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    CVS: $Id: Converter.inc,v 1.39 2007/12/19 02:16:49 ashnazg Exp $
 * @filesource
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @see        parserDocBlock, parserInclude, parserPage, parserClass
 * @see        parserDefine, parserFunction, parserMethod, parserVar
 * @since      1.0rc1
 */
/**
 * Smarty template files
 */
include_once("phpDocumentor/Smarty-2.6.0/libs/Smarty.class.php");
/**
 * Base class for all output converters.
 *
 * The Converter marks the final stage in phpDocumentor.  phpDocumentor works
 * in this order:
 *
 * <pre>Parsing => Intermediate Parsing organization => Conversion to output</pre>
 *
 * A Converter takes output from the {@link phpDocumentor_IntermediateParser} and
 * converts it to output.  With version 1.2, phpDocumentor includes a variety
 * of output converters:
 * <ul>
 *  <li>{@link HTMLframesConverter}</li>
 *  <li>{@link HTMLSmartyConverter}</li>
 *  <li>{@link PDFdefaultConverter}</li>
 *  <li>{@link CHMdefaultConverter}</li>
 *  <li>{@link CSVdia2codeConverter}</li>
 *  <li>{@link XMLDocBookConverter}</li>
 * </ul>
 * {@internal
 * The converter takes output directly from {@link phpDocumentor_IntermediateParser}
 * and using {@link walk()} or {@link walk_everything} (depending on the value of
 * {@link $sort_absolutely_everything}) it "walks" over an array of phpDocumentor elements.}}
 *
 * @package Converters
 * @abstract
 * @author Greg Beaver <cellog@php.net>
 * @since 1.0rc1
 * @version $Id: Converter.inc,v 1.39 2007/12/19 02:16:49 ashnazg Exp $
 */
class Converter
{
    /**
     * This converter knows about the new root tree processing
     * In order to fix PEAR Bug #6389
     * @var boolean
     */
    var $processSpecialRoots = false;
    /**
     * output format of this converter
     *
     * in Child converters, this will match the first part of the -o command-line
     * as in -o HTML:frames:default "HTML"
     * @tutorial phpDocumentor.howto.pkg#using.command-line.output
     * @var string
     */
    var $outputformat = 'Generic';
    /**
     * package name currently being converted
     * @var string
     */
    var $package = 'default';
    /**
     * subpackage name currently being converted
     * @var string
     */
    var $subpackage = '';
    /**
     * set to a classname if currently parsing a class, false if not
     * @var string|false
     */
    var $class = false;
    /**#@+
     * @access private
     */
    /**
     * the workhorse of linking.
     *
     * This array is an array of link objects of format:
     * [package][subpackage][eltype][elname] = descendant of {@link abstractLink}
     * eltype can be page|function|define|class|method|var
     * if eltype is method or var, the array format is:
     * [package][subpackage][eltype][class][elname]
     * @var array
     * @see functionLink, pageLink, classLink, defineLink, methodLink, varLink, globalLink
     */
    var $links = array();

    /**
     * the workhorse of linking, with allowance for support of multiple
     * elements in different files.
     *
     * This array is an array of link objects of format:
     * [package][subpackage][eltype][file][elname] = descendant of {@link abstractLink}
     * eltype can be function|define|class|method|var
     * if eltype is method or var, the array format is:
     * [package][subpackage][eltype][file][class][elname]
     * @var array
     * @see functionLink, pageLink, classLink, defineLink, methodLink, varLink, globalLink
    */
    var $linkswithfile = array();
    /**#@-*/
    /**
     * set to value of -po commandline
     * @tutorial phpDocumentor.howto.pkg#using.command-line.packageoutput
     * @var mixed
     */
    var $package_output;

    /**
     * name of current page being converted
     * @var string
     */
    var $page;

    /**
     * path of current page being converted
     * @var string
     */
    var $path;

    /**
     * template for the procedural page currently being processed
     * @var Smarty
     */
    var $page_data;

    /**
     * template for the class currently being processed
     * @var Smarty
     */
    var $class_data;

    /**
     * current procedural page being processed
     * @var parserPage
     */
    var $curpage;
    /**
     * alphabetical index of all elements sorted by package, subpackage, page,
     * and class.
     * @var array Format: array(package => array(subpackage => array('page'|'class' => array(path|classname => array(element, element,...)))))
     * @uses $sort_absolutely_everything if true, then $package_elements is used,
     *       otherwise, the {@link ParserData::$classelements} and
     *       {@link ParserData::$pageelements} variables are used
     */
    var $package_elements = array();
    /**
     * alphabetical index of all elements
     *
     * @var array Format: array(first letter of element name => array({@link parserElement} or {@link parserPage},...))
     * @see formatIndex(), HTMLframesConverter::formatIndex()
     */
    var $elements = array();
    /**
     * alphabetized index of procedural pages by package
     *
     * @see $leftindex
     * @var array Format: array(package => array(subpackage => array({@link pageLink} 1,{@link pageLink} 2,...)
     */
    var $page_elements = array();
    /**
     * alphabetized index of defines by package
     *
     * @see $leftindex
     * @var array Format: array(package => array(subpackage => array({@link defineLink} 1,{@link defineLink} 2,...)
     */
    var $define_elements = array();
    /**
     * alphabetized index of classes by package
     *
     * @see $leftindex
     * @var array Format: array(package => array(subpackage => array({@link classLink} 1,{@link classLink} 2,...)
     */
    var $class_elements = array();
    /**
     * alphabetized index of global variables by package
     *
     * @see $leftindex
     * @var array Format: array(package => array(subpackage => array({@link globalLink} 1,{@link globalLink} 2,...)
     */
    var $global_elements = array();
    /**
     * alphabetized index of functions by package
     *
     * @see $leftindex
     * @var array Format: array(package => array(subpackage => array({@link functionLink} 1,{@link functionLink} 2,...)
     */
    var $function_elements = array();
    /**
     * alphabetical index of all elements, indexed by package/subpackage
     *
     * @var array Format: array(first letter of element name => array({@link parserElement} or {@link parserPage},...))
     * @see formatPkgIndex(), HTMLframesConverter::formatPkgIndex()
     */
    var $pkg_elements = array();

    /**
     * alphabetical index of all elements on a page by package/subpackage
     *
     * The page itself has a link under ###main
     * @var array Format: array(package => array(subpackage => array(path => array({@link abstractLink} descendant 1, ...)))
     * @see formatLeftIndex()
     */
    var $page_contents = array();

    /**
     * This determines whether the {@link $page_contents} array should be sorted by element type as well as alphabetically by name
     * @see sortPageContentsByElementType()
     * @var boolean
     */
    var $sort_page_contents_by_type = false;
    /**
     * This is used if the content must be passed in the order it should be read, i.e. by package, procedural then classes
     *
     * This fixes bug 637921, and is used by {@link PDFdefaultConverter}
     */
    var $sort_absolutely_everything = false;
    /**
     * alphabetical index of all methods and vars in a class by package/subpackage
     *
     * The class itself has a link under ###main
     * @var array
     * Format:<pre>
     * array(package =>
     *       array(subpackage =>
     *             array(path =>
     *                   array(class =>
     *                         array({@link abstractLink} descendant 1, ...
     *                        )
     *                  )
     *            )
     *      )</pre>
     * @see formatLeftIndex()
     */
    var $class_contents = array();
    /**
     * controls processing of elements marked private with @access private
     *
     * defaults to false.  Set with command-line --parseprivate or -pp
     * @var bool
     */
    var $parseprivate;
    /**
     * controls display of progress information while parsing.
     *
     * defaults to false.  Set to true for cron jobs or other situations where no visual output is necessary
     * @var bool
     */
    var $quietmode;

    /**
     * directory that output is sent to. -t command-line sets this.
     * @tutorial phpDocumentor.howto.pkg#using.command-line.target
     */
    var $targetDir = '';

    /**
     * Directory that the template is in, relative to phpDocumentor root directory
     * @var string
     */
    var $templateDir = '';

    /**
     * Directory that the smarty templates are in
     * @var string
     */
    var $smarty_dir = '';

    /**
     * Name of the template, from last part of -o
     * @tutorial phpDocumentor.howto.pkg#using.command-line.output
     * @var string
     */
    var $templateName = '';

    /**
     * full path of the current file being converted
     */
    var $curfile;

    /**
     * All class information, organized by path, and by package
     * @var Classes
     */
    var $classes;

    /**
     * Flag used to help converters determine whether to do special source highlighting
     * @var boolean
     */
    var $highlightingSource = false;

    /**
     * Hierarchy of packages
     *
     * Every package that contains classes may have parent or child classes
     * in other packages.  In other words, this code is legal:
     *
     * <code>
     * /**
     *  * @package one
     *  * /
     * class one {}
     *
     * /**
     *  * @package two
     *  * /
     * class two extends one {}
     * </code>
     *
     * In this case, package one is a parent of package two
     * @var array
     * @see phpDocumentor_IntermediateParser::$package_parents
     */
    var $package_parents;

    /**
     * Packages associated with categories
     *
     * Used by the XML:DocBook/peardoc2 converter, and available to others, to
     * group many packages into categories
     * @see phpDocumentor_IntermediateParser::$packagecategories
     * @var array
     */
    var $packagecategories;

    /**
     * All packages encountered in parsing
     * @var array
     * @see phpDocumentor_IntermediateParser::$all_packages
     */
    var $all_packages;

    /**
     * A list of files that have had source code generated
     * @var array
     */
    var $sourcePaths = array();

    /**
     * Controls which of the one-element-only indexes are generated.
     *
     * Generation of these indexes for large packages is time-consuming.  This is an optimization feature.  An
     * example of how to use this is in {@link HTMLframesConverter::$leftindex}, and in {@link HTMLframesConverter::formatLeftIndex()}.
     * These indexes are intended for use as navigational aids through documentation, but can be used for anything by converters.
     * @see $class_elements, $page_elements, $function_elements, $define_elements, $global_elements
     * @see formatLeftIndex()
     * @var array
     */
    var $leftindex = array('classes' => true, 'pages' => true, 'functions' => true, 'defines' => true, 'globals' => true);

    /** @access private */
    var $killclass = false;
    /**
     * @var string
     * @see phpDocumentor_IntermediateParser::$title
     */
    var $title = 'Generated Documentation';

    /**
     * Options for each template, parsed from the options.ini file in the template base directory
     * @tutorial phpDocumentor/tutorials.pkg#conversion.ppage
     * @var array
     */
    var $template_options;

    /**
     * Tutorials and Extended Documentation parsed from a tutorials/package[/subpackage] directory
     * @tutorial tutorials.pkg
     * @access private
     */
    var $tutorials = array();

    /**
     * tree-format structure of tutorials and their child tutorials, if any
     * @var array
     * @access private
     */
    var $tutorial_tree = false;

    /**
     * list of tutorials that have already been processed. Used by @link _setupTutorialTree()
     * @var array
     * @access private
     */
    var $processed_tutorials;

    /**
     * List of all @todo tags and a link to the element with the @todo
     *
     * Format: array(package => array(link to element, array(todo {@link parserTag},...)),...)
     * @tutorial tags.todo.pkg
     * @var array
     */
    var $todoList = array();

    /**
     * Directory where compiled templates go - will be deleted on exit
     *
     * @var string
     * @access private
     */
     var $_compiledDir = array();

    /**
     * Initialize Converter data structures
     * @param array {@link $all_packages} value
     * @param array {@link $package_parents} value
     * @param Classes {@link $classes} value
     * @param ProceduralPages {@link $proceduralpages} value
     * @param array {@link $package_output} value
     * @param boolean {@link $parseprivate} value
     * @param boolean {@link $quietmode} value
     * @param string {@link $targetDir} value
     * @param string {@link $templateDir} value
     * @param string (@link $title} value
     */
    function Converter(&$allp, &$packp, &$classes, &$procpages, $po, $pp, $qm, $targetDir, $template, $title)
    {
        $this->all_packages = $allp;
        $this->package_parents = $packp;
        $this->package = $GLOBALS['phpDocumentor_DefaultPackageName'];
        $this->proceduralpages = &$procpages;
        $this->package_output = $po;
        if (is_array($po))
        {
            $a = $po[0];
            $this->all_packages = array_flip($po);
            $this->all_packages[$a] = 1;
        }
        $this->parseprivate = $pp;
        $this->quietmode = $qm;
        $this->classes = &$classes;
        $this->roots = $classes->getRoots($this->processSpecialRoots);
        $this->title = $title;
        $this->setTemplateDir($template);
        $this->setTargetdir($targetDir);
    }

    /**
     * Called by IntermediateParser after creation
     * @access private
     */
    function setTutorials($tutorials)
    {
        $this->tutorials = $tutorials;
    }

    /**
     * @param pkg|cls|proc the tutorial type to search for
     * @param tutorial name
     * @param string package name
     * @param string subpackage name, if any
     * @return false|parserTutorial if the tutorial exists, return it
     */
    function hasTutorial($type, $name, $package, $subpackage = '')
    {
        if (isset($this->tutorials[$package][$subpackage][$type][$name . '.' . $type]))
            return $this->tutorials[$package][$subpackage][$type][$name . '.' . $type];
        return false;
    }

    /**
     * Called by {@link walk()} while converting, when the last class element
     * has been parsed.
     *
     * A Converter can use this method in any way it pleases. HTMLframesConverter
     * uses it to complete the template for the class and to output its
     * documentation
     * @see HTMLframesConverter::endClass()
     * @abstract
     */
    function endClass()
    {
    }

    /**
    * Called by {@link walk()} while converting, when the last procedural page
    * element has been parsed.
    *
    * A Converter can use this method in any way it pleases. HTMLframesConverter
    * uses it to complete the template for the procedural page and to output its
    * documentation
    * @see HTMLframesConverter::endClass()
    * @abstract
    */
    function endPage()
    {
    }

    /**
    * Called by {@link walk()} while converting.
    *
    * This method is intended to be the place that {@link $pkg_elements} is
    * formatted for output.
    * @see HTMLframesConverter::formatPkgIndex()
    * @abstract
    */
    function formatPkgIndex()
    {
    }

    /**
    * Called by {@link walk()} while converting.
    *
    * This method is intended to be the place that {@link $elements} is
    * formatted for output.
    * @see HTMLframesConverter::formatIndex()
    * @abstract
    */
    function formatIndex()
    {
    }

    /**
    * Called by {@link walk()} while converting.
    *
    * This method is intended to be the place that any of
    * {@link $class_elements, $function_elements, $page_elements},
    * {@link $define_elements}, and {@link $global_elements} is formatted for
    * output, depending on the value of {@link $leftindex}
    * @see HTMLframesConverter::formatLeftIndex()
    * @abstract
    */
    function formatLeftIndex()
    {
    }

    /**
     * Called by {@link parserSourceInlineTag::stringConvert()} to allow
     * converters to format the source code the way they'd like.
     *
     * default returns it unchanged (html with xhtml tags)
     * @param string output from highlight_string() - use this function to
     * reformat the returned data for Converter-specific output
     * @return string
     * @deprecated in favor of tokenizer-based highlighting.  This will be
     *             removed for 2.0
     */
    function unmangle($sourcecode)
    {
        return $sourcecode;
    }

    /**
     * Initialize highlight caching
     */
    function startHighlight()
    {
        $this->_highlightCache = array(false, false);
        $this->_appendHighlight = '';
    }

    function getHighlightState()
    {
        return $this->_highlightCache;
    }

    function _setHighlightCache($type, $token)
    {
        $test = ($this->_highlightCache[0] === $type && $this->_highlightCache[1] == $token);
        if (!$test) {
            $this->_appendHighlight = $this->flushHighlightCache();
        } else {
            $this->_appendHighlight = '';
        }
        $this->_highlightCache = array($type, $token);
        return $test;
    }

    /**
     * Return the close text for the current token
     * @return string
     */
    function flushHighlightCache()
    {
        $hc = $this->_highlightCache;
        $this->_highlightCache = array(false, false);
        if ($hc[0]) {
            if (!isset($this->template_options[$hc[0]]['/'.$hc[1]])) {
                return '';
            }
    		return $this->template_options[$hc[0]]['/'.$hc[1]];
        }
        return '';
    }

    /**
     * Used to allow converters to format the source code the way they'd like.
     *
     * default returns it unchanged.  Mainly used by the {@link HighlightParser}
     * {@internal
     * The method takes information from options.ini, the template options
     * file, specifically the [highlightSourceTokens] and [highlightSource]
     * sections, and uses them to enclose tokens.
     *
     * {@source}}}
     * @param integer token value from {@link PHP_MANUAL#tokenizer tokenizer constants}
     * @param string contents of token
     * @param boolean whether the contents are preformatted or need modification
     * @return string
     */
    function highlightSource($token, $word, $preformatted = false)
    {
        if ($token !== false)
        {
            if (!$preformatted) $word = $this->postProcess($word);
            if (isset($this->template_options['highlightSourceTokens'][token_name($token)]))
            {
                if ($this->_setHighlightCache('highlightSourceTokens', token_name($token))) {
                    return $word;
                }
                $e = $this->_appendHighlight;
                return $e . $this->template_options['highlightSourceTokens'][token_name($token)] . $word;
            } else
            {
                $this->_setHighlightCache(false, false);
                $e = $this->_appendHighlight;
                return $e . $word;
            }
        } else
        {
            if (isset($this->template_options['highlightSource'][$word]))
            {
                $newword = ($preformatted ? $word : $this->postProcess($word));
                if ($this->_setHighlightCache('highlightSource', $word)) {
                    return $newword;
                }
                $e = $this->_appendHighlight;
                return $e . $this->template_options['highlightSource'][$word] . $newword;
            } else
            {
                $this->_setHighlightCache(false, false);
                $e = $this->_appendHighlight;
                return $e . ($preformatted ? $word : $this->postProcess($word));
            }
        }
    }

    /**
     * Used to allow converters to format the source code of DocBlocks the way
     * they'd like.
     *
     * default returns it unchanged.  Mainly used by the {@link HighlightParser}
     * {@internal
     * The method takes information from options.ini, the template options
     * file, specifically the [highlightDocBlockSourceTokens] section, and uses
     * it to enclose tokens.
     *
     * {@source}}}
     * @param string name of docblock token type
     * @param string contents of token
     * @param boolean whether the contents are preformatted or need modification
     * @return string
     */
    function highlightDocBlockSource($token, $word, $preformatted = false)
    {
        if (empty($word)) {
            $this->_setHighlightCache(false, false);
            $e = $this->_appendHighlight;
            return $e . $word;
        }
        if (isset($this->template_options['highlightDocBlockSourceTokens'][$token]))
        {
            if (!$preformatted) $word = $this->postProcess($word);
            if ($this->_setHighlightCache('highlightDocBlockSourceTokens', $token)) {
                return $word;
            }
            $e = $this->_appendHighlight;
            return $e . $this->template_options['highlightDocBlockSourceTokens'][$token] . $word;
        } else {
            $this->_setHighlightCache(false, false);
            $e = $this->_appendHighlight;
            return $e . ($preformatted ? $word : $this->postProcess($word));
        }
    }

    /**
     * Used to allow converters to format the source code of Tutorial XML the way
     * they'd like.
     *
     * default returns it unchanged.  Mainly used by the {@link HighlightParser}
     * {@internal
     * The method takes information from options.ini, the template options
     * file, specifically the [highlightDocBlockSourceTokens] section, and uses
     * it to enclose tokens.
     *
     * {@source}}}
     * @param string name of docblock token type
     * @param string contents of token
     * @param boolean whether the contents are preformatted or need modification
     * @return string
     */
    function highlightTutorialSource($token, $word, $preformatted = false)
    {
        if (empty($word)) {
            $this->_setHighlightCache(false, false);
            $e = $this->_appendHighlight;
            return $e . $word;
        }
        if (isset($this->template_options['highlightTutorialSourceTokens'][$token]))
        {
            if (!$preformatted) $word = $this->postProcess($word);
            if ($this->_setHighlightCache('highlightTutorialSourceTokens', $token)) {
                return $word;
            }
            $e = $this->_appendHighlight;
            return $e . $this->template_options['highlightTutorialSourceTokens'][$token] . $word;
        } else {
            $this->_setHighlightCache(false, false);
            $e = $this->_appendHighlight;
            return $e . ($preformatted ? $word : $this->postProcess($word));
        }
    }

    /**
     * Called by {@link parserReturnTag::Convert()} to allow converters to
     * change type names to desired formatting
     *
     * Used by {@link XMLDocBookConverter::type_adjust()} to change true and
     * false to the peardoc2 values
     * @param string
     * @return string
     */
    function type_adjust($typename)
    {
        return $typename;
    }

    /**
     * Used to convert the {@}example} inline tag in a docblock.
     *
     * By default, this just wraps ProgramExample
     * @see XMLDocBookpeardoc2Converter::exampleProgramExample
     * @param string
     * @param boolean true if this is to highlight a tutorial <programlisting>
     * @return string
     */
    function exampleProgramExample($example, $tutorial = false, $inlinesourceparse = null/*false*/,
                            $class = null/*false*/, $linenum = null/*false*/, $filesourcepath = null/*false*/)
    {
        return $this->ProgramExample($example, $tutorial, $inlinesourceparse, $class, $linenum, $filesourcepath);
    }

    /**
     * Used to convert the <<code>> tag in a docblock
     * @param string
     * @param boolean true if this is to highlight a tutorial <programlisting>
     * @return string
     */
    function ProgramExample($example, $tutorial = false, $inlinesourceparse = null/*false*/,
                            $class = null/*false*/, $linenum = null/*false*/, $filesourcepath = null/*false*/)
    {
        $this->highlightingSource = true;
        if (tokenizer_ext)
        {
            $e = $example;
            if (!is_array($example))
            {
                $obj = new phpDocumentorTWordParser;
                $obj->setup($example);
                $e = $obj->getFileSource();
                $bOpenTagFound = false;
                foreach ($e as $ke => $ee)
                {
                    foreach ($ee as $kee => $eee)
                    {
                        if ((int) $e[$ke][$kee][0] == T_OPEN_TAG)
                        {
                            $bOpenTagFound = true;
                        }
                    }
                }
                if (!$bOpenTagFound) {
                    $example = "<?php\n".$example;
                    $obj->setup($example);
                    $e = $obj->getFileSource();
                    unset($e[0]);
                    $e = array_values($e);
                }
                unset($obj);
            }
            $saveclass = $this->class;
            $parser = new phpDocumentor_HighlightParser;
            if (!isset($inlinesourceparse))
            {
                $example = $parser->parse($e, $this, true); // force php mode
            } else
            {
                if (isset($filesourcepath))
                {
                    $example = $parser->parse($e, $this, $inlinesourceparse, $class, $linenum, $filesourcepath);
                } elseif (isset($linenum))
                {
                    $example = $parser->parse($e, $this, $inlinesourceparse, $class, $linenum);
                } elseif (isset($class))
                {
                    $example = $parser->parse($e, $this, $inlinesourceparse, $class);
                } else
                {
                    $example = $parser->parse($e, $this, $inlinesourceparse);
                }
            }
            $this->class = $saveclass;
        } else
        {
            $example = $this->postProcess($example);
        }
        $this->highlightingSource = false;

        if ($tutorial)
        {
            return $example;
        }

        if (!isset($this->template_options['desctranslate'])) return $example;
        if (!isset($this->template_options['desctranslate']['code'])) return $example;
        $example = $this->template_options['desctranslate']['code'] . $example;
        if (!isset($this->template_options['desctranslate']['/code'])) return $example;
        return $example . $this->template_options['desctranslate']['/code'];
    }

    /**
     * @param string
     */
    function TutorialExample($example)
    {
        $this->highlightingSource = true;
        $parse = new phpDocumentor_TutorialHighlightParser;
        $x = $parse->parse($example, $this);
        $this->highlightingSource = false;
        return $x;
    }

    /**
     * Used to convert the contents of <<li>> in a docblock
     * @param string
     * @return string
     */
    function ListItem($item)
    {
        if (!isset($this->template_options['desctranslate'])) return $item;
        if (!isset($this->template_options['desctranslate']['li'])) return $item;
        $item = $this->template_options['desctranslate']['li'] . $item;
        if (!isset($this->template_options['desctranslate']['/li'])) return $item;
        return $item . $this->template_options['desctranslate']['/li'];
    }

    /**
     * Used to convert the contents of <<ol>> or <<ul>> in a docblock
     * @param string
     * @return string
     */
    function EncloseList($list,$ordered)
    {
        $listname = ($ordered ? 'ol' : 'ul');
        if (!isset($this->template_options['desctranslate'])) return $list;
        if (!isset($this->template_options['desctranslate'][$listname])) return $list;
        $list = $this->template_options['desctranslate'][$listname] . $list;
        if (!isset($this->template_options['desctranslate']['/'.$listname])) return $list;
        return $list . $this->template_options['desctranslate']['/'.$listname];
    }

    /**
     * Used to convert the contents of <<pre>> in a docblock
     * @param string
     * @return string
     */
    function PreserveWhiteSpace($string)
    {
        if (!isset($this->template_options['desctranslate'])) return $string;
        if (!isset($this->template_options['desctranslate']['pre'])) return $string;
        $string = $this->template_options['desctranslate']['pre'] . $string;
        if (!isset($this->template_options['desctranslate']['/pre'])) return $string;
        return $string . $this->template_options['desctranslate']['/pre'];
    }

    /**
     * Used to enclose a paragraph in a docblock
     * @param string
     * @return string
     */
    function EncloseParagraph($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['p'])) return $para;
        $para = $this->template_options['desctranslate']['p'] . $para;
        if (!isset($this->template_options['desctranslate']['/p'])) return $para;
        return $para . $this->template_options['desctranslate']['/p'];
    }

    /**
     * Used to convert the contents of <<b>> in a docblock
     * @param string
     * @return string
     */
    function Bolden($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['b'])) return $para;
        $para = $this->template_options['desctranslate']['b'] . $para;
        if (!isset($this->template_options['desctranslate']['/b'])) return $para;
        return $para . $this->template_options['desctranslate']['/b'];
    }

    /**
     * Used to convert the contents of <<i>> in a docblock
     * @param string
     * @return string
     */
    function Italicize($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['i'])) return $para;
        $para = $this->template_options['desctranslate']['i'] . $para;
        if (!isset($this->template_options['desctranslate']['/i'])) return $para;
        return $para . $this->template_options['desctranslate']['/i'];
    }

    /**
     * Used to convert the contents of <<var>> in a docblock
     * @param string
     * @return string
     */
    function Varize($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['var'])) return $para;
        $para = $this->template_options['desctranslate']['var'] . $para;
        if (!isset($this->template_options['desctranslate']['/var'])) return $para;
        return $para . $this->template_options['desctranslate']['/var'];
    }

    /**
     * Used to convert the contents of <<kbd>> in a docblock
     * @param string
     * @return string
     */
    function Kbdize($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['kbd'])) return $para;
        $para = $this->template_options['desctranslate']['kbd'] . $para;
        if (!isset($this->template_options['desctranslate']['/kbd'])) return $para;
        return $para . $this->template_options['desctranslate']['/kbd'];
    }

    /**
     * Used to convert the contents of <<samp>> in a docblock
     * @param string
     * @return string
     */
    function Sampize($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['samp'])) return $para;
        $para = $this->template_options['desctranslate']['samp'] . $para;
        if (!isset($this->template_options['desctranslate']['/samp'])) return $para;
        return $para . $this->template_options['desctranslate']['/samp'];
    }

    /**
     * Used to convert <<br>> in a docblock
     * @param string
     * @return string
     */
    function Br($para)
    {
        if (!isset($this->template_options['desctranslate'])) return $para;
        if (!isset($this->template_options['desctranslate']['br'])) return $para;
        $para = $this->template_options['desctranslate']['br'] . $para;
        return $para;
    }

    /**
     * This version does nothing
     *
     * Perform necessary post-processing of string data.  For example, the HTML
     * Converters should escape < and > to become &lt; and &gt;
     * @return string
     */
    function postProcess($text)
    {
        return $text;
    }

    /**
     * Creates a table of contents for a {@}toc} inline tag in a tutorial
     *
     * This function should return a formatted table of contents.  By default, it
     * does nothing, it is up to the converter to format the TOC
     * @abstract
     * @return string table of contents formatted for use in the current output format
     * @param array format: array(array('tagname' => section, 'link' => returnsee link, 'id' => anchor name, 'title' => from title tag),...)
     */
    function formatTutorialTOC($toc)
    {
        return '';
    }

    /**
     * Write out the formatted source code for a php file
     *
     * This function provides the primary functionality for the
     * {@tutorial tags.filesource.pkg} tag.
     * @param string full path to the file
     * @param string fully highlighted/linked source code of the file
     * @abstract
     */
    function writeSource($filepath, $source)
    {
        debug($source);
        return;
    }

    /**
     * Write out the formatted source code for an example php file
     *
     * This function provides the primary functionality for the
     * {@tutorial tags.example.pkg} tag.
     * @param string example title
     * @param string example filename (no path)
     * @param string fully highlighted/linked source code of the file
     * @abstract
     */
    function writeExample($title, $path, $source)
    {
        return;
    }

    /** Translate the path info into a unique file name for the highlighted
     * source code.
     * @param string $pathinfo
     * @return string
     */
    function getFileSourceName($path)
    {
        global $_phpDocumentor_options;
        $pathinfo = $this->proceduralpages->getPathInfo($path, $this);
        $pathinfo['source_loc'] = str_replace($_phpDocumentor_options['Program_Root'].'/','',$pathinfo['source_loc']);
        $pathinfo['source_loc'] = str_replace('/','_',$pathinfo['source_loc']);
        return "fsource_{$pathinfo['package']}_{$pathinfo['subpackage']}_{$pathinfo['source_loc']}";
    }

    /** Return the fixed path to the source-code file folder.
     * @param string $base Path is relative to this folder
     * @return string
     */
    function getFileSourcePath($base)
    {
        if (substr($base, strlen($base) - 1) != PATH_DELIMITER) {
            $base .= PATH_DELIMITER;
        }
        return $base . '__filesource';
    }

    /** Return the path to the current
     * @param string $pathinfo
     * @return string
     */
    function getCurrentPageURL()
    {
        return '{$srcdir}' . PATH_DELIMITER . $this->page_dir;
    }

    /**
     * @return string an output-format dependent link to phpxref-style highlighted
     * source code
     * @abstract
     */
    function getSourceLink($path)
    {
        return '';
    }

    /**
     * @return string Link to the current page being parsed.
     * Should return {@link $curname} and a converter-specific extension.
     * @abstract
     */
    function getCurrentPageLink()
    {
    }

    /**
     * Return a line of highlighted source code with formatted line number
     *
     * If the $path is a full path, then an anchor to the line number will be
     * added as well
     * @param integer line number
     * @param string highlighted source code line
     * @param false|string full path to @filesource file this line is a part of,
     *        if this is a single line from a complete file.
     * @return string formatted source code line with line number
     */
    function sourceLine($linenumber, $line, $path = false)
    {
        if ($path)
        {
            return $this->getSourceAnchor($path, $linenumber) .
                   $this->Br(sprintf('%-6u',$linenumber).str_replace("\n",'',$line));
        } else
        {
            return $this->Br(sprintf('%-6u',$linenumber).str_replace("\n",'',$line));
        }
    }

    /**
     * Determine whether an element's file has generated source code, used for
     * linking to line numbers of source.
     *
     * Wrapper for {@link $sourcePaths} in this version
     * 
     * {@internal since file paths get stored with most/all slashes 
     * set to forward slash '/', we need to doublecheck that
     * we're not given a backslashed path to search for...
     * if we are, it's likely that it was originally stored
     * with a forward slash.  Further, I'm not convinced it's safe
     * to just check the {@link PHPDOCUMENTOR_WINDOWS} flag, so I'm checking
     * specifically for backslashes intead.}}
     * 
     * @param string full path to the source code file
     * @return boolean
     */
    function hasSourceCode($path)
    {
        return isset($this->sourcePaths[$path]);
        if (strpos($path, '\\') > -1) {
            $modifiedPath = str_replace('\\', '/', $path);
            return isset($this->sourcePaths[$modifiedPath]);
        } else {
            return isset($this->sourcePaths[$path]);
        }
    }

    /**
     * Mark a file as having had source code highlighted
     * @param string full path of source file
     */
    function setSourcePaths($path)
    {
        $this->sourcePaths[$path] = true;
    }

    /**
     * Used to translate an XML DocBook entity like &rdquo; from a tutorial by
     * reading the options.ini file for the template.
     * @param string entity name
     */
    function TranslateEntity($name)
    {
        if (!isset($this->template_options['ppage']))
        {
            if (!$this->template_options['preservedocbooktags'])
            return '';
            else
            return '&'.$name.';';
        }
        if (isset($this->template_options['ppage']['&'.$name.';']))
        {
            return $this->template_options['ppage']['&'.$name.';'];
        } else
        {
            if (!$this->template_options['preservedocbooktags'])
            return '';
            else
            return '&'.$name.';';
        }
    }

    /**
     * Used to translate an XML DocBook tag from a tutorial by reading the
     * options.ini file for the template.
     * @param string tag name
     * @param string any attributes Format: array(name => value)
     * @param string the tag contents, if any
     * @param string the tag contents, if any, unpost-processed
     * @return string
     */
    function TranslateTag($name,$attr,$cdata,$unconvertedcdata)
    {
        if (!isset($this->template_options['ppage']))
        {
            if (!$this->template_options['preservedocbooktags'])
            return $cdata;
            else
            return '<'.$name.$this->AttrToString($name,$attr,true).'>'.$cdata.'</'.$name.'>'."\n";
        }
        // make sure this template transforms the tag into something
        if (isset($this->template_options['ppage'][$name]))
        {
            // test for global attribute transforms like $attr$role = class, changing
            // all role="*" attributes to class="*" in html, for example
            foreach($attr as $att => $val)
            {
                if (isset($this->template_options['$attr$'.$att]))
                {
                    $new = '';
                    if (!isset($this->template_options['$attr$'.$att]['close']))
                    {
                        $new .= '<'.$this->template_options['$attr$'.$att]['open'];
                        if (isset($this->template_options['$attr$'.$att]['cdata!']))
                        {
                            if (isset($this->template_options['$attr$'.$att]['separateall']))
                            $new .= $this->template_options['$attr$'.$att]['separator'];
                            else
                            $new .= ' ';
                            $new .= $this->template_options['$attr$'.$att]['$'.$att];
                            $new .= $this->template_options['$attr$'.$att]['separator'];
                            if ($this->template_options['$attr$'.$att]['quotevalues']) $val = '"'.$val.'"';
                            $new .= $val.'>';
                        } else
                        {
                            $new .= '>'.$val;
                        }
                        $new .= '</'.$this->template_options['$attr$'.$att]['open'].'>';
                    } else
                    {
                        $new .= $this->template_options['$attr$'.$att]['open'] . $val . $this->template_options['$attr$'.$att]['close'];
                    }
                    unset($attr[$att]);
                    $cdata = $new . $cdata;
                }
            }

            if (!isset($this->template_options['ppage']['/'.$name]))
            {// if the close tag isn't specified, we put opening and closing tags around it, with translated attributes
                if (isset($this->template_options['ppage'][$name.'/']))
                $cdata = '<'.$this->template_options['ppage'][$name].$this->AttrToString($name,$attr).'/>' . $cdata;
                else
                $cdata = '<'.$this->template_options['ppage'][$name].$this->AttrToString($name,$attr).'>' . $cdata .
                         '</'.$this->template_options['ppage'][$name].'>';
            } else
            { // if close tag is specified, use the open and close as literal
                if ($name == 'programlisting' && isset($attr['role']) &&
                      ($attr['role'] == 'php' || $attr['role'] == 'tutorial' || $attr['role'] == 'html'))
                { // highlight PHP source
//                    var_dump($unconvertedcdata, $cdata);exit;
                    if ($attr['role'] == 'php') {
                        $cdata = $this->ProgramExample($unconvertedcdata, true);
                    } elseif ($attr['role'] == 'tutorial') {
                        $cdata = $this->TutorialExample($unconvertedcdata);
                    } elseif ($attr['role'] == 'html') {
                        $cdata = $unconvertedcdata;
                    }
                } else
                {// normal case below
                    $cdata = $this->template_options['ppage'][$name].$this->AttrToString($name,$attr). $cdata .$this->template_options['ppage']['/'.$name];
                }
            }
            return $cdata;
        } else
        {
            if ($this->template_options['preservedocbooktags'])
            {
                return '<'.$name.$this->AttrToString($name,$attr,true).'>' . $cdata .
                         '</'.$name.'>'."\n";
            } else
            {
                return $cdata;
            }
        }
    }

    /**
     * Convert the attribute of a Tutorial docbook tag's attribute list
     * to a string based on the template options.ini
     * @param string tag name
     * @param attribute array
     * @param boolean if true, returns attrname="value"...
     * @return string
     */
    function AttrToString($tag,$attr,$unmodified = false)
    {
        $ret = '';
        if ($unmodified)
        {
            $ret = ' ';
            foreach($attr as $n => $v)
            {
                $ret .= $n.' = "'.$v.'"';
            }
            return $ret;
        }
        // no_attr tells us to ignore all attributes
        if (isset($this->template_options['no_attr'])) return $ret;
        // tagname! tells us to ignore all attributes for this tag
        if (isset($this->template_options['ppage'][$tag.'!'])) return $ret;
        if (count($attr)) $ret = ' ';
        // pass 1, check to see if any attributes add together
        $same = array();
        foreach($attr as $n => $v)
        {
            if (isset($this->template_options['ppage'][$tag.'->'.$n]))
            {
                $same[$this->template_options['ppage'][$tag.'->'.$n]][] = $n;
            }
        }
        foreach($attr as $n => $v)
        {
            if (isset($this->template_options['ppage'][$tag.'->'.$n]))
            {
                if (count($same[$this->template_options['ppage'][$tag.'->'.$n]]) == 1)
                { // only 1 attribute translated for this one
                    // this is useful for equivalent value names
                    if (isset($this->template_options['ppage'][$tag.'->'.$n.'+'.$v])) $v = $this->template_options['ppage'][$tag.'->'.$n.'+'.$v];
                } else
                { // more than 1 attribute combines to make the new attribute
                    $teststrtemp = array();
                    foreach($same[$this->template_options['ppage'][$tag.'->'.$n]] as $oldattr)
                    {
                        $teststrtemp[] = $oldattr.'+'.$attr[$oldattr];
                    }
                    $teststrs = array();
                    $num = count($same[$this->template_options['ppage'][$tag.'->'.$n]]);
                    for($i=0;$i<$num;$i++)
                    {
                        $started = false;
                        $a = '';
                        for($j=$i;!$started || $j != $i;$j = ($j + $i) % $num)
                        {
                            if (!empty($a)) $a .= '|';
                            $a .= $teststrtemp[$j];
                        }
                        $teststrs[$i] = $a;
                    }
                    $done = false;
                    foreach($teststrs as $test)
                    {
                        if ($done) break;
                        if (isset($this->template_options['ppage'][$tag.'->'.$test]))
                        {
                            $done = true;
                            $v = $this->template_options['ppage'][$tag.'->'.$test];
                        }
                    }
                }
                $ret .= $this->template_options['ppage'][$tag.'->'.$n].' = "'.$v.'"';
            } else
            {
                if (!isset($this->template_options['ppage'][$tag.'!'.$n]))
                {
                    if (isset($this->template_options['ppage']['$attr$'.$n]))
                    $ret .= $this->template_options['ppage']['$attr$'.$n].' = "'.$v.'"';
                    else
                    $ret .= $n.' = "'.$v.'"';
                }
            }
        }
        return $ret;
    }

    /**
     * Convert the title of a Tutorial docbook tag section
     * to a string based on the template options.ini
     * @param string tag name
     * @param array
     * @param string title text
     * @param string
     * @return string
     */
    function ConvertTitle($tag,$attr,$title,$cdata)
    {
        if (!isset($this->template_options[$tag.'_title'])) return array($attr,$cdata);
        if (isset($this->template_options[$tag.'_title']['tag_attr']))
        {
            $attr[$this->template_options[$tag.'_title']['tag_attr']] = urlencode($cdata);
            $cdata = '';
        } elseif(isset($this->template_options[$tag.'_title']['cdata_start']))
        {
            $cdata = $this->template_options[$tag.'_title']['open'] . $title .
                     $this->template_options[$tag.'_title']['close'] . $cdata;
        } else $cdata = $title.$cdata;
        return array($attr,$cdata);
    }

    /**
     * Return a converter-specific id to distinguish tutorials and their
     * sections
     *
     * Used by {@}id}
     * @return string
     */
    function getTutorialId($package,$subpackage,$tutorial,$id)
    {
        return $package.$subpackage.$tutorial.$id;
    }

    /**
     * Create the {@link $elements, $pkg_elements} and {@link $links} arrays
     * @access private
     * @todo version 2.0 - faulty package_ou…

Large files files are truncated, but you can click here to view the full file