Source for file DescHTML.inc

Documentation is available at DescHTML.inc

  1. <?php
  2. /**
  3.  * All abstract representations of html tags in DocBlocks are handled by the
  4.  * classes in this file
  5.  *
  6.  * Before version 1.2, phpDocumentor simply passed html to converters, without
  7.  * much thought, except the {@link adv_htmlentities()} function was provided
  8.  * along with a list of allowed html.  That list is no longer used, in favor
  9.  * of these classes.
  10.  *
  11.  * The PDF Converter output looked wretched in version 1.1.0 because line breaks
  12.  * in DocBlocks were honored.  This meant that output often had just a few words
  13.  * on every other line!  To fix this problem, DocBlock descriptions are now
  14.  * parsed using the {@link ParserDescParser}, and split into paragraphs.  In
  15.  * addition, html in DocBlocks are parsed into these objects to allow for easy
  16.  * conversion in destination converters.  This design also allows different
  17.  * conversion for different templates within a converter, which separates
  18.  * design from logic almost 100%
  19.  *
  20.  * phpDocumentor :: automatic documentation generator
  21.  * 
  22.  * PHP versions 4 and 5
  23.  *
  24.  * Copyright (c) 2002-2007 Gregory Beaver
  25.  * 
  26.  * LICENSE:
  27.  * 
  28.  * This library is free software; you can redistribute it
  29.  * and/or modify it under the terms of the GNU Lesser General
  30.  * Public License as published by the Free Software Foundation;
  31.  * either version 2.1 of the License, or (at your option) any
  32.  * later version.
  33.  * 
  34.  * This library is distributed in the hope that it will be useful,
  35.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  36.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  37.  * Lesser General Public License for more details.
  38.  * 
  39.  * You should have received a copy of the GNU Lesser General Public
  40.  * License along with this library; if not, write to the Free Software
  41.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  42.  * 
  43.  * @category   ToolsAndUtilities
  44.  * @package    phpDocumentor
  45.  * @subpackage DescHTML
  46.  * @author     Greg Beaver <[email protected]>
  47.  * @copyright  2002-2007 Gregory Beaver
  48.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  49.  * @version    CVS: $Id: DescHTML.inc 246329 2007-11-17 03:07:00Z ashnazg $
  50.  * @filesource
  51.  * @link       http://www.phpdoc.org
  52.  * @link       http://pear.php.net/PhpDocumentor
  53.  * @see        parserDocBlock, parserInclude, parserPage, parserClass
  54.  * @see        parserDefine, parserFunction, parserMethod, parserVar
  55.  * @since      1.2
  56.  * @todo       CS cleanup - change package to PhpDocumentor
  57.  */
  58. /**
  59.  * Used for <<code>> in a description
  60.  *
  61.  * @category   ToolsAndUtilities
  62.  * @package    phpDocumentor
  63.  * @subpackage DescHTML
  64.  * @author     Greg Beaver <[email protected]>
  65.  * @copyright  2002-2007 Gregory Beaver
  66.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  67.  * @version    Release: @VER@
  68.  * @link       http://www.phpdoc.org
  69.  * @link       http://pear.php.net/PhpDocumentor
  70.  * @since      1.2
  71.  * @todo       CS cleanup - change package to PhpDocumentor
  72.  * @todo       CS cleanup - rename class to ParserCode
  73.  */
  74. class parserCode extends parserStringWithInlineTags
  75. {
  76.     /**
  77.      * performs the conversion of code tags
  78.      *
  79.      * @param Converter &$c the converter object
  80.      *
  81.      * @return string the converted code block
  82.      * @uses Converter::ProgramExample()
  83.      * @todo CS cleanup - rename method to convert()
  84.      */
  85.     function Convert(&$c)
  86.     {
  87.         if (!isset($this->value[0])) {
  88.             return '';
  89.         }
  90.         if (is_string($this->value[0]) && $this->value[0]{0} == "\n") {
  91.             $this->value[0] = substr($this->value[0], 1);
  92.         }
  93.         $linktags = array();
  94.         foreach ($this->value as $val) {
  95.             if (phpDocumentor_get_class($val) == 'parserlinkinlinetag'
  96.                 || phpDocumentor_get_class($val) == 'parsertutorialinlinetag'
  97.             ) {
  98.                 $linktags[] = array(
  99.                     $c->postProcess($val->Convert($c, false, false)), $val);
  100.             }
  101.         }
  102.         $a = $c->ProgramExample(rtrim(ltrim(parent::Convert($c,
  103.             false, false), "\n\r")));
  104.         foreach ($linktags as $tag) {
  105.             $a = str_replace($tag[0], $tag[1]->Convert($c, false, false), $a);
  106.         }
  107.         return $a;
  108.     }
  109. }
  110.  
  111. /**
  112.  * Used for <<pre>> in a description
  113.  *
  114.  * @category   ToolsAndUtilities
  115.  * @package    phpDocumentor
  116.  * @subpackage DescHTML
  117.  * @author     Greg Beaver <[email protected]>
  118.  * @copyright  2002-2007 Gregory Beaver
  119.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  120.  * @version    Release: @VER@
  121.  * @link       http://www.phpdoc.org
  122.  * @link       http://pear.php.net/PhpDocumentor
  123.  * @since      1.2
  124.  * @todo       CS cleanup - change package to PhpDocumentor
  125.  * @todo       CS cleanup - rename class to ParserPre
  126.  */
  127. class parserPre extends parserStringWithInlineTags
  128. {
  129.     /**
  130.      * performs the conversion of code tags
  131.      *
  132.      * @param Converter &$c the converter object
  133.      *
  134.      * @return string the converted pre block
  135.      * @uses Converter::PreserveWhiteSpace()
  136.      * @todo CS cleanup - rename method to convert()
  137.      */
  138.     function Convert(&$c)
  139.     {
  140.         return $c->PreserveWhiteSpace(rtrim(ltrim(parent::Convert($c,
  141.             false, false), "\n\r")));
  142.     }
  143. }
  144.  
  145. /**
  146.  * Used for <<b>> in a description
  147.  *
  148.  * @category   ToolsAndUtilities
  149.  * @package    phpDocumentor
  150.  * @subpackage DescHTML
  151.  * @author     Greg Beaver <[email protected]>
  152.  * @copyright  2002-2007 Gregory Beaver
  153.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  154.  * @version    Release: @VER@
  155.  * @link       http://www.phpdoc.org
  156.  * @link       http://pear.php.net/PhpDocumentor
  157.  * @since      1.2
  158.  * @todo       CS cleanup - change package to PhpDocumentor
  159.  * @todo       CS cleanup - rename class to ParserB
  160.  */
  161. class parserB extends parserStringWithInlineTags
  162. {
  163.     /**
  164.      * performs the conversion of bold tags
  165.      *
  166.      * @param Converter &$c the converter object
  167.      *
  168.      * @return string the converted pre block
  169.      * @uses Converter::Bolden()
  170.      * @todo CS cleanup - rename method to convert()
  171.      */
  172.     function Convert(&$c)
  173.     {
  174.         return $c->Bolden(parent::Convert($c));
  175.     }
  176. }
  177.  
  178. /**
  179.  * Used for <<i>> in a description
  180.  *
  181.  * @category   ToolsAndUtilities
  182.  * @package    phpDocumentor
  183.  * @subpackage DescHTML
  184.  * @author     Greg Beaver <[email protected]>
  185.  * @copyright  2002-2007 Gregory Beaver
  186.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  187.  * @version    Release: @VER@
  188.  * @link       http://www.phpdoc.org
  189.  * @link       http://pear.php.net/PhpDocumentor
  190.  * @since      1.2
  191.  * @todo       CS cleanup - change package to PhpDocumentor
  192.  * @todo       CS cleanup - rename class to ParserI
  193.  */
  194. class parserI extends parserStringWithInlineTags
  195. {
  196.     /**
  197.      * performs the conversion of italic tags
  198.      *
  199.      * @param Converter &$c the converter object
  200.      *
  201.      * @return string the converted pre block
  202.      * @uses Converter::Italicize()
  203.      * @todo CS cleanup - rename method to convert()
  204.      */
  205.     function Convert(&$c)
  206.     {
  207.         return $c->Italicize(parent::Convert($c));
  208.     }
  209. }
  210.  
  211. /**
  212.  * Used for <<var>> in a description
  213.  *
  214.  * @category   ToolsAndUtilities
  215.  * @package    phpDocumentor
  216.  * @subpackage DescHTML
  217.  * @author     Greg Beaver <[email protected]>
  218.  * @copyright  2002-2007 Gregory Beaver
  219.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  220.  * @version    Release: @VER@
  221.  * @link       http://www.phpdoc.org
  222.  * @link       http://pear.php.net/PhpDocumentor
  223.  * @since      1.2
  224.  * @todo       CS cleanup - change package to PhpDocumentor
  225.  * @todo       CS cleanup - rename class to ParserDescVar
  226.  */
  227. class parserDescVar extends parserStringWithInlineTags
  228. {
  229.     /**
  230.      * performs the conversion of variable tags
  231.      *
  232.      * @param Converter &$c the converter object
  233.      *
  234.      * @return string the converted pre block
  235.      * @uses Converter::Varize()
  236.      * @todo CS cleanup - rename method to convert()
  237.      */
  238.     function Convert(&$c)
  239.     {
  240.         return $c->Varize(parent::Convert($c));
  241.     }
  242. }
  243.  
  244. /**
  245.  * Used for <<samp>> in a description
  246.  *
  247.  * @category   ToolsAndUtilities
  248.  * @package    phpDocumentor
  249.  * @subpackage DescHTML
  250.  * @author     Greg Beaver <[email protected]>
  251.  * @copyright  2002-2007 Gregory Beaver
  252.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  253.  * @version    Release: @VER@
  254.  * @link       http://www.phpdoc.org
  255.  * @link       http://pear.php.net/PhpDocumentor
  256.  * @since      1.2
  257.  * @todo       CS cleanup - change package to PhpDocumentor
  258.  * @todo       CS cleanup - rename class to ParserSamp
  259.  */
  260. class parserSamp extends parserStringWithInlineTags
  261. {
  262.     /**
  263.      * performs the conversion of sample tags
  264.      *
  265.      * @param Converter &$c the converter object
  266.      *
  267.      * @return string the converted pre block
  268.      * @uses Converter::Sampize()
  269.      * @todo CS cleanup - rename method to convert()
  270.      */
  271.     function Convert(&$c)
  272.     {
  273.         return $c->Sampize(parent::Convert($c));
  274.     }
  275. }
  276.  
  277. /**
  278.  * Used for <<kbd>> in a description
  279.  *
  280.  * @category   ToolsAndUtilities
  281.  * @package    phpDocumentor
  282.  * @subpackage DescHTML
  283.  * @author     Greg Beaver <[email protected]>
  284.  * @copyright  2002-2007 Gregory Beaver
  285.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  286.  * @version    Release: @VER@
  287.  * @link       http://www.phpdoc.org
  288.  * @link       http://pear.php.net/PhpDocumentor
  289.  * @since      1.2
  290.  * @todo       CS cleanup - change package to PhpDocumentor
  291.  * @todo       CS cleanup - rename class to ParserKbd
  292.  */
  293. class parserKbd extends parserStringWithInlineTags
  294. {
  295.     /**
  296.      * performs the conversion of keyboard tags
  297.      *
  298.      * @param Converter &$c the converter object
  299.      *
  300.      * @return string the converted pre block
  301.      * @uses Converter::Kbdize()
  302.      * @todo CS cleanup - rename method to convert()
  303.      */
  304.     function Convert(&$c)
  305.     {
  306.         return $c->Kbdize(parent::Convert($c));
  307.     }
  308. }
  309.  
  310. /**
  311.  * Used for <<br>> in a description
  312.  *
  313.  * @category   ToolsAndUtilities
  314.  * @package    phpDocumentor
  315.  * @subpackage DescHTML
  316.  * @author     Greg Beaver <[email protected]>
  317.  * @copyright  2002-2007 Gregory Beaver
  318.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  319.  * @version    Release: @VER@
  320.  * @link       http://www.phpdoc.org
  321.  * @link       http://pear.php.net/PhpDocumentor
  322.  * @since      1.2
  323.  * @todo       CS cleanup - change package to PhpDocumentor
  324.  * @todo       CS cleanup - rename class to ParserBr
  325.  */
  326. class parserBr extends parserStringWithInlineTags
  327. {
  328.     /**
  329.      * performs the conversion of linebreak tags
  330.      *
  331.      * @param Converter &$c the converter object
  332.      *
  333.      * @return string the converted pre block
  334.      * @uses Converter::Br()
  335.      * @todo CS cleanup - rename method to convert()
  336.      */
  337.     function Convert(&$c)
  338.     {
  339.         return $c->Br($this->getString());
  340.     }
  341. }
  342.  
  343. /**
  344.  * Used for lists <<ol>> and <<ul>>
  345.  *
  346.  * @category   ToolsAndUtilities
  347.  * @package    phpDocumentor
  348.  * @subpackage DescHTML
  349.  * @author     Greg Beaver <[email protected]>
  350.  * @copyright  2002-2007 Gregory Beaver
  351.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  352.  * @version    Release: @VER@
  353.  * @link       http://www.phpdoc.org
  354.  * @link       http://pear.php.net/PhpDocumentor
  355.  * @since      1.2
  356.  * @todo       CS cleanup - change package to PhpDocumentor
  357.  * @todo       CS cleanup - rename class to ParserList
  358.  */
  359. class parserList extends parserStringWithInlineTags
  360. {
  361.     /**
  362.      * @var boolean 
  363.      */
  364.     var $numbered;
  365.     /**
  366.      * @var integer 
  367.      */
  368.     var $items = 0;
  369.     /**
  370.      * Constructor - create a new list
  371.      *
  372.      * @param integer $numbered a reference number for the new list
  373.      */
  374.     function parserList($numbered)
  375.     {
  376.         $this->numbered = $numbered;
  377.     }
  378.     
  379.     /**
  380.      * add an item to a list
  381.      *
  382.      * @param parserStringWithInlineTags $item the item to add
  383.      *
  384.      * @return void 
  385.      */
  386.     function addItem($item)
  387.     {
  388.         $this->value[$this->items++] = $item;
  389.     }
  390.     
  391.     /**
  392.      * add a list
  393.      *
  394.      * @param parserList $list the list to add
  395.      *
  396.      * @return void 
  397.      */
  398.     function addList($list)
  399.     {
  400.         $this->value[$this->items++] = $list;
  401.     }
  402.     
  403.     /**
  404.      * performs the conversion of list tags
  405.      *
  406.      * @param Converter &$c the converter object
  407.      *
  408.      * @return string the converted pre block
  409.      * @uses Converter::ListItem() enclose each item of the list
  410.      * @uses Converter::EncloseList() enclose the list
  411.      * @todo CS cleanup - rename method to convert()
  412.      */
  413.     function Convert(&$c)
  414.     {
  415.         $list = '';
  416.         foreach ($this->value as $item) {
  417.             $list .= $c->ListItem(trim($item->Convert($c)));
  418.         }
  419.         return $c->EncloseList($list, $this->numbered);
  420.     }
  421. }
  422.  
  423. ?>
Documentation generated on Tue, 06 Dec 2011 07:05:26 -0600 by phpDocumentor 1.4.4