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

<?php
/**
 * All abstract representations of DocBlock tags are defined
 * by the classes in this file
 *
 * 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 DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    CVS: $Id: DocBlockTags.inc 287889 2009-08-30 07:27:39Z ashnazg $
 * @filesource
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @see        parserDocBlock, parserInclude, parserPage, parserClass
 * @see        parserDefine, parserFunction, parserMethod, parserVar
 * @since      separate file since version 1.2
 * @todo       CS cleanup - change package to PhpDocumentor
 */
/**
 * used to represent standard tags like @access, etc.
 * This class is aware of inline tags, and will automatically handle them
 * using inherited functions
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @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 parserTag extends parserStringWithInlineTags
{
    /**
     * Type is used by many functions to skip the hassle of 
     * if phpDocumentor_get_class($blah) == 'parserBlah' always '_tag'
     * @var string
     */
    var $type = '_tag';
    /**
     * tag name (see, access, etc.)
     * @var string
     */
    var $keyword = '';
    
    /**
     * Set up the tag
     *
     * {@source}
     *
     * @param string                     $keyword tag name
     * @param parserStringWithInlineTags $value   tag value
     * @param boolean                    $noparse whether to parse the $value 
     *                                            for html tags
     */
    function parserTag($keyword, $value, $noparse = false)
    {
        $this->keyword = $keyword;
        if (!$noparse) {
            $parser = new parserDescParser;
            $parser->subscribe('*', $this);
            $parser->parse($value->value, true, 'parserstringwithinlinetags');
        } else { 
            $this->value = $value; 
        }
    }
    
    /**
     * Perform the output conversion on this {@link parserTag}
     * using the {@link Converter output converter} that is passed in
     *
     * @param Converter &$converter the converter object
     *
     * @return string
     * @see Converter
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$converter)
    {
        if (is_array($this->value)) {
            if (count($this->value) == 1) {
                reset($this->value);
                list(, $val) = each($this->value);
                $a           = $val->Convert($converter);
                return $a;
            }
            $result = '';
            foreach ($this->value as $val) {
                // this is only true if we processed the description
                // in the constructor
                if (phpDocumentor_get_class($val) 
                        == 'parserstringwithinlinetags') {
                    $result .= $converter->
                        EncloseParagraph($val->Convert($converter));
                } else {
                    $result .= $val->Convert($converter);
                }
            }
            return $result;
        } else {
            $a = $this->value->Convert($converter);
            return $a;
        }
    }
    
    /**
     * Gets a count of the number of paragraphs in this
     * tag's description.
     *
     * Useful in determining whether to enclose the
     * tag in a paragraph or not.
     *
     * @return integer (actually, body is empty, so it doesn't return at all)
     * @access private
     * @todo does this need to be implemented?  its body is empty
     */
    function _valueParagraphCount()
    {
    }
    
    /**
     * Called by the {@link parserDescParser} when processing a description.
     *
     * @param integer $a    not used
     * @param array   $desc array of {@link parserStringWithInlineTags} 
     *                      representing paragraphs in the tag description
     *
     * @return void
     * @see parserTag::parserTag()
     * @todo CS cleanup - rename to handleEvent for camelCase rule
     */
    function HandleEvent($a,$desc)
    {
        $this->value = $desc;
    }
    
    /**
     * Returns the text minus any inline tags
     *
     * @return string the text minus any inline tags
     * @see parserStringWithInlineTags::getString()
     */
    function getString()
    {
        if (is_array($this->value)) {
            $result = '';
            foreach ($this->value as $val) {
                $result .= $val->getString();
            }
            return $result;
        } else {
            return $this->value->getString();
        }
    }
}

