NaturalDocs::Languages

A package to manage all the programming languages Natural Docs supports.

Usage and Dependencies

Summary
NaturalDocs::LanguagesA package to manage all the programming languages Natural Docs supports.
Variables
FH_LANGUAGESThe file handle used for writing to Languages.txt.
languagesA hash of all the defined languages.
extensionsA hash of all the defined languages’ extensions.
shebangStringsA hash of all the defined languages’ strings to search for in the shebang (#!)
shebangFilesA hash of all the defined languages for files where it needs to be found via shebang strings.
mainLanguageNamesAn array of the language names that are defined in the main Languages.txt.
Files
Languages.txtThe configuration file that defines or overrides the language definitions for Natural Docs.
File Functions
LoadLoads both the master and the project version of Languages.txt.
LoadFileLoads a particular version of Languages.txt.
ProcessPropertiesProcesses an array of language properties from Languages.txt.
SaveSaves the main and user versions of Languages.txt.
SaveFileSaves a particular version of Topics.txt.
Functions
LanguageOfReturns the language of the passed source file.
OnMostUsedLanguageKnownCalled when the most used language is known.

Variables

FH_LANGUAGES

The file handle used for writing to Languages.txt.

languages

my %languages

A hash of all the defined languages.  The keys are the all-lowercase language names, and the values are NaturalDocs::Languages::Base-derived objects.

extensions

my %extensions

A hash of all the defined languages’ extensions.  The keys are the all-lowercase extensions, and the values are the all-lowercase names of the languages that defined them.

shebangStrings

my %shebangStrings

A hash of all the defined languages’ strings to search for in the shebang (#!) line.  The keys are the all-lowercase strings, and the values are the all-lowercase names of the languages that defined them.

shebangFiles

my %shebangFiles

A hash of all the defined languages for files where it needs to be found via shebang strings.  The keys are the file names, and the values are language names, or undef if the file isn’t supported.  These values should be filled in the first time each file is parsed for a shebang string so that it doesn’t have to be done multiple times.

mainLanguageNames

my @mainLanguageNames

An array of the language names that are defined in the main Languages.txt.

Files

Languages.txt

The configuration file that defines or overrides the language definitions for Natural Docs.  One version sits in Natural Docs’ configuration directory, and another can be in a project directory to add to or override them.

# [comments]

Everything after a # symbol is ignored.  However, for this particular file, comments can only appear on their own lines.  They cannot appear after content on the same line.

Format: [version]

Specifies the file format version of the file.

Sections

Ignore[d] Extension[s]: [extension] [extension] ...

Causes the listed file extensions to be ignored, even if they were previously defined to be part of a language.  The list is space-separated.  ex.  “Ignore Extensions: cvs txt”

Language: [name]

Creates a new language.  Everything underneath applies to this language until the next one.  Names can use any characters.

The languages “Text File” and “Shebang Script” have special meanings.  Text files are considered all comment and don’t have comment symbols.  Shebang scripts have their language determined by the shebang string and automatically include files with no extension in addition to the extensions defined.

If “Text File” doesn’t define ignored prefixes, a package separator, or enum value behavior, those settings will be copied from the language with the most files in the source tree.

Alter Language: [name]

Alters an existing language.  Everything underneath it overrides the previous settings until the next one.  Note that if a property has an [Add/Replace] form and that property has already been defined, you have to specify whether you’re adding to or replacing the defined list.

Language Properties

Extension[s]: [extension] [extension] ...
[Add/Replace] Extension[s]: ...

Defines file extensions for the language’s source files.  The list is space-separated.  ex.  “Extensions: c cpp”.  You can use extensions that were previously used by another language to redefine them.

Shebang String[s]: [string] [string] ...
[Add/Replace] Shebang String[s]: ...

Defines a list of strings that can appear in the shebang (#!) line to designate that it’s part of this language.  They can appear anywhere in the line, so “php” will work for “#!/user/bin/php4”.  You can use strings that were previously used by another language to redefine them.

Ignore[d] Prefix[es] in Index: [prefix] [prefix] ...
Ignore[d] [Topic Type] Prefix[es] in Index: [prefix] [prefix] ...
[Add/Replace] Ignore[d] Prefix[es] in Index: ...
[Add/Replace] Ignore[d] [Topic Type] Prefix[es] in Index: ...

Specifies prefixes that should be ignored when sorting symbols for an index.  Can be specified in general or for a specific TopicType.  The prefixes will still appear, the symbols will just be sorted as if they’re not there.  For example, specifying “ADO_” for functions will mean that “ADO_DoSomething” will appear under D instead of A.

Basic Language Support Properties

These attributes are only available for languages with basic language support.

Line Comment[s]: [symbol] [symbol] ...

Defines a space-separated list of symbols that are used for line comments, if any.  ex.  “Line Comment: //”.

Block Comment[s]: [opening symbol] [closing symbol] [opening symbol] [closing symbol] ...

Defines a space-separated list of symbol pairs that are used for block comments, if any.  ex.  “Block Comment: /* */”.

Package Separator: [symbol]

Defines the default package separator symbol, such as . or ::.  This is for presentation only and will not affect how Natural Docs links are parsed.  The default is a dot.

[Topic Type] Prototype Ender[s]: [symbol] [symbol] ...

When defined, Natural Docs will attempt to collect prototypes from the code following the specified TopicType.  It grabs code until the first ender symbol or the next Natural Docs comment, and if it contains the topic name, it serves as its prototype.  Use \n to specify a line break.  ex.  “Function Prototype Enders: { ;”, “Variable Prototype Enders: = ;”.

Line Extender: [symbol]

Defines the symbol that allows a prototype to span multiple lines if normally a line break would end it.

Enum Values: [global|under type|under parent]

Defines how enum values are referenced.  The default is global.

globalValues are always global, referenced as ‘value’.
under typeValues are under the enum type, referenced as ‘package.enum.value’.
under parentValues are under the enum’s parent, referenced as ‘package.value’.
Perl Package: [perl package]

Specifies the Perl package used to fine-tune the language behavior in ways too complex to do in this file.

Full Language Support Properties

These attributes are only available for languages with full language support.

Full Language Support: [perl package]

Specifies the Perl package that has the parsing routines necessary for full language support.

Revisions

1.32

  • Package Separator is now a basic language support only property.
  • Added Enum Values setting.

1.3

  • The file was introduced.

File Functions

Load

sub Load

Loads both the master and the project version of Languages.txt.

LoadFile

sub LoadFile #(isMain,
tempExtensions,
tempShebangStrings)

Loads a particular version of Languages.txt.

Parameters

isMainWhether the file is the main file or not.
tempExtensionsA hashref where the keys are all-lowercase extensions, and the values are arrayrefs of the all-lowercase names of the languages that defined them, earliest first.  It will be changed by this function.
tempShebangStringsA hashref where the keys are all-lowercase shebang strings, and the values are arrayrefs of the all-lowercase names of the languages that defined them, earliest first.  It will be changed by this function.

ProcessProperties

sub ProcessProperties #(properties,
version,
tempExtensions,
tempShebangStrings)

Processes an array of language properties from Languages.txt.

Parameters

propertiesAn arrayref of properties where each entry is the three consecutive values ( lineNumber, keyword, value ).  It must start with the Language or Alter Language property.
versionThe VersionInt of the file.
tempExtensionsA hashref where the keys are all-lowercase extensions, and the values are arrayrefs of the all-lowercase names of the languages that defined them, earliest first.  It will be changed by this function.
tempShebangStringsA hashref where the keys are all-lowercase shebang strings, and the values are arrayrefs of the all-lowercase names of the languages that defined them, earliest first.  It will be changed by this function.

Save

sub Save

Saves the main and user versions of Languages.txt.

SaveFile

sub SaveFile #(isMain)

Saves a particular version of Topics.txt.

Parameters

isMainWhether the file is the main file or not.

Functions

LanguageOf

sub LanguageOf #(sourceFile)

Returns the language of the passed source file.

Parameters

sourceFileThe source FileName to get the language of.

Returns

A NaturalDocs::Languages::Base-derived object for the passed file, or undef if the file is not a recognized language.

OnMostUsedLanguageKnown

sub OnMostUsedLanguageKnown

Called when the most used language is known.

The configuration file that defines or overrides the language definitions for Natural Docs.
my %languages
A hash of all the defined languages.
my %extensions
A hash of all the defined languages’ extensions.
my %shebangStrings
A hash of all the defined languages’ strings to search for in the shebang (#!)
my %shebangFiles
A hash of all the defined languages for files where it needs to be found via shebang strings.
my @mainLanguageNames
An array of the language names that are defined in the main Languages.txt.
sub Load
Loads both the master and the project version of Languages.txt.
sub LoadFile #(isMain,
tempExtensions,
tempShebangStrings)
Loads a particular version of Languages.txt.
sub ProcessProperties #(properties,
version,
tempExtensions,
tempShebangStrings)
Processes an array of language properties from Languages.txt.
sub Save
Saves the main and user versions of Languages.txt.
sub SaveFile #(isMain)
Saves a particular version of Topics.txt.
The configuration file that defines or overrides the topic definitions for Natural Docs.
sub LanguageOf #(sourceFile)
Returns the language of the passed source file.
sub OnMostUsedLanguageKnown
Called when the most used language is known.
A package to handle the command line and various other program settings.
A base class for all programming language parsers.
A string representing a topic type as defined in Topics.txt.
A comparable integer representing a version number.
A string representing the absolute, platform-dependent path to a file.
Close