NaturalDocs::Languages::ActionScript

NaturalDocs::Languages::Advanced

A subclass to handle the language variations of Flash ActionScript.

Summary

NaturalDocs::Languages::ActionScript	A subclass to handle the language variations of Flash ActionScript.
Constants and Types
XML Tag Type
Package Variables
classModifiers	An existence hash of all the acceptable class modifiers.
memberModifiers	An existence hash of all the acceptable class member modifiers.
declarationEnders	An existence hash of all the tokens that can end a declaration.
isEscaped	Whether the current file being parsed uses escapement.
Interface Functions
PackageSeparator	Returns the package separator symbol.
EnumValues	Returns the EnumValuesType that describes how the language handles enums.
ParseParameterLine	Parses a prototype parameter line and returns it as a NaturalDocs::Languages::Prototype::Parameter object.
TypeBeforeParameter	Returns whether the type appears before the parameter in prototypes.
PreprocessFile	If the file is escaped, strips out all unescaped code.
ParseFile	Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
Statement Parsing Functions	All functions here assume that the current position is at the beginning of a statement.
TryToGetIdentifier	Determines whether the position is at an identifier, and if so, skips it and returns the complete identifier as a string.
TryToGetImport	Determines whether the position is at a import statement, and if so, adds it as a Using statement to the current scope, skips it, and returns true.
TryToGetClass	Determines whether the position is at a class declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetFunction	Determines if the position is on a function declaration, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariable	Determines if the position is on a variable declaration statement, and if so, generates a topic for each variable, skips the statement, and returns true.
Low Level Parsing Functions
GenericSkip	Advances the position one place through general code.
GenericSkipUntilAfter	Advances the position via GenericSkip() until a specific token is reached and passed.
IndiscriminateSkipUntilAfterSequence	Advances the position indiscriminately until a specific token sequence is reached and passed.
SkipToNextStatement	Advances the position via GenericSkip() until the next statement, which is defined as anything in declarationEnders not appearing in brackets or strings.
TryToSkipRegExp	If the current position is on a regular expression, skip past it and return true.
TryToSkipXML	If the current position is on an XML literal, skip past it and return true.
TryToSkipIrregularXML	If the current position is on an irregular XML tag, skip past it and return true.
GetAndSkipXMLTag	Processes the XML tag at the current position, moves beyond it, and returns information about it.
SkipToNextXMLTag	Skips to the next normal XML tag.
TryToSkipXMLWhitespace	If the current position is on XML whitespace, skip past it and return true.
TryToSkipString	If the current position is on a string delimiter, skip past the string and return true.
TryToSkipWhitespace	If the current position is on a whitespace token, a line break token, or a comment, it skips them and returns true.
TryToSkipComment	If the current position is on a comment, skip past it and return true.
TryToSkipLineComment	If the current position is on a line comment symbol, skip past it and return true.
TryToSkipMultilineComment	If the current position is on an opening comment symbol, skip past it and return true.

Constants and Types

XML Tag Type

XML_OPENING_TAG	The tag is an opening one, such as <tag>.
XML_CLOSING_TAG	The tag is a closing one, such as </tag>.
XML_SELF_CONTAINED_TAG	The tag is self contained, such as <tag />.

Package Variables

classModifiers

my %classModifiers

An existence hash of all the acceptable class modifiers. The keys are in all lowercase.

memberModifiers

my %memberModifiers

An existence hash of all the acceptable class member modifiers. The keys are in all lowercase.

declarationEnders

my %declarationEnders

An existence hash of all the tokens that can end a declaration. This is important because statements don’t require a semicolon to end. The keys are in all lowercase.

isEscaped

my $isEscaped

Whether the current file being parsed uses escapement.

Interface Functions

PackageSeparator

sub PackageSeparator

Returns the package separator symbol.

EnumValues

sub EnumValues

Returns the EnumValuesType that describes how the language handles enums.

ParseParameterLine

sub ParseParameterLine #( line )

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

TypeBeforeParameter

sub TypeBeforeParameter

Returns whether the type appears before the parameter in prototypes.

PreprocessFile

sub PreprocessFile

If the file is escaped, strips out all unescaped code. Will translate any unescaped comments into comments surrounded by “\x1C\x1D\x1E\x1F” and “\x1F\x1E\x1D” characters, so chosen because they are the same character lengths as  and will not appear in normal code.

ParseFile

sub ParseFile #( sourceFile,
topicsList )

Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().

Parameters

