NaturalDocs::Parser

A package that coordinates source file parsing between the NaturalDocs::Languages::Base-derived objects and its own sub-packages such as NaturalDocs::Parser::Native.  Also handles sending symbols to NaturalDocs::SymbolTable and other generic topic processing.

Usage and Dependencies

Summary
NaturalDocs::ParserA package that coordinates source file parsing between the NaturalDocs::Languages::Base-derived objects and its own sub-packages such as NaturalDocs::Parser::Native.
Variables
sourceFileThe source FileName currently being parsed.
languageThe language object for the file, derived from NaturalDocs::Languages::Base.
parsedFileAn array of NaturalDocs::Parser::ParsedTopic objects.
parsingForInformationWhether ParseForInformation() was called.
Functions
ParseForInformationParses the input file for information.
ParseForBuildParses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
Interface Functions
OnCommentThe function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
OnClassA function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration.
OnClassParentA function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.
Support Functions
ParseOpens the source file and parses process.
CleanCommentRemoves any extraneous formatting and whitespace from the comment.
Processing Functions
RepairPackagesRecalculates the packages for all comment topics using the auto-topics and the scope record.
MergeAutoTopicsMerges the automatically generated topics into the file.
RemoveRemainingHeaderlessTopicsAfter MergeAutoTopics() is done, this function removes any remaining headerless topics from the file.
MakeAutoGroupsCreates group topics for files that do not have them.
MakeAutoGroupsForCreates group topics for sections of files that do not have them.
AddToClassHierarchyAdds any class topics to the class hierarchy, since they may not have been called with OnClass() if they didn’t match up to an auto-topic.
AddPackageDelineatorsAdds section and class topics to make sure the package is correctly represented in the documentation.
BreakListsBreaks list topics into individual topics.
GetSummaryFromBodyReturns the summary text from the topic body.
GetSummaryFromDescriptionListReturns the summary text from a description list entry.

Variables

sourceFile

my $sourceFile

The source FileName currently being parsed.

language

my $language

The language object for the file, derived from NaturalDocs::Languages::Base.

parsedFile

my @parsedFile

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

parsingForInformation

my $parsingForInformation

Whether ParseForInformation() was called.  If false, then ParseForBuild() was called.

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 FileName to parse.

ParseForBuild

sub ParseForBuild #(file)

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 FileName to parse for building.

Returns

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

Interface Functions

OnComment

sub OnComment #(string[] commentLines,
int lineNumber,
bool isJavaDoc)

The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.

Parameters

commentLinesAn arrayref of the comment’s lines.  The language’s comment symbols should be converted to spaces, and there should be no line break characters at the end of each line.  The original memory will be changed.
lineNumberThe line number of the first of the comment lines.
isJavaDocWhether the comment is in JavaDoc format.

Returns

The number of topics created by this comment, or zero if none.

OnClass

sub OnClass #(class)

A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration.

Parameters

classThe SymbolString of the class encountered.

OnClassParent

sub OnClassParent #(class,
parent,
scope,
using,
resolvingFlags)

A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.

Parameters

classThe SymbolString of the class we’re in.
parentThe SymbolString of the class it inherits.
scopeThe package SymbolString that the reference appeared in.
usingAn arrayref of package SymbolStrings that the reference has access to via “using” statements.
resolvingFlagsAny Resolving Flags to be used when resolving the reference.  RESOLVE_NOPLURAL is added automatically since that would never apply to source code.

Support Functions

Parse

sub Parse

Opens the source file and parses process.  Most of the actual parsing is done in NaturalDocs::Languages::Base->ParseFile() and OnComment(), though.

Do not call externally.  Rather, call ParseForInformation() or ParseForBuild().

Returns

The default menu title of the file.  Will be the FileName if nothing better is found.

CleanComment

sub CleanComment #(commentLines)

Removes any extraneous formatting and whitespace from the comment.  Eliminates comment boxes, horizontal lines, trailing whitespace from lines, and expands all tab characters.  It keeps leading whitespace, though, since it may be needed for example code, and blank lines, since the original line numbers are needed.

Parameters

commentLinesAn arrayref of the comment lines to clean.  The original memory will be changed.  Lines should have the language’s comment symbols replaced by spaces and not have a trailing line break.

Processing Functions

RepairPackages

sub RepairPackages #(autoTopics,
scopeRecord)

Recalculates the packages for all comment topics using the auto-topics and the scope record.  Call this before calling MergeAutoTopics().

Parameters

autoTopicsA reference to the list of automatically generated NaturalDocs::Parser::ParsedTopics.
scopeRecordA reference to an array of NaturalDocs::Languages::Advanced::ScopeChanges.

MergeAutoTopics

