HeaderDoc::Utilities

Declared In:

Introduction

Miscellaneous support functions.

Discussion

The most important of the functions in this package is parseTokens. It is used to provide a number of special tokens used the parsing process. Other functions

Groups

Debugging Functions

Functions for debugging purposes.

Group members:

printArray: Prints an ordered array.
printFields: Prints a reference to an array of fields for debugging.
printHash: Prints a hash table.

Test Helpers

Functions used by the test framework.

Group members:

loadhashes: Restores the hashes backed up with savehashes.
savehashes: Backs up the hashes in a temporary variable.

Path Functions

Functions for working with paths.

Group members:

findRelativePath: Finds the relative path to a file from another file.
getAbsPath: Converts a current-directory-relative path to an absolute path.
makeAbsolutePath: Converts a relative path to an absolute path.
safeName: Otains a safe filename from a header or class name.
safeNameDefaults: Default values for safeName.
safeNameNoCollide: Otains a safe filename from a header or class name, modifying the results as needed to guarantee uniqueness (even on case-insensitive volumes).

Availability Macro Functions

Functions for working with availability macros.

Group members:

addAvailabilityMacro: Adds a new availability macro.
complexAvailabilityToArray: Takes a new-style ("Magic") availability macro and returns a series of availability strings to match it.
complexAvailabilityTokenToOSAndVersion: Interprets an availability macro string within a __OSX_AVAILABLE_STARTING or __OSX_AVAILABLE_BUT_DEPRECATED macro instance.
getAvailabilityMacros: Get availability macro information from a file.

Sorting Functions

Functions for sorting objects.

Group members:

byAccessControl: Sort helper for sorting by access control (public/private).
byLinkage: Sort helper for sorting by linkage state (unused).
byMethodType: Sort helper for sorting objects by method type.
calcDepth: Updates global $depth variable.
dumpCaches: Prints UID caches for debugging purposes.
filterHTMLLinks: Replaces errant <link> tags with @link tags.
fixup_links: Converts @link tags in a string into appropriate link requests.
getDefaultEncoding: Returns the default encoding from your environment.
html_fixup_links: Converts @link tags in a string into appropriate link requests in HTML.
linkageAndObjName: Sort helper for sorting by linkage state (unused) and object name.
nameAndClass: Generates a "name" for a symbol based on the symbol name and class name.
nameFromAPIRef: Takes an API reference marker and returns the name in a suitable form.
objGroup: Sort helper for sorting by group.
objName: Sort helper for sorting by name.
peek: Returns the top entry in a stack array without removing it from the stack.
splitOnPara: Splits a string on the first paragraph (blank line).
stripLeading: Used for stripping the leading '#' off the beginning of every line.
warningFixup: Converts the internal form for @note, @warning, and @important tags into final form (HTML or XML).
xml_fixup_links: Converts @link tags in a string into appropriate link requests in XML.

API Reference Functions

Functions related to API references.

Group members:

chooseBestAPIRef: Returns the API reference that most closely matches the context provided by fromObj.
dereferenceUIDObject: Unregisters a UID-to-object mapping.
objectForUID: Looks up a HeaderDoc object based on its UID (API reference).
registerUID: Registers a name for lookup with resolveLink and a UID for UID conflict detection and avoidance.
resolveLink: Looks up a symbol name and returns a matching API reference if available.
resolveLinks: Runs resolveLinks on a directory of files.
unregister_force_uid_clear: Destroys a UID-to-object mapping without checking for an object match.
unregisterUID: Unregisters a name-to-UID mapping.

Configuration Functions

Functions for working with config files.

Group members:

getHashFromConfigFile: Reads a single HeaderDoc config file and returns a hash table of its values.
updateHashFromConfigFiles: Reads HeaderDoc config files and uses the keys to update a hash table.

File Functions

Functions for working with files

Group members:

getLangAndSubLangFromFilename: Returns the base filename, the language, and the initial language dialect based on a filename.
getLineArrays: Splits the input files into multiple text blocks
linesFromFile: Reads a file and stores the lines in an array (with newlines).

Parser helpers

Functions related to parsing code.

Group members:

allow_everything: Returns whether the curent language allows the -E (allow everything) flag.
isKeyword: Returns whether a token is a keyword.
parseTokens: Returns a set of parse tokens for the specified language and dialect.

String Functions

Functions for working with strings.

Group members:

casecmp: Returns whether two strings match and are non-empty.

HTML helpers

Functions used in HTML output.

Group members:

reencodeInUTF8: Converts non-UTF-8 encoded data to UTF-8.
sanitize: Sanitizes a string for use in a URL

Documentation Block Functions

Functions for working with parts of documentation blocks.

Group members:

