Viewing file:  PackagePageElements.inc (14.86 KB) -rw-rw-rw-
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
<?php
/**
* Data structures used in parsing XML DocBook-based tutorials
*
* Conversion of DocBook-based tutorials is performed using special
* {@link Converter} class methods. By default, these methods simply retrieve
* simple rules for replacement of tags and slight re-ordering from the
* options.ini file present for every template.
*
* In future versions, there may be utilization of xslt or other more powerful
* protocols. However, for most situations, the power of these classes will
* be more than sufficient to handle very complex documentation.
*
* Note that an entire tutorial is contained in a single parserXMLDocBookTag,
* matching the document model for DocBook. The top-level tag, <refentry>,
* contains every other tag and all text.
*
* phpDocumentor :: automatic documentation generator
*
* PHP versions 4 and 5
*
* Copyright (c) 2002-2008 Gregory Beaver
*
* LICENSE:
*
* This library is free software; you can redistribute it
* and/or modify it under the terms of the GNU Lesser General
* Public License as published by the Free Software Foundation;
* either version 2.1 of the License, or (at your option) any
* later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* @category ToolsAndUtilities
* @package phpDocumentor
* @subpackage Tutorial
* @author Gregory Beaver <cellog@php.net>
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version CVS: $Id: PackagePageElements.inc 253643 2008-02-24 04:27:54Z ashnazg $
* @tutorial tutorials.pkg
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @since 1.2.0
* @todo CS cleanup - change package to PhpDocumentor
*/
/**
* Represents <![CDATA[ ]]> sections.
*
* These sections are interpreted as plain text
*
* @category ToolsAndUtilities
* @package phpDocumentor
* @subpackage Tutorial
* @author Gregory Beaver <cellog@php.net>
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: 1.4.4
* @tutorial tutorials.pkg
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
*/
class parserCData extends parserStringWithInlineTags
{
/**
* calls the output conversion
*
* @param Converter &$c the output converter
* @param bool $postprocess if postprocessing is needed
*
* @return string
* @uses Converter::getCData() convert contents to text
* @todo CS cleanup - rename to convert for camelCase rule
*/
function Convert(&$c, $postprocess = true)
{
$val = $this->value;
if ($postprocess) {
foreach ($this->value as $key => $value) {
if (is_string($value)) {
$this->value[$key] = $c->getCData($value);
}
}
}
$this->cache = false;
$x = parent::Convert($c, false);
$this->value = $val;
return $x;
}
}
/**
* a standard XML DocBook Tag
*
* This class is designed to represent all DocBook tags. It is intelligent
* enough to understand the <title> tag, and also the <refname> tag for
* as title for <refentry>
*
* @category ToolsAndUtilities
* @package phpDocumentor
* @subpackage Tutorial
* @author Gregory Beaver <cellog@php.net>
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: 1.4.4
* @tutorial tutorials.pkg
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @since 1.2
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @todo CS cleanup - rename to parserXmlDocBookTag for camelCase rule
*/
class parserXMLDocBookTag extends parserStringWithInlineTags
{
/**
* Attributes from the XML tag
*
* Format: array(attrname => attrvalue, attrname => attrvalue,...)
* @var array
*/
var $attributes = array();
/**
* Name of the tag
* @var string
*/
var $name;
/**#@+
* @access private
*/
/**
* @var parserCData
*/
var $_cdata;
/**
* @var parserTag
*/
var $_title;
/**
* @var parserIdLineTag
*/
var $_id;
/**
* Set to <refpurpose> in <refsynopsisdiv>
* @var parserTag
*/
var $_description;
/**#@-*/
/**
* sets up the tag
*
* @param string $name tag name
*
* @todo CS cleanup - rename to parserXmlDocBookTag for camelCase rule
*/
function parserXMLDocBookTag($name)
{
$this->name = $name;
}
/**
* calls the output conversion
*
* @param Converter &$c the output converter
* @param bool $postprocess if postprocessing is needed
*
* @return string
* @uses Converter::TranslateTag() Calls this to enclose the contents of the
* DocBook tag based on the values in template options.ini file
*/
function Convert(&$c, $postprocess = true)
{
$value = parent::Convert($c, $postprocess);
$simvalue = parent::Convert($c, false);
foreach ($this->attributes as $a => $v) {
$this->attributes[$a] = (is_string($v) ? $v :
$v->Convert($c, $postprocess));
}
if (isset($this->_title)) {
list($this->attributes,$value) = $c->ConvertTitle($this->name,
$this->attributes, $this->_title->Convert($c, $postprocess), $value);
}
return $c->TranslateTag($this->name, $this->attributes, $value, $simvalue);
}
/**
* Begin a new CData section
*
* @return void
* @see addCData()
*/
function startCData()
{
$this->_cdata = new parserCData;
}
/**
* Adds {@link $_cdata} to {@link $value}
*
* @return void
*/
function endCData()
{
$this->value[] = $this->_cdata;
unset($this->_cdata);
}
/**
* Retrieve either the table of contents index,
* or the location that the TOC will go
*
* @param false|integer $state either an index of the {@}toc} tag in $this->value
* or false, if the next index value of $this->value
* is needed
*
* @return int
* @see setTOC()
*/
function getTOC($state = false)
{
if ($state !== false) {
return $this->value[$state];
}
return count($this->value);
}
/**
* sets the TOC value
*
* @param integer $state index of the TOC in $this->value
* @param parserTocInlineTag $val tag value
*
* @return void
*/
function setTOC($state, $val)
{
$this->value[$state] = $val;
}
/**
* add a word to CData
*
* @param string $word word to add
*
* @return void
*/
function addCData($word)
{
$this->_cdata->add($word);
}
/**
* Add an xml tag attribute name="value" pair
*
* if the attribute is id, value must be a {@link parserIdInlineTag}
*
* @param string $name attribute name
* @param string|parserIdInlineTag $value value of attribute
*
* @return void
*/
function addAttribute($name, $value)
{
$this->attributes[$name] = $value;
if ($name == 'id') {
// fix 1153593
if (is_string($value)) {
addWarning(PDERROR_ID_MUST_BE_INLINE, $this->name, $value,
$this->name, $value);
} else {
$this->setId($value);
}
}
}
/**
* Set the title of a DocBook tag section.
*
* For most DocBook tags, the title is represented with a <title></title>
* tag pair. The <refentry> top-level tag is a little different. Instead
* of using <title></title>, phpDocumentor uses the contents of the
* <refname> tag in the <refnamediv> tag
*
* @param parserXMLDocBookTag $title the title element
*
* @return void
*/
function setTitle($title)
{
$this->_title = $title;
}
/**
* If the id attribute is present, this method will set its id
*
* @param parserIdInlineTag $id the id value
*
* @return void
*/
function setId($id)
{
$this->_id = $id;
}
/**
* Return converter-specific formatting of ID.
*
* Passes $c to {@link parserIdInlineTag::Convert()}
*
* @param Converter &$c the output converter
*
* @return string
*/
function getId(&$c)
{
if ($this->_id) {
return trim($this->_id->Convert($c));
}
}
/**
* Determine whether the docbook element has a title
*
* @return boolean
*/
function hasTitle()
{
return isset($this->_title);
}
/**
* Retrieve Converter-specific formatting of the title of this element
*
* @param Converter &$c the output converter
*
* @return string
*/
function getTitle(&$c)
{
if ($this->name == 'refentry') {
foreach ($this->value as $tag) {
if (is_object($tag) && $tag->name == 'refnamediv') {
return $tag->getTitle($c);
}
}
}
if ($this->name == 'refnamediv') {
foreach ($this->value as $tag) {
if (is_object($tag) && is_a($tag, 'parserXMLDocBookTag')
&& $tag->name == 'refname') {
$t = new parserStringWithInlineTags;
foreach ($tag->value as $val) {
$t->add($val);
}
$this->_title = $t;
}
if (is_object($tag) && is_a($tag, 'parserXMLDocBookTag')
&& $tag->name == 'refpurpose') {
$t = new parserStringWithInlineTags;
foreach ($tag->value as $val) {
$t->add($val);
}
$this->_description = $t;
}
}
}
if (isset($this->_title)) {
return $this->_title->Convert($c);
}
if (is_object($this->value[0]) && is_a($tag, 'parserXMLDocBookTag')) {
return $this->value[0]->getTitle($c);
}
if (isset($this->value[1])) {
if (is_object($this->value[1]) && is_a($tag, 'parserXMLDocBookTag')) {
return $this->value[1]->getTitle($c);
}
}
return '';
}
/**
* Retrieve the contents of a subsection
*
* This method uses the $_id members of nested docbook tags to retrieve
* the section defined by $subsection
*
* @param Converter &$c the output converter
* @param string $subsection converter-specific subsection
*
* @return bool|string
*/
function getSubsection(&$c, $subsection)
{
if (!is_object($this->_id)) {
return false;
}
$search = phpDocumentor_clone($this->_id);
if (is_string($this->_id)) {
return false;
}
if (phpDocumentor_get_class($search) != 'parseridinlinetag') {
return false;
}
$search->id = $subsection;
foreach ($this->value as $el) {
if (phpDocumentor_get_class($el) == 'parserxmldocbooktag') {
if ($el->getId($c) == $search->Convert($c)) {
return $el;
} elseif ($a = $el->getSubsection($c, $subsection)) {
return $a;
}
}
}
return false;
}
/**
* Add contents to this tag.
*
* There are four kinds of data in a DocBook tutorial:
* 1. <b>tags</b> - normal tags like <refentry>
* 2. <b>entities</b> - normal entities like ”
* 3. <b><![CDATA[</b> - character data that should not be interpreted,
* like <programlisting> contents
* 4. <b>text</b> - normal non-markup text
*
* All four kinds of data are added here
*
* @param parserEntity|parserCData|parserXMLDocBookTag|string $el nested tag,
* entity, or text
*
* @return mixed
*/
function add($el)
{
if (is_string($el)) {
return parent::add($el);
}
if (phpDocumentor_get_class($el) == 'parserxmldocbooktag') {
if ($el->name == 'title') {
$this->setTitle($el);
} else {
return parent::add($el);
}
} else {
return parent::add($el);
}
}
}
/**
* a standard entity like ”
*
* This class is designed to represent all DocBook entities.
*
* @category ToolsAndUtilities
* @package phpDocumentor
* @subpackage Tutorial
* @author Gregory Beaver <cellog@php.net>
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: 1.4.4
* @tutorial tutorials.pkg
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @since 1.2
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
*/
class parserEntity
{
/**
* sets up the entity
*
* @param string $name entity name
*/
function parserEntity($name)
{
$this->value = $name;
}
/**
* calls the output conversion
*
* @param Converter &$c the output converter
* @param bool $postprocess if postprocessing is needed
*
* @return string
* @uses Converter::TranslateEntity() convert contents to text
* @todo CS cleanup - rename to convert for camelCase rule
*/
function Convert(&$c, $postprocess = true)
{
if ($postprocess) {
return $c->TranslateEntity($this->value);
} else {
$trans_tbl = get_html_translation_table(HTML_ENTITIES);
$trans_tbl = array_flip($trans_tbl);
$ret = strtr('&'.$this->value.';', $trans_tbl);
return $ret;
}
}
}
?>
|