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::NativeA package that converts comments from Natural Docs’ native format into NaturalDocs::Parser::ParsedTopic objects.
Variables
packageA SymbolString representing the package normal topics will be a part of at the current point in the file.
functionListIgnoredHeadingsAn existence hash of all the headings that prevent the parser from creating function list symbols.
Interface Functions
StartThis will be called whenever a file is about to be parsed.
IsMineExamines the comment and returns whether it is definitely Natural Docs content, i.e.
ParseCommentThis will be called whenever a comment capable of containing Natural Docs content is found.
ParseHeaderLineIf the passed line is a topic header, returns the array ( keyword, title ).
Support Functions
MakeParsedTopicCreates a NaturalDocs::Parser::ParsedTopic object for the passed parameters.
FormatBodyConverts the section body to NDMarkup.
AddToCodeBlockAdds a line of text to a code block, handling all the indentation processing required.
RichFormatTextBlockApplies rich NDMarkup formatting to a chunk of text.
@tempTextBlocks
@textBlocks
$bold
$underline
$underlineHasWhitespace
$index
TagTypeReturns whether the tag is a possible opening or closing tag, or neither.
ClosingTagReturns 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

package

my $package

A SymbolString representing the package normal topics will be a part of at the current point in the file.  This is a package variable because it needs to be reserved 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.

IsMine

sub IsMine #(string[] commentLines,
bool isJavaDoc)

Examines the comment and returns whether it is definitely Natural Docs content, i.e. it is owned by this package.  Note that a comment can fail this function and still be interpreted as a Natural Docs content, for example a JavaDoc-styled comment that doesn’t have header lines but no JavaDoc tags either.

Parameters

commentLinesAn arrayref of the comment lines.  Must have been run through NaturalDocs::Parser->CleanComment().
isJavaDocWhether the comment was JavaDoc-styled.

Returns

Whether the comment is definitely Natural Docs content.

ParseComment

sub ParseComment #(commentLines,
isJavaDoc,
lineNumber,
parsedTopics)

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

Parameters

commentLinesAn arrayref of the comment lines.  Must have been run through NaturalDocs::Parser->CleanComment()The original memory will be changed.
isJavaDocWhether the comment is JavaDoc styled.
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.

ParseHeaderLine

sub ParseHeaderLine #(line)

If the passed line is a topic header, returns the array ( keyword, title ).  Otherwise returns an empty array.

Support Functions

MakeParsedTopic

sub MakeParsedTopic #(type,
title,
package,
body,
lineNumber,
isList)

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

Parameters

typeThe TopicType.  May be undef for headerless topics.
titleThe title of the topic.  May be undef for headerless topics.
packageThe package SymbolString the topic appears in.
bodyThe topic’s body in NDMarkup.
lineNumberThe topic’s line number.
isListWhether the topic is a list.

Returns

The NaturalDocs::Parser::ParsedTopic object.

FormatBody

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

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.  May be undef for headerless comments.
isListWhether it’s a list topic.

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.

@tempTextBlocks

my @tempTextBlocks

@textBlocks

my @textBlocks

$bold

my $bold

$underline

my $underline

$underlineHasWhitespace

my $underlineHasWhitespace

$index

my $index

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.

A class for parsed topics of source files.
my $package
A SymbolString representing the package normal topics will be a part of at the current point in the file.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
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 IsMine #(string[] commentLines,
bool isJavaDoc)
Examines the comment and returns whether it is definitely Natural Docs content, i.e.
sub ParseComment #(commentLines,
isJavaDoc,
lineNumber,
parsedTopics)
This will be called whenever a comment capable of containing Natural Docs content is found.
sub ParseHeaderLine #(line)
If the passed line is a topic header, returns the array ( keyword, title ).
sub MakeParsedTopic #(type,
title,
package,
body,
lineNumber,
isList)
Creates a NaturalDocs::Parser::ParsedTopic object for the passed parameters.
sub FormatBody #(commentLines,
startingIndex,
endingIndex,
type,
isList)
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.
my @tempTextBlocks
my @textBlocks
my $bold
my $underline
my $underlineHasWhitespace
my $index
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.
sub CleanComment #(commentLines)
Removes any extraneous formatting and whitespace from the comment.
A string representing a topic type as defined in Topics.txt.
Close