NaturalDocs::Languages::Perl

NaturalDocs::Languages::Perl

A subclass to handle the language variations of Perl.

Summary
NaturalDocs::Languages::PerlA subclass to handle the language variations of Perl.
Language Support
hereDocTerminatorsAn array of active Here Doc terminators, or an empty array if not active.
Interface Functions
PackageSeparatorReturns the package separator symbol.
EnumValuesReturns the EnumValuesType that describes how the language handles enums.
ParseFileParses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
PreprocessFileOverridden to support “=begin nd” and similar.
Statement Parsing FunctionsAll functions here assume that the current position is at the beginning of a statement.
TryToGetPackageDetermines whether the position is at a package declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetBaseDetermines whether the position is at a package base declaration statement, and if so, calls NaturalDocs::Parser->OnClassParent().
TryToGetFunctionDetermines whether the position is at a function declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariableDetermines if the position is at a variable declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariableNameDetermines if the position is at a variable name, and if so, skips it and returns the name.
TryToGetListOfStringsAttempts to retrieve a list of strings from the current position.
Low Level Parsing Functions
GenericSkipAdvances the position one place through general code.
GenericSkipUntilAfterAdvances the position via GenericSkip() until a specific token is reached and passed.
GenericRegexpSkipAdvances the position one place through regexp code.
GenericRegexpSkipUntilAfterAdvances the position via GenericRegexpSkip() until a specific token is reached and passed.
SkipRestOfStatementAdvances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group.
TryToSkipWhitespaceIf the current position is on whitespace it skips them and returns true.
TryToSkipCommentIf the current position is on a comment, skip past it and return true.
TryToSkipLineCommentIf the current position is on a line comment symbol, skip past it and return true.
TryToSkipPODCommentIf the current position is on a POD comment symbol, skip past it and return true.
TryToSkipStringIf the current position is on a string delimiter, skip past the string and return true.
TryToSkipHereDocDeclarationIf the current position is on a Here Doc declaration, add its terminators to hereDocTerminators and skip it.
TryToSkipHereDocContentIf 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.
TryToSkipRegexpIf the current position is on a regular expression or a quote-like operator, skip past it and return true.
Support Functions
IsStringedReturns 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

sourceFileThe name of the source file to parse.
topicListA reference to the list of NaturalDocs::Parser::ParsedTopics being built by the file.

Returns

The array ( autoTopics, scopeRecord ).

autoTopicsAn arrayref of automatically generated topics from the file, or undef if none.
scopeRecordAn 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

indexRefA reference to the current index.
lineNumberRefA reference to the current line number.
noRegExpsIf 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

indexRefA reference to the current index.
lineNumberRefA reference to the current line number.
inBracketsWhether 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

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

indexRefA reference to the index of the position to start at.
lineNumberRefA reference to the line number of the position.
startContentIndexRefA reference to the variable in which to store the index of the first content token.  May be undef.
endContentIndexRefA 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

indexThe index of the postition.
The base class for all languages that have full support in Natural Docs.
my @hereDocTerminators
An array of active Here Doc terminators, or an empty array if not active.
sub PackageSeparator
Returns the package separator symbol.
sub EnumValues
Returns the EnumValuesType that describes how the language handles enums.
How enum values are handled in the language.
sub ParseFile #(sourceFile,
topicsList)
Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
sub OnComment #(string[] commentLines,
int lineNumber,
bool isJavaDoc)
The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
sub PreprocessFile #(lines)
Overridden to support “=begin nd” and similar.
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.
sub TryToGetBase #(indexRef,
lineNumberRef)
Determines whether the position is at a package base declaration statement, and if so, calls NaturalDocs::Parser->OnClassParent().
sub OnClassParent #(class,
parent,
scope,
using,
resolvingFlags)
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.
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.
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.
sub TryToGetVariableName #(indexRef,
lineNumberRef)
Determines if the position is at a variable name, and if so, skips it and returns the name.
sub TryToGetListOfStrings #(indexRef,
lineNumberRef)
Attempts to retrieve a list of strings from the current position.
sub GenericSkip #(indexRef,
lineNumberRef,
noRegExps)
Advances the position one place through general code.
sub GenericSkipUntilAfter #(indexRef,
lineNumberRef,
token,
noRegExps,
allowStringedClosingParens)
Advances the position via GenericSkip() until a specific token is reached and passed.
sub GenericRegexpSkip #(indexRef,
lineNumberRef,
inBrackets)
Advances the position one place through regexp code.
sub GenericRegexpSkipUntilAfter #(indexRef,
lineNumberRef,
token)
Advances the position via GenericRegexpSkip() until a specific token is reached and passed.
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.
sub TryToSkipWhitespace #(indexRef,
lineNumberRef)
If the current position is on whitespace it skips them and returns true.
sub TryToSkipComment #(indexRef,
lineNumberRef)
If the current position is on a comment, skip past it and return true.
sub TryToSkipLineComment #(indexRef,
lineNumberRef)
If the current position is on a line comment symbol, skip past it and return true.
sub TryToSkipPODComment #(indexRef,
lineNumberRef)
If the current position is on a POD comment symbol, skip past it and return true.
sub TryToSkipString #(indexRef,
lineNumberRef,
startContentIndexRef,
endContentIndexRef)
If the current position is on a string delimiter, skip past the string and return true.
sub TryToSkipHereDocDeclaration #(indexRef,
lineNumberRef)
If the current position is on a Here Doc declaration, add its terminators to hereDocTerminators and skip it.
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.
sub TryToSkipRegexp #(indexRef,
lineNumberRef)
If the current position is on a regular expression or a quote-like operator, skip past it and return true.
sub IsStringed #(index)
Returns whether the position is after a string (dollar sign) character.
A class for parsed topics of source files.
A class used to store a scope change.
sub ParseForCommentsAndTokens #(FileName sourceFile,
string[] lineCommentSymbols,
string[] blockCommentSymbols,
string[] javadocLineCommentSymbols,
string[] javadocBlockCommentSymbols)
Loads the passed file, sends all appropriate comments to NaturalDocs::Parser->OnComment(), and breaks the rest into an arrayref of tokens.
Close