mods/phpdoc2/PhpDocumentor/phpDocumentor/PackagePageElements.inc

   1 <?php\r
   2 /**\r
   3  * Data structures used in parsing XML DocBook-based tutorials\r
   4  *\r
   5  * Conversion of DocBook-based tutorials is performed using special\r
   6  * {@link Converter} class methods.  By default, these methods simply retrieve\r
   7  * simple rules for replacement of tags and slight re-ordering from the\r
   8  * options.ini file present for every template.\r
   9  *\r
  10  * In future versions, there may be utilization of xslt or other more powerful\r
  11  * protocols.  However, for most situations, the power of these classes will\r
  12  * be more than sufficient to handle very complex documentation.\r
  13  *\r
  14  * Note that an entire tutorial is contained in a single parserXMLDocBookTag,\r
  15  * matching the document model for DocBook.  The top-level tag, <refentry>,\r
  16  * contains every other tag and all text.\r
  17  * \r
  18  * phpDocumentor :: automatic documentation generator\r
  19  * \r
  20  * PHP versions 4 and 5\r
  21  *\r
  22  * Copyright (c) 2002-2006 Gregory Beaver\r
  23  * \r
  24  * LICENSE:\r
  25  * \r
  26  * This library is free software; you can redistribute it\r
  27  * and/or modify it under the terms of the GNU Lesser General\r
  28  * Public License as published by the Free Software Foundation;\r
  29  * either version 2.1 of the License, or (at your option) any\r
  30  * later version.\r
  31  * \r
  32  * This library is distributed in the hope that it will be useful,\r
  33  * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  34  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\r
  35  * Lesser General Public License for more details.\r
  36  * \r
  37  * You should have received a copy of the GNU Lesser General Public\r
  38  * License along with this library; if not, write to the Free Software\r
  39  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\r
  40  *\r
  41  * @package    phpDocumentor\r
  42  * @subpackage Tutorial\r
  43  * @author     Gregory Beaver <cellog@php.net>\r
  44  * @copyright  2002-2006 Gregory Beaver\r
  45  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL\r
  46  * @version    CVS: $Id: PackagePageElements.inc,v 1.4 2006/05/22 01:07:28 cellog Exp $\r
  47  * @tutorial tutorials.pkg\r
  48  * @link       http://www.phpdoc.org\r
  49  * @link       http://pear.php.net/PhpDocumentor\r
  50  * @since      1.2.0\r
  51  */\r
  52 /**\r
  53  * Represents <![CDATA[ ]]> sections.\r
  54  *\r
  55  * These sections are interpreted as plain text\r
  56  * @package phpDocumentor\r
  57  * @subpackage Tutorial\r
  58  */\r
  59 class parserCData extends parserStringWithInlineTags\r
  60 {\r
  61     /**\r
  62      * @uses Converter::getCData() convert contents to text\r
  63      * @param Converter\r
  64      */\r
  65     function Convert(&$c, $postprocess = true)\r
  66     {\r
  67         $val = $this->value;\r
  68         if ($postprocess)\r
  69         foreach($this->value as $key => $value)\r
  70         {\r
  71             if (is_string($value)) $this->value[$key] = $c->getCData($value);\r
  72         }\r
  73         $this->cache = false;\r
  74         $x = parent::Convert($c, false);\r
  75         $this->value = $val;\r
  76         return $x;\r
  77     }\r
  78 }\r
  79 /**\r
  80  * a standard XML DocBook Tag\r
  81  *\r
  82  * This class is designed to represent all DocBook tags.  It is intelligent\r
  83  * enough to understand the <title> tag, and also the <refname> tag for\r
  84  * as title for <refentry>\r
  85  * @since 1.2\r
  86  * @package phpDocumentor\r
  87  * @subpackage Tutorial\r
  88  */\r
  89 class parserXMLDocBookTag extends parserStringWithInlineTags\r
  90 {\r
  91     /**\r
  92      * Attributes from the XML tag\r
  93      *\r
  94      * Format: array(attrname => attrvalue, attrname => attrvalue,...)\r
  95      * @var array\r
  96      */\r
  97     var $attributes = array();\r
  98     /**\r
  99      * Name of the tag\r
 100      * @var string\r
 101      */\r
 102     var $name;\r
 103     /**#@+ @access private */\r
 104     /** @var parserCData */\r
 105     var $_cdata;\r
 106     /** @var parserTag */\r
 107     var $_title;\r
 108     /** @var parserIdLineTag */\r
 109     var $_id;\r
 110     /**\r
 111      * Set to <refpurpose> in <refsynopsisdiv>\r
 112      * @var parserTag\r
 113      */\r
 114     var $_description;\r
 115     /**#@-*/\r
 116     /**\r
 117      * @param string tag name\r
 118      */\r
 119     function parserXMLDocBookTag($name)\r
 120     {\r
 121         $this->name = $name;\r
 122     }\r
 123     \r
 124     /**\r
 125      * @param Converter\r
 126      * @param boolean\r
 127      * @uses Converter::TranslateTag() Calls this to enclose the contents of the\r
 128      *       DocBook tag based on the values in template options.ini file\r
 129      */\r
 130     function Convert(&$c, $postprocess = true)\r
 131     {\r
 132         $value = parent::Convert($c, $postprocess);\r
 133         $simvalue = parent::Convert($c, false);\r
 134         foreach($this->attributes as $a => $v)\r
 135         {\r
 136             $this->attributes[$a] = (is_string($v) ? $v : $v->Convert($c, $postprocess));\r
 137         }\r
 138         if (isset($this->_title))\r
 139         {\r
 140             list($this->attributes,$value) = $c->ConvertTitle($this->name, $this->attributes, $this->_title->Convert($c, $postprocess), $value);\r
 141         }\r
 142         return $c->TranslateTag($this->name,$this->attributes,$value,$simvalue);\r
 143     }\r
 144     \r
 145     /**\r
 146      * Begin a new CData section\r
 147      * @see addCData()\r
 148      */\r
 149     function startCData()\r
 150     {\r
 151         $this->_cdata = new parserCData;\r
 152     }\r
 153     \r
 154     /**\r
 155      * Adds {@link $_cdata} to {@link $value}\r
 156      */\r
 157     function endCData()\r
 158     {\r
 159         $this->value[] = $this->_cdata;\r
 160         unset($this->_cdata);\r
 161     }\r
 162     \r
 163     /**\r
 164      * Retrieve either the table of contents index, or the location that\r
 165      * the TOC will go\r
 166      * @see setTOC()\r
 167      * @param false|integer either an index of the {@}toc} tag in $this->value\r
 168      *                      or false, if the next index value of $this->value\r
 169      *                      is needed\r
 170      */\r
 171     function getTOC($state = false)\r
 172     {\r
 173         if ($state !== false) return $this->value[$state];\r
 174         return count($this->value);\r
 175     }\r
 176     \r
 177     /**\r
 178      * @param integer index of the TOC in $this->value\r
 179      * @param parserTocInlineTag\r
 180      */\r
 181     function setTOC($state, $val)\r
 182     {\r
 183         $this->value[$state] = $val;\r
 184     }\r
 185     \r
 186     /**\r
 187      * add a word to CData\r
 188      * @param string\r
 189      */\r
 190     function addCData($word)\r
 191     {\r
 192         $this->_cdata->add($word);\r
 193     }\r
 194     \r
 195     /**\r
 196      * Add an xml tag attribute name="value" pair\r
 197      *\r
 198      * if the attribute is id, value must be a {@link parserIdInlineTag}\r
 199      * @param string attribute name\r
 200      * @param string|parserIdInlineTag value of attribute\r
 201      */\r
 202     function addAttribute($name,$value)\r
 203     {\r
 204         $this->attributes[$name] = $value;\r
 205         if ($name == 'id')\r
 206         {\r
 207             // fix 1153593\r
 208             if (is_string($value))\r
 209             {\r
 210                 addWarning(PDERROR_ID_MUST_BE_INLINE,$this->name,$value,$this->name,$value);\r
 211             } else {\r
 212                 $this->setId($value);\r
 213             }\r
 214         }\r
 215     }\r
 216     \r
 217     /**\r
 218      * Set the title of a DocBook tag section.\r
 219      *\r
 220      * For most DocBook tags, the title is represented with a <title></title>\r
 221      * tag pair.  The <refentry> top-level tag is a little different.  Instead\r
 222      * of using <title></title>, phpDocumentor uses the contents of the\r
 223      * <refname> tag in the <refnamediv> tag\r
 224      * @param parserXMLDocBookTag the title element\r
 225      */\r
 226     function setTitle($title)\r
 227     {\r
 228         $this->_title = $title;\r
 229     }\r
 230     \r
 231     /**\r
 232      * If the id attribute is present, this method will set its id\r
 233      * @param parserIdInlineTag\r
 234      */\r
 235     function setId($id)\r
 236     {\r
 237         $this->_id = $id;\r
 238     }\r
 239     \r
 240     /**\r
 241      * Return converter-specific formatting of ID.\r
 242      *\r
 243      * Passes $c to {@link parserIdInlineTag::Convert()}\r
 244      * @param Converter\r
 245      * @return string\r
 246      */\r
 247     function getId(&$c)\r
 248     {\r
 249         if ($this->_id) return trim($this->_id->Convert($c));\r
 250     }\r
 251     \r
 252     /**\r
 253      * Determine whether the docbook element has a title\r
 254      * @return boolean\r
 255      */\r
 256     function hasTitle()\r
 257     {\r
 258         return isset($this->_title);\r
 259     }\r
 260     \r
 261     /**\r
 262      * Retrieve Converter-specific formatting of the title of this element\r
 263      * @return string\r
 264      * @param Converter\r
 265      */\r
 266     function getTitle(&$c)\r
 267     {\r
 268         if ($this->name == 'refentry')\r
 269         {\r
 270             foreach($this->value as $tag)\r
 271             {\r
 272                 if (is_object($tag) && $tag->name == 'refnamediv')\r
 273                 {\r
 274                     return $tag->getTitle($c);\r
 275                 }\r
 276             }\r
 277         }\r
 278         if ($this->name == 'refnamediv')\r
 279         {\r
 280             foreach($this->value as $tag)\r
 281             {\r
 282                 if (is_object($tag) && is_a($tag, 'parserXMLDocBookTag') && $tag->name == 'refname')\r
 283                 {\r
 284                     $t = new parserStringWithInlineTags;\r
 285                     foreach($tag->value as $val) $t->add($val);\r
 286                     $this->_title = $t;\r
 287                 }\r
 288                 if (is_object($tag) && is_a($tag, 'parserXMLDocBookTag') && $tag->name == 'refpurpose')\r
 289                 {\r
 290                     $t = new parserStringWithInlineTags;\r
 291                     foreach($tag->value as $val) $t->add($val);\r
 292                     $this->_description = $t;\r
 293                 }\r
 294             }\r
 295         }\r
 296         if (isset($this->_title))\r
 297         return $this->_title->Convert($c);\r
 298         if (is_object($this->value[0]) && is_a($tag, 'parserXMLDocBookTag')) {\r
 299             return $this->value[0]->getTitle($c);\r
 300         }\r
 301         if (isset($this->value[1])) {\r
 302             if (is_object($this->value[1]) && is_a($tag, 'parserXMLDocBookTag')) {\r
 303                 return $this->value[1]->getTitle($c);\r
 304             }\r
 305         }\r
 306         return '';\r
 307     }\r
 308     \r
 309     /**\r
 310      * Retrieve the contents of a subsection\r
 311      *\r
 312      * This method uses the $_id members of nested docbook tags to retrieve\r
 313      * the section defined by $subsection\r
 314      * @param Converter\r
 315      * @param string converter-specific subsection\r
 316      */\r
 317     function getSubsection(&$c,$subsection)\r
 318     {\r
 319         if (!is_object($this->_id)) {\r
 320             return false;\r
 321         }\r
 322         $search = phpDocumentor_clone($this->_id);\r
 323         if (is_string($this->_id)) return false;\r
 324         if (phpDocumentor_get_class($search) != 'parseridinlinetag') return false;\r
 325         $search->id = $subsection;\r
 326         foreach($this->value as $el)\r
 327         {\r
 328             if (phpDocumentor_get_class($el) == 'parserxmldocbooktag')\r
 329             {\r
 330                 if ($el->getId($c) == $search->Convert($c))\r
 331                 {\r
 332                     return $el;\r
 333                 } elseif ($a = $el->getSubsection($c,$subsection))\r
 334                 {\r
 335                     return $a;\r
 336                 }\r
 337             }\r
 338         }\r
 339         return false;\r
 340     }\r
 341     \r
 342     /**\r
 343      * Add contents to this tag.\r
 344      *\r
 345      * There are four kinds of data in a DocBook tutorial:\r
 346      *  1. <b>tags</b> - normal tags like <refentry>\r
 347      *  2. <b>entities</b> - normal entities like &rdquo;\r
 348      *  3. <b><![CDATA[</b> - character data that should not be interpreted,\r
 349      *     like <programlisting> contents\r
 350      *  4. <b>text</b> - normal non-markup text\r
 351      *\r
 352      * All four kinds of data are added here\r
 353      * @param parserEntity|parserCData|parserXMLDocBookTag|string nested tag,\r
 354      *        entity, or text\r
 355      */\r
 356     function add($el)\r
 357     {\r
 358         if (is_string($el)) return parent::add($el);\r
 359         if (phpDocumentor_get_class($el) == 'parserxmldocbooktag')\r
 360         {\r
 361             if ($el->name == 'title')\r
 362             {\r
 363                 $this->setTitle($el);\r
 364             } else return parent::add($el);\r
 365         } else return parent::add($el);\r
 366     }\r
 367 }\r
 368 \r
 369 /**\r
 370  * a standard entity like &rdquo;\r
 371  *\r
 372  * This class is designed to represent all DocBook entities.\r
 373  * @since 1.2\r
 374  * @package phpDocumentor\r
 375  * @subpackage Tutorial\r
 376  */\r
 377 class parserEntity\r
 378 {\r
 379     /**\r
 380      * @param string entity name\r
 381      */\r
 382     function parserEntity($name)\r
 383     {\r
 384         $this->value = $name;\r
 385     }\r
 386     \r
 387     /**\r
 388      * @uses Converter::TranslateEntity() convert contents to text\r
 389      * @param Converter\r
 390      * @return string\r
 391      */\r
 392     function Convert(&$c, $postprocess = true)\r
 393     {\r
 394         if ($postprocess)\r
 395         return $c->TranslateEntity($this->value);\r
 396         else\r
 397         {\r
 398             $trans_tbl = get_html_translation_table (HTML_ENTITIES);\r
 399             $trans_tbl = array_flip ($trans_tbl);\r
 400             $ret = strtr ('&'.$this->value.';', $trans_tbl);\r
 401             return $ret;\r
 402         }\r
 403     }\r
 404 }\r
 405 ?>