NaturalDocs::Languages::Base

A base class for all programming language parsers.

Summary
NaturalDocs::Languages::BaseA base class for all programming language parsers.
@EXPORT
EnumValuesTypeHow enum values are handled in the language.
SOURCEFILEHANDLEThe handle of the source file currently being parsed.
NewCreates and returns a new object.
NameReturns the language’s name.
ExtensionsReturns an arrayref of the language’s file extensions, or undef if none.
SetExtensionsReplaces the arrayref of the language’s file extensions.
ShebangStringsReturns an arrayref of the language’s shebang strings, or undef if none.
SetShebangStringsReplaces the arrayref of the language’s shebang strings.
PackageSeparatorReturns the language’s package separator string.
PackageSeparatorWasSetReturns whether the language’s package separator string was ever changed from the default.
EnumValuesReturns the EnumValuesType that describes how the language handles enums.
IgnoredPrefixesForReturns an arrayref of ignored prefixes for the passed TopicType, or undef if none.
SetIgnoredPrefixesForReplaces the arrayref of ignored prefixes for the passed TopicType.
HasIgnoredPrefixesReturns whether the language has any ignored prefixes at all.
CopyIgnoredPrefixesOfCopies all the ignored prefix settings of the passed NaturalDocs::Languages::Base object.
Parsing Functions
ParseFileParses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
ParsePrototypeParses the prototype and returns it as a NaturalDocs::Languages::Prototype object.
ParseParameterLineParses a prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
ParsePascalParameterLineParses a Pascal-like prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
TypeBeforeParameterReturns whether the type appears before the parameter in prototypes.
IgnoredPrefixLengthReturns the length of the prefix that should be ignored in the index, or zero if none.
Support Functions
StripOpeningSymbolsDetermines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
StripOpeningJavaDocSymbolsDetermines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
StripOpeningBlockSymbolsDetermines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.
StripOpeningJavaDocBlockSymbolsDetermines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.
StripClosingSymbolDetermines if the line contains a symbol, and if so, truncates it just before the symbol.
NormalizePrototypeNormalizes a prototype.

@EXPORT

our @EXPORT

EnumValuesType

How enum values are handled in the language.

ENUM_GLOBALValues are always global and thus ‘value’.
ENUM_UNDER_TYPEValues are under the type in the hierarchy, and thus ‘package.enum.value’.
ENUM_UNDER_PARENTValues are under the parent in the hierarchy, putting them on the same level as the enum itself.  Thus ‘package.value’.

SOURCEFILEHANDLE

The handle of the source file currently being parsed.

New

sub New #(name)

Creates and returns a new object.

Parameters

nameThe name of the language.

Name

Returns the language’s name.

Extensions

Returns an arrayref of the language’s file extensions, or undef if none.

SetExtensions

Replaces the arrayref of the language’s file extensions.

ShebangStrings

Returns an arrayref of the language’s shebang strings, or undef if none.

SetShebangStrings

Replaces the arrayref of the language’s shebang strings.

PackageSeparator

sub PackageSeparator

Returns the language’s package separator string.

PackageSeparatorWasSet

sub PackageSeparatorWasSet

Returns whether the language’s package separator string was ever changed from the default.

EnumValues

sub EnumValues

Returns the EnumValuesType that describes how the language handles enums.

IgnoredPrefixesFor

sub IgnoredPrefixesFor #(type)

Returns an arrayref of ignored prefixes for the passed TopicType, or undef if none.  The array is sorted so that the longest prefixes are first.

SetIgnoredPrefixesFor

sub SetIgnoredPrefixesFor #(type,
prefixes)

Replaces the arrayref of ignored prefixes for the passed TopicType.

HasIgnoredPrefixes

sub HasIgnoredPrefixes

Returns whether the language has any ignored prefixes at all.

CopyIgnoredPrefixesOf

sub CopyIgnoredPrefixesOf #(language)

Copies all the ignored prefix settings of the passed NaturalDocs::Languages::Base object.

Parsing Functions

ParseFile

Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().  This must be defined by a subclass.

Parameters

sourceFileThe FileName 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 NaturalDocs::Parser::ParsedTopics from the file, or undef if none.
scopeRecordAn arrayref of NaturalDocs::Languages::Advanced::ScopeChanges, or undef if none.

ParsePrototype

sub ParsePrototype #(type,
prototype)

Parses the prototype and returns it as a NaturalDocs::Languages::Prototype object.

Parameters

typeThe TopicType.
prototypeThe text prototype.

Returns

A NaturalDocs::Languages::Prototype object.

ParseParameterLine

sub ParseParameterLine #(line)

Parses a prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.

This vesion assumes a C++ style line.  If you need a Pascal style line, override this function to forward to ParsePascalParameterLine().

Function(parameter, type parameter, type parameter = value);

ParsePascalParameterLine

sub ParsePascalParameterLine #(line)

Parses a Pascal-like prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.  Pascal lines are as follows:

Function (name: type; name, name: type := value)

Also supports ActionScript lines

Function (name: type, name, name: type = value)

TypeBeforeParameter

sub TypeBeforeParameter

Returns whether the type appears before the parameter in prototypes.

For example, it does in C++

