HeaderDoc::ParseTree

Declared In:

Introduction

Parse tree (or token therein) generated by parser.

Discussion

The ParseTree class is a data structure for holding the parse tree as generated by blockParse.

In addition, this class provides a series of utility functions for manipulating the parse tree, generating output from the parse tree in HTML, XML, and plain text formats, and extracting Objective-C method parameter lists.

Member Functions

_initialize: Initializes an instance of a ParseTree object.
acs: Gets/sets the access control state (public, private, etc.) for this tree node.
addAPIOwner: Adds an additional API owner for a tree.
addChild: Adds a child to this node in the parse tree.
addRawParsedParams: Adds the parsed parameter strings from an array (reference) to this node's parsed parameters list.
addSibling: Adds a sibling to this node in the parse tree.
APIOprocessEmbeddedTagsRec: Processes embedded tags within an API owner (class).
apiOwner: Gests/sets the API owner for the tree.
apiOwners: Returns all of the API owners for the tree.
apiOwnerSub: Replaces an API owner for the tree.
childpeeknc: Recursively walks the descendants of this node (and their siblngs/descendants) and returns the first non-space node that is not in a comment.
clone: Duplicates this ParseTree object into another one.
colorTreeSub: Returns an HTML or XML representation of a parse tree/subtree.
commentsNestedIn: Returns whether to process comments in the children of a node with a given token.
curlycount: Counts the number of curly braces at this level in the parse tree.
dbprint: Prints a parse tree in a format designed for debugging.
dbprintrec: The recursive part of dbprint.
DESTROY: Called by Perl when a node is garbage collected.
dispose: Releases references in an attempt to allow Perl to garbage collect this parse tree.
filename: Gets/sets the filename associated with this tree node.
firstchild: Gets/sets the first child parse tree node for this one.
fullpath: Gets/sets the path associated with this tree node.
getNameAndFieldTypeFromDeclaration: Gets the name and the corresponding comment field type (e.g. @struct) for a given declaration
getPTvalue: Uses gcc to calculate the value for a parse tree containing a complex #define macro expression
hidden: Gets/sets whether this node and its children should be hidden when emitting HTML.
hiddenrec: Sets whether this node, its children, and its siblings should be hidden when emitting HTML.
htmlTree: Returns an HTML representation of a parse tree/subtree.
isAfter: Checks to see if this node is at the same level of the parse tree and occurs after the node specified (or is the node specified).
isAvailabilityMacro: Gets/sets whether this token is an availability macro.
isKnownMacroToken: Returns whether this token is a start token for a C preprocessor macro.
isMacro: Trivially returns whether this token should be treated a the start of a macro.
lastSibling: Returns the rightmost sibling of this tree node.
linenum: Gets/sets the line number associated with this tree node.
new: Creates a new ParseTree object.
newCTState: Creates a new state object for use by colorTreeSub.
next: Gets/sets the next parse tree node (sibling) for this one.
nextAtLevelOf: Walks up the parent tree until it reaches a node that is a sibling of matchingnode, then returns the node after that one.
nextnextpeeknc: Recursively walks the siblings of this node (and their descendants) and returns the second non-space node that is not in a comment.
nextNSToken: Returns the parse tree node containing the next non-space token at the current level.
nextpeek: Recursively walks the siblings of this node (and their descendants) and returns the first non-space node.
nextpeeknc: Recursively walks the siblings of this node (and their descendants) and returns the first non-space node that is not in a comment.
nextTokenNoComments: Recursively walks the siblings of this node (and their descendants) and returns the first node (including spaces) that is not in a comment.
objCparsedParams: Scrapes the parameters for an Objective-C method from the parse tree and returns an array.
parent: Gets/sets the parent parse tree node for this one.
parseComplexAvailability: Scrapes out the children of a new-style availability macro and returns a sanitized array.
parsedParamCopy: Copies a parsed parameter list and sets the parsed parameter list for this tree node to be a reference to the resulting array.
parsedParams: Sets the parsed parameter list for this node or searches the parse tree for parsed parameter lists and reurns the result.
parserState: Gets/sets the parser state object associated with this tree node.
printObject: Prints this object for debugging purposes.
printTree: Prints the text of the parse tree to standard output (for debugging).
processEmbeddedTags: Handles embedded HeaderDoc markup, returning a list of parameters, constants, etc.
processEmbeddedTagsRec: Recursively walks the parse tree looking for HeaderDoc markup and processes it.
rawParsedParams: Returns a reference to an array of parsed parameter strings associated with this node.
skipcurly: Walks this parse tree node's sibling chain and returns the node after the nth left brace.
slowprev: Finds the previous node by laborious tree walking of the parent node's children.
test_output_dump: Dumps a parse tree in a manner formatted for use by the Test class (used for running HeaderDoc self tests).
test_output_dump_rec: The recursive part of test_output_dump.
textTree: Prints a text representation of the parse tree as a string.
textTreeNC: Prints a text representation of the parse tree as a string with all comments omitted.
textTreeSub: The recursive portion of textTree and textTreeNC.
token: Gets/sets the token for this tree node.
translateTree: Partially translates Perl code into C
translateTreeRec: Does the real work of translating a Perl script (partially) to C.
trygcc: Uses gcc to calculate the value for a string containing a complex #define macro expression.
xmlTree: Returns an XML representation of a parse tree/subtree.

