Source for file DocBlockTags.inc

Documentation is available at DocBlockTags.inc

  1. <?php
  2. /**
  3.  * All abstract representations of DocBlock tags are defined
  4.  * by the classes in this file
  5.  *
  6.  * phpDocumentor :: automatic documentation generator
  7.  * 
  8.  * PHP versions 4 and 5
  9.  *
  10.  * Copyright (c) 2002-2008 Gregory Beaver
  11.  * 
  12.  * LICENSE:
  13.  * 
  14.  * This library is free software; you can redistribute it
  15.  * and/or modify it under the terms of the GNU Lesser General
  16.  * Public License as published by the Free Software Foundation;
  17.  * either version 2.1 of the License, or (at your option) any
  18.  * later version.
  19.  * 
  20.  * This library is distributed in the hope that it will be useful,
  21.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  22.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  23.  * Lesser General Public License for more details.
  24.  * 
  25.  * You should have received a copy of the GNU Lesser General Public
  26.  * License along with this library; if not, write to the Free Software
  27.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  28.  *
  29.  * @category   ToolsAndUtilities
  30.  * @package    phpDocumentor
  31.  * @subpackage DocBlockTags
  32.  * @author     Greg Beaver <[email protected]>
  33.  * @copyright  2002-2008 Gregory Beaver
  34.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  35.  * @version    CVS: $Id: DocBlockTags.inc 287889 2009-08-30 07:27:39Z ashnazg $
  36.  * @filesource
  37.  * @link       http://www.phpdoc.org
  38.  * @link       http://pear.php.net/PhpDocumentor
  39.  * @see        parserDocBlock, parserInclude, parserPage, parserClass
  40.  * @see        parserDefine, parserFunction, parserMethod, parserVar
  41.  * @since      separate file since version 1.2
  42.  * @todo       CS cleanup - change package to PhpDocumentor
  43.  */
  44. /**
  45.  * used to represent standard tags like @access, etc.
  46.  * This class is aware of inline tags, and will automatically handle them
  47.  * using inherited functions
  48.  *
  49.  * @category   ToolsAndUtilities
  50.  * @package    phpDocumentor
  51.  * @subpackage DocBlockTags
  52.  * @author     Greg Beaver <[email protected]>
  53.  * @copyright  2002-2008 Gregory Beaver
  54.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  55.  * @version    Release: @VER@
  56.  * @link       http://www.phpdoc.org
  57.  * @link       http://pear.php.net/PhpDocumentor
  58.  * @since      1.0rc1
  59.  * @todo       CS cleanup - change package to PhpDocumentor
  60.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  61.  */
  62. {
  63.     /**
  64.      * Type is used by many functions to skip the hassle of
  65.      * if phpDocumentor_get_class($blah) == 'parserBlah' always '_tag'
  66.      * @var string 
  67.      */
  68.     var $type = '_tag';
  69.     /**
  70.      * tag name (see, access, etc.)
  71.      * @var string 
  72.      */
  73.     var $keyword = '';
  74.     
  75.     /**
  76.      * Set up the tag
  77.      *
  78.      * {@source } 
  79.      *
  80.      * @param string                     $keyword tag name
  81.      * @param parserStringWithInlineTags $value   tag value
  82.      * @param boolean                    $noparse whether to parse the $value
  83.      *                                             for html tags
  84.      */
  85.     function parserTag($keyword$value$noparse false)
  86.     {
  87.         $this->keyword = $keyword;
  88.         if (!$noparse{
  89.             $parser new parserDescParser;
  90.             $parser->subscribe('*'$this);
  91.             $parser->parse($value->valuetrue'parserstringwithinlinetags');
  92.         else 
  93.             $this->value = $value
  94.         }
  95.     }
  96.     
  97.     /**
  98.      * Perform the output conversion on this {@link parserTag}
  99.      * using the {@link Converter output converter} that is passed in
  100.      *
  101.      * @param Converter &$converter the converter object
  102.      *
  103.      * @return string 
  104.      * @see Converter
  105.      * @todo CS cleanup - rename to convert for camelCase rule
  106.      */
  107.     function Convert(&$converter)
  108.     {
  109.         if (is_array($this->value)) {
  110.             if (count($this->value== 1{
  111.                 reset($this->value);
  112.                 list($valeach($this->value);
  113.                 $a           $val->Convert($converter);
  114.                 return $a;
  115.             }
  116.             $result '';
  117.             foreach ($this->value as $val{
  118.                 // this is only true if we processed the description
  119.                 // in the constructor
  120.                 if (phpDocumentor_get_class($val
  121.                         == 'parserstringwithinlinetags'{
  122.                     $result .= $converter->
  123.                         EncloseParagraph($val->Convert($converter));
  124.                 else {
  125.                     $result .= $val->Convert($converter);
  126.                 }
  127.             }
  128.             return $result;
  129.         else {
  130.             $a $this->value->Convert($converter);
  131.             return $a;
  132.         }
  133.     }
  134.     
  135.     /**
  136.      * Gets a count of the number of paragraphs in this
  137.      * tag's description.
  138.      *
  139.      * Useful in determining whether to enclose the
  140.      * tag in a paragraph or not.
  141.      *
  142.      * @return integer (actually, body is empty, so it doesn't return at all)
  143.      * @access private
  144.      * @todo does this need to be implemented?  its body is empty
  145.      */
  146.     function _valueParagraphCount()
  147.     {
  148.     }
  149.     
  150.     /**
  151.      * Called by the {@link parserDescParser} when processing a description.
  152.      *
  153.      * @param integer $a    not used
  154.      * @param array   $desc array of {@link parserStringWithInlineTags}
  155.      *                       representing paragraphs in the tag description
  156.      *
  157.      * @return void 
  158.      * @see parserTag::parserTag()
  159.      * @todo CS cleanup - rename to handleEvent for camelCase rule
  160.      */
  161.     function HandleEvent($a,$desc)
  162.     {
  163.         $this->value = $desc;
  164.     }
  165.     
  166.     /**
  167.      * Returns the text minus any inline tags
  168.      *
  169.      * @return string the text minus any inline tags
  170.      * @see parserStringWithInlineTags::getString()
  171.      */
  172.     function getString()
  173.     {
  174.         if (is_array($this->value)) {
  175.             $result '';
  176.             foreach ($this->value as $val{
  177.                 $result .= $val->getString();
  178.             }
  179.             return $result;
  180.         else {
  181.             return $this->value->getString();
  182.         }
  183.     }
  184. }
  185.  
  186. /**
  187.  * This class represents the @name tag
  188.  *
  189.  * @category   ToolsAndUtilities
  190.  * @package    phpDocumentor
  191.  * @subpackage DocBlockTags
  192.  * @author     Greg Beaver <[email protected]>
  193.  * @copyright  2002-2008 Gregory Beaver
  194.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  195.  * @version    Release: @VER@
  196.  * @link       http://www.phpdoc.org
  197.  * @link       http://pear.php.net/PhpDocumentor
  198.  * @tutorial   tags.name.pkg
  199.  * @todo       CS cleanup - change package to PhpDocumentor
  200.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  201.  */
  202. class parserNameTag extends parserTag
  203. {
  204.     /**
  205.      * tag name
  206.      * @var string 
  207.      */
  208.     var $keyword = 'name';
  209.     
  210.     /**
  211.      * set up the name tag
  212.      *
  213.      * @param string $name  tag name (not used)
  214.      * @param string $value tag value
  215.      */
  216.     function parserNameTag($name$value)
  217.     {
  218.         $this->value = $value;
  219.     }
  220.     
  221.     /**
  222.      * process this tag through the given output converter
  223.      *
  224.      * @param Converter &$c output converter
  225.      *
  226.      * @return string converted value of the tag
  227.      * @see parserStringWithInlineTags::Convert()
  228.      * @todo CS cleanup - rename to convert for camelCase rule
  229.      */
  230.     function Convert(&$c)
  231.     {
  232.         return $this->value;
  233.     }
  234. }
  235.  
  236. /**
  237.  * This class represents the @access tag
  238.  *
  239.  * @category   ToolsAndUtilities
  240.  * @package    phpDocumentor
  241.  * @subpackage DocBlockTags
  242.  * @author     Greg Beaver <[email protected]>
  243.  * @copyright  2002-2008 Gregory Beaver
  244.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  245.  * @version    Release: @VER@
  246.  * @link       http://www.phpdoc.org
  247.  * @link       http://pear.php.net/PhpDocumentor
  248.  * @tutorial   tags.access.pkg
  249.  * @todo       CS cleanup - change package to PhpDocumentor
  250.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  251.  */
  252. class parserAccessTag extends parserTag
  253. {
  254.     /**
  255.      * tag name
  256.      * @var string 
  257.      */
  258.     var $keyword = 'access';
  259.     
  260.     /**
  261.      * set to true if the returned tag has a value type of private, protected
  262.      * or public, false otherwise
  263.      * @var boolean 
  264.      */
  265.     var $isvalid = false;
  266.     
  267.     /**
  268.      * checks $value to make sure it is private, protected or public, otherwise
  269.      * it's not a valid @access tag
  270.      *
  271.      * @param parserStringWithInlineTags $value the tag value
  272.      *
  273.      * @see $isvalid
  274.      */
  275.     function parserAccessTag($value)
  276.     {
  277.         if (!is_string($value)) {
  278.             if (is_object($value)) {
  279.                 if (method_exists($value'getstring')) {
  280.                     $value $value->getString();
  281.                 }
  282.             }
  283.         }
  284.         switch(trim($value)) {
  285.         case 'private' :
  286.         case 'public' :
  287.         case 'protected' :
  288.             $this->value   = $value;
  289.             $this->isvalid = true;
  290.             break;
  291.         default :
  292.             addError(PDERROR_ACCESS_WRONG_PARAM$value);
  293.             $this->value = 'public';
  294.             break;
  295.         }
  296.     }
  297.     
  298.     /**
  299.      * process this tag through the given output converter
  300.      *
  301.      * @param Converter &$converter the output converter
  302.      *
  303.      * @return string converted value of the tag
  304.      * @see parserStringWithInlineTags::Convert()
  305.      * @todo CS cleanup - rename to convert for camelCase rule
  306.      */
  307.     function Convert(&$converter)
  308.     {
  309.         return $this->value;
  310.     }
  311.     
  312.     /**
  313.      * No inline tags are possible, returns 'public', 'protected' or 'private'
  314.      *
  315.      * @return string returns the text minus any inline tags
  316.      */
  317.     function getString()
  318.     {
  319.         return $this->value;
  320.     }
  321. }
  322.  
  323. /**
  324.  * represents the "@return" tag
  325.  *
  326.  * @category   ToolsAndUtilities
  327.  * @package    phpDocumentor
  328.  * @subpackage DocBlockTags
  329.  * @author     Greg Beaver <[email protected]>
  330.  * @copyright  2002-2008 Gregory Beaver
  331.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  332.  * @version    Release: @VER@
  333.  * @link       http://www.phpdoc.org
  334.  * @link       http://pear.php.net/PhpDocumentor
  335.  * @tutorial   tags.return.pkg
  336.  * @since      1.0rc1
  337.  * @todo       CS cleanup - change package to PhpDocumentor
  338.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  339.  */
  340. class parserReturnTag extends parserTag
  341. {
  342.     /**
  343.      * always 'return'
  344.      * @var string 
  345.      */
  346.     var $keyword = 'return';
  347.     /**
  348.      * the type a function returns
  349.      */
  350.     var $returnType = 'void';
  351.     
  352.     /**
  353.      * contains a link to the documentation for a class
  354.      * passed as a type in @return, @var or @param
  355.      *
  356.      * Example:
  357.      *
  358.      * <code>
  359.      * class myclass
  360.      * {
  361.      * ...
  362.      * }
  363.      * /** @return myclass blahblahblah
  364.      * ...
  365.      * </code>
  366.      *
  367.      * In this case, $converted_returnType will contain a link to myclass
  368.      * instead of the string 'myclass'
  369.      *
  370.      * @var mixed either the same as $returnType or a link to the docs for a class
  371.      * @see $returnType
  372.      */
  373.     var $converted_returnType = false;
  374.     
  375.     /**
  376.      * set up the tag
  377.      *
  378.      * @param string                     $returnType returned datatype
  379.      * @param parserStringWithInlineTags $value      tag value
  380.      */
  381.     function parserReturnTag($returnType$value)
  382.     {
  383.         $this->returnType = $returnType;
  384.         parent::parserTag('return'$value);
  385.     }
  386.     
  387.     /**
  388.      * process this tag through the given output converter
  389.      * (sets up the $converted_returnType)
  390.      *
  391.      * @param Converter &$converter the output converter
  392.      *
  393.      * @return string converted value of the tag
  394.      * @see parserStringWithInlineTags::Convert(), $converted_returnType
  395.      * @todo CS cleanup - rename to convert for camelCase rule
  396.      */
  397.     function Convert(&$converter)
  398.     {
  399.         $my_types '';
  400.         if (strpos($this->returnType'|')) {
  401.             $types explode('|'$this->returnType);
  402.             foreach ($types as $returntype{
  403.                 $a $converter->getLink($returntype);
  404.                 if (is_object($a&& phpDocumentor_get_class($a== 'classlink'{
  405.                     if (!empty($my_types)) {
  406.                         $my_types .= '|';
  407.                     }
  408.                     $my_types .= $converter->
  409.                         returnSee($a$converter->type_adjust($returntype));
  410.                 else {
  411.                     if (!empty($my_types)) {
  412.                         $my_types .= '|';
  413.                     }
  414.                     $my_types .= $converter->type_adjust($returntype);
  415.                 }
  416.             }
  417.             $this->converted_returnType = $my_types;
  418.         else {
  419.             $a $converter->getLink($this->returnType);
  420.             if (is_object($a&& phpDocumentor_get_class($a== 'classlink'{
  421.                 $this->converted_returnType = $converter->
  422.                     returnSee($a$converter->type_adjust($this->returnType));
  423.             else {
  424.                 $this->converted_returnType = $converter->
  425.                     type_adjust($this->returnType);
  426.             }
  427.         }
  428.         return parserTag::Convert($converter);
  429.     }
  430. }
  431.  
  432. /**
  433.  * represents the "@property" tag
  434.  *
  435.  * @category   ToolsAndUtilities
  436.  * @package    phpDocumentor
  437.  * @subpackage DocBlockTags
  438.  * @author     Greg Beaver <[email protected]>
  439.  * @copyright  2002-2008 Gregory Beaver
  440.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  441.  * @version    Release: @VER@
  442.  * @link       http://www.phpdoc.org
  443.  * @link       http://pear.php.net/PhpDocumentor
  444.  * @tutorial   tags.property.pkg
  445.  * @since      1.4.0a1
  446.  * @todo       CS cleanup - change package to PhpDocumentor
  447.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  448.  */
  449. {
  450.     /**
  451.      * always 'property'
  452.      * @var string 
  453.      */
  454.     var $keyword = 'property';
  455.     /**
  456.      * the type a property has
  457.      * @var string 
  458.      */
  459.     var $returnType = 'mixed';
  460.  
  461.     /**
  462.      * set up the property tag
  463.      *
  464.      * @param string                     $returnType the tag value's datatype
  465.      * @param parserStringWithInlineTags $value      the tag value
  466.      */
  467.     function parserPropertyTag($returnType$value)
  468.     {
  469.         $this->returnType = $returnType;
  470.         parent::parserTag($this->keyword$value);
  471.     }
  472. }
  473.  
  474. /**
  475.  * represents the "@property-read" tag
  476.  *
  477.  * @category   ToolsAndUtilities
  478.  * @package    phpDocumentor
  479.  * @subpackage DocBlockTags
  480.  * @author     Greg Beaver <[email protected]>
  481.  * @copyright  2002-2008 Gregory Beaver
  482.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  483.  * @version    Release: @VER@
  484.  * @link       http://www.phpdoc.org
  485.  * @link       http://pear.php.net/PhpDocumentor
  486.  * @tutorial   tags.property.pkg
  487.  * @since      1.4.0a1
  488.  * @todo       CS cleanup - change package to PhpDocumentor
  489.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  490.  */
  491. {
  492.     /**
  493.      * always 'property-read'
  494.      * @var string 
  495.      */
  496.     var $keyword = 'property-read';
  497. }
  498.  
  499. /**
  500.  * represents the "@property-write" tag
  501.  *
  502.  * @category   ToolsAndUtilities
  503.  * @package    phpDocumentor
  504.  * @subpackage DocBlockTags
  505.  * @author     Greg Beaver <[email protected]>
  506.  * @copyright  2002-2008 Gregory Beaver
  507.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  508.  * @version    Release: @VER@
  509.  * @link       http://www.phpdoc.org
  510.  * @link       http://pear.php.net/PhpDocumentor
  511.  * @tutorial   tags.property.pkg
  512.  * @since      1.4.0a1
  513.  * @todo       CS cleanup - change package to PhpDocumentor
  514.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  515.  */
  516. {
  517.     /**
  518.      * always 'property-write'
  519.      * @var string 
  520.      */
  521.     var $keyword = 'property-write';
  522. }
  523.  
  524. /**
  525.  * represents the "@method" tag
  526.  *
  527.  * @category   ToolsAndUtilities
  528.  * @package    phpDocumentor
  529.  * @subpackage DocBlockTags
  530.  * @author     Greg Beaver <[email protected]>
  531.  * @copyright  2002-2008 Gregory Beaver
  532.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  533.  * @version    Release: @VER@
  534.  * @link       http://www.phpdoc.org
  535.  * @link       http://pear.php.net/PhpDocumentor
  536.  * @tutorial   tags.method.pkg
  537.  * @since      1.4.0a1
  538.  * @todo       CS cleanup - change package to PhpDocumentor
  539.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  540.  */
  541. {
  542.     /**
  543.      * always 'method'
  544.      * @var string 
  545.      */
  546.     var $keyword = 'method';
  547.     /**
  548.      * the return type a method has
  549.      * @var string 
  550.      */
  551.     var $returnType = 'void';
  552. }
  553.  
  554. /**
  555.  * represents the "@var" tag
  556.  *
  557.  * @category   ToolsAndUtilities
  558.  * @package    phpDocumentor
  559.  * @subpackage DocBlockTags
  560.  * @author     Greg Beaver <[email protected]>
  561.  * @copyright  2002-2008 Gregory Beaver
  562.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  563.  * @version    Release: @VER@
  564.  * @link       http://www.phpdoc.org
  565.  * @link       http://pear.php.net/PhpDocumentor
  566.  * @tutorial   tags.var.pkg
  567.  * @since      1.0rc1
  568.  * @todo       CS cleanup - change package to PhpDocumentor
  569.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  570.  */
  571. class parserVarTag extends parserReturnTag
  572. {
  573.     /**
  574.      * always 'var'
  575.      * @var string 
  576.      */
  577.     var $keyword = 'var';
  578.     /**
  579.      * the type a var has
  580.      * @var string 
  581.      */
  582.     var $returnType = 'mixed';
  583. }
  584.  
  585. /**
  586.  * represents the "@param" tag
  587.  *
  588.  * @category   ToolsAndUtilities
  589.  * @package    phpDocumentor
  590.  * @subpackage DocBlockTags
  591.  * @author     Greg Beaver <[email protected]>
  592.  * @copyright  2002-2008 Gregory Beaver
  593.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  594.  * @version    Release: @VER@
  595.  * @link       http://www.phpdoc.org
  596.  * @link       http://pear.php.net/PhpDocumentor
  597.  * @tutorial   tags.param.pkg
  598.  * @todo       CS cleanup - change package to PhpDocumentor
  599.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  600.  */
  601. class parserParamTag extends parserVarTag
  602. {
  603.     /**
  604.      * always 'param'
  605.      * @var string 
  606.      */
  607.     var $keyword = 'param';
  608. }
  609.  
  610. /**
  611.  * represents the "@staticvar" tag
  612.  *
  613.  * @category   ToolsAndUtilities
  614.  * @package    phpDocumentor
  615.  * @subpackage DocBlockTags
  616.  * @author     Greg Beaver <[email protected]>
  617.  * @copyright  2002-2008 Gregory Beaver
  618.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  619.  * @version    Release: @VER@
  620.  * @link       http://www.phpdoc.org
  621.  * @link       http://pear.php.net/PhpDocumentor
  622.  * @tutorial   tags.staticvar.pkg
  623.  * @todo       CS cleanup - change package to PhpDocumentor
  624.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  625.  */
  626. {
  627.     /**
  628.      * always 'staticvar'
  629.      * @var string 
  630.      */
  631.     var $keyword = 'staticvar';
  632. }
  633.  
  634. /**
  635.  * represents the "@link" tag
  636.  *
  637.  * @category   ToolsAndUtilities
  638.  * @package    phpDocumentor
  639.  * @subpackage DocBlockTags
  640.  * @author     Greg Beaver <[email protected]>
  641.  * @copyright  2002-2008 Gregory Beaver
  642.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  643.  * @version    Release: @VER@
  644.  * @link       http://www.phpdoc.org
  645.  * @link       http://pear.php.net/PhpDocumentor
  646.  * @since      1.0rc1
  647.  * @tutorial   tags.link.pkg
  648.  * @todo       CS cleanup - change package to PhpDocumentor
  649.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  650.  */
  651. class parserLinkTag extends parserTag
  652. {
  653.     /**
  654.      * always 'link'
  655.      * @var string 
  656.      */
  657.     var $keyword = 'link';
  658.     
  659.     /**
  660.      * sets up the link tag
  661.      *
  662.      * @param string $link URL to link to
  663.      *                      (might also contain the URL's
  664.      *                      description text)
  665.      */
  666.     function parserLinkTag($link)
  667.     {
  668.         $start $val $link->getString();
  669.         if (strpos($val' ')) {
  670.             $val   explode(' '$val);
  671.             $start array_shift($val);
  672.             $val   join($val' ');
  673.         }
  674.         $a new parserLinkInlineTag($start$val);
  675.         $b new parserStringWithInlineTags;
  676.         $b->add($a);
  677.         $this->value = $b;
  678.     }
  679. }
  680.  
  681. /**
  682.  * represents the "@see" tag
  683.  *
  684.  * @category   ToolsAndUtilities
  685.  * @package    phpDocumentor
  686.  * @subpackage DocBlockTags
  687.  * @author     Greg Beaver <[email protected]>
  688.  * @copyright  2002-2008 Gregory Beaver
  689.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  690.  * @version    Release: @VER@
  691.  * @link       http://www.phpdoc.org
  692.  * @link       http://pear.php.net/PhpDocumentor
  693.  * @since      1.0rc1
  694.  * @tutorial   tags.see.pkg
  695.  * @todo       CS cleanup - change package to PhpDocumentor
  696.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  697.  */
  698. class parserSeeTag extends parserLinkTag
  699. {
  700.     /**
  701.      * always 'see'
  702.      * @var string 
  703.      */
  704.     var $keyword = 'see';
  705.     
  706.     /**
  707.      * sets up the see tag
  708.      *
  709.      * @param string $name element to link to
  710.      */
  711.     function parserSeeTag($name)
  712.     {
  713.         parserTag::parserTag($this->keyword$nametrue);
  714.     }
  715.  
  716.     /**
  717.      * process this tag through the given output converter
  718.      *
  719.      * @param Converter &$converter the output converter
  720.      *
  721.      * @return string converted value of the tag
  722.      * @see parserStringWithInlineTags::Convert()
  723.      * @todo CS cleanup - rename to convert for camelCase rule
  724.      */
  725.     function Convert(&$converter)
  726.     {
  727.         if ($this->value->hasInlineTag()) {
  728.             addErrorDie(PDERROR_INLINETAG_IN_SEE);
  729.         }
  730.         $a $converter->getLink(trim($this->value->Convert($converter)));
  731.         if (is_string($a)) {
  732.             // feature 564991
  733.             if (strpos($a'://')) {
  734.                 // php function
  735.                 return $converter->returnLink($astr_replace('PHP_MANUAL#'''
  736.                     $this->value->Convert($converter)));
  737.             }
  738.             return $a;
  739.         }
  740.         if (is_object($a)) {
  741.             return $converter->returnSee($a);
  742.         }
  743.         // getLink parsed a comma-delimited list of linked thingies, 
  744.         // add the commas back in
  745.         if (is_array($a)) {
  746.             $b '';
  747.             foreach ($a as $i => $bub{
  748.                 if (!empty($b)) {
  749.                     $b .= ', ';
  750.                 }
  751.                 if (is_string($a[$i])) {
  752.                     $b .= $a[$i];
  753.                 }
  754.                 if (is_object($a[$i])) {
  755.                     $b .= $converter->returnSee($a[$i]);
  756.                 }
  757.             }
  758.             return $b;
  759.         }
  760.         return false;
  761.     }
  762. }
  763.  
  764. /**
  765.  * represents the "@see" tag
  766.  *
  767.  * Link to a license, instead of including lines and lines of license information
  768.  * in every file
  769.  *
  770.  * @category   ToolsAndUtilities
  771.  * @package    phpDocumentor
  772.  * @subpackage DocBlockTags
  773.  * @author     Greg Beaver <[email protected]>
  774.  * @copyright  2002-2008 Gregory Beaver
  775.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  776.  * @version    Release: @VER@
  777.  * @link       http://www.phpdoc.org
  778.  * @link       http://pear.php.net/PhpDocumentor
  779.  * @tutorial   tags.license.pkg
  780.  * @todo       CS cleanup - change package to PhpDocumentor
  781.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  782.  */
  783. {
  784.     /**
  785.      * always 'license'
  786.      * @var string 
  787.      */
  788.     var $keyword = 'license';
  789.     
  790.     /**
  791.      * set up the license tag
  792.      *
  793.      * @param string $name unused?
  794.      * @param string $link URL to link to
  795.      */
  796.     function parserLicenseTag($name$link)
  797.     {
  798.         $a       explode(' '$link->getString());
  799.         $url     array_shift($a);
  800.         $license join($a' ');
  801.         if (empty($license)) {
  802.             $license $url;
  803.         }
  804.         $a new parserLinkInlineTag($url$license);
  805.         $b new parserStringWithInlineTags;
  806.         $b->add($a);
  807.         $this->value = $b;
  808.     }
  809. }
  810.  
  811. /**
  812.  * represents the "@uses" tag
  813.  *
  814.  * This is exactly like @see except that the element used
  815.  * has a @useby link to this element added to its docblock
  816.  *
  817.  * @category   ToolsAndUtilities
  818.  * @package    phpDocumentor
  819.  * @subpackage DocBlockTags
  820.  * @author     Greg Beaver <[email protected]>
  821.  * @copyright  2002-2008 Gregory Beaver
  822.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  823.  * @version    Release: @VER@
  824.  * @link       http://www.phpdoc.org
  825.  * @link       http://pear.php.net/PhpDocumentor
  826.  * @since      1.2
  827.  * @tutorial   tags.uses.pkg
  828.  * @todo       CS cleanup - change package to PhpDocumentor
  829.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  830.  */
  831. class parserUsesTag extends parserSeeTag
  832. {
  833.     /**
  834.      * Always "uses"
  835.      * @var string 
  836.      */
  837.     var $keyword = 'uses';
  838.     /**
  839.      * @access private
  840.      */
  841.     var $_description;
  842.     
  843.     /**
  844.      * set up the uses tag
  845.      *
  846.      * @param string                     $seeel       element to link to
  847.      * @param parserStringWithInlineTags $description description of how
  848.      *                                                 the element is used
  849.      */
  850.     function parserUsesTag($seeel$description)
  851.     {
  852.         if ($seeel->hasInlineTag()) {
  853.             addErrorDie(PDERROR_DUMB_USES);
  854.         }
  855.         parent::parserSeeTag($seeel);
  856.         $this->_description $description;
  857.     }
  858.     
  859.     /**
  860.      * Return a link to documentation for other element,
  861.      * and description of how it is used
  862.      *
  863.      * Works exactly like {@link parent::Convert()}
  864.      * except that it also includes a description of
  865.      * how the element used is used.
  866.      *
  867.      * @param Converter &$c the output converter
  868.      *
  869.      * @return string link to the uses target
  870.      * @todo CS cleanup - rename to convert for camelCase rule
  871.      */
  872.     function Convert(&$c)
  873.     {
  874.         $val         $this->value;
  875.         $see         parent::Convert($c);
  876.         $this->value = $this->_description;
  877.         $desc_val    parserTag::Convert($c);
  878.         if (!empty($desc_val)) {
  879.             $see .= ' - '.$desc_val;
  880.         }
  881.         $this->value = $val;
  882.         return $see;
  883.     }
  884.     
  885.     /**
  886.      * Get the text of the link to the element that is being used
  887.      *
  888.      * @return string 
  889.      * @access private
  890.      */
  891.     function getSeeElement()
  892.     {
  893.         return $this->value->getString();
  894.     }
  895.     
  896.     /**
  897.      * Get the description of how the element used is being used.
  898.      *
  899.      * @return parserStringWithInlineTags 
  900.      */
  901.     function getDescription()
  902.     {
  903.         return $this->_description;
  904.     }
  905. }
  906.  
  907. /**
  908.  * This is a virtual tag, it is created by @uses to cross-reference the used element
  909.  *
  910.  * This is exactly like @uses.
  911.  *
  912.  * @category   ToolsAndUtilities
  913.  * @package    phpDocumentor
  914.  * @subpackage DocBlockTags
  915.  * @author     Greg Beaver <[email protected]>
  916.  * @copyright  2002-2008 Gregory Beaver
  917.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  918.  * @version    Release: @VER@
  919.  * @link       http://www.phpdoc.org
  920.  * @link       http://pear.php.net/PhpDocumentor
  921.  * @since      1.2
  922.  * @todo       CS cleanup - change package to PhpDocumentor
  923.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  924.  */
  925. {
  926.     /**
  927.      * Always "usedby"
  928.      * @var string 
  929.      */
  930.     var $keyword = 'usedby';
  931.     /**
  932.      * @access private
  933.      */
  934.     var $_link;
  935.     
  936.     /**
  937.      * set up the usedby tag
  938.      *
  939.      * @param abstractLink $link        link of element that uses this element
  940.      * @param string       $description description of how the element is used
  941.      */
  942.     function parserUsedByTag($link$description)
  943.     {
  944.         $this->value = $description;
  945.         $this->_link $link;
  946.     }
  947.     
  948.     /**
  949.      * process this tag through the given output converter
  950.      *
  951.      * @param Converter &$c the output converter
  952.      *
  953.      * @return string 
  954.      * @todo CS cleanup - rename to convert for camelCase rule
  955.      */
  956.     function Convert(&$c)
  957.     {
  958.         $see      $c->returnSee($this->_link);
  959.         $desc_val parserTag::Convert($c);
  960.         if (!empty($desc_val)) {
  961.             $see .= ' - '.$desc_val;
  962.         }
  963.         return $see;
  964.     }
  965. }
  966.  
  967. /**
  968.  * represents "@tutorial"
  969.  *
  970.  * This is exactly like @see except that it only links to tutorials
  971.  *
  972.  * @category   ToolsAndUtilities
  973.  * @package    phpDocumentor
  974.  * @subpackage DocBlockTags
  975.  * @author     Greg Beaver <[email protected]>
  976.  * @copyright  2002-2008 Gregory Beaver
  977.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  978.  * @version    Release: @VER@
  979.  * @link       http://www.phpdoc.org
  980.  * @link       http://pear.php.net/PhpDocumentor
  981.  * @since      1.2
  982.  * @tutorial   phpDocumentor/tutorials.pkg
  983.  * @tutorial   tags.tutorial.pkg
  984.  * @todo       CS cleanup - change package to PhpDocumentor
  985.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  986.  */
  987. {
  988.     /**
  989.      * Always "tutorial"
  990.      * @var string 
  991.      */
  992.     var $keyword = 'tutorial';
  993.  
  994.     /**
  995.      * process this tag through the given output converter
  996.      *
  997.      * @param Converter &$converter the output converter
  998.      *
  999.      * @return string|bool
  1000.      * @see parserStringWithInlineTags::Convert()
  1001.      * @todo CS cleanup - rename to convert for camelCase rule
  1002.      */
  1003.     function Convert(&$converter)
  1004.     {
  1005.         $a $converter->getTutorialLink(trim($this->value->Convert($converter)));
  1006.         if (is_string($a)) {
  1007.             return $a;
  1008.         }
  1009.         if (is_object($a)) {
  1010.             return $converter->returnSee($a);
  1011.         }
  1012.         // getLink parsed a comma-delimited list of linked thingies, 
  1013.         // add the commas back in
  1014.         if (is_array($a)) {
  1015.             $b '';
  1016.             foreach ($a as $i => $bub{
  1017.                 if (!empty($b)) {
  1018.                     $b .= ', ';
  1019.                 }
  1020.                 if (is_string($a[$i])) {
  1021.                     $b .= $a[$i];
  1022.                 }
  1023.                 if (is_object($a[$i])) {
  1024.                     $b .= $converter->returnSee($a[$i]);
  1025.                 }
  1026.             }
  1027.             return $b;
  1028.         }
  1029.         return false;
  1030.     }
  1031. }
  1032.  
  1033. /**
  1034.  * represents "@filesource"
  1035.  * 
  1036.  * Use this to create a link to a highlighted phpxref-style source file listing
  1037.  *
  1038.  * @category   ToolsAndUtilities
  1039.  * @package    phpDocumentor
  1040.  * @subpackage DocBlockTags
  1041.  * @author     Greg Beaver <[email protected]>
  1042.  * @copyright  2002-2008 Gregory Beaver
  1043.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  1044.  * @version    Release: @VER@
  1045.  * @link       http://www.phpdoc.org
  1046.  * @link       http://pear.php.net/PhpDocumentor
  1047.  * @since      1.2
  1048.  * @tutorial   tags.filesource.pkg
  1049.  * @todo       CS cleanup - change package to PhpDocumentor
  1050.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  1051.  */
  1052. {
  1053.     /**
  1054.      * Always "filesource"
  1055.      * @var string 
  1056.      */
  1057.     var $keyword = 'filesource';
  1058.     /**
  1059.      * @var array 
  1060.      */
  1061.     var $source;
  1062.     /**
  1063.      * @var string 
  1064.      */
  1065.     var $path;
  1066.     /**
  1067.      * Flag variable, controls double writes of file for each converter
  1068.      * @var array 
  1069.      * @access private
  1070.      */
  1071.     var $_converted array();
  1072.  
  1073.     /**
  1074.      * Set {@link $source} to $value, and set up path
  1075.      *
  1076.      * @param string $filepath the file's path
  1077.      * @param array  $value    output from
  1078.      *                          {@link phpDocumentorTWordParser::getFileSource()}
  1079.      */
  1080.     function parserFileSourceTag($filepath$value)
  1081.     {
  1082.         parent::parserTag($this->keyword'');
  1083.         $this->path   = $filepath;
  1084.         $this->source = $value;
  1085.     }
  1086.  
  1087.     /**
  1088.      * Return a link to the highlighted source and generate the source
  1089.      *
  1090.      * @param Converter &$c the output converter
  1091.      *
  1092.      * @return string output from {@link getSourceLink()}
  1093.      * @uses ConvertSource() generate source code and write it out
  1094.      * @todo CS cleanup - rename to convert for camelCase rule
  1095.      */
  1096.     function Convert(&$c)
  1097.     {
  1098.         $this->ConvertSource($c);
  1099.         return $this->getSourceLink($c);
  1100.     }
  1101.  
  1102.     /**
  1103.      * convert the source code
  1104.      *
  1105.      * @param Converter &$c the output converter
  1106.      *
  1107.      * @return void 
  1108.      * @uses phpDocumentor_HighlightParser highlights source code
  1109.      * @uses writeSource()
  1110.      * @todo CS cleanup - rename to convertSource for camelCase rule
  1111.      * @todo what's up with all the "return" statements?
  1112.      *        can they _all_ be removed?
  1113.      */
  1114.     function ConvertSource(&$c)
  1115.     {
  1116.         $this->writeSource($c$c->
  1117.             ProgramExample($this->sourcetruefalsefalsefalse$this->path));
  1118.         return;
  1119.         $parser new phpDocumentor_HighlightParser;
  1120.         $return '';
  1121.         $return $parser->
  1122.             parse($this->source$cfalsefalsefalse$this->path);
  1123.         $this->writeSource($c$return);
  1124.     }
  1125.  
  1126.     /**
  1127.      * have the output converter write the source code
  1128.      *
  1129.      * @param Converter &$c     the output converter
  1130.      * @param string    $source highlighted source code
  1131.      *
  1132.      * @return void 
  1133.      * @uses Converter::writeSource() export highlighted file source
  1134.      */
  1135.     function writeSource(&$c$source)
  1136.     {
  1137.         $c->writeSource($this->path$source);
  1138.     }
  1139.  
  1140.     /**
  1141.      * gets path to the sourcecode file
  1142.      *
  1143.      * @param Converter &$c the output converter
  1144.      *
  1145.      * @return output from getSourceLink()
  1146.      * @uses Converter::getSourceLink()
  1147.      */
  1148.     function getSourceLink(&$c)
  1149.     {
  1150.         return $c->getSourceLink($this->path);
  1151.     }
  1152. }
  1153.  
  1154. /**
  1155.  * represents "@example"
  1156.  * 
  1157.  * @category   ToolsAndUtilities
  1158.  * @package    phpDocumentor
  1159.  * @subpackage DocBlockTags
  1160.  * @author     Greg Beaver <[email protected]>
  1161.  * @copyright  2002-2008 Gregory Beaver
  1162.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  1163.  * @version    Release: @VER@
  1164.  * @link       http://www.phpdoc.org
  1165.  * @link       http://pear.php.net/PhpDocumentor
  1166.  * @tutorial   tags.example.pkg
  1167.  * @todo       CS cleanup - change package to PhpDocumentor
  1168.  * @todo       CS cleanup - change classname to PhpDocumentor_*
  1169.  */
  1170. {
  1171.     /**
  1172.      * always "example"
  1173.      * @var string 
  1174.      */
  1175.     var $keyword = 'example';
  1176.  
  1177.     /**
  1178.      * Reads and parses the example file indicated
  1179.      *
  1180.      * The example tag takes one parameter: the full path to a php file that
  1181.      * should be parsed and included as an example.
  1182.      *
  1183.      * @param parserStringWithInlineTags $value        tag value
  1184.      * @param string                     $current_path path of file containing
  1185.      *                                                  this @example tag
  1186.      *
  1187.      * @uses phpDocumentorTWordParser::getFileSource() uses to parse an example
  1188.      *        and retrieve all tokens by line number
  1189.      * @todo does this "x = y = z = false" still work as expected in PHP5?
  1190.      * @todo CS cleanup - rename constant to TOKENIZER_EXT
  1191.      */
  1192.     function parserExampleTag($value$current_path)
  1193.     {
  1194.         global $_phpDocumentor_setting;
  1195.         parent::parserTag('example'$value);
  1196.         $path false;
  1197.         // code thanks to Sam Blum, modified by Greg Beaver
  1198.         $tagValue $value->getString();
  1199.  
  1200.         $path $isAbsPath 
  1201.               = $pathOnly 
  1202.               = $fileName 
  1203.               = $fileExt 
  1204.               = $original_path  
  1205.               = $title 
  1206.               = false;
  1207.         do {
  1208.             // make sure the format is stuff.ext description
  1209.             if (!preg_match('`(.*)\.(\w*)\s(.*)`'$tagValue$match)) {
  1210.                 // or format is stuff.ext
  1211.                 if (!preg_match('`(.*)\.(\w*)\s*$`'$tagValue$match)) {
  1212.                     // Murphy: Some funny path was given
  1213.                     $original_path $tagValue// used for error output
  1214.                     break// try-block
  1215.                 }
  1216.             }
  1217.             if (strlen($match[1]=== 0{
  1218.                 // Murphy: Some funny path was given
  1219.                 $original_path $tagValue// used for error output
  1220.                 break// try-block
  1221.             }
  1222.             $fileExt $match[2];
  1223.             $title   'example';
  1224.             if (isset($match[3])) {
  1225.                 $title trim($match[3]);
  1226.             }
  1227.             // Replace windows '\' the path.
  1228.             $pathTmp str_replace('\\''/'$match[1])
  1229.  
  1230.             // Is there a path and a file or is it just a file?
  1231.             if (strpos($pathTmp'/'=== false{
  1232.                 // No path part
  1233.                 $pathOnly '';
  1234.                 $fileName $pathTmp .'.'$fileExt;
  1235.             else {
  1236.                 // split the path on the last directory, find the filename
  1237.                 $splitPos strrpos($pathTmp'/')
  1238.                 $pathOnly substr($match[1]0$splitPos+1);
  1239.                 $fileName substr($match[1]$splitPos+1.'.'$fileExt;
  1240.                 // Is the path absolute? (i.e. does it start like an absolute path?)
  1241.                 if (('/' === $pathTmp[0]|| preg_match('`^\w*:`i'$pathTmp)) 
  1242.                     // works for both windows 'C:' and URLs like 'http://'
  1243.                     $isAbsPath true// Yes
  1244.                 }
  1245.             }
  1246.  
  1247.             $original_path $pathOnly $fileName;
  1248.  
  1249.             // Now look for the file starting with abs. path.
  1250.             if ($isAbsPath{
  1251.                 // remove any weirdities like /../file.ext
  1252.                 $tmp realpath($original_path)
  1253.                 if ($tmp && is_file($tmp)) {
  1254.                     $path $tmp;
  1255.                 }
  1256.                 // Alway break if abs. path was detected,
  1257.                 // even if file was not found.
  1258.                 break// try-block
  1259.             }
  1260.  
  1261.             // Search for the example file some standard places 
  1262.             // 1) Look if the ini-var examplesdir is set and look there ...
  1263.             if (isset($_phpDocumentor_setting['examplesdir'])) {
  1264.                 $tmp realpath($_phpDocumentor_setting['examplesdir'
  1265.                     . PATH_DELIMITER  $original_path);
  1266.                 if ($tmp && is_file($tmp)) {
  1267.                     $path $tmp// Yo! found it :)
  1268.                     break// try-block
  1269.                 }
  1270.             }
  1271.  
  1272.             // 2) Then try to look for an 'example/'-dir 
  1273.             //    below the *currently* parsed file ...
  1274.             if (!empty($current_path)) {
  1275.                 $tmp realpath(dirname($current_pathPATH_DELIMITER 
  1276.                     . 'examples' PATH_DELIMITER $fileName);
  1277.                 if ($tmp && is_file($tmp)) {
  1278.                     $path $tmp// Yo! found it :)
  1279.                     break// try-block
  1280.                 }
  1281.             }
  1282.  
  1283.             // 3) Then try to look for the example file 
  1284.             //    below the subdir PHPDOCUMENTOR_BASE/examples/ ...
  1285.             if (is_dir(PHPDOCUMENTOR_BASE PATH_DELIMITER 'examples')) {
  1286.                 $tmp realpath(PHPDOCUMENTOR_BASE PATH_DELIMITER 
  1287.                     . 'examples' PATH_DELIMITER $original_path);
  1288.                 if ($tmp && is_file($tmp)) {
  1289.                     $path $tmp// Yo! found it :)
  1290.                     break// try-block
  1291.                 }
  1292.             }
  1293.  
  1294.             $tmp realpath(PHPDOCUMENTOR_BASE PATH_DELIMITER $original_path);
  1295.             if ($tmp && is_file($tmp)) {
  1296.                 $path $tmp// Yo! found it :)
  1297.                 break// try-block
  1298.             }
  1299.             // If we reach this point, nothing was found and $path is false.
  1300.         while (false);
  1301.  
  1302.         if (!$path{
  1303.             addWarning(PDERROR_EXAMPLE_NOT_FOUND$original_path);
  1304.             $this->_title 'example not found';
  1305.             $this->path   = false;
  1306.         else {
  1307.             $this->_title ($title$title 'example';
  1308.             // make a unique html-filename but avoid it to get too long.
  1309.             $uniqueFileName str_replace(array(':'
  1310.                 DIRECTORY_SEPARATOR'/')array('_''_''_')$path);
  1311.             $uniqueFileName substr($uniqueFileName-50'_' md5($path);
  1312.             $this->path     = $uniqueFileName;
  1313.             
  1314.             $f @fopen($path'r');
  1315.             if ($f{
  1316.                 $example fread($ffilesize($path));
  1317.                 if (tokenizer_ext{
  1318.                     $obj new phpDocumentorTWordParser;
  1319.                     $obj->setup($example);
  1320.                     $this->source     = $obj->getFileSource();
  1321.                     $this->origsource $example;
  1322.                     unset($obj);
  1323.                 else {
  1324.                     $this->source = $example;
  1325.                 }
  1326.             }
  1327.         }
  1328.     }
  1329.     
  1330.     /**
  1331.      * convert the source code
  1332.      *
  1333.      * @param Converter &$c the output converter
  1334.      *
  1335.      * @return void 
  1336.      * @uses phpDocumentor_HighlightParser highlights source code
  1337.      * @uses writeSource()
  1338.      * @todo CS cleanup - rename to convertSource for camelCase rule
  1339.      * @todo what's up with all the "return" statements?
  1340.      *        can they _all_ be removed?
  1341.      */
  1342.     function ConvertSource(&$c)
  1343.     {
  1344.         $this->writeSource($c$c->ProgramExample($this->sourcetruenull,
  1345.                             nullnullnull$this->origsource));
  1346.         return;
  1347.         $parser new phpDocumentor_HighlightParser;
  1348.         $return '';
  1349.         $return $parser->parse($this->source$c);
  1350.         $this->writeSource($c$return);
  1351.     }
  1352.  
  1353.     /**
  1354.      * have the output converter write the source code
  1355.      *
  1356.      * @param Converter &$c     the output converter
  1357.      * @param string    $source highlighted source code
  1358.      *
  1359.      * @return void 
  1360.      * @access private
  1361.      * @uses Converter::writeExample() writes final example out
  1362.      */
  1363.     function writeSource(&$c$source)
  1364.     {
  1365.         if ($this->path{
  1366.             $c->writeExample($this->_title$this->path$source);
  1367.         }
  1368.     }
  1369.  
  1370.     /**
  1371.      * Retrieve a converter-specific link to the example
  1372.      *
  1373.      * @param Converter &$c the output converter
  1374.      *
  1375.      * @return string 
  1376.      * @uses Converter::getExampleLink() retrieve the link to the example
  1377.      */
  1378.     function getSourceLink(&$c)
  1379.     {
  1380.         if (!$this->pathreturn $this->_title;
  1381.         return $c->getExampleLink($this->path$this->_title);
  1382.     }
  1383. }
  1384.  
  1385. ?>

Documentation generated on Mon, 05 Dec 2011 21:20:40 -0600 by phpDocumentor 1.4.4