Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

executable file 540 lines (519 sloc) 16.093 kb
<?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$
* @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: @VER@
* @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: @VER@
* @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);
}
// if current element is a graphic make sure the linked file is copied to the
// given location
if ($this->name == "graphic")
{
$val = $this->attributes['fileref'];
$src = substr($c->curpath, 0, (strrpos($c->curpath, $c->package) - strlen($c->curpath)) );
$sourceDir = $src.$c->package.'/';
$targetDir = $c->base_dir.'/'.$c->package.'/';
$targetDir.= (!empty($c->subpackage)) ? $c->subpackage.'/' : '';
$targetDir .= 'figures/';
$filename = substr($val, strrpos($val, '/') + 1);
if (file_exists($sourceDir.$val))
{
if (!file_exists($targetDir))
{
mkdir($targetDir,0775, true);
}
if (copy($sourceDir.$val, $targetDir.$filename))
{
$this->attributes['fileref'] = './figures/'.$filename;
}
}
}
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 &rdquo;
* 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 &rdquo;
*
* 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: @VER@
* @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;
}
}
}
?>
Jump to Line
Something went wrong with that request. Please try again.