canMatchTag: Returns whether a closing tag matches the top of the stack.
classTypeFromFieldAndBPinfo: Returns the API reference type for a class based on block parser info and the HeaderDoc comment.
emptyHDok: Returns whether a HeaderDoc comment requires a declaration after it or not.
filterHeaderDocComment: Processes a comment block, stripping off leading '*' and whitespace.
filterHeaderDocTagContents: Interprets the contents of tags like @discussion.
fixXHTMLAttributes: Converts legal HTML (but illegal XML) attributes to legal XML attributes.
getAPINameAndDisc: Gets an API name and discussion from a top-level tag, e.g. @function myFunctionName.
getJustTheTag: Gets the tag name from a tag.
guess_prioritized_encoding: Returns a reasonable, prioritized guess of the encoding for a block of data.
nestignore: Returns whether a HeaderDoc comment containing a given top-level tag can legally be nested inside a documented declaration.
newHTMLTagContext: Creates an obect with info about the current HTML tag context.
processHeaderComment: Processes a comment for a header (@header tag).
processTopLevel: The top-level HeaderDoc comment processing code.
replaceTag: Replaces the @warning and @important tags with appropriate HTML markup.
smartsplit: Attempts to intelligently split the leading line in a declaration.
stringToFields: Splits a string containing a HeaderDoc comment into an array of fields with the leading @ stripped. The first of these field is the leading discussion (if applicable).
validTag: Checks a HeaderDoc tag for validity in a given context.
warnHDComment: Prints a warning when a HeaderDoc command appears in a place where it is not expected.

XML Helpers

Functions used in XML output.

Group members:

html2xhtml: Converts a string of HTML to XHTML using xmllint (slow).
stripTags: Strips HTML tags from a block of HTML.
unescape_legal: Unescapes a legal character to avoid bogus length check warnings.

Member Functions

addAvailabilityMacro: Adds a new availability macro.
allow_everything: Returns whether the curent language allows the -E (allow everything) flag.
byAccessControl: Sort helper for sorting by access control (public/private).
byLinkage: Sort helper for sorting by linkage state (unused).
byMethodType: Sort helper for sorting objects by method type.
calcDepth: Updates global $depth variable.
canMatchTag: Returns whether a closing tag matches the top of the stack.
casecmp: Returns whether two strings match and are non-empty.
chooseBestAPIRef: Returns the API reference that most closely matches the context provided by fromObj.
classTypeFromFieldAndBPinfo: Returns the API reference type for a class based on block parser info and the HeaderDoc comment.
complexAvailabilityToArray: Takes a new-style ("Magic") availability macro and returns a series of availability strings to match it.
complexAvailabilityTokenToOSAndVersion: Interprets an availability macro string within a __OSX_AVAILABLE_STARTING or __OSX_AVAILABLE_BUT_DEPRECATED macro instance.
dereferenceUIDObject: Unregisters a UID-to-object mapping.
dumpCaches: Prints UID caches for debugging purposes.
emptyHDok: Returns whether a HeaderDoc comment requires a declaration after it or not.
filterHeaderDocComment: Processes a comment block, stripping off leading '*' and whitespace.
filterHeaderDocTagContents: Interprets the contents of tags like @discussion.
filterHTMLLinks: Replaces errant <link> tags with @link tags.
findRelativePath: Finds the relative path to a file from another file.
fixup_links: Converts @link tags in a string into appropriate link requests.
fixXHTMLAttributes: Converts legal HTML (but illegal XML) attributes to legal XML attributes.
getAbsPath: Converts a current-directory-relative path to an absolute path.
getAPINameAndDisc: Gets an API name and discussion from a top-level tag, e.g. @function myFunctionName.
getAvailabilityMacros: Get availability macro information from a file.
getDefaultEncoding: Returns the default encoding from your environment.
getHashFromConfigFile: Reads a single HeaderDoc config file and returns a hash table of its values.
getJustTheTag: Gets the tag name from a tag.
getLangAndSubLangFromFilename: Returns the base filename, the language, and the initial language dialect based on a filename.
getLineArrays: Splits the input files into multiple text blocks
guess_prioritized_encoding: Returns a reasonable, prioritized guess of the encoding for a block of data.
html2xhtml: Converts a string of HTML to XHTML using xmllint (slow).
html_fixup_links: Converts @link tags in a string into appropriate link requests in HTML.
isKeyword: Returns whether a token is a keyword.
linesFromFile: Reads a file and stores the lines in an array (with newlines).
linkageAndObjName: Sort helper for sorting by linkage state (unused) and object name.
loadhashes: Restores the hashes backed up with savehashes.
makeAbsolutePath: Converts a relative path to an absolute path.
nameAndClass: Generates a "name" for a symbol based on the symbol name and class name.
nameFromAPIRef: Takes an API reference marker and returns the name in a suitable form.
nestignore: Returns whether a HeaderDoc comment containing a given top-level tag can legally be nested inside a documented declaration.
newHTMLTagContext: Creates an obect with info about the current HTML tag context.
objectForUID: Looks up a HeaderDoc object based on its UID (API reference).
objGroup: Sort helper for sorting by group.
objName: Sort helper for sorting by name.
parseTokens: Returns a set of parse tokens for the specified language and dialect.
peek: Returns the top entry in a stack array without removing it from the stack.
printArray: Prints an ordered array.
printFields: Prints a reference to an array of fields for debugging.
printHash: Prints a hash table.
processHeaderComment: Processes a comment for a header (@header tag).
processTopLevel: The top-level HeaderDoc comment processing code.
reencodeInUTF8: Converts non-UTF-8 encoded data to UTF-8.
registerUID: Registers a name for lookup with resolveLink and a UID for UID conflict detection and avoidance.
replaceTag: Replaces the @warning and @important tags with appropriate HTML markup.
resolveLink: Looks up a symbol name and returns a matching API reference if available.
resolveLinks: Runs resolveLinks on a directory of files.
safeName: Otains a safe filename from a header or class name.
safeNameNoCollide: Otains a safe filename from a header or class name, modifying the results as needed to guarantee uniqueness (even on case-insensitive volumes).
sanitize: Sanitizes a string for use in a URL
savehashes: Backs up the hashes in a temporary variable.
smartsplit: Attempts to intelligently split the leading line in a declaration.
splitOnPara: Splits a string on the first paragraph (blank line).
stringToFields: Splits a string containing a HeaderDoc comment into an array of fields with the leading @ stripped. The first of these field is the leading discussion (if applicable).
stripLeading: Used for stripping the leading '#' off the beginning of every line.
stripTags: Strips HTML tags from a block of HTML.
unescape_legal: Unescapes a legal character to avoid bogus length check warnings.
unregister_force_uid_clear: Destroys a UID-to-object mapping without checking for an object match.
unregisterUID: Unregisters a name-to-UID mapping.
updateHashFromConfigFiles: Reads HeaderDoc config files and uses the keys to update a hash table.
validTag: Checks a HeaderDoc tag for validity in a given context.
warnHDComment: Prints a warning when a HeaderDoc command appears in a place where it is not expected.
warningFixup: Converts the internal form for @note, @warning, and @important tags into final form (HTML or XML).
xml_fixup_links: Converts @link tags in a string into appropriate link requests in XML.

