HeaderDoc::BlockParse

The path to the file being parsed.

The line number where the current block begins. The line number printed is (fileoffset + inputCounter).

A reference to an array of code lines.

The offset within the array. This is added to fileoffset when printing the line number.

Set to 1 for parsing function arguments, enum constants, or struct fields, 2 for reparsing embedded HeaderDoc markup in a class, 0 otherwise.

This has the following effects:

• Disables warnings when parsing arguments to avoid seeing them twice.

• Disables C preprocessing (to avoid double-replacement).

• Sets $parseTokens{assignmentwithcolon} = 2 in AppleScript.

• Disables the handling of the of and in tokens and label keywords in AppleScript.

• Forces the block parser to return only the outer name for a type (a la $HeaderDoc::outerNamesOnly) if argpase is 2.

A reference to a hash of tokens to ignore on all headers.

A reference to a hash of tokens, generated from @ignore headerdoc comments.

A reference to a hash of tokens, generated from @ignorefunmacro headerdoc comments.

A reference to a hash of keywords.

Boolean value that controls whether keywords should be processed in a case-sensitive fashion.

The language family to use in parsing. Overrides HeaderDoc::lang.

The language variant to use in parsing. Overrides HeaderDoc::sublang.

Enables parsing of if/else statements. Not used by HeaderDoc; used by other tools that share this parser.

Set to 1 by the outer layers when the filename matches a particular filename. This is useful when you need to enable lots of debugging for a single file. When 1, enables lots of debugging.

The programming language being parsed. This is deprecated, and is used only if you do not pass in a value for the lang parameter.

The programming language dialect being parsed (e.g. cpp for C++). This is deprecated, and is used only if you do not pass in a value for the sublang parameter.

The current access control state (public, private, protected, etc.). When a permanent access control change (with a colon after it) occurs, this global variable is modified. After a declaration, the temporary (per-declaration) access control state is restored from this variable.

Set to 1 if (in C) you want a function declaration to end after the closing parenthesis even if there is no trailing semicolon. Do NOT set this for normal parsing; it will break many typedef declarations and similar. This also enables some broken man page detection for deleting lines that say or and and.

Indicates that parsing should continue. Upon receiving a terminating token, this gets set to zero, and parsing ends at the end of the line.

This gets high when we see an opening brace at the start of parsing. If the parser returned, you would get a bogus declaration, so instead, the parser reboots itself, starting parsing from scratch at the next line.

The programming language being parsed. Set from HeaderDoc::lang.

The programming language dialect being parsed (e.g. cpp for C++). Set from HeaderDoc::sublang.

Legacy formatting cruft variable.

Indicates whether the parser is in a regular expression. Values are:

• 0 — Not in a regex (or in the tail of a regex).

• 1 — In the second part of a two-part regexp, or the only part of a one-part regexp.

• 2 — Between the two parts; only occurs if the separator is neither '|' nor '/'. Otherwise, this state gets skipped.

• 3 — In the first part of a regular expression after the first separator.

• 4 — Before the first separator. This state ends instantly unless there is a prefix.

When parsing regular expressions, the contents of the right side are largely unparsed (no parenthesis or bracket interpolation, for example). Thus, it is important to know whether you are in the left side or the right side during parsing. Unfortunately, the inRegexp variable only indicates how many pieces remain in the regexp. Although this is vital information, it is insufficient for this purpose. For a single-part regexp, you would have to look for 1, but for a two-part regexp, a 1 would indicate the last part instead of the first. This variable solves that problem.

Values are:

• 0 — Not in the first part of a regular expression.

• 1 — In the first part of a regular expression.

• 2 — Before the first part of a regular expression.

The value is 2 up to and including the leading symbol (e.g. /). It goes to zero upon reaching the symbol that terminates the first part of the regular expression (e.g. /).

In a regular expression character class, the first character behaves differently; a closing bracket as the first character in a character class is treated as a literal. (For example, []] is a character class containing only a close bracket.) To support this, the inRegexpCharClass has several values:

• 0 — Not in a character class.

• 1 — In a chracter class (not at the beginning).

• 2 — The first character of a character class. (Reduced to 1 at end of token loop.)

• 3 — Just saw the opening bracket. (Reduced to 2 at end of token loop.)

• 4 — In a nested character class. (Reduced to 1 after closing :] mark.)

• 5 — In a nested character class after possible trailing colon. (Reduced to 1 if next character is a right bracket.)

• 6 — In a nested character class at possible trailing colon. (Reduced to 5 at end of token loop.)

Certain regular expression commands don't result in any parsing within them (e.g. the tr command). If set, this is equivalent to setting inRegexpFirstPart to 0.

