NaturalDocs:: Languages:: PerlNaturalDocs::Languages::Perl |
A subclass to handle the language variations of Perl. Summary | A subclass to handle the language variations of Perl. | | | | Returns the language’s name. | | Returns an arrayref of the extensions of the language’s files. | | Returns an arrayref of the strings that can appear in the language’s shebang string. | | | | | | Perl’s variables start with symbols: $ for scalars, @ for arrays, and % for hashes. | | All functions here assume that the current position is at the beginning of a statement. | | Determines whether the position is at a package declaration statement, and if so, generates a topic for it, skips it, and returns true. | | Determines whether the position is at a package base declaration statement, and if so, calls <NaturalDocs::Parser->OnParent()>. | | Determines whether the position is at a function declaration statement, and if so, generates a topic for it, skips it, and returns true. | | Determines if the position is at a variable declaration statement, and if so, generates a topic for it, skips it, and returns true. | | Determines if the position is at a variable name, and if so, skips it and returns the name. | | Attempts to retrieve a list of strings from the current position. | | | | Advances the position one place through general code. | | Advances the position via GenericSkip() until a specific token is reached and passed. | | Advances the position one place through regexp code. | | | | Advances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group. | | If the current position is on a whitespace or line break token, skip all line breaks and whitespace and return true. | | If the current position is on a comment, skip past it and return true. | | If the current position is on a line comment symbol, skip past it and return true. | | If the current position is on a POD comment symbol, skip past it and return true. | | If the current position is on a string delimiter, skip past the string and return true. | | If the current position is on a regular expression or a quote-like operator, skip past it and return true. | | | | Returns whether the position is after a string (dollar sign) character. |
NameReturns the language’s name. ExtensionsReturns an arrayref of the extensions of the language’s files. ShebangStringsReturns an arrayref of the strings that can appear in the language’s shebang string. ParseFile| sub ParseFile # | ( | sourceFile, | | | topicsList | ) | |
|
Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment(). ParametersReturnsThe array ( autoTopics, scopeRecord ). MakeSortableSymbol| sub MakeSortableSymbol # | ( | name, | | | type | ) | |
|
Perl’s variables start with symbols: $ for scalars, @ for arrays, and % for hashes. This function strips them off for sorting. Statement Parsing FunctionsAll 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->OnParent()>. Supported Syntaxesuse 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 FunctionsGenericSkip| sub GenericSkip # | ( | indexRef, | | | lineNumberRef | ) | |
|
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. |
GenericSkipUntilAfter| sub GenericSkipUntilAfter # | ( | indexRef, | | | lineNumberRef, | | | token | ) | |
|
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 a whitespace or line break token, skip all line breaks and whitespace and return true. 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. |
ReturnsWhether 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.
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.
IsStringedReturns whether the position is after a string (dollar sign) character. Parameters| index | The index of the postition. |
|