ACS Text Format - Revision history

Retro00064: /* Format Violations */ added Category:File formats.

2011-09-05T02:15:33Z

Format Violations: added Category:File formats.

← Older revision		Revision as of 02:15, 5 September 2011
Line 74:		Line 74:

	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.		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.

			[[Category:File formats]]

Windwalkr at 13:32, 4 March 2010

2010-03-04T13:32:42Z

← Older revision		Revision as of 13:32, 4 March 2010
Line 1:		Line 1:
	The [[ACS Text Format]] is an Auran-defined format used for storing [[Config.txt file]]s and other generic key/value data. At the simplest level, an ACS Text file is a standard text file encoded in [http://en.wikipedia.org/wiki/UTF-8 UTF-8]. It is typically recommended that an ACS Text file start with a Unicode BOM sequence, however that is not strictly required.		The [[ACS Text Format]] is an Auran-defined format used for storing [[Config.txt file]]s and other generic key/value data. At the simplest level, an ACS Text file is a standard text file encoded in [http://en.wikipedia.org/wiki/UTF-8 UTF-8]. It is typically recommended that an ACS Text file start with a [http://en.wikipedia.org/wiki/Byte_order_mark Unicode BOM sequence], however that is not strictly required.

	=Basic File Structure=		=Basic File Structure=

Windwalkr at 13:31, 4 March 2010

2010-03-04T13:31:50Z

← Older revision		Revision as of 13:31, 4 March 2010
Line 69:		Line 69:
	=Key Ordering=		=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.		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=		=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.		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.

Windwalkr: New page: 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 e...

2010-03-04T13:31:02Z

New page: 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 e...

New page

The [[ACS Text Format]] is an Auran-defined format used for storing [[Config.txt file]]s and other generic key/value data. At the simplest level, an ACS Text file is a standard text file encoded in [http://en.wikipedia.org/wiki/UTF-8 UTF-8]. It is typically recommended that an ACS Text file start with a Unicode BOM sequence, however that is not strictly required.

=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 [http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form 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 [[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.

=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.