_initialize

Initializes an instance of a ParseTree object.

sub _initialize

Parameters

self: The object to initialize.

acs

Gets/sets the access control state (public, private, etc.) for this tree node.

sub acs

Parameters

self: This tree node.
ACCESSCONTROLSTATE: The new access control value to set. (Optional.)

addAPIOwner

Adds an additional API owner for a tree.

sub addAPIOwner

Parameters

self: This node.
newapio: The API owner to add.

addChild

Adds a child to this node in the parse tree.

sub addChild

Parameters

self: The current parse tree node.
name: The token value for the new node.
hide: Pass 1 if this node (and its children) should be hidden when emitting the tree as HTML, else 0.

Return Value

Returns the new child node.

addRawParsedParams

Adds the parsed parameter strings from an array (reference) to this node's parsed parameters list.

sub addRawParsedParams

Parameters

self: This parse tree node.
pplref: A reference to a parsed parameter list.

See Also

rawParsedParams

addSibling

Adds a sibling to this node in the parse tree.

sub addSibling

Parameters

self: The current parse tree node.
name: The token value for the new node.
hide: Pass 1 if this node (and its children) should be hidden when emitting the tree as HTML, else 0.

Return Value

Returns the new sibling node.

APIOprocessEmbeddedTagsRec

Processes embedded tags within an API owner (class).

sub APIOprocessEmbeddedTagsRec(
    $$$$$$$$)

Discussion

Unlike processEmbeddedTagsRec, this function does significantly less work because the code in APIOwner.pm handles most of the effort, thanks in part to the pots of parser gold hidden in the parse tree's hollow.

This function also works differently because instead of adding fields to a struct or whatever, it is adding functions, data types, variables, and even classes that are part of another class.

apiOwner

Gests/sets the API owner for the tree.

sub apiOwner

Parameters

self: This tree node.
newapio: The new API owner value. (Optional.)

apiOwners

Returns all of the API owners for the tree.

sub apiOwners

Parameters

self: This tree node.

apiOwnerSub

Replaces an API owner for the tree.

sub apiOwnerSub

Parameters

self: This tree node.
old: The previous API owner to delete.
new: The new API owner to insert.

childpeeknc

Recursively walks the descendants of this node (and their siblngs/descendants) and returns the first non-space node that is not in a comment.

sub childpeeknc

Parameters

self: The node whose children you want to search.
soc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc_b: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.

clone

Duplicates this ParseTree object into another one.

sub clone

Parameters

self: The object to clone.
clone: The victim object.

colorTreeSub

Returns an HTML or XML representation of a parse tree/subtree.

sub colorTreeSub

Parameters

self

The top of the tree/subtree to print.

ctstate

The colortree state object. It should contain the parameters listed below.

keep_whitespace

