Natural Docs
Version 1.2
Natural Docs
Packages
Objects
Languages
Output Formats
Extensions
Documentation
Indexes
Web Site

NaturalDocs:: Languages:: Base

NaturalDocs::Languages::Base
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.
Implementation
The class is implemented as a blessed arrayref.
SOURCEFILEHANDLE
The handle of the source file currently being parsed.
New
Creates and returns a new object.
Information Functions
Name
Returns the name of the language.
Extensions
Returns all the possible extensions of the language’s files as an arrayref.
ShebangStrings
Returns all the possible strings that can appear in a shebang line (#!)
Parsing Functions
ParseFile
Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
FormatPrototype
Parses a prototype so that it can be formatted nicely in the output.
MakeSortableSymbol
Returns the symbol that should be used for sorting.
Support Functions
StripOpeningSymbol
Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
StripClosingSymbol
Determines if the line contains a symbol, and if so, truncates it just before the symbol.

Implementation

The class is implemented as a blessed arrayref.  There are no members in this base class, however.

SOURCEFILEHANDLE

The handle of the source file currently being parsed.

New

sub New

Creates and returns a new object.

Information Functions

Name

Returns the name of the language.  This must be defined by a subclass.

Extensions

Returns all the possible extensions of the language’s files as an arrayref.  Each one must be in all lowercase.  This function must be defined by a subclass.

ShebangStrings

sub ShebangStrings

Returns all the possible strings that can appear in a shebang line (#!) of the language’s files.  It is returned as an arrayref, or undef if not applicable, and all the strings must be in all lowercase.

The default implementation returns undef.

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 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.

FormatPrototype

sub FormatPrototype #(type,
prototype)

Parses a prototype so that it can be formatted nicely in the output.  By default, it formats function prototypes assuming the parameter list is enclosed in parenthesis and parameters are separated by commas and semicolons.  It leaves all other prototypes alone.

Parameters

typeThe topic type.
prototypeThe text prototype.

Returns

The array ( preParam, opening, params, closing, postParam ).

preParamThe part of the prototype prior to the parameter list.  If there is no parameter list, this is the only part of the array that will be defined.
openThe opening symbol to the parameter list, such as parenthesis.  If there is none but there are parameters, it will be a space.
paramsAn arrayref of parameters, one per entry.  Will be undef if none.
closeThe closing symbol to the parameter list, such as parenthesis.  If there is none but there are parameters, it will be a space.
postParamThe part of the prototype after the parameter list, or undef if none.

MakeSortableSymbol

sub MakeSortableSymbol #(name,
type)

Returns the symbol that should be used for sorting.  For example, in Perl, a scalar variable would be “$var”.  However, we would want to sort on “var” so that all scalar variables don’t get dumped into the symbols category in the indexes.  By default, this function returns the original symbol.

Parameters

nameThe name of the symbol.
typeThe symbol’s type.  One of the <Topic Types>.

Returns

The symbol to sort on.  If the symbol doesn’t need to be altered, just return name.

Support Functions

StripOpeningSymbol

sub StripOpeningSymbol #(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.

StripClosingSymbol

sub StripClosingSymbol #(lineRef,
symbols)

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

Parameters

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

Returns

The array ( symbol, lineRemainder ), or undef if the symbol was not found.

symbolThe symbol that was found.
lineRemainderEverything on the line following the symbol.
Copyright © 2003-2004 Greg Valure.  Generated by Natural Docs.
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.
sub New
Creates and returns a new object.
sub ShebangStrings
Returns all the possible strings that can appear in a shebang line (#!)
sub OnComment #(commentLines,
lineNumber)
The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
sub FormatPrototype #(type,
prototype)
Parses a prototype so that it can be formatted nicely in the output.
sub MakeSortableSymbol #(name,
type)
Returns the symbol that should be used for sorting.
sub StripOpeningSymbol #(lineRef,
symbols)
Determines if the line starts with any of the passed symbols, and if so, replaces it with spaces.
sub StripClosingSymbol #(lineRef,
symbols)
Determines if the line contains a symbol, and if so, truncates it just before the symbol.
A class for parsed topics of source files.
A class used to store a scope change.