path: root/buildscripts/PhpDocumentor/phpDocumentor/ParserData.inc

<?php
/**
 * Parser Data Structures
 * 
 * phpDocumentor :: automatic documentation generator
 * 
 * PHP versions 4 and 5
 *
 * Copyright (c) 2002-2008 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
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage ParserData
 * @author     Gregory Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    CVS: $Id: ParserData.inc 253814 2008-02-26 12:15:56Z ashnazg $
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 */

/**
 * Contains information about a PHP file, used to group procedural elements
 * together.
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage ParserData
 * @author     Gregory Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @filesource
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserPage
{
    /**
     * Type is used by many functions to skip the hassle of if
     * <code>phpDocumentor_get_class($blah) == 'parserBlah'</code>
     * @var string
     */
    var $type = 'page';
    /**
     * not implemented in this version, will be used to link xml output pages
     * @var string
     */
    var $id = '';
    /**
     * filename.ext (no path)
     * @var string
     */
    var $file = '';
    /**
     * relative source location
     * @var string
     */
    var $sourceLocation = '';
    /**
     * phpdoc-safe name (only letters, numbers and _)
     * @var string
     */
    var $name = '';
    /**
     * original phpdoc-safe name (only letters, numbers and _)
     * 
     * This fixes [ 1391432 ] Too many underscores in include links.
     * @var string
     */
    var $origName = '';
    /**
     * @var string
     */
    var $category = 'default';
    /**
     * @var string
     */
    var $package = 'default';
    /**
     * @var string
     */
    var $subpackage = '';
    /**
     * @var string
     */
    var $parserVersion = PHPDOCUMENTOR_VER;
    /**
     * not implemented yet
     * file modification date, will be used for makefiles
     * @var string
     */
    var $modDate = '';
    /**
     * @var string full path this page represents
     */
    var $path = '';
    /**
     * Tokenized source code of the file
     * @var array
     */
    var $source = array();
    /**
     * Used to limit output, contains contents of --packageoutput commandline.
     * Does not increase parsing time.  Use --ignore for that
     * @see phpDocumentor_IntermediateParser::$packageoutput, 
     *      Converter::$package_output
     * @var mixed either false or an array of packages
     */
    var $packageOutput = false;
    
    /**
     * sets package to default package
     *
     * @global string default package name
     */
    function parserPage()
    {
        global $phpDocumentor_DefaultPackageName;
        $this->package = $GLOBALS['phpDocumentor_DefaultPackageName'];
    }
    
    /**
     * gets the tag type
     *
     * @return string always "page"
     */
    function getType()
    {
        return 'page';
    }
    
    /**
     * Sets the source code of the file for highlighting.
     *
     * PHP 4.3.0+ passes an array of tokenizer tokens by line number.  PHP
     * 4.2.3- passes a string to be passed to {@link highlight_string()}
     *
     * @param string|array $source the token array/string
     *
     * @return void
     */
    function setSource($source)
    {
        $this->source = $source;
    }
    
    /**
     * Sets the name to display in documentation (can be an alias set with @name)
     *
     * @param string $file the file name
     *
     * @return void
     */
    function setFile($file)
    {
        $this->file = $file;
    }
    
    /**
     * gets the file name
     *
     * @return string|bool filename.ext or @name alias,
     *                     or FALSE if it's not set
     */
    function getFile()
    {
        if (!isset($this->file)) {
            return false;
        }
        return $this->file;
    }
    
    /**
     * sets the path to the file
     *
     * @param string $path full path to file
     *
     * @return void
     */
    function setPath($path)
    {
        // look for special windows case
        if (SMART_PATH_DELIMITER === '\\') {
            $this->path = strtr($path, '/', '\\');
        } else {
            $this->path = $path;
        }
    }
    
    /**
     * gets the path
     *
     * @return string fully delimited path (OS-dependent format),
     *                or FALSE if it's not set
     */
    function getPath()
    {
        if (!isset($this->path)) {
            return false;
        }
        return $this->path;
    }
    
    /**
     * loads the package output array
     *
     * @param array $packages array of packages to display in documentation 
     *                        (package1,package2,...)
     *
     * @return void
     * @see phpDocumentor_IntermediateParser::$packageoutput
     */
    function setPackageOutput($packages)
    {
        $this->packageOutput = $packages;
    }
    
    /**
     * gets the package output array
     *
     * @return array array of packages (package1,package2,...)
     * @see phpDocumentor_IntermediateParser::$packageoutput
     */
    function getPackageOutput()
    {
        return $this->packageOutput;
    }
    
    /**
     * sets the name
     *
     * @param string $name phpdoc-safe name (only _, numbers and letters) 
     *                     set by Parser::parse()
     *
     * @return void
     * @see Parser::parse()
     */
    function setName($name)
    {
        $this->origName = $name;
        $this->name     = $name;
    }
    
    /**
     * gets the name
     *
     * @return string phpdoc-safe name (only _, numbers and letters),
     *                or FALSE if it's not set
     */
    function getName()
    {
        if (!isset($this->name)) {
            return false;
        }
        return $this->name;
    }
    
    /**
     * sets the source location
     *
     * @param string $source path of this file relative to program root
     *
     * @return void
     */
    function setSourceLocation($source)
    {
        $this->sourceLocation = $source;
    }
    
    /**
     * gets the source location
     *
     * @param Converter $c       the output converter
     * @param bool      $pearize if this parameter is true, 
     *                           it will truncate the source location 
     *                           to the subdirectory of pear
     *
     * @return string path of this file relative to program root
     * @todo determine if the str_replace in the 'pear/' ELSE branch should be
     *       removed (see Documentation/tests/bug1574043.php).  It does NOT exist
     *       in the similar function parserClass->getSourceLocation() in
     *       ParserElements.inc.
     */
    function getSourceLocation ($c, $pearize = false)
    {
        global $_phpDocumentor_options;
        if (!isset($this->sourceLocation)) {
            $sl = false;   
        } else {
            $sl = $this->sourceLocation;
            if ($pearize) {
                if (strpos($sl, 'pear/')) {
                    $sl = substr($sl, strpos($sl, 'pear/') + 5);
                } else {
                    $sl = str_replace($_phpDocumentor_options['Program_Root'] 
                        . PATH_DELIMITER, '', $sl);
                }
            }
        }
        return $sl;
    }

    /**
     * Not implemented in this version
     *
     * @return bool tell the parser whether to parse the file,
     *              otherwise this function will retrieve the parsed data 
     *              from external file
     */
    function getParseData()
    {
        return true;
    }
}

