NaturalDocs::Languages::Perl

NaturalDocs::Languages::Advanced

A subclass to handle the language variations of Perl.

Summary

NaturalDocs::Languages::Perl	A subclass to handle the language variations of Perl.
Language Support
hereDocTerminators	An array of active Here Doc terminators, or an empty array if not active.
Interface Functions
PackageSeparator	Returns the package separator symbol.
EnumValues	Returns the EnumValuesType that describes how the language handles enums.
ParseFile	Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
PreprocessFile	Overridden to support “=begin nd” and similar.
Statement Parsing Functions	All functions here assume that the current position is at the beginning of a statement.
TryToGetPackage	Determines whether the position is at a package declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetBase	Determines whether the position is at a package base declaration statement, and if so, calls NaturalDocs::Parser->OnClassParent().
TryToGetFunction	Determines whether the position is at a function declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariable	Determines if the position is at a variable declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariableName	Determines if the position is at a variable name, and if so, skips it and returns the name.
TryToGetListOfStrings	Attempts to retrieve a list of strings from the current position.
Low Level Parsing Functions
GenericSkip	Advances the position one place through general code.
GenericSkipUntilAfter	Advances the position via GenericSkip() until a specific token is reached and passed.
GenericRegexpSkip	Advances the position one place through regexp code.
GenericRegexpSkipUntilAfter	Advances the position via GenericRegexpSkip() until a specific token is reached and passed.
SkipRestOfStatement	Advances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group.
TryToSkipWhitespace	If the current position is on whitespace it skips them and returns true.
TryToSkipComment	If the current position is on a comment, skip past it and return true.
TryToSkipLineComment	If the current position is on a line comment symbol, skip past it and return true.
TryToSkipPODComment	If the current position is on a POD comment symbol, skip past it and return true.
TryToSkipString	If the current position is on a string delimiter, skip past the string and return true.
TryToSkipHereDocDeclaration	If the current position is on a Here Doc declaration, add its terminators to hereDocTerminators and skip it.
TryToSkipHereDocContent	If the current position is at the beginning of a line and there are entries in hereDocTerminators, skips lines until all the terminators are exhausted or we reach the end of the file.
TryToSkipRegexp	If the current position is on a regular expression or a quote-like operator, skip past it and return true.
Support Functions
IsStringed	Returns whether the position is after a string (dollar sign) character.

Language Support

Supported

Packages
Inheritance via “use base” and “@ISA =”.
Functions
Variables

Not supported yet

Constants

hereDocTerminators

my @hereDocTerminators

An array of active Here Doc terminators, or an empty array if not active. Each entry is an arrayref of tokens. The entries must appear in the order they must appear in the source.

Interface Functions

PackageSeparator

sub PackageSeparator

Returns the package separator symbol.

EnumValues

sub EnumValues

Returns the EnumValuesType that describes how the language handles enums.

ParseFile

sub ParseFile #( sourceFile,
topicsList )

Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().

Parameters

sourceFile	The name of the source file to parse.
topicList	A reference to the list of NaturalDocs::Parser::ParsedTopics being built by the file.

Returns

The array ( autoTopics, scopeRecord ).

autoTopics	An arrayref of automatically generated topics from the file, or undef if none.
scopeRecord	An arrayref of NaturalDocs::Languages::Advanced::ScopeChanges, or undef if none.

PreprocessFile

sub PreprocessFile #( lines )

Overridden to support “=begin nd” and similar.

”=begin [nd|naturaldocs|natural docs|jd|javadoc|java doc]” all translate to “=begin nd”.
”=[nd|naturaldocs|natural docs]” also translate to “=begin nd”.
”=end [nd|naturaldocs|natural docs|jd|javadoc]” all translate to “=end nd”.
”=cut” from a ND block translates into “=end nd”, but the next line will be altered to begin with “(NDPODBREAK)”. This is so if there is POD leading into ND which ends with a cut, the parser can still end the original POD because the end ND line would have been removed. Remember, NaturalDocs::Languages::Advanced->ParseForCommentsAndTokens() removes Natural Docs-worthy comments to save parsing time.
”=pod begin nd” and “=pod end nd” are supported for compatibility with ND 1.32 and earlier, even though the syntax is a mistake.
It also supports the wrong plural forms, so naturaldoc/natural doc/javadocs/java docs will work.

Statement Parsing Functions

All functions here assume that the current position is at the beginning of a statement.

Note for developers: I am well aware that the code in these functions do not check if we’re past the end of the tokens as often as it should. We’re making use of the fact that Perl will always return undef in these cases to keep the code simpler.

TryToGetPackage

sub TryToGetPackage #( indexRef,
lineNumberRef )

Determines whether the position is at a package declaration statement, and if so, generates a topic for it, skips it, and returns true.

TryToGetBase

sub TryToGetBase #( indexRef,
lineNumberRef )

Determines whether the position is at a package base declaration statement, and if so, calls NaturalDocs::Parser->OnClassParent().

Supported Syntaxes

use base [list of strings]
@ISA = [list of strings]
@[package]::ISA = [list of strings]
our @ISA = [list of strings]

TryToGetFunction

sub TryToGetFunction #( indexRef,
lineNumberRef )

Determines whether the position is at a function declaration statement, and if so, generates a topic for it, skips it, and returns true.

TryToGetVariable

sub TryToGetVariable #( indexRef,
lineNumberRef )

Determines if the position is at a variable declaration statement, and if so, generates a topic for it, skips it, and returns true.

Supported Syntaxes

