Class: Converter

Source Location: /PEAR/PhpDocumentor/phpDocumentor/Converter.inc

Class Converter

Class Overview

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

Located in /PEAR/PhpDocumentor/phpDocumentor/Converter.inc [line 74]

Author(s):

Greg Beaver <cellog@php.net>

API Tags:

Abstract:

Information Tags:

Version:	$Id: Converter.inc,v 1.39 2007/12/19 02:16:49 ashnazg Exp $
Since:	1.0rc1

Properties

Methods

[ Top ]

Descendants

Child Class	Description
CHMdefaultConverter	Generates files that MS HTML Help Worshop can use to create a MS Windows compiled help file (CHM)
XMLDocBookpeardoc2Converter	XML DocBook converter.
XMLDocBookConverter	XML DocBook converter.
HTMLSmartyConverter	HTML output converter.
HTMLframesConverter	HTML output converter.
PDFdefaultConverter	PDF output converter.

[ Top ]

Property Summary

array	$all_packages	All packages encountered in parsing
string\|false	$class	set to a classname if currently parsing a class, false if not
Classes	$classes	All class information, organized by path, and by package
array	$class_contents	alphabetical index of all methods and vars in a class by package/subpackage
Smarty	$class_data	template for the class currently being processed
array	$class_elements	alphabetized index of classes by package
mixed	$curfile	full path of the current file being converted
parserPage	$curpage	current procedural page being processed
array	$define_elements	alphabetized index of defines by package
array	$elements	alphabetical index of all elements
array	$function_elements	alphabetized index of functions by package
array	$global_elements	alphabetized index of global variables by package
boolean	$highlightingSource	Flag used to help converters determine whether to do special source highlighting
array	$leftindex	Controls which of the one-element-only indexes are generated.
string	$outputformat	output format of this converter
string	$package	package name currently being converted
array	$packagecategories	Packages associated with categories
array	$package_elements	alphabetical index of all elements sorted by package, subpackage, page, and class.
mixed	$package_output	set to value of -po commandline
array	$package_parents	Hierarchy of packages
string	$page	name of current page being converted
array	$page_contents	alphabetical index of all elements on a page by package/subpackage
Smarty	$page_data	template for the procedural page currently being processed
array	$page_elements	alphabetized index of procedural pages by package
bool	$parseprivate	controls processing of elements marked private with @access private
string	$path	path of current page being converted
array	$pkg_elements	alphabetical index of all elements, indexed by package/subpackage
boolean	$processSpecialRoots	This converter knows about the new root tree processing
bool	$quietmode	controls display of progress information while parsing.
string	$smarty_dir	Directory that the smarty templates are in
mixed	$sort_absolutely_everything	This is used if the content must be passed in the order it should be read, i.e. by package, procedural then classes
boolean	$sort_page_contents_by_type	This determines whether the $page_contents array should be sorted by element type as well as alphabetically by name
array	$sourcePaths	A list of files that have had source code generated
string	$subpackage	subpackage name currently being converted
mixed	$targetDir	directory that output is sent to. -t command-line sets this.
string	$templateDir	Directory that the template is in, relative to phpDocumentor root directory
string	$templateName	Name of the template, from last part of -o
array	$template_options	Options for each template, parsed from the options.ini file in the template base directory
string	$title
array	$todoList	List of all @todo tags and a link to the element with the @todo

[ Top ]

Method Summary