/**
 * Contains an in-memory representation of all documentable elements
 * ({@link parserPage}, {@link parserFunction}, {@link parserDefine},
 * {@link parserInclude}, {@link parserClass}, {@link parserMethod},
 * {@link parserVar}) and their DocBlocks ({@link parserDocBlock}).
 *
 * This class works in coordination with {@link phpDocumentor_IntermediateParser}
 * to take output from {@link Parser::handleEvent()} and create indexes, links,
 * and other assorted things (all documented in phpDocumentor_IntermediateParser
 * and {@link Converter})
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage ParserData
 * @author     Gregory Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @filesource
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 */
class parserData
{
    /**
     * {@link parserPage} element that is this parserData's parent, or false if
     * not set.
     * @var false|parserPage
     */
    var $parent = false;
    /**
     * array of parsed elements
     * @var array
     */
    var $elements = array();
    /**
     * @var boolean
     * @access private
     */
    var $_hasclasses = false;
    /**
     * @var boolean
     * @access private
     */
    var $_hasinterfaces = false;
    /**
     * array of parsed elements with @access private
     * @var array
     */
    var $privateelements = array();
    /**
     * array of parsed class elements
     * @var array
     */
    var $classelements = array();
    
    /**
     * @var parserTutorial|false
     */
    var $tutorial = false;
    /**
     * array of parsed class elements with @access private
     * @var array
     */
    var $privateclasselements = array();
    /**
     * array of links descended from {@link abstractLink}
     * @var array
     * @see pageLink, defineLink, classLink, functionLink, methodLink, varLink
     */
    var $links = array();
    /**
     * used by {@link phpDocumentor_IntermediateParser::handleDocBlock()} to
     * determine whether a docblock is a page-level docblock or not.  $clean is
     * true as long as only 0 or 1 docblock has been parsed, and no element
     * other than parserPage has been parsed
     * @var boolean
     */
    var $clean = true;
    /**
     * DocBlock ({@link parserDocBlock}) for this page, or false if not set
     * @var mixed
     */
    var $docblock = false;
    /**
     * Flag used to determine whether a page-level docblock is present
     * @var boolean
     * @access private
     */
    var $_explicitdocblock = false;
    /**
     * Type is used by many functions to skip the hassle of if
     * <code>phpDocumentor_get_class($blah) == 'parserBlah'</code>
     * always 'page', used in element indexing and conversion functions found in
     * {@link Converter}
     * @var string
     */
    var $type = 'page';
    
