Class Converter

Description

Base class for all output converters.

The Converter marks the final stage in phpDocumentor. phpDocumentor works in this order:

Parsing => Intermediate Parsing organization => Conversion to output

A Converter takes output from the phpDocumentor_IntermediateParser and converts it to output. With version 1.2, phpDocumentor includes a variety of output converters:

{@ and using walk() or walk_everything (depending on the value of $sort_absolutely_everything) it "walks" over an array of phpDocumentor elements.}}

  • author: Greg Beaver <cellog@php.net>
  • version: $Id: Converter.inc 291278 2009-11-24 17:43:20Z ashnazg $
  • abstract:
  • since: 1.0rc1

Located in /phpDocumentor/Converter.inc (line 74)


	
			
Direct descendents
Class Description
HTMLframesConverter HTML output converter.
HTMLSmartyConverter HTML output converter.
XMLDocBookpeardoc2Converter XML DocBook converter.
XMLDocBookConverter XML DocBook converter.
PDFdefaultConverter PDF output converter.
CHMdefaultConverter Generates files that MS HTML Help Worshop can use to create a MS Windows compiled help file (CHM)
Variable Summary
Method Summary
Converter Converter (array &$allp, array &$packp, Classes &$classes, ProceduralPages &$procpages, array $po, boolean $pp, boolean $qm, string $targetDir, string $template, string $title)
string AttrToString (string $tag, attribute $attr, [boolean $unmodified = false])
string Bolden (string $para)
string Br (string $para)
void checkState (mixed $state)
void cleanup ()
void Convert (mixed &$element)
void convertClass ( &$element)
void convertConst (parserConst &$element, [ $additions = array()])
void convertDefine (parserDefine &$element, [array $addition = array()])
void ConvertErrorLog ()
void convertFunction (parserFunction &$element, [ $addition = array()])
void convertGlobal (parserGlobal &$element, [array $addition = array()])
void convertInclude (parserInclude &$element, [ $addition = array()])
void convertMethod (parserMethod &$element, [ $additions = array()])
void convertPage (parserPage &$element)
string ConvertTitle (string $tag, array $attr, string $title, string $cdata)
void ConvertTodoList ()
void &convertTutorial (parserTutorial &$element)
void convertVar (parserVar &$element, [ $additions = array()])
void Convert_RIC (README|INSTALL|CHANGELOG $name, string $contents)
void copyFile (string $file, [ $subdir = ''])
void createParentDir (string $dir)
string EncloseList (string $list,  $ordered)
string EncloseParagraph (string $para)
void endClass ()
void endPage ()
string exampleProgramExample (string $example, [boolean $tutorial = false], [ $inlinesourceparse = null], [ $class = null], [ $linenum = null], [ $filesourcepath = null])
void formatIndex ()
void formatLeftIndex ()
void formatPkgIndex ()
string formatTutorialTOC (array $toc)
array getClassesOnPage (parserData &$element)
mixed getClassLink (string $expr, string $package, [ $file = false], [ $text = false])
mixed getConstLink (string $expr, string $class, string $package, [ $file = false], [ $text = false])
string getConverterDir ()
string getCurrentPageLink ()
string getCurrentPageURL (string $pathinfo)
mixed getDefineLink (string $expr, string $package, [ $file = false], [ $text = false])
string getFileSourceName ( $path, string $pathinfo)
string getFileSourcePath (string $base)
array getFormattedConflicts (mixed &$element, string $type)
array getFormattedDescVars (parserVar &$element)
array|false getFormattedMethodImplements (parserMethod &$element)
array|false getFormattedOverrides (parserMethod &$element)
mixed getFunctionLink (string $expr, string $package, [ $file = false], [ $text = false])
mixed getGlobalLink (string $expr, string $package, [ $file = false], [ $text = false])
string getGlobalValue (string $value)
string getId (abstractLink &$link)
string getIncludeValue (string $value, string $ipath)
mixed &getLink (string $expr, [string $package = false], [array $packages = false])
mixed getMethodLink (string $expr, string $class, string $package, [ $file = false], [ $text = false])
mixed getPageLink (string $expr, string $package, [ $path = false], [ $text = false], [ $packages = false])
array getSortedClassTreeFromClass (string $class, string $package, string $subpackage)
string getSourceLink ( $path)
void getState ()
string getTutorialId ( $package,  $subpackage,  $tutorial,  $id)
tutorialLink|string getTutorialLink (string $expr, [string $package = false], [string $subpackage = false], [array $packages = false])
array getTutorialTree (parserTutorial|array $tutorial)
mixed getVarLink (string $expr, string $class, string $package, [ $file = false], [ $text = false])
boolean hasSourceCode (string $path)
false|parserTutorial hasTutorial (pkg|cls|proc $type, tutorial $name, string $package, [string $subpackage = ''])
string highlightDocBlockSource (string $token, string $word, [boolean $preformatted = false])
string highlightSource (integer $token, string $word, [boolean $preformatted = false])
string highlightTutorialSource (string $token, string $word, [boolean $preformatted = false])
string Italicize (string $para)
string Kbdize (string $para)
string ListItem (string $item)
Smarty &newSmarty ()
void Output ( $title)
string postProcess ( $text)
array prepareDocBlock (mixed &$element, [array $names = array()], [boolean $nopackage = true])
string PreserveWhiteSpace (string $string)
string ProgramExample (string $example, [boolean $tutorial = false], [ $inlinesourceparse = null], [ $class = null], [ $linenum = null], [ $filesourcepath = null])
string returnLink (string $link, string $text)
string returnSee (abstractLink &$link, [string $eltext = false])
string Sampize (string $para)
void setSourcePaths (string $path)
void setTargetDir (string $dir)
void setTemplateBase (string $base, string $dir)
void setTemplateDir (string $dir)
string sourceLine (integer $linenumber, string $line, [false|string $path = false])
void startHighlight ()
void TranslateEntity (string $name)
string TranslateTag (string $name, string $attr, string $cdata, string $unconvertedcdata)
void TutorialExample (string $example)
string type_adjust (string $typename)
string unmangle (string $sourcecode)
string vardump_tree ( $tree, [ $indent = ''])
string Varize (string $para)
void walk (array &$pages, array &$package_pages)
void walk_everything ()
void writeExample (string $title, string $path, string $source)
void writeFile (string $file, string $data, [boolean $binary = false])
void writeSource (string $filepath, string $source)
void _rmdir (string $directory)
void _setHighlightCache ( $type,  $token)
string _tutorial_path (parserTutorial $pkg, [parserTutorial $subpkg = 0], [parserTutorial $namepkg = 0])
Variables
array $all_packages (line 366)