Converter	Converter()	Initialize Converter data structures
string	AttrToString()	Convert the attribute of a Tutorial docbook tag's attribute list
string	Bolden()	Used to convert the contents of <b> in a docblock
string	Br()	Used to convert <br> in a docblock
void	checkState()	Compare parserStringWithInlineTags::Convert() cache state to $state
void	cleanup()	Finish up parsing/cleanup directories
void	Convert()	Convert all elements to output format
void	convertClass()	Default Class Handler
void	convertConst()	Converts class constants for template output.
void	convertDefine()	Converts defines for template output
void	ConvertErrorLog()	Convert the phpDocumentor parsing/conversion error log
void	convertFunction()	Converts function for template output
void	convertGlobal()	Converts global variables for template output
void	convertInclude()	Converts includes for template output
void	convertMethod()	Converts method for template output
void	convertPage()	Default Page Handler
string	ConvertTitle()	Convert the title of a Tutorial docbook tag section
void	ConvertTodoList()	Convert the list of all @todo tags
void	&convertTutorial()	Default Tutorial Handler
void	convertVar()	Converts class variables for template output.
void	Convert_RIC()	Convert README/INSTALL/CHANGELOG file contents to output format
void	copyFile()	Copies a file from the template directory to the target directory
void	createParentDir()	Recursively creates all subdirectories that don't exist in the $dir path
string	EncloseList()	Used to convert the contents of <ol> or <ul> in a docblock
string	EncloseParagraph()	Used to enclose a paragraph in a docblock
void	endClass()	Called by walk() while converting, when the last class element has been parsed.
void	endPage()	Called by walk() while converting, when the last procedural page element has been parsed.
string	exampleProgramExample()	Used to convert the {@example} inline tag in a docblock.
string	flushHighlightCache()	Return the close text for the current token
void	formatIndex()	Called by walk() while converting.
void	formatLeftIndex()	Called by walk() while converting.
void	formatPkgIndex()	Called by walk() while converting.
string	formatTutorialTOC()	Creates a table of contents for a {@toc} inline tag in a tutorial
void	generateChildClassList()	returns a list of child classes
string	generateFormattedClassTree()	returns an array containing the class inheritance tree from the root object to the class.
array	getClassesOnPage()	gets a list of all classes declared on a procedural page represented by
mixed	getClassLink()	return false or a classLink to $expr
mixed	getConstLink()	return false or a constLink to $expr in $class
string	getConverterDir()	Get the absolute path to the converter's base directory
string	getCurrentPageLink()
string	getCurrentPageURL()	Return the path to the current
mixed	getDefineLink()	return false or a defineLink to $expr
string	getFileSourceName()	Translate the path info into a unique file name for the highlighted source code.
string	getFileSourcePath()	Return the fixed path to the source-code file folder.
array	getFormattedConflicts()
array	getFormattedDescMethods()	Get a list of methods in child classes that override this method
array	getFormattedDescVars()	Get a list of vars in child classes that override this var
string	getFormattedImplements()	returns an array containing the class inheritance tree from the root object to the class.
array	getFormattedInheritedConsts()	Return template-enabled list of inherited class constants
array	getFormattedInheritedMethods()	Return template-enabled list of inherited methods
array	getFormattedInheritedVars()	Return template-enabled list of inherited variables
array\|false	getFormattedMethodImplements()	Get the method this method(s) implemented from an interface, if any
array\|false	getFormattedOverrides()	Get the method this method overrides, if any
mixed	getFunctionLink()	return false or a functionLink to $expr
mixed	getGlobalLink()	return false or a globalLink to $expr
string	getGlobalValue()	Parse a global variable's default value for class initialization.
void	getHighlightState()
string	getId()	take abstractLink descendant and text $eltext and return a
string	getIncludeValue()	Parse an include's file to see if it is a file documented in this project
mixed	&getLink()	The meat of the @see tag and inline {@link} tag
mixed	getMethodLink()	return false or a methodLink to $expr in $class
mixed	getPageLink()	return false or a pageLink to $expr
array	getSortedClassTreeFromClass()	Return a tree of all classes that extend this class
string	getSourceLink()
void	getState()	Return parserStringWithInlineTags::Convert() cache state
string	getTutorialId()	Return a converter-specific id to distinguish tutorials and their sections
tutorialLink\|string	getTutorialLink()	The meat of the @tutorial tag and inline {@tutorial} tag
array	getTutorialTree()	Get a tree structure representing the hierarchy of tutorials
mixed	getVarLink()	return false or a varLink to $expr in $class
boolean	hasSourceCode()	Determine whether an element's file has generated source code, used for linking to line numbers of source.
false\|parserTutorial	hasTutorial()
string	highlightDocBlockSource()	Used to allow converters to format the source code of DocBlocks the way they'd like.
string	highlightSource()	Used to allow converters to format the source code the way they'd like.
string	highlightTutorialSource()	Used to allow converters to format the source code of Tutorial XML the way they'd like.
string	Italicize()	Used to convert the contents of <i> in a docblock
string	Kbdize()	Used to convert the contents of <kbd> in a docblock
string	ListItem()	Used to convert the contents of <li> in a docblock
Smarty	&newSmarty()	Return a Smarty template object to operate with
void	Output()	do all necessary output
string	postProcess()	This version does nothing
array	prepareDocBlock()	convert the element's DocBlock for output
string	PreserveWhiteSpace()	Used to convert the contents of <pre> in a docblock
string	ProgramExample()	Used to convert the <code> tag in a docblock
string	returnLink()	take URL $link and text $text and return a link in the format needed for the Converter
string	returnSee()	take abstractLink descendant and text $eltext and return a link
string	Sampize()	Used to convert the contents of <samp> in a docblock
void	setSourcePaths()	Mark a file as having had source code highlighted
void	setTargetDir()	Sets the output directory for generated documentation
void	setTemplateBase()	Set the template directory with a different template base directory
void	setTemplateDir()	sets the template directory based on the $outputformat and $name
void	sortPageContentsByElementType()	sorts $page_contents by element type as well as alphabetically
string	sourceLine()	Return a line of highlighted source code with formatted line number
void	startHighlight()	Initialize highlight caching
void	TranslateEntity()	Used to translate an XML DocBook entity like ” from a tutorial by reading the options.ini file for the template.
string	TranslateTag()	Used to translate an XML DocBook tag from a tutorial by reading the options.ini file for the template.
void	TutorialExample()
string	type_adjust()	Called by parserReturnTag::Convert() to allow converters to change type names to desired formatting
string	unmangle()	Called by parserSourceInlineTag::stringConvert() to allow converters to format the source code the way they'd like.
string	vardump_tree()	Debugging function for dumping $tutorial_tree
string	Varize()	Used to convert the contents of <var> in a docblock
void	walk()	called by phpDocumentor_IntermediateParser::Convert() to traverse the array of pages and their elements, converting them to the output format
void	walk_everything()	walk over elements by package rather than page
void	writeExample()	Write out the formatted source code for an example php file
void	writeFile()	Writes a file to target dir
void	writeSource()	Write out the formatted source code for a php file
void	_rmdir()	Completely remove a directory and its contents
void	_setHighlightCache()
string	_tutorial_path()	Returns the path to this tutorial as a string