void Function (int a, int b)

but does not in Pascal

function Function (a: int; b, c: int)

IgnoredPrefixLength

sub IgnoredPrefixLength #(name,
type)

Returns the length of the prefix that should be ignored in the index, or zero if none.

Parameters

nameThe name of the symbol.
typeThe symbol’s TopicType.

Returns

The length of the prefix to ignore, or zero if none.

Support Functions

StripOpeningSymbols

sub StripOpeningSymbols #(lineRef,
symbols)

Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.  This only happens if the only thing before it on the line is whitespace.

Parameters

lineRefA reference to the line to check.
symbolsAn arrayref of the symbols to check for.

Returns

If the line starts with any of the passed comment symbols, it will replace it in the line with spaces and return the symbol.  If the line doesn’t, it will leave the line alone and return undef.

StripOpeningJavaDocSymbols

sub StripOpeningJavaDocSymbols #(lineRef,
symbols)

Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.  This only happens if the only thing before it on the line is whitespace and the next character after it is whitespace or the end of the line.

Parameters

lineRefA reference to the line to check.
symbolsAn arrayref of the symbols to check for.

Returns

If the line starts with any of the passed comment symbols, it will replace it in the line with spaces and return the symbol.  If the line doesn’t, it will leave the line alone and return undef.

StripOpeningBlockSymbols

sub StripOpeningBlockSymbols #(lineRef,
symbolPairs)

Determines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.  This only happens if the only thing before it on the line is whitespace.

Parameters

lineRefA reference to the line to check.
symbolPairsAn arrayref of the symbol pairs to check for.  Pairs are specified as two consecutive array entries, with the opening symbol first.

Returns

If the line starts with any of the opening symbols, it will replace it in the line with spaces and return the closing symbol.  If the line doesn’t, it will leave the line alone and return undef.

StripOpeningJavaDocBlockSymbols

sub StripOpeningJavaDocBlockSymbols #(lineRef,
symbolPairs)

Determines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.  This only happens if the only thing before it on the line is whitespace and the next character is whitespace or the end of the line.

Parameters

lineRefA reference to the line to check.
symbolPairsAn arrayref of the symbol pairs to check for.  Pairs are specified as two consecutive array entries, with the opening symbol first.

Returns

If the line starts with any of the opening symbols, it will replace it in the line with spaces and return the closing symbol.  If the line doesn’t, it will leave the line alone and return undef.

StripClosingSymbol

sub StripClosingSymbol #(lineRef,
symbol)

Determines if the line contains a symbol, and if so, truncates it just before the symbol.

Parameters

lineRefA reference to the line to check.
symbolThe symbol to check for.

Returns

The remainder of the line, or undef if the symbol was not found.

NormalizePrototype

sub NormalizePrototype #(prototype)

Normalizes a prototype.  Specifically, condenses spaces, tabs, and line breaks into single spaces and removes leading and trailing ones.

Parameters

prototypeThe original prototype string.

Returns

The normalized prototype.

The base class for all languages that have full support in Natural Docs.
A class containing the characteristics of a particular programming language for basic support within Natural Docs.
our @EXPORT
sub New #(name)
Creates and returns a new object.
sub PackageSeparator
Returns the language’s package separator string.
sub PackageSeparatorWasSet
Returns whether the language’s package separator string was ever changed from the default.
sub EnumValues
Returns the EnumValuesType that describes how the language handles enums.
How enum values are handled in the language.
sub IgnoredPrefixesFor #(type)
Returns an arrayref of ignored prefixes for the passed TopicType, or undef if none.
A string representing a topic type as defined in Topics.txt.
sub SetIgnoredPrefixesFor #(type,
prefixes)
Replaces the arrayref of ignored prefixes for the passed TopicType.
sub HasIgnoredPrefixes
Returns whether the language has any ignored prefixes at all.
sub CopyIgnoredPrefixesOf #(language)
Copies all the ignored prefix settings of the passed NaturalDocs::Languages::Base object.
A base class for all programming language parsers.
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 ParsePrototype #(type,
prototype)
Parses the prototype and returns it as a NaturalDocs::Languages::Prototype object.
A data class for storing parsed prototypes.
sub ParseParameterLine #(line)
Parses a prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
A data class for storing parsed prototype parameters.
sub ParsePascalParameterLine #(line)
Parses a Pascal-like prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
sub TypeBeforeParameter
Returns whether the type appears before the parameter in prototypes.
sub IgnoredPrefixLength #(name,
type)
Returns the length of the prefix that should be ignored in the index, or zero if none.
sub StripOpeningSymbols #(lineRef,
symbols)
Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
sub StripOpeningJavaDocSymbols #(lineRef,
symbols)
Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
sub StripOpeningBlockSymbols #(lineRef,
symbolPairs)
Determines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.
sub StripOpeningJavaDocBlockSymbols #(lineRef,
symbolPairs)
Determines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.
sub StripClosingSymbol #(lineRef,
symbol)
Determines if the line contains a symbol, and if so, truncates it just before the symbol.
sub NormalizePrototype #(prototype)
Normalizes a prototype.
A string representing the absolute, platform-dependent path to a file.
A class for parsed topics of source files.
A class used to store a scope change.
Close