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.
| NaturalDocs:: | A package that converts comments from Natural Docs’ native format into NaturalDocs::Parser::ParsedTopic objects. |
| Variables | |
| package | A SymbolString representing the package normal topics will be a part of 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. |
| IsMine | Examines the comment and returns whether it is definitely Natural Docs content, i.e. |
| ParseComment | This will be called whenever a comment capable of containing Natural Docs content is found. |
| ParseHeaderLine | If the passed line is a topic header, returns the array ( keyword, title ). |
| 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. |
| @tempTextBlocks | |
| @textBlocks | |
| $bold | |
| $underline | |
| $underlineHasWhitespace | |
| $index | |
| 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. |
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.
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.
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.
| commentLines | An arrayref of the comment lines. Must have been run through NaturalDocs::Parser->CleanComment(). |
| isJavaDoc | Whether the comment was JavaDoc-styled. |
Whether the comment is definitely Natural Docs content.
sub ParseComment #( commentLines, isJavaDoc, lineNumber, parsedTopics )
This will be called whenever a comment capable of containing Natural Docs content is found.
| commentLines | An arrayref of the comment lines. Must have been run through NaturalDocs::Parser->CleanComment(). The original memory will be changed. |
| isJavaDoc | Whether the comment is JavaDoc styled. |
| lineNumber | The line number of the first of the comment lines. |
| parsedTopics | A reference to the array where any new NaturalDocs::Parser::ParsedTopics should be placed. |
The number of parsed topics added to the array, or zero if none.
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.
| type | The TopicType. May be undef for headerless topics. |
| title | The title of the topic. May be undef for headerless topics. |
| package | The package SymbolString the topic appears in. |
| body | The topic’s body in NDMarkup. |
| lineNumber | The topic’s line number. |
| isList | Whether the topic is a list. |
The NaturalDocs::Parser::ParsedTopic object.
sub FormatBody #( commentLines, startingIndex, endingIndex, type, isList )
Converts the section body to NDMarkup.
| commentLines | The arrayref of comment lines. |
| startingIndex | The starting index of the body to format. |
| endingIndex | The ending index of the body to format, not inclusive. |
| type | The type of the section. May be undef for headerless comments. |
| isList | Whether it’s a list topic. |
The body formatted in NDMarkup.
sub AddToCodeBlock #( line, codeBlockRef, removedSpacesRef )
Adds a line of text to a code block, handling all the indentation processing required.
| line | The line of text to add. |
| codeBlockRef | A reference to the code block to add it to. |
| removedSpacesRef | A 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. |
sub RichFormatTextBlock #( text )
Applies rich NDMarkup formatting to a chunk of text. This includes both amp chars, formatting tags, and link tags.
| text | The block of text to format. |
The formatted text block.
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().
| textBlocks | A reference to an array of text blocks. |
| index | The index of the tag. |
POSSIBLE_OPENING_TAG, POSSIBLE_CLOSING_TAG, or NOT_A_TAG.
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.
| 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. |
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 SymbolString representing the package normal topics will be a part of at the current point in the file.
my $package
An existence hash of all the headings that prevent the parser from creating function list symbols.
my %functionListIgnoredHeadings
This will be called whenever a file is about to be parsed.
sub Start
Examines the comment and returns whether it is definitely Natural Docs content, i.e.
sub IsMine #( string[] commentLines, bool isJavaDoc )
This will be called whenever a comment capable of containing Natural Docs content is found.
sub ParseComment #( commentLines, isJavaDoc, lineNumber, parsedTopics )
If the passed line is a topic header, returns the array ( keyword, title ).
sub ParseHeaderLine #( line )
Creates a NaturalDocs::Parser::ParsedTopic object for the passed parameters.
sub MakeParsedTopic #( type, title, package, body, lineNumber, isList )
Converts the section body to NDMarkup.
sub FormatBody #( commentLines, startingIndex, endingIndex, type, isList )
Adds a line of text to a code block, handling all the indentation processing required.
sub AddToCodeBlock #( line, codeBlockRef, removedSpacesRef )
Applies rich NDMarkup formatting to a chunk of text.
sub RichFormatTextBlock #( text )
my @tempTextBlocks
my @textBlocks
my $bold
my $underline
my $underlineHasWhitespace
my $index
Returns whether the tag is a possible opening or closing tag, or neither.
sub TagType #( textBlocks, index )
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 ClosingTag #( textBlocks, index, hasWhitespace )
Removes any extraneous formatting and whitespace from the comment.
sub CleanComment #( commentLines )