[ Top ]

Properties

array $all_packages [line 366]

All packages encountered in parsing

API Tags:

See:

phpDocumentor_IntermediateParser::$all_packages

[ Top ]

string|false $class = false [line 105]

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

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$class : name of current class being converted
XMLDocBookConverter::$class : name of current class being converted

[ Top ]

Classes $classes [line 319]

All class information, organized by path, and by package

[ Top ]

array $class_contents = array() [line 269]

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

The class itself has a link under ###main

API Tags:

See:

Converter::formatLeftIndex()

[ Top ]

Smarty $class_data [line 165]

template for the class currently being processed

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$class_data : template for the class currently being processed
XMLDocBookConverter::$class_data : template for the class currently being processed

[ Top ]

array $class_elements = array() [line 208]

alphabetized index of classes by package

API Tags:

See:

Converter::$leftindex

[ Top ]

mixed $curfile [line 313]

full path of the current file being converted

[ Top ]

parserPage $curpage [line 171]

current procedural page being processed

[ Top ]

array $define_elements = array() [line 201]

alphabetized index of defines by package

API Tags:

See:

Converter::$leftindex

[ Top ]

array $elements = array() [line 187]

alphabetical index of all elements

API Tags:

See:

Converter::formatIndex(), HTMLframesConverter::formatIndex()

[ Top ]

array $function_elements = array() [line 222]

alphabetized index of functions by package

API Tags:

See:

Converter::$leftindex

[ Top ]

array $global_elements = array() [line 215]

alphabetized index of global variables by package

API Tags:

See:

Converter::$leftindex

[ Top ]

boolean $highlightingSource = false [line 325]

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

[ Top ]

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

Controls which of the one-element-only indexes are generated.

Generation of these indexes for large packages is time-consuming. This is an optimization feature. An example of how to use this is in HTMLframesConverter::$leftindex, and in HTMLframesConverter::formatLeftIndex(). These indexes are intended for use as navigational aids through documentation, but can be used for anything by converters.

API Tags:

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

Redefined in descendants as:

CHMdefaultConverter::$leftindex : indexes of elements by package that need to be generated
XMLDocBookpeardoc2Converter::$leftindex : indexes of elements by package that need to be generated
XMLDocBookConverter::$leftindex : indexes of elements by package that need to be generated
HTMLSmartyConverter::$leftindex : indexes of elements by package that need to be generated
HTMLframesConverter::$leftindex : indexes of elements by package that need to be generated
PDFdefaultConverter::$leftindex

[ Top ]

string $outputformat = 'Generic' [line 90]

output format of this converter

in Child converters, this will match the first part of the -o command-line as in -o HTML:frames:default "HTML"

Information Tags:

Tutorial:

phpDocumentor Tutorial

Redefined in descendants as:

[ Top ]