sub MergeAutoTopics #(language,
autoTopics)

Merges the automatically generated topics into the file.  If an auto-topic matches an existing topic, it will have it’s prototype and package transferred.  If it doesn’t, the auto-topic will be inserted into the list unless NaturalDocs::Settings->DocumentedOnly() is set.  If an existing topic doesn’t have a title, it’s assumed to be a headerless comment and will be merged with the next auto-topic or discarded.

Parameters

languageThe NaturalDocs::Languages::Base-derived class for the file.
autoTopicsA reference to the list of automatically generated topics.

RemoveRemainingHeaderlessTopics

sub RemoveRemainingHeaderlessTopics

After MergeAutoTopics() is done, this function removes any remaining headerless topics from the file.  If they don’t merge into anything, they’re not valid topics.

MakeAutoGroups

sub MakeAutoGroups

Creates group topics for files that do not have them.

MakeAutoGroupsFor

sub MakeAutoGroupsFor #(startIndex,
endIndex)

Creates group topics for sections of files that do not have them.  A support function for MakeAutoGroups().

Parameters

startIndexThe index to start at.
endIndexThe index to end at.  Not inclusive.

Returns

The number of group topics added.

AddToClassHierarchy

sub AddToClassHierarchy

Adds any class topics to the class hierarchy, since they may not have been called with OnClass() if they didn’t match up to an auto-topic.

AddPackageDelineators

sub AddPackageDelineators

Adds section and class topics to make sure the package is correctly represented in the documentation.  Should be called last in this process.

BreakLists

sub BreakLists

Breaks list topics into individual topics.

GetSummaryFromBody

sub GetSummaryFromBody #(body)

Returns the summary text from the topic body.

Parameters

bodyThe complete topic body, in NDMarkup.

Returns

The topic summary, or undef if none.

GetSummaryFromDescriptionList

sub GetSummaryFromDescriptionList #(description)

Returns the summary text from a description list entry.

Parameters

descriptionThe description in NDMarkup.  Should be the content between the <dd></dd> tags only.

Returns

The description summary, or undef if none.

A base class for all programming language parsers.
A package that converts comments from Natural Docs’ native format into NaturalDocs::Parser::ParsedTopic objects.
my $sourceFile
The source FileName currently being parsed.
A string representing the absolute, platform-dependent path to a file.
my $language
The language object for the file, derived from NaturalDocs::Languages::Base.
my @parsedFile
An array of NaturalDocs::Parser::ParsedTopic objects.
A class for parsed topics of source files.
my $parsingForInformation
Whether ParseForInformation() was called.
sub ParseForInformation #(file)
Parses the input file for information.
sub ParseForBuild #(file)
Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
sub OnComment #(string[] commentLines,
int lineNumber,
bool isJavaDoc)
The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
sub OnClass #(class)
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration.
sub OnClassParent #(class,
parent,
scope,
using,
resolvingFlags)
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.
sub Parse
Opens the source file and parses process.
sub CleanComment #(commentLines)
Removes any extraneous formatting and whitespace from the comment.
sub RepairPackages #(autoTopics,
scopeRecord)
Recalculates the packages for all comment topics using the auto-topics and the scope record.
sub MergeAutoTopics #(language,
autoTopics)
Merges the automatically generated topics into the file.
sub RemoveRemainingHeaderlessTopics
After MergeAutoTopics() is done, this function removes any remaining headerless topics from the file.
sub MakeAutoGroups
Creates group topics for files that do not have them.
sub MakeAutoGroupsFor #(startIndex,
endIndex)
Creates group topics for sections of files that do not have them.
sub AddToClassHierarchy
Adds any class topics to the class hierarchy, since they may not have been called with OnClass() if they didn’t match up to an auto-topic.
sub AddPackageDelineators
Adds section and class topics to make sure the package is correctly represented in the documentation.
sub BreakLists
Breaks list topics into individual topics.
sub GetSummaryFromBody #(body)
Returns the summary text from the topic body.
sub GetSummaryFromDescriptionList #(description)
Returns the summary text from a description list entry.
A package that handles all the gory details of managing symbols.
A package to handle the command line and various other program settings.
A package to manage all the programming languages Natural Docs supports.
A package that manages information about the files in the source tree, as well as the list of files that have to be parsed and built.
A package that handles all the gory details of managing the class hierarchy.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
Used to influence the method of resolving references in NaturalDocs::SymbolTable.
The reference text may not be interpreted as a plural, and thus match singular forms as well.
Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
A class used to store a scope change.
sub DocumentedOnly
Returns whether undocumented code aspects should be included in the output.
A markup format used by the parser, both internally and in NaturalDocs::Parser::ParsedTopic objects.
Close