NaturalDocs::ConfigFile

A package to manage Natural Docs’ configuration files.

Usage

  • Only one configuration file can be managed with this package at a time.  You must close the file before opening another one.
Summary
NaturalDocs::ConfigFileA package to manage Natural Docs’ configuration files.
FormatAll configuration files are text files.
CFCharsThe characters that can appear in configuration file keywords and user-defined element names: letters, numbers, spaces, dashes, slashes, apostrophes, and periods.
Variables
CONFIG_FILEHANDLEThe file handle used for the configuration file.
fileThe FileName for the current configuration file being parsed.
lineReaderThe LineReader used to read the configuration file.
errorsAn array of errors added by AddError().
lineNumberThe current line number for the configuration file.
hasBraceGroupsWhether the file has brace groups or not.
virtualLinesAn array of virtual lines if a line from the file contained more than one.
Functions
OpenOpens a configuration file for parsing and returns the format VersionInt.
CloseCloses the current configuration file.
GetLineReturns the next line containing content, or an empty array if none.
LineNumberReturns the line number for the line last returned by GetLine().
Error Functions
AddErrorStores an error for the current configuration file.
ErrorCountReturns how many errors the configuration file has.
PrintErrorsAndAnnotateFilePrints the errors to STDERR in the standard GNU format and annotates the configuration file with them.
Misc Functions
HasOnlyCFCharsReturns whether the passed string contains only CFChars.
CFCharNamesReturns a plain-english list of CFChars which can be embedded in a sentence.
ObscureObscures the passed text so that it is not user editable and returns it.
UnobscureRestores text encoded with Obscure() and returns it.

Format

All configuration files are text files.

# [comment]

Comments start with the # character.

Format: [version]

All configuration files must have a format line as its first line containing content.  Whitespace and comments are permitted ahead of it.

[keyword]: [value]

Keywords can only contain CFChars.  Keywords are not case sensitive.  Values can be anything and run until the end of the line or a comment.

[value]

Lines that don’t start with a valid keyword format are considered to be all value.

[line] { [line] } [line]

Files supporting brace groups (specified in Open()) may also have braces that can appear anywhere.  It allows more than one thing to appear per line, which isn’t supported otherwise.  Consequently, values may not have braces.

CFChars

The characters that can appear in configuration file keywords and user-defined element names: letters, numbers, spaces, dashes, slashes, apostrophes, and periods.

Although the list above is exhaustive, it should be noted that you especially can not use colons (messes up keyword: value sequences) commas (messes up item, item, item list sequences) and hashes (messes up comment detection.)

You can search the source code for [CFChars] to find all the instances where this definition is used.

Variables

CONFIG_FILEHANDLE

The file handle used for the configuration file.

file

my $file

The FileName for the current configuration file being parsed.

lineReader

my $lineReader

The LineReader used to read the configuration file.

errors

my @errors

An array of errors added by AddError().  Every odd entry is the line number, and every even entry following is the error message.

lineNumber

my $lineNumber

The current line number for the configuration file.

hasBraceGroups

my $hasBraceGroups

Whether the file has brace groups or not.

virtualLines

my @virtualLines

An array of virtual lines if a line from the file contained more than one.

Files with brace groups may have more than one virtual line per actual file line, such as “Group: A { Group: B”.  When that happens, any extra virtual lines are put into here so they can be returned on the next call.

Functions

Open

sub Open #(file,
hasBraceGroups)

Opens a configuration file for parsing and returns the format VersionInt.

Parameters

fileThe FileName to parse.
hasBraceGroupsWhether the file supports brace groups or not.  If so, lines with braces will be split apart behind the scenes.

Returns

The VersionInt of the file, or undef if the file doesn’t exist.

Close

sub Close

Closes the current configuration file.

GetLine

sub GetLine

Returns the next line containing content, or an empty array if none.

Returns

Returns the array ( keyword, value, comment ), or an empty array if none.  All tabs will be converted to spaces, and all whitespace will be condensed into a single space.

keywordThe keyword part of the line, if any.  Is converted to lowercase and doesn’t include the colon.  If the file supports brace groups, opening and closing braces will be returned as keywords.
valueThe value part of the line, minus any whitespace.  Keeps its original case.
commentThe comment following the line, if any.  This includes the # symbol and a leading space if there was any whitespace, since it may be significant.  Otherwise undef.  Used for lines where the # character needs to be accepted as part of the value.

LineNumber

sub LineNumber

Returns the line number for the line last returned by GetLine().

Error Functions

AddError

sub AddError #(message,
lineNumber)

Stores an error for the current configuration file.  Will be attached to the last line read by GetLine().

Parameters

messageThe error message.
lineNumberThe line number to use.  If not specified, it will use the line number from the last call to GetLine().

ErrorCount

sub ErrorCount

Returns how many errors the configuration file has.

PrintErrorsAndAnnotateFile

sub PrintErrorsAndAnnotateFile

Prints the errors to STDERR in the standard GNU format and annotates the configuration file with them.  It does not end execution.  Close() must be called before this function.

Misc Functions

HasOnlyCFChars

sub HasOnlyCFChars #(string)

Returns whether the passed string contains only CFChars.

CFCharNames

sub CFCharNames

Returns a plain-english list of CFChars which can be embedded in a sentence.  For example, “You can only use [CFCharsList()] in the name.

Obscure

sub Obscure #(text)

Obscures the passed text so that it is not user editable and returns it.  The encoding method is not secure; it is just designed to be fast and to discourage user editing.

Unobscure

sub Unobscure #(text)

Restores text encoded with Obscure() and returns it.

my $file
The FileName for the current configuration file being parsed.
A string representing the absolute, platform-dependent path to a file.
my $lineReader
The LineReader used to read the configuration file.
An object to handle reading text files line by line in a cross platform manner.
my @errors
An array of errors added by AddError().
sub AddError #(message,
lineNumber)
Stores an error for the current configuration file.
my $lineNumber
The current line number for the configuration file.
my $hasBraceGroups
Whether the file has brace groups or not.
my @virtualLines
An array of virtual lines if a line from the file contained more than one.
sub Open #(file,
hasBraceGroups)
Opens a configuration file for parsing and returns the format VersionInt.
A comparable integer representing a version number.
sub Close
Closes the current configuration file.
sub GetLine
Returns the next line containing content, or an empty array if none.
sub LineNumber
Returns the line number for the line last returned by GetLine().
sub ErrorCount
Returns how many errors the configuration file has.
sub PrintErrorsAndAnnotateFile
Prints the errors to STDERR in the standard GNU format and annotates the configuration file with them.
sub HasOnlyCFChars #(string)
Returns whether the passed string contains only CFChars.
The characters that can appear in configuration file keywords and user-defined element names: letters, numbers, spaces, dashes, slashes, apostrophes, and periods.
sub CFCharNames
Returns a plain-english list of CFChars which can be embedded in a sentence.
sub Obscure #(text)
Obscures the passed text so that it is not user editable and returns it.
sub Unobscure #(text)
Restores text encoded with Obscure() and returns it.
Close