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

Class: phpDocumentor_IntermediateParser

Source Location: /phpDocumentor/IntermediateParser.inc

Class phpDocumentor_IntermediateParser

Class Overview

The phpDocumentor_IntermediateParser Class

This class performs the work of organizing raw data from the parser in the format of descendants of the parserElement class. This is also where processing of package pages occurs, in phpDocumentor_IntermediateParser::handleClass() for class-level packages and phpDocumentor_IntermediateParser::handleDocBlock() for page-level packages.

Most of the work of this parser goes to matching up DocBlocks with the elements that they are documenting. Since DocBlocks are passed before the element they document, the last DocBlock is stored in phpDocumentor_IntermediateParser::$last and then placed into the $docblock parameter of the parserElement descendant object.

Located in /phpDocumentor/IntermediateParser.inc [line 60]



		
				Author(s):
		
  • Gregory Beaver
Information Tags:
Version:  $Id: IntermediateParser.inc 317234 2011-09-24 05:03:55Z ashnazg $
Copyright:  2002 Gregory Beaver

Properties

Methods

[ Top ]
Property Summary
array   $all_packages   list of all packages encountered while documenting. Used in automatic linking.
Classes   $classes   used to keep track of inheritance at the smartest level possible for a
array   $converters   an array of template names indexed by converter name
string   $cur_class   Name of the class currently being parsed.
parserData   $data   $data contains parsed structures for the current page being parsed
mixed   $db_template  
mixed   $event_handlers   the functions which handle output from the Parser
parserDocBlock   $last  
string   $lasttype   type of the last parser Element handled
array   $packagecategories   Used to determine the category for tutorials.
false|array   $packageoutput   array of packages to parser and output documentation for, if not all packages should be documented
array   $package_pages   array of parsed package pages
array   $package_parents   Keeps track of packages of classes that have parent classes in another package. Used in automatic linking.
array   $pages  
boolean   $parsePrivate   set in Setup.inc.php to the value of the parseprivate commandline
array   $privatepages   Put away a page that has been @ignored or @access private if !$parsePrivate
mixed   $private_class   this variable is used to prevent parsing of elements with an @ignore tag
ProceduralPages   $proceduralpages   used to keep track of all elements in a procedural page. Handles name
boolean   $quietMode   set in Setup.inc.php to the value of the quitemode commandline option.
array   $ric   Stores parsed CHANGELOG/INSTALL/README files
mixed   $targetDir   used to set the output directory
mixed   $templateBase   used to set the template base directory
string   $title  
string   $type   type of the current parser Element being handled
boolean   $undocumentedElementWarnings   set in Setup.inc.php to the value of the undocumentedElementWarnings commandline option.
mixed   $uses  

