|
|||
|
| Glossary |
| HKeys-CM |
| HKeys-DVR |
| HKeys-SUR |
| HKeys-WIN |
| Mouse use |
| Notations |
The ACS Text Format is an Auran-defined international languages supporting text 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 was historically necessary that an ACS Text file start with a Unicode BOM sequence (Byte Order Mark), which was often initialized by the exporter or importer modules in the process of making an asset. However while that is generally still recommended it has not been strictly required since the 2005 release of TRS2006 and the abandonment of the practice of bundling GMAX with Trainz.
|
Basic File Structure
- In programmer jargon
- A 'key' (or 'keyword') is an 'specific' human and machine readable 'identifier', specifically of an unique or enumerated nature belonging to a set of such legally specifiable identifiers. These keys are the lexiconical identifiers used in translating meanings from human to machine CPU. If the term is not legal, the machine's software has no way of interpreting and giving meaning to the spelled (or misspelled) term.
- A 'value'
- 'unordered' lists are lines of data which can be rearranged without adversely affecting meaning.
- 'processing scope' means within the momentary subprogram, subroutine or handler of such and such a specific case (i.e. some predicted and handled context' so a particular 'process')
ACS Text files contain an unordered list of key-value pairs. In any given processing scope, each key must be unique.
- Technical geek-speach...
- the tricksy phrases here are direct quotes of the N3V Wiki source page linked below at page bottom; the interpretation and definition phrases we hope will make the geek-speak comprehensible and understandable so the lay person can internalize the meaning and make the implications 'mastered' and 'commandable'.
A key-value pair can be declared in Extended Backus—Naur Form (EBNF) (Metasyntax forming a context-free grammar) 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.
- (I've been programming since 1976, and even my eyes glaze over reading and trying to understand that... so we write for you here in the Wikibook!)
Template:Textbox
- In layperson terms
Auran/N3V have set up a system of data structures where there are pairs and values, and some values are complex types which can include other simple and complex types.
These later are called data structures like structs, unions, or arrays in many languages—especially C-language derived computer languages and are generally just lumped together as 'containers' in Trainz. When you see a container containing a container you are dealing with a structure part of which is another structure type, such as arrays (e.g. passenger lists product types) or bogeys (trucks, which specify wheels, X,y,z factors of mount points, type of mounting, etc., but all data which is related to the other factors so 'is grouped together' since it is used together and that's the way we humans think of it best too.)
Permitted Keyname characters
- 'This section refers to the creation of keynames, or tags in Trainz. The average user has nothing to do with such, but a Content Creator, particularly script writer's can, do, and likely will.
- Nonetheless, the prohibitions also extend to filenames, so making a username violating this standard is likely to fail on validation. But go ahead, if you like Faults messages!
A key (key name) 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 config.txt compliant with this 'ACS Text file standard. Implementations must accept all valid characters when parsing an ACS Text file.
- 'a' .. 'z'
- '0' .. '9'
- '-'
- '/'
- '_'
Note these key omissions: '\', ':', ';', '`', '~',, '@', '*', '#', '$', '%', '^', '&', '{', '[', ')', ']'
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 tags and/or 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 (including the newline or CR-LF ASCII EOL sequence). The delimiting value is the enclosing quote marks.
<string-value> ::= <double-quote> { <string-character> } <double-quote> [ <whitespace> ] ;
KUID Values
A KUID value is a single KUID in a kuid 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.