ACS Text Format
The ACS Text Format is an Auran-defined format used for storing Config.txt files and other generic key/value data. At the simplest level, an ACS Text file is a standard text file encoded in UTF-8. It is typically recommended that an ACS Text file start with a Unicode BOM sequence, however that is not strictly required.
Contents |
Basic File Structure
ACS Text files contain an unordered list of key-value pairs. In any given scope, each key must be unique. A key-value pair can be declared in EBNF as follows:
<singlespace> ::= ' ' | <TAB> ;
<whitespace> ::= <singlespace> | { <singlespace> } ;
<line-start> ::= { <whitespace> | <EOL> } ;
<key-value-pair> ::= <line-start> <key> <whitespace> <value> <EOL> ;
<acs-text-file> ::= [ <unicode-bom> ] { <key-value-pair> } <line-start> ;
It is important to note that the <value> may span multiple lines in some cases.
Keys
A key is a sequence of unicode characters with a maximum size of 511 bytes. Control characters (ASCII 0..31) and the space character (ASCII 32) are not permitted. Uppercase ASCII characters (ASCII 64..89) are not permitted. The open-brace character (ASCII 123) is not permitted as the first character of a key. The close-brace character (ASCII 125) is not permitted.
For future compatibility, it is strongly recommended that implementations limit keys to the following set of characters when constructing an ACS Text file. Implementations 'must accept all valid characters when parsing an ACS Text file.
- 'a' .. 'z'
- '0' .. '9'
- '-'
- '/'
- '_'
Values
Each value may include zero or more UTF-8 characters. Several types of value are available with unique encodings. Value types are automatically identified based on the contents of the value, no type information is written into the file.
<value> ::= <null-value> | <numeric-value> | <numeric-array-value> | <string-value> | <kuid-value> | <container-value> ;
Null Value
A null value is literally a zero-length value.
<null-value> ::= [ <whitespace> ] ;
Numeric Values
A numeric value is an integer or decimal representation.
<number> ::= [ "-" ] <digit> { <digit> } [ "." <digit> { <digit> } ] ;
<numeric-value> ::= <number> [ <whitespace> ] ;
Numeric Array Values
A numeric array value is a sequence of multiple numbers, separated by commas.
<array-separator> ::= [ <whitespace> ] "," [ <whitespace> ] ;
<numeric-array-value> ::= <number> <array-separator> { <number> <array-separator> } <number> [ <whitespace> ] ;
String Values
A string value is a sequence of zero or more UTF-8 characters, surrounded by quotation marks (ASCII 34.) The use of the double quote character (ASCII 34) and the backslash character (ASCII 92) are proscribed. Strings may continue over multiple lines and may include whitespace.
<string-value> ::= <double-quote> { <string-character> } <double-quote> [ <whitespace> ] ;
KUID Values
A KUID value is a single KUID in a valid format.
<kuid-value> ::= <KUID> [ <whitespace> ] ;
Container Values
A container value nests additional key-value pairs over multiple lines.
<container-value> ::= [ <EOL> ] "{" <EOL> { <key-value-pair> } <line-start> "}" ;
Key Ordering
The ACS Text Format is technically an unordered key-value soup, however all existing implementations are order-preserving for trivial (read, write) operations. It is recommended that future implementations maintain this convention.
Format Violations
The effect of a format violation detected during parsing is undefined. An implementation which follows this specification must not generate a file which violates any aspect of this specification.