/**
 * This class represents the @name tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.name.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserNameTag extends parserTag
{
    /**
     * tag name
     * @var string
     */
    var $keyword = 'name';
    
    /**
     * set up the name tag
     *
     * @param string $name  tag name (not used)
     * @param string $value tag value 
     */
    function parserNameTag($name, $value)
    {
        $this->value = $value;
    }
    
    /**
     * process this tag through the given output converter
     *
     * @param Converter &$c output converter
     *
     * @return string converted value of the tag
     * @see parserStringWithInlineTags::Convert()
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$c)
    {
        return $this->value;
    }
}

/**
 * This class represents the @access tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.access.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserAccessTag extends parserTag
{
    /**
     * tag name
     * @var string
     */
    var $keyword = 'access';
    
    /**
     * set to true if the returned tag has a value type of private, protected
     * or public, false otherwise
     * @var boolean
     */
    var $isvalid = false;
    
    /**
     * checks $value to make sure it is private, protected or public, otherwise
     * it's not a valid @access tag
     *
     * @param parserStringWithInlineTags $value the tag value
     *
     * @see $isvalid
     */
    function parserAccessTag($value)
    {
        if (!is_string($value)) {
            if (is_object($value)) {
                if (method_exists($value, 'getstring')) {
                    $value = $value->getString();
                }
            }
        }
        switch(trim($value)) {
        case 'private' :
        case 'public' :
        case 'protected' :
            $this->value   = $value;
            $this->isvalid = true;
            break;
        default :
            addError(PDERROR_ACCESS_WRONG_PARAM, $value);
            $this->value = 'public';
            break;
        }
    }
    
    /**
     * process this tag through the given output converter
     *
     * @param Converter &$converter the output converter
     *
     * @return string converted value of the tag
     * @see parserStringWithInlineTags::Convert()
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$converter)
    {
        return $this->value;
    }
    
    /**
     * No inline tags are possible, returns 'public', 'protected' or 'private'
     *
     * @return string returns the text minus any inline tags
     */
    function getString()
    {
        return $this->value;
    }
}

/**
 * represents the "@return" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.return.pkg
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserReturnTag extends parserTag
{
    /**
     * always 'return'
     * @var string
     */
    var $keyword = 'return';
    /**
     * the type a function returns
     */
    var $returnType = 'void';
    
    /**
     * contains a link to the documentation for a class 
     * passed as a type in @return, @var or @param
     *
     * Example:
     *
     * <code>
     * class myclass
     * {
     * ...
     * }
     * /** @return myclass blahblahblah
     * ...
     * </code>
     *
     * In this case, $converted_returnType will contain a link to myclass 
     * instead of the string 'myclass'
     *
     * @var mixed either the same as $returnType or a link to the docs for a class
     * @see $returnType
     */
    var $converted_returnType = false;
    
    /**
     * set up the tag
     *
     * @param string                     $returnType returned datatype
     * @param parserStringWithInlineTags $value      tag value
     */
    function parserReturnTag($returnType, $value)
    {
        $this->returnType = $returnType;
        parent::parserTag('return', $value);
    }
    
    /**
     * process this tag through the given output converter
     * (sets up the $converted_returnType)
     *
     * @param Converter &$converter the output converter
     *
     * @return string converted value of the tag
     * @see parserStringWithInlineTags::Convert(), $converted_returnType
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$converter)
    {
        $my_types = '';
        if (strpos($this->returnType, '|')) {
            $types = explode('|', $this->returnType);
            foreach ($types as $returntype) {
                $a = $converter->getLink($returntype);
                if (is_object($a) && phpDocumentor_get_class($a) == 'classlink') {
                    if (!empty($my_types)) {
                        $my_types .= '|';
                    }
                    $my_types .= $converter->
                        returnSee($a, $converter->type_adjust($returntype));
                } else {
                    if (!empty($my_types)) {
                        $my_types .= '|';
                    }
                    $my_types .= $converter->type_adjust($returntype);
                }
            }
            $this->converted_returnType = $my_types;
        } else {
            $a = $converter->getLink($this->returnType);
            if (is_object($a) && phpDocumentor_get_class($a) == 'classlink') {
                $this->converted_returnType = $converter->
                    returnSee($a, $converter->type_adjust($this->returnType));
            } else {
                $this->converted_returnType = $converter->
                    type_adjust($this->returnType);
            }
        }
        return parserTag::Convert($converter);
    }
}

/**
 * represents the "@property" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.property.pkg
 * @since      1.4.0a1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserPropertyTag extends parserReturnTag
{
    /**
     * always 'property'
     * @var string
     */
    var $keyword = 'property';
    /**
     * the type a property has
     * @var string
     */
    var $returnType = 'mixed';

    /**
     * set up the property tag
     *
     * @param string                     $returnType the tag value's datatype
     * @param parserStringWithInlineTags $value      the tag value
     */
    function parserPropertyTag($returnType, $value)
    {
        $this->returnType = $returnType;
        parent::parserTag($this->keyword, $value);
    }
}

