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

NaturalDocs:: Parser:: Native

A package that converts comments from Natural Docs’ native format into NaturalDocs::Parser::ParsedTopic objects.  Unlike most second-level packages, these are packages and not object classes.

Summary
NaturalDocs:: Parser:: Native
A package that converts comments from Natural Docs’ native format into NaturalDocs::Parser::ParsedTopic objects.
Variables
scope
The scope at the current point in the file.
functionListIgnoredHeadings
An existence hash of all the headings that prevent the parser from creating function list symbols.
Interface Functions
Start
This will be called whenever a file is about to be parsed.
ParseComment
This will be called whenever a comment capable of containing Natural Docs content is found.
Support Functions
MakeParsedTopic
Creates a NaturalDocs::Parser::ParsedTopic object for the passed parameters.
FormatBody
Converts the section body to NDMarkup.
AddToCodeBlock
Adds a line of text to a code block, handling all the indentation processing required.
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

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.

functionListIgnoredHeadings

my %functionListIgnoredHeadings

An existence hash of all the headings that prevent the parser from creating function list symbols.  Whenever one of these headings are used in a function list topic, symbols are not created from definition lists until the next heading.  The keys are in all lowercase.

Interface Functions

Start

sub Start

This will be called whenever a file is about to be parsed.  It allows the package to reset its internal state.

ParseComment

sub ParseComment #(commentLines,
lineNumber,
parsedTopics)

This will be called whenever a comment capable of containing Natural Docs content is found.

Parameters

commentLinesAn arrayref of the comment’s lines.  All tabs must be expanded into spaces, and all comment symbols, boxes, lines, and trailing whitespace should be removed.  Leading whitespace and multiple blank lines should be preserved.
lineNumberThe line number of the first of the comment lines.
parsedTopicsA reference to the array where any new NaturalDocs::Parser::ParsedTopics should be placed.

Returns

The number of parsed topics added to the array, or zero if none.

Support Functions

MakeParsedTopic

sub MakeParsedTopic #(name,
class,
type,
body,
lineNumber)

Creates a NaturalDocs::Parser::ParsedTopic object for the passed parameters.  Scope is gotten from the package variable scope instead of from the parameters.  The summary is generated from the body.

Parameters

nameThe name of the section.
classThe class of the section.
typeThe section type.
bodyThe section’s body in NDMarkup.
lineNumberThe topic’s line number.

Returns

The NaturalDocs::Parser::ParsedTopic object.

FormatBody

sub FormatBody #(commentLines,
startingIndex,
endingIndex,
type)

Converts the section body to NDMarkup.

Parameters

commentLinesThe arrayref of comment lines.
startingIndexThe starting index of the body to format.
endingIndexThe ending index of the body to format, not inclusive.
typeThe type of the section.

Returns

The body formatted in NDMarkup.

AddToCodeBlock

sub AddToCodeBlock #(line,
codeBlockRef,
removedSpacesRef)

Adds a line of text to a code block, handling all the indentation processing required.

Parameters

lineThe line of text to add.
codeBlockRefA reference to the code block to add it to.
removedSpacesRefA reference to a variable to hold the number of spaces removed.  It needs to be stored between calls.  It will reset itself automatically when the code block codeBlockRef points to is undef.

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.
Copyright © 2003-2004 Greg Valure.  Generated by Natural Docs.
A class for parsed topics of source files.
my $scope
The scope at the current point in the file.
my %functionListIgnoredHeadings
An existence hash of all the headings that prevent the parser from creating function list symbols.
sub Start
This will be called whenever a file is about to be parsed.
sub ParseComment #(commentLines,
lineNumber,
parsedTopics)
This will be called whenever a comment capable of containing Natural Docs content is found.
sub MakeParsedTopic #(name,
class,
type,
body,
lineNumber)
Creates a NaturalDocs::Parser::ParsedTopic object for the passed parameters.
sub FormatBody #(commentLines,
startingIndex,
endingIndex,
type)
Converts the section body to NDMarkup.
A markup format used by the parser, both internally and in NaturalDocs::Parser::ParsedTopic objects.
sub AddToCodeBlock #(line,
codeBlockRef,
removedSpacesRef)
Adds a line of text to a code block, handling all the indentation processing required.
sub RichFormatTextBlock #(text)
Applies rich NDMarkup formatting to a chunk of text.
sub TagType #(textBlocks,
index)
Returns whether the tag is a possible opening or closing tag, or neither.
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.