Set to 1 if whitespace should be preserved in the output, else 0.

apio

The owner of the parse tree. This may be an API owner or may jut be an ordinary type class instance (e.g. Struct).

This is mostly used for using methods in the HeaderElement class and obtaining filenames/line numbers for debugging.

type

Indicates information about what we're currently parsing. Possible values are:

typedef
struct
record
union
enum
funcptr
hexnumber
pastd - pascal type declaration
pasvar - pascal variable declaration
pasrec - pascal record declaration

depth

The nesting depth within the parse tree. Used for leading space calculations.

inComment

On initial call, 0. On recursion, possible values are:

0 — Not in a comment.
1 — In a multi-line (soc) comment.
2 — In a single-line (ilc) comment.

inQuote

On initial call, 0. On recursion, possible values are:

0 — Not in quote.
1 — Inside double quotes.
2 — Inside single quote.
3 — In a Python triple-quote or a Ruby quote. See inRubyQuote to determine which.

inRubyQuote

On initial call, 0. On recursion, possible values are:

0 — Not in a Ruby quote.
1 — Inside either %{ or %/
2 — Inside <<. Prevents coloring of the initial token.

inObjCMethod

Pass in 1 if this is a parse tree for an Objective-C method, else pass in 0.

lastBrace

The last brace or parentheses character seen, or +/- in Objective-C methods), or special tokens that are treated like braces.

parseTokensRef

A reference to the parse tokens hash returned by a call to parseTokens.

prespace

The leading spaces that should be inserted to the left of this token if it wraps to the start of a line.

lang

The current language.

sublang

The current language dialect (e.g. cpp for C++).

xmlmode

Set to 1 if you want XML output, 0 for HTML.

newlen

The length of the current line. Set to 0 on first call.

breakable

Indicates whether the formatter can break before this token.

0 — Not a good spot to break.
1 — Breakable before this token.
2 — Breakable after this token.
3 — This token must be at the start of a line.

inMacro

Set to 0 on first call. During tree walk, this goes high when the tree walk code enters a C preprocessor macro and remains high until the end of the macro.

inEnum

Set to 0 on first call. Goes high when inside an enumeration.

seenEquals

Set to 0 on first call. Goes high after the equals sign in a variable declaration.

lastKeyword

Contains the last keyword encountered. Set to an empty string on first call. Used for guessing types in generating link requests.

lastnstoken

The last non-space token encountered. Set to an empty string on first call.

lastTreeNode

The tree node at which output stops. This node and its descendants are included in output, but not this node's siblings.

lastTokenType

Contains the type of the last token emitted. One of: star, string, char, comment, preprocessor, number, keyword, function, var, template, type, param, or ignore.

On initial call, an empty string.

spaceSinceLastToken

Indicates that whitespace has been seen since the last non-space token. This ensures that required space does not get deleted.

On initial call, 0.

inAttribute

On initial call, 0. On recursion, set to 1 after the attribute keyword (or equivalent) is encountered.

Causes the next word token to be interpreted as ordinary text.

Also prevents the normal line break after the open parenthesis.

inRaises

On initial call, 0. On recursion, set to 1 after the raises keyword (or equivalent) is encountered.

Causes the next word token to be interpreted as a variable (an exception) instead of a type.

Also prevents the normal line break after the open parenthesis.

inTypeOf

On initial call, 0. On recursion, set to 1 after the typeof keyword (or equivalent) is encountered.

Causes the next word token to be interpreted as a variable instead of a type.

Also prevents the normal line break after the open parenthesis.

drop_pdefine_contents

Set to 1 if the contents of #define macros should be dropped from the output, else 0.

ASinName

On initial call, set to 0. During the recursive walk of the parse tree, this gets set to 1 when the current tree node in an AppleScript name.

Discussion

This is a helper function shared by htmlTree and xmlTree. You should not call this directly.

Local Variables

tokenType: Contains the type of the last token emitted. One of: star, string, char, comment, preprocessor, number, keyword, function, var, template, type, param, or ignore.

commentsNestedIn

Returns whether to process comments in the children of a node with a given token.

