NaturalDocs::Languages::Base

Exporter

NaturalDocs::Languages::Advanced

NaturalDocs::Languages::Simple

A base class for all programming language parsers.

Summary

NaturalDocs::Languages::Base	A base class for all programming language parsers.
@EXPORT
EnumValuesType	How enum values are handled in the language.
SOURCEFILEHANDLE	The handle of the source file currently being parsed.
New	Creates and returns a new object.
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	Returns the language’s package separator string.
PackageSeparatorWasSet	Returns whether the language’s package separator string was ever changed from the default.
EnumValues	Returns the EnumValuesType that describes how the language handles enums.
IgnoredPrefixesFor	Returns an arrayref of ignored prefixes for the passed TopicType, or undef if none.
SetIgnoredPrefixesFor	Replaces the arrayref of ignored prefixes for the passed TopicType.
HasIgnoredPrefixes	Returns whether the language has any ignored prefixes at all.
CopyIgnoredPrefixesOf	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().
ParsePrototype	Parses the prototype and returns it as a NaturalDocs::Languages::Prototype object.
ParseParameterLine	Parses a prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
ParsePascalParameterLine	Parses a Pascal-like prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
TypeBeforeParameter	Returns whether the type appears before the parameter in prototypes.
IgnoredPrefixLength	Returns the length of the prefix that should be ignored in the index, or zero if none.
Support Functions
StripOpeningSymbols	Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
StripOpeningJavaDocSymbols	Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
StripOpeningBlockSymbols	Determines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.
StripOpeningJavaDocBlockSymbols	Determines if the line starts with any of the opening symbols in the passed symbol pairs, and if so, replaces it with spaces.
StripClosingSymbol	Determines if the line contains a symbol, and if so, truncates it just before the symbol.
NormalizePrototype	Normalizes a prototype.

@EXPORT

our @EXPORT

EnumValuesType

How enum values are handled in the language.

ENUM_GLOBAL	Values are always global and thus ‘value’.
ENUM_UNDER_TYPE	Values are under the type in the hierarchy, and thus ‘package.enum.value’.
ENUM_UNDER_PARENT	Values 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

name	The 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

sourceFile	The FileName 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 NaturalDocs::Parser::ParsedTopics from the file, or undef if none.
scopeRecord	An 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

type	The TopicType.
prototype	The 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

name	The name of the symbol.
type	The 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

lineRef	A reference to the line to check.
symbols	An 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

lineRef	A reference to the line to check.
symbols	An 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

lineRef	A reference to the line to check.
symbolPairs	An 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

lineRef	A reference to the line to check.
symbolPairs	An 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

lineRef	A reference to the line to check.
symbol	The 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

prototype

The original prototype string.

Returns

The normalized prototype.