/**
 * represents the "@property-read" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.property.pkg
 * @since      1.4.0a1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserPropertyReadTag extends parserPropertyTag
{
    /**
     * always 'property-read'
     * @var string
     */
    var $keyword = 'property-read';
}

/**
 * represents the "@property-write" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.property.pkg
 * @since      1.4.0a1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserPropertyWriteTag extends parserPropertyTag
{
    /**
     * always 'property-write'
     * @var string
     */
    var $keyword = 'property-write';
}

/**
 * represents the "@method" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.method.pkg
 * @since      1.4.0a1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserMethodTag extends parserPropertyTag
{
    /**
     * always 'method'
     * @var string
     */
    var $keyword = 'method';
    /**
     * the return type a method has
     * @var string
     */
    var $returnType = 'void';
}

/**
 * represents the "@var" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.var.pkg
 * @since      1.0rc1
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserVarTag extends parserReturnTag
{
    /**
     * always 'var'
     * @var string
     */
    var $keyword = 'var';
    /**
     * the type a var has
     * @var string
     */
    var $returnType = 'mixed';
}

/**
 * represents the "@param" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.param.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserParamTag extends parserVarTag
{
    /**
     * always 'param'
     * @var string
     */
    var $keyword = 'param';
}

/**
 * represents the "@staticvar" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.staticvar.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserStaticvarTag extends parserParamTag
{
    /**
     * always 'staticvar'
     * @var string
     */
    var $keyword = 'staticvar';
}

/**
 * represents the "@link" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @tutorial   tags.link.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserLinkTag extends parserTag
{
    /**
     * always 'link'
     * @var string
     */
    var $keyword = 'link';
    
    /**
     * sets up the link tag
     *
     * @param string $link URL to link to
     *                     (might also contain the URL's
     *                     description text)
     */
    function parserLinkTag($link)
    {
        $start = $val = $link->getString();
        if (strpos($val, ' ')) {
            $val   = explode(' ', $val);
            $start = array_shift($val);
            $val   = join($val, ' ');
        }
        $a = new parserLinkInlineTag($start, $val);
        $b = new parserStringWithInlineTags;
        $b->add($a);
        $this->value = $b;
    }
}