string $package = 'default' [line 95]

package name currently being converted

[ Top ]

array $packagecategories [line 359]

Packages associated with categories

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

API Tags:

See:

phpDocumentor_IntermediateParser::$packagecategories

[ Top ]

array $package_elements = array() [line 180]

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

API Tags:

Uses:

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

[ Top ]

mixed $package_output [line 141]

set to value of -po commandline

Information Tags:

Tutorial:

phpDocumentor Tutorial

[ Top ]

array $package_parents [line 349]

Hierarchy of packages

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

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

API Tags:

See:

phpDocumentor_IntermediateParser::$package_parents

[ Top ]

string $page [line 147]

name of current page being converted

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$page : name of current page being converted
XMLDocBookConverter::$page : name of current page being converted

[ Top ]

array $page_contents = array() [line 238]

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

The page itself has a link under ###main

API Tags:

See:

Converter::formatLeftIndex()

[ Top ]

Smarty $page_data [line 159]

template for the procedural page currently being processed

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$page_data : template for the procedural page currently being processed
XMLDocBookConverter::$page_data : template for the procedural page currently being processed

[ Top ]

array $page_elements = array() [line 194]

alphabetized index of procedural pages by package

API Tags:

See:

Converter::$leftindex

[ Top ]

bool $parseprivate [line 276]

controls processing of elements marked private with @access private

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

[ Top ]

string $path [line 153]

path of current page being converted

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$path : path of current page being converted
XMLDocBookConverter::$path : path of current page being converted

[ Top ]

array $pkg_elements = array() [line 229]

alphabetical index of all elements, indexed by package/subpackage

API Tags:

See:

Converter::formatPkgIndex(), HTMLframesConverter::formatPkgIndex()

[ Top ]

boolean $processSpecialRoots = false [line 81]

This converter knows about the new root tree processing

In order to fix PEAR Bug #6389

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$processSpecialRoots : This converter knows about the new root tree processing
HTMLSmartyConverter::$processSpecialRoots : This converter knows about the new root tree processing
HTMLframesConverter::$processSpecialRoots : This converter knows about the new root tree processing

[ Top ]

bool $quietmode [line 283]

controls display of progress information while parsing.

defaults to false. Set to true for cron jobs or other situations where no visual output is necessary

[ Top ]

string $smarty_dir = '' [line 301]

Directory that the smarty templates are in

Redefined in descendants as:

PDFdefaultConverter::$smarty_dir

[ Top ]

mixed $sort_absolutely_everything = false [line 251]

This is used if the content must be passed in the order it should be read, i.e. by package, procedural then classes

This fixes bug 637921, and is used by PDFdefaultConverter

API Tags:

Usedby:

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

Redefined in descendants as:

XMLDocBookpeardoc2Converter::$sort_absolutely_everything : Pass elements by package, simplifies generation of package.xml/category.xml
PDFdefaultConverter::$sort_absolutely_everything : default PDF Converter wants elements sorted by type as well as alphabetically

[ Top ]

boolean $sort_page_contents_by_type = false [line 245]

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

API Tags:

See:

Converter::sortPageContentsByElementType()

Redefined in descendants as:

CHMdefaultConverter::$sort_page_contents_by_type : CHMdefaultConverter wants elements sorted by type as well as alphabetically
XMLDocBookpeardoc2Converter::$sort_page_contents_by_type : XMLDocBookConverter wants elements sorted by type as well as alphabetically
XMLDocBookConverter::$sort_page_contents_by_type : XMLDocBookConverter wants elements sorted by type as well as alphabetically
HTMLSmartyConverter::$sort_page_contents_by_type : Smarty Converter wants elements sorted by type as well as alphabetically
HTMLframesConverter::$sort_page_contents_by_type : Smarty Converter wants elements sorted by type as well as alphabetically

[ Top ]

array $sourcePaths = array() [line 372]

A list of files that have had source code generated

[ Top ]

string $subpackage = '' [line 100]

subpackage name currently being converted

[ Top ]

mixed $targetDir = '' [line 289]

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

Information Tags:

Tutorial:

phpDocumentor Tutorial

[ Top ]

string $templateDir = '' [line 295]

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

[ Top ]

string $templateName = '' [line 308]

Name of the template, from last part of -o

Information Tags:

Tutorial:

phpDocumentor Tutorial

[ Top ]

array $template_options [line 399]

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

Information Tags:

Tutorial:&nb

	Converters

[ class tree: Converters ] [ index: Converters ] [ all elements ]