NaturalDocs:: Parser

A package that parses the input file either for symbols or to send to NaturalDocs::Builder

Usage and Dependencies

Summary
A package that parses the input file either for symbols or to send to NaturalDocs::Builder.
A hash of the text synonyms for the tokens.
The file currently being parsed.
The language of the file currently being parsed.
What mode the parser is currently in.
The scope at the current point in the file.
Whether the current file has Natural Docs content or not.
The default menu title of the current file.
The state of the default menu title, since it can be determined different ways.
An array of NaturalDocs::Parser::ParsedTopic objects.
Parses the input file for information.
Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
Do not call these functions directly, as they are stages in the parsing process.
Begins the parsing process.
Extracts comments from the passed content and sends them individually to CleanComment().
Parses the passed content for single line comments.
Removes any extraneous formatting or whitespace from the comment and sends it to ExtractTopics().
Takes the comment and extracts any Natural Docs topics in it.
Handles the parsed topic as appropriate for the parser mode.
Converts the section body to NDMarkup.
Applies rich NDMarkup formatting to a chunk of text.
Returns whether the tag is a possible opening or closing tag, or neither.
Returns whether a tag is closed or not, where it’s closed if it is, and optionally whether there is any whitespace between the tags.

Variables

synonyms

my %synonyms

A hash of the text synonyms for the tokens.  For example, “procedure”, “routine”, and “function” all map to TOPIC_FUNCTION.  The keys are the synonyms in all lowercase, and the values are one of the Topic Types

file

my $file

The file currently being parsed. 

language

my $language

The language of the file currently being parsed.  Is a NaturalDocs::Languages::Language object. 

mode

What mode the parser is currently in. 

PARSE_FOR_INFORMATIONThe parser was called with ParseForInformation().  It will go through the file and extract symbol definitions and references for NaturalDocs::SymbolTable and information about the file for NaturalDocs::Project
PARSE_FOR_BUILDThe parser was called with ParseForBuild().  It will go through the file and generate NaturalDocs::Parser::ParsedTopic objects to be used in generating output. 

scope

my $scope

The scope at the current point in the file.  This is a package variable because it needs to be preserved between function calls. 

hasContent

my $hasContent

Whether the current file has Natural Docs content or not. 

defaultMenuTitle

my $defaultMenuTitle

The default menu title of the current file.  Will be the file name if a suitable one cannot be found. 

menuTitleState

The state of the default menu title, since it can be determined different ways. 

States

INDEFINITEThe title has a value, but will be changed by any content. 
DEFINITEThe title has been determined conclusively. 
DEFINITE_IF_ONLYThe title will keep its current value only if is no more content in the file. 

parsedFile

my @parsedFile

An array of NaturalDocs::Parser::ParsedTopic objects. 

Functions

ParseForInformation

sub ParseForInformation #(file)

Parses the input file for information.  Will update the information about the file in NaturalDocs::SymbolTable and NaturalDocs::Project

Parameters

fileThe name of the file to parse. 

ParseForBuild

sub ParseForBuild #(filename)

Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref. 

Note that all new and changed files should be parsed for symbols via ParseForInformation() before calling this function on any file.  The reason is that NaturalDocs::SymbolTable needs to know about all the symbol definitions and references to resolve them properly. 

Parameters

fileThe name of the file to parse for building. 

Returns

An arrayref of the source file as NaturalDocs::Parser::ParsedTopic objects. 

Parser Stages

Do not call these functions directly, as they are stages in the parsing process.  Rather, call ParseForInformation() or ParseForBuild()

Parse

sub Parse

Begins the parsing process.  Do not call directly; rather, call ParseForInformation() or ParseForBuild()file and mode should be set prior to calling; it will set everything else itself. 

ExtractComments

sub ExtractComments #(content)

Extracts comments from the passed content and sends them individually to CleanComment()

Parameters

contentThe file content. 

ExtractLineComments

sub ExtractLineComments #(content)

Parses the passed content for single line comments.  Merges adjacent ones and sends them to CleanComment()

Parameters

contentThe content to be searched for single line comments. 

CleanComment

sub CleanComment #(comment, functionPrototype, variablePrototype)

Removes any extraneous formatting or whitespace from the comment and sends it to ExtractTopics().  Eliminates comment boxes, horizontal lines, leading and trailing line breaks, leading and trailing whitespace from lines, and more than two line breaks in a row. 

Parameters

commentThe comment to clean. 
functionPrototypeThe potential function prototype appearing after it.  Undef if none or not applicable. 
variablePrototypeThe potential variable prototype appearing after it.  Undef if none or not applicable. 

ExtractTopics

sub ExtractTopics #(comment, functionPrototype, variablePrototype)

Takes the comment and extracts any Natural Docs topics in it. 

Parameters

commentThe comment to interpret
functionPrototypeThe potential function prototype.  Undef if none or not applicable. 
variablePrototypeThe potential variable prototype.  Undef if none or not applicable. 

InterpretTopic

sub InterpretTopic #(name, class, type, body, functionPrototype, variablePrototype)

Handles the parsed topic as appropriate for the parser mode.  If we’re parsing for build, it adds it to parsedFile.  If we’re parsing for symbols, it adds all symbol definitions and references to NaturalDocs::SymbolTable.  Scope is gotten from the package variable scope instead of from the parameters. 

Parameters

nameThe name of the section. 
classThe class of the section. 
typeThe section type. 
bodyThe section’s body in NDMarkup
functionPrototypeThe potential function prototype. 
variablePrototypeThe potential variable prototype. 

Support Functions

FormatBody

sub FormatBody #(body, type)

Converts the section body to NDMarkup

Parameters

bodyThe body itself. 
typeThe type of the section. 

Returns

The body formatted in NDMarkup

RichFormatTextBlock

sub RichFormatTextBlock #(text)

Applies rich NDMarkup formatting to a chunk of text.  This includes both amp chars, formatting tags, and link tags. 

Parameters

textThe block of text to format. 

Returns

The formatted text block. 

TagType

sub TagType #(textBlocks, index)

Returns whether the tag is a possible opening or closing tag, or neither.  “Possible” because it doesn’t check if an opening tag is closed or a closing tag is opened, just whether the surrounding characters allow it to be a candidate for a tag.  For example, in “A _B” the underscore is a possible opening underline tag, but in “A_B” it is not.  Support function for RichFormatTextBlock()

Parameters

textBlocksA reference to an array of text blocks. 
indexThe index of the tag. 

Returns

POSSIBLE_OPENING_TAG, POSSIBLE_CLOSING_TAG, or NOT_A_TAG. 

ClosingTag

sub ClosingTag #(textBlocks, index, hasWhitespace)

Returns whether a tag is closed or not, where it’s closed if it is, and optionally whether there is any whitespace between the tags.  Support function for RichFormatTextBlock()

The results of this function are in full context, meaning that if it says a tag is closed, it can be interpreted as that tag in the final output.  It takes into account any spoiling factors, like there being two opening tags in a row. 

Parameters

textBlocksA reference to an array of text blocks. 
indexThe index of the opening tag. 
hasWhitespaceRefA reference to the variable that will hold whether there is whitespace between the tags or not.  If undef, the function will not check.  If the tag is not closed, the variable will not be changed. 

Returns

If the tag is closed, it returns the index of the closing tag and puts whether there was whitespace between the tags in hasWhitespaceRef if it was specified.  If the tag is not closed, it returns -1 and doesn’t touch the variable pointed to by hasWhitespaceRef.