In the trailing part of a regular expression.

Indicates the number of levels of nested parentheses the current token is within.

Indicates that the parser is currently processing a Pascal type declaration.

Used to tell the parameter parsing code to skip the end-of-comment character. (The value of inComment (in the parserState object) goes to 0 before that code, so without this, it would end up at the start of the next parameter.)

In AppleScript parsing, set to 1 when a vertical pipe operator (|) is encountered to protect an identifier. Set to 0 when the next vertical pipe operator is encountered.

In the cruft after a colon in a C++ method declaration.

The (input) line being parsed.

The current token being processed (from curline).

The token after the token being processed (from curline).

In some cases, it is necessary to drop a token for formatting purposes but keep it in the parse tree. When this is needed, the treepart variable contains the original token, and the part variable contains a placeholder value (generally a space).

This variable is rather odd. The last token in this string is the last character, but it may contain multiple characters. This should probably not be used in the parser, but it is used in a few spots.

The last non-space token encountered.

The last token encountered (though newlines and carriage returns may be replaced by a space).

The ParserState object used for storing most of the parser state variables.

This variable is normally 0. It gets set to 1 to tell the hollow insertion code (at the bottom of the token loop) to set the value of the hollow variable (in the parserState object) to the tree node for the current token (which has not been created yet at the time this variable gets set).

Indicates that in spite of sethollow being set to 1, the current node is a bad place to insert the parser state because it is one of the access control tokens (e.g. public/private) or because it isn't really being inserted into the tree.

Normally 0. Set to 1 if the parser state should be pushed onto the stack after this token.

Normally 0. Set to 1 if the parser state should be pushed onto the stack after the next word token. May also be set to 2 if the parser state should be pushed at the word token after the next word token.

Normally 0. Set to 1 if the parser state should be pushed onto the stack after the next opening brace.

Normally 0. The name of this variable is slightly misleading. When used, the variable is initially set to 2. On the next word token (and only a word token), this variable is decremented to 1.

At this point, matching behavior changes, and the parser state is pushed at the first token that is either a word token, an at sign (@), a minus sign (-), or a plus sign (+).

The top of the current parse tree.

The current position in the parse tree.

Used to control whether the code at the bottom of the token loop should trigger a loop nesting after the current token.

• 0 — tokens after this one should be siblings of this one.

• 1 — tokens after this one should be nested as children of this node.

• 2 — tokens after this one should be nested as children of this node and this node has already been inserted into the tree, so it should not be inserted again at the bottom of the loop.

This gets set to 1 if the current part should not be inserted into the parse tree (generally because it has already been inserted in some form during parsing).

This indicates that the current position in the parse tree should be popped from the treeStack stack after the next newline character.

Indicates that this is a token that follows a state change to a new state in which the seenBraces flag was previously set, and that this token should be treated as though seenBraces were still set. This flag is only supported in bits of code after where it is first set (in the right closing brace code).

Stack for regular expression characters.

Stack for brace tokens, including the left curly brace, the start-of-template (sotemplate) value, the left square bracket, the left parenthesis and the opening class marker for class markers that aren't followed by a left curly brace (Objective-C @interface, for example).

A stack containing values from parsedParamParse (in the parserState object). These are pushed and popped on curly braces, parentheses, etc. This is basically used for keeping track of which split character to use as the parser goes into deeper nesting levels (e.g. when dropping into a function pointer/callback inside a struct).

