File Source for XMLDocBookpeardoc2Converter.inc

<?php
/**
* Outputs documentation in XML DocBook format, in the version expected by
* pear.php.net's documentation team
*
* phpDocumentor :: automatic documentation generator
*
* PHP versions 4 and 5
*
* Copyright (c) 2002-2006 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
*
* @package Converters
* @subpackage XMLDocBook
* @author Greg Beaver <cellog@php.net>
* @copyright 2002-2006 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version CVS: $Id: XMLDocBookpeardoc2Converter.inc,v 1.8 2007/04/24 21:32:15 ashnazg Exp $
* @filesource
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @since 1.2
*/
/**
* XML DocBook converter.
* This Converter takes output from the {@link Parser} and converts it to DocBook
* output for PEAR documentation.
*
* This Converter differs from the parent DocBook Converter in that it does not
* recognize the possibility of procedural pages or of functions! All functions
* must be defined as static methods for namespace purposes. In addition, all
* constants and global variables for a package are grouped together as per
* peardoc2 requirements. Include statements are not documented. If you want
* to document a normal project, don't use the peardoc2 converter, use the
* DocBook converter.
* @package Converters
* @subpackage XMLDocBook
* @author Greg Beaver <cellog@php.net>
* @since 1.2
* @version $Id: XMLDocBookpeardoc2Converter.inc,v 1.8 2007/04/24 21:32:15 ashnazg Exp $
*/
class XMLDocBookpeardoc2Converter extends Converter
{
/**
* This converter knows about the new root tree processing
* In order to fix PEAR Bug #6389
* @var boolean
*/
var $processSpecialRoots = true;
/**
* XMLDocBookConverter wants elements sorted by type as well as alphabetically
* @see Converter::$sort_page_contents_by_type
* @var boolean
*/
var $sort_page_contents_by_type = true;
/** @var string */
var $outputformat = 'XML';
/** @var string */
var $name = 'DocBook/peardoc2';
/**
* indexes of elements by package that need to be generated
* @var array
*/
var $leftindex = array('classes' => true, 'pages' => false, 'functions' => false, 'defines' => true, 'globals' => true);
/**
* whether a @see is going to be in the {@link $base_dir}, or in a package/subpackage subdirectory of $base_dir
* @var boolean
*/
var $local = true;
/**
* name of current page being converted
* @var string
*/
var $page;
/**
* path of current page being converted
* @var string
*/
var $path;
/**
* name of current class being converted
* @var string
*/
var $class;
/**
* template for the procedural page currently being processed
* @var Template
*/
var $page_data;
/**
* output directory for the current procedural page being processed
* @var string
*/
var $page_dir;
/**
* Constants, used for constants.tpl
* @var array
*/
var $_peardoc2_constants = false;
/**
* Global Variables, used for globals.tpl
* @var array
*/
var $_peardoc2_globals = false;
/**
* target directory passed on the command-line.
* {@link $targetDir} is malleable, always adding package/ and package/subpackage/ subdirectories onto it.
* @var string
*/
var $base_dir;
/**
* output directory for the current class being processed
* @var string
*/
var $class_dir;
/**
* template for the class currently being processed
* @var Template
*/
var $class_data;
/**
* array of converted package page names.
* Used to link to the package page in the left index
* @var array Format: array(package => 1)
*/
var $package_pages = array();
/**
* Contents of the packagename.xml file are stored in this template variable
* @var Smarty
*/
var $packagexml;
/**
* controls formatting of parser informative output
*
* Converter prints:
* "Converting /path/to/file.php... Procedural Page Elements... Classes..."
* Since HTMLdefaultConverter outputs files while converting, it needs to send a \n to start a new line. However, if there
* is more than one class, output is messy, with multiple \n's just between class file output. This variable prevents that
* and is purely cosmetic
* @var boolean
*/
var $juststarted = false;
/**
* contains all of the template procedural page element loop data needed for the current template
* @var array
*/
var $current;
/**
* contains all of the template class element loop data needed for the current template
* @var array
*/
var $currentclass;
/**
* Pass elements by package, simplifies generation of package.xml/category.xml
*/
var $sort_absolutely_everything = true;
/**
* template options. Currently only 1 recognized option usepear
*
* usepear tells the getLink() function to return a package link to PEAR and PEAR_ERROR if possible, and to link directly
* to the fully-delimited link package#class.method or package#file.method in PEAR style, if possible, even if the
* package is not parsed. This will allow parsing of separate PEAR packages without parsing the entire thing at once!
* @var array
*/
var $template_options = array('usepear' => false);
var $function_data = array();
var $method_data = array();
var $_write_constants_xml = array();
var $_write_globals_xml = array();
var $sourceloc = '';
/**
* peardoc2 Category
* @var string
*/
var $category;
/**
* Used to re-format output so that it's easy for translators to handle
*
* @var XML_Beautifier|false
* @access private
*/
var $_beautifier = false;
/**
* sets {@link $base_dir} to $targetDir
* @see Converter()
*/
function XMLDocBookpeardoc2Converter(&$allp, &$packp, &$classes, &$procpages, $po, $pp, $qm, $targetDir, $templateDir, $title)
{
if (!class_exists('XML_Beautifier')) {
@include_once 'XML/Beautifier.php';
}
Converter::Converter($allp, $packp, $classes, $procpages,$po, $pp, $qm, $targetDir, $templateDir, $title);
if (class_exists('XML_Beautifier')) {
require_once 'phpDocumentor/Converters/XML/DocBook/peardoc2/Beautifier.php';
$this->_beautifier = new phpDocumentor_peardoc2_XML_Beautifier;
$this->_beautifier->setOption('indent', ' ');
}
$this->base_dir = $targetDir;
}
/**
* do that stuff in $template_options
*/
function &getLink($expr, $package = false, $packages = false)
{
return Converter::getLink($expr, $package, $packages);
}
function unmangle($s,$sourcecode)
{
return '<programlisting role="php"><![CDATA[
'.$sourcecode.']]></programlisting>';
}
/**
* Writes a file to target dir, beautify any .xml files first
* @param string filename
* @param string file contents
* @param boolean true if the data is binary and not text
*/
function writeFile($file,$data,$binary = false)
{
if ($this->_beautifier && substr($file, -4) == '.xml') {
$ret = $this->_beautifier->formatString($data);
if (PEAR::isError($ret)) {
addWarning(PDERROR_BEAUTIFYING_FAILED, $ret->getMessage());
$ret = $data;
}
$data = $ret;
}
return parent::writeFile($file, $data, $binary);
}
/**
* Used to convert the {@}example} inline tag in a docblock.
*
* By default, this just wraps ProgramExample
* @see XMLDocBookpeardoc2Converter::exampleProgramExample
* @param string
* @param boolean true if this is to highlight a tutorial <programlisting>
* @return string
*/
function exampleProgramExample($example, $tutorial = false, $inlinesourceparse = null/*false*/,
$class = null/*false*/, $linenum = null/*false*/, $filesourcepath = null/*false*/)
{
return '<example><title>Example</title><programlisting role="php"><![CDATA[' .
$example . ']]></programlisting></example>';
$this->ProgramExample($example, $tutorial, $inlinesourceparse, $class, $linenum, $filesourcepath)
. '</example>';
}
function writeExample($title, $path, $source)
{
$this->_save_example = array($title, $source);
}
function getExampleLink($unused, $title)
{
$source = $this->_save_example[1];
return '<para><example><title>' . $title . '</title>' . $source . '</example></para>';
}
function type_adjust($typename)
{
if (isset($this->template_options['typechanging'][trim($typename)]))
return $this->template_options['typechanging'][trim($typename)];
$a = $this->getLink($typename);
if (is_object($a))
{
if (phpDocumentor_get_class($a) == 'classlink')
return '<classname>'.$typename.'</classname>';
if (phpDocumentor_get_class($a) == 'functionlink' || phpDocumentor_get_class($a) == 'methodlink')
return '<function>'.$typename.'</function>';
if (phpDocumentor_get_class($a) == 'definelink')
return '<constant>'.$typename.'</constant>';
if (phpDocumentor_get_class($a) == 'varlink')
return '<varname>'.$typename.'</varname>';
}
return $typename;
}
/**
* Writes out the template file of {@link $class_data} and unsets the template to save memory
* @see registerCurrentClass()
* @see parent::endClass()
* @todo move class summary into an array to be written out at the end
* of parsing each package
*/
function endClass()
{
$a = '../';
if (!empty($this->subpackage)) $a .= '../';
if ($this->juststarted)
{
$this->juststarted = false;
phpDocumentor_out("\n");
flush();
}
foreach($this->method_data as $func)
{
$func[0]->assign("phpdocversion",PHPDOCUMENTOR_VER);
$func[0]->assign("phpdocwebsite",PHPDOCUMENTOR_WEBSITE);
$this->setTargetDir($this->base_dir . PATH_DELIMITER . strtolower($this->category) . PATH_DELIMITER . strtolower($this->class_dir . PATH_DELIMITER . str_replace(array('_','.'),array('-','--'),$this->class)));
$this->writefile(strtolower($func[1] ). '.xml','\n" . $func[0]->fetch('method.tpl'));
}
// code below is in packagename.xml handling, see Output()
/* $this->setTargetDir($this->base_dir . PATH_DELIMITER . strtolower($this->category) . PATH_DELIMITER . strtolower($this->class_dir));
$this->writefile(str_replace(array('_','.'),array('-','--'),strtolower($this->class)) . '.xml',$this->class_data->fetch('class.tpl'));*/
unset($this->class_data);
}
function addSummaryToPackageXml($template_output)
{
$this->packagexml->append('ids',$template_output);
}
/**
* @param parserClass|false$element is false if this is the end of all conversion
*/
function flushPackageXml($element)
{
if (isset($this->packagexml))
{
if (!$element || $element->docblock->package != $this->package) // finished with package
{
if (isset($this->_write_constants_xml[$this->category][$this->package]) &&
$this->_write_constants_xml[$this->category][$this->package])
{
$this->packagexml->append('ids',
'&package.' .
strtolower($this->category.'.' .
str_replace(array('_','.'),array('-','--'),$this->package).'.constants;'));
$this->_write_constants_xml[$this->category][$this->package] = false;
}
if (isset($this->_write_globals_xml[$this->category][$this->package]) &&
$this->_write_globals_xml[$this->category][$this->package])
{
$this->packagexml->append('ids',
'&package.'.strtolower($this->category.'.' .
str_replace(array('_','.'),array('-','--'),$this->package).'.globals;'));
$this->_write_globals_xml[$this->category][$this->package] = false;
}
$this->setTargetDir($this->base_dir . PATH_DELIMITER . strtolower($this->category));
$this->writefile(str_replace('_','-',strtolower($this->package)).'.xml',
'\n" . $this->packagexml->fetch('package.tpl'));
$this->packagexml->clear_all_assign();
if ($element) {
$this->packagexml->assign('package',$element->docblock->package);
$this->packagexml->assign('ids',array());
$this->packagexml->assign('id',$this->getId($element, true));
}
}
} else
{
$this->packagexml = $this->newSmarty();
$this->packagexml->assign('package',$element->docblock->package);
$this->packagexml->assign('ids',array());
$this->packagexml->assign('id',$this->getId($element, true));
}
}
/**
* @param string
* @param string
* @return string <ulink url="'.$link.'">'.$text.'</ulink>
*/
function returnLink($link,$text)
{
return '<ulink url="'.$link.'">'.$text.'</ulink>';
}
function makeLeft()
{
}
/**
* Does nothing
*/
function formatPkgIndex()
{
}
/**
* Does nothing
*/
function formatIndex()
{
}
/**
* Does nothing
*/
function writeNewPPage($key)
{
}
/**
* Does nothing
*/
function writeSource()
{
}
/**
* Creates package/lang/categoryname/packagename.xml for each package
*/
function formatLeftIndex()
{
$this->makeLeft();
}
/**
* This function takes an {@link abstractLink} descendant and returns an html link
*
* @param abstractLink a descendant of abstractlink should be passed, and never text
* @param string text to display in the link
* @param boolean this parameter is not used, and is deprecated
* @param boolean determines whether the returned text is enclosed in an <link> tag
*/
function returnSee(&$element, $eltext = false, $local = true, $with_a = true)
{
if (!$element) return false;
if (!$eltext)
{
$eltext = '';
switch($element->type)
{
case 'tutorial' :
$eltext = $element->title;
break;
case 'class' :
$eltext = '<classname>'.$element->name.'</classname>';
break;
case 'method' :
$eltext .= '<function>';
case 'var' :
if ($element->type == 'var') $eltext .= '<varname>';
$eltext .= $element->class.'::';
case 'page' :
case 'define' :
if ($element->type == 'define')
$eltext .= '<constant>';
case 'function' :
if ($element->type == 'function')
$eltext .= '<function>';
case 'global' :
default :
$eltext .= $element->name;
if ($element->type == 'function' || $element->type == 'method') $eltext .= '</function>';
if ($element->type == 'var') $eltext .= '</varname>';
if ($element->type == 'define') $eltext .= '</constant>';
break;
}
} elseif (!is_object($element)) {
return false;
} elseif ($element->type == 'method')
{
$eltext = str_replace($element->name . '()', $element->name, $eltext);
}
if ($element->type == 'page' || $element->type == 'function' || $element->type == 'var')
{ // we ignore all procedural pages, instead, constant, function and
&n

	Converters XMLDocBook

[ class tree: Converters ] [ index: Converters ] [ all elements ]

Source for file XMLDocBookpeardoc2Converter.inc