Docs For Class Converter

Description

Located in File: /phpDocumentor/Converter.inc

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 <[email protected]>
version: - $Id: Converter.inc 291278 2009-11-24 17:43:20Z ashnazg $
abstract: -
since: - 1.0rc1

Classes extended from Converter:

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)

Class Variables

Summary:

array $all_packages

string|false $class

Classes $classes

array $class_contents

Smarty $class_data

array $class_elements

mixed $curfile

parserPage $curpage

array $define_elements

array $elements

array $function_elements

array $global_elements

boolean $highlightingSource

array $leftindex

string $outputformat

string $package

array $packagecategories

array $package_elements

mixed $package_output

array $package_parents

string $page

array $page_contents

Smarty $page_data

array $page_elements

bool $parseprivate

string $path

array $pkg_elements

boolean $processSpecialRoots

bool $quietmode

string $smarty_dir

mixed $sort_absolutely_everything

boolean $sort_page_contents_by_type

array $sourcePaths

string $subpackage

mixed $targetDir

string $templateDir

string $templateName

array $template_options

string $title

array $todoList

$all_packages (line 366)

Data type : array

All packages encountered in parsing

see: - phpDocumentor_IntermediateParser::$all_packages

$class = false (line 105)

Data type : string|false

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

$classes (line 319)

Data type : Classes

All class information, organized by path, and by package

$class_contents = array() (line 269)

Data type : array

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

The class itself has a link under ###main

