Natural Docs
Version 1.2
Natural Docs
Packages
Objects
Languages
Output Formats
Extensions
Documentation
Indexes
Web Site

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:: 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.
Variables
sourceFile
The name of the source file currently being parsed.
parsedFile
An array of NaturalDocs::Parser::ParsedTopic objects.
parsingForInformation
Whether ParseForInformation() was called.
Functions
ParseForInformation
Parses the input file for information.
ParseForBuild
Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
Interface Functions
OnComment
The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
OnClass
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration.
OnClassParent
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.
Support Functions
Parse
Opens the source file and parses process.
CleanComment
Removes any extraneous formatting and whitespace from the comment.
Processing Functions
MakeAutoGroups
Creates group topics for files that do not have them.
MakeAutoGroupsFor
Creates group topics for sections of files that do not have them.
RepairScope
Recalculates the scope for all comment topics using the auto-topics and the scope record.
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.
MergeAutoTopics
Merges the automatically generated topics into the file.
AddScopeDelineators
Adds section and class topics to make sure the scope is correctly represented in the documentation.

Variables

sourceFile

my $sourceFile

The name of the source file currently being parsed.

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 name of the file 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 name of the file to parse for building.

Returns

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

Interface Functions

OnComment

sub OnComment #(commentLines,
lineNumber)

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 may be changed.
lineNumberThe line number of the first of the comment lines.

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 class encountered.

OnClassParent

sub OnClassParent #(class,
parent,
protection)

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

Parameters

classThe class we’re in.
parentThe class it inherits.
protectionPublic/private/protected, if applicable.  Undef otherwise.

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 file name if nothing better is found.

CleanComment

sub CleanComment #(commentLines)

Removes any extraneous formatting and whitespace from the comment.  Eliminates comment boxes, horizontal lines, leading and trailing line breaks, trailing whitespace from lines, and expands all tab characters.  It keeps leading whitespace, though, since it may be needed for example code, and multiple 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

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.

RepairScope

sub RepairScope #(autoTopics,
scopeRecord)

Recalculates the scope 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 topics.
scopeRecordA reference to an array of NaturalDocs::Languages::Advanced::ScopeChanges.

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.

MergeAutoTopics

sub MergeAutoTopics #(language,
autoTopics)

Merges the automatically generated topics into the file.  If an auto-topic matches an existing topic, it will be deleted and, if appropriate, have it’s prototype, class, and scope transferred.  If it doesn’t, the auto-topic will be inserted into the list unless NaturalDocs::Settings->DocumentedOnly() is set.

Parameters

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

AddScopeDelineators

sub AddScopeDelineators

Adds section and class topics to make sure the scope is correctly represented in the documentation.  Should be called last in this process.
Copyright © 2003-2004 Greg Valure.  Generated by Natural Docs.
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 name of the source file currently being parsed.
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 #(commentLines,
lineNumber)
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,
protection)
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 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 RepairScope #(autoTopics,
scopeRecord)
Recalculates the scope for all comment topics using the auto-topics and the scope record.
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 MergeAutoTopics #(language,
autoTopics)
Merges the automatically generated topics into the file.
sub AddScopeDelineators
Adds section and class topics to make sure the scope is correctly represented in the documentation.
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.
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.