/**
 * represents the "@see" tag
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.0rc1
 * @tutorial   tags.see.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserSeeTag extends parserLinkTag
{
    /**
     * always 'see'
     * @var string
     */
    var $keyword = 'see';
    
    /**
     * sets up the see tag
     *
     * @param string $name element to link to
     */
    function parserSeeTag($name)
    {
        parserTag::parserTag($this->keyword, $name, true);
    }

    /**
     * process this tag through the given output converter
     *
     * @param Converter &$converter the output converter
     *
     * @return string converted value of the tag
     * @see parserStringWithInlineTags::Convert()
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$converter)
    {
        if ($this->value->hasInlineTag()) {
            addErrorDie(PDERROR_INLINETAG_IN_SEE);
        }
        $a = $converter->getLink(trim($this->value->Convert($converter)));
        if (is_string($a)) {
            // feature 564991
            if (strpos($a, '://')) {
                // php function
                return $converter->returnLink($a, str_replace('PHP_MANUAL#', '', 
                    $this->value->Convert($converter)));
            }
            return $a;
        }
        if (is_object($a)) {
            return $converter->returnSee($a);
        }
        // getLink parsed a comma-delimited list of linked thingies, 
        // add the commas back in
        if (is_array($a)) {
            $b = '';
            foreach ($a as $i => $bub) {
                if (!empty($b)) {
                    $b .= ', ';
                }
                if (is_string($a[$i])) {
                    $b .= $a[$i];
                }
                if (is_object($a[$i])) {
                    $b .= $converter->returnSee($a[$i]);
                }
            }
            return $b;
        }
        return false;
    }
}

/**
 * represents the "@see" tag
 *
 * Link to a license, instead of including lines and lines of license information
 * in every file
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.license.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserLicenseTag extends parserLinkTag
{
    /**
     * always 'license'
     * @var string
     */
    var $keyword = 'license';
    
    /**
     * set up the license tag
     *
     * @param string $name unused?
     * @param string $link URL to link to
     */
    function parserLicenseTag($name, $link)
    {
        $a       = explode(' ', $link->getString());
        $url     = array_shift($a);
        $license = join($a, ' ');
        if (empty($license)) {
            $license = $url;
        }
        $a = new parserLinkInlineTag($url, $license);
        $b = new parserStringWithInlineTags;
        $b->add($a);
        $this->value = $b;
    }
}

/**
 * represents the "@uses" tag
 *
 * This is exactly like @see except that the element used 
 * has a @useby link to this element added to its docblock
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.2
 * @tutorial   tags.uses.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserUsesTag extends parserSeeTag
{
    /**
     * Always "uses"
     * @var string
     */
    var $keyword = 'uses';
    /**
     * @access private
     */
    var $_description;
    
    /**
     * set up the uses tag
     *
     * @param string                     $seeel       element to link to
     * @param parserStringWithInlineTags $description description of how 
     *                                                the element is used
     */
    function parserUsesTag($seeel, $description)
    {
        if ($seeel->hasInlineTag()) {
            addErrorDie(PDERROR_DUMB_USES);
        }
        parent::parserSeeTag($seeel);
        $this->_description = $description;
    }
    
    /**
     * Return a link to documentation for other element,
     * and description of how it is used
     *
     * Works exactly like {@link parent::Convert()} 
     * except that it also includes a description of 
     * how the element used is used.
     *
     * @param Converter &$c the output converter
     *
     * @return string link to the uses target
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$c)
    {
        $val         = $this->value;
        $see         = parent::Convert($c);
        $this->value = $this->_description;
        $desc_val    = parserTag::Convert($c);
        if (!empty($desc_val)) {
            $see .= ' - '.$desc_val;
        }
        $this->value = $val;
        return $see;
    }
    
    /**
     * Get the text of the link to the element that is being used
     *
     * @return string
     * @access private
     */
    function getSeeElement()
    {
        return $this->value->getString();
    }
    
    /**
     * Get the description of how the element used is being used.
     *
     * @return parserStringWithInlineTags
     */
    function getDescription()
    {
        return $this->_description;
    }
}