sourceFile	The FileName 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 topics from the file, or undef if none.
scopeRecord	An arrayref of NaturalDocs::Languages::Advanced::ScopeChanges, or undef if none.

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.

TryToGetIdentifier

sub TryToGetIdentifier #( indexRef,
lineNumberRef,
allowStar )

Determines whether the position is at an identifier, and if so, skips it and returns the complete identifier as a string. Returns undef otherwise.

Parameters

indexRef	A reference to the current token index.
lineNumberRef	A reference to the current line number.
allowStar	If set, allows the last identifier to be a star.

TryToGetImport

sub TryToGetImport #( indexRef,
lineNumberRef )

Determines whether the position is at a import statement, and if so, adds it as a Using statement to the current scope, skips it, and returns true.

TryToGetClass

sub TryToGetClass #( indexRef,
lineNumberRef )

Determines whether the position is at a class declaration statement, and if so, generates a topic for it, skips it, and returns true.

Supported Syntaxes

Classes
Interfaces
Classes and interfaces with _global

TryToGetFunction

sub TryToGetFunction #( indexRef,
lineNumberRef )

Determines if the position is on a function declaration, and if so, generates a topic for it, skips it, and returns true.

Supported Syntaxes

Functions
Constructors
Properties
Functions with _global
Functions with namespaces

TryToGetVariable

sub TryToGetVariable #( indexRef,
lineNumberRef )

Determines if the position is on a variable declaration statement, and if so, generates a topic for each variable, skips the statement, and returns true.

Supported Syntaxes

Variables
Variables with _global
Variables with type * (untyped)
Constants
Variables and constants with namespaces

Low Level Parsing Functions

GenericSkip

sub GenericSkip #( indexRef,
lineNumberRef )

Advances the position one place through general code.

If the position is on a 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 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.

IndiscriminateSkipUntilAfterSequence

sub IndiscriminateSkipUntilAfterSequence #( indexRef,
lineNumberRef,
token,
token,
... )

Advances the position indiscriminately until a specific token sequence is reached and passed.

SkipToNextStatement

sub SkipToNextStatement #( indexRef,
lineNumberRef )

Advances the position via GenericSkip() until the next statement, which is defined as anything in declarationEnders not appearing in brackets or strings. It will always advance at least one token.

TryToSkipRegExp

sub TryToSkipRegExp #( indexRef,
lineNumberRef )

If the current position is on a regular expression, skip past it and return true.

TryToSkipXML

sub TryToSkipXML #( indexRef,
lineNumberRef )

If the current position is on an XML literal, skip past it and return true.

TryToSkipIrregularXML

sub TryToSkipIrregularXML #( indexRef,
lineNumberRef )

If the current position is on an irregular XML tag, skip past it and return true. Irregular XML tags are defined as

CDATA	<![CDATA[ ... ]]>
Comments	<!-- ... -->
PI	<? ... ?>

GetAndSkipXMLTag

sub GetAndSkipXMLTag #( indexRef,
lineNumberRef )

Processes the XML tag at the current position, moves beyond it, and returns information about it. Assumes the position is on the opening angle bracket of the tag and the tag is a normal XML tag, not one of the ones handled by TryToSkipIrregularXML().

Parameters

indexRef	A reference to the index of the position of the opening angle bracket.
lineNumberRef	A reference to the line number of the position of the opening angle bracket.

Returns

The array ( tagType, name ).

tagType	One of the XML Tag Type constants.
identifier	The identifier of the tag. If it’s an empty tag (<> or </>), this will be “(anonymous)”.

SkipToNextXMLTag

sub SkipToNextXMLTag #( indexRef,
lineNumberRef )

Skips to the next normal XML tag. It will not stop at elements handled by TryToSkipIrregularXML(). Note that if the position is already at an XML tag, it will not move.

TryToSkipXMLWhitespace

sub TryToSkipXMLWhitespace #( indexRef,
lineNumberRef )

If the current position is on XML whitespace, skip past it and return true.

TryToSkipString

sub TryToSkipString #( indexRef,
lineNumberRef )

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.

Returns

Whether the position was at a string.

Syntax Support

Supports quotes and apostrophes.

TryToSkipWhitespace

sub TryToSkipWhitespace #( indexRef,
lineNumberRef )

If the current position is on a whitespace token, a line break token, or a comment, it skips them and returns true. If there are a number of these in a row, it skips them all.

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.

TryToSkipMultilineComment

sub TryToSkipMultilineComment #( indexRef,
lineNumberRef )

If the current position is on an opening comment symbol, skip past it and return true.