Docs For Class ProceduralPages

Description

Located in File: /phpDocumentor/ProceduralPages.inc

Intermediate procedural page parsing structure.

This structure parses defines, functions, and global variables by file, and then iterates over the elements to document conflicts.

author: - Greg Beaver <[email protected]>
version: - Release: @VER@
copyright: - 2002-2008 Gregory Beaver
link: - http://pear.php.net/PhpDocumentor
link: - http://www.phpdoc.org
todo: - CS cleanup - change package to PhpDocumentor
since: - 1.1
license: - LGPL

Class Variables

Summary:

string $curfile

array $defineconflicts

array $definesbyfile

array $definesbynamefile

array $functionconflicts

array $functionsbyfile

array $functionsbynamefile

array $globalconflicts

array $globalsbyfile

array $globalsbynamefile

array $ignorepages

array $includesbyfile

array $pageclasspackages

array $pageconflicts

array $pagepackages

array $pages

array $pathpages

$curfile (line 67)

Data type : string

file being parsed, used in every add function to match up elements with the file that contains them

see: - addClass(), addMethod(), addVar(), nextFile()

$defineconflicts = array() (line 314)

Data type : array

Namespace conflicts within all documented packages of functions

Format:

     array(
         functionname => array(
             full path,
             full path,
             ...
         )
     )

$definesbyfile = array() (line 157)

Data type : array

array of parsed defines organized by the full path of the file that contains the define.

Format:

     array(
         full path => array(
             definename => parserDefine
         )
     )

$definesbynamefile = array() (line 211)

Data type : array

array of file names organized by defines that are in the file.

This structure is designed to handle name conflicts. Two files can contain defines with the same name, and this array will record both filenames to help control namespace errors Format:

     array(
         definename => array(
             full path of file containing definename,
             full path of file 2 containing definename,
             ...
         )
     )

$functionconflicts = array() (line 282)

Data type : array

Namespace conflicts within all documented packages of functions

Format:

     array(
         functionname => array(
             full path,
             full path,
             ...
         )
     )

$functionsbyfile = array() (line 142)

Data type : array

array of parsed functions organized by the full path of the file that contains the function.

Format:

     array(
         full path => array(
             functionname => parserFunction
         )
     )

$functionsbynamefile = array() (line 192)

Data type : array

array of file names organized by functions that are in the file.

This structure is designed to handle name conflicts. Two files can contain functions with the same name, and this array will record both filenames to help control namespace errors Format:

     array(
         functionname => array(
             full path of file containing functionname,
             full path of file 2 containing functionname,
             ...
         )
     )

$globalconflicts = array() (line 330)

Data type : array

Namespace conflicts within all documented packages of functions

Format:

     array(
         functionname => array(
             full path,
             full path,
             ...
         )
     )

$globalsbyfile = array() (line 172)

Data type : array

array of parsed global variables organized by the full path of the file that contains the global variable definition.

Format:

     array(
         full path => array(
             globalname => parserGlobal
         )
     )

$globalsbynamefile = array() (line 231)

Data type : array

array of file names organized by global variables that are in the file.

This structure is designed to handle name conflicts. Two files can contain global variables with the same name, and this array will record both filenames to help control namespace errors Format:

     array(
         global variablename => array(
             full path of file containing global variablename,
             full path of file 2 containing global variablename,
             ...
         )
     )

$ignorepages = array() (line 100)

Data type : array

array of all procedural pages ordered by name

that have been ignored via -po or @access private or @ignore Format:

     array(
         name => array(
             fullpath => parserPage,
             fullpath => parserPage2 [if there are name conflicts],
             ...
         )
     )

$includesbyfile = array() (line 127)

Data type : array

array of parsed includes organized by the full path of the file that contains the include.

Format:

     array(
         full path => array(
             includename => parserInclude
         )
     )

$pageclasspackages = array() (line 266)

Data type : array

array of packages assigned to classes in a file, ordered by fullpath

Format:

     array(
         fullpath => array(
             packagename => array(
                 subpackagename => 1,
                 subpackagename => 1,
                 ..
             ),
             packagename2 => array(...
             )
         )
     )

$pageconflicts = array() (line 298)

Data type : array

Namespace conflicts within all documented pages

Format:

     array(
         pagename => array(
             fullpath,
             fullpath,
             ...
         )
     )

$pagepackages = array() (line 246)

Data type : array

array of packages ordered by full path

Format:

     array(
         fullpath => array(
             packagename,
             subpackagename
         )
     )

$pages = array() (line 83)

Data type : array

array of all procedural pages ordered by name

Format:

     array(
         name => array(
             fullpath => parserPage,
             fullpath => parserPage2 [if there are name conflicts],
             ...
         )
     )

$pathpages = array() (line 112)

Data type : array

array of all procedural page names ordered by full path to the file

Format:

     array(
         fullpath => name
     )

Class Constants

Summary:

Method Detail

Summary:

void addClassPackageToFile (string $file, string $package, string $subpackage)

void addDefine (parserDefine &$element)

void addFunction (parserFunction &$element)

void addGlobal (parserGlobal &$element)

void addInclude (parserInclude &$element)

void addPage (parserPage &$element)

void addPagePackage (string $path, string $package, string $subpackage)

array|bool getPathInfo (string $path, mixed &$c)

array|string getRealPath (string $path, string $file)

void ignorePage (parserPage &$element)

parserPage|bool pathMatchesParsedFile (string $path, string $infile)

void replaceElement (parserElement &$element)

void setName (string $name)

void setParseBase (mixed $pbase)

void setupPagePackages ()

void setupPages (phpDocumentor_IntermediateParser &$render)

Method addClassPackageToFile (line 613)

void addClassPackageToFile( string $file, string $package, string $subpackage)

adds a package from a class to the current file

Parameters

string $file: full path to the file that contains the class
string $package: package name
string $subpackage: subpackage name

Info

Method addDefine (line 552)

void addDefine( parserDefine &$element)

sets up the $definesbyfile array using $curfile

Parameters

parserDefine &$element: the "define" element

Info

Method addFunction (line 508)

void addFunction( parserFunction &$element)

sets up the $functionsbyfile array using $curfile

Parameters

parserFunction &$element: the "function" object

Info

Method addGlobal (line 530)

void addGlobal( parserGlobal &$element)

sets up the $globalsbyfile array using $curfile

Parameters

parserGlobal &$element: the "global" element

Info

Method addInclude (line 496)

void addInclude( parserInclude &$element)

sets up the $includesbyfile array using $curfile

Parameters

parserInclude &$element: the "include" element object

Info

Method addPage (line 349)

void addPage( parserPage &$element)

sets up the $pages array

Parameters

parserPage &$element: the parser page element

Info

Method addPagePackage (line 450)

void addPagePackage( string $path, string $package, string $subpackage)

Changes the package of the page represented by $path

changes package in both the $pages array and the pagepackages array

Parameters

string $path: full path
string $package: the package name
string $subpackage: the subpackage name

Info

Method getPathInfo (line 385)

array|bool getPathInfo( string $path, mixed &$c)

gathers path-related info about a given element

Parameters

string $path: path to the element
mixed &$c: ???

Info

return - an array of path info, or FALSE
todo - figure out what &$c is and update the param tag

Method getRealPath (line 1033)

array|string getRealPath( string $path, string $file)

Ensures the path to the file is an absolute path

Parameters

string $path: path to the file
string $file: the file name

Info

return - returns an array of possible file locations or a string if there is an exact match

Method ignorePage (line 368)

void ignorePage( parserPage &$element)

moves a page from the $pages array to the $ignorepages array

Parameters

parserPage &$element: the parser page element

Info

Method pathMatchesParsedFile (line 983)

parserPage|bool pathMatchesParsedFile( string $path, string $infile)

checks to see if the parsed file matches the given path

Parameters

string $path: the path to look for
string $infile: the file to check

Info

return - matched parserPage if found, or FALSE if not found

Method replaceElement (line 575)

void replaceElement( parserElement &$element)

Used to align an element with the package of its parent page prior to Conversion.

Parameters

parserElement &$element: the element to align

Info

Method setName (line 421)

void setName( string $name)

Change a page's name from its file to alias $name

This function is used to handle a @name tag in a page-level DocBlock

Parameters

string $name: the alias

Info

Method setParseBase (line 969)

void setParseBase( mixed $pbase)

sets the parser base

Parameters

mixed $pbase: the parser base

Info

Method setupPagePackages (line 628)

void setupPagePackages( )

if there is one class package in a file, the parent path inherits the package if its package is default.

helps with -po to avoid dumb bugs

Info

Method setupPages (line 911)

void setupPages( phpDocumentor_IntermediateParser &$render)

Adjusts packages of all pages and removes name conflicts within a package

Automatic linking requires that each linkable name have exactly one element associated with it. In other words, there cannot be two functions named foo() in the same package.

This also adheres to php rules with one exception:

if ($test == 3) {
define('whatever', 'this thing');
} else {
define('whatever', 'this other thing');
}

phpDocumentor is not aware of conditional control structures because it would slow things down considerably. So, what phpDocumentor does is automatically ignore the second define and raise a warning. The warning can be eliminated with an @ignore tag on the second element like so:

if ($test == 3) {
define('whatever', 'this thing');
} else {
/**
* @ignore
*/
define('whatever', 'this other thing');
}

If there are two files that contain the same procedural elements in the same package (for example, a common configuration file common.php), they will also be ignored as if they were in the same file. The reasoning behind this is simple. A package is an indivisible set of files and classes that a user will include in their code. Name conflicts must be avoided to allow successful execution.

This function also plays the all-important role of calling phpDocumentor_IntermediateParser::addElementToPage() in order to add processed elements to their pages for Conversion.