A stack of parse trees. These are pushed and popped at various points during the parse process as braces, colons, parentheses, etc. The behavior is controlled by the variables treeNest, treeSkip, treePopTwo (in parserState, and treePopOnNewLine.

Temporary variable used for leading space during formatting.

Temporary variable used for leading space during formatting.

Temporary storage used during formatting.

The string currently being parsed. Was at one time used for checking for quoting, but no longer.

An obscure spacing workaround.

An obscure spacing workaround.

When set to a nonzero value, the noInsert variable in the ParseTree object created after the next open curly brace gets set to this value.

The API owner object (class, header, etc.) into which new declarations should be inserted.

The path to the file being parsed.

The full (possibly relative) path to the current input file.

Set to 1 if an @function comment preceded this declaration.

Set to 1 if a new-style comment (with no top-level HeaderDoc tag) preceded this declaration.

Set to 1 if an @typedef comment preceded this declaration.

Set to 1 if an @struct comment preceded this declaration.

Set to 1 if an @enum comment preceded this declaration.

Set to 1 if an @union comment preceded this declaration.

Set to 1 if an @constant or @const comment preceded this declaration.

Set to 1 if an @var comment preceded this declaration.

Set to 1 if an @method comment preceded this declaration.

Set to 1 if an @define comment preceded this declaration.

Set to 2 if an @defineblock or @definedblock comment preceded this declaration.

Set to 1 if an @class comment preceded this declaration.

Set to 1 if an @interface comment preceded this declaration.

The line number where the current block begins. The line number printed is (blockOffset + inputCounter).

A reference to the initial array of category (HeaderDoc::ObjCCategory) objects. New category objects are added to this array.

A reference to the initial array of class (HeaderDoc::CPPClass and HeaderDoc::ObjCClss) objects. New category objects are added to this array.

The class type, based on what class was last parsed. Used when parsing fragments within a class. Legal values are intf, occ, occCat, or any value that is valid for sublang.

This is used to determine whether to treat the @method tag as an Objective-C method (HeaderDoc::Method) or as a normal method (HeaderDoc::Function).

The new access control state (public, private, etc.). It is named cpp because at the time it was naed, the only langauge that required it was C++ (where sublang = "cpp").

An array of fields returned from a call to stringToFields on a HeaderDoc comment.

The function group currently in effect.

The header object that will eventually contain any objects produced.

The offset within the array. This is added to blockOffset when printing the line number.

A reference to an array of code lines.

The language family to use in parsing. Overrides HeaderDoc::lang.

The number of lines in inputlinesref.

Text before the initial @ in the preceding HeaderDoc comment. Contains the discussion in a new-style comment. Otherwise, contains whitespace.

Set to 1 if output should be in XML format, else 0. This sets the outputformat value on new objects.

Set to 1 to enable lots of general debug spew.

Set to 1 to enable lots of debug spew specific to tracking down infinite loops.

Set to 1 to enable lots of debug spew specific to parameter handling.

Set to 1 to debug block handling (both define blocks and blocks wrapped in C preprocessor macros).

Set to 1 to use subparse mode (handling a declaration extracted out of an existing parse tree).

The source parse tree in subparse mode. Ignored otherwise.

No longer used. Always pass zero.

Pass 1 to allow blocks to be created when a #if statement is found immediately after a HeaderDoc comment. Pass 0 to disable this feature.

Used in block mode because subparseTree is empty by definition when the comment precedes the declaration.

The language variant to use in parsing. Overrides HeaderDoc::sublang used in previous versions of this function. Optional FOR NOW.

A HashObject instance that reflects the current position in the CPP hash tree. This is used by the parser to manage the C preprocessor hash tables in the presence of #if directives.

For a detailed explanation, see the documentation for the HashObject class.

Although this is optional, if you don't pass these correctly, you won't get support for #if/#else/#endif blocks.

A HashObject instance that represents the root of the CPP hash tree. This is used by the parser to manage the C preprocessor hash tables in the presence of #if directives.

For a detailed explanation, see the documentation for the HashObject class.

Although this is optional, if you don't pass these correctly, you won't get support for #if/#else/#endif blocks.

Possible values:

• 0 — Not in a block of any kind.

• 1 — Got an @defineblock comment, but have not yet seen any #define macros.

• 2 — Got an @defineblock comment, and have seen at least one #define macro.

• 3 — Got a #if macro before the first declaration. Treat the following declarations as a group until the corresponding #endif macro

The topmost parser state context object from blockParse.

The top of the parser tree object from blockParse.

Set to 1 for parsing function arguments, enum constants, or struct fields, 2 for reparsing embedded HeaderDoc markup in a class, 0 otherwise. For more details, see blockParse.

The declaration returned by blockParse. If you pass an empty string, the declaration is obtained from the parse tree.

Set to 1 if a C++ method with private parameters has been parsed and the public declaration needs to be restored.

The public declaration to restore.

The access control state when the block parser finished, including any access control changes parsed this round.

Set to 1 to dump lots of debug information.

The base line number of the LineRange object containing this declaration. In subparse mode (reprocessing a declaration embedded in a class), this value gets overwritten with the correct value from the tree. Thus, this value is only relevant when this function is called from blockParse itself.

Set to 0 when this is called from blockParse. Set to 1 when reinterpreting a parse tree obtained from a declaration within a class.

The token for #define. Used to determine whether to run a separate parser to extract the #define macro parameters.

The line number relative to the start of the LineRange object containing this declaration. In subparse mode (reprocessing a declaration embedded in a class), this value gets overwritten with the correct value from the tree. Thus, this value is only relevant when this function is called from blockParse itself.

Set by the -O flag.

The opening symbol.

If 1, returns the original symbol and prints a warning message on error. If 0, returns an empty string on error (with no warning).

An array of fields.

The part before the first @ sign (the declaration of a new-style HeaderDoc comment, or empty for an old-style HeaderDoc comment).

Content to use if the field set is empty.

The array to dump.

The key in each object to modify.

The desired value for the specified key.

If 0, replace the existing value with $value.

If 1, append $value to the existing value (space-delimited).

The array to dump.

The key in each object to match.

The value for that key that, if matching, indicates the object should be modified.

The key in each object to modify.

The desired value for the specified key.

If 0, replace the existing value with $value.

If 1, append $value to the existing value (space-delimited).

The parse tree for the macro in question.

True if the declaration's contents should be omitted entirely.

The string form of the macro in question.

True if the declaration's contents should be omitted entirely.

The name of the C preprocessor macro for which these arguments are the parameters.

The line number where this line appears. Used for determining which #define directives apply at that point in time.

An array containing a parse tree for each actual parameters to this instance of the C preprocessor macro (in order of occurrence).

The part to process.

The line number where the part appears. Used for determining which #define directives apply at that point in time.

A parse tree for the actual argument in question.

The text of the declaration to parse.

The line number (for debugging purposes).

The name of the #define.

Set to 1 to print debug info.

The header file path (for debugging purposes).

A reference to the array to search.

The key in each object to search.

The expected value of that key.

The class token.

A reference to a hash in which the names of the macro tokens (e.g. #define, #if, #ifdef) are the hash keys.

If 0, includes all tokens as-is.

If 1, includes only tokens that begin with a # sign and strips off the leading #, e.g. define instead of #define.

If 2, includes only tokens that do not begin with a # sign.

The original availability derived from comments.

The array of availability nodes generated from parse tokens parsed by the parser.

A reference to the array to dump.

IN: The current master object from blockParseOutside. This master object is generated based on the top-level tag in the HeaderDoc comment, if present. (If the comment has no top-level tag, this is a generic HeaderElement object.)

IN: The typedefname parse token (obtained from a call to parseTokens.

IN: The typestring field out of the parser state object. See the parserState class for more information.

IN: The posstypes field out of the parser state object. See the parserState class for more information.

IN: The primary type returned by the parser. For example, in the case of a typedef struct declaration, the outer type would be typedef.

IN: The type that we are searching for (as defined by the HeaderDoc comment).

IN: The class type of the enclosing context.

OUT: The class type of the class just parsed; unchanged if the current declaration is not a class.

IN: The class keyword from the HeaderDoc comment (e.g. for an @class comment, the value is class). If unspecified, the value is auto.

IN: The raw declaration. For classes, passed to classTypeFromFieldAndBPinfo. Otherwise unused.

IN: A reference to the array of fields from the HeaderDoc comment.

IN: The name of the current function group.

IN: Probably doesn't matter.

OUT: Returns 1 if the variable declaration is a constant, else 0.

IN: Nonzero if the parser is in a #define block. (For details, see blockParseOutside.

IN: Nonzero if the HeaderDoc comment began with @class.

IN: Nonzero if the HeaderDoc comment began with @interface.

IN: Nonzero if the HeaderDoc comment began with @typedef.

IN: Nonzero if the HeaderDoc comment began with @struct.

IN: The filename with leading path parts (for debugging purposes/warnings).

IN: The position within the current text block (for debugging purposes/warnings).

IN: The offset of the current text block from the start of the file (for debugging purposes/warnings).

IN: The programming language of the file being parsed. Used to determine whether certain Pascal-specific keywords are active.

IN: The value of localDebug in blockParseOutside. Set high for debugging.

IN: The function body. Used to populate the object (if it's a function).

IN: The object into which this object will eventually be inserted. (Used to set the appropriate field in the object; this function does NOT add the object to the apiOwner object in any way.)

IN: An override for the inputCounter field used when doing a subparse (handling a parse tree that has already been parsed once). Leave unset normally.

IN: An override for the blockOffset field used when doing a subparse (handling a parse tree that has already been parsed once). Leave unset normally.

IN: The superclass name (obtained from the block parser).

IN: The name of the class that this class implements (Java-specific, obtained from the block parser).

IN: Indicates that the processComment() call should me made on the resulting object even if curtype is UNKNOWN (meaning that the comment would normally get processed later in blockParseOutside). Used only in the case of a conversion request in blockParseOutisde.

A reference to an array of objects to be cross-linked.

A reference to the brace stack array.

The path of the current header. Used for error messages.

The current line number within the header. Used for error messages.

A reference to the new CPP symbol hash.

A reference to the new CPP argument hash.