var: - Format:

 array(package =>
       array(subpackage =>
             array(path =>
                   array(class =>
                         array(abstractLink descendant 1, ...
                        )
                  )
            )
      )

see: - Converter::formatLeftIndex()

$class_data (line 165)

Data type : Smarty

template for the class currently being processed

$class_elements = array() (line 208)

Data type : array

alphabetized index of classes by package

var: - Format: array(package => array(subpackage => array(classLink 1,classLink 2,...)
see: - Converter::$leftindex

$curfile (line 313)

Data type : mixed

full path of the current file being converted

$curpage (line 171)

Data type : parserPage

current procedural page being processed

$define_elements = array() (line 201)

Data type : array

alphabetized index of defines by package

var: - Format: array(package => array(subpackage => array(defineLink 1,defineLink 2,...)
see: - Converter::$leftindex

$elements = array() (line 187)

Data type : array

alphabetical index of all elements

var: - Format: array(first letter of element name => array(parserElement or parserPage,...))
see: - Converter::formatIndex(), HTMLframesConverter::formatIndex()

$function_elements = array() (line 222)

Data type : array

alphabetized index of functions by package

var: - Format: array(package => array(subpackage => array(functionLink 1,functionLink 2,...)
see: - Converter::$leftindex

$global_elements = array() (line 215)

Data type : array

alphabetized index of global variables by package

var: - Format: array(package => array(subpackage => array(globalLink 1,globalLink 2,...)
see: - Converter::$leftindex

$highlightingSource = false (line 325)

Data type : boolean

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

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

Data type : 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 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.

see: - Converter::formatLeftIndex()
see: - Converter::$class_elements, Converter::$page_elements, Converter::$function_elements, Converter::$define_elements, Converter::$global_elements

$outputformat = 'Generic' (line 90)

Data type : string

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 Tutorial

$package = 'default' (line 95)

Data type : string

package name currently being converted

$packagecategories (line 359)

Data type : array

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

$package_elements = array() (line 180)

Data type : array

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

$package_output (line 141)

Data type : mixed

set to value of -po commandline

tutorial: - phpDocumentor Tutorial

$package_parents (line 349)

Data type : array

Hierarchy of packages

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

/**
* @package one
* /
class one {}
/**
* @package two
* /
class two extends one {}

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

see: - phpDocumentor_IntermediateParser::$package_parents

$page (line 147)

Data type : string

name of current page being converted

$page_contents = array() (line 238)

Data type : array

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

The page itself has a link under ###main

var: - Format: array(package => array(subpackage => array(path => array(abstractLink descendant 1, ...)))
see: - Converter::formatLeftIndex()

$page_data (line 159)

Data type : Smarty

template for the procedural page currently being processed

$page_elements = array() (line 194)

Data type : array

alphabetized index of procedural pages by package

var: - Format: array(package => array(subpackage => array(pageLink 1,pageLink 2,...)
see: - Converter::$leftindex

$parseprivate (line 276)

Data type : bool

controls processing of elements marked private with @access private

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

$path (line 153)

Data type : string

path of current page being converted

$pkg_elements = array() (line 229)

Data type : array

alphabetical index of all elements, indexed by package/subpackage

var: - Format: array(first letter of element name => array(parserElement or parserPage,...))
see: - Converter::formatPkgIndex(), HTMLframesConverter::formatPkgIndex()

$processSpecialRoots = false (line 81)

Data type : boolean

This converter knows about the new root tree processing

In order to fix PEAR Bug #6389

$quietmode (line 283)

Data type : bool

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

$smarty_dir = '' (line 301)

Data type : string

Directory that the smarty templates are in

$sort_absolutely_everything = false (line 251)

Data type : mixed

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

$sort_page_contents_by_type = false (line 245)

Data type : boolean

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

see: - Converter::sortPageContentsByElementType()

$sourcePaths = array() (line 372)

Data type : array

A list of files that have had source code generated

$subpackage = '' (line 100)

Data type : string

subpackage name currently being converted

$targetDir = '' (line 289)

Data type : mixed

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

tutorial: - phpDocumentor Tutorial

$templateDir = '' (line 295)

Data type : string

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

$templateName = '' (line 308)

Data type : string

Name of the template, from last part of -o

tutorial: - phpDocumentor Tutorial

$template_options (line 399)

Data type : array

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

tutorial: - phpDocumentor Tutorials

$title = 'Generated Documentation' (line 392)

Data type : string

see: - phpDocumentor_IntermediateParser::$title

$todoList = array() (line 429)

Data type : array

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

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

tutorial: - @todo

Class Constants

Summary:

Method Detail

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])

string flushHighlightCache ()

void formatIndex ()

void formatLeftIndex ()

void formatPkgIndex ()

string formatTutorialTOC (array $toc)

void generateChildClassList (parserClass $class)

string generateFormattedClassTree (parserClass $class)

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 getFormattedDescMethods (parserMethod &$element)

array getFormattedDescVars (parserVar &$element)

string getFormattedImplements (parserClass $el)

array getFormattedInheritedConsts (parserConst $child)

array getFormattedInheritedMethods (parserMethod $child)

array getFormattedInheritedVars (parserVar $child)

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)

void getHighlightState ()

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)

void sortPageContentsByElementType ( &$pages)

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])

Constructor Converter (line 452)

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

Initialize Converter data structures

Parameters

array &$allp: $all_packages value
array &$packp: $package_parents value
Classes &$classes: $classes value
ProceduralPages &$procpages: $proceduralpages value
array $po: $package_output value
boolean $pp: $parseprivate value
boolean $qm: $quietmode value
string $targetDir: $targetDir value
string $template: $templateDir value
string $title: (@link $title} value

Info

Method AttrToString (line 1307)

string AttrToString( string $tag, attribute $attr, [boolean $unmodified = false])

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

to a string based on the template options.ini

Parameters

string $tag: tag name
attribute $attr: array
boolean $unmodified: if true, returns attrname="value"...

Info

Method Bolden (line 931)

string Bolden( string $para)

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

Parameters

string $para:

Info

usedby - parserB::Convert()

Method Br (line 1001)

string Br( string $para)

Overridden in child classes as:

XMLDocBookpeardoc2Converter::Br()

Used to convert <br> in a docblock

Parameters

string $para:

Info

usedby - parserBr::Convert()

Method checkState (line 5393)

void checkState( mixed $state)

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

Parameters

mixed $state:

Info

see - parserStringWithInlineTags::Convert()
abstract -

Method cleanup (line 5102)

void cleanup( )

Finish up parsing/cleanup directories

Info

Method Convert (line 3982)

void Convert( mixed &$element)

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.

Parameters

mixed &$element: parserElement descendant or parserPackagePage or parserData

Info

throws - PDERROR_NO_CONVERT_HANDLER

Method convertClass (line 4046)

void convertClass( &$element)

Overridden in child classes as:

HTMLframesConverter::convertClass(): Converts class for template output

HTMLSmartyConverter::convertClass(): Converts class for template output

XMLDocBookpeardoc2Converter::convertClass(): Converts class for template output

XMLDocBookConverter::convertClass(): Converts class for template output

PDFdefaultConverter::convertClass()

CHMdefaultConverter::convertClass(): Converts class for template output

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.}}

Parameters

&$element:

Info

Method convertConst (line 4233)

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

Overridden in child classes as:

HTMLframesConverter::convertConst(): Converts class variables for template output

HTMLSmartyConverter::convertConst(): Converts class variables for template output

PDFdefaultConverter::convertConst()

CHMdefaultConverter::convertConst(): Converts class constants for template output

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

Parameters

parserConst &$element:
$additions:

Info

Method convertDefine (line 4358)

void convertDefine( parserDefine &$element, [array $addition = array()])

Overridden in child classes as:

HTMLframesConverter::convertDefine(): Converts defines for template output

HTMLSmartyConverter::convertDefine(): Converts defines for template output

XMLDocBookpeardoc2Converter::convertDefine(): Converts defines for template output

XMLDocBookConverter::convertDefine(): Converts defines for template output

PDFdefaultConverter::convertDefine()

CHMdefaultConverter::convertDefine(): Converts defines for template output

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()}}

Parameters

parserDefine &$element:
array $addition: any additional template variables should be in this array

Info

uses - Converter::postProcess() - on define_value template value, makes it displayable

Method ConvertErrorLog (line 2426)

void ConvertErrorLog( )

Overridden in child classes as:

HTMLframesConverter::ConvertErrorLog(): Create errors.html template file output

HTMLSmartyConverter::ConvertErrorLog(): Create errors.html template file output

XMLDocBookpeardoc2Converter::ConvertErrorLog(): Create errors.html template file output

XMLDocBookConverter::ConvertErrorLog(): Create errors.html template file output

CHMdefaultConverter::ConvertErrorLog(): Create errors.html template file output

Convert the phpDocumentor parsing/conversion error log

Info

abstract -

Method convertFunction (line 4415)

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

Overridden in child classes as:

HTMLframesConverter::convertFunction(): Converts function for template output

HTMLSmartyConverter::convertFunction(): Converts function for template output

XMLDocBookpeardoc2Converter::convertFunction(): Converts function for template output - does nothing in peardoc2!

XMLDocBookConverter::convertFunction(): Converts function for template output

PDFdefaultConverter::convertFunction()

CHMdefaultConverter::convertFunction(): Converts function for template output

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

Parameters

parserFunction &$element:
$addition:

Info

see - Converter::prepareDocBlock()

Method convertGlobal (line 4324)

void convertGlobal( parserGlobal &$element, [array $addition = array()])

Overridden in child classes as:

HTMLframesConverter::convertGlobal(): Converts global variables for template output

HTMLSmartyConverter::convertGlobal(): Converts global variables for template output

XMLDocBookpeardoc2Converter::convertGlobal(): Converts global variables for template output

XMLDocBookConverter::convertGlobal(): Converts global variables for template output

PDFdefaultConverter::convertGlobal()

CHMdefaultConverter::convertGlobal(): Converts global variables for template output

Converts global variables for template output

Conversion Handlers

Parameters

parserGlobal &$element:
array $addition: any additional template variables should be in this array

Info

uses - Converter::postProcess() - on global_value template value, makes it displayable

Method convertInclude (line 4387)

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

Overridden in child classes as:

HTMLframesConverter::convertInclude(): Converts include elements for template output

HTMLSmartyConverter::convertInclude(): Converts include elements for template output

XMLDocBookpeardoc2Converter::convertInclude(): Converts include elements for template output

XMLDocBookConverter::convertInclude(): Converts include elements for template output

PDFdefaultConverter::convertInclude()

CHMdefaultConverter::convertInclude(): Converts include elements for template output

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

Parameters

parserInclude &$element:
$addition:

Info

see - Converter::prepareDocBlock()

Method convertMethod (line 4113)

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

Overridden in child classes as:

HTMLframesConverter::convertMethod(): Converts class methods for template output

HTMLSmartyConverter::convertMethod(): Converts class methods for template output

XMLDocBookpeardoc2Converter::convertMethod(): Converts method for template output

XMLDocBookConverter::convertMethod(): Converts method for template output

PDFdefaultConverter::convertMethod()

CHMdefaultConverter::convertMethod(): Converts class methods for template output

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

Parameters

parserMethod &$element:
$additions:

Info

Method convertPage (line 4278)

void convertPage( parserPage &$element)

Overridden in child classes as:

HTMLframesConverter::convertPage(): converts procedural pages for template output

HTMLSmartyConverter::convertPage(): converts procedural pages for template output

XMLDocBookpeardoc2Converter::convertPage(): converts procedural pages for template output

XMLDocBookConverter::convertPage(): converts procedural pages for template output

PDFdefaultConverter::convertPage()

CHMdefaultConverter::convertPage(): converts procedural pages for template output

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.}}

Parameters

parserPage &$element:

Info

Method ConvertTitle (line 1396)

string ConvertTitle( string $tag, array $attr, string $title, string $cdata)

Convert the title of a Tutorial docbook tag section

to a string based on the template options.ini

Parameters

string $tag: tag name
array $attr:
string $title: title text
string $cdata:

Info

Method ConvertTodoList (line 2434)

void ConvertTodoList( )

Overridden in child classes as:

HTMLframesConverter::ConvertTodoList()

HTMLSmartyConverter::ConvertTodoList()

CHMdefaultConverter::ConvertTodoList()

Convert the list of all @todo tags

Info

abstract -

Method convertTutorial (line 4010)

void &convertTutorial( parserTutorial &$element)

Overridden in child classes as:

HTMLframesConverter::convertTutorial()

HTMLSmartyConverter::convertTutorial()

XMLDocBookpeardoc2Converter::convertTutorial(): Convert tutorials for output

XMLDocBookConverter::convertTutorial()

PDFdefaultConverter::convertTutorial()

CHMdefaultConverter::convertTutorial()

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.}}

Parameters

parserTutorial &$element:

Info

Method convertVar (line 4181)

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

Overridden in child classes as:

HTMLframesConverter::convertVar(): Converts class variables for template output

HTMLSmartyConverter::convertVar(): Converts class variables for template output

XMLDocBookpeardoc2Converter::convertVar(): Does nothing in this converter

XMLDocBookConverter::convertVar(): Converts class variables for template output.

PDFdefaultConverter::convertVar()

CHMdefaultConverter::convertVar(): Converts class variables for template output

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

Parameters

parserVar &$element:
$additions:

Info

Method Convert_RIC (line 3962)

void Convert_RIC( README|INSTALL|CHANGELOG $name, string $contents)

Overridden in child classes as:

HTMLframesConverter::Convert_RIC(): Convert README/INSTALL/CHANGELOG file contents to output format

HTMLSmartyConverter::Convert_RIC(): Convert README/INSTALL/CHANGELOG file contents to output format

PDFdefaultConverter::Convert_RIC(): Convert README/INSTALL/CHANGELOG file contents to output format

CHMdefaultConverter::Convert_RIC(): Convert README/INSTALL/CHANGELOG file contents to output format

Convert README/INSTALL/CHANGELOG file contents to output format

Parameters

README|INSTALL|CHANGELOG $name:
string $contents: contents of the file

Info

abstract -

Method copyFile (line 5368)

void copyFile( string $file, [ $subdir = ''])

Copies a file from the template directory to the target directory

thanks to Robert Hoffmann for this fix

Parameters

string $file:
$subdir:

Info

Method createParentDir (line 5284)

void createParentDir( string $dir)

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

Parameters

string $dir:

Info

Method EncloseList (line 888)

string EncloseList( string $list, $ordered)

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

Parameters

string $list:
$ordered:

Info

usedby - parserList::Convert() - enclose the list

Method EncloseParagraph (line 917)

string EncloseParagraph( string $para)

Used to enclose a paragraph in a docblock

Parameters

string $para:

Info

Method endClass (line 507)

void endClass( )

Overridden in child classes as:

HTMLframesConverter::endClass(): Writes out the template file of $class_data and unsets the template to save memory

HTMLSmartyConverter::endClass(): Writes out the template file of $class_data and unsets the template to save memory

XMLDocBookpeardoc2Converter::endClass(): Writes out the template file of $class_data and unsets the template to save memory

XMLDocBookConverter::endClass(): Writes out the template file of $class_data and unsets the template to save memory

CHMdefaultConverter::endClass(): Writes out the template file of $class_data and unsets the template to save memory

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

Info

see - HTMLframesConverter::endClass()
abstract -

Method endPage (line 521)

void endPage( )

Overridden in child classes as:

HTMLframesConverter::endPage(): Writes out the template file of $page_data and unsets the template to save memory

HTMLSmartyConverter::endPage(): Writes out the template file of $page_data and unsets the template to save memory

XMLDocBookConverter::endPage(): Writes out the template file of $page_data and unsets the template to save memory

CHMdefaultConverter::endPage(): Writes out the template file of $page_data and unsets the template to save memory

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

Info

see - HTMLframesConverter::endClass()
abstract -

Method exampleProgramExample (line 773)

string exampleProgramExample( string $example, [boolean $tutorial = false], [ $inlinesourceparse = null], [ $class = null], [ $linenum = null], [ $filesourcepath = null])

Overridden in child classes as:

XMLDocBookpeardoc2Converter::exampleProgramExample(): Used to convert the {@example} inline tag in a docblock.

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

By default, this just wraps ProgramExample

Parameters

string $example:
boolean $tutorial: true if this is to highlight a tutorial <programlisting>
$inlinesourceparse:
$class:
$linenum:
$filesourcepath:

Info

see - XMLDocBookpeardoc2Converter::exampleProgramExample

Method flushHighlightCache (line 609)

string flushHighlightCache( )

Return the close text for the current token

Info

Method formatIndex (line 545)

void formatIndex( )

Overridden in child classes as:

HTMLframesConverter::formatIndex(): HTMLdefaultConverter uses this function to format template index.html and packages.html

HTMLSmartyConverter::formatIndex(): HTMLdefaultConverter uses this function to format template index.html and packages.html

XMLDocBookpeardoc2Converter::formatIndex(): Does nothing

XMLDocBookConverter::formatIndex(): HTMLdefaultConverter uses this function to format template index.html and packages.html

CHMdefaultConverter::formatIndex(): CHMdefaultConverter uses this function to format template index.html and packages.html

Called by walk() while converting.

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

Info

see - HTMLframesConverter::formatIndex()
abstract -

Method formatLeftIndex (line 559)

void formatLeftIndex( )

Overridden in child classes as:

HTMLframesConverter::formatLeftIndex(): Generate indexes for li_package.html and classtree output files

HTMLSmartyConverter::formatLeftIndex(): Generate indexes for li_package.html and classtree output files

XMLDocBookpeardoc2Converter::formatLeftIndex(): Creates package/lang/categoryname/packagename.xml for each package

XMLDocBookConverter::formatLeftIndex(): Generate indexes for li_package.html and classtree output files

CHMdefaultConverter::formatLeftIndex(): Generate indexes for li_package.html and classtree output files

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

Info

see - HTMLframesConverter::formatLeftIndex()
abstract -

Method formatPkgIndex (line 533)

void formatPkgIndex( )

Overridden in child classes as:

HTMLframesConverter::formatPkgIndex(): HTMLdefaultConverter chooses to format both package indexes and the complete index here

HTMLSmartyConverter::formatPkgIndex(): HTMLdefaultConverter chooses to format both package indexes and the complete index here

XMLDocBookpeardoc2Converter::formatPkgIndex(): Does nothing

XMLDocBookConverter::formatPkgIndex(): HTMLdefaultConverter chooses to format both package indexes and the complete index here

CHMdefaultConverter::formatPkgIndex(): CHMdefaultConverter chooses to format both package indexes and the complete index here

Called by walk() while converting.

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

Info

see - HTMLframesConverter::formatPkgIndex()
abstract -

Method formatTutorialTOC (line 1030)

string formatTutorialTOC( array $toc)

Overridden in child classes as:

HTMLframesConverter::formatTutorialTOC(): Use the template tutorial_toc.tpl to generate a table of contents for HTML

HTMLSmartyConverter::formatTutorialTOC(): Use the template tutorial_toc.tpl to generate a table of contents for HTML

CHMdefaultConverter::formatTutorialTOC(): Use the template tutorial_toc.tpl to generate a table of contents for HTML

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

Parameters

array $toc: format: array(array('tagname' => section, 'link' => returnsee link, 'id' => anchor name, 'title' => from title tag),...)

Info

return - table of contents formatted for use in the current output format
abstract -
usedby - parserTocInlineTag::Convert() - passes an array of format:

Method generateChildClassList (line 4818)

void generateChildClassList( parserClass $class)

Overridden in child classes as:

XMLDocBookpeardoc2Converter::generateChildClassList(): returns a list of child classes

returns a list of child classes

Parameters

parserClass $class: class variable

Info

uses - parserClass::getChildClassList()

Method generateFormattedClassTree (line 4665)

string generateFormattedClassTree( parserClass $class)

Overridden in child classes as:

HTMLframesConverter::generateFormattedClassTree(): returns an array containing the class inheritance tree from the root object to the class

HTMLSmartyConverter::generateFormattedClassTree(): returns an array containing the class inheritance tree from the root object to the class

XMLDocBookpeardoc2Converter::generateFormattedClassTree(): returns an array containing the class inheritance tree from the root object to the class

XMLDocBookConverter::generateFormattedClassTree(): returns an array containing the class inheritance tree from the root object to the class

CHMdefaultConverter::generateFormattedClassTree(): returns an array containing the class inheritance tree from the root object to the class

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

Parameters

parserClass $class: class variable

Info

return - Converter-specific class tree for an individual class
abstract -

Method getClassesOnPage (line 4617)

array getClassesOnPage( parserData &$element)

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

$element, a parserData class

Parameters

parserData &$element:

Info

return -

links to each classes documentation

Format:

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

Method getClassLink (line 3179)

mixed getClassLink( string $expr, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getClassLink()

HTMLSmartyConverter::getClassLink()

XMLDocBookpeardoc2Converter::getClassLink()

XMLDocBookConverter::getClassLink()

PDFdefaultConverter::getClassLink()

CHMdefaultConverter::getClassLink()

return false or a classLink to $expr

Parameters

string $expr: class name
string $package: package name
$file:
$text:

Info

return - returns a classLink or false if the element is not found in package $package
see - classLink

Method getConstLink (line 3354)

mixed getConstLink( string $expr, string $class, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getConstLink()

HTMLSmartyConverter::getConstLink()

PDFdefaultConverter::getConstLink()

CHMdefaultConverter::getConstLink()

return false or a constLink to $expr in $class

Parameters

string $expr: constant name
string $class: class name
string $package: package name
$file:
$text:

Info

return - returns a varLink or false if the element is not found in package $package, class $class
see - constLink

Method getConverterDir (line 5189)

string getConverterDir( )

Get the absolute path to the converter's base directory

Info

Method getCurrentPageLink (line 1115)

string getCurrentPageLink( )

Overridden in child classes as:

HTMLframesConverter::getCurrentPageLink()

HTMLSmartyConverter::getCurrentPageLink()

CHMdefaultConverter::getCurrentPageLink()

Info

return - Link to the current page being parsed. Should return $curname and a converter-specific extension.
abstract -

Method getCurrentPageURL (line 1095)

string getCurrentPageURL( string $pathinfo)

Return the path to the current

Parameters

string $pathinfo:

Info

Method getDefineLink (line 3227)

mixed getDefineLink( string $expr, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getDefineLink()

HTMLSmartyConverter::getDefineLink()

XMLDocBookpeardoc2Converter::getDefineLink()

XMLDocBookConverter::getDefineLink()

PDFdefaultConverter::getDefineLink()

CHMdefaultConverter::getDefineLink()

return false or a defineLink to $expr

Parameters

string $expr: constant name
string $package: package name
$file:
$text:

Info

return - returns a defineLink or false if the element is not found in package $package
see - defineLink

Method getFileSourceName (line 1070)

string getFileSourceName( $path, string $pathinfo)

Overridden in child classes as:

PDFdefaultConverter::getFileSourceName()

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

Parameters

string $pathinfo:
$path:

Info

Method getFileSourcePath (line 1083)

string getFileSourcePath( string $base)

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

Parameters

string $base: Path is relative to this folder

Info

Method getFormattedConflicts (line 4718)

array getFormattedConflicts( mixed &$element, string $type)

Parameters

mixed &$element: parserClass, parserFunction, parserDefine or parserGlobal
string $type: type to display. either 'class','function','define' or 'global variable'

Info

return - links to conflicting elements, or empty array
uses - parserGlobal::getConflicts()
uses - parserFunction::getConflicts()
uses - parserDefine::getConflicts()
uses - parserClass::getConflicts()

Method getFormattedDescMethods (line 4738)

array getFormattedDescMethods( parserMethod &$element)

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

Parameters

parserMethod &$element:

Info

return - empty array or array(array('link'=>link to method, 'sdesc'=>short description of the method),...)
uses - parserMethod::getOverridingMethods()

Method getFormattedDescVars (line 4759)

array getFormattedDescVars( parserVar &$element)

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

Parameters

parserVar &$element:

Info

return - empty array or array('link'=>link to var, 'sdesc'=>short description of the method
uses - parserVar::getOverridingVars()

Method getFormattedImplements (line 4681)

string getFormattedImplements( parserClass $el)

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

Parameters

parserClass $el: class variable

Info

return - Converter-specific class tree for an individual class
abstract -

Method getFormattedInheritedConsts (line 5023)

array getFormattedInheritedConsts( parserConst $child)

Return template-enabled list of inherited class constants

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

Parameters

parserConst $child: class constant

Info

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()

Method getFormattedInheritedMethods (line 4935)

array getFormattedInheritedMethods( parserMethod $child)

Return template-enabled list of inherited methods

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

Parameters

parserMethod $child: class method

Info

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()

Method getFormattedInheritedVars (line 4864)

array getFormattedInheritedVars( parserVar $child)

Return template-enabled list of inherited variables

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

Parameters

parserVar $child: class var

Info

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()

Method getFormattedMethodImplements (line 4797)

array|false getFormattedMethodImplements( parserMethod &$element)

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

Parameters

parserMethod &$element:

Info

return - array('link'=>link to implemented method, 'sdesc'=>short description
uses - parserMethod::getImplements()

Method getFormattedOverrides (line 4780)

array|false getFormattedOverrides( parserMethod &$element)

Get the method this method overrides, if any

Parameters

parserMethod &$element:

Info

return - array('link'=>link to overridden method, 'sdesc'=>short description
see - parserMethod::getOverrides()

Method getFunctionLink (line 3203)

mixed getFunctionLink( string $expr, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getFunctionLink()

HTMLSmartyConverter::getFunctionLink()

XMLDocBookpeardoc2Converter::getFunctionLink()

XMLDocBookConverter::getFunctionLink()

PDFdefaultConverter::getFunctionLink()

CHMdefaultConverter::getFunctionLink()

return false or a functionLink to $expr

Parameters

string $expr: function name
string $package: package name
$file:
$text:

Info

return - returns a functionLink or false if the element is not found in package $package
see - functionLink

Method getGlobalLink (line 3251)

mixed getGlobalLink( string $expr, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getGlobalLink()

HTMLSmartyConverter::getGlobalLink()

XMLDocBookpeardoc2Converter::getGlobalLink()

XMLDocBookConverter::getGlobalLink()

PDFdefaultConverter::getGlobalLink()

CHMdefaultConverter::getGlobalLink()

return false or a globalLink to $expr

Parameters

string $expr: global variable name (with leading $)
string $package: package name
$file:
$text:

Info

return - returns a defineLink or false if the element is not found in package $package
see - defineLink

Method getGlobalValue (line 5213)

string getGlobalValue( string $value)

Overridden in child classes as:

PDFdefaultConverter::getGlobalValue()

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

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

$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

Parameters

string $value: default value of a global variable.

Info

return - default global variable value with link to class if it's "new Class"

Method getHighlightState (line 588)

void getHighlightState( )

Info

Method getId (line 3952)

string getId( abstractLink &$link)

Overridden in child classes as:

HTMLframesConverter::getId()

HTMLSmartyConverter::getId()

XMLDocBookpeardoc2Converter::getId(): Get the id value needed to allow linking

XMLDocBookConverter::getId(): Get the id value needed to allow linking

CHMdefaultConverter::getId()

take abstractLink descendant and text $eltext and return a

unique ID in the format needed for the Converter

Parameters

abstractLink &$link:

Info

return - unique identifier of $element
abstract -

Method getIncludeValue (line 5254)

string getIncludeValue( string $value, string $ipath)

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:

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

Parameters

string $value: file included by include statement.
string $ipath: path of file that has the include statement

Info

return - included file with link to docs for file, if found

Method getLink (line 3565)

mixed &getLink( string $expr, [string $package = false], [array $packages = false])

Overridden in child classes as:

XMLDocBookpeardoc2Converter::getLink(): do that stuff in $template_options

XMLDocBookConverter::getLink(): do that stuff in $template_options

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

$expr is a string with many allowable formats:

proceduralpagename.ext
constant_name
classname::function()
classname::constantname
classname::$variablename
classname
object classname
function functionname()
global $globalvarname
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.

class myclass
{
// from inside the class definition, use "function conflict()" to refer to procedural function "conflict()"
function conflict()
{
}
}
function conflict()
{
}

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

Parameters

string $expr: expression to search for a link
string $package: package to start searching in
array $packages: list of all packages to search in

Info

return - getLink returns a descendant of abstractLink if it finds a link, otherwise it returns a string
see - pageLink, functionLink, defineLink, classLink, methodLink, varLink
see - Converter::getPageLink(), Converter::getDefineLink(), Converter::getVarLink(), Converter::getFunctionLink(), Converter::getClassLink()

Method getMethodLink (line 3300)

mixed getMethodLink( string $expr, string $class, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getMethodLink()

HTMLSmartyConverter::getMethodLink()

XMLDocBookpeardoc2Converter::getMethodLink()

XMLDocBookConverter::getMethodLink()

PDFdefaultConverter::getMethodLink()

CHMdefaultConverter::getMethodLink()

return false or a methodLink to $expr in $class

Parameters

string $expr: method name
string $class: class name
string $package: package name
$file:
$text:

Info

return - returns a methodLink or false if the element is not found in package $package, class $class
see - methodLink

Method getPageLink (line 3275)

mixed getPageLink( string $expr, string $package, [ $path = false], [ $text = false], [ $packages = false])

Overridden in child classes as:

HTMLframesConverter::getPageLink()

HTMLSmartyConverter::getPageLink()

XMLDocBookpeardoc2Converter::getPageLink()

XMLDocBookConverter::getPageLink()

PDFdefaultConverter::getPageLink()

CHMdefaultConverter::getPageLink()

return false or a pageLink to $expr

Parameters

string $expr: procedural page name
string $package: package name
$path:
$text:
$packages:

Info

return - returns a pageLink or false if the element is not found in package $package
see - pageLink

Method getSortedClassTreeFromClass (line 2954)

array getSortedClassTreeFromClass( string $class, string $package, string $subpackage)

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:

class X extends Y
{
...
}

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

Parameters

string $class: class name
string $package:
string $subpackage:

Info

return - Format: see docs
see - HTMLframesConverter::getRootTree()

Method getSourceLink (line 1105)

string getSourceLink( $path)

Overridden in child classes as:

HTMLframesConverter::getSourceLink()

HTMLSmartyConverter::getSourceLink()

PDFdefaultConverter::getSourceLink()

CHMdefaultConverter::getSourceLink()

Parameters

$path:

Info

return - an output-format dependent link to phpxref-style highlighted source code
abstract -
usedby - parserFileSourceTag::getSourceLink()

Method getState (line 5382)

void getState( )

Overridden in child classes as:

PDFdefaultConverter::getState()

Return parserStringWithInlineTags::Convert() cache state

Info

see - parserStringWithInlineTags::Convert()
abstract -

Method getTutorialId (line 1418)

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

Overridden in child classes as:

HTMLframesConverter::getTutorialId()

HTMLSmartyConverter::getTutorialId()

XMLDocBookpeardoc2Converter::getTutorialId()

XMLDocBookConverter::getTutorialId()

PDFdefaultConverter::getTutorialId()

CHMdefaultConverter::getTutorialId()

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

Used by {@id}

Parameters

$package:
$subpackage:
$tutorial:
$id:

Info

usedby - parserTocInlineTag::Convert() - retrieve the tutorial ID for
usedby - parserIdInlineTag::Convert() - retrieve converter-specific ID

Method getTutorialLink (line 3417)

tutorialLink|string getTutorialLink( string $expr, [string $package = false], [string $subpackage = false], [array $packages = 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:

* @tutorial package/subpackage/file.cls
* @tutorial package/file.cls
* @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:

current package/subpackage
all other subpackages of current package
parent package, if this package has classes that extend classes in another package
all other packages

Parameters

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

Info

return - returns either a link, or the original text, if not found
since - 1.2

Method getTutorialTree (line 1974)

array getTutorialTree( parserTutorial|array $tutorial)

Overridden in child classes as:

HTMLframesConverter::getTutorialTree()

HTMLSmartyConverter::getTutorialTree()

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(...)
                        )
                      )
      )

Parameters

parserTutorial|array $tutorial:

Info

tutorial - phpDocumentor Tutorials

Method getVarLink (line 3327)

mixed getVarLink( string $expr, string $class, string $package, [ $file = false], [ $text = false])

Overridden in child classes as:

HTMLframesConverter::getVarLink()

HTMLSmartyConverter::getVarLink()

XMLDocBookpeardoc2Converter::getVarLink()

XMLDocBookConverter::getVarLink()

PDFdefaultConverter::getVarLink()

CHMdefaultConverter::getVarLink()

return false or a varLink to $expr in $class

Parameters

string $expr: var name
string $class: class name
string $package: package name
$file:
$text:

Info

return - returns a varLink or false if the element is not found in package $package, class $class
see - varLink

Method hasSourceCode (line 1159)

boolean hasSourceCode( string $path)

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

Wrapper for $sourcePaths in this version

Parameters

string $path: full path to the source code file

Info

Method hasTutorial (line 490)

false|parserTutorial hasTutorial( pkg|cls|proc $type, tutorial $name, string $package, [string $subpackage = ''])

Parameters

pkg|cls|proc $type: the tutorial type to search for
tutorial $name: name
string $package: package name
string $subpackage: subpackage name, if any

Info

return - if the tutorial exists, return it

Method highlightDocBlockSource (line 690)

string highlightDocBlockSource( string $token, string $word, [boolean $preformatted = false])

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

Parameters

string $token: name of docblock token type
string $word: contents of token
boolean $preformatted: whether the contents are preformatted or need modification

Info

Method highlightSource (line 637)

string highlightSource( integer $token, string $word, [boolean $preformatted = false])

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

default returns it unchanged. Mainly used by the HighlightParser

Parameters

integer $token: token value from tokenizer constants
string $word: contents of token
boolean $preformatted: whether the contents are preformatted or need modification

Info

Method highlightTutorialSource (line 728)

string highlightTutorialSource( string $token, string $word, [boolean $preformatted = false])

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

Parameters

string $token: name of docblock token type
string $word: contents of token
boolean $preformatted: whether the contents are preformatted or need modification

Info

Method Italicize (line 945)

string Italicize( string $para)

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

Parameters

string $para:

Info

usedby - parserI::Convert()

Method Kbdize (line 973)

string Kbdize( string $para)

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

Parameters

string $para:

Info

usedby - parserKbd::Convert()

Method ListItem (line 874)

string ListItem( string $item)

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

Parameters

string $item:

Info

usedby - parserList::Convert() - enclose each item of the list

Method newSmarty (line 5075)

Smarty &newSmarty( )

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.

Info

Method Output (line 5137)

void Output( $title)

Overridden in child classes as:

HTMLframesConverter::Output(): This function is not used by HTMLdefaultConverter, but is required by Converter

HTMLSmartyConverter::Output(): This function is not used by HTMLdefaultConverter, but is required by Converter

XMLDocBookpeardoc2Converter::Output(): Generate the constants.xml, packagename.xml, and globals.xml files

XMLDocBookConverter::Output(): This function is not used by HTMLdefaultConverter, but is required by Converter

PDFdefaultConverter::Output(): calls Cezpdf::ezOutput() and writes documentation.pdf to targetDir

CHMdefaultConverter::Output(): Create the phpdoc.hhp, contents.hhc files needed by MS HTML Help Compiler to create a CHM file

do all necessary output

Parameters

$title:

Info

see - Converter
abstract -
usedby - phpDocumentor_IntermediateParser::Convert()

Method postProcess (line 1016)

string postProcess( $text)

Overridden in child classes as:

HTMLframesConverter::postProcess(): Uses htmlspecialchars() on the input

HTMLSmartyConverter::postProcess(): Uses htmlspecialchars() on the input

XMLDocBookpeardoc2Converter::postProcess()

XMLDocBookConverter::postProcess()

PDFdefaultConverter::postProcess()

CHMdefaultConverter::postProcess(): Uses htmlspecialchars() on the input

This version does nothing

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

Parameters

$text:

Info

usedby - Converter::convertDefine() - on define_value template value, makes it displayable
usedby - Converter::convertGlobal() - on global_value template value, makes it displayable

Method prepareDocBlock (line 4480)

array prepareDocBlock( mixed &$element, [array $names = array()], [boolean $nopackage = true])

Overridden in child classes as:

XMLDocBookpeardoc2Converter::prepareDocBlock()

XMLDocBookConverter::prepareDocBlock()

convert the element's DocBlock for output

This function converts all tags and descriptions for output

Parameters

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

Info

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 ]
      )

Method PreserveWhiteSpace (line 903)

string PreserveWhiteSpace( string $string)

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

Parameters

string $string:

Info

usedby - parserPre::Convert()

Method ProgramExample (line 785)

string ProgramExample( string $example, [boolean $tutorial = false], [ $inlinesourceparse = null], [ $class = null], [ $linenum = null], [ $filesourcepath = null])

Overridden in child classes as:

HTMLframesConverter::ProgramExample(): Used to convert the <code> tag in a docblock

HTMLSmartyConverter::ProgramExample(): Used to convert the <code> tag in a docblock

XMLDocBookpeardoc2Converter::ProgramExample()

CHMdefaultConverter::ProgramExample(): Used to convert the <code> tag in a docblock

Used to convert the <code> tag in a docblock

Parameters

string $example:
boolean $tutorial: true if this is to highlight a tutorial <programlisting>
$inlinesourceparse:
$class:
$linenum:
$filesourcepath:

Info

usedby - parserCode::Convert()

Method returnLink (line 3929)

string returnLink( string $link, string $text)

Overridden in child classes as:

HTMLframesConverter::returnLink()

HTMLSmartyConverter::returnLink()

XMLDocBookpeardoc2Converter::returnLink()

XMLDocBookConverter::returnLink()

PDFdefaultConverter::returnLink()

CHMdefaultConverter::returnLink()

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

Parameters

string $link: URL
string $text: text to display

Info

return - link to $link
abstract -

Method returnSee (line 3941)

string returnSee( abstractLink &$link, [string $eltext = false])

Overridden in child classes as:

HTMLframesConverter::returnSee(): This function takes an abstractLink descendant and returns an html link

HTMLSmartyConverter::returnSee(): This function takes an abstractLink descendant and returns an html link

XMLDocBookpeardoc2Converter::returnSee(): This function takes an abstractLink descendant and returns an html link

XMLDocBookConverter::returnSee(): This function takes an abstractLink descendant and returns an html link

PDFdefaultConverter::returnSee(): Returns a bookmark using Cezpdf 009

CHMdefaultConverter::returnSee(): This function takes an abstractLink descendant and returns an html link

take abstractLink descendant and text $eltext and return a link

in the format needed for the Converter

Parameters

abstractLink &$link:
string $eltext:

Info

return - link to $element
abstract -

Method Sampize (line 987)

string Sampize( string $para)

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

Parameters

string $para:

Info

usedby - parserSamp::Convert()

Method setSourcePaths (line 1174)

void setSourcePaths( string $path)

Mark a file as having had source code highlighted

Parameters

string $path: full path of source file

Info

Method setTargetDir (line 5312)

void setTargetDir( string $dir)

Overridden in child classes as:

HTMLframesConverter::setTargetDir(): calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied

HTMLSmartyConverter::setTargetDir(): calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied

XMLDocBookConverter::setTargetDir(): calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied

CHMdefaultConverter::setTargetDir(): calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied

Sets the output directory for generated documentation

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

Parameters

string $dir: the output directory

Info

Method setTemplateBase (line 5148)

void setTemplateBase( string $base, string $dir)

Set the template directory with a different template base directory

Parameters

string $base: template base directory
string $dir: template name

Info

tutorial - phpDocumentor Tutorial

Method setTemplateDir (line 5173)

void setTemplateDir( string $dir)

Overridden in child classes as:

XMLDocBookpeardoc2Converter::setTemplateDir()

XMLDocBookConverter::setTemplateDir()

PDFdefaultConverter::setTemplateDir()

CHMdefaultConverter::setTemplateDir()

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

Also sets $templateName to the $dir parameter

Parameters

string $dir: subdirectory

Info

Method sortPageContentsByElementType (line 2570)

void sortPageContentsByElementType( &$pages)

sorts $page_contents by element type as well as alphabetically

Parameters

&$pages:

Info

see - $sort_page_contents_by_element_type

Method sourceLine (line 1130)

string sourceLine( integer $linenumber, string $line, [false|string $path = false])

Overridden in child classes as:

HTMLframesConverter::sourceLine(): Return a line of highlighted source code with formatted line number

HTMLSmartyConverter::sourceLine(): Return a line of highlighted source code with formatted line number

CHMdefaultConverter::sourceLine(): Return a line of highlighted source code with formatted line number

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

Parameters

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.

Info

return - formatted source code line with line number

Method startHighlight (line 582)

void startHighlight( )

Initialize highlight caching

Info

Method TranslateEntity (line 1184)

void TranslateEntity( string $name)

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

Parameters

string $name: entity name

Info

usedby - parserEntity::Convert() - convert contents to text

Method TranslateTag (line 1214)

string TranslateTag( string $name, string $attr, string $cdata, string $unconvertedcdata)

Overridden in child classes as:

PDFdefaultConverter::TranslateTag(): Used to translate an XML DocBook tag from a tutorial by reading the options.ini file for the template.

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

Parameters

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

Info

usedby - parserXMLDocBookTag::Convert() - Calls this to enclose the contents of the DocBook tag based on the values in template options.ini file

Method TutorialExample (line 860)

void TutorialExample( string $example)

Overridden in child classes as:

HTMLframesConverter::TutorialExample()

HTMLSmartyConverter::TutorialExample()

CHMdefaultConverter::TutorialExample()

Parameters

string $example:

Info

Method type_adjust (line 759)

string type_adjust( string $typename)

Overridden in child classes as:

XMLDocBookpeardoc2Converter::type_adjust()

XMLDocBookConverter::type_adjust()

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

Parameters

string $typename:

Info

Method unmangle (line 574)

string unmangle( string $sourcecode)

Overridden in child classes as:

HTMLframesConverter::unmangle()

HTMLSmartyConverter::unmangle()

XMLDocBookpeardoc2Converter::unmangle()

XMLDocBookConverter::unmangle()

PDFdefaultConverter::unmangle()

CHMdefaultConverter::unmangle()

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)

Parameters

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

Info

deprecated - in favor of tokenizer-based highlighting. This will be removed for 2.0
usedby - parserSourceInlineTag::stringConvert() - remove the extraneous stuff from http://www.php.net/highlight_string

Method vardump_tree (line 2202)

string vardump_tree( $tree, [ $indent = ''])

Debugging function for dumping $tutorial_tree

Parameters

$tree:
$indent:

Info

Method Varize (line 959)

string Varize( string $para)

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

Parameters

string $para:

Info

usedby - parserDescVar::Convert()

Method walk (line 1705)

void walk( array &$pages, array &$package_pages)

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.}}

Parameters

array &$pages: Format: array(fullpath => parserData structure with full parserData::$elements and parserData::$class_elements.
array &$package_pages: Format: array(parserPackagePage 1, parserPackagePage 2,...)

Info

usedby - phpDocumentor_IntermediateParser::Convert() - passes $pages and $package_pages
uses - Converter::_createPkgElements() - sets up $elements and $pkg_elements array, as well as $links

Method walk_everything (line 2267)

void walk_everything( )

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