All packages encountered in parsing

string|false $class = false (line 105)

set to a classname if currently parsing a class, false if not


Redefined in descendants as:
Classes $classes (line 319)

All class information, organized by path, and by package

array $class_contents = array() (line 269)

alphabetical index of all methods and vars in a class by package/subpackage

The class itself has a link under ###main

Smarty $class_data (line 165)

template for the class currently being processed


Redefined in descendants as:
array $class_elements = array() (line 208)

alphabetized index of classes by package

mixed $curfile (line 313)

full path of the current file being converted

parserPage $curpage (line 171)

current procedural page being processed

array $define_elements = array() (line 201)

alphabetized index of defines by package

array $elements = array() (line 187)

alphabetical index of all elements

array $function_elements = array() (line 222)

alphabetized index of functions by package

array $global_elements = array() (line 215)

alphabetized index of global variables by package

boolean $highlightingSource = false (line 325)

Flag used to help converters determine whether to do special source highlighting

array $leftindex = array('classes' => true, 'pages' => true, 'functions' => true, 'defines' => true, 'globals' => true) (line 384)

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 HTMLframesConverter::$leftindex, and in HTMLframesConverter::formatLeftIndex(). These indexes are intended for use as navigational aids through documentation, but can be used for anything by converters.


Redefined in descendants as:
string $outputformat = 'Generic' (line 90)

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"


Redefined in descendants as:
string $package = 'default' (line 95)

package name currently being converted

array $packagecategories (line 359)

Packages associated with categories

Used by the XML:DocBook/peardoc2 converter, and available to others, to group many packages into categories

array $package_elements = array() (line 180)

alphabetical index of all elements sorted by package, subpackage, page, and class.

  • var: Format: array(package => array(subpackage => array('page'|'class' => array(path|classname => array(element, element,...)))))
  • uses: Converter::$sort_absolutely_everything - if true, then $package_elements is used, otherwise, the ParserData::$classelements and ParserData::$pageelements variables are used
mixed $package_output (line 141)

set to value of -po commandline

array $package_parents (line 349)

Hierarchy of packages

