Class phpDocumentor_IntermediateParser

(line 60)

Description




	Located in File: /phpDocumentor/IntermediateParser.inc





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.











Class Variables


Summary:



    array
    $all_packages




    Classes
    $classes




    array
    $converters




    string
    $cur_class




    parserData
    $data




    mixed
    $db_template




    mixed
    $event_handlers




    parserDocBlock
    $last




    string
    $lasttype




    array
    $packagecategories




    false|array
    $packageoutput




    array
    $package_pages




    array
    $package_parents




    array
    $pages




    boolean
    $parsePrivate




    array
    $privatepages




    mixed
    $private_class




    ProceduralPages
    $proceduralpages




    boolean
    $quietMode




    array
    $ric




    mixed
    $targetDir




    mixed
    $templateBase




    string
    $title




    string
    $type




    boolean
    $undocumentedElementWarnings




    mixed
    $uses









 $all_packages = array() (line 186)
 


Data type : array



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









 $classes =  false (line 268)
 


Data type : Classes



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


dumb computer


    
	








 $converters =  false (line 287)
 


Data type : array



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'
    2. 



    
		
  • var: - Format: array(Convertername1 => templatename)
    • 
		
  • see: - Converter
    • 
	








 $cur_class =  '' (line 88)
 


Data type : string



Name of the class currently being parsed.


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


    
	








 $data (line 237)
 


Data type : parserData



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


    
	








 $db_template (line 295)
 


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


Data type : mixed



the functions which handle output from the Parser









 $last (line 65)
 


Data type : parserDocBlock



    
	








 $lasttype =  '' (line 80)
 


Data type : string



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"









 $packagecategories = array() (line 173)
 


Data type : array



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


    
		
  • var: - Format: packagename => categoryname
    • 
	








 $packageoutput =  false (line 206)
 


Data type : false|array



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









 $package_pages = array() (line 133)
 


Data type : array



array of parsed package pages


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


    
	








 $package_parents = array() (line 164)
 


Data type : array



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.









 $pages = array() (line 138)
 


Data type : array



    
		
  • var: - array of all parserData containing page information
    • 
	








 $parsePrivate =  false (line 106)
 


Data type : boolean



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









 $privatepages = array() (line 151)
 


Data type : array



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


    
	








 $private_class =  false (line 113)
 


Data type : mixed



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









 $proceduralpages =  false (line 276)
 


Data type : ProceduralPages



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


conflicts with elegance


    
		
  • since: - 1.1
    • 
	








 $quietMode =  false (line 248)
 


Data type : boolean



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)









 $ric = array() (line 303)
 


Data type : array



Stores parsed CHANGELOG/INSTALL/README files


    
		
  • var: - Format: array(CHANGELOG => contents,                           INSTALL => contents,                           README => contents)
    • 
	








 $targetDir (line 119)
 


Data type : mixed



used to set the output directory









 $templateBase (line 125)
 


Data type : mixed



used to set the template base directory









 $title =  '' (line 291)
 


Data type : string



    
		
  • var: - Title of generated documentation, passed to Converters
    • 
	








 $type =  '' (line 97)
 


Data type : string



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


    
	








 $undocumentedElementWarnings =  false (line 261)
 


Data type : boolean



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)









 $uses = array() (line 293)
 


Data type : mixed



    
	










Class Constants


Summary:









Method Detail


