NaturalDocs:: Parser

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

Usage and Dependencies

Prior to use, NaturalDocs::Settings, NaturalDocs::Languages, NaturalDocs::Project, and NaturalDocs::SymbolTable must be initialized. NaturalDocs::SymbolTable does not have to be fully resolved.
Aside from that, the package is ready to use right away. It does not have its own initialization function.

Summary

NaturalDocs:: Parser	A package that parses the input file either for symbols or to send to NaturalDocs::Builder.
Variables
synonyms	A hash of the text synonyms for the tokens.
file	The file currently being parsed.
language	The language of the file currently being parsed.
mode	What mode the parser is currently in.
scope	The scope at the current point in the file.
hasContent	Whether the current file has Natural Docs content or not.
defaultMenuTitle	The default menu title of the current file.
menuTitleState	The state of the default menu title, since it can be determined different ways.
parsedFile	An array of NaturalDocs::Parser::ParsedTopic objects.
Functions
ParseForInformation	Parses the input file for information.
ParseForBuild	Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
Parser Stages	Do not call these functions directly, as they are stages in the parsing process.
Parse	Begins the parsing process.
ExtractComments	Extracts comments from the passed content and sends them individually to CleanComment().
ExtractLineComments	Parses the passed content for single line comments.
CleanComment	Removes any extraneous formatting or whitespace from the comment and sends it to ExtractTopics().
ExtractTopics	Takes the comment and extracts any Natural Docs topics in it.
InterpretTopic	Handles the parsed topic as appropriate for the parser mode.
Support Functions
FormatBody	Converts the section body to NDMarkup.
RichFormatTextBlock	Applies rich NDMarkup formatting to a chunk of text.
TagType	Returns whether the tag is a possible opening or closing tag, or neither.
ClosingTag	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_INFORMATION	The 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_BUILD	The 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

INDEFINITE	The title has a value, but will be changed by any content.
DEFINITE	The title has been determined conclusively.
DEFINITE_IF_ONLY	The 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

file	The 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

file	The 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

content

The file content.

ExtractLineComments

sub ExtractLineComments #(content)

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

Parameters

content

The 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

comment	The comment to clean.
functionPrototype	The potential function prototype appearing after it. Undef if none or not applicable.
variablePrototype	The 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

comment	The comment to interpret
functionPrototype	The potential function prototype. Undef if none or not applicable.
variablePrototype	The 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

name	The name of the section.
class	The class of the section.
type	The section type.
body	The section’s body in NDMarkup.
functionPrototype	The potential function prototype.
variablePrototype	The potential variable prototype.

Support Functions

FormatBody

sub FormatBody #(body, type)

Converts the section body to NDMarkup.

Parameters

body	The body itself.
type	The 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

text	The 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

textBlocks	A reference to an array of text blocks.
index	The 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

textBlocks	A reference to an array of text blocks.
index	The index of the opening tag.
hasWhitespaceRef	A 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.