Supports variables declared with “my”, “our”, and “local”.
Supports multiple declarations in one statement, such as “my ($x, $y);”.
Supports types and attributes.

TryToGetVariableName

sub TryToGetVariableName #( indexRef,
lineNumberRef )

Determines if the position is at a variable name, and if so, skips it and returns the name.

TryToGetListOfStrings

sub TryToGetListOfStrings #( indexRef,
lineNumberRef )

Attempts to retrieve a list of strings from the current position. Returns an arrayref of them if any are found, or undef if none. It stops the moment it reaches a non-string, so “string1, variable, string2” will only return string1.

Supported Syntaxes

Supports parenthesis.
Supports all string forms supported by TryToSkipString().
Supports qw() string arrays.

Low Level Parsing Functions

GenericSkip

sub GenericSkip #( indexRef,
lineNumberRef,
noRegExps )

Advances the position one place through general code.

If the position is on a comment or string, it will skip it completely.
If the position is on an opening symbol, it will skip until the past the closing symbol.
If the position is on a regexp or quote-like operator, it will skip it completely.
If the position is on a backslash, it will skip it and the following token.
If the position is on whitespace (including comments), it will skip it completely.
Otherwise it skips one token.

Parameters

indexRef	A reference to the current index.
lineNumberRef	A reference to the current line number.
noRegExps	If set, does not test for regular expressions.

GenericSkipUntilAfter

sub GenericSkipUntilAfter #( indexRef,
lineNumberRef,
token,
noRegExps,
allowStringedClosingParens )

Advances the position via GenericSkip() until a specific token is reached and passed.

GenericRegexpSkip

sub GenericRegexpSkip #( indexRef,
lineNumberRef,
inBrackets )

Advances the position one place through regexp code.

If the position is on an opening symbol, it will skip until the past the closing symbol.
If the position is on a backslash, it will skip it and the following token.
If the position is on whitespace (not including comments), it will skip it completely.
Otherwise it skips one token.

Also differs from GenericSkip() in that the parenthesis in $( and $) do count against the scope, where they wouldn’t normally.

Parameters

indexRef	A reference to the current index.
lineNumberRef	A reference to the current line number.
inBrackets	Whether we’re in brackets or not. If true, we don’t care about matching braces and parenthesis.

GenericRegexpSkipUntilAfter

sub GenericRegexpSkipUntilAfter #( indexRef,
lineNumberRef,
token )

Advances the position via GenericRegexpSkip() until a specific token is reached and passed.

SkipRestOfStatement

sub SkipRestOfStatement #( indexRef,
lineNumberRef )

Advances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group. Of course, either of those appearing inside parenthesis, a nested brace group, etc. don’t count.

TryToSkipWhitespace

sub TryToSkipWhitespace #( indexRef,
lineNumberRef )

If the current position is on whitespace it skips them and returns true. If there are a number of these in a row, it skips them all.

Supported Syntax

Whitespace
Line break
All comment forms supported by TryToSkipComment()
Here Doc content

TryToSkipComment

sub TryToSkipComment #( indexRef,
lineNumberRef )

If the current position is on a comment, skip past it and return true.

TryToSkipLineComment

sub TryToSkipLineComment #( indexRef,
lineNumberRef )

If the current position is on a line comment symbol, skip past it and return true.

TryToSkipPODComment

sub TryToSkipPODComment #( indexRef,
lineNumberRef )

If the current position is on a POD comment symbol, skip past it and return true.

TryToSkipString

sub TryToSkipString #( indexRef,
lineNumberRef,
startContentIndexRef,
endContentIndexRef )

If the current position is on a string delimiter, skip past the string and return true.

Parameters

indexRef	A reference to the index of the position to start at.
lineNumberRef	A reference to the line number of the position.
startContentIndexRef	A reference to the variable in which to store the index of the first content token. May be undef.
endContentIndexRef	A reference to the variable in which to store the index of the end of the content, which is one past the last content token. may be undef.

Returns

Whether the position was at a string. The index, line number, and content index variabls will only be changed if true.

Syntax Support

Supports quotes, apostrophes, backticks, q(), qq(), qx(), and qw().
All symbols are supported for the letter forms.

TryToSkipHereDocDeclaration

sub TryToSkipHereDocDeclaration #( indexRef,
lineNumberRef )

If the current position is on a Here Doc declaration, add its terminators to hereDocTerminators and skip it.

Syntax Support

Supports <<EOF
Supports << “String” with all string forms supported by TryToSkipString().

TryToSkipHereDocContent

sub TryToSkipHereDocContent #( indexRef,
lineNumberRef )

If the current position is at the beginning of a line and there are entries in hereDocTerminators, skips lines until all the terminators are exhausted or we reach the end of the file.

Returns

Whether the position was on Here Doc content.

TryToSkipRegexp

sub TryToSkipRegexp #( indexRef,
lineNumberRef )

If the current position is on a regular expression or a quote-like operator, skip past it and return true.

Syntax Support

Supports //, ??, m//, qr//, s///, tr///, and y///.
All symbols are supported for the letter forms.
?? is not supported because it could cause problems with ?: statements. The generic parser has a good chance of successfully stumbling through a regex, whereas the regex code will almost certainly see the rest of the file as part of it.

Support Functions

IsStringed

sub IsStringed #( index )

Returns whether the position is after a string (dollar sign) character. Returns false if it’s preceded by two dollar signs so “if ($x == $$)” doesn’t skip the closing parenthesis as stringed.

Parameters

index

The index of the postition.