Summary:



    

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

    

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

    

            void
        addElementToPage
        (parserElement $element, string $path)
        

    

            void
        addPackageParent
        (parserClass &$class)
        

    

            void
        addPage
        (parserPage $page, string $path)
        

    

            void
        addPageIfNecessary
        (string $path,  &$class)
        

    

            void
        addPrivatePage
        (parserPage $page, string $path)
        

    

            void
        addUses
        (parserElement $element, string $path)
        

    

            int
        ClasselementCmp
        (mixed $a, mixed $b)
        

    

            void
        Convert
        ( $title,  $converter)
        

    

            int
        elementCmp
        (mixed $a, mixed $b)
        

    

            void
        handleClass
        (integer $event, parserClass $data)
        

    

            void
        handleConst
        (integer $event, parserVar $data)
        

    

            void
        handleDefine
        (integer $event, parserDefine $data)
        

    

            void
        handleDocBlock
        (integer $event, parserDocBlock $data)
        

    

            void
        HandleEvent
        (integer $event, mixed $data)
        

    

            void
        handleFunction
        (integer $event, parserFunction $data)
        

    

            void
        handleGlobal
        (integer $event, parserGlobal $data)
        

    

            void
        handleInclude
        (integer $event, parserInclude $data)
        

    

            void
        handleMethod
        (integer $event, parserMethod $data)
        

    

            void
        handlePackagePage
        (integer $event, parserPackagePage $data)
        

    

            void
        handlePage
        (integer $event, parserPage $data)
        

    

            void
        handleTutorial
        (integer $event, parserTutorial $data)
        

    

            void
        handleVar
        (integer $event, parserVar $data)
        

    

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

    

            void
        parsePackagePage
        (string $package, string $path)
        

    

            void
        setParsePrivate
        (bool $parse)
        

    

            void
        setQuietMode
        (bool $quietMode)
        

    

            void
        setTargetDir
        (string $dir)
        

    

            void
        setTemplateBase
        (string $dir)
        

    

            void
        setUndocumentedElementWarningsMode
        (bool $undocumentedElementWarnings)
        

    

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











 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
    • 
		

		
	
Info

	





 Method 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)
    • 
		

		
	
Info

	
    
		






 Method 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: 
    • 
		

		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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
    • 
		

		
	
Info

	





 Method 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: 
    • 
		

		
	
Info

	
    
		






 Method 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
    • 
		

		
	
Info

	





 Method 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
    • 
		

		
	
Info

	





 Method 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: 
    • 
		

		
	
Info

	
    
			
  • see - generateElementIndex()
    • 
		






 Method 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: 
    • 
		

		
	
Info

	





 Method elementCmp (line 1763)
 
 

int elementCmp(
mixed
$a, mixed
$b)


	

does a natural case sort on two parserElement descendants

		
Parameters

	
    
			
  • mixed $a: 
    • 
			
  • mixed $b: 
    • 
		

		
	
Info

	
    
			
  • see - generateElementIndex()
    • 
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
			
  • 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
    • 
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method 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

	
		
	
Info

	
    
		






 Method handleTutorial (line 530)
 
 

void handleTutorial(
integer
$event, parserTutorial
$data)


	

handle post-parsing of Tutorials.


This adds the parsed tutorial to the tutorial tree

		
Parameters

	
		
	
Info

	
    
			
  • since - 1.2
    • 
			
  • uses - $tutorials - sets the value of tutorials to parameter $data
    • 
		






 Method 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

	
		
	
Info

	
    
		






 Method 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: 
    • 
		

		
	
Info

	





 Method 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
    • 
		

		
	
Info

	





 Method 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: 
    • 
		

		
	
Info

	
    
		






 Method 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: 
    • 
		

		
	
Info

	
    
		






 Method setTargetDir (line 1884)
 
 

void setTargetDir(
string
$dir)


	

Sets the output directory

		
Parameters

	
    
			
  • string $dir: the output directory
    • 
		

		
	
Info

	
    
		






 Method setTemplateBase (line 1895)
 
 

void setTemplateBase(
string
$dir)


	

Sets the template base directory

		
Parameters

	
    
			
  • string $dir: the template base directory
    • 
		

		
	
Info

	





 Method 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: 
    • 
		

		
	
Info

	
    
		






 Method _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
    • 
		

		
	
Info

	







Inherited Variables





Inherited Class Variable Summary


	




Inherited Methods





Inherited Method Summary


	




	

		

		Documentation generated on Mon, 05 Dec 2011 21:28:22 -0600 by phpDocumentor 1.4.4