[ Top ]
Method Summary
phpDocumentor_IntermediateParser   phpDocumentor_IntermediateParser()   sets up basic data structures
void   addConverter()   Add a converter name to use to the list of converters
void   addElementToPage()   adds a processed descendant of parserElement to the $pages array or $privatepages array
void   addPackageParent()   If the parent class of $class is in a different package, adds it to the
void   addPage()   Replaces the parserPage represented by $this->pages[$path] with $page
void   addPageIfNecessary()   add a new parserPage to the $pages array if none is found
void   addPrivatePage()   Adds a parserPage element to the parserData element in $this->privatepages[$path]
void   addUses()   Add all the @uses tags from $element to the $uses array so that @usedby
int   ClasselementCmp()   does a natural case sort on two class elements (either parserClass, parserMethod or parserVar
void   Convert()   Interface to the Converter
int   elementCmp()   does a natural case sort on two parserElement descendants
void   handleClass()   handles post-parsing of classes
void   handleConst()   handles post-parsing of class constants
void   handleDefine()   handles post-parsing of defines
void   handleDocBlock()   handles post-parsing of DocBlocks
void   HandleEvent()   called via Parser::parse() and Parser's inherited method Publisher::publishEvent()
void   handleFunction()   handles post-parsing of functions
void   handleGlobal()   handles post-parsing of global variables
void   handleInclude()   handles post-parsing of include/require/include_once/require_once
void   handleMethod()   handles post-parsing of class methods
void   handlePackagePage()   handles post-parsing of Package-level documentation pages.
void   handlePage()   handles post-parsing of procedural pages
void   handleTutorial()   handle post-parsing of Tutorials.
void   handleVar()   handles post-parsing of class vars
void   Output()   call this method once parsing has completed.
void   parsePackagePage()   Backward-compatibility only, use the new tutorials for more power
void   setParsePrivate()   set display of elements marked with @access private
void   setQuietMode()   set parsing information output mode (quiet or verbose)
void   setTargetDir()   Sets the output directory
void   setTemplateBase()   Sets the template base directory
void   setUndocumentedElementWarningsMode()   show warnings for undocumented elements
void   _guessPackage()   Guess the package/subpackage based on subdirectory if the --pear option

[ Top ]
Properties
array   $all_packages = array() [line 186]

list of all packages encountered while documenting. Used in automatic linking.

Converter::getLink() first checks if an ambiguous link is found in the current package. If not, it then checks in parent packages, and if still not found, uses this array to check in the rest of the packages before giving up

API Tags:
See:  Converter::getLink()


[ Top ]
Classes   $classes = false [line 268]

used to keep track of inheritance at the smartest level possible for a

dumb computer


[ Top ]
array   $converters = false [line 287]

an array of template names indexed by converter name

For example, if the default HTMLframesConverter is using the DOM/l0l33t template, the array will be

  1. $converters['frames''DOM/l0l33t'

API Tags:
See:  Converter


[ Top ]
string   $cur_class = '' [line 88]

Name of the class currently being parsed.

It is only used (and only valid) when phpDocumentor_IntermediateParser is parsing a class


[ Top ]
parserData   $data [line 237]

$data contains parsed structures for the current page being parsed

In version 1.1+, $data is only used to store the current page information. All handling of documented elements is handled by the ProceduralPages and Classes classes.


[ Top ]
mixed   $db_template [line 295]

[ Top ]
mixed   $event_handlers = array(
'docblock' => 'handleDocBlock',
'page' => 'handlePage',
'class' => 'handleClass',
'define' => 'handleDefine',
'function' => 'handleFunction',
'method' => 'handleMethod',
'var' => 'handleVar',
'const' => 'handleConst',
'packagepage' => 'handlePackagePage',
'include' => 'handleInclude',
'global' => 'handleGlobal',
'tutorial' => 'handleTutorial',
)
[line 214]

the functions which handle output from the Parser

API Tags:
See:  phpDocumentor_IntermediateParser::handlePackagePage(), phpDocumentor_IntermediateParser::handleInclude(), phpDocumentor_IntermediateParser::handleTutorial()
See:  phpDocumentor_IntermediateParser::handleDefine(), phpDocumentor_IntermediateParser::handleFunction(), phpDocumentor_IntermediateParser::handleMethod(), phpDocumentor_IntermediateParser::handleVar()
See:  handleEvent(), phpDocumentor_IntermediateParser::handleDocBlock(), phpDocumentor_IntermediateParser::handlePage(), phpDocumentor_IntermediateParser::handleClass()


[ Top ]
parserDocBlock   $last [line 65]

[ Top ]
string   $lasttype = '' [line 80]

type of the last parser Element handled

This is used in handleDocBlock to determine whether a DocBlock is a page-level DocBlock in conjunction with the parserData::$clean var. A page-level DocBlock is alwaysthe first DocBlock in a file, and must be followed by another DocBlock. The first test is handled by parserData::$clean, which is set to false on the first encounter of an element, and the second test is handled by this variable, which must be equal to "docblock"

API Tags:
See:  phpDocumentor_IntermediateParser::handleDocBlock()


[ Top ]
array   $packagecategories = array() [line 173]

Used to determine the category for tutorials.

WARNING: If more than one category exists, the last category encountered will overwrite the previous and will raise a big warning


[ Top ]
false|array   $packageoutput = false [line 206]

array of packages to parser and output documentation for, if not all packages should be documented

Format:
array(package1,package2,...)
or false if not set

Use this option to limit output similar to ignoring files. If you have some temporary files that you don't want to specify by name but don't want included in output, set a package name for all the elements in your project, and set packageoutput to that name. the default package will be ignored. Parsing speed does not improve. If you want to ignore files for speed reasons, use the ignore command-line option

API Tags:
See:  Io

Information Tags:
Tutorial:  -po, --packageoutput

[ Top ]
array   $package_pages = array() [line 133]

array of parsed package pages

used by Convert() to convert all package pages into output


[ Top ]
array   $package_parents = array() [line 164]

Keeps track of packages of classes that have parent classes in another package. Used in automatic linking.

This array is updated by addPackageParent(), which is called in Classes::processChild() to keep track of classes that descend from classes in different packages. In other words, if class foo is in package one, and class bar is in package two, an entry $package_parents['two'] = 'one' will be made.

API Tags:
See:  Converter::getLink()


[ Top ]
array   $pages = array() [line 138]

[ Top ]
boolean   $parsePrivate = false [line 106]

set in Setup.inc.php to the value of the parseprivate commandline

option. If this option is true, elements with an @access private tag will be parsed and displayed

Information Tags:
Tutorial:  -pp, --parseprivate

[ Top ]
array   $privatepages = array() [line 151]

Put away a page that has been @ignored or @access private if !$parsePrivate

When a page has @access private in its DocBlock, it is placed here instead of in $pages, to allow for proper Class parsing. Since classes and pages are parsed as if they were separate, this array allows public classes on private pages to retrieve information needed about the page that holds the class and to addPageIfNecessary() to the $pages array


[ Top ]
mixed   $private_class = false [line 113]

this variable is used to prevent parsing of elements with an @ignore tag

API Tags:
See:  phpDocumentor_IntermediateParser::$parsePrivate
See:  phpDocumentor_IntermediateParser::$packageoutput


[ Top ]
ProceduralPages   $proceduralpages = false [line 276]

used to keep track of all elements in a procedural page. Handles name

conflicts with elegance

Information Tags:
Since:  1.1

[ Top ]
boolean   $quietMode = false [line 248]

set in Setup.inc.php to the value of the quitemode commandline option.

If this option is true, informative output while parsing will not be displayed (documentation is unaffected)

Information Tags:
Tutorial:  -q, --quiet

[ Top ]
array   $ric = array() [line 303]

Stores parsed CHANGELOG/INSTALL/README files


[ Top ]
mixed   $targetDir [line 119]

used to set the output directory

API Tags:
See:  phpDocumentor_IntermediateParser::setTargetDir()


[ Top ]
mixed   $templateBase [line 125]

used to set the template base directory

API Tags:
See:  phpDocumentor_IntermediateParser::setTemplateBase()


[ Top ]
string   $title = '' [line 291]

[ Top ]
string   $type = '' [line 97]

type of the current parser Element being handled

This is used by HandleEvent() to set the $lasttype var, which is used to detect page-level DocBlocks


[ Top ]
boolean   $undocumentedElementWarnings = false [line 261]

set in Setup.inc.php to the value of the undocumentedElementWarnings commandline option.

If this option is true, warnings about certain elements (classes, methods) that are not documented with DocBlocks will be shown while parsing, and will also be displayed in the errors.html page (other documentation is unaffected)

Information Tags:
Tutorial:  -ue, --undocumentedelements

[ Top ]
mixed   $uses = array() [line 293]

[ Top ]
Methods
Constructor phpDocumentor_IntermediateParser  [line 326]

  phpDocumentor_IntermediateParser phpDocumentor_IntermediateParser( [string $title = 'Generated Documentation']  )

sets up basic data structures

Parameters:
string   $title:  Title of generated documentation, passed to Converters

API Tags:
See:  phpDocumentor_IntermediateParser::$title, phpDocumentor_IntermediateParser::$data, phpDocumentor_IntermediateParser::$classes, phpDocumentor_IntermediateParser::$proceduralpages


[ Top ]
addConverter  [line 1710]

  void addConverter( string $output, string $name, string $template  )

Add a converter name to use to the list of converters

Sets up the $converters array.

Parameters:
string   $output:  output format (HTML, PDF, XML). Must be all caps
string   $name:  Converter name (frames, for example, is the name of HTMLframesConverter)
string   $template:  template to use, should be a relative path to the templates dir (like DOM/default)


[ Top ]
addElementToPage  [line 1476]

  void addElementToPage( parserElement $element, string $path  )

adds a processed descendant of parserElement to the $pages array or $privatepages array

This function expects the page to exist in either $pages or $privatepages. It calls the parserData::addElement() method to add $element to the page.

Parameters:
parserElement   $element:  this will actually be a descendant of parserElement
string   $path: 


[ Top ]
addPackageParent  [line 1687]

  void addPackageParent( parserClass &$class  )

If the parent class of $class is in a different package, adds it to the

$package_parents array

Parameters:
parserClass   &$class: 


[ Top ]
addPage  [line 1370]

  void addPage( parserPage $page, string $path  )

Replaces the parserPage represented by $this->pages[$path] with $page

Called by addPageIfNecessary(), handleDocBlock() and ProceduralPages::setupPages(), this method first checks to see if the page has been added. If not, it assumes that the page has either been @ignored or set with @access private with --parseprivate off, and returns addPrivatePage(). Otherwise, it sets the pages[$path] to be the parserPage $page and sets the package and subpackage to that of $page

Parameters:
parserPage   $page: 
string   $path:  full path to the file

API Tags:
See:  phpDocumentor_IntermediateParser::$pages


[ Top ]
addPageIfNecessary  [line 1400]

  void addPageIfNecessary( string $path, &$class  )

add a new parserPage to the $pages array if none is found

This method is used when a page has been @ignored or marked with @access private, and a public class is in the page (a class with no @access private in its DocBlock). The method first creates a new page in the $pages array and then copies path information, and calls addPage() to set up packages

Parameters:
string   $path:  full path of page
   &$class: 


[ Top ]
addPrivatePage  [line 1438]

  void addPrivatePage( parserPage $page, string $path  )

Adds a parserPage element to the parserData element in $this->privatepages[$path]

Performs a similar function to addPage, but adds to the $privatePages array

Parameters:
parserPage   $page: 
string   $path:  full path to the page

API Tags:
See:  phpDocumentor_IntermediateParser::addPage()


[ Top ]
addUses  [line 1507]

  void addUses( parserElement $element, string $path  )

Add all the @uses tags from $element to the $uses array so that @usedby

virtual tags can be added

Parameters:
parserElement   $element:  descendant of parserElement
string   $path:  full path to the file

API Tags:
Uses:  parserUsesTag::getSeeElement() - used to initialize $uses
Uses:  parserUsesTag::getDescription() - used to initialize $uses


[ Top ]
ClasselementCmp  [line 1777]

  int ClasselementCmp( mixed $a, mixed $b  )

does a natural case sort on two class elements (either parserClass, parserMethod or parserVar

Parameters:
mixed   $a: 
mixed   $b: 

API Tags:
See:  generateElementIndex()


[ Top ]
Convert  [line 1652]

  void Convert( $title, $converter  )

Interface to the Converter

This function simply passes $pages and package_pages to the walk() method, and then calls the Output() method. Note that Output() is not required to do anything, and in fact doesn't in HTMLframesConverter.

Parameters:
   $title: 
   $converter: 

API Tags:
Uses:  Converter::walk() - passes $pages and $package_pages
Uses:  Converter::Output()


[ Top ]
elementCmp  [line 1763]

  int elementCmp( mixed $a, mixed $b  )

does a natural case sort on two parserElement descendants

Parameters:
mixed   $a: 
mixed   $b: 

API Tags:
See:  generateElementIndex()


[ Top ]
handleClass  [line 905]

  void handleClass( integer $event, parserClass $data  )

handles post-parsing of classes

This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It sets $cur_class to its name, and if an @ignore tag is found in the DocBlock, it sets $private_class to true, to prevent post-parsing of any of the class's vars or methods. Then it checks for the existence of a package page for the class's package

Parameters:
integer   $event:  Event number from Parser.inc
parserClass   $data: 


[ Top ]
handleConst  [line 609]

  void handleConst( integer $event, parserVar $data  )

handles post-parsing of class constants

This function aligns $data's $path var and packages to match the parent object

Parameters:
integer   $event:  Event number from Parser.inc
parserVar   $data: 


[ Top ]
handleDefine  [line 849]

  void handleDefine( integer $event, parserDefine $data  )

handles post-parsing of defines

This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page and adds itself to the ProceduralPages class

Parameters:
integer   $event:  Event number from Parser.inc
parserDefine   $data: 


[ Top ]
handleDocBlock  [line 1047]

  void handleDocBlock( integer $event, parserDocBlock $data  )

handles post-parsing of DocBlocks

This function sets $last to the DocBlock represented by $data, to allow the next documentable element passed to phpDocumentor_IntermediateParser to link the DocBlock into its $docblock property. This function also checks for two special cases of DocBlocks:

  1. First DocBlock in the file contains a @package tag
  2. First DocBlock in the file is immediately followed by another DocBlock
In both cases, the function extracts this tag and uses it as the page-level package. If the @package tag is in the DocBlock of an element (function, global variable, whatever) that isn't a page-level DocBlock, a warning will be raised to notify the author that a @package tag belongs in a page-level DocBlock.

New in version 1.2.2, if the first DocBlock in a file contains a @package tag, it is a page-level DocBlock.

If the DocBlock is page-level, it is processed with _processPageLevelDocBlock

Finally, the function replaces the old parserPage in parserData::$data->parent with the new one containing information from the DocBlock by calling addPage(), and checks for package-level docs.

Parameters:
integer   $event:  Event number from Parser.inc
parserDocBlock   $data: 


[ Top ]
HandleEvent  [line 1227]

  void HandleEvent( integer $event, mixed $data  )

called via Parser::parse() and Parser's inherited method Publisher::publishEvent()

$event is one of the PHPDOC constants from Parser.inc. If it is not PHPDOCUMENTOR_EVENT_NEWSTATE, then a function name is retrieved from the $event_handlers array and called to handle the $data

Parameters:
integer   $event:  event number from Parser.inc
mixed   $data:  if $event is PHPDOCUMENTOR_EVENT_NEWSTATE, $data is a PHP_DOC_EVENT_END_PAGE or STATE_END_CLASS, otherwise $data is either a parserDocBlock, parserPage or descendant of parserElement

API Tags:
Global:  array $_phpDocumentor_setting$phpDocumentor_DefaultPackageName: we use 'sourcecode' to determine whether to highlight the source of the current file if it has no file-level docblock


[ Top ]
handleFunction  [line 763]

  void handleFunction( integer $event, parserFunction $data  )

handles post-parsing of functions

This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page, aligns the docblock's @param, @global, and @staticvar tags with the information parsed from the function source code.

If source code has been parsed by a {@source} tag, the source is added to its docblock, and then the parserFunction adds itself to the ProceduralPages class

Parameters:
integer   $event:  Event number from Parser.inc
parserFunction   $data: 


[ Top ]
handleGlobal  [line 459]

  void handleGlobal( integer $event, parserGlobal $data  )

handles post-parsing of global variables

This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page, and adds itself to the ProceduralPages class

Parameters:
integer   $event:  Event number from Parser.inc
parserGlobal   $data: 


[ Top ]
handleInclude  [line 403]

  void handleInclude( integer $event, parserInclude $data  )

handles post-parsing of include/require/include_once/require_once

This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page, and adds itself to the ProceduralPages class

Parameters:
integer   $event:  Event number from Parser.inc
parserInclude   $data: 


[ Top ]
handleMethod  [line 659]

  void handleMethod( integer $event, parserMethod $data  )

handles post-parsing of class methods

This function first aligns $data's path and package to match the parent object, and also aligns the docblock's @param, @global, and @staticvar tags with the information parsed from the method source code. It also checks to see if the method is a constructor and sets the $isConstructor flag. If source code has been parsed by a {@source} tag, the source is added to its docblock

Finally, it adds the method to the Classes class.

Parameters:
integer   $event:  Event number from Parser.inc
parserMethod   $data: 


[ Top ]
handlePackagePage  [line 515]

  void handlePackagePage( integer $event, parserPackagePage $data  )

handles post-parsing of Package-level documentation pages.

sets the $package_pages[$data->package] to $data

Parameters:
integer   $event:  Event number from Parser.inc
parserPackagePage   $data: 


[ Top ]
handlePage  [line 1001]

  void handlePage( integer $event, parserPage $data  )

handles post-parsing of procedural pages

this event is called at the start of a new page, before the Parser knows whether the page will contain any procedural pages or not

Parameters:
integer   $event:  Event number from Parser.inc
parserPage   $data: 


[ Top ]
handleTutorial  [line 530]

  void handleTutorial( integer $event, parserTutorial $data  )

handle post-parsing of Tutorials.

This adds the parsed tutorial to the tutorial tree

Parameters:
integer   $event:  Event Number
parserTutorial   $data: 

API Tags:
Uses:  $tutorials - sets the value of tutorials to parameter $data

Information Tags:
Since:  1.2

[ Top ]
handleVar  [line 550]

  void handleVar( integer $event, parserVar $data  )

handles post-parsing of class vars

This function sets up a @var tag if none is found, and aligns $data's $path var and packages to match the parent object

Parameters:
integer   $event:  Event number from Parser.inc
parserVar   $data: 


[ Top ]
Output  [line 1807]

  void Output( [ $title = "Generated Documentation"]  )

call this method once parsing has completed.

This method calls the private methods fixClasses and fixProcPages, both of which adjust inheritance and package information based on complicated post-parsing rules described in ProceduralPages::setupPages() and Classes::Inherit(). Then, it sorts elements of the $pages array and calls Convert for each Converter in the $converters array

Parameters:
   $title: 

API Tags:
See:  phpDocumentor_IntermediateParser::Convert()
See:  phpDocumentor_IntermediateParser::$pages
See:  phpDocumentor_IntermediateParser::$converters


[ Top ]
parsePackagePage  [line 1181]

  void parsePackagePage( string $package, string $path  )

Backward-compatibility only, use the new tutorials for more power

Parameters:
string   $package:  package name of package file to parse
string   $path:  directory of file that contains package name

Information Tags:
Tutorial:  phpDocumentor Tutorials

[ Top ]
setParsePrivate  [line 1931]

  void setParsePrivate( bool $parse  )

set display of elements marked with @access private

If set to true, elements will be displayed

Parameters:
bool   $parse: 


[ Top ]
setQuietMode  [line 1908]

  void setQuietMode( bool $quietMode  )

set parsing information output mode (quiet or verbose)

If set to false, no parsing information (parsing /php/file/thisfile.php, Converting etc.) will be displayed. Useful for cron jobs

Parameters:
bool   $quietMode: 


[ Top ]
setTargetDir  [line 1884]

  void setTargetDir( string $dir  )

Sets the output directory

Parameters:
string   $dir:  the output directory


[ Top ]
setTemplateBase  [line 1895]

  void setTemplateBase( string $dir  )

Sets the template base directory

Parameters:
string   $dir:  the template base directory

Information Tags:
Tutorial:  -tb, --templatebase

[ Top ]
setUndocumentedElementWarningsMode  [line 1920]

  void setUndocumentedElementWarningsMode( bool $undocumentedElementWarnings  )

show warnings for undocumented elements

If set to false, no warnings will be shown for undocumented elements. Useful for identifying classes and methods that haven't yet been documented.

Parameters:
bool   $undocumentedElementWarnings: 


[ Top ]
_guessPackage  [line 376]

  void _guessPackage( string $path, template-ready $sourceloc  )

Guess the package/subpackage based on subdirectory if the --pear option

A file in pear/dir/file.php will be in package "dir." A file in pear/dir/subdir/file.php will be in package "dir," subpackage "subdir."

Parameters:
string   $path:  full path of file
template-ready   $sourceloc:  source location Program_Root/dir/file.php

API Tags:
Global:  array $_phpDocumentor_setting: uses the 'pear' option to determine whether to guess based on subdirectory

Information Tags:
Tutorial:  -p, --pear

[ Top ]

Documentation generated on Tue, 06 Dec 2011 07:20:21 -0600 by phpDocumentor 1.4.4