File Source for Converter.inc

<?php
/**
* Base class for all Converters
*
* phpDocumentor :: automatic documentation generator
*
* PHP versions 4 and 5
*
* Copyright (c) 2001-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
* @author Greg Beaver <cellog@php.net>
* @copyright 2001-2006 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version CVS: $Id: Converter.inc,v 1.39 2007/12/19 02:16:49 ashnazg Exp $
* @filesource
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @see parserDocBlock, parserInclude, parserPage, parserClass
* @see parserDefine, parserFunction, parserMethod, parserVar
* @since 1.0rc1
*/
/**
* Smarty template files
*/
include_once("phpDocumentor/Smarty-2.6.0/libs/Smarty.class.php");
/**
* Base class for all output converters.
*
* The Converter marks the final stage in phpDocumentor. phpDocumentor works
* in this order:
*
* <pre>Parsing => Intermediate Parsing organization => Conversion to output</pre>
*
* A Converter takes output from the {@link phpDocumentor_IntermediateParser} and
* converts it to output. With version 1.2, phpDocumentor includes a variety
* of output converters:
* <ul>
* <li>{@link HTMLframesConverter}</li>
* <li>{@link HTMLSmartyConverter}</li>
* <li>{@link PDFdefaultConverter}</li>
* <li>{@link CHMdefaultConverter}</li>
* <li>{@link CSVdia2codeConverter}</li>
* <li>{@link XMLDocBookConverter}</li>
* </ul>
* {@internal
* The converter takes output directly from {@link phpDocumentor_IntermediateParser}
* and using {@link walk()} or {@link walk_everything} (depending on the value of
* {@link $sort_absolutely_everything}) it "walks" over an array of phpDocumentor elements.}}}
*
* @package Converters
* @abstract
* @author Greg Beaver <cellog@php.net>
* @since 1.0rc1
* @version $Id: Converter.inc,v 1.39 2007/12/19 02:16:49 ashnazg Exp $
*/
class Converter
{
/**
* This converter knows about the new root tree processing
* In order to fix PEAR Bug #6389
* @var boolean
*/
var $processSpecialRoots = false;
/**
* output format of this converter
*
* in Child converters, this will match the first part of the -o command-line
* as in -o HTML:frames:default "HTML"
* @tutorial phpDocumentor.howto.pkg#using.command-line.output
* @var string
*/
var $outputformat = 'Generic';
/**
* package name currently being converted
* @var string
*/
var $package = 'default';
/**
* subpackage name currently being converted
* @var string
*/
var $subpackage = '';
/**
* set to a classname if currently parsing a class, false if not
* @var string|false
*/
var $class = false;
/**#@+
* @access private
*/
/**
* the workhorse of linking.
*
* This array is an array of link objects of format:
* [package][subpackage][eltype][elname] = descendant of {@link abstractLink}
* eltype can be page|function|define|class|method|var
* if eltype is method or var, the array format is:
* [package][subpackage][eltype][class][elname]
* @var array
* @see functionLink, pageLink, classLink, defineLink, methodLink, varLink, globalLink
*/
var $links = array();
/**
* the workhorse of linking, with allowance for support of multiple
* elements in different files.
*
* This array is an array of link objects of format:
* [package][subpackage][eltype][file][elname] = descendant of {@link abstractLink}
* eltype can be function|define|class|method|var
* if eltype is method or var, the array format is:
* [package][subpackage][eltype][file][class][elname]
* @var array
* @see functionLink, pageLink, classLink, defineLink, methodLink, varLink, globalLink
*/
var $linkswithfile = array();
/**#@-*/
/**
* set to value of -po commandline
* @tutorial phpDocumentor.howto.pkg#using.command-line.packageoutput
* @var mixed
*/
var $package_output;
/**
* name of current page being converted
* @var string
*/
var $page;
/**
* path of current page being converted
* @var string
*/
var $path;
/**
* template for the procedural page currently being processed
* @var Smarty
*/
var $page_data;
/**
* template for the class currently being processed
* @var Smarty
*/
var $class_data;
/**
* current procedural page being processed
* @var parserPage
*/
var $curpage;
/**
* alphabetical index of all elements sorted by package, subpackage, page,
* and class.
* @var array Format: array(package => array(subpackage => array('page'|'class' => array(path|classname => array(element, element,...)))))
* @uses $sort_absolutely_everything if true, then $package_elements is used,
* otherwise, the {@link ParserData::$classelements} and
* {@link ParserData::$pageelements} variables are used
*/
var $package_elements = array();
/**
* alphabetical index of all elements
*
* @var array Format: array(first letter of element name => array({@link parserElement} or {@link parserPage},...))
* @see formatIndex(), HTMLframesConverter::formatIndex()
*/
var $elements = array();
/**
* alphabetized index of procedural pages by package
*
* @see $leftindex
* @var array Format: array(package => array(subpackage => array({@link pageLink} 1,{@link pageLink} 2,...)
*/
var $page_elements = array();
/**
* alphabetized index of defines by package
*
* @see $leftindex
* @var array Format: array(package => array(subpackage => array({@link defineLink} 1,{@link defineLink} 2,...)
*/
var $define_elements = array();
/**
* alphabetized index of classes by package
*
* @see $leftindex
* @var array Format: array(package => array(subpackage => array({@link classLink} 1,{@link classLink} 2,...)
*/
var $class_elements = array();
/**
* alphabetized index of global variables by package
*
* @see $leftindex
* @var array Format: array(package => array(subpackage => array({@link globalLink} 1,{@link globalLink} 2,...)
*/
var $global_elements = array();
/**
* alphabetized index of functions by package
*
* @see $leftindex
* @var array Format: array(package => array(subpackage => array({@link functionLink} 1,{@link functionLink} 2,...)
*/
var $function_elements = array();
/**
* alphabetical index of all elements, indexed by package/subpackage
*
* @var array Format: array(first letter of element name => array({@link parserElement} or {@link parserPage},...))
* @see formatPkgIndex(), HTMLframesConverter::formatPkgIndex()
*/
var $pkg_elements = array();
/**
* alphabetical index of all elements on a page by package/subpackage
*
* The page itself has a link under ###main
* @var array Format: array(package => array(subpackage => array(path => array({@link abstractLink} descendant 1, ...)))
* @see formatLeftIndex()
*/
var $page_contents = array();
/**
* This determines whether the {@link $page_contents} array should be sorted by element type as well as alphabetically by name
* @see sortPageContentsByElementType()
* @var boolean
*/
var $sort_page_contents_by_type = false;
/**
* This is used if the content must be passed in the order it should be read, i.e. by package, procedural then classes
*
* This fixes bug 637921, and is used by {@link PDFdefaultConverter}
*/
var $sort_absolutely_everything = false;
/**
* alphabetical index of all methods and vars in a class by package/subpackage
*
* The class itself has a link under ###main
* @var array
* Format:<pre>
* array(package =>
* array(subpackage =>
* array(path =>
* array(class =>
* array({@link abstractLink} descendant 1, ...
* )
* )
* )
* )</pre>
* @see formatLeftIndex()
*/
var $class_contents = array();
/**
* controls processing of elements marked private with @access private
*
* defaults to false. Set with command-line --parseprivate or -pp
* @var bool
*/
var $parseprivate;
/**
* controls display of progress information while parsing.
*
* defaults to false. Set to true for cron jobs or other situations where no visual output is necessary
* @var bool
*/
var $quietmode;
/**
* directory that output is sent to. -t command-line sets this.
* @tutorial phpDocumentor.howto.pkg#using.command-line.target
*/
var $targetDir = '';
/**
* Directory that the template is in, relative to phpDocumentor root directory
* @var string
*/
var $templateDir = '';
/**
* Directory that the smarty templates are in
* @var string
*/
var $smarty_dir = '';
/**
* Name of the template, from last part of -o
* @tutorial phpDocumentor.howto.pkg#using.command-line.output
* @var string
*/
var $templateName = '';
/**
* full path of the current file being converted
*/
var $curfile;
/**
* All class information, organized by path, and by package
* @var Classes
*/
var $classes;
/**
* Flag used to help converters determine whether to do special source highlighting
* @var boolean
*/
var $highlightingSource = false;
/**
* Hierarchy of packages
*
* Every package that contains classes may have parent or child classes
* in other packages. In other words, this code is legal:
*
* <code>
* /**
* * @package one
* * /
* class one {}
*
* /**
* * @package two
* * /
* class two extends one {}
* </code>
*
* In this case, package one is a parent of package two
* @var array
* @see phpDocumentor_IntermediateParser::$package_parents
*/
var $package_parents;
/**
* Packages associated with categories
*
* Used by the XML:DocBook/peardoc2 converter, and available to others, to
* group many packages into categories
* @see phpDocumentor_IntermediateParser::$packagecategories
* @var array
*/
var $packagecategories;
/**
* All packages encountered in parsing
* @var array
* @see phpDocumentor_IntermediateParser::$all_packages
*/
var $all_packages;
/**
* A list of files that have had source code generated
* @var array
*/
var $sourcePaths = array();
/**
* Controls which of the one-element-only indexes are generated.
*
* Generation of these indexes for large packages is time-consuming. This is an optimization feature. An
* example of how to use this is in {@link HTMLframesConverter::$leftindex}, and in {@link HTMLframesConverter::formatLeftIndex()}.
* These indexes are intended for use as navigational aids through documentation, but can be used for anything by converters.
* @see $class_elements, $page_elements, $function_elements, $define_elements, $global_elements
* @see formatLeftIndex()
* @var array
*/
var $leftindex = array('classes' => true, 'pages' => true, 'functions' => true, 'defines' => true, 'globals' => true);
/** @access private */
var $killclass = false;
/**
* @var string
* @see phpDocumentor_IntermediateParser::$title
*/
var $title = 'Generated Documentation';
/**
* Options for each template, parsed from the options.ini file in the template base directory
* @tutorial phpDocumentor/tutorials.pkg#conversion.ppage
* @var array
*/
var $template_options;
/**
* Tutorials and Extended Documentation parsed from a tutorials/package[/subpackage] directory
* @tutorial tutorials.pkg
* @access private
*/
var $tutorials = array();
/**
* tree-format structure of tutorials and their child tutorials, if any
* @var array
* @access private
*/
var $tutorial_tree = false;
/**
* list of tutorials that have already been processed. Used by @link _setupTutorialTree()
* @var array
* @access private
*/
var $processed_tutorials;
/**
* List of all @todo tags and a link to the element with the @todo
*
* Format: array(package => array(link to element, array(todo {@link parserTag},...)),...)
* @tutorial tags.todo.pkg
* @var array
*/
var $todoList = array();
/**
* Directory where compiled templates go - will be deleted on exit
*
* @var string
* @access private
*/
var $_compiledDir = array();
/**
* Initialize Converter data structures
* @param array {@link $all_packages} value
* @param array {@link $package_parents} value
* @param Classes {@link $classes} value
* @param ProceduralPages {@link $proceduralpages} value
* @param array {@link $package_output} value
* @param boolean {@link $parseprivate} value
* @param boolean {@link $quietmode} value
* @param string {@link $targetDir} value
* @param string {@link $templateDir} value
* @param string (@link $title} value
*/
function Converter(&$allp, &$packp, &$classes, &$procpages, $po, $pp, $qm, $targetDir, $template, $title)
{
$this->all_packages = $allp;
$this->package_parents = $packp;
$this->package = $GLOBALS['phpDocumentor_DefaultPackageName'];
$this->proceduralpages = &$procpages;
$this->package_output = $po;
if (is_array($po))
{
$a = $po[0];
$this->all_packages = array_flip($po);
$this->all_packages[$a] = 1;
}
$this->parseprivate = $pp;
$this->quietmode = $qm;
$this->classes = &$classes;
$this->roots = $classes->getRoots($this->processSpecialRoots);
$this->title = $title;
$this->setTemplateDir($template);
$this->setTargetdir($targetDir);
}
/**
* Called by IntermediateParser after creation
* @access private
*/
function setTutorials($tutorials)
{
$this->tutorials = $tutorials;
}
/**
* @param pkg|cls|procthe tutorial type to search for
* @param tutorial name
* @param string package name
* @param string subpackage name, if any
* @return false|parserTutorialif the tutorial exists, return it
*/
function hasTutorial($type, $name, $package, $subpackage = '')
{
if (isset($this->tutorials[$package][$subpackage][$type][$name . '.' . $type]))
return $this->tutorials[$package][$subpackage][$type][$name . '.' . $type];
return false;
}
/**
* Called by {@link walk()} while converting, when the last class element
* has been parsed.
*
* A Converter can use this method in any way it pleases. HTMLframesConverter
* uses it to complete the template for the class and to output its
* documentation
* @see HTMLframesConverter::endClass()
* @abstract
*/
function endClass()
{
}
/**
* Called by {@link walk()} while converting, when the last procedural page
* element has been parsed.
*
* A Converter can use this method in any way it pleases. HTMLframesConverter
* uses it to complete the template for the procedural page and to output its
* documentation
* @see HTMLframesConverter::endClass()
* @abstract
*/
function endPage()
{
}
/**
* Called by {@link walk()} while converting.
*
* This method is intended to be the place that {@link $pkg_elements} is
* formatted for output.
* @see HTMLframesConverter::formatPkgIndex()
* @abstract
*/
function formatPkgIndex()
{
}
/**
* Called by {@link walk()} while converting.
*
* This method is intended to be the place that {@link $elements} is
* formatted for output.
* @see HTMLframesConverter::formatIndex()
* @abstract
*/
function formatIndex()
{
}
/**
* Called by {@link walk()} while converting.
*
* This method is intended to be the place that any of
* {@link $class_elements, $function_elements, $page_elements},
* {@link $define_elements}, and {@link $global_elements} is formatted for
* output, depending on the value of {@link $leftindex}
* @see HTMLframesConverter::formatLeftIndex()
* @abstract
*/
function formatLeftIndex()
{
}
/**
* Called by {@link parserSourceInlineTag::stringConvert()} to allow
* converters to format the source code the way they'd like.
*
* default returns it unchanged (html with xhtml tags)
* @param string output from highlight_string() - use this function to
* reformat the returned data for Converter-specific output
* @return string
* @deprecated in favor of tokenizer-based highlighting. This will be
* removed for 2.0
*/
function unmangle($sourcecode)
{
return $sourcecode;
}
/**
* Initialize highlight caching
*/
function startHighlight()
{
$this->_highlightCache = array(false, false);
$this->_appendHighlight = '';
}
function getHighlightState()
{
return $this->_highlightCache;
}
function _setHighlightCache($type, $token)
{
$test = ($this->_highlightCache[0] === $type && $this->_highlightCache[1] == $token);
if (!$test) {
$this->_appendHighlight = $this->flushHighlightCache();
} else {
$this->_appendHighlight = '';
}
$this->_highlightCache = array($type, $token);
return $test;
}
/**
* Return the close text for the current token
* @return string
*/
function flushHighlightCache()
{
$hc = $this->_highlightCache;
$this->_highlightCache = array(false, false);
if ($hc[0]) {
if (!isset($this->template_options[$hc[0]]['/'.$hc[1]])) {
return '';
}
return $this->template_options[$hc[0]]['/'.$hc[1]];
}
return '';
}
/**
* Used to allow converters to format the source code the way they'd like.
*
* default returns it unchanged. Mainly used by the {@link HighlightParser}
* {@internal
* The method takes information from options.ini, the template options
* file, specifically the [highlightSourceTokens] and [highlightSource]
* sections, and uses them to enclose tokens.
*
* {@source } }
* @param integer token value from {@link PHP_MANUAL#tokenizer tokenizer constants}
* @param string contents of token
* @param boolean whether the contents are preformatted or need modification
* @return string
*/
function highlightSource($token, $word, $preformatted = false)
{
<

	Converters

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

Source for file Converter.inc