addAvailabilityMacro

Adds a new availability macro.

sub addAvailabilityMacro(
    $$;$)

Parameters

token: The availability macri token to add.
description: A text description to use in content if this token is encountered in a declaration.

allow_everything

Returns whether the curent language allows the -E (allow everything) flag.

sub allow_everything

Parameters

lang: The current programming language.
sublang: The current programming language variant (e.g. cpp for C++).

byAccessControl

Sort helper for sorting by access control (public/private).

sub byAccessControl(
    $$)

Parameters

obj1: The first object to compare.
obj2: The second object to compare.

byLinkage

Sort helper for sorting by linkage state (unused).

sub byLinkage(
    $$)

Parameters

obj1: The first object to compare.
obj2: The second object to compare.

byMethodType

Sort helper for sorting objects by method type.

sub byMethodType(
    $$)

Parameters

obj1: Object 1.
obj2: Object 2.

calcDepth

Updates global $depth variable.

sub calcDepth

Parameters

self: The APIOwner object.

Discussion

The depth variable is used for creating links to outside resources.

canMatchTag

Returns whether a closing tag matches the top of the stack.

sub canMatchTag

Parameters

arrayref: A reference to the tag stack array.
tag: The closing tag to check.

Discussion

If the top node in the stack matches, returns 1.

If the top node was added implicitly, returns 1.

If the top node should go away because the top node is one that can be auto-closed, returns 1.

Otherwise returns 0.

casecmp

Returns whether two strings match and are non-empty.

sub casecmp

Parameters

a: The first string.
b: The second string.
case: If 1, perform case-sensitive comparison; if 0, perform a case-insensitive comparison.

chooseBestAPIRef

Returns the API reference that most closely matches the context provided by fromObj.

sub chooseBestAPIRef

Parameters

fromObj: The object you're linking from (empty if not known).
arrayref: A reference to an array containing the candidate API references to check.

Return Value

Returns the array ($value, $bogus) containing the best value and a flag to indicate whether the conflict is solely caused by a function parameter or local variable that is local to a different function.

classTypeFromFieldAndBPinfo

Returns the API reference type for a class based on block parser info and the HeaderDoc comment.

sub classTypeFromFieldAndBPinfo

Discussion

