Subversion-Projekte lars-tiefland.php_share

<?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;

    }

}

?>