/**
 * This is a virtual tag, it is created by @uses to cross-reference the used element
 *
 * This is exactly like @uses.
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.2
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserUsedByTag extends parserUsesTag
{
    /**
     * Always "usedby"
     * @var string
     */
    var $keyword = 'usedby';
    /**
     * @access private 
     */
    var $_link;
    
    /**
     * set up the usedby tag
     *
     * @param abstractLink $link        link of element that uses this element
     * @param string       $description description of how the element is used
     */
    function parserUsedByTag($link, $description)
    {
        $this->value = $description;
        $this->_link = $link;
    }
    
    /**
     * process this tag through the given output converter
     *
     * @param Converter &$c the output converter
     *
     * @return string
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$c)
    {
        $see      = $c->returnSee($this->_link);
        $desc_val = parserTag::Convert($c);
        if (!empty($desc_val)) {
            $see .= ' - '.$desc_val;
        }
        return $see;
    }
}

/**
 * represents "@tutorial"
 *
 * This is exactly like @see except that it only links to tutorials
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.2
 * @tutorial   phpDocumentor/tutorials.pkg
 * @tutorial   tags.tutorial.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserTutorialTag extends parserSeeTag
{
    /**
     * Always "tutorial"
     * @var string
     */
    var $keyword = 'tutorial';

    /**
     * process this tag through the given output converter
     *
     * @param Converter &$converter the output converter
     *
     * @return string|bool
     * @see parserStringWithInlineTags::Convert()
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$converter)
    {
        $a = $converter->getTutorialLink(trim($this->value->Convert($converter)));
        if (is_string($a)) {
            return $a;
        }
        if (is_object($a)) {
            return $converter->returnSee($a);
        }
        // getLink parsed a comma-delimited list of linked thingies, 
        // add the commas back in
        if (is_array($a)) {
            $b = '';
            foreach ($a as $i => $bub) {
                if (!empty($b)) {
                    $b .= ', ';
                }
                if (is_string($a[$i])) {
                    $b .= $a[$i];
                }
                if (is_object($a[$i])) {
                    $b .= $converter->returnSee($a[$i]);
                }
            }
            return $b;
        }
        return false;
    }
}

/**
 * represents "@filesource"
 * 
 * Use this to create a link to a highlighted phpxref-style source file listing
 *
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @since      1.2
 * @tutorial   tags.filesource.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserFileSourceTag extends parserTag
{
    /**
     * Always "filesource"
     * @var string
     */
    var $keyword = 'filesource';
    /**
     * @var array
     */
    var $source;
    /**
     * @var string
     */
    var $path;
    /**
     * Flag variable, controls double writes of file for each converter
     * @var array
     * @access private
     */
    var $_converted = array();

    /**
     * Set {@link $source} to $value, and set up path
     *
     * @param string $filepath the file's path
     * @param array  $value    output from 
     *                         {@link phpDocumentorTWordParser::getFileSource()}
     */
    function parserFileSourceTag($filepath, $value)
    {
        parent::parserTag($this->keyword, '');
        $this->path   = $filepath;
        $this->source = $value;
    }

    /**
     * Return a link to the highlighted source and generate the source
     *
     * @param Converter &$c the output converter
     *
     * @return string output from {@link getSourceLink()}
     * @uses ConvertSource() generate source code and write it out
     * @todo CS cleanup - rename to convert for camelCase rule
     */
    function Convert(&$c)
    {
        $this->ConvertSource($c);
        return $this->getSourceLink($c);
    }

    /**
     * convert the source code
     *
     * @param Converter &$c the output converter
     *
     * @return void
     * @uses phpDocumentor_HighlightParser highlights source code
     * @uses writeSource()
     * @todo CS cleanup - rename to convertSource for camelCase rule
     * @todo what's up with all the "return" statements?
     *       can they _all_ be removed?
     */
    function ConvertSource(&$c)
    {
        $this->writeSource($c, $c->
            ProgramExample($this->source, true, false, false, false, $this->path));
        return;
        $parser = new phpDocumentor_HighlightParser;
        $return = '';
        $return = $parser->
            parse($this->source, $c, false, false, false, $this->path);
        $this->writeSource($c, $return);
    }

    /**
     * have the output converter write the source code
     *
     * @param Converter &$c     the output converter
     * @param string    $source highlighted source code
     *
     * @return void
     * @uses Converter::writeSource() export highlighted file source
     */
    function writeSource(&$c, $source)
    {
        $c->writeSource($this->path, $source);
    }

    /**
     * gets path to the sourcecode file
     *
     * @param Converter &$c the output converter
     *
     * @return output from getSourceLink()
     * @uses Converter::getSourceLink()
     */
    function getSourceLink(&$c)
    {
        return $c->getSourceLink($this->path);
    }
}