classTypeFromFieldAndBPinfo takes the type requested in the headerdoc comment (or auto if none requested), the type returned by the block parser, and the declaration (or the first few bytes thereof) and determines what HeaderDoc object should be created.

      Matching list:
        HD                    CODE                    Use
        @interface            ----                    same as @class (usually C COM Interface)
        @class                @class                  ObjCCategory (gross)
                                                      /|\ should be ObjCClass?
        @class                class                   CPPClass
        @class                typedef struct          CPPClass
        @class                @interface              ObjCClass
        @category             @interface              ObjCCategory
        @protocol             @protocol               ObjCProtocol
        auto                  @interface name : ...   ObjCClass
        auto                  @interface name(...)    ObjCCategory
        auto                  @protocol               ObjCProtocol
        auto                  class                   CPPClass
        auto                  namespace               CPPClass
        auto                  module                  CPPClass
        auto                  package                 CPPClass

complexAvailabilityToArray

Takes a new-style ("Magic") availability macro and returns a series of availability strings to match it.

sub complexAvailabilityToArray(
    $$)

Parameters

token: The initial token of the availability macro.
availstring: The remaining tokens in the availability macro as a string.

Discussion

This is used for the new-style complex availability macros. These can be identified by either the word Magic in the Availability.list file or by the presence of parenthesized arguments in the macro's actual usage.

complexAvailabilityTokenToOSAndVersion

Interprets an availability macro string within a __OSX_AVAILABLE_STARTING or __OSX_AVAILABLE_BUT_DEPRECATED macro instance.

sub complexAvailabilityTokenToOSAndVersion(
    $)

Parameters

string: The string to interpret.

dereferenceUIDObject

Unregisters a UID-to-object mapping.

sub dereferenceUIDObject

Parameters

uid: The UID to unregister.
object: The object to unregister.

Discussion

If the object is not registered with this UID, this call fails silently.

dumpCaches

Prints UID caches for debugging purposes.

sub dumpCaches

emptyHDok

Returns whether a HeaderDoc comment requires a declaration after it or not.

sub emptyHDok

Parameters

line: The line (beginning with a HeaderDoc token) to check.

Return Value

Returns 2 if a declaration cannot follow.

Returns 1 if a declaration is optional (empty is OK).

Returns 0 if a declaration is mandatory.

filterHeaderDocComment

Processes a comment block, stripping off leading '*' and whitespace.

sub filterHeaderDocComment

Parameters

headerDocCommentLinesArrayRef: A reference to an array of lines containing the HeaderDoc comment to process.
lang: The programming language for this comment.
sublang: The language variant for this comment (e.g. cpp for C++).
inputCounter: The line at which this comment block began.

filterHeaderDocTagContents

Interprets the contents of tags like @discussion.

sub filterHeaderDocTagContents

Parameters

tagcontents: The string to process.

Discussion

Process the contents of a tag, e.g. @discussion. The argument should contain just the text to be processed, not the tag itself or any end-of-comment marker.

filterHTMLLinks

Replaces errant <link> tags with @link tags.

sub filterHTMLLinks

Discussion