sub commentsNestedIn

Parameters

token: The token to check.
soc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
eoc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc_b: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
lbrace: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
case_sensitive: The start-of-comment token for the current programming language. Obtained by a call to keywords.

Discussion

The tree walking code explicitly avoid things like strings and regular expressions without the need to search for them by disallowing children of any non-word, non-whitespace characters other than parentheses, curly braces, and colons.

curlycount

Counts the number of curly braces at this level in the parse tree.

sub curlycount

Parameters

self: This parse tree node.
lbrace: The left brace token to look for.
last: The last node to include.

Discussion

Because this function checks at a given level, it updates the last node to be the ancestor of the last node at the same level as the starting node. (Why doesn't this use nextAtLevelOf?)

dbprint

Prints a parse tree in a format designed for debugging.

sub dbprint

Parameters

self: The parse tree object to print.

dbprintrec

The recursive part of dbprint.

sub dbprintrec

Parameters

self: The parse tree/subtree to dump.
depth: The number of nesting levels above this token.
lastnode: The last node to emit. This node and its children appear in the output, but not its siblings.

DESTROY

Called by Perl when a node is garbage collected.

sub DESTROY

Parameters

self: The root of the parse tree to release.

Discussion

Used for debugging memory behavior.

dispose

Releases references in an attempt to allow Perl to garbage collect this parse tree.

sub dispose

Parameters

self: The root of the parse tree to release.

filename

Gets/sets the filename associated with this tree node.

sub filename

Parameters

self: This tree node.
FILENAME: The new filename value to set. (Optional.)

firstchild

Gets/sets the first child parse tree node for this one.

sub firstchild

Parameters

self: This parse tree object.
NEXT: The new child node. (Optional.)

fullpath

Gets/sets the path associated with this tree node.

sub fullpath

Parameters

self: This tree node.
FILENAME: The new filename value to set. (Optional.)

Discussion

This contains the (relative or absolute) path for the owning header, as passed in on the command line.

getNameAndFieldTypeFromDeclaration

Gets the name and the corresponding comment field type (e.g. @struct) for a given declaration

sub getNameAndFieldTypeFromDeclaration

Parameters

self: This parse tree object.
string: The declaration to parse.
apio: The object (may be API owner or not) to which the resulting objects should be added.
typedefname: The keyword typedef or equivalent.
case_sensitive: Set to 0/1 depending on whether the current programming language uses case-sensitive token matching.
keywordhashref: A reference to the keyword hash for this language (obtained with a call to the keywords function).

Discussion

This helper reduces the amount of code needed to use the block parser in several places in the parse tree code by consolidating this logic in one place.

getPTvalue

Uses gcc to calculate the value for a parse tree containing a complex #define macro expression

sub getPTvalue

Parameters

self: The parse tree object.

Discussion

Although it should be possible for the new code in MacroFilter.pm to be easily adapted to do this job, at the time, that code did not exist.

hidden

Gets/sets whether this node and its children should be hidden when emitting HTML.

sub hidden

Parameters

self: This tree node.
value: The new token value to set. (Optional.)

Discussion

If a new value is specified, this function recursively modifies its descendants.

hiddenrec

Sets whether this node, its children, and its siblings should be hidden when emitting HTML.

sub hiddenrec

Parameters

self: This tree node.
value: The new token value to set.

Discussion

This function recursively modifies its descendants and siblings.

htmlTree

Returns an HTML representation of a parse tree/subtree.

sub htmlTree

Parameters

self: The top of the tree/subtree to print.
keep_whitespace: Set to 1 if whitespace should be preserved in the output, else 0.
drop_pdefine_contents: Set to 1 if the contents of #define macros should be dropped from the output, else 0.

isAfter

Checks to see if this node is at the same level of the parse tree and occurs after the node specified (or is the node specified).

sub isAfter

Parameters

self: The current node.
node: The specified node for comparison.

isAvailabilityMacro

Gets/sets whether this token is an availability macro.

sub isAvailabilityMacro

Parameters

self: The parse tree node.
newvalue: The new value to set. (Optional.)

isKnownMacroToken

Returns whether this token is a start token for a C preprocessor macro.

sub isKnownMacroToken

Parameters

token: The token to check.
macroListRef: A reference to the macro hash returned by a call to parseTokens.
case_sensitive: Set to 0/1 depending on whether the language uses case-sensitive token matching. This value is generally obtained with a call to keywords.

isMacro

Trivially returns whether this token should be treated a the start of a macro.

sub isMacro

Parameters

self: This parse tree instance (unused).
token: The token to check.
lang: The current language.
sublang: The current language dialect (e.g. cpp for C++).

lastSibling

Returns the rightmost sibling of this tree node.

sub lastSibling

Parameters

self: This tree node.

linenum

Gets/sets the line number associated with this tree node.

sub linenum

Parameters

self: This tree node.
LINENUM: The new line number value to set. (Optional.)

Discussion

This value indicates where this tree node came fron within the enclosing header.

new

Creates a new ParseTree object.

sub new

Parameters

param: A reference to the relevant package object (e.g. HeaderDoc::ParseTree->new() to allocate a new instance of this class).

newCTState

Creates a new state object for use by colorTreeSub.

sub newCTState

Parameters

withref
morevalues: Additional values to add.

Discussion

This greatly reduces the number of arguments to colorTreeSub. It has no other purpose beyond making the code more readable by treating the current state as an object.

Keys and legal values are described as local variables for colorTreeSub.

Gets/sets the next parse tree node (sibling) for this one.

sub next

Parameters

self: This parse tree object.
NEXT: The new next node. (Optional.)

nextAtLevelOf

Walks up the parent tree until it reaches a node that is a sibling of matchingnode, then returns the node after that one.

sub nextAtLevelOf

Parameters

self: The starting node.
matchingnode: The node whose level you want ot match.
fullpath: The path of the file containing this parse tree (used for debugging messages).

nextnextpeeknc

Recursively walks the siblings of this node (and their descendants) and returns the second non-space node that is not in a comment.

sub nextnextpeeknc

Parameters

self: The node whose siblings you want to search.
soc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc_b: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.

nextNSToken

Returns the parse tree node containing the next non-space token at the current level.

sub nextNSToken

Parameters

self: The initial parse tree node.

nextpeek

Recursively walks the siblings of this node (and their descendants) and returns the first non-space node.

sub nextpeek

Parameters

self: The node whose siblings you want to search.

nextpeeknc

Recursively walks the siblings of this node (and their descendants) and returns the first non-space node that is not in a comment.

sub nextpeeknc

Parameters

self: The node whose siblings you want to search.
soc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc_b: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.

nextTokenNoComments

Recursively walks the siblings of this node (and their descendants) and returns the first node (including spaces) that is not in a comment.

sub nextTokenNoComments(
    $$$$$)

Parameters

self: The node whose siblings you want to search.
soc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc_b: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.

objCparsedParams

Scrapes the parameters for an Objective-C method from the parse tree and returns an array.

sub objCparsedParams()

Parameters

self: The parse tree for the method.

parent

Gets/sets the parent parse tree node for this one.

sub parent

Parameters

self: This parse tree object.
NEXT: The new parent node. (Optional.)

parseComplexAvailability

Scrapes out the children of a new-style availability macro and returns a sanitized array.

sub parseComplexAvailability

Parameters

self: The parse tree node, taken from availabilityNodesArray in the ParserState object.

Discussion

Most of the hard work is done by complexAvailabilityToArray.

This function is exclusively used by mergeComplexAvailability.

parsedParamCopy

Copies a parsed parameter list and sets the parsed parameter list for this tree node to be a reference to the resulting array.

sub parsedParamCopy

Parameters

self: This tree node.
pplref: A reference to the parsed parameter list array to copy.

parsedParams

Sets the parsed parameter list for this node or searches the parse tree for parsed parameter lists and reurns the result.

sub parsedParams(
    $)

Parameters

self: This object.
pplref: A reference to a parsed parameter list. (Optional.)

Discussion

This subroutine is for future transition. The end goal is to move the parsed parameter support from the HeaderElement level entirely into the parse tree.

parserState

Gets/sets the parser state object associated with this tree node.

sub parserState

Parameters

self: This tree node.
PARSERSTATE: The new parser state value to set. (Optional.)

Discussion

Parser state objects are inserted into the parse tree to make it easier to interpret declarations within classes.

printObject

Prints this object for debugging purposes.

sub printObject

Parameters

self: This object.

printTree

Prints the text of the parse tree to standard output (for debugging).

sub printTree

Parameters

self: The top of the tree/subtree to print

See Also

dbprint

processEmbeddedTags

Handles embedded HeaderDoc markup, returning a list of parameters, constants, etc.

sub processEmbeddedTags

Parameters

self: The top of the parse tree/subtree to scan.
xmlmode: Set to 1 if output mode is XML.
apiOwner: If this parse tree is owned by an API owner, this variable indicates the primary API owner to which the resulting objects should be added. If this parse tree is owned by a non-API-oowner object (e.g. a Struct object), this value is unused.

processEmbeddedTagsRec

Recursively walks the parse tree looking for HeaderDoc markup and processes it.

sub processEmbeddedTagsRec

Discussion

This subroutine processes the parse tree recursively looking for (and subsequently processing) embedded headerdoc markup, then parses the associated declarations. This is a helper function that does the actual work for processEmbeddedTags.

rawParsedParams

Returns a reference to an array of parsed parameter strings associated with this node.

sub rawParsedParams

Parameters

self: This parse tree node.

See Also

addRawParsedParams

skipcurly

Walks this parse tree node's sibling chain and returns the node after the nth left brace.

sub skipcurly

Parameters

self: The starting parse tree node.
lbrace: The left brace token to look for.
count: The number of braces to skip past.

slowprev

Finds the previous node by laborious tree walking of the parent node's children.

sub slowprev()

Parameters

self: This tree node.

Discussion

This function should be avoided if at all possible. It is currently unused, though it was used in the distant past. It is retained for completeness.

test_output_dump

Dumps a parse tree in a manner formatted for use by the Test class (used for running HeaderDoc self tests).

sub test_output_dump

Parameters

self: The parse tree/subtree to dump.
depth: The number of nesting levels above this token.
lastnode: The last node to emit. This node and its children appear in the output, but not its siblings.

Discussion

This is similar to dbprint in many ways, but it omits object IDs that change from run to run.

test_output_dump_rec

The recursive part of test_output_dump.

sub test_output_dump_rec

Parameters

self: The parse tree/subtree to dump.
depth: The number of nesting levels above this token.
lastnode: The last node to emit. This node and its children appear in the output, but not its siblings.

textTree

Prints a text representation of the parse tree as a string.

sub textTree

Parameters

self: The top of the tree/subtree to dump.

textTreeNC

Prints a text representation of the parse tree as a string with all comments omitted.

sub textTreeNC

Parameters

self: The top of the tree/subtree to dump.
lang: The current language.
sublang: The current language dialect (e.g. cpp for C++).

textTreeSub

The recursive portion of textTree and textTreeNC.

sub textTreeSub

Parameters

self: The top of the tree/subtree to dump.
nc: Set to 1 if comments should be dropped, else 0.
nh: Set to 1 if hidden tokens should be dropped, else 0.
soc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
ilc_b: The start-of-comment token for the current programming language. Obtained by a call to parseTokens.
lastnode: The last node to include. This node and children of this node are included, but not siblings of this node.

token

Gets/sets the token for this tree node.

sub token

Parameters

self: This tree node.
TOKEN: The new token value to set. (Optional.)

translateTree

Partially translates Perl code into C

sub translateTree

translateTreeRec

Does the real work of translating a Perl script (partially) to C.

sub translateTreeRec

Parameters

self

The tree to translate.

A translation state object (initially empty).

trygcc

Uses gcc to calculate the value for a string containing a complex #define macro expression.

sub trygcc

Parameters

self: The parse tree object. (Unused.)
rawvalue: The expression to interpret.

Discussion

Used by getPTvalue.

Although it should be possible for the new code in MacroFilter.pm to be easily adapted to do this job, at the time, that code did not exist.

xmlTree

Returns an XML representation of a parse tree/subtree.

sub xmlTree

Parameters

self: The top of the tree/subtree to print.
keep_whitespace: Set to 1 if whitespace should be preserved in the output, else 0.
drop_pdefine_contents: Set to 1 if the contents of #define macros should be dropped from the output, else 0.

Member Data

ACCESSCONTROLSTATE

The access control state in force at the time this node was created.

APIOWNERS

An array of API objects that reference the parse tree rooted in this node.

BLOCKOFFSET

The line number of the first line of the LineRange object.

CPNC

A cached copy of the results of childpeeknc for this node.

FILENAME

The filename component of the header or source file that contains the API content that this parse tree describes. Does not include leading path parts.

FIRSTCHILD

The first child (descendant) node of this node.

FULLPATH

The full (possibly relative) path to the header or source file that contains the the API content that this parse tree describes.

HeaderDoc::ParseTree::VERSION

The revision control revision number for this module.

HIDDEN

Indicates that this node should not be emitted in HTML output.

HIDEMACROLASTTOKEN

Set to 1 on the space or 2 on the curly brace after a macro name. Used to hide the contents of a macro for output purposes, depending on flags.

HTMLTREE

A cached copy of the HTML tree for the parse tree rooted in this node, as generated by htmlTree.

INPUTCOUNTER

The line number where this tree object appeared relative to the start of the LineRange object.

ISAVAILABILITYMACRO

Indicates that this node is an availability macro. This is used for wrapping content in both HTML and XML.

LINENUM

The actual line number in the header ($self->{INPUTCOUNTER} + $self->{BLOCKOFFSET}).

NEXT

The next (sibling) node in the parse tree.

NTNC

A cached copy of the results of nextTokenNoComments for this node.

PARENT

The parent node in the parse tree.

PARSEDPARAMS

An array of parsed parameter objects associated with this node. Each entry in this array should be a MinorAPIElement object, but right now, it's a mixture of objects and strings. This is not currrently used for anything, but may be used in the future once support is fully integrated in the parser.

PARSERSTATE

A parser state object stored at this node in the parse tree. used for reparsing class contents.

PETDONE

Set to 1 by processEmbeddedTags to indicate that this parse tree has already been processed. This prevents duplicate insertion of symbols nested within classes.

RAWPARSEDPARAMETERS

An array of parsed parameters associated with this node. Each entry in this array is a string containing the text of a parameter. This is currently unused.

RE_STATE

Indicates that this node is part of a regular expression. This value contains one of the following values:

RE_PREFIX (the optional "command" letters before the expression)

RE_START (the opening slash or other delimiter)

RE_PARTSEP (the intermediate delimiter or delimiters)

RE_END (the trailing slash or other delimiter).

Note that the trailing flags are not tagged in any special way because you can trivially distinguish the parse tree node that contains them by inspecting the node after RE_END.

REFCOUNT

The number of API objects that reference this parse tree. The parse tree cannot be purged until this count goes to zero.

TOKEN

The token itself.

XMLTREE

A cached copy of the XML tree for the parse tree rooted in this node, as generated by xmlTree.

ACCESSCONTROLSTATE

The access control state in force at the time this node was created.

$self->{ACCESSCONTROLSTATE}

APIOWNERS

An array of API objects that reference the parse tree rooted in this node.

$self->{APIOWNERS}

BLOCKOFFSET

The line number of the first line of the LineRange object.

$self->{BLOCKOFFSET}

CPNC

A cached copy of the results of childpeeknc for this node.

$self->{CPNC}

FILENAME

The filename component of the header or source file that contains the API content that this parse tree describes. Does not include leading path parts.

$self->{FILENAME}

FIRSTCHILD

The first child (descendant) node of this node.

$self->{FIRSTCHILD}

FULLPATH

The full (possibly relative) path to the header or source file that contains the the API content that this parse tree describes.

$self->{FULLPATH}