    /**
     * add a new element to the tracking array
     *
     * @param parserElement &$element add a parsed element to the 
     *                                {@link $elements} array,
     *                                also sets {@link $clean} to false
     *
     * @return void
     */
    function addElement(&$element)
    {
        $element->setPath($this->parent->path);
        if ($element->getType() == 'class' 
            || $element->getType() == 'method' 
            || $element->getType() == 'var'
            || $element->getType() == 'const'
        ) {
            if ($element->getType() == 'class') {
                if ($element->isInterface()) {
                    $this->_hasinterfaces = true;
                } else {
                    $this->_hasclasses = true;
                }
            }
            $this->classelements[] = $element;
        } else {
            $this->elements[] = $element;
        }
        $this->clean = false;
    }

    /**
     * Does this package have interfaces?
     *
     * @return bool
     */
    function hasInterfaces()
    {
        return $this->_hasinterfaces;
    }

    /**
     * Does this package have classes?
     *
     * @return boolean
     */
    function hasClasses()
    {
        return $this->_hasclasses;
    }

    /**
     * adds a tutorial parser
     *
     * @param parserTutorial $t  a tutorial parser
     * @param Converter      &$c the output converter
     *
     * @return void
     */
    function addTutorial($t, &$c)
    {
        $this->tutorial = new tutorialLink;
        $this->tutorial->addLink('', $t->path, $t->name, $t->package, 
            $t->subpackage, $t->getTitle($c));
    }
    
    /**
     * If this file has a tutorial associated with it, 
     * returns a link to the tutorial.
     *
     * @return tutorialLink
     */
    function getTutorial()
    {
        return $this->tutorial;
    }
    
    /**
     * If the page-level DocBlock was present in the source, returns true
     *
     * @return bool
     */
    function hasExplicitDocBlock()
    {
        return $this->_explicitdocblock;
    }
    
    /**
     * Tells this page that its DocBlock was not implicit
     *
     * @return bool
     */
    function explicitDocBlock()
    {
        $this->_explicitdocblock = true;
    }
    
    /**
     * adds a link
     *
     * @param parserElement &$element       element to add a new link (descended from
     *                                      {@link abstractLink}) to the
     *                                      {@link $links} array
     * @param string        $classorpackage classname for elements that are
     *                                      class-based (this may be deprecated in
     *                                      the future, as the classname should be
     *                                      contained within the element.  if
     *                                      $element is a page, this parameter is a
     *                                      package name
     * @param string        $subpackage     subpackage name for page elements
     *
     * @return string
     */
    function addLink(&$element, $classorpackage = '', $subpackage = '')
    {
        switch($element->type)
        {
        case 'function':
                $x = new functionLink;
                $x->addLink($this->parent->path, $this->parent->name, $element->name,
                    $element->docblock->package, $element->docblock->subpackage);
                return $x;
            break;
        case 'define':
                $x = new defineLink;
                $x->addLink($this->parent->path, $this->parent->name, $element->name,
                    $element->docblock->package, $element->docblock->subpackage);
                return $x;
            break;
        case 'global':
                $x = new globalLink;
                $x->addLink($this->parent->path, $this->parent->name, $element->name,
                    $element->docblock->package, $element->docblock->subpackage);
                return $x;
            break;
        case 'class':
                $x = new classLink;
                $x->addLink($this->parent->path, $this->parent->name, $element->name,
                    $element->docblock->package, $element->docblock->subpackage);
                return $x;
            break;
        case 'method':
                $x = new methodLink;
                $x->addLink($classorpackage, $this->parent->path, 
                    $this->parent->name, $element->name, $element->docblock->package,
                    $element->docblock->subpackage);
                return $x;
            break;
        case 'var':
                $x = new varLink;
                $x->addLink($classorpackage, $this->parent->path,
                    $this->parent->name, $element->name, $element->docblock->package,
                    $element->docblock->subpackage);
                return $x;
            break;
        case 'page':
            if (empty($classorpackage)) {
                    $classorpackage = $GLOBALS['phpDocumentor_DefaultPackageName'];
            }
                $x = new pageLink;
                $x->addLink($element->path, $element->name, $element->file,
                    $classorpackage, $subpackage);
                return $x;
            break;
        }
    }
    
