diff options
Diffstat (limited to 'buildscripts/PhpDocumentor/phpDocumentor/Converter.inc')
| -rwxr-xr-x | buildscripts/PhpDocumentor/phpDocumentor/Converter.inc | 5460 |
1 files changed, 0 insertions, 5460 deletions
diff --git a/buildscripts/PhpDocumentor/phpDocumentor/Converter.inc b/buildscripts/PhpDocumentor/phpDocumentor/Converter.inc deleted file mode 100755 index 7f658189..00000000 --- a/buildscripts/PhpDocumentor/phpDocumentor/Converter.inc +++ /dev/null @@ -1,5460 +0,0 @@ -<?php -/** - * Base class for all Converters - * - * phpDocumentor :: automatic documentation generator - * - * PHP versions 4 and 5 - * - * Copyright (c) 2001-2006 Gregory Beaver - * - * LICENSE: - * - * This library is free software; you can redistribute it - * and/or modify it under the terms of the GNU Lesser General - * Public License as published by the Free Software Foundation; - * either version 2.1 of the License, or (at your option) any - * later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - * - * @package Converters - * @author Greg Beaver <cellog@php.net> - * @copyright 2001-2006 Gregory Beaver - * @license http://www.opensource.org/licenses/lgpl-license.php LGPL - * @version CVS: $Id: Converter.inc 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|proc the tutorial type to search for - * @param tutorial name - * @param string package name - * @param string subpackage name, if any - * @return false|parserTutorial if 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 <<b>> 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 <<i>> 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 <<br>> 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|string full 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("<b>ERROR</b>: 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]<br>"; - $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|parserTag list 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|parserPage only 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|string returns 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->prev || $element->next); - if ($element->parent) - { - $template->assign('up',$this->getId($element->parent)); - $template->assign('uptitle',$element->parent->title); - } - if ($element->prev) - { - $template->assign('prev',$this->getId($element->prev)); - $template->assign('prevtitle',$element->prev->title); - } - if ($element->next) - { - $template->assign('next',$this->getId($element->next)); - $template->assign('nexttitle',$element->next->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|false array('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|false array('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(); - } -} -?> |