/**
 * represents "@example"
 * 
 * @category   ToolsAndUtilities
 * @package    phpDocumentor
 * @subpackage DocBlockTags
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2002-2008 Gregory Beaver
 * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version    Release: 1.4.3
 * @link       http://www.phpdoc.org
 * @link       http://pear.php.net/PhpDocumentor
 * @tutorial   tags.example.pkg
 * @todo       CS cleanup - change package to PhpDocumentor
 * @todo       CS cleanup - change classname to PhpDocumentor_*
 */
class parserExampleTag extends parserFileSourceTag
{
    /**
     * always "example"
     * @var string
     */
    var $keyword = 'example';

    /**
     * Reads and parses the example file indicated
     *
     * The example tag takes one parameter: the full path to a php file that
     * should be parsed and included as an example.
     *
     * @param parserStringWithInlineTags $value        tag value
     * @param string                     $current_path path of file containing 
     *                                                 this @example tag
     *
     * @uses phpDocumentorTWordParser::getFileSource() uses to parse an example
     *       and retrieve all tokens by line number
     * @todo does this "x = y = z = false" still work as expected in PHP5?
     * @todo CS cleanup - rename constant to TOKENIZER_EXT
     */
    function parserExampleTag($value, $current_path)
    {
        global $_phpDocumentor_setting;
        parent::parserTag('example', $value);
        $path = false;
        // code thanks to Sam Blum, modified by Greg Beaver
        $tagValue = $value->getString();

        $path = $isAbsPath 
              = $pathOnly 
              = $fileName 
              = $fileExt 
              = $original_path  
              = $title 
              = false;
        do {
            // make sure the format is stuff.ext description
            if (!preg_match('`(.*)\.(\w*)\s(.*)`', $tagValue, $match)) {
                // or format is stuff.ext
                if (!preg_match('`(.*)\.(\w*)\s*$`', $tagValue, $match)) {
                    // Murphy: Some funny path was given
                    $original_path = $tagValue; // used for error output
                    break; // try-block
                }
            }
            if (strlen($match[1]) === 0) {
                // Murphy: Some funny path was given
                $original_path = $tagValue; // used for error output
                break; // try-block
            }
            $fileExt = $match[2];
            $title   = 'example';
            if (isset($match[3])) {
                $title = trim($match[3]);
            }
            // Replace windows '\' the path.
            $pathTmp = str_replace('\\', '/', $match[1]); 

            // Is there a path and a file or is it just a file?
            if (strpos($pathTmp, '/') === false) {
                // No path part
                $pathOnly = '';
                $fileName = $pathTmp .'.'. $fileExt;
            } else {
                // split the path on the last directory, find the filename
                $splitPos = strrpos($pathTmp, '/'); 
                $pathOnly = substr($match[1], 0, $splitPos+1);
                $fileName = substr($match[1], $splitPos+1) .'.'. $fileExt;
                // Is the path absolute? (i.e. does it start like an absolute path?)
                if (('/' === $pathTmp[0]) || preg_match('`^\w*:`i', $pathTmp)) { 
                    // works for both windows 'C:' and URLs like 'http://'
                    $isAbsPath = true; // Yes
                }
            }

            $original_path = $pathOnly . $fileName;

            // Now look for the file starting with abs. path.
            if ($isAbsPath) {
                // remove any weirdities like /../file.ext
                $tmp = realpath($original_path); 
                if ($tmp && is_file($tmp)) {
                    $path = $tmp;
                }
                // Alway break if abs. path was detected,
                // even if file was not found.
                break; // try-block
            }

            // Search for the example file some standard places 
            // 1) Look if the ini-var examplesdir is set and look there ...
            if (isset($_phpDocumentor_setting['examplesdir'])) {
                $tmp = realpath($_phpDocumentor_setting['examplesdir'] 
                    . PATH_DELIMITER  . $original_path);
                if ($tmp && is_file($tmp)) {
                    $path = $tmp; // Yo! found it :)
                    break; // try-block
                }
            }

            // 2) Then try to look for an 'example/'-dir 
            //    below the *currently* parsed file ...
            if (!empty($current_path)) {
                $tmp = realpath(dirname($current_path) . PATH_DELIMITER 
                    . 'examples' . PATH_DELIMITER . $fileName);
                if ($tmp && is_file($tmp)) {
                    $path = $tmp; // Yo! found it :)
                    break; // try-block
                }
            }

            // 3) Then try to look for the example file 
            //    below the subdir PHPDOCUMENTOR_BASE/examples/ ...
            if (is_dir(PHPDOCUMENTOR_BASE . PATH_DELIMITER . 'examples')) {
                $tmp = realpath(PHPDOCUMENTOR_BASE . PATH_DELIMITER 
                    . 'examples' . PATH_DELIMITER . $original_path);
                if ($tmp && is_file($tmp)) {
                    $path = $tmp; // Yo! found it :)
                    break; // try-block
                }
            }

            $tmp = realpath(PHPDOCUMENTOR_BASE . PATH_DELIMITER . $original_path);
            if ($tmp && is_file($tmp)) {
                $path = $tmp; // Yo! found it :)
                break; // try-block
            }
            // If we reach this point, nothing was found and $path is false.
        } while (false);

        if (!$path) {
            addWarning(PDERROR_EXAMPLE_NOT_FOUND, $original_path);
            $this->_title = 'example not found';
            $this->path   = false;
        } else {
            $this->_title = ($title) ? $title : 'example';
            // make a unique html-filename but avoid it to get too long.
            $uniqueFileName = str_replace(array(':', 
                DIRECTORY_SEPARATOR, '/'), array('_', '_', '_'), $path);
            $uniqueFileName = substr($uniqueFileName, -50) . '_' . md5($path);
            $this->path     = $uniqueFileName;
            
            $f = @fopen($path, 'r');
            if ($f) {
                $example = fread($f, filesize($path));
                if (tokenizer_ext) {
                    $obj = new phpDocumentorTWordParser;
                    $obj->setup($example);
                    $this->source     = $obj->getFileSource();
                    $this->origsource = $example;
                    unset($obj);
                } else {
                    $this->source = $example;
                }
            }
        }
    }
    