We ran into a nasty bug where somebody put in <link< and </link< instead of @link. For some reason, xmllint --html --xmlout fails to close the tag properly (as with other normally-unclosed HTML tags like <hr&gr;) which results in broken XML (not to mention that this wasn't the desired behavior). This function fixes that problem.

Note that xmllint is no longer trusted for tag fixing, but this code does no harm, so it was not removed. The right way to include style sheets in HeaderDoc HTML is through configuration files, not by embedding the HTML in a HeaderDoc comment.

findRelativePath

Finds the relative path to a file from another file.

sub findRelativePath

Parameters

fromMe: The path of the file where the link itself will be written.
toMe: The path of the file the link will point to.

fixup_links

Converts @link tags in a string into appropriate link requests.

sub fixup_links

Parameters

self: The APIOwner object.
string: The input string.
mode: Pass 0 for HTML, 1 for XML.

fixXHTMLAttributes

Converts legal HTML (but illegal XML) attributes to legal XML attributes.

sub fixXHTMLAttributes

Parameters

orig_attributes: A string containing the original attributes (without the trailing right angle bracket).

Return Value

A string containing the attributes formatted for XML output, with any unquoted values quoted, with any empty attributes assigned a value (adds =""), and with spaces between attributes if missing.

Discussion

This function attempts to return proper XML from even severely damaged HTML input, but in some cases, even this code must punt and drop the remaining attributes.

getAbsPath

Converts a current-directory-relative path to an absolute path.

sub getAbsPath

Parameters

filename: The original path.

getAPINameAndDisc

Gets an API name and discussion from a top-level tag, e.g. @function myFunctionName.

sub getAPINameAndDisc

Parameters

line: The contents of the tag (with the actual tag stripped off the front).
joinpattern: The contents of a regular expression. If nonempty, this expression determines a list of tokens which are considered to automatically get merged with the name if they appear before or after a space that would otherwise terminate the name. This allows a space prior to a leading parenthesis in a category name, for example. This join pattern is passed on to smartsplit.

getAvailabilityMacros

Get availability macro information from a file.

sub getAvailabilityMacros

Parameters

filename: The filename to read macros from. This file normally lives in the HeaderDoc modules directory.
quiet: Set to 1 to suppress normal output.

getDefaultEncoding

Returns the default encoding from your environment.

sub getDefaultEncoding

Discussion

Used to determine the encoding of time and date stamps returned by calls to POSIX strtime and friends.

getHashFromConfigFile

Reads a single HeaderDoc config file and returns a hash table of its values.

sub getHashFromConfigFile

Parameters

configHashRef: The configuration hash to update.
fileArrayRef: An array of files in the order that they should be read. Later values overwrites earlier values.

getJustTheTag

Gets the tag name from a tag.

sub getJustTheTag

Parameters

rawtag: The entire tag.

getLangAndSubLangFromFilename

Returns the base filename, the language, and the initial language dialect based on a filename.

sub getLangAndSubLangFromFilename

Parameters

filename: The filename.

Return Value

Returns ($rootFileName, $lang, $sublang).

getLineArrays

Splits the input files into multiple text blocks

sub getLineArrays

Parameters

rawLineArrayRef: A reference to an array of lines.
lang: The current programming language.
sublamg: The current programming language dialect (e.g. cpp for C++).

Discussion

This function does heavy text manipuation and is the prime suspect in cases of missing text in comments, odd spacing problems, and so on.

guess_prioritized_encoding

Returns a reasonable, prioritized guess of the encoding for a block of data.

sub guess_prioritized_encoding

html2xhtml

Converts a string of HTML to XHTML using xmllint (slow).

sub html2xhtml

Parameters

html: The string of HTML to convert.
debugname: An arbitrary name for this block of HTML (e.g. function MyFunc abstract) to distinguish it from other blocks in the output spew when debugging is enabled.

html_fixup_links

Converts @link tags in a string into appropriate link requests in HTML.

sub html_fixup_links

Parameters

self: The APIOwner object.
string: The input string.

Discussion

Calls fixup_links to do the actual work.

isKeyword

Returns whether a token is a keyword.

sub isKeyword

Parameters

keywordref: A reference to the keyword hash returned by keywords.
case_sensitive: A boolean value (0/1) indicating whether the current language uses case-sensitive token matching. Use the value returned by keywords.

linesFromFile

Reads a file and stores the lines in an array (with newlines).

sub linesFromFile

Parameters

filePath: The file to read.

Return Value

Returns the encoding and a reference to an array of lines.

linkageAndObjName

Sort helper for sorting by linkage state (unused) and object name.

sub linkageAndObjName(
    $$)

Parameters

obj1: The first object to compare.
obj2: The second object to compare.

loadhashes

Restores the hashes backed up with savehashes.

sub loadhashes

Parameters

alldecs: Pass 1 when testing alldecs, 0 otherwise.

Discussion

Used during the test process so that we can store this information and retrieve it after the tests are run.

makeAbsolutePath

Converts a relative path to an absolute path.

sub makeAbsolutePath

Parameters

relPath: A relative path.
args: The path of the file that the relative path is relative to.

Discussion

This is basically the inverse of findRelativePath.

nameAndClass

Generates a "name" for a symbol based on the symbol name and class name.

sub nameAndClass(
    $$$$)

Discussion

Depending on the values of $lang and HeaderDoc::nameFromAPIRefReturnsOnlyName, this function returns either the object's name, className::objectName, or [ className objectName ].

nameFromAPIRef

Takes an API reference marker and returns the name in a suitable form.

sub nameFromAPIRef

Discussion

If HeaderDoc::nameFromAPIRefReturnsOnlyName is set, returns the name by itself. Otherwise, the format depends on the language of the API symbol.

For example, if the API reference is of type "cpp", this function returns className::methodName for methods within a class.

Note: for now, the above is a lie. It just returns the name.

nestignore

Returns whether a HeaderDoc comment containing a given top-level tag can legally be nested inside a documented declaration.

sub nestignore

Discussion

Most calls to warnHDComment from headerDoc2HTML.pl or blockParseOutside should always result in an error (since they occur only outside the context of a declaration.

The exception is test point 12, which can cause false positives for @defineblock blocks. For this reason, there is an explicit check to ignore defines inside such a block.

newHTMLTagContext

Creates an obect with info about the current HTML tag context.

sub newHTMLTagContext

Parameters

tag: The HTML tag.
synthesized: Pass 1 if this was added automatically, 0 otherwise.

objectForUID

Looks up a HeaderDoc object based on its UID (API reference).

sub objectForUID

Parameters

uid: The UID to look up.

objGroup

Sort helper for sorting by group.

sub objGroup(
    $$)

Parameters

obj1: The first object to compare.
obj2: The second object to compare.

objName

Sort helper for sorting by name.

sub objName(
    $$)

Parameters

obj1: The first object to compare.
obj2: The second object to compare.

parseTokens

Returns a set of parse tokens for the specified language and dialect.

sub parseTokens

Parameters

lang: The current programming language.
sublang: The dialect of the programming language (e.g. cpp for C++).

Local Variables

Returned data structure fields

sotemplate: Start of template (usually <).
eotemplate: End of template (usually >).
soc: Start of multi-line comment.
eoc: End of multi-line comment.
ilc: Single-line comment.
ilc_b: Second single-line comment. Used in PHP where a single-line comment can start with either the C++-style two slashes (//) or the shell-style hash mark (#).
soconstructor: Start of a constructor. In some languages like TCL, there's a token for that.
sofunction: Token that marks the star of a function declaration. For example, in Perl, this is sub.
soprocedure: Token that marks the start of a procedure declaration in languages that have separate functions and procedures. For example, in Pascal, this is procedure.
operator: The operator keyword in C++.
sopreproc: Start of a preprocessor macro (in languages that support it).
lbrace: The primary left brace character.
lbraceunconditionalre: A regular expression containing other patterns that are always considered left braces. Currently used for for/if in Python and Ruby, and tell in AppleScript.
lbraceconditionalre: In Ruby/Python, a set of tokens that are treated as left braces unless they are immediately after a right brace. Basically, this handles begin/while/until when used at the end of a line in Ruby/Python.
rbrace: The primary right brace token.
enumname: The keyword enum or equivalent in languages that support this and have such a token.
unionname: The keyword union or equivalent in languages that support this and have such a token.
structname: The keyword struct or equivalent in languages that support this and have such a token.
typedefname: The keyword typedef or equivalent in languages that support this and have such a token.
varname: The keyword var or equivalent in languages that require a keyword before a variable declaration.
constname: The keyword const or equivalent in languages that have such a concept.
functionisbrace: Set to 1 if a function declaration is treated as an open brace.
classisbrace: Set to 1 if a class declaration is treated as an open brace. (This is not used for ObjC clases; they are special.)
structisbrace: Set to 1 if a struct declaration is treated as an open brace.
macronames: A reference to a hash table whose keys are the names of C preprocessor parser tokens (including the leading # character).
classregexp: A regular expression containing any tokens that should be treated as the start of a class.
classbraceregexp: A regular expression containing any tokens from classregexp that should also be treated as a brace (e.g. @interface in Objective-C).
classclosebraceregexp: A regular expression containing any tokens that both end a class declaration and should be treated as a close brace (e.g. @end in Objective-C).
accessregexp: A regular expression containing access control tokens (e.g. public, private, protected).
requiredregexp: A regular expression for the Objective-C @required and @optional keywords. Empty for other languages.
propname: A string containing the Objective-C @required and @optional keywords. Empty for other languages.
objcdynamicname: Unused for now.
objcsynthesizename: Unused for now.
moduleregexp: A regular expression containing tokens that should be treated as the start of a module declaration.
assignmentwithcolon: Used for AppleScript. Indicates that a colon is an assignment statement in this language.
labelregexp: A regular expression for Applescript labels.
parmswithcurlybraces: Indicates that function parameters are wrapped by curly braces in this language (TCL) instead of parentheses.
superclasseswithcurlybraces: Indicates that superclass names are wrapped by curly braces in this language (TCL).
definename: This is broken out so that we can abuse CPP in IDL processing for cpp_quote without actually allowing #define macros to be parsed from the code. This is only used for code parsing, NOT for interpreting the actual #define macros themselves!
regexpfirstcharpattern: A regular expression that matches any symbol that is a legal start token for a regular expression. In Perl, there are a lot of these. In Ruby and JavaScript, only slash (/) is allowed. In Tcl, only a left curly brace is allowed (because other regular expressions are just strings).
regexpcharpattern: A regular expression containing a list of tokens that are special in regular expressions. In general, only start tokens are listed, with the exception of the close curly brace. This should probably be the same for every language that supports regular expressions.
regexppattern: A list of special Perl commands that are immediately followed by a regular expression (e.g. tr).
singleregexppattern: A list of special Perl commands that are immediately followed by a one-part regular expression (e.g. qq). This is a strict subset of regexppattern.
regexpAllowedAfter: A list of symbols that a regular expression can follow. This prevents other uses of certain common symbol (e.g. /) from incorrectly triggering the start of regular expression parsing.
regexpAllowedAtStartOfLine: Set to 1 in languages where regular expressions are first-class objects (Ruby) and thus can legally appear as the first symbol on a line in addition to places that can be detected based on the previous symbol.
TCLregexpcommand: Set to "regexp" in Tcl. This is a regular expression that matches a list of commands in scripting languages that can take an unquoted (non-string) regular expression.
rbracetakesargument: Normally zero. Set to 1 if a right brace marker (e.g. end) is followed by another token (e.g. tell) that tells what type of block it closes.

peek

Returns the top entry in a stack array without removing it from the stack.

sub peek

Parameters

ref: A reference to the stack array.

Discussion

This is a trivial function that returns a look at the top of a stack. This seems like it should be part of the language. If there is an equivalent, this should be dropped.

printArray

Prints an ordered array.

sub printArray

Parameters

theArray: The array to print.

printFields

Prints a reference to an array of fields for debugging.

sub printFields

Parameters

fieldref: The array reference.

printHash

Prints a hash table.

sub printHash

Parameters

theHash: The hash to print.

processHeaderComment

Processes a comment for a header (@header tag).

sub processHeaderComment

Parameters

apiOwner: The Header object.
rootOutputDir: The output directory where this header's content should be written.
fieldArrayRef: An array of fields in this comment.
lang: The programming language for this header.
debugging: Set to 1 to enable additional debug output.
reprocess_input: Usually 0 on entry. Set to 1 by return if this comment includes tags that would require rereading and reprocessing the entire header (e.g. ignoring certain tokens). Passed by reference.

processTopLevel

The top-level HeaderDoc comment processing code.

sub processTopLevel

Parameters

inHeader: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @header tag.
inClass: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @class tag.
inInterface: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @interface tag.
inCPPHeader: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @language tag with a value of c++.
inOCCHeader: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @language tag with a value of objc.
inPerlScript: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @language tag with a value of perl.
inShellScript: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @language tag with a value of shell.
inPHPScript: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @language tag with a value of php.
inJavaSource: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @language tag with a value of java or javascript.
inFunctionGroup: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @functiongroup tag.
inGroup: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @group tag.
inFunction: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @function tag.
inPDefine: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @define tag, 2 if it contains an @defineblock or @definedblock tag, or 0 if it contains neither.
inTypedef: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @typedef tag.
inUnion: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @union tag.
inStruct: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @struct tag.
inConstant: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @constant tag.
inVar: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @var tag.
inEnum: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @enum tag.
inMethod: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @method tag.
inAvailabilityMacro: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag in this comment is an @availabilitymacro tag.
inUnknown: Typically 0 at this point. The returned version of this value contains 1 if the top-level tag is absent.
classType: The class type of the class that this comment is inside. Used to determine handling of the @method tag.
line: The HeaderDoc comment block.
inputCounter: The line number of this line within the current LineRange block.
blockOffset: The line number of the first line within the current LineRange block relative to the start of the file.
fullpath: The full path of the file being parsed.
linenumdebug: Enables/disables printing debug information related to line numbering.
localDebug: Enables/disables debugging.

Discussion

Processes a HeaderDoc comment looking for top-level (e.g. @function) HeaderDoc tags.

This code was moved from the main headerDoc2HTML.pl tool so that it could be used as part of the test suite.

reencodeInUTF8

Converts non-UTF-8 encoded data to UTF-8.

sub reencodeInUTF8

Parameters

string: The string to convert.

registerUID

Registers a name for lookup with resolveLink and a UID for UID conflict detection and avoidance.

sub registerUID(
    $$$)

Parameters

uid: The unique ID (API reference) to register).
name: The symbol name to register.
object: The object matching this registration (a subclass of HeaderElement).

replaceTag

Replaces the @warning and @important tags with appropriate HTML markup.

sub replaceTag(
    $$$)

resolveLink

Looks up a symbol name and returns a matching API reference if available.

sub resolveLink

Discussion

This function supports the use of the @link tag to link to functions and types within a single file. If you specify something like @link foo .... @/link, This code gets called. If you specify an API ref instead of a bare symbol name, you should not even get here.

Known issues:

Not all APIs are registered here. It would be nice to be able to link to classes.

This uses the first UID by default. It should be using the nearest UID instead (e.g. a method within the current class).

resolveLinks

Runs resolveLinks on a directory of files.

sub resolveLinks(
    $$$)

Parameters

path

The path of a directory containing files to link together.

xreflist

A (regrettably space-delimited) list of external cross-reference files. (Optional.)

A space-delimited list of API reference prefixes (in addition to the default apple_ref).

safeName

Otains a safe filename from a header or class name.

sub safeName

Parameters

args

A hash of arguments. The default arguments are in safeNameDefaults. Normally, you override only the filename argument, e.g.

my $safename = &safeName(filename => $name);

safeNameNoCollide

Otains a safe filename from a header or class name, modifying the results as needed to guarantee uniqueness (even on case-insensitive volumes).

sub safeNameNoCollide

Parameters

args

A hash of arguments. The default arguments are in safeNameDefaults. Normally, you override only the filename argument, e.g.

my $safename = &safeNameNoCollide(filename => $name);

sanitize

Sanitizes a string for use in a URL

sub sanitize

Parameters

string: The string to sanitize.
isname: Is this the name of a function or type? If so, be a little looser to conform with the apple_ref spec (even though the result does technically violate the HTML spec). (Optional; default 0.)

savehashes

Backs up the hashes in a temporary variable.

sub savehashes

Parameters

alldecs: Pass 1 when testing alldecs, 0 otherwise.

Discussion

Used during the test process so that we can store this information and retrieve it after the tests are run.

smartsplit

Attempts to intelligently split the leading line in a declaration.

sub smartsplit

Parameters

line: The line to split.
pattern: A pattern containing tokens that should cause the following token to be concatenated onto the first one even if there are spaces between them.

Discussion

For example, if someone mistakenly writes @function class :: function, this function attempts to do the right thing.

splitOnPara

Splits a string on the first paragraph (blank line).

sub splitOnPara

Parameters

string: The string to split.

Return Value

Returns the first part, the rest, and whether the split was successful (1) or not (0).

stringToFields

Splits a string containing a HeaderDoc comment into an array of fields with the leading @ stripped. The first of these field is the leading discussion (if applicable).

sub stringToFields(
    $$$$$$)

stripLeading

Used for stripping the leading '#' off the beginning of every line.

sub stripLeading

Discussion

This could probably be done with a couple of regular expressions, but the filter code is tricky enough without making it even less readable.

stripTags

Strips HTML tags from a block of HTML.

sub stripTags

Parameters

html: The source HTML.

unescape_legal

Unescapes a legal character to avoid bogus length check warnings.

sub unescape_legal

unregister_force_uid_clear

Destroys a UID-to-object mapping without checking for an object match.

sub unregister_force_uid_clear

Parameters

uid: The UID to forcibly unregister.

unregisterUID

Unregisters a name-to-UID mapping.

sub unregisterUID

Parameters

uid: The UID to unregister.
name: The name to unregister.

Discussion

If the name is not registered with this UID, this call fails silently.

updateHashFromConfigFiles

Reads HeaderDoc config files and uses the keys to update a hash table.

sub updateHashFromConfigFiles

Parameters

configHashRef: The configuration hash to update.
fileArrayRef: An array of files in the order that they should be read. Later values overwrites earlier values.

validTag

Checks a HeaderDoc tag for validity in a given context.

sub validTag

Parameters

field

The tag name.

level

Default 0.

0 — Include both top-level (e.g. @function) and second-level (e.g. @abstract) HeaderDoc tags.
1 — Include only top-level (e.g. @function) HeaderDoc tags.
2 — Include only second-level (e.g. @abstract) HeaderDoc tags.

Return Value

Returns 1 if a tag is valid, -1 if a tag should be replaced with another string, or 0 if a tag is not valid.

warnHDComment

Prints a warning when a HeaderDoc command appears in a place where it is not expected.

sub warnHDComment

Parameters

teststring: string to be checked for headerdoc markup
linenum: line number
dectype: declaration type
dp: debug point string

Return Value

Returns 0 if this HeaerDoc comment is legal.

Returns 1 if this HeaerDoc comment is not legal.

Returns 2 if this HeaerDoc comment is an @define inside an @defineblock tag.

warningFixup

Converts the internal form for @note, @warning, and @important tags into final form (HTML or XML).

sub warningFixup

xml_fixup_links

Converts @link tags in a string into appropriate link requests in XML.

sub xml_fixup_links

Parameters

self: The APIOwner object.
string: The input string.

Discussion

Calls fixup_links to do the actual work.

Member Data

HeaderDoc::Utilities::VERSION: The revision control revision number for this module.
safeNameDefaults: Default values for safeName.

HeaderDoc::Utilities::VERSION

The revision control revision number for this module.

$HeaderDoc::Utilities::VERSION = '$Revision: 1334261201 $';

Discussion

In the git repository, contains the number of seconds since January 1, 1970.

safeNameDefaults

Default values for safeName.

my %safeNameDefaults = (
    filename => "",
    fileLengthLimit =>"$macFileLengthLimit",
    longestExtension => "$longestExtension");

Last Updated: Saturday, August 06, 2016