    /**
     * returns a link
     *
     * @param Converter &$c   the output converter
     * @param bool      $text a text flag
     *
     * @return string
     */
    function &getLink(&$c, $text = false)
    {
        $a = $c->getPageLink($this->parent->file, $this->docblock->package,
            $this->parent->path, $text);
        return $a;
    }
    
    /**
     * returns a list of all classes declared in a file
     *
     * @param Converter &$c output converter
     *
     * @return array Format: array(
     *                           packagename => parserClass,
     *                           packagename => parserClass,
     *                           ...
     *                       )
     */
    function getClasses(&$c)
    {
        $r  = $c->classes->getClassesInPath($this->parent->path);
        $rr = array();
        if ($r) {
            foreach ($r as $class => $obj) {
                $rr[$obj->docblock->package][] = $obj;
            }
        }
        return $rr;
    }
    
    /**
     * Get the output-safe filename (. changed to _)
     *
     * @return string
     */
    function getName()
    {
        if (isset($this->parent) && $this->parent) {
            return $this->parent->getName();
        }
    }
    
    /**
     * sets the parent
     *
     * @param parserPage &$parent parent element of this parsed data
     *
     * @return void
     */
    function setParent(&$parent)
    {
        $this->parent = $parent;
    }
    
    /**
     * checks if the element is "cleaned" already
     *
     * @return bool returns the value of {@link $clean}
     */
    function isClean()
    {
        return $this->clean;
    }
    
    /**
     * sets the docblock
     *
     * @param parserDocBlock &$docblock docblock element
     *
     * @return void
     * @see parserDocBlock
     */
    function setDocBlock(&$docblock)
    {
        $this->docblock = $docblock;
    }
}

/**
 * Base class for all elements
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage ParserData
 * @author     Gregory Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @filesource
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @abstract
 */
class parserBase
{
    /**
     * Type is used by many functions to skip the hassle of if 
     * phpDocumentor_get_class($blah) == 'parserBlah'... always base
     * @var string
     */
    var $type = 'base';
    /**
     * set to different things by its descendants
     * @abstract
     * @var mixed
     */
    var $value = false;

    /**
     * gets the type
     *
     * @return string returns value of {@link $type}
     */
    function getType()
    {
        return $this->type;
    }
    
    /**
     * sets the given value
     *
     * @param mixed $value set the value of this element
     *
     * @return void
     */
    function setValue($value)
    {
        $this->value = $value;
    }
    
    /**
     * gets the value
     *
     * @return mixed get the value of this element (element-dependent)
     */
    function getValue()
    {
        return $this->value;
    }
}


/**
 * Used to represent strings that contain inline tags, 
 * so that they can be properly parsed at link time
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage ParserData
 * @author     Gregory Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @filesource
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 */
class parserStringWithInlineTags extends parserBase
{
    /**
     * Type is used by many functions to skip the hassle of 
     * if phpDocumentor_get_class($blah) == 'parserBlah'...
     * always '_string'
     * @var string
     */
    var $type = '_string';
    /**
     * @access private
     */
    var $cache = false;
    /**
     * array of strings and {@link parserInlineTag}s
     * Format:
     * array(string1,string2,parserInlineTag1,string3,parserInlineTag2,...)
     * @var array
     */
    var $value = array();

