16 The status files hold and transmit status information of a single task (submission).
18 A status is an (unordered) dictionary of **key:value** entries and named subtrees.
19 Keys of both the entries and subtrees may consist only of letters, numbers, ``-`` and ``_``
20 (must match ``[a-zA-Z0-9-_]+``). The keys are case-sensitive.
22 The values are arbitrary byte-strings not containing character ``\0`` (ASCII char. 0).
23 Note that this permits almost any encoding that can avoid the character ``\0``, such as UTF-8.
24 When processing the values as strings, Moe decodes the strings as UTF-8 (unless stated otherwise).
26 The format is line oriented (delimited by ``\n``),
27 whitespace characters (`` \t\r``) at the beginning of a line are ignored.
28 The file consists of empty lines, comments, entries and subtrees.
30 Comments start with ``#`` and continue until the end of the line.
31 Comments must occur alone on the line.
33 Entries are written as a key and a colon. Everything after the colon (incl. whitespace)
34 is considered to be part of the value.
35 Multi-line values continue on following lines, prefixed by a single semicolon.
37 A subtree consists of a key followed by ``(``, the subtree is closed by ``)`` on a single line.
39 Keys of entries and subtrees must be unique in every subtree, including the top-level of a status file.
46 ELEMENT = WS '\n' | COMMENT | ENTRY | SUBTREE
47 SUBTREE = WS KEY '(' WS '\n' STATUS ')' WS '\n'
48 ENTRY = WS KEY WS ':' VALUE '\n' ( WS ':' VALUE '\n' )*
49 COMMENT = WS re('#[^\n\0]*\n'
50 KEY = re([a-zA-Z0-9-_]+)
54 Every ``ELEMENT`` ends with a newline. ``ENTRY`` is a (possibly multiline) **key:value** pair.
60 A common operation is to update status file *A* with *B*. This proceeds level-by level starting with the top levels
61 of *A* and *B*. The result is a union of the entries, entries of *B* overwriting the corresponding entries of *A*.
62 Any subtrees with matching names are updated recursively. A subtree of *A* and an entry of *B* of the same name
63 (or vice versa) are not allowed.
70 .. automodule:: moe.status