phpDocumentor phpDocumentor
DocBlockTags
[ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ]

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-2006 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.  * @package    phpDocumentor
  30.  * @subpackage DocBlockTags
  31.  * @author     Greg Beaver <cellog@php.net>
  32.  * @copyright  2002-2006 Gregory Beaver
  33.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  34.  * @version    CVS: $Id: DocBlockTags.inc,v 1.8 2006/10/24 04:18:14 cellog Exp $
  35.  * @filesource
  36.  * @link       http://www.phpdoc.org
  37.  * @link       http://pear.php.net/PhpDocumentor
  38.  * @see        parserDocBlock, parserInclude, parserPage, parserClass
  39.  * @see        parserDefine, parserFunction, parserMethod, parserVar
  40.  * @since      separate file since version 1.2
  41.  */
  42. /**
  43.  * used to represent standard tags like @access, etc.
  44.  * This class is aware of inline tags, and will automatically handle them
  45.  * using inherited functions
  46.  * @package phpDocumentor
  47.  * @subpackage DocBlockTags
  48.  * @author Greg Beaver <cellog@users.sourceforge.net>
  49.  * @since 1.0rc1
  50.  * @version $Id: DocBlockTags.inc,v 1.8 2006/10/24 04:18:14 cellog Exp $
  51.  */
  52. {
  53.     /**
  54.      * Type is used by many functions to skip the hassle of if phpDocumentor_get_class($blah) == 'parserBlah'
  55.      * always '_tag'
  56.      * @var string 
  57.      */
  58.     var $type = '_tag';
  59.     /**
  60.      * tag name (see, access, etc.)
  61.      * @var string 
  62.      */
  63.     var $keyword = '';
  64.     
  65.     /**
  66.      * Set up the tag
  67.      *
  68.      * {@source } 
  69.      * @param string $keyword tag name
  70.      * @param parserStringWithInlineTags $value 
  71.      * @param boolean whether to parse the $value for html tags
  72.      */
  73.     function parserTag($keyword$value$noparse false)
  74.     {
  75.         $this->keyword = $keyword;
  76.         if (!$noparse)
  77.         {
  78.             $parser new parserDescParser;
  79.             $parser->subscribe('*',$this);
  80.             $parser->parse($value->value,true,'parserstringwithinlinetags');
  81.         else $this->value = $value;
  82.     }
  83.     
  84.     /**
  85.      * @param Converter 
  86.      * @see Converter
  87.      */
  88.     function Convert(&$converter)
  89.     {
  90.         if (is_array($this->value))
  91.         {
  92.             if (count($this->value== 1)
  93.             {
  94.                 reset($this->value);
  95.                 list(,$valeach($this->value);
  96.                 $a $val->Convert($converter);
  97.                 return $a;
  98.             }
  99.             $result '';
  100.             foreach($this->value as $val)
  101.             {
  102.                 // this is only true if we processed the description in
  103.                 // the constructor
  104.                 if (phpDocumentor_get_class($val== 'parserstringwithinlinetags')
  105.                 $result .= $converter->EncloseParagraph($val->Convert($converter));
  106.                 else
  107.                 $result .= $val->Convert($converter);
  108.             }
  109.             return $result;
  110.         else
  111.         {
  112.             $a $this->value->Convert($converter);
  113.             return $a;
  114.         }
  115.     }
  116.     
  117.     /**
  118.      * Gets a count of the number of paragraphs in this
  119.      * tag's description.
  120.      *
  121.      * Useful in determining whether to enclose the
  122.      * tag in a paragraph or not.
  123.      * @access private
  124.      * @return integer 
  125.      */
  126.     function _valueParagraphCount()
  127.     {
  128.     }
  129.     
  130.     /**
  131.      * Called by the {@link parserDescParser} when processing a description.
  132.      * @param integer not used
  133.      * @param array array of {@link parserStringWithInlineTags} representing
  134.      *               paragraphs in the tag description
  135.      * @see parserTag::parserTag()
  136.      */
  137.     function HandleEvent($a,$desc)
  138.     {
  139.         $this->value = $desc;
  140.     }
  141.     
  142.     /**
  143.      * @return string returns the text minus any inline tags
  144.      * @see parserStringWithInlineTags::getString()
  145.      */
  146.     function getString()
  147.     {
  148.         if (is_array($this->value))
  149.         {
  150.             $result '';
  151.             foreach($this->value as $val)
  152.             {
  153.                 $result .= $val->getString();
  154.             }
  155.             return $result;
  156.         else return $this->value->getString();
  157.     }
  158. }
  159.  
  160. /**
  161.  * This class represents the @name tag
  162.  * @tutorial tags.name.pkg
  163.  * @package phpDocumentor
  164.  * @subpackage DocBlockTags
  165.  */
  166. class parserNameTag extends parserTag
  167. {
  168.     /**
  169.      * tag name
  170.      * @var string 
  171.      */
  172.     var $keyword = 'name';
  173.     
  174.     /**
  175.      * @param string not used
  176.      * @param string name
  177.      */
  178.     function parserNameTag($name$value)
  179.     {
  180.         $this->value = $value;
  181.     }
  182.     
  183.     /**
  184.      * @see parserStringWithInlineTags::Convert()
  185.      * @param Converter 
  186.      * @return string converted value of the tag
  187.      */
  188.     function Convert(&$c)
  189.     {
  190.         return $this->value;
  191.     }
  192. }
  193.  
  194. /**
  195.  * This class represents the @access tag
  196.  * @tutorial tags.access.pkg
  197.  * @package phpDocumentor
  198.  * @subpackage DocBlockTags
  199.  */
  200. class parserAccessTag extends parserTag
  201. {
  202.     /**
  203.      * tag name
  204.      * @var string 
  205.      */
  206.     var $keyword = 'access';
  207.     
  208.     /**
  209.      * set to true if the returned tag has a value type of private, protected
  210.      * or public, false otherwise
  211.      * @var boolean 
  212.      */
  213.     var $isvalid = false;
  214.     
  215.     /**
  216.      * checks $value to make sure it is private, protected or public, otherwise
  217.      * it's not a valid @access tag
  218.      * @see $isvalid
  219.      * @param parserStringWithInlineTags $value 
  220.      */
  221.     function parserAccessTag($value)
  222.     {
  223.         if (!is_string($value))
  224.         {
  225.             if (is_object($value))
  226.             {
  227.                 if (method_exists($value,'getstring'))
  228.                 {
  229.                     $value $value->getString();
  230.                 }
  231.             }
  232.         }
  233.         switch(trim($value))
  234.         {
  235.             case 'private' :
  236.             case 'public' :
  237.             case 'protected' :
  238.                 $this->value = $value;
  239.                 $this->isvalid = true;
  240.             break;
  241.             default :
  242.             addError(PDERROR_ACCESS_WRONG_PARAM,$value);
  243.                 $this->value = 'public';
  244.             break;
  245.         }
  246.     }
  247.     
  248.     /**
  249.      * @see parserStringWithInlineTags::Convert()
  250.      * @param Converter 
  251.      * @return string converted value of the tag
  252.      */
  253.     function Convert(&$converter)
  254.     {
  255.         return $this->value;
  256.     }
  257.     
  258.     /**
  259.      * No inline tags are possible, returns 'public', 'protected' or 'private'
  260.      * @return string returns the text minus any inline tags
  261.      */
  262.     function getString()
  263.     {
  264.         return $this->value;
  265.     }
  266. }
  267.  
  268. /**
  269.  * represents "@return"
  270.  * @tutorial tags.return.pkg
  271.  * @package phpDocumentor
  272.  * @subpackage DocBlockTags
  273.  * @author Greg Beaver <cellog@users.sourceforge.net>
  274.  * @since 1.0rc1
  275.  * @version $Id: DocBlockTags.inc,v 1.8 2006/10/24 04:18:14 cellog Exp $
  276.  */
  277. class parserReturnTag extends parserTag
  278. {
  279.     /**
  280.      * always 'return'
  281.      * @var string 
  282.      */
  283.     var $keyword = 'return';
  284.     /**
  285.      * the type a function returns
  286.      */
  287.     var $returnType = 'void';
  288.     
  289.     /**
  290.      * contains a link to the documentation for a class passed as a type in @return, @var or @param
  291.      *
  292.      * Example:
  293.      *
  294.      * <code>
  295.      * class myclass
  296.      * {
  297.      * ...
  298.      * }
  299.      * /** @return myclass blahblahblah
  300.      * ...
  301.      * </code>
  302.      *
  303.      * In this case, $converted_returnType will contain a link to myclass instead of the string 'myclass'
  304.      * @var mixed either the same as $returnType or a link to the docs for a class
  305.      * @see $returnType
  306.      */
  307.     var $converted_returnType = false;
  308.     
  309.     /**
  310.      * @param string 
  311.      * @param parserStringWithInlineTags 
  312.      */
  313.     function parserReturnTag($returnType$value)
  314.     {
  315.         $this->returnType = $returnType;
  316.         parent::parserTag('return',$value);
  317.     }
  318.     
  319.     /**
  320.      * sets up $converted_returnType
  321.      * @see parserStringWithInlineTags::Convert(), $converted_returnType
  322.      * @param Converter 
  323.      * @return string converted value of the tag
  324.      */
  325.     function Convert(&$converter)
  326.     {
  327.         $my_types '';
  328.         if (strpos($this->returnType,'|'))
  329.         {
  330.             $types explode('|',$this->returnType);
  331.             foreach($types as $returntype)
  332.             {
  333.                 $a $converter->getLink($returntype);
  334.                 if (is_object($a&& phpDocumentor_get_class($a== 'classlink')
  335.                 {
  336.                     if (!empty($my_types)) $my_types .= '|';
  337.                     $my_types .= $converter->returnSee($a,$converter->type_adjust($returntype));
  338.                 else
  339.                 {
  340.                     if (!empty($my_types)) $my_types .= '|';
  341.                     $my_types .= $converter->type_adjust($returntype);
  342.                 }
  343.             }
  344.             $this->converted_returnType = $my_types;
  345.         else
  346.         {
  347.             $a $converter->getLink($this->returnType);
  348.             if (is_object($a&& phpDocumentor_get_class($a== 'classlink')
  349.             {
  350.                 $this->converted_returnType = $converter->returnSee($a,$converter->type_adjust($this->returnType));
  351.             else
  352.             {
  353.                 $this->converted_returnType = $converter->type_adjust($this->returnType);
  354.             }
  355.         }
  356.         return parserTag::Convert($converter);
  357.     }
  358. }
  359.  
  360. /**
  361.  * represents "@var"
  362.  * @tutorial tags.var.pkg
  363.  * @package phpDocumentor
  364.  * @subpackage DocBlockTags
  365.  * @author Greg Beaver <cellog@users.sourceforge.net>
  366.  * @since 1.0rc1
  367.  * @version $Id: DocBlockTags.inc,v 1.8 2006/10/24 04:18:14 cellog Exp $
  368.  */
  369. class parserVarTag extends parserReturnTag
  370. {
  371.     /**
  372.      * always 'var'
  373.      * @var string 
  374.      */
  375.     var $keyword = 'var';
  376.     /**
  377.      * the type a var has
  378.      * @var string 
  379.      */
  380.     var $returnType = 'mixed';
  381. }
  382.  
  383. /**
  384.  * Represents "@param"
  385.  * @tutorial tags.param.pkg
  386.  * @package phpDocumentor
  387.  * @subpackage DocBlockTags
  388.  */
  389. class parserParamTag extends parserVarTag
  390. {
  391.     /**
  392.      * always 'param'
  393.      * @var string 
  394.      */
  395.     var $keyword = 'param';
  396. }
  397.  
  398. /**
  399.  * Represents "@staticvar"
  400.  * @tutorial tags.staticvar.pkg
  401.  * @package phpDocumentor
  402.  * @subpackage DocBlockTags
  403.  */
  404. {
  405.     /**
  406.      * always 'staticvar'
  407.      * @var string 
  408.      */
  409.     var $keyword = 'staticvar';
  410. }
  411.  
  412. /**
  413.  * represents "@link"
  414.  * @tutorial tags.link.pkg
  415.  * @package phpDocumentor
  416.  * @subpackage DocBlockTags
  417.  * @author Greg Beaver <cellog@users.sourceforge.net>
  418.  * @since 1.0rc1
  419.  * @version $Id: DocBlockTags.inc,v 1.8 2006/10/24 04:18:14 cellog Exp $
  420.  */
  421. class parserLinkTag extends parserTag
  422. {
  423.     /**
  424.      * always 'link'
  425.      * @var string 
  426.      */
  427.     var $keyword = 'link';
  428.     
  429.     /**
  430.      * URL to link to
  431.      * @param string $link 
  432.      */
  433.     function parserLinkTag($link)
  434.     {
  435.         $start $val $link->getString();
  436.         if (strpos($val,' '))
  437.         {
  438.             $start array_shift($val explode(' ',$val));
  439.             $val join($val' ');
  440.         }
  441.         $a new parserLinkInlineTag($start,$val);
  442.         $b new parserStringWithInlineTags;
  443.         $b->add($a);
  444.         $this->value = $b;
  445.     }
  446. }
  447.  
  448. /**
  449.  * represents "@see"
  450.  * @tutorial tags.see.pkg
  451.  * @package phpDocumentor
  452.  * @subpackage DocBlockTags
  453.  * @author Greg Beaver <cellog@users.sourceforge.net>
  454.  * @since 1.0rc1
  455.  * @version $Id: DocBlockTags.inc,v 1.8 2006/10/24 04:18:14 cellog Exp $
  456.  */
  457. class parserSeeTag extends parserLinkTag
  458. {
  459.     /**
  460.      * always 'see'
  461.      * @var string 
  462.      */
  463.     var $keyword = 'see';
  464.     
  465.     /**
  466.      * @param string element to link to
  467.      */
  468.     function parserSeeTag($name)
  469.     {
  470.         parserTag::parserTag($this->keyword,$name,true);
  471.     }
  472.  
  473.     /**
  474.      * @param Converter 
  475.      * @see parserStringWithInlineTags::Convert()
  476.      */
  477.     function Convert(&$converter)
  478.     {
  479.         if ($this->value->hasInlineTag())
  480.         {
  481.             addErrorDie(PDERROR_INLINETAG_IN_SEE);
  482.         }
  483.         $a $converter->getLink(trim($this->value->Convert($converter)));
  484.         if (is_string($a))
  485.         {
  486.             // feature 564991
  487.             if (strpos($a,'://'))
  488.             {
  489.                 // php function
  490.                 return $converter->returnLink($a,str_replace('PHP_MANUAL#','',$this->value->Convert($converter)));
  491.             }
  492.             return $a;
  493.         }
  494.         if (is_object($a)) return $converter->returnSee($a);
  495.         // getLink parsed a comma-delimited list of linked thingies, add the commas back in
  496.         if (is_array($a))
  497.         {
  498.             $b '';
  499.             foreach($a as $i => $bub)
  500.             {
  501.                 if (!empty($b)) $b .= ', ';
  502.                 if (is_string($a[$i])) $b .= $a[$i];
  503.                 if (is_object($a[$i])) $b .= $converter->returnSee($a[$i]);
  504.             }
  505.             return $b;
  506.         }
  507.         return false;
  508.     }
  509. }
  510.  
  511. /**
  512.  * represents "@license"
  513.  *
  514.  * Link to a license, instead of including lines and lines of license information
  515.  * in every file
  516.  * @tutorial tags.license.pkg
  517.  * @package phpDocumentor
  518.  * @subpackage DocBlockTags
  519.  */
  520. {
  521.     /**
  522.      * always 'license'
  523.      * @var string 
  524.      */
  525.     var $keyword = 'license';
  526.     
  527.     /**
  528.      * URL to link to
  529.      * @param string $link 
  530.      */
  531.     function parserLicenseTag($name$link)
  532.     {
  533.         $a explode(' ',$link->getString());
  534.         $url array_shift($a);
  535.         $license join($a,' ');
  536.         if (empty($license)) $license $url;
  537.         $a new parserLinkInlineTag($url$license);
  538.         $b new parserStringWithInlineTags;
  539.         $b->add($a);
  540.         $this->value = $b;
  541.     }
  542. }
  543.  
  544. /**
  545.  * represents "@uses"
  546.  *
  547.  * This is exactly like @see except that the element used has a @useby link to this element added to its docblock
  548.  * @package phpDocumentor
  549.  * @subpackage DocBlockTags
  550.  * @tutorial tags.uses.pkg
  551.  * @since 1.2
  552.  */
  553. class parserUsesTag extends parserSeeTag
  554. {
  555.     /**
  556.      * Always "uses"
  557.      * @var string 
  558.      */
  559.     var $keyword = 'uses';
  560.     /** @access private */
  561.     var $_description;
  562.     
  563.     /**
  564.      * @param string element to link to
  565.      * @param parserStringWithInlineTags description of how the element is used
  566.      */
  567.     function parserUsesTag($seeel$description)
  568.     {
  569.         if ($seeel->hasInlineTag()) {
  570.             addErrorDie(PDERROR_DUMB_USES);
  571.         }
  572.         parent::parserSeeTag($seeel);
  573.         $this->_description $description;
  574.     }
  575.     
  576.     /**
  577.      * Return a link to documentation for other element, and description of how
  578.      * it is used
  579.      *
  580.      * Works exactly like {@link parent::Convert()} except that it also includes
  581.      * a description of how the element used is used.
  582.      * @return string 
  583.      * @param Converter 
  584.      */
  585.     function Convert(&$c)
  586.     {
  587.         $val $this->value;
  588.         $see parent::Convert($c);
  589.         $this->value = $this->_description;
  590.           $desc_val parserTag::Convert($c);
  591.         if (!empty($desc_val)) {
  592.            $see .= ' - '.$desc_val;
  593.         }
  594.         $this->value = $val;
  595.         return $see;
  596.     }
  597.     
  598.     /**
  599.      * Get the text of the link to the element that is being used
  600.      * @return string 
  601.      * @access private
  602.      */
  603.     function getSeeElement()
  604.     {
  605.         return $this->value->getString();
  606.     }
  607.     
  608.     /**
  609.      * Get the description of how the element used is being used.
  610.      * @return parserStringWithInlineTags 
  611.      */
  612.     function getDescription()
  613.     {
  614.         return $this->_description;
  615.     }
  616. }
  617.  
  618. /**
  619.  * This is a virtual tag, it is created by @uses to cross-reference the used element
  620.  *
  621.  * This is exactly like @uses.
  622.  * @package phpDocumentor
  623.  * @subpackage DocBlockTags
  624.  * @since 1.2
  625.  */
  626. {
  627.     /**
  628.      * Always "usedby"
  629.      * @var string 
  630.      */
  631.     var $keyword = 'usedby';
  632.     /** @access private */
  633.     var $_link;
  634.     
  635.     /**
  636.      * @param abstractLink link of element that uses this element
  637.      * @param string description of how the element is used
  638.      */
  639.     function parserUsedByTag($link$description)
  640.     {
  641.         $this->value = $description;
  642.         $this->_link $link;
  643.     }
  644.     
  645.     /**
  646.      * @return string 
  647.      * @param Converter 
  648.      */
  649.     function Convert(&$c)
  650.     {
  651.         $see $c->returnSee($this->_link);
  652.           $desc_val parserTag::Convert($c);
  653.         if (!empty($desc_val)) {
  654.            $see .= ' - '.$desc_val;
  655.         }
  656.         return $see;
  657.     }
  658. }
  659.  
  660. /**
  661.  * represents "@tutorial"
  662.  *
  663.  * This is exactly like @see except that it only links to tutorials
  664.  * @tutorial phpDocumentor/tutorials.pkg
  665.  * @tutorial tags.tutorial.pkg
  666.  * @package phpDocumentor
  667.  * @subpackage DocBlockTags
  668.  * @since 1.2
  669.  */
  670. {
  671.     /**
  672.      * Always "tutorial"
  673.      * @var string 
  674.      */
  675.     var $keyword = 'tutorial';
  676.     /**
  677.      * @param Converter 
  678.      * @see parserStringWithInlineTags::Convert()
  679.      */
  680.     function Convert(&$converter)
  681.     {
  682.         $a $converter->getTutorialLink(trim($this->value->Convert($converter)));
  683.         if (is_string($a))
  684.         {
  685.             return $a;
  686.         }
  687.         if (is_object($a)) return $converter->returnSee($a);
  688.         // getLink parsed a comma-delimited list of linked thingies, add the commas back in
  689.         if (is_array($a))
  690.         {
  691.             $b '';
  692.             foreach($a as $i => $bub)
  693.             {
  694.                 if (!empty($b)) $b .= ', ';
  695.                 if (is_string($a[$i])) $b .= $a[$i];
  696.                 if (is_object($a[$i])) $b .= $converter->returnSee($a[$i]);
  697.             }
  698.             return $b;
  699.         }
  700.         return false;
  701.     }
  702. }
  703.  
  704. /**
  705.  * represents "@filesource"
  706.  * 
  707.  * Use this to create a link to a highlighted phpxref-style source file listing
  708.  * @package phpDocumentor
  709.  * @subpackage DocBlockTags
  710.  * @tutorial tags.filesource.pkg
  711.  */
  712. {
  713.     /**
  714.      * Always "filesource"
  715.      * @var string 
  716.      */
  717.     var $keyword = 'filesource';
  718.     /** @var array */
  719.     var $source;
  720.     /** @var string */
  721.     var $path;
  722.     /**
  723.      * Flag variable, controls double writes of file for each converter
  724.      * @access private
  725.      * @var array 
  726.      */
  727.     var $_converted array();
  728.     /**
  729.      * Set {@link $source} to $value, and set up path
  730.      * @param string 
  731.      * @param array output from {@link phpDocumentorTWordParser::getFileSource()}
  732.      */
  733.     function parserFileSourceTag($filepath$value)
  734.     {
  735.         parent::parserTag($this->keyword'');
  736.         $this->path = $filepath;
  737.         $this->source = $value;
  738.     }
  739.  
  740.     /**
  741.      * Return a link to the highlighted source and generate the source
  742.      * @uses ConvertSource() generate source code and write it out
  743.      * @return string output from {@link getSourceLink()}
  744.      * @param Converter 
  745.      */
  746.     function Convert(&$c)
  747.     {
  748.         $this->ConvertSource($c);
  749.         return $this->getSourceLink($c);
  750.     }
  751.  
  752.     /**
  753.      * @param Converter 
  754.      * @uses phpDocumentor_HighlightParser highlights source code
  755.      * @uses writeSource()
  756.      */
  757.     function ConvertSource(&$c)
  758.     {
  759.         $this->writeSource($c$c->ProgramExample($this->sourcetruefalsefalsefalse$this->path));
  760.         return;
  761.         $parser new phpDocumentor_HighlightParser;
  762.         $return '';
  763.         $return $parser->parse($this->source,$cfalsefalsefalse$this->path);
  764.         $this->writeSource($c$return);
  765.     }
  766.  
  767.     /**
  768.      * @param Converter 
  769.      * @param string highlighted source code
  770.      * @uses Converter::writeSource() export highlighted file source
  771.      */
  772.     function writeSource(&$c$source)
  773.     {
  774.         $c->writeSource($this->path$source);
  775.     }
  776.  
  777.     /**
  778.      * @uses Converter::getSourceLink()
  779.      * @param Converter 
  780.      * @return output from getSourceLink()
  781.      */
  782.     function getSourceLink(&$c)
  783.     {
  784.         return $c->getSourceLink($this->path);
  785.     }
  786. }
  787.  
  788. /**
  789.  * represents "@example"
  790.  * 
  791.  * The example tag
  792.  * @package phpDocumentor
  793.  * @subpackage DocBlockTags
  794.  * @tutorial tags.example.pkg
  795.  */
  796. {
  797.     /**
  798.      * always "example"
  799.      * @var string 
  800.      */
  801.     var $keyword = 'example';
  802.     /**
  803.      * Reads and parses the example file indicated
  804.      *
  805.      * The example tag takes one parameter: the full path to a php file that
  806.      * should be parsed and included as an example.
  807.      * @uses phpDocumentorTWordParser::getFileSource() uses to parse an example
  808.      *        and retrieve all tokens by line number
  809.      * @param parserStringWithInlineTags 
  810.      * @param string path of file containing this @example tag
  811.      */
  812.     function parserExampleTag($value$current_path)
  813.     {
  814.         global $_phpDocumentor_setting;
  815.         parent::parserTag('example'$value);
  816.         $path false;
  817.         // code thanks to Sam Blum, modified by Greg Beaver
  818.         $tagValue $value->getString();
  819.         $path $isAbsPath $pathOnly $fileName $fileExt $original_path  $title FALSE;
  820.         do
  821.         {
  822.             // make sure the format is stuff.ext description
  823.             if (!preg_match('`(.*)\.(\w*)\s(.*)`'$tagValue$match))
  824.             {
  825.                 // or format is stuff.ext
  826.                 if (!preg_match('`(.*)\.(\w*)\s*$`'$tagValue$match))
  827.                 {
  828.                     // Murphy: Some funny path was given
  829.                     $original_path $tagValue// used for error output
  830.                     break// try-block
  831.                 }
  832.             }
  833.             if (strlen($match[1]=== 0)
  834.             {
  835.                 // Murphy: Some funny path was given
  836.                 $original_path $tagValue// used for error output
  837.                 break// try-block
  838.             }
  839.             $fileExt $match[2];
  840.             $title 'example';
  841.             if (isset($match[3]))
  842.             {
  843.                 $title trim($match[3]);
  844.             }
  845.             $pathTmp str_replace('\\''/'$match[1])// Replace windows '\' the path.
  846.  
  847.             // Is there a path and a file or is it just a file?
  848.             if (strpos($pathTmp,'/'=== false)
  849.             {
  850.                 // No path part
  851.                 $pathOnly '';
  852.                 $fileName $pathTmp .'.'$fileExt;
  853.             else
  854.             {
  855.                 $splitPos strrpos($pathTmp,'/')// split the path on the last directory, find the filename
  856.                 $pathOnly substr($match[1]0$splitPos+1);
  857.                 $fileName substr($match[1]$splitPos+1.'.'$fileExt;
  858.                 // Is the path absolute? (i.e. does it start like an absolute path?)
  859.                 if (('/' === $pathTmp[0]|| preg_match('`^\w*:`i'$pathTmp))
  860.                 // works for both windows 'C:' and URLs like 'http://'
  861.                     $isAbsPath true// Yes
  862.                 }
  863.             }
  864.  
  865.             $original_path $pathOnly $fileName;
  866.  
  867.             // Now look for the file starting with abs. path.
  868.             if ($isAbsPath)
  869.             {
  870.                 $tmp realpath($original_path)// remove any weirdities like /../file.ext
  871.                 if ($tmp && is_file($tmp))
  872.                 {
  873.                     $path $tmp;
  874.                 }
  875.                 // Alway break if abs. path was detected; even if file was not found.
  876.                 break// try-block
  877.             }
  878.  
  879.             // Search for the example file some standard places 
  880.             // 1) Look if the ini-var examplesdir is set and look there ...
  881.             if (isset($_phpDocumentor_setting['examplesdir']))
  882.             {
  883.                 $tmp realpath($_phpDocumentor_setting['examplesdir'PATH_DELIMITER  $original_path);
  884.                 if ($tmp && is_file($tmp))
  885.                 {
  886.                     $path $tmp// Yo! found it :)
  887.                     break// try-block
  888.                 }
  889.             }
  890.  
  891.             // 2) Then try to look for an 'example/'-dir below the *currently* parsed file ...
  892.             if (!empty($current_path))
  893.             {
  894.                 $tmp realpath(dirname($current_pathPATH_DELIMITER 'examples' PATH_DELIMITER $fileName);
  895.                 if ($tmp && is_file($tmp))
  896.                 {
  897.                     $path $tmp// Yo! found it :)
  898.                     break// try-block
  899.                 }
  900.             }
  901.  
  902.             // 3) Then try to look for the example file below the subdir PHPDOCUMENTOR_BASE/examples/ ...
  903.             if (is_dir(PHPDOCUMENTOR_BASE PATH_DELIMITER 'examples'))
  904.             {
  905.                 $tmp realpath(PHPDOCUMENTOR_BASE PATH_DELIMITER 'examples' PATH_DELIMITER $original_path);
  906.                 if ($tmp && is_file($tmp))
  907.                 {
  908.                     $path $tmp// Yo! found it :)
  909.                     break// try-block
  910.                 }
  911.             }
  912.  
  913.             $tmp realpath(PHPDOCUMENTOR_BASE PATH_DELIMITER $original_path);
  914.             if ($tmp && is_file($tmp))
  915.             {
  916.                 $path $tmp// Yo! found it :)
  917.                 break// try-block
  918.             }
  919.             // If we reach this point, nothing was found and $path is false.
  920.         while (false);
  921.  
  922.         if (!$path)
  923.         {
  924.             addWarning(PDERROR_EXAMPLE_NOT_FOUND$original_path);
  925.             $this->_title 'example not found';
  926.             $this->path = false;
  927.         else
  928.         {
  929.             $this->_title ($title$title 'example';
  930.             // make a unique html-filename but avoid it to get too long.
  931.             $uniqueFileName str_replace(array(':'DIRECTORY_SEPARATOR,'/')array('_''_''_')$path);
  932.             $uniqueFileName substr($uniqueFileName,-50'_' md5($path);
  933.             $this->path = $uniqueFileName;
  934.             
  935.             $f @fopen($path,'r');
  936.             if ($f)
  937.             {
  938.                 $example fread($f,filesize($path));
  939.                 if (tokenizer_ext)
  940.                 {
  941.                     $obj new phpDocumentorTWordParser;
  942.                     $obj->setup($example);
  943.                     $this->source = $obj->getFileSource();
  944.                     $this->origsource $example;
  945.                     unset($obj);
  946.                 else
  947.                 {
  948.                     $this->source = $example;
  949.                 }
  950.             }
  951.         }
  952.     }
  953.     
  954.     /**
  955.      * @param Converter 
  956.      * @uses phpDocumentor_HighlightParser highlights source code
  957.      * @uses writeSource()
  958.      */
  959.     function ConvertSource(&$c)
  960.     {
  961.         $this->writeSource($c$c->ProgramExample($this->sourcetruenull,
  962.                             nullnullnull$this->origsource));
  963.         return;
  964.         $parser new phpDocumentor_HighlightParser;
  965.         $return '';
  966.         $return $parser->parse($this->source,$c);
  967.         $this->writeSource($c$return);
  968.     }
  969.  
  970.     /**
  971.      * @param Converter $c 
  972.      * @param string parsed example source
  973.      * @uses Converter::writeExample() writes final example out
  974.      * @access private
  975.      */
  976.     function writeSource(&$c$source)
  977.     {
  978.         if ($this->path)
  979.         $c->writeExample($this->_title$this->path$source);
  980.     }
  981.  
  982.     /**
  983.      * Retrieve a converter-specific link to the example
  984.      *
  985.      * @param Converter 
  986.      * @uses Converter::getExampleLink() retrieve the link to the example
  987.      */
  988.     function getSourceLink(&$c)
  989.     {
  990.         if (!$this->pathreturn $this->_title;
  991.         return $c->getExampleLink($this->path$this->_title);
  992.     }
  993. }
  994.  
  995. ?>

Documentation generated on Tue, 24 Oct 2006 09:22:13 -0500 by phpDocumentor 1.3.1