    /**
     * convert the source code
     *
     * @param Converter &$c the output converter
     *
     * @return void
     * @uses phpDocumentor_HighlightParser highlights source code
     * @uses writeSource()
     * @todo CS cleanup - rename to convertSource for camelCase rule
     * @todo what's up with all the "return" statements?
     *       can they _all_ be removed?
     */
    function ConvertSource(&$c)
    {
        $this->writeSource($c, $c->ProgramExample($this->source, true, null,
                            null, null, null, $this->origsource));
        return;
        $parser = new phpDocumentor_HighlightParser;
        $return = '';
        $return = $parser->parse($this->source, $c);
        $this->writeSource($c, $return);
    }

    /**
     * have the output converter write the source code
     *
     * @param Converter &$c     the output converter
     * @param string    $source highlighted source code
     *
     * @return void
     * @access private
     * @uses Converter::writeExample() writes final example out
     */
    function writeSource(&$c, $source)
    {
        if ($this->path) {
            $c->writeExample($this->_title, $this->path, $source);
        }
    }

    /**
     * Retrieve a converter-specific link to the example
     *
     * @param Converter &$c the output converter
     *
     * @return string
     * @uses Converter::getExampleLink() retrieve the link to the example
     */
    function getSourceLink(&$c)
    {
        if (!$this->path) return $this->_title;
        return $c->getExampleLink($this->path, $this->_title);
    }
}

?>