Class: Converter
Source Location: /PhpDocumentor-1.5.0a1/phpDocumentor/Converter.inc
Base class for all output converters.
Author(s):
Version:
|
|
|
Child classes:
|
Inherited Variables
|
Inherited Methods
|
Class Details
Class Variables
$all_packages =
[line 366]
All packages encountered in parsing
$charset = 'iso-8859-1'
[line 398]
$class = false
[line 105]
set to a classname if currently parsing a class, false if not
$classes =
[line 319]
All class information, organized by path, and by package
$class_contents = array()
[line 269]
alphabetical index of all methods and vars in a class by package/subpackage The class itself has a link under ###main
$class_data =
[line 165]
template for the class currently being processed
$class_elements = array()
[line 208]
alphabetized index of classes by package
$curfile =
[line 313]
full path of the current file being converted
$curpage =
[line 171]
current procedural page being processed
$define_elements = array()
[line 201]
alphabetized index of defines by package
$elements = array()
[line 187]
alphabetical index of all elements
$function_elements = array()
[line 222]
alphabetized index of functions by package
$global_elements = array()
[line 215]
alphabetized index of global variables by package
$highlightingSource = false
[line 325]
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]
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.
$outputformat = 'Generic'
[line 90]
output format of this converter in Child converters, this will match the first part of the -o command-line as in -o HTML:frames:default "HTML"
$package = 'default'
[line 95]
package name currently being converted
$packagecategories =
[line 359]
Packages associated with categories Used by the XML:DocBook/peardoc2 converter, and available to others, to group many packages into categories
$package_elements = array()
[line 180]
alphabetical index of all elements sorted by package, subpackage, page, and class.
$package_output =
[line 141]
set to value of -po commandline
$package_parents =
[line 349]
Hierarchy of packages Every package that contains classes may have parent or child classes in other packages. In other words, this code is legal:
In this case, package one is a parent of package two
$page =
[line 147]
name of current page being converted
$page_contents = array()
[line 238]
alphabetical index of all elements on a page by package/subpackage The page itself has a link under ###main
$page_data =
[line 159]
template for the procedural page currently being processed
$page_elements = array()
[line 194]
alphabetized index of procedural pages by package
$parseprivate =
[line 276]
controls processing of elements marked private with @access private defaults to false. Set with command-line --parseprivate or -pp
$path =
[line 153]
path of current page being converted
$pkg_elements = array()
[line 229]
alphabetical index of all elements, indexed by package/subpackage
$processSpecialRoots = false
[line 81]
This converter knows about the new root tree processing In order to fix PEAR Bug #6389
$quietmode =
[line 283]
controls display of progress information while parsing. defaults to false. Set to true for cron jobs or other situations where no visual output is necessary
$smarty_dir = ''
[line 301]
Directory that the smarty templates are in
$sort_absolutely_everything = false
[line 251]
This is used if the content must be passed in the order it should be read, i.e. by package, procedural then classes This fixes bug 637921, and is used by PDFdefaultConverter
$sort_page_contents_by_type = false
[line 245]
This determines whether the $page_contents array should be sorted by element type as well as alphabetically by name
$sourcePaths = array()
[line 372]
A list of files that have had source code generated
$subpackage = ''
[line 100]
subpackage name currently being converted
$targetDir = ''
[line 289]
directory that output is sent to. -t command-line sets this.
$templateDir = ''
[line 295]
Directory that the template is in, relative to phpDocumentor root directory
$templateName = ''
[line 308]
Name of the template, from last part of -o
$template_options =
[line 405]
Options for each template, parsed from the options.ini file in the template base directory
$title = 'Generated Documentation'
[line 392]
$todoList = array()
[line 435]
List of all @todo tags and a link to the element with the @todo Format: array(package => array(link to element, array(todo parserTag,...)),...)
Method Detail
Converter (Constructor) [line 459]
Converter Converter(
array
&$allp, array
&$packp, Classes
&$classes, ProceduralPages
&$procpages, array
$po, boolean
$pp, boolean
$qm, string
$targetDir, string
$template, string
$title, string
$charset)
|
|
Initialize Converter data structures
Parameters:
AttrToString [line 1319]
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:
Bolden [line 939]
string Bolden(
string
$para)
|
|
Used to convert the contents of <b> in a docblock
Parameters:
Br [line 1009]
checkState [line 5406]
void checkState(
mixed
$state)
|
|
Compare parserStringWithInlineTags::Convert() cache state to $state
Parameters:
cleanup [line 5115]
Finish up parsing/cleanup directories
Convert [line 3994]
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:
convertClass [line 4058]
convertConst [line 4245]
convertDefine [line 4370]
ConvertErrorLog [line 2438]
convertFunction [line 4427]
convertGlobal [line 4336]
convertInclude [line 4399]
convertMethod [line 4125]
convertPage [line 4290]
ConvertTitle [line 1408]
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:
ConvertTodoList [line 2446]
convertTutorial [line 4022]
convertVar [line 4193]
Convert_RIC [line 3974]
copyFile [line 5381]
void copyFile(
string
$file, [
$subdir = ''])
|
|
Copies a file from the template directory to the target directory thanks to Robert Hoffmann for this fix
Parameters:
createParentDir [line 5297]
void createParentDir(
string
$dir)
|
|
Recursively creates all subdirectories that don't exist in the $dir path
Parameters:
EncloseList [line 896]
string EncloseList(
string
$list,
$ordered)
|
|
Used to convert the contents of <ol> or <ul> in a docblock
Parameters:
EncloseParagraph [line 925]
string EncloseParagraph(
string
$para)
|
|
Used to enclose a paragraph in a docblock
Parameters:
endClass [line 515]
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
Overridden in child classes as:
- XMLDocBookConverter::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
- CHMdefaultConverter::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
- HTMLframesConverter::endClass()
- Writes out the template file of $class_data and unsets the template to save memory
endPage [line 529]
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
Overridden in child classes as:
- 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
- HTMLSmartyConverter::endPage()
- Writes out the template file of $page_data and unsets the template to save memory
- HTMLframesConverter::endPage()
- Writes out the template file of $page_data and unsets the template to save memory
exampleProgramExample [line 781]
string exampleProgramExample(
string
$example, [boolean
$tutorial = false], [
$inlinesourceparse = null], [
$class = null], [
$linenum = null], [
$filesourcepath = null])
|
|
Used to convert the {@example} inline tag in a docblock. By default, this just wraps ProgramExample
Overridden in child classes as:
- XMLDocBookpeardoc2Converter::exampleProgramExample()
- Used to convert the {@example} inline tag in a docblock.
Parameters:
flushHighlightCache [line 617]
string flushHighlightCache(
)
|
|
Return the close text for the current token
formatIndex [line 553]
formatLeftIndex [line 567]
formatPkgIndex [line 541]
formatTutorialTOC [line 1038]
string formatTutorialTOC(
array
$toc)
|
|
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
Overridden in child classes as:
- CHMdefaultConverter::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
- HTMLframesConverter::formatTutorialTOC()
- Use the template tutorial_toc.tpl to generate a table of contents for HTML
Parameters:
generateChildClassList [line 4830]
generateFormattedClassTree [line 4677]
getClassesOnPage [line 4629]
gets a list of all classes declared on a procedural page represented by $element, a parserData class
Parameters:
getClassLink [line 3191]
getConstLink [line 3366]
getConverterDir [line 5202]
string getConverterDir(
)
|
|
Get the absolute path to the converter's base directory
getCurrentPageLink [line 1123]
getCurrentPageURL [line 1103]
string getCurrentPageURL(
string
$pathinfo)
|
|
Return the path to the current
Parameters:
getDefineLink [line 3239]
getFileSourceName [line 1078]
string getFileSourceName(
$path, string
$pathinfo)
|
|
Translate the path info into a unique file name for the highlighted source code.
Overridden in child classes as:
- PDFdefaultConverter::getFileSourceName()
Parameters:
getFileSourcePath [line 1091]
string getFileSourcePath(
string
$base)
|
|
Return the fixed path to the source-code file folder.
Parameters:
getFormattedConflicts [line 4730]
array getFormattedConflicts(
mixed
&$element, string
$type)
|
|
Parameters:
getFormattedDescMethods [line 4750]
Get a list of methods in child classes that override this method
Parameters:
getFormattedDescVars [line 4771]
array getFormattedDescVars(
parserVar
&$element)
|
|
Get a list of vars in child classes that override this var
Parameters:
getFormattedImplements [line 4693]
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:
getFormattedInheritedConsts [line 5035]
Return template-enabled list of inherited class constants uses parserConst helper function getInheritedConsts and generates a template-enabled list using getClassLink()
Parameters:
getFormattedInheritedMethods [line 4947]
Return template-enabled list of inherited methods uses parserMethod helper function getInheritedMethods and generates a template-enabled list using getClassLink()
Parameters:
getFormattedInheritedVars [line 4876]
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:
getFormattedMethodImplements [line 4809]
array|false getFormattedMethodImplements(
parserMethod
&$element)
|
|
Get the method this method(s) implemented from an interface, if any
Parameters:
getFormattedOverrides [line 4792]
Get the method this method overrides, if any
Parameters:
getFunctionLink [line 3215]
getGlobalLink [line 3263]
getGlobalValue [line 5226]
string getGlobalValue(
string
$value)
|
|
Parse a global variable's default value for class initialization. If a global variable's default value is "new class" as in:
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
Overridden in child classes as:
- PDFdefaultConverter::getGlobalValue()
Parameters:
getHighlightState [line 596]
void getHighlightState(
)
|
|
getId [line 3964]
getIncludeValue [line 5267]
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:
getLink [line 3577]
mixed &getLink(
string
$expr, [string
$package = false], [array
$packages = false])
|
|
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
Overridden in child classes as:
- XMLDocBookConverter::getLink()
- do that stuff in $template_options
- XMLDocBookpeardoc2Converter::getLink()
- do that stuff in $template_options
Parameters:
getMethodLink [line 3312]
getPageLink [line 3287]
getSortedClassTreeFromClass [line 2966]
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:
getSourceLink [line 1113]
getState [line 5395]
getTutorialId [line 1430]
getTutorialLink [line 3429]
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:
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:
getTutorialTree [line 1986]
getVarLink [line 3339]
hasSourceCode [line 1167]
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:
hasTutorial [line 498]
false|parserTutorial hasTutorial(
pkg|cls|proc
$type, tutorial
$name, string
$package, [string
$subpackage = ''])
|
|
Parameters:
highlightDocBlockSource [line 698]
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:
highlightSource [line 645]
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:
highlightTutorialSource [line 736]
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:
Italicize [line 953]
string Italicize(
string
$para)
|
|
Used to convert the contents of <i> in a docblock
Parameters:
Kbdize [line 981]
string Kbdize(
string
$para)
|
|
Used to convert the contents of <kbd> in a docblock
Parameters:
ListItem [line 882]
string ListItem(
string
$item)
|
|
Used to convert the contents of <li> in a docblock
Parameters:
newSmarty [line 5087]
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.
Output [line 5150]
postProcess [line 1024]
prepareDocBlock [line 4492]
PreserveWhiteSpace [line 911]
string PreserveWhiteSpace(
string
$string)
|
|
Used to convert the contents of <pre> in a docblock
Parameters:
ProgramExample [line 793]
returnLink [line 3941]
returnSee [line 3953]
Sampize [line 995]
string Sampize(
string
$para)
|
|
Used to convert the contents of <samp> in a docblock
Parameters:
setSourcePaths [line 1182]
void setSourcePaths(
string
$path)
|
|
Mark a file as having had source code highlighted
Parameters:
setTargetDir [line 5325]
void setTargetDir(
string
$dir)
|
|
Sets the output directory for generated documentation As of 1.3.0RC6, this also sets the compiled templates directory inside the target directory
Overridden in child classes as:
- 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
- HTMLSmartyConverter::setTargetDir()
- calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied
- HTMLframesConverter::setTargetDir()
- calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied
Parameters:
setTemplateBase [line 5161]
void setTemplateBase(
string
$base, string
$dir)
|
|
Set the template directory with a different template base directory
Parameters:
setTemplateDir [line 5186]
sortPageContentsByElementType [line 2582]
void sortPageContentsByElementType(
&$pages)
|
|
sorts $page_contents by element type as well as alphabetically
Parameters:
sourceLine [line 1138]
string sourceLine(
integer
$linenumber, string
$line, [false|string
$path = false])
|
|
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
Overridden in child classes as:
- CHMdefaultConverter::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
- HTMLframesConverter::sourceLine()
- Return a line of highlighted source code with formatted line number
Parameters:
startHighlight [line 590]
Initialize highlight caching
TranslateEntity [line 1192]
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:
TranslateTag [line 1222]
string TranslateTag(
string
$name, string
$attr, string
$cdata, string
$unconvertedcdata)
|
|
Used to translate an XML DocBook tag from a tutorial by reading the options.ini file for the template.
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.
Parameters:
TutorialExample [line 868]
type_adjust [line 767]
unmangle [line 582]
vardump_tree [line 2214]
string vardump_tree(
$tree, [
$indent = ''])
|
|
Debugging function for dumping $tutorial_tree
Parameters:
Varize [line 967]
string Varize(
string
$para)
|
|
Used to convert the contents of <var> in a docblock
Parameters:
walk [line 1717]
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:
walk_everything [line 2279]
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
writeExample [line 1068]
writeFile [line 5358]
void writeFile(
string
$file, string
$data, [boolean
$binary = false])
|
|
Writes a file to target dir
Overridden in child classes as:
- XMLDocBookpeardoc2Converter::writeFile()
- Writes a file to target dir, beautify any .xml files first
Parameters:
writeSource [line 1052]
Documentation generated on Mon, 11 Mar 2019 15:50:16 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.
|
|