Every package that contains classes may have parent or child classes in other packages. In other words, this code is legal:

  1.  /**
  2.   * @package one
  3.   * /
  4.  class one {}
  5.  
  6.  /**
  7.   * @package two
  8.   * /
  9.  class two extends one {}

In this case, package one is a parent of package two

string $page (line 147)

name of current page being converted


Redefined in descendants as:
array $page_contents = array() (line 238)

alphabetical index of all elements on a page by package/subpackage

The page itself has a link under ###main

Smarty $page_data (line 159)

template for the procedural page currently being processed


Redefined in descendants as:
array $page_elements = array() (line 194)

alphabetized index of procedural pages by package

bool $parseprivate (line 276)

controls processing of elements marked private with @access private

defaults to false. Set with command-line --parseprivate or -pp

string $path (line 153)

path of current page being converted


Redefined in descendants as:
array $pkg_elements = array() (line 229)

alphabetical index of all elements, indexed by package/subpackage

boolean $processSpecialRoots = false (line 81)

This converter knows about the new root tree processing

In order to fix PEAR Bug #6389


Redefined in descendants as:
bool $quietmode (line 283)

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

string $smarty_dir = '' (line 301)

Directory that the smarty templates are in


Redefined in descendants as:
mixed $sort_absolutely_everything = false (line 251)

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 PDFdefaultConverter

  • usedby: Converter::$package_elements - if true, then $package_elements is used, otherwise, the ParserData::$classelements and ParserData::$pageelements variables are used

Redefined in descendants as:
boolean $sort_page_contents_by_type = false (line 245)

This determines whether the $page_contents array should be sorted by element type as well as alphabetically by name


Redefined in descendants as:
array $sourcePaths = array() (line 372)

A list of files that have had source code generated

string $subpackage = '' (line 100)

subpackage name currently being converted

mixed $targetDir = '' (line 289)

directory that output is sent to. -t command-line sets this.

string $templateDir = '' (line 295)

Directory that the template is in, relative to phpDocumentor root directory

string $templateName = '' (line 308)

Name of the template, from last part of -o

array $template_options (line 399)

Options for each template, parsed from the options.ini file in the template base directory


Redefined in descendants as:
string $title = 'Generated Documentation' (line 392)
array $todoList = array() (line 429)

List of all @todo tags and a link to the element with the @todo

Format: array(package => array(link to element, array(todo parserTag,...)),...)

Methods
Constructor Converter (line 452)

Initialize Converter data structures

Converter Converter (array &$allp, array &$packp, Classes &$classes, ProceduralPages &$procpages, array $po, boolean $pp, boolean $qm, string $targetDir, string $template, string $title)
AttrToString (line 1307)

Convert the attribute of a Tutorial docbook tag's attribute list

to a string based on the template options.ini

string AttrToString (string $tag, attribute $attr, [boolean $unmodified = false])
  • string $tag: tag name
  • attribute $attr: array
  • boolean $unmodified: if true, returns attrname="value"...
Bolden (line 931)

Used to convert the contents of <b> in a docblock

string Bolden (string $para)
  • string $para
Br (line 1001)

Used to convert <br> in a docblock

string Br (string $para)
  • string $para

Redefined in descendants as:
checkState (line 5393)

Compare parserStringWithInlineTags::Convert() cache state to $state

void checkState (mixed $state)
  • mixed $state
cleanup (line 5102)

Finish up parsing/cleanup directories

void cleanup ()
Convert (line 3982)

Convert all elements to output format

This will call ConvertXxx where Xxx is http://www.php.net/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.

  • throws: PDERROR_NO_CONVERT_HANDLER
void Convert (mixed &$element)
convertClass (line 4046)

Default Class Handler

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. Sets up the class template. {@, getFormattedConflicts, getFormattedInheritedMethods, and getFormattedInheritedVars are called to complete vital template setup.}}

void convertClass ( &$element)
  • &$element

Redefined in descendants as:
convertConst (line 4233)

Converts class constants for template output.

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template.

This function must be called by a child converter with any extra template variables needed in the parameter $addition

void convertConst (parserConst &$element, [ $additions = array()])

Redefined in descendants as:
convertDefine (line 4358)

Converts defines for template output

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. This function must be called by a child converter with any extra template variables needed in the parameter $addition {@, this method also uses utility functions getGlobalValue(), getFormattedConflicts()}}

void convertDefine (parserDefine &$element, [array $addition = array()])
  • parserDefine &$element
  • array $addition: any additional template variables should be in this array

Redefined in descendants as:
ConvertErrorLog (line 2426)

Convert the phpDocumentor parsing/conversion error log

  • abstract:
void ConvertErrorLog ()

Redefined in descendants as:
convertFunction (line 4415)

Converts function for template output

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. This function must be called by a child converter with any extra template variables needed in the parameter $addition

void convertFunction (parserFunction &$element, [ $addition = array()])

Redefined in descendants as:
convertGlobal (line 4324)

Converts global variables for template output

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. This function must be called by a child converter with any extra template variables needed in the parameter $addition {@, this method also uses utility functions getGlobalValue(), getFormattedConflicts()}}

void convertGlobal (parserGlobal &$element, [array $addition = array()])
  • parserGlobal &$element
  • array $addition: any additional template variables should be in this array

Redefined in descendants as:
convertInclude (line 4387)

Converts includes for template output

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. This function must be called by a child converter with any extra template variables needed in the parameter $addition

void convertInclude (parserInclude &$element, [ $addition = array()])

Redefined in descendants as:
convertMethod (line 4113)

Converts method for template output

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. This function must be called by a child converter with any extra template variables needed in the parameter $addition

void convertMethod (parserMethod &$element, [ $additions = array()])

Redefined in descendants as:
convertPage (line 4278)

Default Page Handler

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. {@, this class uses getSourceLocation() and getClassesOnPage() to set template variables. Also used is getPageName(), to get a Converter-specific name for the page.}}

void convertPage (parserPage &$element)

Redefined in descendants as:
ConvertTitle (line 1396)

Convert the title of a Tutorial docbook tag section

to a string based on the template options.ini

string ConvertTitle (string $tag, array $attr, string $title, string $cdata)
  • string $tag: tag name
  • array $attr
  • string $title: title text
  • string $cdata
ConvertTodoList (line 2434)

Convert the list of all @todo tags

  • abstract:
void ConvertTodoList ()

Redefined in descendants as:
convertTutorial (line 4010)

Default Tutorial Handler

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template. Sets up the tutorial template, and its prev/next/parent links {@ and uses the parserTutorial::prev, parserTutorial::next, parserTutorial::parent links to set up those links.}}

void &convertTutorial (parserTutorial &$element)

Redefined in descendants as:
convertVar (line 4181)

Converts class variables for template output.

Conversion Handlers

All of the convert* handlers set up template variables for the Smarty template.

This function must be called by a child converter with any extra template variables needed in the parameter $addition

void convertVar (parserVar &$element, [ $additions = array()])

Redefined in descendants as:
Convert_RIC (line 3962)

Convert README/INSTALL/CHANGELOG file contents to output format

  • abstract:
void Convert_RIC (README|INSTALL|CHANGELOG $name, string $contents)
  • README|INSTALL|CHANGELOG $name
  • string $contents: contents of the file

Redefined in descendants as:
copyFile (line 5368)

Copies a file from the template directory to the target directory

thanks to Robert Hoffmann for this fix

void copyFile (string $file, [ $subdir = ''])
  • string $file
  • $subdir
createParentDir (line 5284)

Recursively creates all subdirectories that don't exist in the $dir path

void createParentDir (string $dir)
  • string $dir
EncloseList (line 888)

Used to convert the contents of <ol> or <ul> in a docblock

string EncloseList (string $list,  $ordered)
  • string $list
  • $ordered
EncloseParagraph (line 917)

Used to enclose a paragraph in a docblock

string EncloseParagraph (string $para)
  • string $para
endClass (line 507)

Called by 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

void endClass ()

Redefined in descendants as:
endPage (line 521)

Called by 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

void endPage ()

Redefined in descendants as:
exampleProgramExample (line 773)

Used to convert the {@example} inline tag in a docblock.

By default, this just wraps ProgramExample

  • see: XMLDocBookpeardoc2Converter::exampleProgramExample
string exampleProgramExample (string $example, [boolean $tutorial = false], [ $inlinesourceparse = null], [ $class = null], [ $linenum = null], [ $filesourcepath = null])
  • string $example
  • boolean $tutorial: true if this is to highlight a tutorial <programlisting>
  • $inlinesourceparse
  • $class
  • $linenum
  • $filesourcepath

Redefined in descendants as:
flushHighlightCache (line 609)

Return the close text for the current token

string flushHighlightCache ()
formatIndex (line 545)

Called by walk() while converting.

This method is intended to be the place that $elements is formatted for output.

void formatIndex ()

Redefined in descendants as:
formatLeftIndex (line 559)

Called by walk() while converting.

This method is intended to be the place that any of $class_elements, $function_elements, $page_elements, $define_elements, and $global_elements is formatted for output, depending on the value of $leftindex

void formatLeftIndex ()

Redefined in descendants as:
formatPkgIndex (line 533)

Called by walk() while converting.

This method is intended to be the place that $pkg_elements is formatted for output.

void formatPkgIndex ()

Redefined in descendants as:
formatTutorialTOC (line 1030)

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

  • return: table of contents formatted for use in the current output format
  • abstract:
  • usedby: parserTocInlineTag::Convert() - passes an array of format:
string formatTutorialTOC (array $toc)
  • array $toc: format: array(array('tagname' => section, 'link' => returnsee link, 'id' => anchor name, 'title' => from title tag),...)

Redefined in descendants as:
generateChildClassList (line 4818)

returns a list of child classes

void generateChildClassList (parserClass $class)

Redefined in descendants as:
generateFormattedClassTree (line 4665)

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: Converter-specific class tree for an individual class
  • abstract:
string generateFormattedClassTree (parserClass $class)

Redefined in descendants as:
getClassesOnPage (line 4617)

gets a list of all classes declared on a procedural page represented by

$element, a parserData class

  • return:

    links to each classes documentation

    Format:

     array('name' => class name,
           'sdesc' => summary of the class
           'link' => link to the class's documentation)

array getClassesOnPage (parserData &$element)
getClassLink (line 3179)

return false or a classLink to $expr

  • return: returns a classLink or false if the element is not found in package $package
  • see: classLink
mixed getClassLink (string $expr, string $package, [ $file = false], [ $text = false])
  • string $expr: class name
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
getConstLink (line 3354)

return false or a constLink to $expr in $class

  • return: returns a varLink or false if the element is not found in package $package, class $class
  • see: constLink
mixed getConstLink (string $expr, string $class, string $package, [ $file = false], [ $text = false])
  • string $expr: constant name
  • string $class: class name
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
getConverterDir (line 5189)

Get the absolute path to the converter's base directory

string getConverterDir ()
getCurrentPageLink (line 1115)
  • return: Link to the current page being parsed. Should return $curname and a converter-specific extension.
  • abstract:
string getCurrentPageLink ()

Redefined in descendants as:
getCurrentPageURL (line 1095)

Return the path to the current

string getCurrentPageURL (string $pathinfo)
  • string $pathinfo
getDefineLink (line 3227)

return false or a defineLink to $expr

  • return: returns a defineLink or false if the element is not found in package $package
  • see: defineLink
mixed getDefineLink (string $expr, string $package, [ $file = false], [ $text = false])
  • string $expr: constant name
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
getFileSourceName (line 1070)

Translate the path info into a unique file name for the highlighted source code.

string getFileSourceName ( $path, string $pathinfo)
  • string $pathinfo
  • $path

Redefined in descendants as:
getFileSourcePath (line 1083)

Return the fixed path to the source-code file folder.

string getFileSourcePath (string $base)
  • string $base: Path is relative to this folder
getFormattedConflicts (line 4718)
array getFormattedConflicts (mixed &$element, string $type)
getFormattedDescMethods (line 4738)

Get a list of methods in child classes that override this method

array getFormattedDescMethods (parserMethod &$element)
getFormattedDescVars (line 4759)

Get a list of vars in child classes that override this var

array getFormattedDescVars (parserVar &$element)
getFormattedImplements (line 4681)

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: Converter-specific class tree for an individual class
  • abstract:
string getFormattedImplements (parserClass $el)
getFormattedInheritedConsts (line 5023)

Return template-enabled list of inherited class constants

uses parserConst helper function getInheritedConsts and generates a template-enabled list using getClassLink()

  • return: Format:
     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),
                  ...),
       ...)
  • see: Converter::getClassLink(), parserMethod::getInheritedConsts()
array getFormattedInheritedConsts (parserConst $child)
getFormattedInheritedMethods (line 4935)

Return template-enabled list of inherited methods

uses parserMethod helper function getInheritedMethods and generates a template-enabled list using getClassLink()

  • return: Format:
     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' => parserMethod::getIntricateFunctionCall()
                                           returned array,
                        'sdesc' => summary of inherited variable),
                  ...),
       ...)
  • see: Converter::getClassLink(), parserMethod::getInheritedMethods()
array getFormattedInheritedMethods (parserMethod $child)
getFormattedInheritedVars (line 4864)

Return template-enabled list of inherited variables

uses parserVar helper function getInheritedVars and generates a template-enabled list using getClassLink()

  • return: Format:
     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),
                  ...),
       ...)
  • see: Converter::getClassLink(), parserVar::getInheritedVars()
array getFormattedInheritedVars (parserVar $child)
getFormattedMethodImplements (line 4797)

Get the method this method(s) implemented from an interface, if any

array|false getFormattedMethodImplements (parserMethod &$element)
getFormattedOverrides (line 4780)

Get the method this method overrides, if any

array|false getFormattedOverrides (parserMethod &$element)
getFunctionLink (line 3203)

return false or a functionLink to $expr

mixed getFunctionLink (string $expr, string $package, [ $file = false], [ $text = false])
  • string $expr: function name
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
getGlobalLink (line 3251)

return false or a globalLink to $expr

  • return: returns a defineLink or false if the element is not found in package $package
  • see: defineLink
mixed getGlobalLink (string $expr, string $package, [ $file = false], [ $text = false])
  • string $expr: global variable name (with leading $)
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
getGlobalValue (line 5213)

Parse a global variable's default value for class initialization.

If a global variable's default value is "new class" as in:

  1.  $globalvar new Parser
This method will document it not as "new Parser" but instead as "new Parser". For examples, see phpdoc.inc. Many global variables are classes, and phpDocumentor links to their documentation

  • return: default global variable value with link to class if it's "new Class"
string getGlobalValue (string $value)
  • string $value: default value of a global variable.

Redefined in descendants as:
getHighlightState (line 588)
void getHighlightState ()
getId (line 3952)

take abstractLink descendant and text $eltext and return a

unique ID in the format needed for the Converter

  • return: unique identifier of $element
  • abstract:
string getId (abstractLink &$link)

Redefined in descendants as:
getIncludeValue (line 5254)

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:

  1.  include ("file.ext");

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:

  • absolute path to file
  • ./file.ext or ../file.ext
  • relpath/to/file.ext if relpath is a subdirectory of the base parse directory
For examples, see Setup.inc.php includes. Every include auto-links to the documentation for the file that is included

  • return: included file with link to docs for file, if found
string getIncludeValue (string $value, string $ipath)
  • string $value: file included by include statement.
  • string $ipath: path of file that has the include statement
getLink (line 3565)

The meat of the @see tag and inline {@link} tag

$expr is a string with many allowable formats:

  1. proceduralpagename.ext
  2. constant_name
  3. classname::function()
  4. classname::constantname
  5. classname::$variablename
  6. classname
  7. object classname
  8. function functionname()
  9. global $globalvarname
  10. packagename#expr where expr is any of the above

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: "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.

  1.  class myclass
  2.  {
  3.   // from inside the class definition, use "function conflict()" to refer to procedural function "conflict()"
  4.     function conflict()
  5.     {
  6.     }
  7.  }
  8.  
  9.  function conflict()
  10.  {
  11.  }

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

mixed &getLink (string $expr, [string $package = false], [array $packages = false])
  • string $expr: expression to search for a link
  • string $package: package to start searching in
  • array $packages: list of all packages to search in

Redefined in descendants as:
getMethodLink (line 3300)

return false or a methodLink to $expr in $class

  • return: returns a methodLink or false if the element is not found in package $package, class $class
  • see: methodLink
mixed getMethodLink (string $expr, string $class, string $package, [ $file = false], [ $text = false])
  • string $expr: method name
  • string $class: class name
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
getPageLink (line 3275)

return false or a pageLink to $expr

  • return: returns a pageLink or false if the element is not found in package $package
  • see: pageLink
mixed getPageLink (string $expr, string $package, [ $path = false], [ $text = false], [ $packages = false])
  • string $expr: procedural page name
  • string $package: package name
  • $path
  • $text
  • $packages

Redefined in descendants as:
getSortedClassTreeFromClass (line 2954)

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:

 array('#root' =>
         array('link' => classLink to $class,
               'parent' => false,
               'children' => array(array('class' => 'childclass1',
                                         'package' => 'child1package'),
                                    array('class' => 'childclass2',
                                         'package' => 'child2package'),...
                                  )
               ),
       'child1package#childclass1' =>
         array('link' => classLink to childclass1,
               'parent' => '#root',
               'children' => array(array('class' => 'kidclass',
                                         'package' => 'kidpackage'),...
                                  )
              ),
       'kidpackage#kidclass' =>
         array('link' => classLink to kidclass,
               'parent' => 'child1package#childclass1',
               'children' => array() // no children
              ),
      ....
      )

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.

  • link - a classLink to the current class
  • parent - a classLink to the class's parent, or false (except for one special case described below)
  • 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

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:

  1.  class extends Y
  2.  {
  3.  ...
  4.  }
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

array getSortedClassTreeFromClass (string $class, string $package, string $subpackage)
  • string $class: class name
  • string $package
  • string $subpackage
getSourceLink (line 1105)
string getSourceLink ( $path)
  • $path

Redefined in descendants as:
getState (line 5382)

Return parserStringWithInlineTags::Convert() cache state

void getState ()

Redefined in descendants as:
getTutorialId (line 1418)

Return a converter-specific id to distinguish tutorials and their sections

Used by {@id}

string getTutorialId ( $package,  $subpackage,  $tutorial,  $id)
  • $package
  • $subpackage
  • $tutorial
  • $id

Redefined in descendants as:
getTutorialLink (line 3417)

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:

  1.  * @tutorial package/subpackage/file.cls
  2.  * @tutorial package/file.cls
  3.  * @tutorial file.cls

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:

  1. current package/subpackage
  2. all other subpackages of current package
  3. parent package, if this package has classes that extend classes in another package
  4. all other packages

  • return: returns either a link, or the original text, if not found
  • since: 1.2
tutorialLink|string getTutorialLink (string $expr, [string $package = false], [string $subpackage = false], [array $packages = false])
  • string $expr: the original expression
  • string $package: package to look in first
  • string $subpackage: subpackage to look in first
  • array $packages: 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
getTutorialTree (line 1974)

Get a tree structure representing the hierarchy of tutorials

Returns an array in format:

 array('tutorial' => parserTutorial,
       'kids' => array( // child tutorials
                   array('tutorial' => child parserTutorial,
                         'kids' => array(...)
                        )
                      )
      )

array getTutorialTree (parserTutorial|array $tutorial)

Redefined in descendants as:
getVarLink (line 3327)

return false or a varLink to $expr in $class

  • return: returns a varLink or false if the element is not found in package $package, class $class
  • see: varLink
mixed getVarLink (string $expr, string $class, string $package, [ $file = false], [ $text = false])
  • string $expr: var name
  • string $class: class name
  • string $package: package name
  • $file
  • $text

Redefined in descendants as:
hasSourceCode (line 1159)

Determine whether an element's file has generated source code, used for linking to line numbers of source.

Wrapper for $sourcePaths in this version

boolean hasSourceCode (string $path)
  • string $path: full path to the source code file
hasTutorial (line 490)
  • return: if the tutorial exists, return it
false|parserTutorial hasTutorial (pkg|cls|proc $type, tutorial $name, string $package, [string $subpackage = ''])
  • pkg|cls|proc $type: the tutorial type to search for
  • tutorial $name: name
  • string $package: package name
  • string $subpackage: subpackage name, if any
highlightDocBlockSource (line 690)

Used to allow converters to format the source code of DocBlocks the way they'd like.

default returns it unchanged. Mainly used by the HighlightParser

string highlightDocBlockSource (string $token, string $word, [boolean $preformatted = false])
  • string $token: name of docblock token type
  • string $word: contents of token
  • boolean $preformatted: whether the contents are preformatted or need modification
highlightSource (line 637)

Used to allow converters to format the source code the way they'd like.

default returns it unchanged. Mainly used by the HighlightParser

string highlightSource (integer $token, string $word, [boolean $preformatted = false])
  • integer $token: token value from tokenizer constants
  • string $word: contents of token
  • boolean $preformatted: whether the contents are preformatted or need modification
highlightTutorialSource (line 728)

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 HighlightParser

string highlightTutorialSource (string $token, string $word, [boolean $preformatted = false])
  • string $token: name of docblock token type
  • string $word: contents of token
  • boolean $preformatted: whether the contents are preformatted or need modification
Italicize (line 945)

Used to convert the contents of <i> in a docblock

string Italicize (string $para)
  • string $para
Kbdize (line 973)

Used to convert the contents of <kbd> in a docblock

string Kbdize (string $para)
  • string $para
ListItem (line 874)

Used to convert the contents of <li> in a docblock

string ListItem (string $item)
  • string $item
newSmarty (line 5075)

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.

Smarty &newSmarty ()
Output (line 5137)

do all necessary output

void Output ( $title)
  • $title

Redefined in descendants as:
postProcess (line 1016)

This version does nothing

Perform necessary post-processing of string data. For example, the HTML Converters should escape < and > to become &lt; and &gt;

string postProcess ( $text)
  • $text

Redefined in descendants as:
prepareDocBlock (line 4480)

convert the element's DocBlock for output

This function converts all tags and descriptions for output

  • return: Format:
     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 ]
          )
array prepareDocBlock (mixed &$element, [array $names = array()], [boolean $nopackage = true])
  • mixed &$element: any descendant of parserElement, or parserData
  • array $names: used to translate tagnames into other tags
  • boolean $nopackage: set to false for pages and classes, the only elements allowed to specify @package

Redefined in descendants as:
PreserveWhiteSpace (line 903)

Used to convert the contents of <pre> in a docblock

string PreserveWhiteSpace (string $string)
  • string $string
ProgramExample (line 785)

Used to convert the <code> tag in a docblock

string ProgramExample (string $example, [boolean $tutorial = false], [ $inlinesourceparse = null], [ $class = null], [ $linenum = null], [ $filesourcepath = null])
  • string $example
  • boolean $tutorial: true if this is to highlight a tutorial <programlisting>
  • $inlinesourceparse
  • $class
  • $linenum
  • $filesourcepath

Redefined in descendants as:
returnLink (line 3929)

take URL $link and text $text and return a link in the format needed for the Converter

  • return: link to $link
  • abstract:
string returnLink (string $link, string $text)
  • string $link: URL
  • string $text: text to display

Redefined in descendants as:
returnSee (line 3941)

take abstractLink descendant and text $eltext and return a link

in the format needed for the Converter

  • return: link to $element
  • abstract:
string returnSee (abstractLink &$link, [string $eltext = false])

Redefined in descendants as:
Sampize (line 987)

Used to convert the contents of <samp> in a docblock

string Sampize (string $para)
  • string $para
setSourcePaths (line 1174)

Mark a file as having had source code highlighted

void setSourcePaths (string $path)
  • string $path: full path of source file
setTargetDir (line 5312)

Sets the output directory for generated documentation

As of 1.3.0RC6, this also sets the compiled templates directory inside the target directory

void setTargetDir (string $dir)
  • string $dir: the output directory

Redefined in descendants as:
setTemplateBase (line 5148)

Set the template directory with a different template base directory

void setTemplateBase (string $base, string $dir)
  • string $base: template base directory
  • string $dir: template name
setTemplateDir (line 5173)

sets the template directory based on the $outputformat and $name

Also sets $templateName to the $dir parameter

void setTemplateDir (string $dir)
  • string $dir: subdirectory

Redefined in descendants as:
sortPageContentsByElementType (line 2570)

sorts $page_contents by element type as well as alphabetically

  • see: $sort_page_contents_by_element_type
void sortPageContentsByElementType ( &$pages)
  • &$pages
sourceLine (line 1130)

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

  • return: formatted source code line with line number
string sourceLine (integer $linenumber, string $line, [false|string $path = false])
  • integer $linenumber: line number
  • string $line: highlighted source code line
  • false|string $path: full path to @filesource file this line is a part of, if this is a single line from a complete file.

Redefined in descendants as:
startHighlight (line 582)

Initialize highlight caching

void startHighlight ()
TranslateEntity (line 1184)

Used to translate an XML DocBook entity like &rdquo; from a tutorial by reading the options.ini file for the template.

void TranslateEntity (string $name)
  • string $name: entity name
TranslateTag (line 1214)

Used to translate an XML DocBook tag from a tutorial by reading the options.ini file for the template.

string TranslateTag (string $name, string $attr, string $cdata, string $unconvertedcdata)
  • string $name: tag name
  • string $attr: any attributes Format: array(name => value)
  • string $cdata: the tag contents, if any
  • string $unconvertedcdata: the tag contents, if any, unpost-processed

Redefined in descendants as:
TutorialExample (line 860)
void TutorialExample (string $example)
  • string $example

Redefined in descendants as:
type_adjust (line 759)

Called by parserReturnTag::Convert() to allow converters to change type names to desired formatting

Used by XMLDocBookConverter::type_adjust() to change true and false to the peardoc2 values

string type_adjust (string $typename)
  • string $typename

Redefined in descendants as:
unmangle (line 574)

Called by parserSourceInlineTag::stringConvert() to allow converters to format the source code the way they'd like.

default returns it unchanged (html with xhtml tags)

string unmangle (string $sourcecode)
  • string $sourcecode: output from highlight_string() - use this function to reformat the returned data for Converter-specific output

Redefined in descendants as:
vardump_tree (line 2202)

Debugging function for dumping $tutorial_tree

string vardump_tree ( $tree, [ $indent = ''])
  • $tree
  • $indent
Varize (line 959)

Used to convert the contents of <var> in a docblock

string Varize (string $para)
  • string $para
walk (line 1705)

called by 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 Convert(), which then passes to the Convert*() methods. A child Converter need not override any of these unless special functionality must be added. see Converter Default Template Variables for details. {@ and the left indexes specified by $leftindexes, and then sorts them by calling sortIndexes().

Next, it converts all README/CHANGELOG/INSTALL-style files, using Convert_RIC.

After this, it passes all package-level docs to Convert(). Then, it calls the index sorting functions formatPkgIndex(), formatIndex() and 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 parserDefine, parserInclude parserGlobal, and parserFunction are passed to Convert().

Then, class elements are passed in this order: parserClass, then all of the parserVars in the class and all of the parserMethods in the class. Classes are in alphabetical order, and both vars and methods are in alphabetical order.

Finally, ConvertErrorLog() is called and the data walk is complete.}}

void walk (array &$pages, array &$package_pages)
walk_everything (line 2267)

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

void walk_everything ()
writeExample (line 1060)

Write out the formatted source code for an example php file

This function provides the primary functionality for the @example tag.

  • abstract:
void writeExample (string $title, string $path, string $source)
  • string $title: example title
  • string $path: example filename (no path)
  • string $source: fully highlighted/linked source code of the file

Redefined in descendants as:
writeFile (line 5345)

Writes a file to target dir

void writeFile (string $file, string $data, [boolean $binary = false])
  • string $file
  • string $data
  • boolean $binary: true if the data is binary and not text

Redefined in descendants as:
writeSource (line 1044)

Write out the formatted source code for a php file

This function provides the primary functionality for the @filesource tag.

void writeSource (string $filepath, string $source)
  • string $filepath: full path to the file
  • string $source: fully highlighted/linked source code of the file

Redefined in descendants as:
_rmdir (line 5114)

Completely remove a directory and its contents

void _rmdir (string $directory)
  • string $directory
_setHighlightCache (line 593)
void _setHighlightCache ( $type,  $token)
  • $type
  • $token
_tutorial_path (line 2081)

Returns the path to this tutorial as a string

string _tutorial_path (parserTutorial $pkg, [parserTutorial $subpkg = 0], [parserTutorial $namepkg = 0])

Documentation generated on Mon, 05 Dec 2011 21:09:14 -0600 by phpDocumentor 1.4.4