Source for file Converter.inc

Documentation is available at Converter.inc

<?php
/**
* Base class for all Converters
*
* phpDocumentor :: automatic documentation generator
*
* PHP versions 4 and 5
*
*
* 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>
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version CVS: $Id: Converter.inc 287891 2009-08-30 08:08:00Z ashnazg $
* @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 287891 2009-08-30 08:08:00Z ashnazg $
*/
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)
{
if ($token !== false)
{
if (!$preformatted) $word = $this->postProcess($word);
if (isset($this->template_options['highlightSourceTokens'][token_name($token)]))
{
if ($this->_setHighlightCache('highlightSourceTokens', token_name($token))) {
return $word;
}
$e = $this->_appendHighlight;
return $e . $this->template_options['highlightSourceTokens'][token_name($token)] . $word;
} else
{
$this->_setHighlightCache(false, false);
$e = $this->_appendHighlight;
return $e . $word;
}
} else
{
if (isset($this->template_options['highlightSource'][$word]))
{
$newword = ($preformatted ? $word : $this->postProcess($word));
if ($this->_setHighlightCache('highlightSource', $word)) {
return $newword;
}
$e = $this->_appendHighlight;
return $e . $this->template_options['highlightSource'][$word] . $newword;
} else
{
$this->_setHighlightCache(false, false);
$e = $this->_appendHighlight;
return $e . ($preformatted ? $word : $this->postProcess($word));
}
}
}
/**
* Used to allow converters to format the source code of DocBlocks 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 [highlightDocBlockSourceTokens] section, and uses
* it to enclose tokens.
*
* {@source } }
* @param string name of docblock token type
* @param string contents of token
* @param boolean whether the contents are preformatted or need modification
* @return string
*/
function highlightDocBlockSource($token, $word, $preformatted = false)
{
if (empty($word)) {
$this->_setHighlightCache(false, false);
$e = $this->_appendHighlight;
return $e . $word;
}
if (isset($this->template_options['highlightDocBlockSourceTokens'][$token]))
{
if (!$preformatted) $word = $this->postProcess($word);
if ($this->_setHighlightCache('highlightDocBlockSourceTokens', $token)) {
return $word;
}
$e = $this->_appendHighlight;
return $e . $this->template_options['highlightDocBlockSourceTokens'][$token] . $word;
} else {
$this->_setHighlightCache(false, false);
$e = $this->_appendHighlight;
return $e . ($preformatted ? $word : $this->postProcess($word));
}
}
/**
* Used to allow converters to format the source code of Tutorial XML 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 [highlightDocBlockSourceTokens] section, and uses
* it to enclose tokens.
*
* {@source } }
* @param string name of docblock token type
* @param string contents of token
* @param boolean whether the contents are preformatted or need modification
* @return string
*/
function highlightTutorialSource($token, $word, $preformatted = false)
{
if (empty($word)) {
$this->_setHighlightCache(false, false);
$e = $this->_appendHighlight;
return $e . $word;
}
if (isset($this->template_options['highlightTutorialSourceTokens'][$token]))
{
if (!$preformatted) $word = $this->postProcess($word);
if ($this->_setHighlightCache('highlightTutorialSourceTokens', $token)) {
return $word;
}
$e = $this->_appendHighlight;
return $e . $this->template_options['highlightTutorialSourceTokens'][$token] . $word;
} else {
$this->_setHighlightCache(false, false);
$e = $this->_appendHighlight;
return $e . ($preformatted ? $word : $this->postProcess($word));
}
}
/**
* Called by {@link parserReturnTag::Convert()} to allow converters to
* change type names to desired formatting
*
* Used by {@link XMLDocBookConverter::type_adjust()} to change true and
* false to the peardoc2 values
* @param string
* @return string
*/
function type_adjust($typename)
{
return $typename;
}
/**
* 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 $this->ProgramExample($example, $tutorial, $inlinesourceparse, $class, $linenum, $filesourcepath);
}
/**
* Used to convert the <<code>> tag in a docblock
* @param string
* @param boolean true if this is to highlight a tutorial <programlisting>
* @return string
*/
function ProgramExample($example, $tutorial = false, $inlinesourceparse = null/*false*/,
$class = null/*false*/, $linenum = null/*false*/, $filesourcepath = null/*false*/)
{
$this->highlightingSource = true;
if (tokenizer_ext)
{
$e = $example;
if (!is_array($example))
{
$obj = new phpDocumentorTWordParser;
$obj->setup($example);
$e = $obj->getFileSource();
$bOpenTagFound = false;
foreach ($e as $ke => $ee)
{
foreach ($ee as $kee => $eee)
{
if ((int) $e[$ke][$kee][0] == T_OPEN_TAG)
{
$bOpenTagFound = true;
}
}
}
if (!$bOpenTagFound) {
$example = "<?php\n".$example;
$obj->setup($example);
$e = $obj->getFileSource();
unset($e[0]);
$e = array_values($e);
}
unset($obj);
}
$saveclass = $this->class;
$parser = new phpDocumentor_HighlightParser;
if (!isset($inlinesourceparse))
{
$example = $parser->parse($e, $this, true); // force php mode
} else
{
if (isset($filesourcepath))
{
$example = $parser->parse($e, $this, $inlinesourceparse, $class, $linenum, $filesourcepath);
} elseif (isset($linenum))
{
$example = $parser->parse($e, $this, $inlinesourceparse, $class, $linenum);
} elseif (isset($class))
{
$example = $parser->parse($e, $this, $inlinesourceparse, $class);
} else
{
$example = $parser->parse($e, $this, $inlinesourceparse);
}
}
$this->class = $saveclass;
} else
{
$example = $this->postProcess($example);
}
$this->highlightingSource = false;
if ($tutorial)
{
return $example;
}
if (!isset($this->template_options['desctranslate'])) return $example;
if (!isset($this->template_options['desctranslate']['code'])) return $example;
$example = $this->template_options['desctranslate']['code'] . $example;
if (!isset($this->template_options['desctranslate']['/code'])) return $example;
return $example . $this->template_options['desctranslate']['/code'];
}
/**
* @param string
*/
function TutorialExample($example)
{
$this->highlightingSource = true;
$parse = new phpDocumentor_TutorialHighlightParser;
$x = $parse->parse($example, $this);
$this->highlightingSource = false;
return $x;
}
/**
* Used to convert the contents of <<li>> in a docblock
* @param string
* @return string
*/
function ListItem($item)
{
if (!isset($this->template_options['desctranslate'])) return $item;
if (!isset($this->template_options['desctranslate']['li'])) return $item;
$item = $this->template_options['desctranslate']['li'] . $item;
if (!isset($this->template_options['desctranslate']['/li'])) return $item;
return $item . $this->template_options['desctranslate']['/li'];
}
/**
* Used to convert the contents of <<ol>> or <<ul>> in a docblock
* @param string
* @return string
*/
function EncloseList($list,$ordered)
{
$listname = ($ordered ? 'ol' : 'ul');
if (!isset($this->template_options['desctranslate'])) return $list;
if (!isset($this->template_options['desctranslate'][$listname])) return $list;
$list = $this->template_options['desctranslate'][$listname] . $list;
if (!isset($this->template_options['desctranslate']['/'.$listname])) return $list;
return $list . $this->template_options['desctranslate']['/'.$listname];
}
/**
* Used to convert the contents of <<pre>> in a docblock
* @param string
* @return string
*/
function PreserveWhiteSpace($string)
{
if (!isset($this->template_options['desctranslate'])) return $string;
if (!isset($this->template_options['desctranslate']['pre'])) return $string;
$string = $this->template_options['desctranslate']['pre'] . $string;
if (!isset($this->template_options['desctranslate']['/pre'])) return $string;
return $string . $this->template_options['desctranslate']['/pre'];
}
/**
* Used to enclose a paragraph in a docblock
* @param string
* @return string
*/
function EncloseParagraph($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['p'])) return $para;
$para = $this->template_options['desctranslate']['p'] . $para;
if (!isset($this->template_options['desctranslate']['/p'])) return $para;
return $para . $this->template_options['desctranslate']['/p'];
}
/**
* Used to convert the contents of <> in a docblock
* @param string
* @return string
*/
function Bolden($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['b'])) return $para;
$para = $this->template_options['desctranslate']['b'] . $para;
if (!isset($this->template_options['desctranslate']['/b'])) return $para;
return $para . $this->template_options['desctranslate']['/b'];
}
/**
* Used to convert the contents of <> in a docblock
* @param string
* @return string
*/
function Italicize($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['i'])) return $para;
$para = $this->template_options['desctranslate']['i'] . $para;
if (!isset($this->template_options['desctranslate']['/i'])) return $para;
return $para . $this->template_options['desctranslate']['/i'];
}
/**
* Used to convert the contents of <<var>> in a docblock
* @param string
* @return string
*/
function Varize($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['var'])) return $para;
$para = $this->template_options['desctranslate']['var'] . $para;
if (!isset($this->template_options['desctranslate']['/var'])) return $para;
return $para . $this->template_options['desctranslate']['/var'];
}
/**
* Used to convert the contents of <<kbd>> in a docblock
* @param string
* @return string
*/
function Kbdize($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['kbd'])) return $para;
$para = $this->template_options['desctranslate']['kbd'] . $para;
if (!isset($this->template_options['desctranslate']['/kbd'])) return $para;
return $para . $this->template_options['desctranslate']['/kbd'];
}
/**
* Used to convert the contents of <<samp>> in a docblock
* @param string
* @return string
*/
function Sampize($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['samp'])) return $para;
$para = $this->template_options['desctranslate']['samp'] . $para;
if (!isset($this->template_options['desctranslate']['/samp'])) return $para;
return $para . $this->template_options['desctranslate']['/samp'];
}
/**
* Used to convert < > in a docblock
* @param string
* @return string
*/
function Br($para)
{
if (!isset($this->template_options['desctranslate'])) return $para;
if (!isset($this->template_options['desctranslate']['br'])) return $para;
$para = $this->template_options['desctranslate']['br'] . $para;
return $para;
}
/**
* This version does nothing
*
* Perform necessary post-processing of string data. For example, the HTML
* Converters should escape < and > to become < and >
* @return string
*/
function postProcess($text)
{
return $text;
}
/**
* Creates a table of contents for a {@}toc} inline tag in a tutorial
*
* This function should return a formatted table of contents. By default, it
* does nothing, it is up to the converter to format the TOC
* @abstract
* @return string table of contents formatted for use in the current output format
* @param array format: array(array('tagname' => section, 'link' => returnsee link, 'id' => anchor name, 'title' => from title tag),...)
*/
function formatTutorialTOC($toc)
{
return '';
}
/**
* Write out the formatted source code for a php file
*
* This function provides the primary functionality for the
* {@tutorial tags.filesource.pkg} tag.
* @param string full path to the file
* @param string fully highlighted/linked source code of the file
* @abstract
*/
function writeSource($filepath, $source)
{
debug($source);
return;
}
/**
* Write out the formatted source code for an example php file
*
* This function provides the primary functionality for the
* {@tutorial tags.example.pkg} tag.
* @param string example title
* @param string example filename (no path)
* @param string fully highlighted/linked source code of the file
* @abstract
*/
function writeExample($title, $path, $source)
{
return;
}
/** Translate the path info into a unique file name for the highlighted
* source code.
* @param string $pathinfo
* @return string
*/
function getFileSourceName($path)
{
global $_phpDocumentor_options;
$pathinfo = $this->proceduralpages->getPathInfo($path, $this);
$pathinfo['source_loc'] = str_replace($_phpDocumentor_options['Program_Root'].'/','',$pathinfo['source_loc']);
$pathinfo['source_loc'] = str_replace('/','_',$pathinfo['source_loc']);
return "fsource_{$pathinfo['package']}_{$pathinfo['subpackage']}_{$pathinfo['source_loc']}";
}
/** Return the fixed path to the source-code file folder.
* @param string $base Path is relative to this folder
* @return string
*/
function getFileSourcePath($base)
{
if (substr($base, strlen($base) - 1) != PATH_DELIMITER) {
$base .= PATH_DELIMITER;
}
return $base . '__filesource';
}
/** Return the path to the current
* @param string $pathinfo
* @return string
*/
function getCurrentPageURL()
{
return '{$srcdir}' . PATH_DELIMITER . $this->page_dir;
}
/**
* @return string an output-format dependent link to phpxref-style highlighted
* source code
* @abstract
*/
function getSourceLink($path)
{
return '';
}
/**
* @return string Link to the current page being parsed.
* Should return {@link $curname} and a converter-specific extension.
* @abstract
*/
function getCurrentPageLink()
{
}
/**
* Return a line of highlighted source code with formatted line number
*
* If the $path is a full path, then an anchor to the line number will be
* added as well
* @param integer line number
* @param string highlighted source code line
* @param false|stringfull path to @filesource file this line is a part of,
* if this is a single line from a complete file.
* @return string formatted source code line with line number
*/
function sourceLine($linenumber, $line, $path = false)
{
if ($path)
{
return $this->getSourceAnchor($path, $linenumber) .
$this->Br(sprintf('%-6u',$linenumber).str_replace("\n",'',$line));
} else
{
return $this->Br(sprintf('%-6u',$linenumber).str_replace("\n",'',$line));
}
}
/**
* Determine whether an element's file has generated source code, used for
* linking to line numbers of source.
*
* Wrapper for {@link $sourcePaths} in this version
*
* {@internal since file paths get stored with most/all slashes
* set to forward slash '/', we need to doublecheck that
* we're not given a backslashed path to search for...
* if we are, it's likely that it was originally stored
* with a forward slash. Further, I'm not convinced it's safe
* to just check the {@link PHPDOCUMENTOR_WINDOWS} flag, so I'm checking
* specifically for backslashes intead.}}}
*
* @param string full path to the source code file
* @return boolean
*/
function hasSourceCode($path)
{
return isset($this->sourcePaths[$path]);
if (strpos($path, '\\') > -1) {
$modifiedPath = str_replace('\\', '/', $path);
return isset($this->sourcePaths[$modifiedPath]);
} else {
return isset($this->sourcePaths[$path]);
}
}
/**
* Mark a file as having had source code highlighted
* @param string full path of source file
*/
function setSourcePaths($path)
{
$this->sourcePaths[$path] = true;
}
/**
* Used to translate an XML DocBook entity like ” from a tutorial by
* reading the options.ini file for the template.
* @param string entity name
*/
function TranslateEntity($name)
{
if (!isset($this->template_options['ppage']))
{
if (!$this->template_options['preservedocbooktags'])
return '';
else
return '&'.$name.';';
}
if (isset($this->template_options['ppage']['&'.$name.';']))
{
return $this->template_options['ppage']['&'.$name.';'];
} else
{
if (!$this->template_options['preservedocbooktags'])
return '';
else
return '&'.$name.';';
}
}
/**
* Used to translate an XML DocBook tag from a tutorial by reading the
* options.ini file for the template.
* @param string tag name
* @param string any attributes Format: array(name => value)
* @param string the tag contents, if any
* @param string the tag contents, if any, unpost-processed
* @return string
*/
function TranslateTag($name,$attr,$cdata,$unconvertedcdata)
{
if (!isset($this->template_options['ppage']))
{
if (!$this->template_options['preservedocbooktags'])
return $cdata;
else
return '<'.$name.$this->AttrToString($name,$attr,true).'>'.$cdata.'</'.$name.'>'."\n";
}
// make sure this template transforms the tag into something
if (isset($this->template_options['ppage'][$name]))
{
// test for global attribute transforms like $attr$role = class, changing
// all role="*" attributes to class="*" in html, for example
foreach($attr as $att => $val)
{
if (isset($this->template_options['$attr$'.$att]))
{
$new = '';
if (!isset($this->template_options['$attr$'.$att]['close']))
{
$new .= '<'.$this->template_options['$attr$'.$att]['open'];
if (isset($this->template_options['$attr$'.$att]['cdata!']))
{
if (isset($this->template_options['$attr$'.$att]['separateall']))
$new .= $this->template_options['$attr$'.$att]['separator'];
else
$new .= ' ';
$new .= $this->template_options['$attr$'.$att]['$'.$att];
$new .= $this->template_options['$attr$'.$att]['separator'];
if ($this->template_options['$attr$'.$att]['quotevalues']) $val = '"'.$val.'"';
$new .= $val.'>';
} else
{
$new .= '>'.$val;
}
$new .= '</'.$this->template_options['$attr$'.$att]['open'].'>';
} else
{
$new .= $this->template_options['$attr$'.$att]['open'] . $val . $this->template_options['$attr$'.$att]['close'];
}
unset($attr[$att]);
$cdata = $new . $cdata;
}
}
if (!isset($this->template_options['ppage']['/'.$name]))
{// if the close tag isn't specified, we put opening and closing tags around it, with translated attributes
if (isset($this->template_options['ppage'][$name.'/']))
$cdata = '<'.$this->template_options['ppage'][$name].$this->AttrToString($name,$attr).'/>' . $cdata;
else
$cdata = '<'.$this->template_options['ppage'][$name].$this->AttrToString($name,$attr).'>' . $cdata .
'</'.$this->template_options['ppage'][$name].'>';
} else
{ // if close tag is specified, use the open and close as literal
if ($name == 'programlisting' && isset($attr['role']) &&
($attr['role'] == 'php' || $attr['role'] == 'tutorial' || $attr['role'] == 'html'))
{ // highlight PHP source
// var_dump($unconvertedcdata, $cdata);exit;
if ($attr['role'] == 'php') {
$cdata = $this->ProgramExample($unconvertedcdata, true);
} elseif ($attr['role'] == 'tutorial') {
$cdata = $this->TutorialExample($unconvertedcdata);
} elseif ($attr['role'] == 'html') {
$cdata = $unconvertedcdata;
}
} else
{// normal case below
$cdata = $this->template_options['ppage'][$name].$this->AttrToString($name,$attr). $cdata .$this->template_options['ppage']['/'.$name];
}
}
return $cdata;
} else
{
if ($this->template_options['preservedocbooktags'])
{
return '<'.$name.$this->AttrToString($name,$attr,true).'>' . $cdata .
'</'.$name.'>'."\n";
} else
{
return $cdata;
}
}
}
/**
* Convert the attribute of a Tutorial docbook tag's attribute list
* to a string based on the template options.ini
* @param string tag name
* @param attribute array
* @param boolean if true, returns attrname="value"...
* @return string
*/
function AttrToString($tag,$attr,$unmodified = false)
{
$ret = '';
if ($unmodified)
{
$ret = ' ';
foreach($attr as $n => $v)
{
$ret .= $n.' = "'.$v.'"';
}
return $ret;
}
// no_attr tells us to ignore all attributes
if (isset($this->template_options['no_attr'])) return $ret;
// tagname! tells us to ignore all attributes for this tag
if (isset($this->template_options['ppage'][$tag.'!'])) return $ret;
if (count($attr)) $ret = ' ';
// pass 1, check to see if any attributes add together
$same = array();
foreach($attr as $n => $v)
{
if (isset($this->template_options['ppage'][$tag.'->'.$n]))
{
$same[$this->template_options['ppage'][$tag.'->'.$n]][] = $n;
}
}
foreach($attr as $n => $v)
{
if (isset($this->template_options['ppage'][$tag.'->'.$n]))
{
if (count($same[$this->template_options['ppage'][$tag.'->'.$n]]) == 1)
{ // only 1 attribute translated for this one
// this is useful for equivalent value names
if (isset($this->template_options['ppage'][$tag.'->'.$n.'+'.$v])) $v = $this->template_options['ppage'][$tag.'->'.$n.'+'.$v];
} else
{ // more than 1 attribute combines to make the new attribute
$teststrtemp = array();
foreach($same[$this->template_options['ppage'][$tag.'->'.$n]] as $oldattr)
{
$teststrtemp[] = $oldattr.'+'.$attr[$oldattr];
}
$teststrs = array();
$num = count($same[$this->template_options['ppage'][$tag.'->'.$n]]);
for($i=0;$i<$num;$i++)
{
$started = false;
$a = '';
for($j=$i;!$started || $j != $i;$j = ($j + $i) % $num)
{
if (!empty($a)) $a .= '|';
$a .= $teststrtemp[$j];
}
$teststrs[$i] = $a;
}
$done = false;
foreach($teststrs as $test)
{
if ($done) break;
if (isset($this->template_options['ppage'][$tag.'->'.$test]))
{
$done = true;
$v = $this->template_options['ppage'][$tag.'->'.$test];
}
}
}
$ret .= $this->template_options['ppage'][$tag.'->'.$n].' = "'.$v.'"';
} else
{
if (!isset($this->template_options['ppage'][$tag.'!'.$n]))
{
if (isset($this->template_options['ppage']['$attr$'.$n]))
$ret .= $this->template_options['ppage']['$attr$'.$n].' = "'.$v.'"';
else
$ret .= $n.' = "'.$v.'"';
}
}
}
return $ret;
}
/**
* Convert the title of a Tutorial docbook tag section
* to a string based on the template options.ini
* @param string tag name
* @param array
* @param string title text
* @param string
* @return string
*/
function ConvertTitle($tag,$attr,$title,$cdata)
{
if (!isset($this->template_options[$tag.'_title'])) return array($attr,$cdata);
if (isset($this->template_options[$tag.'_title']['tag_attr']))
{
$attr[$this->template_options[$tag.'_title']['tag_attr']] = urlencode($cdata);
$cdata = '';
} elseif(isset($this->template_options[$tag.'_title']['cdata_start']))
{
$cdata = $this->template_options[$tag.'_title']['open'] . $title .
$this->template_options[$tag.'_title']['close'] . $cdata;
} else $cdata = $title.$cdata;
return array($attr,$cdata);
}
/**
* Return a converter-specific id to distinguish tutorials and their
* sections
*
* Used by {@}id}
* @return string
*/
function getTutorialId($package,$subpackage,$tutorial,$id)
{
return $package.$subpackage.$tutorial.$id;
}
/**
* Create the {@link $elements, $pkg_elements} and {@link $links} arrays
* @access private
* @todo version 2.0 - faulty package_output logic should be removed
*
* in this version, if the parent file isn't in the package, all
* the procedural elements are simply shunted to another package!
*/
function _createPkgElements(&$pages)
{
if (empty($this->elements))
{
$this->elements = array();
$this->pkg_elements = array();
$this->links = array();
phpDocumentor_out('Building indexes...');
flush();
foreach($pages as $j => $flub)
{
$this->package = $pages[$j]->parent->package;
$this->subpackage = $pages[$j]->parent->subpackage;
$this->class = false;
$this->curfile = $pages[$j]->parent->getFile();
$this->curname = $this->getPageName($pages[$j]->parent);
$this->curpath = $pages[$j]->parent->getPath();
$use = true;
if ($this->package_output)
{
if (in_array($this->package,$this->package_output))
{
$this->addElement($pages[$j]->parent,$pages[$j]);
} else
{
if (count($pages[$j]->classelements))
{
list(,$pages[$j]->parent->package) = each($this->package_output);
reset($this->package_output);
$pages[$j]->parent->subpackage = '';
$this->addElement($pages[$j]->parent,$pages[$j]);
} else
{
unset($pages[$j]);
continue;
}
}
} else
{
$this->addElement($pages[$j]->parent,$pages[$j]);
}
if ($use)
for($i=0; $i<count($pages[$j]->elements); $i++)
{
$pages[$j]->elements[$i]->docblock->package = $this->package;
$pages[$j]->elements[$i]->docblock->subpackage = $this->subpackage;
$this->proceduralpages->replaceElement($pages[$j]->elements[$i]);
$this->addElement($pages[$j]->elements[$i]);
}
for($i=0; $i<count($pages[$j]->classelements); $i++)
{
if ($this->class)
{
if ($pages[$j]->classelements[$i]->type == 'class')
{
if ($this->checkKillClass($pages[$j]->classelements[$i]->getName(),$pages[$j]->classelements[$i]->getPath())) continue;
$this->package = $pages[$j]->classelements[$i]->docblock->package;
if ($this->package_output) if (!in_array($this->package,$this->package_output)) continue;
$this->subpackage = $pages[$j]->classelements[$i]->docblock->subpackage;
$this->class = $pages[$j]->classelements[$i]->name;
} else
{
if ($this->killclass) continue;
// force all contained elements to have parent package/subpackage
$pages[$j]->classelements[$i]->docblock->package = $this->package;
$pages[$j]->classelements[$i]->docblock->subpackage = $this->subpackage;
}
}
if ($pages[$j]->classelements[$i]->type == 'class')
{
if ($this->checkKillClass($pages[$j]->classelements[$i]->getName(),$pages[$j]->classelements[$i]->getPath())) continue;
$this->package = $pages[$j]->classelements[$i]->docblock->package;
if ($this->package_output) if (!in_array($this->package,$this->package_output)) continue;
$this->subpackage = $pages[$j]->classelements[$i]->docblock->subpackage;
$this->class = $pages[$j]->classelements[$i]->name;
}
if (!$this->killclass) $this->addElement($pages[$j]->classelements[$i]);
}
}
phpDocumentor_out("done\n");
flush();
}
$this->sortIndexes();
$this->sortTodos();
if ($this->sort_page_contents_by_type) $this->sortPageContentsByElementType($pages);
}
/**
* Process the {@link $tutorials} array
*
* Using the tutorialname.ext.ini files, this method sets up tutorial
* hierarchy. There is some minimal error checking to make sure that no
* tutorial links to itself, even two levels deep as in tute->next->tute.
*
* If all tests pass, it creates the hierarchy
* @uses generateTutorialOrder()
* @uses _setupTutorialTree()
* @access private
*/
function _processTutorials()
{
$parents = $all = array();
foreach($this->tutorials as $package => $els)
{
if ($this->package_output)
{
if (!in_array($package,$this->package_output))
{
unset($this->tutorials[$package]);
continue;
}
}
if (!isset($this->pkg_elements[$package]))
{
unset($this->tutorials[$package]);
continue;
}
foreach($els as $subpackage => $els2)
{
foreach($els2 as $type => $tutorials)
{
foreach($tutorials as $tutorial)
{
if ($tutorial->ini)
{
if (isset($tutorial->ini['Linked Tutorials']))
{
foreach($tutorial->ini['Linked Tutorials'] as $child)
{
$sub = (empty($tutorial->subpackage) ? '' : $tutorial->subpackage . '/');
$kid = $tutorial->package . '/' . $sub . $child . '.' . $tutorial->tutorial_type;
// parent includes self as a linked tutorial?
$kidlink = $this->getTutorialLink($kid,false,false,array($tutorial->package));
if (is_object($kidlink) && $this->returnSee($kidlink) == $tutorial->getLink($this))
{ // bad!
addErrorDie(PDERROR_TUTORIAL_IS_OWN_CHILD,$tutorial->name,$tutorial->name.'.ini');
}
}
$parents[] = $tutorial;
}
}
$all[$package][$subpackage][$type][] = $tutorial;
}
}
}
}
// loop error-checking, use this to eliminate possibility of accidentally linking to a parent as a child
$testlinks = array();
foreach($parents as $parent)
{
$testlinks[$parent->name]['links'][] = $parent->getLink($this);
$testlinks[$parent->name]['name'][$parent->getLink($this)] = $parent->name;
}
// generate the order of tutorials, and link them together
foreach($parents as $parent)
{
foreach($parent->ini['Linked Tutorials'] as $child)
{
$sub = (empty($parent->subpackage) ? '' : $parent->subpackage . '/');
$kid = $parent->package . '/' . $sub . $child . '.' . $parent->tutorial_type;
// child tutorials must be in the same package AND subpackage
// AND have the same extension as the parent, makes things clearer for both ends
if (in_array($this->returnSee($this->getTutorialLink($kid,false,false,array($parent->package))),$testlinks[$parent->name]['links']))
addErrorDie(PDERROR_TUTORIAL_IS_OWN_GRANDPA,$testlinks[$parent->name][$this->returnSee($this->getTutorialLink($kid,false,false,array($parent->package)))],$kid->name,$testlinks[$parent->name][$this->returnSee($this->getTutorialLink($kid,false,false,array($parent->package)))],$kid->name.'.ini');
if ($this->returnSee($this->getTutorialLink($kid,false,false,array($parent->package))) == $kid)
{
addWarning(PDERROR_CHILD_TUTORIAL_NOT_FOUND, $child . '.' . $parent->tutorial_type, $parent->name .'.ini',$parent->package, $parent->subpackage);
}
}
}
$new = $tree = $roots = array();
// build a list of all 'root' tutorials (tutorials without parents).
foreach($parents as $i => $parent)
{
if (! $parent->isChildOf($parents)) {
$roots[] = $parent;
}
}
$parents = $roots;
// add the parents and all child tutorials in order to the list of tutorials to process
foreach($parents as $parent)
{
$this->generateTutorialOrder($parent,$all,$new);
}
if (count($all))
{
// add the leftover tutorials
foreach($all as $package => $els)
{
foreach($els as $subpackage => $els2)
{
foreach($els2 as $type => $tutorials)
{
foreach($tutorials as $tutorial)
{
$new[$package][$subpackage][$type][] = $tutorial;
}
}
}
}
}
// remove the old, unprocessed tutorials, and set it up with the next code
$this->tutorials = array();
// reset integrity of the tutorial list
$prev = false;
uksort($new, 'tutorialcmp');
// debug($this->vardump_tree($new));exit;
foreach($new as $package => $els)
{
foreach($els as $subpackage => $els2)
{
foreach($els2 as $type => $tutorials)
{
foreach($tutorials as $tutorial)
{
if ($prev)
{
$this->tutorials[$prevpackage][$prevsubpackage][$prevtype][$prevname]->setNext($tutorial,$this);
$tutorial->setPrev($prev,$this);
}
$this->tutorials[$package][$subpackage][$type][$tutorial->name] = $tutorial;
$prev = $tutorial->getLink($this,true);
$prevpackage = $package;
$prevsubpackage = $subpackage;
$prevtype = $type;
$prevname = $tutorial->name;
}
}
}
}
$this->tutorial_tree = $this->_setupTutorialTree();
return $new;
}
/**
* called by {@link phpDocumentor_IntermediateParser::Convert()} to traverse
* the array of pages and their elements, converting them to the output format
*
* The walk() method should be flexible enough such that it never needs
* modification. walk() sets up all of the indexes, and sorts everything in
* logical alphabetical order. It then passes each element individually to
* {@link Convert()}, which then passes to the Convert*() methods. A child
* Converter need not override any of these unless special functionality must
* be added. see {@tutorial Converters/template.vars.cls} for details.
* {@internal
* walk() first creates all of the indexes {@link $elements, $pkg_elements}
* and the left indexes specified by {@link $leftindexes},
* and then sorts them by calling {@link sortIndexes()}.
*
* Next, it converts all README/CHANGELOG/INSTALL-style files, using
* {@link Convert_RIC}.
*
* After this, it
* passes all package-level docs to Convert(). Then, it calls the index
* sorting functions {@link formatPkgIndex(), formatIndex()} and
* {@link formatLeftIndex()}.
*
* Finally, it converts each procedural page in alphabetical order. This
* stage passes elements from the physical file to Convert() in alphabetical
* order. First, procedural page elements {@link parserDefine, parserInclude}
* {@link parserGlobal}, and {@link parserFunction} are passed to Convert().
*
* Then, class elements are passed in this order: {@link parserClass}, then
* all of the {@link parserVar}s in the class and all of the
* {@link parserMethod}s in the class. Classes are in alphabetical order,
* and both vars and methods are in alphabetical order.
*
* Finally, {@link ConvertErrorLog()} is called and the data walk is complete.}}}
* @param array Format: array(fullpath => {@link parserData} structure with full {@link parserData::$elements}
* and {@link parserData::$class_elements}.
* @param array Format: array({@link parserPackagePage} 1, {@link parserPackagePage} 2,...)
* @uses Converter::_createPkgElements() sets up {@link $elements} and
* {@link $pkg_elements} array, as well as {@link $links}
*/
function walk(&$pages,&$package_pages)
{
if (empty($pages))
{
die("ERROR: nothing parsed");
}
$this->_createPkgElements($pages);
if (count($this->ric))
{
phpDocumentor_out("Converting README/INSTALL/CHANGELOG contents...\n");
flush();
foreach($this->ric as $name => $contents)
{
phpDocumentor_out("$name...");
flush();
$this->Convert_RIC($name,$contents);
}
phpDocumentor_out("\ndone\n");
flush();
}
foreach($package_pages as $i => $perp)
{
if ($this->package_output)
{
if (!in_array($package_pages[$i]->package,$this->package_output)) continue;
}
phpDocumentor_out('Converting package page for package '.$package_pages[$i]->package.'... ');
flush();
$this->package = $package_pages[$i]->package;
$this->subpackage = '';
$this->class = false;
$this->Convert($package_pages[$i]);
phpDocumentor_out("done\n");
flush();
}
phpDocumentor_out("Converting tutorials/extended docs\n");
flush();
// get tutorials into the order they will display, and set next/prev links
$new = $this->_processTutorials();
foreach($this->tutorials as $package => $els)
{
foreach($els as $subpackage => $els2)
{
foreach($els2 as $type => $tutorials)
{
foreach($tutorials as $tutorial)
{
switch ($type)
{
case 'pkg' :
$a = '';
if ($tutorial->ini)
$a .= 'Top-level ';
if (!empty($tutorial->subpackage))
$a .= 'Sub-';
$ptext = "Converting ${a}Package-level tutorial ".$tutorial->name.'...';
break;
case 'cls' :
$a = '';
if ($tutorial->ini)
$a .= 'Top-level ';
$ptext = "Converting ${a}Class-level tutorial " . $tutorial->name ." and associating...";
$link = Converter::getClassLink(str_replace('.cls','',$tutorial->name), $tutorial->package);
if (is_object($link))
{
if ($this->sort_absolutely_everything)
{
$addend = 'unsuccessful ';
if (isset($this->package_elements[$tutorial->package][$tutorial->subpackage]['class'][$link->name]))
{
$this->package_elements[$tutorial->package][$tutorial->subpackage]['class'][$link->name][0]->addTutorial($tutorial,$this);
$addend = 'success ';
}
} else
{
$addend = 'unsuccessful ';
if (!isset($this->classes->killclass[str_replace('.cls','',$tutorial->name)]) && !isset($this->classes->killclass[str_replace('.cls','',$tutorial->name)][$tutorial->path]))
{
foreach($pages as $j => $inf)
{
foreach($inf->classelements as $i => $class)
{
if ($class->type == 'class' && $class->name == str_replace('.cls','',$tutorial->name) && $class->path == $link->path)
{
$pages[$j]->classelements[$i]->addTutorial($tutorial,$this);
$addend = 'success ';
}
}
}
}
}
$ptext .= $addend;
} else $ptext .= "unsuccessful ";
break;
case 'proc' :
$a = '';
if ($tutorial->ini)
$a .= 'Top-level ';
$ptext = "Converting ${a}Procedural-level tutorial ".$tutorial->name." and associating...";
$link = Converter::getPageLink(str_replace('.proc','',$tutorial->name), $tutorial->package);
if (is_object($link))
{
$addend = 'unsuccessful ';
if ($this->sort_absolutely_everything)
{
if (isset($this->package_elements[$tutorial->package][$tutorial->subpackage]['page'][$link->path]))
{
$this->package_elements[$tutorial->package][$tutorial->subpackage]['page'][$link->path][0]->addTutorial($tutorial,$this);
$addend = "success ";
}
} else
{
foreach($pages as $j => $info)
{
if ($j == $link->path)
{
$pages[$j]->addTutorial($tutorial,$this);
$addend = "success ";
}
}
}
$ptext .= $addend;
} else $ptext .= "unsuccessful ";
break;
}
phpDocumentor_out($ptext);
flush();
$this->package = $tutorial->package;
$this->subpackage = $tutorial->subpackage;
$this->Convert($tutorial);
phpDocumentor_out("done\n");
flush();
}
}
}
}
phpDocumentor_out("Formatting Package Indexes...");
flush();
$this->formatPkgIndex();
phpDocumentor_out("done\n");
flush();
phpDocumentor_out("Formatting Index...");
flush();
$this->formatIndex();
phpDocumentor_out("done\n\n");
flush();
phpDocumentor_out("Formatting Left Quick Index...");
flush();
$this->formatLeftIndex();
phpDocumentor_out("done\n\n");
flush();
if ($this->sort_absolutely_everything) return $this->walk_everything();
foreach($pages as $j => $flub)
{
phpDocumentor_out('Converting '.$pages[$j]->parent->getPath());
flush();
$this->package = $pages[$j]->parent->package;
$this->subpackage = $pages[$j]->parent->subpackage;
$this->class = false;
$this->curfile = $pages[$j]->parent->getFile();
$this->curname = $this->getPageName($pages[$j]->parent);
$this->curpath = $pages[$j]->parent->getPath();
$use = true;
if ($this->package_output)
{
if (in_array($this->package,$this->package_output))
{
$this->Convert($pages[$j]);
} else
{
$use = false;
}
} else
{
$this->Convert($pages[$j]);
}
phpDocumentor_out(" Procedural Page Elements...");
flush();
if ($use)
for($i=0; $i<count($pages[$j]->elements); $i++)
{
$a = $pages[$j]->elements[$i]->docblock->getKeyword('access');
if (is_object($a)) $a = $a->getString();
if (!$this->parseprivate && ($a == 'private'))
continue;
// phpDocumentor_out(" ".$pages[$j]->elements[$i]->name."\n");
$pages[$j]->elements[$i]->docblock->package = $this->package;
$pages[$j]->elements[$i]->docblock->subpackage = $this->subpackage;
$this->Convert($pages[$j]->elements[$i]);
}
phpDocumentor_out(" Classes...");
$this->class = false;
flush();
for($i=0; $i<count($pages[$j]->classelements); $i++)
{
if ($this->class)
{
if ($pages[$j]->classelements[$i]->type == 'class')
{
if (!$this->killclass) $this->endClass();
$this->killclass = false;
if ($this->checkKillClass($pages[$j]->classelements[$i]->getName(),$pages[$j]->classelements[$i]->getPath())) continue;
$this->package = $pages[$j]->classelements[$i]->docblock->package;
if ($this->package_output) if (!in_array($this->package,$this->package_output)) continue;
$this->subpackage = $pages[$j]->classelements[$i]->docblock->subpackage;
$this->class = $pages[$j]->classelements[$i]->name;
} else
{
$a = $pages[$j]->classelements[$i]->docblock->getKeyword('access');
if (is_object($a)) $a = $a->getString();
if (!$this->parseprivate && ($a == 'private'))
continue;
if ($this->killclass) continue;
// force all contained elements to have parent package/subpackage
$pages[$j]->classelements[$i]->docblock->package = $this->package;
$pages[$j]->classelements[$i]->docblock->subpackage = $this->subpackage;
}
}
if ($pages[$j]->classelements[$i]->type == 'class')
{
$this->killclass = false;
if ($this->checkKillClass($pages[$j]->classelements[$i]->getName(),$pages[$j]->classelements[$i]->getPath())) continue;
$this->package = $pages[$j]->classelements[$i]->docblock->package;
if ($this->package_output) if (!in_array($this->package,$this->package_output)) continue;
$this->subpackage = $pages[$j]->classelements[$i]->docblock->subpackage;
$this->class = $pages[$j]->classelements[$i]->name;
}
if ($this->killclass) continue;
// phpDocumentor_out(" ".$pages[$j]->classelements[$i]->name."\n");
$this->Convert($pages[$j]->classelements[$i]);
}
if (count($pages[$j]->classelements) && !$this->killclass) $this->endClass();
phpDocumentor_out(" done\n");
flush();
$this->endPage();
}
phpDocumentor_out("\nConverting @todo List...");
flush();
if (count($this->todoList))
{
$this->ConvertTodoList();
}
phpDocumentor_out("done\n");
flush();
phpDocumentor_out("\nConverting Error Log...");
flush();
$this->ConvertErrorLog();
phpDocumentor_out("done\n");
flush();
}
/**
* Get a tree structure representing the hierarchy of tutorials
*
* Returns an array in format:
* <pre>
* array('tutorial' => {@link parserTutorial},
* 'kids' => array( // child tutorials
* array('tutorial' => child {@link parserTutorial},
* 'kids' => array(...)
* )
* )
* )
* </pre>
* @param parserTutorial|array
* @tutorial tutorials.pkg
* @return array
*/
function getTutorialTree($tutorial)
{
if (is_object($tutorial))
{
$path = $this->_tutorial_path($tutorial,$tutorial,$tutorial);
if (isset($this->tutorial_tree[$path])) {
$tutorial = $this->tutorial_tree[$path];
} else {
return false;
}
}
$tree = array();
if (isset($tutorial['tutorial']))
{
$tree['tutorial'] = $tutorial['tutorial'];
if (isset($tutorial['child']))
{
foreach($tutorial['child'] as $a => $b)
{
$btut = $b['tutorial'];
$res = array(
'tutorial' => $this->tutorials
[$btut->package][$btut->subpackage]
[$btut->tutorial_type][$btut->name]
);
if (isset($b['child']))
{
$tempres = Converter::getTutorialTree($b);
$res['kids'] = $tempres['kids'];
}
$tree['kids'][] = $res;
}
}
}
return $tree;
}
/**
* Remove tutorials one by one from $all, and transfer them into $new in the
* order they should be parsed
* @param parserTutorial
* @param array
* @param array
* @access private
*/
function generateTutorialOrder($parent,&$all,&$new)
{
// remove from the list of tutorials to process
foreach($all[$parent->package][$parent->subpackage][$parent->tutorial_type] as $ind => $t)
{
if ($t->name == $parent->name) {
unset($all[$parent->package][$parent->subpackage][$parent->tutorial_type][$ind]);
}
}
// add to the new ordered list of tutorials
$x = &$new[$parent->package][$parent->subpackage][$parent->tutorial_type];
if (!is_object($x[count($x) - 1]) || $x[count($x) - 1]->name != $parent->name)
{ // only add if the parent isn't also a child
$new[$parent->package][$parent->subpackage][$parent->tutorial_type][] = $parent;
// add a new branch to the tree
}
// process all child tutorials, and insert them in order
// debug("processing parent ".$parent->name);
if ($parent->ini)
{
foreach($parent->ini['Linked Tutorials'] as $child)
{
$sub = (empty($parent->subpackage) ? '' : $parent->subpackage . '/');
$kid = $parent->package . '/' . $sub . $child . '.' . $parent->tutorial_type;
$_klink = $this->getTutorialLink($kid,false,false,array($parent->package));
if (is_object($_klink)) {
$klink = $this->returnSee($_klink);
} else {
$klink = false;
}
// remove the child from the list of remaining tutorials
foreach($all[$parent->package][$parent->subpackage][$parent->tutorial_type] as $ind => $tute)
{
if ($klink && $tute->getLink($this) == $klink)
{
// set up parent, next and prev links
$tute->setParent($parent, $this);
// remove the child from the list of tutorials to process
foreach($all[$parent->package][$parent->subpackage][$parent->tutorial_type] as $ind => $t)
{
if ($t->name == $tute->name)
unset($all[$parent->package][$parent->subpackage][$parent->tutorial_type][$ind]);
}
// add to the new ordered list of tutorials
$new[$parent->package][$parent->subpackage][$parent->tutorial_type][] = $tute;
if ($tute->ini)
{
// add all the child's child tutorials to the list
$this->generateTutorialOrder($tute,$all,$new);
}
}
}
}
}
return;
}
/** Returns the path to this tutorial as a string
* @param parserTutorial $pkg
* @param parserTutorial $subpkg
* @param parserTutorial $namepkg
* @return string */
function _tutorial_path($pkg, $subpkg = 0, $namepkg = 0)
{
if (!$subpkg) {
$subpkg = $pkg;
}
if (!$namepkg) {
$namepkg = $pkg;
}
$subpackagename = ($subpkg->subpackage ? '/' . $subpkg->subpackage : '');
return $pkg->package . $subpackagename . '/' . $namepkg->name;
}
/**
* Creates a tree structure of tutorials
*
* Format:
* <pre>
* array('package/subpackage/tutorial1.ext' =>
* array('tutorial' => {@link parserTutorial},
* 'child' =>
* array('package/subpackage/child1tutorial.ext' => ...,
* 'package/subpackage/child2tutorial.ext' => ...,
* ...
* )
* 'package/subpackage/tutorial2.ext' => ...,
* ...
* )
* </pre>
* @return array the tutorial tree
* @access private
*/
function _setupTutorialTree($parent = false)
{
if (! isset($this->processed_tutorials)) {
$this->processed_tutorials = array();
}
$tree = array();
if (!$parent)
{
foreach($this->tutorials as $package => $s)
{
foreach($s as $subpackage => $t)
{
foreach($t as $type => $n)
{
foreach($n as $name => $tutorial)
{
if ($tutorial->parent) {
continue;
}
$child_path = $this->_tutorial_path($tutorial,$tutorial,$tutorial);
if (isset($this->processed_tutorials[$child_path])) {
continue;
}
$this->processed_tutorials[$child_path] = $tutorial;
//debug("parent ".$tutorial->name);
$ret = $this->_setupTutorialTree($tutorial);
if (!count($tree)) {
$tree = $ret;
} else {
$tree = array_merge($tree,$ret);
}
}
}
}
}
return $tree;
}
$parent_path = $this->_tutorial_path($parent);
$tree[$parent_path]['tutorial'] = $parent;
// process all child tutorials, and insert them in order
if ($parent->ini)
{
foreach($parent->ini['Linked Tutorials'] as $child)
{
if (isset($this->tutorials[$parent->package][$parent->subpackage]
[$parent->tutorial_type][$child . '.' .
$parent->tutorial_type])) {
// remove the child from the list of remaining tutorials
$tute = $this->tutorials[$parent->package][$parent->subpackage]
[$parent->tutorial_type][$child . '.' .
$parent->tutorial_type];
} else {
$tute = false;
}
if (!$tute) {
continue;
}
$child_path = $this->_tutorial_path($parent,$parent,$tute);
if (isset($this->processed_tutorials[$child_path])) {
continue;
}
$this->processed_tutorials[$child_path] = $tute;
if ($tute->name != $child . '.' . $parent->tutorial_type) {
continue;
}
//echo "Adding [$child_path] to [$parent_path] ";
$tree[$parent_path]['child'][$this->_tutorial_path($parent,$parent,$tute)]['tutorial']
= $tute;
if (!$tute->ini) {
continue;
}
// add all the child's child tutorials to the list
if (!isset($tree[$parent_path]['child'])) {
$tree[$parent_path]['child'] = $this->_setupTutorialTree($tute);
} else {
$tree[$parent_path]['child'] = array_merge($tree[$parent_path]['child'],
$this->_setupTutorialTree($tute));
}
}
}
return $tree;
}
/**
* Debugging function for dumping {@link $tutorial_tree}
* @return string
*/
function vardump_tree($tree,$indent='')
{
if (phpDocumentor_get_class($tree) == 'parsertutorial') return $tree->name.' extends '.($tree->parent? $tree->parent->name : 'nothing');
$a = '';
foreach($tree as $ind => $stuff)
{
$x = $this->vardump_tree($stuff,"$indent ");
$a .= $indent.'['.$ind." => \n ".$indent.$x."]\n";
}
return substr($a,0,strlen($a) - 1);
}
/**
* @access private
*/
function sort_package_elements($a,$b)
{
if (($a->type == $b->type) && (isset($a->isConstructor) && $a->isConstructor)) return -1;
if (($a->type == $b->type) && (isset($b->isConstructor) && $b->isConstructor)) return 1;
if ($a->type == $b->type) return strnatcasecmp($a->name,$b->name);
if ($a->type == 'class') return -1;
if ($b->type == 'class') return 1;
if ($a->type == 'const') return -1;
if ($b->type == 'const') return 1;
if ($a->type == 'var') return -1;
if ($b->type == 'var') return 1;
if ($a->type == 'page') return -1;
if ($b->type == 'page') return 1;
if ($a->type == 'include') return -1;
if ($b->type == 'include') return 1;
if ($a->type == 'define') return -1;
if ($b->type == 'define') return 1;
if ($a->type == 'global') return -1;
if ($b->type == 'global') return 1;
if ($a->type == 'function') return -1;
if ($b->type == 'function') return 1;
}
/**
* @access private
*/
function defpackagesort($a,$b)
{
if ($a == $GLOBALS['phpDocumentor_DefaultPackageName']) return -1;
if ($b == $GLOBALS['phpDocumentor_DefaultPackageName']) return 0;
return strnatcasecmp($a,$b);
}
/**
* @access private
*/
function Pc_sort($a,$b)
{
return strnatcasecmp(key($a),key($b));
}
/**
* walk over elements by package rather than page
*
* This method is designed for converters like the PDF converter that need
* everything passed in alphabetical order by package/subpackage and by
* procedural and then class information
* @see PDFdefaultConverter
* @see walk()
*/
function walk_everything()
{
global $hooser;
$hooser = false;
uksort($this->package_elements,array($this,'defpackagesort'));
foreach($this->package_elements as $package => $r)
{
if ($this->package_output)
{
if (!in_array($this->package,$this->package_output))
{
unset($this->package_elements[$package]);
continue;
}
}
uksort($this->package_elements[$package],'strnatcasecmp');
}
foreach($this->package_elements as $package => $r)
{
foreach($this->package_elements[$package] as $subpackage => $r)
{
if (isset($r['page']))
{
uksort($r['page'],'strnatcasecmp');
foreach($r['page'] as $page => $oo)
{
usort($this->package_elements[$package][$subpackage]['page'][$page],array($this,'sort_package_elements'));
}
}
if (isset($r['class']))
{
uksort($r['class'],'strnatcasecmp');
foreach($r['class'] as $page => $oo)
{
usort($r['class'][$page],array($this,'sort_package_elements'));
}
}
$this->package_elements[$package][$subpackage] = $r;
}
}
foreach($this->package_elements as $package => $s)
{
$notyet = false;
foreach($s as $subpackage => $r)
{
$this->package = $package;
$this->subpackage = $subpackage;
if (isset($r['page']))
{
$this->class = false;
foreach($r['page'] as $page => $elements)
{
if (is_array($elements))
{
foreach($elements as $element)
{
if ($element->type == 'page')
{
phpDocumentor_out('Converting '.$element->parent->getPath());
flush();
$this->curfile = $element->parent->getFile();
$this->curname = $this->getPageName($element->parent);
$this->curpath = $element->parent->getPath();
$notyet = true;
} else
{
// force all contained elements to have parent package/subpackage
$element->docblock->package = $this->package;
$element->docblock->subpackage = $this->subpackage;
$a = $element->docblock->getKeyword('access');
if (is_object($a)) $a = $a->getString();
if (!$this->parseprivate && ($a == 'private'))
continue;
}
if ($notyet)
{
phpDocumentor_out(" Procedural Page Elements...");
flush();
$notyet = false;
}
$this->Convert($element);
}
}
$this->endPage();
phpDocumentor_out("done\n");
flush();
}
}
$start_classes = true;
if (isset($r['class']))
{
foreach($r['class'] as $class => $elements)
{
foreach($elements as $element)
{
if ($element->type == 'class')
{
if (!$start_classes)
{
if (count($elements) && !$this->killclass) $this->endClass();
phpDocumentor_out("done\n");
flush();
}
$start_classes = false;
$this->class = $element->getName();
$this->killclass = false;
if ($this->checkKillClass($element->getName(),$element->getPath())) continue;
if (!$this->killclass)
{
phpDocumentor_out('Converting '.$this->class."...");
flush();
$notyet = true;
}
} else
{
if ($notyet)
{
phpDocumentor_out("Variables/methods/Class constants...\n");
flush();
$notyet = false;
}
$a = $element->docblock->getKeyword('access');
if (is_object($a)) $a = $a->getString();
if (!$this->parseprivate && ($a == 'private'))
continue;
if ($this->killclass) continue;
// force all contained elements to have parent package/subpackage
$element->docblock->package = $this->package;
$element->docblock->subpackage = $this->subpackage;
}
if ($this->killclass) continue;
$this->Convert($element);
}
}
if (count($elements) && !$this->killclass) $this->endClass();
phpDocumentor_out("done\n");
flush();
} // if isset($r['class'])
} // foreach($s
} // foreach($this->package_elements)
phpDocumentor_out("\nConverting @todo List...");
flush();
if (count($this->todoList))
{
$this->ConvertTodoList();
}
phpDocumentor_out("done\n");
flush();
phpDocumentor_out("\nConverting Error Log...");
flush();
$this->ConvertErrorLog();
phpDocumentor_out("done\n");
flush();
}
/**
* Convert the phpDocumentor parsing/conversion error log
* @abstract
*/
function ConvertErrorLog()
{
}
/**
* Convert the list of all @todo tags
* @abstract
*/
function ConvertTodoList()
{
}
/**
* Sorts the @todo list - do not override or modify this function
* @access private
* @uses _sortTodos passed to {@link usort()} to sort the todo list
*/
function sortTodos()
{
phpDocumentor_out("\nSorting @todo list...");
flush();
foreach($this->todoList as $package => $r) {
usort($this->todoList[$package], array('Converter', '_sortTodoPackage'));
foreach ($r as $a => $sub) {
if (is_array($this->todoList[$package][$a][1])) {
usort($this->todoList[$package][$a][1],array('Converter', '_sortTodos'));
}
}
}
phpDocumentor_out("done\n");
}
/** @access private */
function _sortTodoPackage($a, $b)
{
return strnatcasecmp($a[0]->name, $b[0]->name);
}
/** @access private */
function _sortTodos($a, $b)
{
if (!is_object($a)) {
var_dump($a);
}
return strnatcasecmp($a->getString(), $b->getString());
}
/**
* Sorts all indexes - do not override or modify this function
* @uses $leftindex based on the value of leftindex, sorts link arrays
* @uses $class_elements sorts with {@link compareLink}
* @uses $page_elements sorts with {@link compareLink}
* @uses $define_elements sorts with {@link compareLink}
* @uses $global_elements sorts with {@link compareLink}
* @uses $function_elements sorts with {@link compareLink}
* @uses $elements sorts with {@link elementCmp}
* @uses $pkg_elements sorts with {@link elementCmp} after sorting by
* package/subpackage alphabetically
* @access private
*/
function sortIndexes()
{
phpDocumentor_out("\nSorting Indexes...");
flush();
uksort($this->elements,'strnatcasecmp');
if ($this->leftindex['classes'])
{
foreach($this->class_elements as $package => $o1)
{
foreach($o1 as $subpackage => $links)
{
usort($this->class_elements[$package][$subpackage],array($this,'compareLink'));
}
}
}
if ($this->leftindex['pages'])
{
foreach($this->page_elements as $package => $o1)
{
uksort($this->page_elements[$package],'strnatcasecmp');
foreach($o1 as $subpackage => $links)
{
usort($this->page_elements[$package][$subpackage],array($this,'compareLink'));
}
}
}
if ($this->leftindex['defines'])
{
foreach($this->define_elements as $package => $o1)
{
uksort($this->define_elements[$package],'strnatcasecmp');
foreach($o1 as $subpackage => $links)
{
usort($this->define_elements[$package][$subpackage],array($this,'compareLink'));
}
}
}
if ($this->leftindex['globals'])
{
foreach($this->global_elements as $package => $o1)
{
uksort($this->global_elements[$package],'strnatcasecmp');
foreach($o1 as $subpackage => $links)
{
usort($this->global_elements[$package][$subpackage],array($this,'compareLink'));
}
}
}
if ($this->leftindex['functions'])
{
foreach($this->function_elements as $package => $o1)
{
uksort($this->function_elements[$package],'strnatcasecmp');
foreach($o1 as $subpackage => $links)
{
usort($this->function_elements[$package][$subpackage],array($this,'compareLink'));
}
}
}
foreach($this->elements as $letter => $nothuing)
{
uasort($this->elements[$letter],array($this,"elementCmp"));
}
foreach($this->pkg_elements as $package => $els)
{
uksort($this->pkg_elements[$package],'strnatcasecmp');
foreach($this->pkg_elements[$package] as $subpackage => $els)
{
if (empty($els)) continue;
uksort($this->pkg_elements[$package][$subpackage],'strnatcasecmp');
foreach($els as $letter => $yuh)
{
usort($this->pkg_elements[$package][$subpackage][$letter],array($this,"elementCmp"));
}
}
}
phpDocumentor_out("done\n");
flush();
}
/**
* sorts {@link $page_contents} by element type as well as alphabetically
* @see $sort_page_contents_by_element_type
*/
function sortPageContentsByElementType(&$pages)
{
foreach($this->page_contents as $package => $els)
{
foreach($this->page_contents[$package] as $subpackage => $els)
{
if (empty($els)) continue;
foreach($this->page_contents[$package][$subpackage] as $path => $stuff)
{
if (!count($pages[$path]->elements)) continue;
usort($pages[$path]->elements,array($this,'eltypecmp'));
usort($this->page_contents[$package][$subpackage][$path],array($this,'eltypecmp'));
if (isset($this->page_contents[$package][$subpackage][$path][0]))
$this->page_contents[$package][$subpackage][$path]['###main'] = $this->page_contents[$package][$subpackage][$path][0];
unset($this->page_contents[$package][$subpackage][$path][0]);
}
}
}
}
/**
* @access private
* @see Converter::sortIndexes()
*/
function compareLink($a, $b)
{
return strnatcasecmp($a->name,$b->name);
}
/**
* @access private
* @see Converter::sortPageContentsByElementType()
*/
function eltypecmp($a, $b)
{
if ($a->type == 'page') return -1;
if ($b->type == 'page') return 1;
return strnatcasecmp($a->type.$a->name,$b->type.$b->name);
}
/**
* does a nat case sort on the specified second level value of the array
*
* @param mixed $a
* @param mixed $b
* @return int
* @access private
*/
function elementCmp ($a, $b)
{
return strnatcasecmp($a->getName(), $b->getName());
}
/**
* Used to stop conversion of @ignored or private @access classes
* @uses $killclass sets killclass based on the value of {@link Classes::$killclass}
* and {@link $package_output}
* @access private
*/
function checkKillClass($class, $path)
{
$this->killclass = false;
if (isset($this->classes->killclass[$class]) && isset($this->classes->killclass[$class][$path])) $this->killclass = true;
if ($this->package_output)
{
$a = $this->classes->getClass($class, $path);
if (!in_array($a->docblock->package,$this->package_output)) $this->killclass = true;
}
if (PHPDOCUMENTOR_DEBUG && $this->killclass) debug("$class $path killed");
return $this->killclass;
}
/**
* @param abstractLink descendant of abstractLink
* @param array|parserTaglist of @todos|@todo tag
* @access private
*/
function addTodoLink($link, $todos)
{
$this->todoList[$link->package][] = array($link, $todos);
}
/**
* Adds all elements to the {@link $elements, $pkg_elements, $links},
* {@link $linkswithfile} and left indexes - Do not modify or override
* @access private
* @param parserBase any documentable element descendant of parserBase
* except parserTutorial
* @param false|parserPageonly used to add a {@link parserPage} if the
* $element passed is a parserPage
* @staticvar string path of current page, used for {@link $page_contents} setup
*/
function addElement(&$element,$pageel=false)
{
static $curpath = '';
if ($this->package_output)
{
if (!in_array($this->package, $this->package_output)) return;
}
if ($pageel && phpDocumentor_get_class($pageel) == 'parserdata')
{
if (isset($pageel->docblock) && phpDocumentor_get_class($pageel->docblock) == 'parserdocblock')
{
$a = $pageel->docblock->getKeyword('todo');
if ($a)
{
$this->addTodoLink($this->addLink($element),$a);
}
}
}
if (isset($element->docblock))
{
$a = $element->docblock->getKeyword('access');
if (is_object($a)) $a = $a->getString();
if (!$this->parseprivate && ($a == 'private'))
return;
$a = $element->docblock->getKeyword('todo');
if ($a)
{
if ($element->type != 'include') {
$this->addTodoLink($this->addLink($element),$a);
} else {
addWarning(PDERROR_NOTODO_INCLUDE, $element->getLineNumber(),
$element->getPath());
}
}
}
$startPositionOfElementName = 0; // which character of the element name actually starts its textual name
switch($element->type)
{
case 'page' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->package][$element->subpackage]['page'][$element->getPath()][] = $pageel;
}
$link = $this->addLink($element);
$curpath = $element->getPath();
if ($this->leftindex['pages'])
$this->page_elements[$element->package][$element->subpackage][] = $link;
$this->page_contents[$element->package][$element->subpackage][$curpath]['###main'] = $link;
break;
case 'class' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['class'][$this->class][] = $element;
}
$link = $this->addLink($element);
if ($this->leftindex['classes'])
$this->class_elements[$element->docblock->package][$element->docblock->subpackage][] = $link;
$this->class_contents[$element->docblock->package][$element->docblock->subpackage][$this->class]['###main'] = $link;
break;
case 'include' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['page'][$curpath][] = $element;
}
$link = $this->addLink($element);
break;
case 'define' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['page'][$curpath][] = $element;
}
$link = $this->addLink($element);
if ($this->leftindex['defines'])
$this->define_elements[$element->docblock->package][$element->docblock->subpackage][] = $link;
$this->page_contents[$element->docblock->package][$element->docblock->subpackage][$curpath][] = $link;
break;
case 'global' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['page'][$curpath][] = $element;
}
$link = $this->addLink($element);
$startPositionOfElementName = 1; // lose the leading "$" character
if ($this->leftindex['globals'])
$this->global_elements[$element->docblock->package][$element->docblock->subpackage][] = $link;
$this->page_contents[$element->docblock->package][$element->docblock->subpackage][$curpath][] = $link;
break;
case 'var' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['class'][$this->class][] = $element;
}
$link = $this->addLink($element);
$startPositionOfElementName = 1; // lose the leading "$" character
$this->class_contents[$element->docblock->package][$element->docblock->subpackage][$this->class][] = $link;
break;
case 'const' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['class'][$this->class][] = $element;
}
$link = $this->addLink($element);
$this->class_contents[$element->docblock->package][$element->docblock->subpackage][$this->class][] = $link;
break;
case 'method' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['class'][$this->class][] = $element;
}
$link = $this->addLink($element);
$this->class_contents[$element->docblock->package][$element->docblock->subpackage][$this->class][] = $link;
break;
case 'function' :
if ($this->sort_absolutely_everything)
{
$this->package_elements[$element->docblock->package][$element->docblock->subpackage]['page'][$curpath][] = $element;
}
$link = $this->addLink($element);
if ($this->leftindex['functions'])
$this->function_elements[$element->docblock->package][$element->docblock->subpackage][] = $link;
$this->page_contents[$element->docblock->package][$element->docblock->subpackage][$curpath][] = $link;
break;
default :
break;
}
if ($element->getType() != 'include')
{
if ($element->getType() == 'var' || $element->getType() == 'method'|| $element->getType() == 'const')
{
$this->links[$this->package][$this->subpackage][$element->getType()][$element->class][$element->getName()] = $link;
$this->linkswithfile[$this->package][$this->subpackage][$element->getType()][$element->getPath()][$element->class][$element->getName()] = $link;
} else
{
if ($element->type == 'page')
{
$this->links[$this->package][$this->subpackage][$element->getType()][$element->getFile()] = $link;
$this->linkswithfile[$this->package][$this->subpackage][$element->getType()][$element->getPath()][$element->getFile()] = $link;
} else
{
$this->links[$this->package][$this->subpackage][$element->getType()][$element->getName()] = $link;
$this->linkswithfile[$this->package][$this->subpackage][$element->getType()][$element->getPath()][$element->getName()] = $link;
}
}
}
if ($element->type == 'page')
{
$this->elements[substr(strtolower($element->getFile()),$startPositionOfElementName,1)][] = $element;
$this->pkg_elements[$this->package][$this->subpackage][substr(strtolower($element->getFile()),$startPositionOfElementName,1)][] = $element;
} else
{
$this->elements[substr(strtolower($element->getName()),$startPositionOfElementName,1)][] = $element;
$this->pkg_elements[$this->package][$this->subpackage][substr(strtolower($element->getName()),$startPositionOfElementName,1)][] = $element;
}
}
/**
* returns an abstract link to element. Do not modify or override
*
* This method should only be called in process of Conversion, unless
* $element is a parserPage, or $page is set to true, and $element is
* not a parserPage
* @return abstractLink abstractLink descendant
* @access private
* @param parserElement element to add a new link (descended from
* {@link abstractLink})to the {@link $links} array
* @param string classname for elements that are class-based (this may be
* deprecated in the future, as the classname
* should be contained within the element. if $element is a
* page, this parameter is a package name
* @param string subpackage name for page elements
*/
function addLink(&$element,$page = false)
{
if ($page)
{
// create a fake parserPage to extract the fileAlias for this link
$fakepage = new parserPage;
$fakepage->setPath($element->getPath());
$fakepage->setFile(basename($element->getPath()));
$this->curname = $this->getPageName($fakepage);
}
switch($element->type)
{
case 'function':
$x = new functionLink;
$x->addLink($element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'define':
$x = new defineLink;
$x->addLink($element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'global':
$x = new globalLink;
$x->addLink($element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'class':
$x = new classLink;
$x->addLink($element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'method':
$x = new methodLink;
$x->addLink($this->class, $element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'var':
$x = new varLink;
$x->addLink($this->class, $element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'const':
$x = new constLink;
$x->addLink($this->class, $element->getPath(), $this->curname, $element->name, $element->docblock->package, $element->docblock->subpackage, $element->docblock->category);
return $x;
break;
case 'page':
$x = new pageLink;
$x->addLink($element->getPath(),$this->getPageName($element),$element->file,$element->package, $element->subpackage, $element->category);
return $x;
break;
}
}
/**
* Return a tree of all classes that extend this class
*
* The data structure returned is designed for a non-recursive algorithm,
* and is somewhat complex.
* In most cases, the array returned is:
*
* <pre>
* array('#root' =>
* array('link' => {@link classLink} to $class,
* 'parent' => false,
* 'children' => array(array('class' => 'childclass1',
* 'package' => 'child1package'),
* array('class' => 'childclass2',
* 'package' => 'child2package'),...
* )
* ),
* 'child1package#childclass1' =>
* array('link' => {@link classLink} to childclass1,
* 'parent' => '#root',
* 'children' => array(array('class' => 'kidclass',
* 'package' => 'kidpackage'),...
* )
* ),
* 'kidpackage#kidclass' =>
* array('link' => {@link classLink} to kidclass,
* 'parent' => 'child1package#childclass1',
* 'children' => array() // no children
* ),
* ....
* )
*</pre>
*
* To describe this format using language, every class in the tree has an
* entry in the first level of the array. The index for all child
* classes that extend the root class is childpackage#childclassname.
* Each entry in the array has 3 elements: link, parent, and children.
* <ul>
* <li>link - a {@link classLink} to the current class</li>
* <li>parent - a {@link classLink} to the class's parent, or false (except for one special case described below)</li>
* <li>children - an array of arrays, each entry has a 'class' and 'package' index to the child class,
* used to find the entry in the big array</li>
* </ul>
*
* special cases are when the #root class has a parent in another package,
* or when the #root class extends a class not found
* by phpDocumentor. In the first case, parent will be a
* classLink to the parent class. In the second, parent will be the
* extends clause, as in:
* <code>
* class X extends Y
* {
* ...
* }
* </code>
* in this case, the #root entry will be array('link' => classLink to X, 'parent' => 'Y', children => array(...))
*
* The fastest way to design a method to process the array returned
* is to copy HTMLframesConverter::getRootTree() into
* your converter and to modify the html to whatever output format you are going to use
* @see HTMLframesConverter::getRootTree()
* @param string class name
* @param string
* @param string
* @return array Format: see docs
*/
function getSortedClassTreeFromClass($class,$package,$subpackage)
{
$my_tree = array();
$root = $this->classes->getClassByPackage($class,$package);
if (!$root) return false;
$class_children = $this->classes->getDefiniteChildren($class,$root->curfile);
if (!$class_children)
{
// special case: parent class is found, but is not part of this package, class has no children
if (is_array($root->parent))
{
$x = $root->getParent($this);
if ($x->docblock->package != $package)
{
$v = Converter::getClassLink($root->getName(),$package,$root->getPath());
return array('#root' => array('link' => $v,'parent' => Converter::getClassLink($x->getName(),$x->docblock->package,$x->getPath()), 'children' => array()));
}
} else
{ // class has normal situation, no children
if (is_string($root->getParent($this)))
return array('#root' => array('link' => Converter::getClassLink($root->getName(),$package,$root->getPath()), 'parent' => $root->getExtends(),'children' => array()));
else
return array('#root' => array('link' => Converter::getClassLink($root->getName(),$package,$root->getPath()), 'parent' => false, 'children' => array()));
}
}
// special case: parent class is found, but is not part of this package, class has children
if (is_array($root->parent))
{
$x = $root->getParent($this);
if ($x->docblock->package != $package)
{
$v = Converter::getClassLink($root->getName(),$package,$root->getPath());
$my_tree = array('#root' => array('link' => $v, 'parent' => Converter::getClassLink($x->getName(),$x->docblock->package,$x->getPath()), 'children' => array()));
} else
{
}
} else
$my_tree = array('#root' => array('link' => Converter::getClassLink($root->getName(),$package,$root->getPath()), 'parent' => false, 'children' => array()));
// location of tree walker
$cur = '#root';
$lastcur = array(array(false,0));
$childpos = 0;
if (isset($class_children))
{
do
{
if (!$class_children)
{
list($cur, $childpos) = array_pop($lastcur);
if (isset($my_tree[$cur]['children'][$childpos + 1]))
{
array_push($lastcur, array($cur, $childpos + 1));
$par = $cur;
$cur = $my_tree[$cur]['children'][$childpos + 1];
$x = $this->classes->getClassByPackage($cur['class'],$cur['package']);
$childpos = 0;
$cur = $cur['package'] . '#' . $cur['class'];
$my_tree[$cur]['link'] = Converter::getClassLink($x->getName(),$x->docblock->package,$x->getPath());
$my_tree[$cur]['parent'] = $par;
$my_tree[$cur]['children'] = array();
$class_children = $this->classes->getDefiniteChildren($x->getName(), $x->curfile);
continue;
} else
{
$class_children = false;
continue;
}
}
foreach($class_children as $chileclass => $chilefile)
{
$ch = $this->classes->getClass($chileclass,$chilefile);
$my_tree[$cur]['children'][] = array('class' => $ch->getName(), 'package' => $ch->docblock->package);
}
usort($my_tree[$cur]['children'],'rootcmp');
if (isset($my_tree[$cur]['children'][$childpos]))
{
array_push($lastcur, array($cur, $childpos));
$par = $cur;
$cur = $my_tree[$cur]['children'][$childpos];
$x = $this->classes->getClassByPackage($cur['class'],$cur['package']);
$cur = $cur['package'] . '#' . $cur['class'];
$my_tree[$cur]['link'] = Converter::getClassLink($x->getName(),$x->docblock->package,$x->getPath());
$my_tree[$cur]['parent'] = $par;
$my_tree[$cur]['children'] = array();
$childpos = 0;
$class_children = $this->classes->getDefiniteChildren($x->getName(), $x->curfile);
} else
{
list($cur, $childpos) = array_pop($lastcur);
}
} while ($cur);
}
return $my_tree;
}
/**
* do not override
* @return bool true if a link to this class exists in package $package and subpackage $subpackage
* @param string $expr class name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedClass($expr,$package,$subpackage,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['class'][$file][$expr]);
return isset($this->links[$package][$subpackage]['class'][$expr]);
}
/**
* do not override
* @return bool true if a link to this function exists in package $package and subpackage $subpackage
* @param string $expr function name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedFunction($expr,$package,$subpackage,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['function'][$file][$expr]);
return isset($this->links[$package][$subpackage]['function'][$expr]);
}
/**
* do not override
* @return bool true if a link to this define exists in package $package and subpackage $subpackage
* @param string $expr define name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedDefine($expr,$package,$subpackage,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['define'][$file][$expr]);
return isset($this->links[$package][$subpackage]['define'][$expr]);
}
/**
* do not override
* @return bool true if a link to this define exists in package $package and subpackage $subpackage
* @param string $expr define name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedGlobal($expr,$package,$subpackage,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['global'][$file][$expr]);
return isset($this->links[$package][$subpackage]['global'][$expr]);
}
/**
* do not override
* @return bool true if a link to this procedural page exists in package $package and subpackage $subpackage
* @param string $expr procedural page name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedPage($expr,$package,$subpackage,$path=false)
{
if ($path)
return isset($this->linkswithfile[$package][$subpackage]['page'][$path][$expr]);
return isset($this->links[$package][$subpackage]['page'][$expr]);
}
/**
* do not override
* @return bool true if a link to this method exists in package $package, subpackage $subpackage and class $class
* @param string $expr method name
* @param string $class class name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedMethod($expr,$package,$subpackage,$class,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['method'][$file][$class][$expr]);
return isset($this->links[$package][$subpackage]['method'][$class][$expr]);
}
/**
* do not override
* @return bool true if a link to this method exists in package $package, subpackage $subpackage and class $class
* @param string $expr var name
* @param string $class class name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedVar($expr,$package,$subpackage,$class,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['var'][$file][$class][$expr]);
return isset($this->links[$package][$subpackage]['var'][$class][$expr]);
}
/**
* do not override
* @return bool true if a link to this method exists in package $package, subpackage $subpackage and class $class
* @param string $expr constant name
* @param string $class class name
* @param string $package package to search in
* @param string $subpackage subpackage to search in
* @access private
*/
function isLinkedConst($expr,$package,$subpackage,$class,$file=false)
{
if ($file)
return isset($this->linkswithfile[$package][$subpackage]['const'][$file][$class][$expr]);
return isset($this->links[$package][$subpackage]['const'][$class][$expr]);
}
/**
* return false or a {@link classLink} to $expr
* @param string $expr class name
* @param string $package package name
* @return mixed returns a {@link classLink} or false if the element is not found in package $package
* @see classLink
*/
function getClassLink($expr,$package,$file=false, $text = false)
{
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedClass($expr,$package,$subpackage,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['class'][$file][$expr];
}
return $this->links[$package][$subpackage]['class'][$expr];
}
}
return false;
}
/**
* return false or a {@link functionLink} to $expr
* @param string $expr function name
* @param string $package package name
* @return mixed returns a {@link functionLink} or false if the element is not found in package $package
* @see functionLink
*/
function getFunctionLink($expr,$package,$file=false, $text = false)
{
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedFunction($expr,$package,$subpackage,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['function'][$file][$expr];
}
return $this->links[$package][$subpackage]['function'][$expr];
}
}
return false;
}
/**
* return false or a {@link defineLink} to $expr
* @param string $expr constant name
* @param string $package package name
* @return mixed returns a {@link defineLink} or false if the element is not found in package $package
* @see defineLink
*/
function getDefineLink($expr,$package,$file=false, $text = false)
{
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedDefine($expr,$package,$subpackage,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['define'][$file][$expr];
}
return $this->links[$package][$subpackage]['define'][$expr];
}
}
return false;
}
/**
* return false or a {@link globalLink} to $expr
* @param string $expr global variable name (with leading $)
* @param string $package package name
* @return mixed returns a {@link defineLink} or false if the element is not found in package $package
* @see defineLink
*/
function getGlobalLink($expr,$package,$file=false, $text = false)
{
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedGlobal($expr,$package,$subpackage,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['global'][$file][$expr];
}
return $this->links[$package][$subpackage]['global'][$expr];
}
}
return false;
}
/**
* return false or a {@link pageLink} to $expr
* @param string $expr procedural page name
* @param string $package package name
* @return mixed returns a {@link pageLink} or false if the element is not found in package $package
* @see pageLink
*/
function getPageLink($expr,$package,$path = false, $text = false, $packages = false)
{
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedPage($expr,$package,$subpackage,$path))
{
if ($path)
{
return $this->linkswithfile[$package][$subpackage]['page'][$path][$expr];
}
return $this->links[$package][$subpackage]['page'][$expr];
}
}
return false;
}
/**
* return false or a {@link methodLink} to $expr in $class
* @param string $expr method name
* @param string $class class name
* @param string $package package name
* @return mixed returns a {@link methodLink} or false if the element is not found in package $package, class $class
* @see methodLink
*/
function getMethodLink($expr,$class,$package,$file=false, $text = false)
{
$expr = trim($expr);
$class = trim($class);
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedMethod($expr,$package,$subpackage,$class,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['method'][$file][$class][$expr];
}
return $this->links[$package][$subpackage]['method'][$class][$expr];
}
}
return false;
}
/**
* return false or a {@link varLink} to $expr in $class
* @param string $expr var name
* @param string $class class name
* @param string $package package name
* @return mixed returns a {@link varLink} or false if the element is not found in package $package, class $class
* @see varLink
*/
function getVarLink($expr,$class,$package,$file=false, $text = false)
{
$expr = trim($expr);
$class = trim($class);
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedVar($expr,$package,$subpackage,$class,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['var'][$file][$class][$expr];
}
return $this->links[$package][$subpackage]['var'][$class][$expr];
}
}
return false;
}
/**
* return false or a {@link constLink} to $expr in $class
* @param string $expr constant name
* @param string $class class name
* @param string $package package name
* @return mixed returns a {@link varLink} or false if the element is not found in package $package, class $class
* @see constLink
*/
function getConstLink($expr,$class,$package,$file=false, $text = false)
{
$expr = trim($expr);
$class = trim($class);
if (!isset($this->links[$package])) return false;
foreach($this->links[$package] as $subpackage => $notused)
{
if ($this->isLinkedConst($expr,$package,$subpackage,$class,$file))
{
if ($file)
{
return $this->linkswithfile[$package][$subpackage]['const'][$file][$class][$expr];
}
return $this->links[$package][$subpackage]['const'][$class][$expr];
}
}
return false;
}
/**
* The meat of the @tutorial tag and inline {@}tutorial} tag
*
* Take a string and return an abstract link to the tutorial it represents.
* Since tutorial naming literally works like the underlying filesystem, the
* way to reference the tutorial is similar. Tutorials are located in a
* subdirectory of any directory parsed, which is named 'tutorials/' (we
* try to make things simple when we can :). They are further organized by
* package and subpackage as:
*
* tutorials/package/subpackage
*
* and the files are named *.cls, *.pkg, or *.proc, and so a link to a tutorial
* named file.cls can be referenced (depending on context) as any of:
*
* <code>
* * @tutorial package/subpackage/file.cls
* * @tutorial package/file.cls
* * @tutorial file.cls
* </code>
*
* The first case will only be needed if file.cls exists in both the current
* package, in anotherpackage/file.cls and in anotherpackage/subpackage/file.cls
* and you wish to reference the one in anotherpackage/subpackage.
* The second case is only needed if you wish to reference file.cls in another
* package and it is unique in that package. the third will link to the first
* file.cls it finds using this search method:
*
* <ol>
* <li>current package/subpackage</li>
* <li>all other subpackages of current package</li>
* <li>parent package, if this package has classes that extend classes in
* another package</li>
* <li>all other packages</li>
* </ol>
* @return tutorialLink|stringreturns either a link, or the original text, if not found
* @param string the original expression
* @param string package to look in first
* @param string subpackage to look in first
* @param array array of package names to search in if not found in parent packages.
* This is used to limit the search, phpDocumentor automatically searches
* all packages
* @since 1.2
*/
function getTutorialLink($expr, $package = false, $subpackage = false, $packages = false)
{
// is $expr a comma-delimited list?
if (strpos($expr,','))
{
$a = explode(',',$expr);
$b = array();
for($i=0;$i<count($a);$i++)
{
// if so return each component with a link
$b[] = Converter::getTutorialLink(trim($a[$i]));
}
return $b;
}
$subsection = '';
if (strpos($expr,'#'))
{
$a = explode('#',$expr);
$org = $expr;
$expr = $a[0];
$subsection = $a[1];
}
if (strpos($expr,'/'))
{
$a = explode('/',$expr);
if (count($a) == 3)
{
return Converter::getTutorialLink($a[2],$a[0],$a[1],array());
}
if (count($a) == 2)
{
return Converter::getTutorialLink($a[1],$a[0],false,array());
}
}
if (!$package) $package = $this->package;
if (!$subpackage) $subpackage = $this->subpackage;
if (!isset($this->all_packages[$package])) return $expr;
elseif (isset($packages[$package])) unset($packages[$package]);
$ext = pathinfo($expr, PATHINFO_EXTENSION);
if (isset($this->tutorials[$package][$subpackage][$ext][$expr]))
{
$a = $this->tutorials[$package][$subpackage][$ext][$expr];
$link = new tutorialLink;
$link->addLink($subsection,$a->path,$a->name,$a->package,$a->subpackage,$a->getTitle($this,$subsection));
return $link;
}
do
{
if (!is_array($packages))
{
$packages = $this->all_packages;
if (isset($packages[$package])) unset($packages[$package]);
}
if (isset($this->tutorials[$package]))
{
if (isset($this->tutorials[$package][$subpackage][$ext][$expr]))
{
$a = $this->tutorials[$package][$subpackage][$ext][$expr];
$link = new tutorialLink;
$link->addLink($subsection,$a->path,$a->name,$a->package,$a->subpackage,$a->getTitle($this));
return $link;
} else
{
foreach($this->tutorials[$package] as $subpackage => $stuff)
{
if (isset($stuff[$ext][$expr]))
{
$a = $stuff[$ext][$expr];
$link = new tutorialLink;
$link->addLink($subsection,$a->path,$a->name,$a->package,$a->subpackage,$a->getTitle($this));
return $link;
}
}
}
}
// try other packages
// look in parent package first, if found
if (isset($this->package_parents[$package]))
{
$p1 = $package;
$package = $this->package_parents[$package];
} else
{
// no parent package, so start with the first one that's left
list($package,) = @each($packages);
}
if ($package)
{
if (isset($packages[$package])) unset($packages[$package]);
}
} while (count($packages) || $package);
addWarning(PDERROR_TUTORIAL_NOT_FOUND,$expr);
return $expr;
}
/**
* The meat of the @see tag and inline {@}link} tag
*
* $expr is a string with many allowable formats:
* <ol>
* <li>proceduralpagename.ext</li>
* <li>constant_name</li>
* <li>classname::function()</li>
* <li>classname::constantname</li> (new 1.2.4)
* <li>classname::$variablename</li>
* <li>classname</li>
* <li>object classname</li>
* <li>function functionname()</li>
* <li>global $globalvarname</li>
* <li>packagename#expr where expr is any of the above</li>
* </ol>
*
* New in version 1.1, you can explicitly specify a package to link to that
* is different from the current package. Use the # operator
* to specify a new package, as in tests#bug-540368.php (which should appear
* as a link like: "{@link tests#bug-540368.php}"). This
* example links to the procedural page bug-540368.php in package
* tests. Also, the "function" operator is now used to specifically
* link to a function instead of a method in the current class.
*
* <code>
* class myclass
* {
* // from inside the class definition, use "function conflict()" to refer to procedural function "conflict()"
* function conflict()
* {
* }
* }
*
* function conflict()
* {
* }
* </code>
*
* If classname:: is not present, and the see tag is in a documentation
* block within a class, then the function uses the classname to
* search for $expr as a function or variable within classname, or any of its parent classes.
* given an $expr without '$', '::' or '()' getLink first searches for
* classes, procedural pages, constants, global variables, and then searches for
* methods and variables within the default class, and finally for any function
*
* @param string $expr expression to search for a link
* @param string $package package to start searching in
* @param array $packages list of all packages to search in
* @return mixed getLink returns a descendant of {@link abstractLink} if it finds a link, otherwise it returns a string
* @see getPageLink(), getDefineLink(), getVarLink(), getFunctionLink(), getClassLink()
* @see pageLink, functionLink, defineLink, classLink, methodLink, varLink
*/
function &getLink($expr, $package = false, $packages = false)
{
// is $expr a comma-delimited list?
if (strpos($expr,','))
{
$a = explode(',',$expr);
$b = array();
for($i=0;$i<count($a);$i++)
{
// if so return each component with a link
$b[] = Converter::getLink(trim($a[$i]));
}
return $b;
}
if (strpos($expr,'#'))
{
$a = explode('#',$expr);
if (count($a) == 2)
{ // can have exactly 1 package override, otherwise it's ignored
// feature 564991, link to php manual
if ($a[0] == 'PHP_MANUAL') {
$s = 'http://www.php.net/'.$a[1];
return $s;
}
$s = &Converter::getLink($a[1],$a[0],array());
return $s;
}
}
$a = &$this->_getLink($expr, $package, $packages);
return $a;
}
/**
* @access private
*/
function &_getLink($expr, $package = false, $packages = false)
{
if (!$package) $package = $this->package;
//
if (!isset($this->all_packages[$package])) return $expr;
elseif (isset($packages[$package])) unset($packages[$package]);
$links = &$this->links;
$class = $this->class;
if (strpos($expr,'function ') === 0)
{ // asking for a function, not a method
if ($test = Converter::getFunctionLink(str_replace('function ','',str_replace('()','',$expr)), $package)) return $test;
else return $expr;
}
if (strpos($expr,'global ') === 0)
{ // asking for a global variable
if ($test = Converter::getGlobalLink(str_replace('global ','',$expr), $package)) return $test;
else return $expr;
}
if (strpos($expr,'object ') === 0)
{ // asking for a class
if ($test = Converter::getClassLink(str_replace('object ','',$expr), $package)) return $test;
else return $expr;
}
if (strpos($expr,'constant ') === 0)
{ // asking for a class
if ($test = Converter::getDefineLink(str_replace('constant ','',$expr), $package)) return $test;
else return $expr;
}
// are we in a class?
if ($class)
{
// is $expr simply a word? see if it is the class
if (trim($expr) == $class)
{
if ($test = Converter::getClassLink(trim(str_replace('object ','',$expr)),$package)) return $test;
}
// if not, check to see if it is a method or variable of this class tree
if (!strpos($expr,'::'))
{
// if get is neither get() nor $get, assume get is a function, add () to make get()
if (strpos($expr,'$') !== 0 && !strpos($expr,'()')) //$get = $get.'()';
{
if ($a = $this->getLinkMethod($expr,$class,$package)) return $a;
if ($a = $this->getLinkConst($expr,$class,$package)) return $a;
if ($a = $this->getLinkVar('$'.$expr,$class,$package)) return $a;
}
if (strpos($expr,'()')) if ($a = $this->getLinkMethod($expr,$class,$package)) return $a;
if (is_numeric(strpos($expr,'$'))) if ($a = $this->getLinkVar($expr,$class,$package)) return $a;
}
}
if ($test = Converter::getClassLink(trim(str_replace('object ','',$expr)),$package)) return $test;
if ($test = Converter::getPageLink(trim($expr),$package)) return $test;
if ($test = Converter::getDefineLink(trim($expr),$package)) return $test;
if ($test = Converter::getGlobalLink(trim($expr),$package)) return $test;
// if (strpos($expr,'.'))
// package specified
if (!is_array($packages))
{
$packages = $this->all_packages;
}
do
{
if (isset($packages[$package])) unset($packages[$package]);
if ($test = Converter::getClassLink(str_replace('object ','',$expr),$package)) return $test;
if ($test = Converter::getPageLink($expr,$package)) return $test;
if ($test = Converter::getDefineLink($expr,$package)) return $test;
if ($test = Converter::getGlobalLink($expr,$package)) return $test;
// is $expr in class::method() or class::$variable format?
if (strpos($expr,'function ') === 0)
{ // asking for a function, not a method
if ($test = Converter::getFunctionLink(str_replace('function','',str_replace('()','',$expr)), $package)) return $test;
else return $expr;
}
$test = $this->_getDoubleColon($expr, $package, $packages, $class, $links);
if (!is_string($test)) return $test;
if (strpos($test, 'parent::') === 0) return $test;
// $expr does not have ::
if (is_numeric(@strpos('$',$expr)))
{
// default to current class, whose name is contained in $this->render->parent
if ($test = Converter::getVarLink($expr, $class, $package)) return $test;
}
// $expr is a function? (non-method)
if (@strpos($expr,'()'))
{
// otherwise, see if it is a method
if ($class)
{
if ($test = Converter::getMethodLink(str_replace('()','',$expr), $class, $package)) return $test;
}
// extract the function name, use it to retrieve the file that the function is in
// $page = $this->func_page[str_replace('function ','',str_replace('()','',$expr))];
// return the link
if ($test = Converter::getFunctionLink(str_replace('function ','',str_replace('()','',$expr)), $package)) return $test;
}
// $expr is just a word. First, test to see if it is a function of the current package
if ($test = Converter::getFunctionLink(str_replace('function ','',str_replace('()','',$expr)), $package)) return $test;
// try other packages
// look in parent package first, if found
if (isset($this->package_parents[$package]) && in_array($this->package_parents[$package], $packages))
{
$p1 = $package;
$package = $this->package_parents[$package];
if ($package)
{
if (isset($packages[$package])) unset($packages[$package]);
}
continue;
}
// no parent package, so start with the first one that's left
$package = @array_shift(@array_keys($packages));
if ($package && isset($packages[$package]))
{
unset($packages[$package]);
}
} while (count($packages) || $package);
$funcs = get_defined_functions();
// feature 564991, link to php manual
if (in_array(str_replace(array('(',')'),array('',''),$expr),$funcs['internal']))
{
$return = 'http://www.php.net/'.str_replace(array('(',')'),array('',''),$expr);
return $return;
}
// no links found
return $expr;
}
/**
* Split up getLink to make it easier to debug
* @access private
*/
function _getDoubleColon(&$expr, &$package, &$packages, $class, $links)
{
if (@strpos($expr,'::'))
{
$class_method = explode('::',$expr);
if ($class_method[0] == 'parent')
{
// can only have parent in the same package as the class! subtle bug
$package = $this->package;
$packages = array();
$cl = $this->classes->getClassByPackage($class,$package);
if (!$cl)
{ // this is possible if an example file has parent::method()
return $expr;
}
$par = $cl->getParent($this);
$phpparent = false;
if (is_object($par))
{
$package = $par->docblock->package;
$phpparent = $par->getName();
} else
{
addWarning(PDERROR_CLASS_PARENT_NOT_FOUND,$class,$package,$class_method[1]);
return $expr;
}
if ($phpparent) $class_method[0] = $phpparent;
}
if (strpos($class_method[1],'()'))
{
// strip everything but the function name, return a link
if ($test = Converter::getMethodLink(str_replace('()','',$class_method[1]), $class_method[0], $package)) return $test;
}
if ($test = Converter::getVarLink($class_method[1], $class_method[0], $package)) return $test;
if ($test = Converter::getConstLink($class_method[1], $class_method[0], $package)) return $test;
}
return $expr;
}
/**
* cycle through parent classes to retrieve a link to a method
* do not use or override, used by getLink
* @access private
*/
function &getLinkMethod($expr, $class, $package)
{
$links = &$this->links;
do
{
// is $expr in class::method() or class::$variable format?
if (@strpos($expr,'::'))
{
$class_method = explode('::',$expr);
if ($class_method[0] == 'parent')
{
$cl = $this->classes->getClassByPackage($class,$package);
$par = $cl->getParent($this);
$phpparent = false;
if (is_object($par))
{
$package = $par->docblock->package;
$phpparent = $par->getName();
} else addWarning(PDERROR_CLASSPARENT_NOTFOUND,$class,$package,$class_method[1]);
if ($phpparent) $class_method[0] = $phpparent;
} else
{
$cl = $this->classes->getClassByPackage($class,$package);
}
if (strpos($class_method[1],'()'))
{
// strip everything but the function name, return a link
if ($test = Converter::getMethodLink(str_replace('function ','',str_replace('()','',$class_method[1])), $class_method[0], $package)) return $test;
}
}
if ($test = Converter::getMethodLink(str_replace('()','',$expr), $class, $package)) return $test;
$cl = $this->classes->getClassByPackage($class,$package);
if ($cl)
{
$par = $cl->getParent($this);
if (is_object($par))
{
$package = $par->docblock->package;
$class = $par->getName();
} else $class = $par;
} else $class = false;
} while ($class);
// no links found
$flag = false;
return $flag;
}
/**
* cycle through parent classes to retrieve a link to a var
* do not use or override, used by getLink
* @access private
*/
function &getLinkVar($expr, $class, $package)
{
$links = &$this->links;
do
{
// is $expr in class::method() or class::$variable format?
if (@strpos($expr,'::'))
{
$class_method = explode('::',$expr);
if ($class_method[0] == 'parent')
{
$cl = $this->classes->getClassByPackage($class,$package);
$phpparent = false;
$par = $cl->getParent($this);
if (is_object($par))
{
$package = $par->docblock->package;
$phpparent = $par->getName();
} else addWarning(PDERROR_CLASSPARENT_NOTFOUND,$class,$package,$class_method[1]);
if ($phpparent) $class_method[0] = $phpparent;
} else
{
$cl = $this->classes->getClassByPackage($class,$package);
}
if ($test = Converter::getVarLink($class_method[1], $class_method[0], $package)) return $test;
if ($test = Converter::getVarLink('$'.$class_method[1], $class_method[0], $package)) return $test;
}
if ($test = Converter::getVarLink($expr, $class, $package)) return $test;
if ($test = Converter::getVarLink('$'.$expr, $class, $package)) return $test;
$cl = $this->classes->getClassByPackage($class,$package);
if ($cl)
{
$par = $cl->getParent($this);
if (is_object($par))
{
$package = $par->docblock->package;
$class = $par->getName();
} else $class = $par;
} else $class = false;
} while ($class);
// no links found
$class = false;
return $class;
}
/**
* cycle through parent classes to retrieve a link to a class constant
* do not use or override, used by getLink
* @access private
* @since 1.2.4
*/
function &getLinkConst($expr, $class, $package)
{
$links = &$this->links;
do
{
// is $expr in class::method() or class::$variable format?
if (@strpos($expr,'::'))
{
$class_method = explode('::',$expr);
if ($class_method[0] == 'parent')
{
$cl = $this->classes->getClassByPackage($class,$package);
$phpparent = false;
$par = $cl->getParent($this);
if (is_object($par))
{
$package = $par->docblock->package;
$phpparent = $par->getName();
} else addWarning(PDERROR_CLASSPARENT_NOTFOUND,$class,$package,$class_method[1]);
if ($phpparent) $class_method[0] = $phpparent;
} else
{
$cl = $this->classes->getClassByPackage($class,$package);
}
if ($test = Converter::getConstLink($class_method[1], $class_method[0], $package)) return $test;
}
if ($test = Converter::getConstLink($expr, $class, $package)) return $test;
$cl = $this->classes->getClassByPackage($class,$package);
if ($cl)
{
$par = $cl->getParent($this);
if (is_object($par))
{
$package = $par->docblock->package;
$class = $par->getName();
} else $class = $par;
} else $class = false;
} while ($class);
// no links found
$flag = false;
return $flag;
}
/**
* take URL $link and text $text and return a link in the format needed for the Converter
* @param string URL
* @param string text to display
* @return string link to $link
* @abstract
*/
function returnLink($link,$text)
{
}
/**
* take {@link abstractLink} descendant and text $eltext and return a link
* in the format needed for the Converter
* @param abstractLink
* @param string
* @return string link to $element
* @abstract
*/
function returnSee(&$link, $eltext = false)
{
}
/**
* take {@link abstractLink} descendant and text $eltext and return a
* unique ID in the format needed for the Converter
* @param abstractLink
* @return string unique identifier of $element
* @abstract
*/
function getId(&$link)
{
}
/**
* Convert README/INSTALL/CHANGELOG file contents to output format
* @param README|INSTALL|CHANGELOG
* @param string contents of the file
* @abstract
*/
function Convert_RIC($name, $contents)
{
}
/**
* Convert all elements to output format
*
* This will call ConvertXxx where Xxx is {@link ucfirst}($element->type).
* It is expected that a child converter defines a handler for every
* element type, even if that handler does nothing. phpDocumentor will
* terminate with an error if a handler doesn't exist.
* {@internal
* Since 1.2.0 beta 3, this function has been moved from child converters
* to the parent, because it doesn't really make sense to put it in the
* child converter, and we can add error handling.
*
* {@source } }
* @throws {@link PDERROR_NO_CONVERT_HANDLER}
* @param mixed {@link parserElement} descendant or {@link parserPackagePage} or {@link parserData}
*/
function Convert(&$element)
{
$handler = 'convert'.ucfirst($element->type);
if (method_exists($this,$handler))
{
$this->$handler($element);
} else
{
addErrorDie(PDERROR_NO_CONVERTER_HANDLER,$element->type,$handler,phpDocumentor_get_class($this));
}
}
/**#@+
* Conversion Handlers
*
* All of the convert* handlers set up template variables for the Smarty
* template.{@internal In addition, the {@link newSmarty()} method is
* called to retrieve the global Smarty template}}
*/
/**
* Default Tutorial Handler
*
* Sets up the tutorial template, and its prev/next/parent links
* {@internal
* Retrieves the title using {@link parserTutorial::getTitle()} and uses the
* {@link parserTutorial::prev, parserTutorial::next, parserTutorial::parent}
* links to set up those links.}}}
* @param parserTutorial
*/
function &convertTutorial(&$element)
{
$this->package = $element->package;
$this->subpackage = $element->subpackage;
$x = $element->Convert($this);
$template = &$this->newSmarty();
$template->assign('contents',$x);
$template->assign('title',$element->getTitle($this));
$template->assign('nav',$element->parent || $element->Пред || $element->След);
if ($element->parent)
{
$template->assign('up',$this->getId($element->parent));
$template->assign('uptitle',$element->parent->title);
}
if ($element->Пред)
{
$template->assign('prev',$this->getId($element->Пред));
$template->assign('prevtitle',$element->Пред->title);
}
if ($element->След)
{
$template->assign('next',$this->getId($element->След));
$template->assign('nexttitle',$element->След->title);
}
return $template;
}
/**
* Default Class Handler
*
* Sets up the class template.
* {@internal special methods
* {@link generateChildClassList(), generateFormattedClassTree()},
* {@link getFormattedConflicts, getFormattedInheritedMethods},
* and {@link getFormattedInheritedVars} are called to complete vital
* template setup.}}}
*/
function convertClass(&$element)
{
$this->class = $element->getName();
$this->class_data = &$this->newSmarty();
$this->class_data->assign("class_name",$element->getName());
$this->class_data->assign("vars",array());
$this->class_data->assign("methods",array());
$this->class_data->assign("consts",array());
$this->class_data->assign("is_interface", $element->isInterface());
$this->class_data->assign("implements", $this->getFormattedImplements($element));
$this->class_data->assign("package",$element->docblock->package);
$this->class_data->assign("line_number",$element->getLineNumber());
$this->class_data->assign("source_location",$element->getSourceLocation($this));
$this->class_data->assign("page_link",$this->getCurrentPageLink());
$docblock = $this->prepareDocBlock($element, false);
$this->class_data->assign("sdesc",$docblock['sdesc']);
$this->class_data->assign("desc",$docblock['desc']);
$this->class_data->assign("access", $docblock['access']);
$this->class_data->assign("abstract", $docblock['abstract']);
$this->class_data->assign("tags",$docblock['tags']);
$this->class_data->assign("api_tags",$docblock['api_tags']);
$this->class_data->assign("info_tags",$docblock['info_tags']);
$this->class_data->assign("utags",$docblock['utags']);
$this->class_data->assign( "prop_tags", $docblock['property_tags'] );
if ($this->hasSourceCode($element->getPath())) {
$this->class_data->assign("class_slink",$this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true));
}
else
$this->class_data->assign("class_slink",false);
$this->class_data->assign("children", $this->generateChildClassList($element));
$this->class_data->assign("class_tree", $this->generateFormattedClassTree($element));
$this->class_data->assign("conflicts", $this->getFormattedConflicts($element,"classes"));
$inherited_methods = $this->getFormattedInheritedMethods($element);
if (!empty($inherited_methods))
{
$this->class_data->assign("imethods",$inherited_methods);
} else
{
$this->class_data->assign("imethods",false);
}
$inherited_vars = $this->getFormattedInheritedVars($element);
if (!empty($inherited_vars))
{
$this->class_data->assign("ivars",$inherited_vars);
} else
{
$this->class_data->assign("ivars",false);
}
$inherited_consts = $this->getFormattedInheritedConsts($element);
if (!empty($inherited_consts))
{
$this->class_data->assign("iconsts",$inherited_consts);
} else
{
$this->class_data->assign("iconsts",false);
}
}
/**
* Converts method for template output
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* @param parserMethod
*/
function convertMethod(&$element, $additions = array())
{
$fname = $element->getName();
$docblock = $this->prepareDocBlock($element);
$returntype = 'void';
if ($element->isConstructor) $returntype = $element->class;
if ($element->docblock->return)
{
$a = $element->docblock->return->Convert($this);
$returntype = $element->docblock->return->converted_returnType;
}
$params = $param_i = array();
if (count($element->docblock->params))
foreach($element->docblock->params as $param => $val)
{
$a = $val->Convert($this);
$params[] = $param_i[$param] = array("var" => $param,"datatype" => $val->converted_returnType,"data" => $a);
}
if ($element->docblock->hasaccess) {
$acc = $docblock['access'];
} else {
$acc = 'public';
}
if ($this->hasSourceCode($element->getPath()))
$additions["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->class_data->append('methods',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'static' => $docblock['static'],
'abstract' => $docblock['abstract'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'see_tags' => $docblock['see_tags'],
'info_tags_sorted' => $docblock['info_tags_sorted'],
'info_tags' => $docblock['info_tags'],
'utags' => $docblock['utags'],
'constructor' => $element->isConstructor,
'access' => $acc,
'function_name' => $fname,
'function_return' => $returntype,
'function_call' => $element->getFunctionCall(),
'ifunction_call' => $element->getIntricateFunctionCall($this, $param_i),
'descmethod' => $this->getFormattedDescMethods($element),
'method_overrides' => $this->getFormattedOverrides($element),
'method_implements' => $this->getFormattedMethodImplements($element),
'line_number' => $element->getLineNumber(),
'id' => $this->getId($element),
'params' => $params),
$additions));
}
/**
* Converts class variables for template output.
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* @param parserVar
*/
function convertVar(&$element, $additions = array())
{
$docblock = $this->prepareDocBlock($element);
$b = 'mixed';
if ($element->docblock->hasaccess)
$acc = $element->docblock->tags['access'][0]->value;
else
$acc = 'public';
if ($element->docblock->var)
{
$b = $element->docblock->var->converted_returnType;
}
if ($this->hasSourceCode($element->getPath()))
$additions["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->class_data->append('vars',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'static' => $docblock['static'],
'abstract' => $docblock['abstract'],
'utags' => $docblock['utags'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'info_tags' => $docblock['info_tags'],
'var_name' => $element->getName(),
'has_default' => strlen($element->getValue()),
'var_default' => $this->postProcess($element->getValue()),
'var_type' => $b,
'access' => $acc,
'line_number' => $element->getLineNumber(),
'descvar' => $this->getFormattedDescVars($element),
'var_overrides' => $this->getFormattedOverrides($element),
'id' => $this->getId($element)),
$additions));
}
/**
* Converts class constants for template output.
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* @param parserConst
*/
function convertConst(&$element, $additions = array())
{
$docblock = $this->prepareDocBlock($element);
if ($element->docblock->hasaccess)
$acc = $element->docblock->tags['access'][0]->value;
else
$acc = 'public';
if ($this->hasSourceCode($element->getPath()))
$additions["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->class_data->append('consts',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'access' => $docblock['access'],
'abstract' => $docblock['abstract'],
'utags' => $docblock['utags'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'info_tags' => $docblock['info_tags'],
'const_name' => $element->getName(),
'const_value' => $this->postProcess($element->getValue()),
'access' => $acc,
'line_number' => $element->getLineNumber(),
'id' => $this->getId($element)),
$additions));
}
/**
* Default Page Handler
*
* {@internal In addition to setting up the smarty template with {@link newSmarty()},
* this class uses {@link getSourceLocation()} and {@link getClassesOnPage()}
* to set template variables. Also used is {@link getPageName()}, to get
* a Converter-specific name for the page.}}}
* @param parserPage
*/
function convertPage(&$element)
{
$this->page_data = &$this->newSmarty(true);
$this->page = $this->getPageName($element->parent);
$this->path = $element->parent->getPath();
$this->curpage = &$element->parent;
$this->page_data->assign("source_location",$element->parent->getSourceLocation($this));
$this->page_data->assign("functions",array());
$this->page_data->assign("includes",array());
$this->page_data->assign("defines",array());
$this->page_data->assign("globals",array());
$this->page_data->assign("classes",$this->getClassesOnPage($element));
$this->page_data->assign("hasclasses",$element->hasClasses());
$this->page_data->assign("hasinterfaces",$element->hasInterfaces());
$this->page_data->assign("name", $element->parent->getFile());
if ($t = $element->getTutorial())
{
$this->page_data->assign("tutorial",$this->returnSee($t));
} else
{
$this->page_data->assign("tutorial",false);
}
if ($element->docblock)
{
$docblock = $this->prepareDocBlock($element, false);
$this->page_data->assign("sdesc",$docblock['sdesc']);
$this->page_data->assign("desc",$docblock['desc']);
$this->page_data->assign("tags",$docblock['tags']);
$this->page_data->assign("api_tags",$docblock['api_tags']);
$this->page_data->assign("info_tags",$docblock['info_tags']);
$this->page_data->assign("utags",$docblock['utags']);
}
}
/**
* Converts global variables for template output
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* {@internal
* In addition to using {@link prepareDocBlock()}, this method also
* uses utility functions {@link getGlobalValue(), getFormattedConflicts()}}}}
* @param parserGlobal
* @uses postProcess() on global_value template value, makes it displayable
* @param array any additional template variables should be in this array
*/
function convertGlobal(&$element, $addition = array())
{
$docblock = $this->prepareDocBlock($element);
$value = $this->getGlobalValue($element->getValue());
if ($this->hasSourceCode($element->getPath()))
$addition["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->page_data->append('globals',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'info_tags' => $docblock['info_tags'],
'utags' => $docblock['utags'],
'global_name' => $element->getName(),
'global_type' => $element->getDataType($this),
'global_value' => $value,
'line_number' => $element->getLineNumber(),
'global_conflicts' => $this->getFormattedConflicts($element,"global variables"),
'id' => $this->getId($element)),
$addition));
}
/**
* Converts defines for template output
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* {@internal
* In addition to using {@link prepareDocBlock()}, this method also
* uses utility functions {@link getGlobalValue(), getFormattedConflicts()}}}}
* @param parserDefine
* @uses postProcess() on define_value template value, makes it displayable
* @param array any additional template variables should be in this array
*/
function convertDefine(&$element, $addition = array())
{
$docblock = $this->prepareDocBlock($element);
if ($this->hasSourceCode($element->getPath()))
$addition["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->page_data->append('defines',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'info_tags' => $docblock['info_tags'],
'utags' => $docblock['utags'],
'define_name' => $element->getName(),
'line_number' => $element->getLineNumber(),
'define_value' => $this->postProcess($element->getValue()),
'define_conflicts' => $this->getFormattedConflicts($element,"defines"),
'id' => $this->getId($element)),
$addition));
}
/**
* Converts includes for template output
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* @see prepareDocBlock()
* @param parserInclude
*/
function convertInclude(&$element, $addition = array())
{
$docblock = $this->prepareDocBlock($element);
$per = $this->getIncludeValue($element->getValue(), $element->getPath());
if ($this->hasSourceCode($element->getPath()))
$addition["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->page_data->append('includes',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'info_tags' => $docblock['info_tags'],
'utags' => $docblock['utags'],
'include_name' => $element->getName(),
'line_number' => $element->getLineNumber(),
'include_value' => $per),
$addition));
}
/**
* Converts function for template output
*
* This function must be called by a child converter with any extra
* template variables needed in the parameter $addition
* @see prepareDocBlock()
* @param parserFunction
*/
function convertFunction(&$element, $addition = array())
{
$docblock = $this->prepareDocBlock($element);
$fname = $element->getName();
$params = $param_i = array();
if (count($element->docblock->params))
foreach($element->docblock->params as $param => $val)
{
$a = $val->Convert($this);
$params[] = $param_i[$param] = array("var" => $param,"datatype" => $val->converted_returnType,"data" => $a);
}
$returntype = 'void';
if ($element->docblock->return)
{
$a = $element->docblock->return->Convert($this);
$returntype = $element->docblock->return->converted_returnType;
}
if ($this->hasSourceCode($element->getPath()))
$addition["slink"] = $this->getSourceAnchor($element->getPath(),$element->getLineNumber(),$element->getLineNumber(),true);
$this->page_data->append('functions',array_merge(
array('sdesc' => $docblock['sdesc'],
'desc' => $docblock['desc'],
'tags' => $docblock['tags'],
'api_tags' => $docblock['api_tags'],
'info_tags' => $docblock['info_tags'],
'utags' => $docblock['utags'],
'function_name' => $fname,
'function_return' => $returntype,
'function_conflicts' => $this->getFormattedConflicts($element,"functions"),
'ifunction_call' => $element->getIntricateFunctionCall($this, $param_i),
'function_call' => $element->getFunctionCall(),
'line_number' => $element->getLineNumber(),
'id' => $this->getId($element),
'params' => $params),
$addition));
}
/**#@-*/
/**
* convert the element's DocBlock for output
*
* This function converts all tags and descriptions for output
* @param mixed any descendant of {@link parserElement}, or {@link parserData}
* @param array used to translate tagnames into other tags
* @param boolean set to false for pages and classes, the only elements allowed to specify @package
* @return array
*
* Format:
* <pre>
* array('sdesc' => DocBlock summary
* 'desc' => DocBlock detailed description
* 'tags' => array('keyword' => tagname, 'data' => tag description)
* known tags
* 'api_tags' => array('keyword' => tagname, 'data' => tag description)
* known api documentation tags
* 'info_tags' => array('keyword' => tagname, 'data' => tag description)
* known informational tags
* [ 'utags' => array('keyword' => tagname, 'data' => tag description
* unknown tags ]
* [ 'vartype' => type from @var/@return tag ]
* [ 'var_descrip' => description from @var/@return tag ]
* )
* </pre>
*/
function prepareDocBlock(&$element, $names = array(),$nopackage = true)
{
$tagses = $element->docblock->listTags();
$tags = $ret = $api_tags = $info_tags = array();
$api_tags_arr = array("abstract", "access", "deprecated", "example", "filesource",
"global", "internal", "name", "return", "see",
"property", "property-read", "property-write", "method",
"staticvar", "usedby", "uses", "var");
if (!$nopackage)
{
$tags[] = array('keyword' => 'package','data' => $element->docblock->package);
if (!empty($element->docblock->subpackage)) $tags[] = array('keyword' => 'subpackage','data' => $element->docblock->subpackage);
}
if ($element->docblock->var)
{
$a = $element->docblock->var->Convert($this);
$ret['vartype'] = $element->docblock->var->converted_returnType;
if (!empty($a))
{
$tags[] = array('keyword' => 'var', 'data' => $a);
$ret["var_descrip"] = $a;
}
}
if ($element->docblock->return)
{
$a = $element->docblock->return->Convert($this);
$ret['vartype'] = $element->docblock->return->converted_returnType;
if (!empty($a))
{
$tags[] = $api_tags[] = array('keyword' => 'return', 'data' => $a);
$ret["var_descrip"] = $a;
}
}
if ($element->docblock->funcglobals)
foreach($element->docblock->funcglobals as $global => $val)
{
if ($a = $this->getGlobalLink($global,$element->docblock->package))
{
$global = $a;
}
$b = Converter::getLink($val[0]);
if (is_object($b) && phpDocumentor_get_class($b) == 'classlink')
{
$val[0] = $this->returnSee($b);
}
$tags[] = $api_tags[] = array('keyword' => 'global','data' => $val[0].' '.$global.': '.$val[1]->Convert($this));
}
if ($element->docblock->statics)
foreach($element->docblock->statics as $static => $val)
{
$a = $val->Convert($this);
$tags[] = $api_tags[] = array('keyword' => 'staticvar','data' => $val->converted_returnType.' '.$static.': '.$a);
}
$property_tags = array();
foreach ( $element->docblock->properties as $prop_name => $val )
{
$a = $val->Convert( $this );
if ( !empty( $a ) )
{
$tags[] = $api_tags[] = array( 'keyword' => $val->keyword ,
'data' => $val->converted_returnType . ' ' . $prop_name . ': ' . $a );
$prop['prop_name'] = $prop_name;
$prop['access'] = $val->keyword == 'property-read' ? 'read' :
( $val->keyword == 'property-write' ? 'write' : 'read/write' );
$prop['prop_type'] = $val->converted_returnType;
$prop['sdesc'] = $a;
$property_tags[ $prop_name ] = $prop;
}
}
ksort( $property_tags, SORT_STRING );
$property_tags = array_values( $property_tags );
$info_tags_sorted = array();
$ret['static'] = false;
foreach($tagses as $tag)
{
if (isset($names[$tag->keyword])) $tag->keyword = $names[$tag->keyword];
if ($tag->keyword == 'static') {
$ret['static'] = true;
continue;
}
if ($tag->keyword)
$tags[] = array("keyword" => $tag->keyword,"data" => $tag->Convert($this));
if (in_array($tag->keyword, $api_tags_arr)) {
$api_tags[] = array("keyword" => $tag->keyword,"data" => $tag->Convert($this));
} else {
$info_tags[] = array("keyword" => $tag->keyword,"data" => $tag->Convert($this));
@list( $className, $desc ) = explode( " ", $tag->Convert($this), 2 );
$info_tags_sorted[ $tag->keyword ][] = array( 'keyword' => $className, 'data' => $desc );
}
}
$utags = array();
foreach($element->docblock->unknown_tags as $keyword => $tag)
{
foreach($tag as $t)
$utags[] = array('keyword' => $keyword, 'data' => $t->Convert($this));
}
$ret['abstract'] = false;
$ret['access'] = 'public';
$see_tags = array();
foreach($tags as $tag)
{
if ($tag['keyword'] == 'access') {
$ret['access'] = $tag['data'];
}
if ($tag['keyword'] == 'abstract') {
$ret['abstract'] = true;
}
if ($tag['keyword'] == 'see' || $tag['keyword'] == 'uses' ||
$tag['keyword'] == 'usedby') {
$see_tags[] = $tag['data'];
}
}
$ret['sdesc'] = $element->docblock->getSDesc($this);
$ret['desc'] = $element->docblock->getDesc($this);
$ret['tags'] = $tags;
$ret['see_tags'] = $see_tags;
$ret['info_tags_sorted'] = $info_tags_sorted;
$ret['api_tags'] = $api_tags;
$ret['info_tags'] = $info_tags;
$ret['utags'] = $utags;
$ret['property_tags'] = $property_tags;
return $ret;
}
/**
* gets a list of all classes declared on a procedural page represented by
* $element, a {@link parserData} class
* @param parserData &$element
* @return array links to each classes documentation
*
* Format:
* <pre>
* array('name' => class name,
* 'sdesc' => summary of the class
* 'link' => link to the class's documentation)
* </pre>
*/
function getClassesOnPage(&$element)
{
global $_phpDocumentor_setting;
$a = $element->getClasses($this);
$classes = array();
foreach($a as $package => $clas)
{
if (!empty($_phpDocumentor_setting['packageoutput']))
{
$packages = explode(',',$_phpDocumentor_setting['packageoutput']);
if (!in_array($package, $packages)) continue;
}
for($i=0; $i<count($clas); $i++)
{
if ($this->parseprivate || ! ($clas[$i]->docblock && $clas[$i]->docblock->hasaccess && $clas[$i]->docblock->tags['access'][0]->value == 'private'))
{
$sdesc = '';
$r = array();
$sdesc = $clas[$i]->docblock->getSDesc($this);
if ($clas[$i]->docblock->hasaccess)
$r['access'] = $clas[$i]->docblock->tags['access'][0]->value;
else
$r['access'] = 'public';
if (isset ($clas[$i]->docblock->tags['abstract']))
$r['abstract'] = TRUE;
else
$r['abstract'] = FALSE;
$r['name'] = $clas[$i]->getName();
$r['sdesc'] = $sdesc;
$r['link'] = $this->getClassLink($clas[$i]->getName(),$package,$clas[$i]->getPath());
$classes[] = $r;
}
}
}
return $classes;
}
/**
* returns an array containing the class inheritance tree from the root
* object to the class.
*
* This method must be overridden, or phpDocumentor will halt with a fatal
* error
* @return string Converter-specific class tree for an individual class
* @param parserClass class variable
* @abstract
*/
function generateFormattedClassTree($class)
{
addErrorDie(PDERROR_CONVERTER_OVR_GFCT,phpDocumentor_get_class($this));
}
/**
* returns an array containing the class inheritance tree from the root
* object to the class.
*
* This method must be overridden, or phpDocumentor will halt with a fatal
* error
* @return string Converter-specific class tree for an individual class
* @param parserClass class variable
* @abstract
*/
function getFormattedImplements($el)
{
$ret = array();
foreach ($el->getImplements() as $interface)
{
$link = $this->getLink($interface);
if ($link && is_object($link)) {
$ret[] = $this->returnSee($link);
} else {
if (class_exists('ReflectionClass')) {
if (interface_exists($interface)) {
$inter = new ReflectionClass($interface);
if ($inter->isInternal()) {
$ret[] = $interface . ' (internal interface)';
} else {
$ret[] = $interface;
}
}
} else {
$ret[] = $interface;
}
}
}
return $ret;
}
/**
* @param mixed {@link parserClass, parserFunction, parserDefine} or
* {@link parserGlobal}
* @param string type to display. either 'class','function','define'
* or 'global variable'
* @return array links to conflicting elements, or empty array
* @uses parserClass::getConflicts()
* @uses parserFunction::getConflicts()
* @uses parserDefine::getConflicts()
* @uses parserGlobal::getConflicts()
*/
function getFormattedConflicts(&$element,$type)
{
$conflicts = $element->getConflicts($this);
$r = array();
if (!$conflicts) return false;
foreach($conflicts as $package => $class)
{
$r[] = $class->getLink($this,$class->docblock->package);
}
if (!empty($r)) $r = array('conflicttype' => $type, 'conflicts' => $r);
return $r;
}
/**
* Get a list of methods in child classes that override this method
* @return array empty array or array(array('link'=>link to method,
* 'sdesc'=>short description of the method),...)
* @uses parserMethod::getOverridingMethods()
* @param parserMethod
*/
function getFormattedDescMethods(&$element)
{
$meths = $element->getOverridingMethods($this);
$r = array();
for($i=0; $i<count($meths); $i++)
{
$ms = array();
$ms['link'] = $meths[$i]->getLink($this);
$ms['sdesc'] = $meths[$i]->docblock->getSDesc($this);
$r[] = $ms;
}
return $r;
}
/**
* Get a list of vars in child classes that override this var
* @return array empty array or array('link'=>link to var,
* 'sdesc'=>short description of the method
* @uses parserVar::getOverridingVars()
* @param parserVar
*/
function getFormattedDescVars(&$element)
{
$vars = $element->getOverridingVars($this);
$r = array();
for($i=0; $i<count($vars); $i++)
{
$vs = array();
$vs['link'] = $vars[$i]->getLink($this);
$vs['sdesc'] = $vars[$i]->docblock->getSDesc($this);
$r[] = $vs;
}
return $r;
}
/**
* Get the method this method overrides, if any
* @return array|falsearray('link'=>link to overridden method,
* 'sdesc'=>short description
* @see parserMethod::getOverrides()
* @param parserMethod
*/
function getFormattedOverrides(&$element)
{
$ovr = $element->getOverrides($this);
if (!$ovr) return false;
$sdesc = $ovr->docblock->getSDesc($this);
$name = method_exists($ovr, 'getFunctionCall') ? $ovr->getFunctionCall() : $ovr->getName();
$link = ($link = $ovr->getLink($this)) ? $link : $ovr->getClass() . '::' . $name;
return array('link' => $link,'sdesc' => $sdesc);
}
/**
* Get the method this method(s) implemented from an interface, if any
* @return array|falsearray('link'=>link to implemented method,
* 'sdesc'=>short description
* @uses parserMethod::getImplements()
* @param parserMethod
*/
function getFormattedMethodImplements(&$element)
{
$ovr = $element->getImplements($this);
if (!$ovr) return false;
$ret = array();
foreach ($ovr as $impl) {
$sdesc = $impl->docblock->getSDesc($this);
$name = $impl->getName();
$link = ($link = $impl->getLink($this)) ? $link : $impl->getClass() . '::' . $name;
$ret[] = array('link' => $link,'sdesc' => $sdesc);
}
return $ret;
}
/**
* returns a list of child classes
*
* @param parserClass class variable
* @uses parserClass::getChildClassList()
*/
function generateChildClassList($class)
{
$kids = $class->getChildClassList($this);
$list = array();
if (count($kids))
{
for($i=0; $i<count($kids); $i++)
{
$lt['link'] = $kids[$i]->getLink($this);
$lt['sdesc'] = $kids[$i]->docblock->getSDesc($this);
if ($kids[$i]->docblock->hasaccess)
$lt['access'] = $kids[$i]->docblock->tags['access'][0]->value;
else
$lt['access'] = 'public';
$lt['abstract'] = isset ($kids[$i]->docblock->tags['abstract'][0]);
$list[] = $lt;
}
} else return false;
return $list;
}
/**
* Return template-enabled list of inherited variables
*
* uses parserVar helper function getInheritedVars and generates a
* template-enabled list using getClassLink()
* @param parserVar $child class var
* @see getClassLink(), parserVar::getInheritedVars()
* @return array Format:
* <pre>
* array(
* array('parent_class' => link to parent class's documentation,
* 'ivars' =>
* array(
* array('name' => inherited variable name,
* 'link' => link to inherited variable's documentation,
* 'default' => default value of inherited variable,
* 'sdesc' => summary of inherited variable),
* ...),
* ...)
* </pre>
*/
function getFormattedInheritedVars($child)
{
$package = $child->docblock->package;
$subpackage = $child->docblock->subpackage;
$ivars = $child->getInheritedVars($this);
$results = array();
if (!count($ivars)) return $results;
foreach($ivars as $parent => $vars)
{
$file = $vars['file'];
$vars = $vars['vars'];
$par = $this->classes->getClass($parent,$file);
if ($par) {
$package = $par->docblock->package;
}
usort($vars,array($this,"sortVar"));
$result['parent_class'] = $this->getClassLink($parent, $package);
if (!$result['parent_class']) {
$result['parent_class'] = $parent . ' (Internal Class)';
}
foreach($vars as $var)
{
$info = array();
if ($var->docblock->hasaccess) {
$info['access'] = $var->docblock->tags['access'][0]->value;
} else {
$info['access'] = 'public';
}
$info['abstract'] = isset ($var->docblock->tags['abstract'][0]);
$info['name'] = $var->getName();
$info['link'] = $var->getLink($this);
if (!$info['link']) {
$info['link'] = $info['name'];
}
$info['default'] = $this->postProcess($var->getValue());
if ($var->docblock)
$info['sdesc'] = $var->docblock->getSDesc($this);
$result["ivars"][] = $info;
}
$results[] = $result;
$result = array();
}
return $results;
}
/**
* Return template-enabled list of inherited methods
*
* uses parserMethod helper function getInheritedMethods and generates a
* template-enabled list using getClassLink()
* @param parserMethod $child class method
* @see getClassLink(), parserMethod::getInheritedMethods()
* @return array Format:
* <pre>
* array(
* array('parent_class' => link to parent class's documentation,
* 'ivars' =>
* array(
* array('name' => inherited variable name,
* 'link' => link to inherited variable's documentation,
* 'function_call' => {@link parserMethod::getIntricateFunctionCall()}
* returned array,
* 'sdesc' => summary of inherited variable),
* ...),
* ...)
* </pre>
*/
function getFormattedInheritedMethods($child)
{
$package = $child->docblock->package;
$subpackage = $child->docblock->subpackage;
$imethods = $child->getInheritedMethods($this);
$results = array();
if (!count($imethods)) return $results;
foreach($imethods as $parent => $methods)
{
$file = $methods['file'];
$methods = $methods['methods'];
$par = $this->classes->getClass($parent,$file);
if ($par) {
$package = $par->docblock->package;
}
usort($methods,array($this,"sortMethod"));
$result['parent_class'] = $this->getClassLink($parent,$package);
if (!$result['parent_class']) {
$result['parent_class'] = $parent . ' (Internal Class)';
}
foreach($methods as $method)
{
$info = array();
if ($method->docblock->hasaccess) {
$info['access'] = $method->docblock->tags['access'][0]->value;
} else {
$info['access'] = 'public';
}
$info['abstract'] = isset ($method->docblock->tags['abstract'][0]);
if ($method->isConstructor) $info['constructor'] = 1;
$returntype = 'void';
if ($method->isConstructor) {
$returntype = $method->getClass();
}
if ($method->docblock->return) {
$a = $method->docblock->return->Convert($this);
$returntype = $method->docblock->return->converted_returnType;
}
$info['function_return'] = $returntype;
$info['static'] = isset ($method->docblock->tags['static'][0]);
$info['link'] = $method->getLink($this);
if (!$info['link']) {
$info['link'] = $method->getFunctionCall();
}
$info['name'] = $method->getName();
if ($method->docblock)
$info['sdesc'] = $method->docblock->getSDesc($this);
$params = array();
if (count($method->docblock->params))
foreach($method->docblock->params as $param => $val)
{
$a = $val->Convert($this);
$params[$param] = array("var" => $param,"datatype" => $val->converted_returnType,"data" => $a);
}
$info['function_call'] = $method->getIntricateFunctionCall($this,$params);
$result["imethods"][] = $info;
}
$results[] = $result;
$result = array();
}
return $results;
}
/**
* Return template-enabled list of inherited class constants
*
* uses parserConst helper function getInheritedConsts and generates a
* template-enabled list using getClassLink()
* @param parserConst $child class constant
* @see getClassLink(), parserMethod::getInheritedConsts()
* @return array Format:
* <pre>
* array(
* array('parent_class' => link to parent class's documentation,
* 'ivars' =>
* array(
* array('name' => inherited constant name,
* 'link' => link to inherited constant's documentation,
* 'value' => constant value,
* 'sdesc' => summary of inherited constant),
* ...),
* ...)
* </pre>
*/
function getFormattedInheritedConsts($child)
{
$package = $child->docblock->package;
$subpackage = $child->docblock->subpackage;
$ivars = $child->getInheritedConsts($this);
$results = array();
if (!count($ivars)) return $results;
foreach($ivars as $parent => $vars)
{
$file = $vars['file'];
$vars = $vars['consts'];
$par = $this->classes->getClass($parent,$file);
if ($par) {
$package = $par->docblock->package;
}
usort($vars,array($this,"sortVar"));
$result['parent_class'] = $this->getClassLink($parent,$package);
if (!$result['parent_class']) {
$result['parent_class'] = $parent . ' (Internal Class)';
}
foreach($vars as $var)
{
$info = array();
if ($var->docblock->hasaccess) {
$info['access'] = $var->docblock->tags['access'][0]->value;
} else {
$info['access'] = 'public';
}
$info['name'] = $var->getName();
$info['link'] = $var->getLink($this);
if (!$info['link']) {
$info['link'] = $info['name'] . ' = ' . $var->getValue();
}
$info['value'] = $this->postProcess($var->getValue());
if ($var->docblock)
$info['sdesc'] = $var->docblock->getSDesc($this);
$result["iconsts"][] = $info;
}
$results[] = $result;
$result = array();
}
return $results;
}
/**
* Return a Smarty template object to operate with
*
* This returns a Smarty template with pre-initialized variables for use.
* If the method "SmartyInit()" exists, it is called.
* @return Smarty
*/
function &newSmarty()
{
$templ = new Smarty;
$templ->use_sub_dirs = false;
$templ->template_dir = realpath($this->smarty_dir . PATH_DELIMITER . 'templates');
$templatename = get_class($this) . $this->templateName;
if (!file_exists($this->targetDir . DIRECTORY_SEPARATOR . md5($templatename))) {
// we'll delete this on finishing conversion
$this->_compiledDir[$this->targetDir . DIRECTORY_SEPARATOR . md5($templatename)] = 1;
mkdir($this->targetDir . DIRECTORY_SEPARATOR . md5($templatename),0775);
}
$templ->compile_dir = realpath($this->targetDir . PATH_DELIMITER . md5($templatename));
$templ->config_dir = realpath($this->smarty_dir . PATH_DELIMITER . 'configs');
$templ->assign("date",date("r",time()));
$templ->assign("maintitle",$this->title);
$templ->assign("package",$this->package);
$templ->assign("phpdocversion",PHPDOCUMENTOR_VER);
$templ->assign("phpdocwebsite",PHPDOCUMENTOR_WEBSITE);
$templ->assign("subpackage",$this->subpackage);
if (method_exists($this,'SmartyInit')) return $this->SmartyInit($templ);
return $templ;
}
/**
* Finish up parsing/cleanup directories
*/
function cleanup()
{
foreach ($this->_compiledDir as $dir => $one) {
$this->_rmdir($dir);
}
}
/**
* Completely remove a directory and its contents
*
* @param string $directory
*/
function _rmdir($directory)
{
$handle = @opendir($directory);
if ($handle) {
while (false !== ($file = readdir($handle))) {
if ($file == '.' || $file == '..') {
continue;
}
if (is_dir($directory . DIRECTORY_SEPARATOR . $file)) {
$this->_rmdir($directory . DIRECTORY_SEPARATOR . $file);
}
@unlink($directory . DIRECTORY_SEPARATOR . $file);
}
closedir($handle);
@rmdir($directory);
}
}
/**
* do all necessary output
* @see Converter
* @abstract
*/
function Output($title)
{
phpDocumentor_out("WARNING: Generic Converter::Output was used, no output will be generated");
}
/**
* Set the template directory with a different template base directory
* @tutorial phpDocumentor.howto.pkg#using.command-line.templatebase
* @param string template base directory
* @param string template name
*/
function setTemplateBase($base, $dir)
{
// remove trailing /'s from the base path, if any
$base = str_replace('\\','/',$base);
while ($base{strlen($base) - 1} == '/') $base = substr($base,0,strlen($base) - 1);
$this->templateName = substr($dir,0,strlen($dir) - 1);
$this->templateDir = $base . "/Converters/" . $this->outputformat . "/" . $this->name . "/templates/" . $dir;
if (!is_dir($this->templateDir))
{
addErrorDie(PDERROR_TEMPLATEDIR_DOESNT_EXIST, $this->templateDir);
}
$this->smarty_dir = $this->templateDir;
if (file_exists($this->templateDir . PATH_DELIMITER . 'options.ini'))
{
// retrieve template options, allow array creation
$this->template_options = phpDocumentor_parse_ini_file($this->templateDir . PATH_DELIMITER . 'options.ini',true);
}
}
/**
* sets the template directory based on the {@link $outputformat} and {@link $name}
* Also sets {@link $templateName} to the $dir parameter
* @param string subdirectory
*/
function setTemplateDir($dir)
{
if ('@DATA-DIR@' != '@'.'DATA-DIR@') {
$templateBase = str_replace('\\', '/', '@DATA-DIR@/PhpDocumentor/phpDocumentor');
} else {
$templateBase = str_replace('\\','/',$GLOBALS['_phpDocumentor_install_dir']) . '/phpDocumentor';
}
$this->setTemplateBase($templateBase, $dir);
}
/**
* Get the absolute path to the converter's base directory
* @return string
*/
function getConverterDir()
{
if ('@DATA-DIR@' != '@' . 'DATA-DIR@') {
return str_replace('\\', '/', "@DATA-DIR@/PhpDocumentor/phpDocumentor/Converters/") . $this->outputformat . "/" . $this->name;
} else {
return str_replace('\\','/',$GLOBALS['_phpDocumentor_install_dir']) ."/phpDocumentor/Converters/" . $this->outputformat . "/" . $this->name;
}
}
/**
* Parse a global variable's default value for class initialization.
*
* If a global variable's default value is "new class" as in:
* <code>
* $globalvar = new Parser
* </code>
* This method will document it not as "new Parser" but instead as
* "new {@link Parser}". For examples, see {@link phpdoc.inc}.
* Many global variables are classes, and phpDocumentor links to their
* documentation
* @return string default global variable value with link to class if
* it's "new Class"
* @param string default value of a global variable.
*/
function getGlobalValue($value)
{
if (strpos($value,'new') === 0)
{
preg_match('/new([^(]*)((?:.|\r|\n)*)/',$value,$newval);
if (isset($newval[1]))
{
$a = Converter::getLink(trim($newval[1]));
if (!isset($newval[2])) $newval[2] = '';
if ($a && phpDocumentor_get_class($a) == 'classlink') $value = 'new '.$this->returnSee($a) .
$this->postProcess($newval[2]);
}
return $value;
}
return $this->postProcess($value);
}
/**
* Parse an include's file to see if it is a file documented in this project
*
* Although not very smart yet, this method will try to look for the
* included file file.ext:
*
* <code>
* include ("file.ext");
* </code>
*
* If it finds it, it will return a link to the file's documentation. As of
* 1.2.0rc1, phpDocumentor is smarty enough to find these cases:
* <ul>
* <li>absolute path to file</li>
* <li>./file.ext or ../file.ext</li>
* <li>relpath/to/file.ext if relpath is a subdirectory of the base parse
* directory</li>
* </ul>
* For examples, see {@link Setup.inc.php} includes.
* Every include auto-links to the documentation for the file that is included
* @return string included file with link to docs for file, if found
* @param string file included by include statement.
* @param string path of file that has the include statement
*/
function getIncludeValue($value, $ipath)
{
preg_match('/"([^"\']*\.[^"\']*)"/',$value,$match);
if (!isset($match[1]))
preg_match('/\'([^"\']*\.[^"\']*)\'/',$value,$match);
if (isset($match[1]))
{
$fancy_per = $this->proceduralpages->pathMatchesParsedFile($match[1],$ipath);
if ($fancy_per)
{
$link = $this->addLink($fancy_per);
if (is_object($link) && phpDocumentor_get_class($link) == 'pagelink' &&
isset($this->all_packages[$link->package]))
{
$value = $this->returnSee($link,$value);
}
} else
{
$per = Converter::getLink($match[1]);
if (is_object($per) && phpDocumentor_get_class($per) == 'pagelink')
$value = $this->returnSee($per);
}
}
return $value;
}
/**
* Recursively creates all subdirectories that don't exist in the $dir path
* @param string $dir
*/
function createParentDir($dir)
{
if (empty($dir)) return;
$tmp = explode(SMART_PATH_DELIMITER,$dir);
array_pop($tmp);
$parent = implode(SMART_PATH_DELIMITER,$tmp);
if ($parent != '' && !file_exists($parent))
{
$test = @mkdir($parent,0775);
if (!$test)
{
$this->createParentDir($parent);
$test = @mkdir($parent,0775);
phpDocumentor_out("Creating Parent Directory $parent\n");
} else
{
phpDocumentor_out("Creating Parent Directory $parent\n");
}
}
}
/**
* Sets the output directory for generated documentation
*
* As of 1.3.0RC6, this also sets the compiled templates directory inside
* the target directory
* @param string $dir the output directory
*/
function setTargetDir($dir)
{
if (strlen($dir) > 0)
{
$this->targetDir = $dir;
// if directory does exist create it, this should have more error checking in the future
if (!file_exists($dir))
{
$tmp = str_replace(array("/","\\"),SMART_PATH_DELIMITER,$dir);
if (substr($tmp,-1) == SMART_PATH_DELIMITER)
{
$tmp = substr($tmp,0,(strlen($tmp)-1));
}
$this->createParentDir($tmp);
phpDocumentor_out("Creating Directory $dir\n");
mkdir($dir,0775);
} elseif (!is_dir($dir))
{
echo "Output path: '$dir' is not a directory\n";
die();
}
} else {
echo "a target directory must be specified\n try phpdoc -h\n";
die();
}
}
/**
* Writes a file to target dir
* @param string
* @param string
* @param boolean true if the data is binary and not text
*/
function writeFile($file,$data,$binary = false)
{
if (!file_exists($this->targetDir))
{
mkdir($this->targetDir,0775);
}
$string = '';
if ($binary) $string = 'binary file ';
phpDocumentor_out(" Writing $string".$this->targetDir . PATH_DELIMITER . $file . "\n");
flush();
$write = 'w';
if ($binary) $write = 'wb';
$fp = fopen($this->targetDir . PATH_DELIMITER . $file,$write);
set_file_buffer( $fp, 0 );
fwrite($fp,$data,strlen($data));
fclose($fp);
}
/**
* Copies a file from the template directory to the target directory
* thanks to Robert Hoffmann for this fix
* @param string
*/
function copyFile($file, $subdir = '')
{
if (!file_exists($this->targetDir))
{
mkdir($this->targetDir,0775);
}
copy($this->templateDir . $subdir . PATH_DELIMITER . $file, $this->targetDir . PATH_DELIMITER . $file);
}
/**
* Return parserStringWithInlineTags::Convert() cache state
* @see parserStringWithInlineTags::Convert()
* @abstract
*/
function getState()
{
return true;
}
/**
* Compare parserStringWithInlineTags::Convert() cache state to $state
* @param mixed
* @see parserStringWithInlineTags::Convert()
* @abstract
*/
function checkState($state)
{
return true;
}
}
/**
* @access private
* @see Converter::getSortedClassTreeFromClass()
*/
function rootcmp($a, $b)
{
return strnatcasecmp($a['class'],$b['class']);
}
/**
* @access private
* @global string used to make the first tutorials converted the default package tutorials
*/
function tutorialcmp($a, $b)
{
global $phpDocumentor_DefaultPackageName;
if ($a == $phpDocumentor_DefaultPackageName) return -1;
if ($b == $phpDocumentor_DefaultPackageName) return 1;
return strnatcasecmp($a, $b);
}
/**
* smart htmlentities, doesn't entity the allowed tags list
* Since version 1.1, this function uses htmlspecialchars instead of
* htmlentities, for international support
* This function has been replaced by functionality in {@link ParserDescCleanup.inc}
* @param string $s
* @return string browser-displayable page
* @deprecated As of v1.2, No longer needed, as valid tags are parsed out of the source,
* and everything else is {@link Converter::postProcess()} handled
*/
function adv_htmlentities($s)
{
return;
global $phpDocumentor___html,$_phpDocumentor_html_allowed;
$result = htmlspecialchars($s);
$entities = array_flip(get_html_translation_table(HTML_SPECIALCHARS));
$result = strtr($result,$phpDocumentor___html);
$matches = array();
preg_match_all('/(<img.*>)/U',$result,$matches);
for($i=0;$i<count($matches[1]);$i++)
{
$result = str_replace($matches[1][$i],strtr($matches[1][$i],array_flip(get_html_translation_table(HTML_SPECIALCHARS))),$result);
}
preg_match_all('/(<font.*>)/U',$result,$matches);
for($i=0;$i<count($matches[1]);$i++)
{
$result = str_replace($matches[1][$i],strtr($matches[1][$i],array_flip(get_html_translation_table(HTML_SPECIALCHARS))),$result);
}
preg_match_all('/(<ol.*>)/U',$result,$matches);
for($i=0;$i<count($matches[1]);$i++)
{
$result = str_replace($matches[1][$i],strtr($matches[1][$i],array_flip(get_html_translation_table(HTML_SPECIALCHARS))),$result);
}
preg_match_all('/(<ul.*>)/U',$result,$matches);
for($i=0;$i<count($matches[1]);$i++)
{
$result = str_replace($matches[1][$i],strtr($matches[1][$i],array_flip(get_html_translation_table(HTML_SPECIALCHARS))),$result);
}
preg_match_all('/(<li.*>)/U',$result,$matches);
for($i=0;$i<count($matches[1]);$i++)
{
$result = str_replace($matches[1][$i],strtr($matches[1][$i],array_flip(get_html_translation_table(HTML_SPECIALCHARS))),$result);
}
preg_match_all('/(<a .*>)/U',$result,$matches);
for($i=0;$i<count($matches[1]);$i++)
{
$result = str_replace($matches[1][$i],strtr($matches[1][$i],array_flip(get_html_translation_table(HTML_SPECIALCHARS))),$result);
}
return $result;
}
/**
* Used solely for setting up the @uses list
* @package ignore
* @ignore
*/
class __dummyConverter extends Converter
{
function setTemplateDir(){}
function setTargetDir(){}
function getPageName(&$element)
{
if (phpDocumentor_get_class($element) == 'parserpage') return '_'.$element->getName();
return '_'.$element->parent->getName();
}
}
?>

PHP5

Для web разработчика

Nov 21
File Source for Converter.inc

Source for file Converter.inc

PHP5

Для web разработчика

Nov 21File Source for Converter.inc

Source for file Converter.inc

Nov 21
File Source for Converter.inc