A package to manage Natural Docs’ configuration files.
| NaturalDocs:: | A package to manage Natural Docs’ configuration files. |
| Format | All configuration files are text files. |
| CFChars | The characters that can appear in configuration file keywords and user-defined element names: letters, numbers, spaces, dashes, slashes, apostrophes, and periods. |
| Variables | |
| CONFIG_FILEHANDLE | The file handle used for the configuration file. |
| file | The FileName for the current configuration file being parsed. |
| errors | An array of errors added by AddError(). |
| lineNumber | The current line number for the configuration file. |
| hasBraceGroups | Whether the file has brace groups or not. |
| virtualLines | An array of virtual lines if a line from the file contained more than one. |
| Functions | |
| Open | Opens a configuration file for parsing and returns the format VersionInt. |
| Close | Closes the current configuration file. |
| GetLine | Returns the next line containing content, or an empty array if none. |
| LineNumber | Returns the line number for the line last returned by GetLine(). |
| Error Functions | |
| AddError | Stores an error for the current configuration file. |
| ErrorCount | Returns how many errors the configuration file has. |
| PrintErrorsAndAnnotateFile | Prints the errors to STDERR in the standard GNU format and annotates the configuration file with them. |
| Misc Functions | |
| HasOnlyCFChars | Returns whether the passed string contains only CFChars. |
| CFCharNames | Returns a plain-english list of CFChars which can be embedded in a sentence. |
| Obscure | Obscures the passed text so that it is not user editable and returns it. |
| Unobscure | Restores text encoded with Obscure() and returns it. |
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.
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.
my $file
The FileName for the current configuration file being parsed.
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.
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.
sub Open #( file, hasBraceGroups )
Opens a configuration file for parsing and returns the format VersionInt.
| file | The FileName to parse. |
| hasBraceGroups | Whether the file supports brace groups or not. If so, lines with braces will be split apart behind the scenes. |
The VersionInt of the file, or undef if the file doesn’t exist.
sub GetLine
Returns the next line containing content, or an empty array if none.
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.
| keyword | The 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. |
| value | The value part of the line, minus any whitespace. Keeps its original case. |
| comment | The 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. |
sub LineNumber
Returns the line number for the line last returned by GetLine().
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.
sub HasOnlyCFChars #( string )
Returns whether the passed string contains only CFChars.
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.
sub Unobscure #( text )
Restores text encoded with Obscure() and returns it.
The FileName for the current configuration file being parsed.
my $file
An array of errors added by AddError().
my @errors
Stores an error for the current configuration file.
sub AddError #( message, lineNumber )
The current line number for the configuration file.
my $lineNumber
Whether the file has brace groups or not.
my $hasBraceGroups
An array of virtual lines if a line from the file contained more than one.
my @virtualLines
Opens a configuration file for parsing and returns the format VersionInt.
sub Open #( file, hasBraceGroups )
Closes the current configuration file.
sub Close
Returns the next line containing content, or an empty array if none.
sub GetLine
Returns the line number for the line last returned by GetLine().
sub LineNumber
Returns how many errors the configuration file has.
sub ErrorCount
Prints the errors to STDERR in the standard GNU format and annotates the configuration file with them.
sub PrintErrorsAndAnnotateFile
Returns whether the passed string contains only CFChars.
sub HasOnlyCFChars #( string )
Returns a plain-english list of CFChars which can be embedded in a sentence.
sub CFCharNames
Obscures the passed text so that it is not user editable and returns it.
sub Obscure #( text )
Restores text encoded with Obscure() and returns it.
sub Unobscure #( text )