    /**
     * equivalent to the . operator ($a = $b . $c)
     *
     * @param mixed $stringOrInlineTag either a string or a {@link parserInlineTag}
     *
     * @return void
     */
    function add($stringOrInlineTag)
    {
        if (is_string($stringOrInlineTag)) {
            if (!count($this->value)) {
                $this->value[] = $stringOrInlineTag;
                return;
            }
            if (is_string($this->value[count($this->value) - 1])) {
                $this->value[count($this->value) - 1] .= $stringOrInlineTag;
                return;
            } else {
                $this->value[] = $stringOrInlineTag;
                return;
            }
        } else {
            if (is_a($stringOrInlineTag, 'parserinlinetag') 
                && phpDocumentor_setup::checkIgnoreTag($stringOrInlineTag->
                    inlinetype, true)
            ) {
                return;
            }
            $this->value[] = $stringOrInlineTag;
        }
    }
    
    /**
     * Determine whether the string contains any inline tags
     *
     * @return bool
     * @tutorial inlinetags.pkg
     */
    function hasInlineTag()
    {
        for ($i=0; $i<count($this->value); $i++) {
            if (is_a($this->value[$i], 'parserinlinetag')) {
                return true;
            }
        }
        return false;
    }
    
    /**
     * Pass source code to any {@}source} tags contained within the string
     * for later conversion.
     *
     * @param string|array $source source code ready to be highlighted
     *
     * @return void
     */
    function setSource($source)
    {
        for ($i=0; $i<count($this->value); $i++) {
            if (phpDocumentor_get_class($this->value[$i]) == 'parsersourceinlinetag'
            ) {
                $this->value[$i]->setSource($source);
            }
        }
    }

    /**
     * equivalent to trim(strlen($string))
     *
     * @return integer length of the string this object represents
     */
    function trimmedStrlen()
    {
        $a = 0;
        for ($i=0; $i<count($this->value); $i++) {
            if (is_string($this->value[$i])) {
                if ($i == 0) {
                    $a += strlen(ltrim($this->value[$i]));
                } elseif ($i == count($this->value[$i]) - 1) {
                    $a += strlen(chop($this->value[$i]));
                }
            } else {
                $a += $this->value[$i]->Strlen();
            }
        }
        return $a;
    }
    
    /**
     * return the string unconverted (all inline tags are taken out - this
     * should only be used in pre-parsing to see if any other text
     * is in the string)
     *
     * @param bool $trim whether to trim the string
     *
     * @return string trimmed value
     * @uses parserInlineTag::getString() removes inline tag length, as it is
     *       indeterminate until conversion.
     */
    function getString($trim = true)
    {
        $a = '';
        for ($i=0; $i<count($this->value); $i++) {
            if (is_string($this->value[$i])) {
                $a .= $this->value[$i];
            } else {
                $a .= $this->value[$i]->getString();
            }
        }
        if ($trim) {
            $a = trim($a);
        }
        return $a;
    }
    
    /**
     * Use to convert the string to a real string 
     * with all inline tags parsed and linked
     *
     * @param Converter &$converter  the output converter
     * @param bool      $postprocess true if one needs to postprocess
     * @param bool      $trim        false if the output should not be trimmed
     *
     * @return string
     * @see Converter::returnSee()
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$converter, $postprocess = true, $trim = true)
    {
        if ($this->cache) {
            if ($converter->name == $this->cache['name'] 
                && $converter->outputformat == $this->cache['output'] 
                && $converter->checkState($this->cache['state']) 
                && $this->cache['postprocess'] === $postprocess
            ) {
                return $this->cache['contents'];
            }
            if ($converter->name != $this->cache['name']) {
                $this->cache = false;
            }
        }
        if (is_string($this->value)) {
            return $this->value;
        }
        $a = '';
        for ($i=0; $i<count($this->value); $i++) {
            if (is_string($this->value[$i])) {
                if ($postprocess && !method_exists($converter, 'postProcess')) {
                    var_dump('a', $converter);
                }
                if ($postprocess) {
                    $a .= $converter->postProcess($this->value[$i]);
                } else {
                    $a .= $this->value[$i];
                }
            } else {
                $a .= $this->value[$i]->Convert($converter, $postprocess);
            }
        }
        if ($trim) {
            $a = trim($a);
        }
        $this->cache = array(
            'name'        => $converter->name,
            'output'      => $converter->outputformat, 
            'contents'    => $a, 
            'state'       => $converter->getState(), 
            'postprocess' => $postprocess
        );
        return $a;
    }
}

?>