Moe status files
================
-.. contents::
- :local:
+.. contents::
+ :local:
-------------------
Status files syntax
-------------------
-The status files hold and transmit status information of a single task (submission).
+A status file records all status information on a single submission.
-A status is an (unordered) dictionary of **key:value** entries and named subtrees.
-Keys of both the entries and subtrees may consist only of letters, numbers, ``-`` and ``_``
-(must match ``[a-zA-Z0-9-_]+``). The keys are case-sensitive.
+It is an (unordered) dictionary of **key:value** entries and named subtrees.
+Keys of both the entries and subtrees may consist only of letters, numbers, ``-`` and ``_``
+(must match ``[a-zA-Z0-9_-]+``). The keys are case-sensitive.
The values are arbitrary byte-strings not containing character ``\0`` (ASCII char. 0).
-Note that this permits almost any encoding that can avoid the character ``\0``, such as UTF-8.
-When processing the values as strings, Moe decodes the strings as UTF-8 (unless stated otherwise).
+Note that this permits almost any encoding that can avoid the character ``\0``, such as UTF-8.
+When processing the values as strings, Moe always uses UTF-8 (unless stated otherwise).
-The format is line oriented (delimited by ``\n``),
+The format is line oriented (delimited by ``\n``),
whitespace characters (`` \t\r``) at the beginning of a line are ignored.
-The file consists of empty lines, comments, entries and subtrees.
+The file consists of empty lines, comments, entries and subtrees.
-Comments start with ``#`` and continue until the end of the line.
+Comments start with ``#`` and continue until the end of the line.
Comments must occur alone on the line.
-Entries are written as a key and a colon. Everything after the colon (incl. whitespace)
+Entries are written as a key and a colon. Everything after the colon (incl. whitespace)
is considered to be part of the value.
Multi-line values continue on following lines, prefixed by a single semicolon.
A subtree consists of a key followed by ``(``, the subtree is closed by ``)`` on a single line.
-Keys of entries and subtrees must be unique in every subtree, including the top-level of a status file.
+Keys of entries and of subtrees must be unique in every subtree, including the top level of the status file.
Status file grammar
^^^^^^^^^^^^^^^^^^^
ELEMENT = WS '\n' | COMMENT | ENTRY | SUBTREE
SUBTREE = WS KEY '(' WS '\n' STATUS ')' WS '\n'
ENTRY = WS KEY WS ':' VALUE '\n' ( WS ':' VALUE '\n' )*
- COMMENT = WS re('#[^\n\0]*\n'
+ COMMENT = WS re('#[^\n\0]*\n'
KEY = re([a-zA-Z0-9-_]+)
VALUE = re([^\n\0]*)
WS = re(['\r\t ']*)
-Every ``ELEMENT`` ends with a newline. ``ENTRY`` is a (possibly multiline) **key:value** pair.
+Every ``ELEMENT`` ends with a newline. ``ENTRY`` is a (possibly multiline) **key:value** pair.
---------------------
Updating status files