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:
Located in /phpDocumentor/Converter.inc (line 74)
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) |
All packages encountered in parsing
set to a classname if currently parsing a class, false if not
alphabetical index of all methods and vars in a class by package/subpackage
The class itself has a link under ###main
template for the class currently being processed
alphabetized index of classes by package
full path of the current file being converted
current procedural page being processed
alphabetized index of defines by package
alphabetical index of all elements
alphabetized index of functions by package
alphabetized index of global variables by package
Flag used to help converters determine whether to do special source highlighting
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.
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"
package name currently being converted
Packages associated with categories
Used by the XML:DocBook/peardoc2 converter, and available to others, to group many packages into categories
alphabetical index of all elements sorted by package, subpackage, page, and class.
set to value of -po commandline
Hierarchy of packages
Every package that contains classes may have parent or child classes in other packages. In other words, this code is legal:
In this case, package one is a parent of package two
name of current page being converted
alphabetical index of all elements on a page by package/subpackage
The page itself has a link under ###main
template for the procedural page currently being processed
alphabetized index of procedural pages by package
controls processing of elements marked private with @access private
defaults to false. Set with command-line --parseprivate or -pp
path of current page being converted
alphabetical index of all elements, indexed by package/subpackage
This converter knows about the new root tree processing
In order to fix PEAR Bug #6389
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
Directory that the smarty templates are in
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
This determines whether the $page_contents array should be sorted by element type as well as alphabetically by name
A list of files that have had source code generated
subpackage name currently being converted
directory that output is sent to. -t command-line sets this.
Directory that the template is in, relative to phpDocumentor root directory
Name of the template, from last part of -o
Options for each template, parsed from the options.ini file in the template base directory
Initialize Converter data structures
Convert the attribute of a Tutorial docbook tag's attribute list
to a string based on the template options.ini
Used to convert the contents of <b> in a docblock
Used to convert <br> in a docblock
Compare parserStringWithInlineTags::Convert() cache state to $state
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.
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.}}
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
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()}}
Convert the phpDocumentor parsing/conversion error log
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
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()}}
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
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
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.}}
Convert the title of a Tutorial docbook tag section
to a string based on the template options.ini
Convert the list of all @todo tags
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.}}
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
Convert README/INSTALL/CHANGELOG file contents to output format
Copies a file from the template directory to the target directory
thanks to Robert Hoffmann for this fix
Recursively creates all subdirectories that don't exist in the $dir path
Used to convert the contents of <ol> or <ul> in a docblock
Used to enclose a paragraph in a docblock
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
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
Used to convert the {@example} inline tag in a docblock.
By default, this just wraps ProgramExample
Return the close text for the current token
Called by walk() while converting.
This method is intended to be the place that $elements is formatted for output.
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
Called by walk() while converting.
This method is intended to be the place that $pkg_elements is formatted for output.
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
returns a list of child classes
returns an array containing the class inheritance tree from the root object to the class.
This method must be overridden, or phpDocumentor will halt with a fatal error
gets a list of all classes declared on a procedural page represented by
$element, a parserData class
return false or a classLink to $expr
return false or a constLink to $expr in $class
Get the absolute path to the converter's base directory
Return the path to the current
return false or a defineLink to $expr
Translate the path info into a unique file name for the highlighted source code.
Return the fixed path to the source-code file folder.
Get a list of methods in child classes that override this method
Get a list of vars in child classes that override this var
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 template-enabled list of inherited class constants
uses parserConst helper function getInheritedConsts and generates a template-enabled list using getClassLink()
Return template-enabled list of inherited methods
uses parserMethod helper function getInheritedMethods and generates a template-enabled list using getClassLink()
Return template-enabled list of inherited variables
uses parserVar helper function getInheritedVars and generates a template-enabled list using getClassLink()
Get the method this method(s) implemented from an interface, if any
Get the method this method overrides, if any
return false or a functionLink to $expr
return false or a globalLink to $expr
Parse a global variable's default value for class initialization.
If a global variable's default value is "new class" as in:
take abstractLink descendant and text $eltext and return a
unique ID in the format needed for the Converter
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:
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:
The meat of the @see tag and inline {@link} tag
$expr is a string with many allowable formats:
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.
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
return false or a methodLink to $expr in $class
return false or a pageLink to $expr
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.
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:
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
Return parserStringWithInlineTags::Convert() cache state
Return a converter-specific id to distinguish tutorials and their sections
Used by {@id}
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:
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:
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(...) ) ) )
return false or a varLink to $expr in $class
Determine whether an element's file has generated source code, used for linking to line numbers of source.
Wrapper for $sourcePaths in this version
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
Used to allow converters to format the source code the way they'd like.
default returns it unchanged. Mainly used by the HighlightParser
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
Used to convert the contents of <i> in a docblock
Used to convert the contents of <kbd> in a docblock
Used to convert the contents of <li> in a docblock
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.
do all necessary output
This version does nothing
Perform necessary post-processing of string data. For example, the HTML Converters should escape < and > to become < and >
convert the element's DocBlock for output
This function converts all tags and descriptions for output
Used to convert the contents of <pre> in a docblock
Used to convert the <code> tag in a docblock
take URL $link and text $text and return a link in the format needed for the Converter
take abstractLink descendant and text $eltext and return a link
in the format needed for the Converter
Used to convert the contents of <samp> in a docblock
Mark a file as having had source code highlighted
Sets the output directory for generated documentation
As of 1.3.0RC6, this also sets the compiled templates directory inside the target directory
Set the template directory with a different template base directory
sets the template directory based on the $outputformat and $name
Also sets $templateName to the $dir parameter
sorts $page_contents by element type as well as alphabetically
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
Used to translate an XML DocBook entity like ” 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.
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
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)
Debugging function for dumping $tutorial_tree
Used to convert the contents of <var> in a docblock
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.}}
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
Write out the formatted source code for an example php file
This function provides the primary functionality for the @example tag.
Writes a file to target dir
Write out the formatted source code for a php file
This function provides the primary functionality for the @filesource tag.
Completely remove a directory and its contents
Returns the path to this tutorial as a string
Documentation generated on Mon, 05 Dec 2011 21:37:10 -0600 by phpDocumentor 1.4.4