t/doc/status.rst

   1 .. _status:
   2
   3 .. highlight:: none
   4
   5 ================
   6 Moe status files
   7 ================
   8
   9 .. contents::
  10   :local:
  11
  12 -------------------
  13 Status files syntax
  14 -------------------
  15
  16 The status files hold and transmit status information of a single task (submission).
  17
  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.
  21
  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).
  25
  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.
  29
  30 Comments start with ``#`` and continue until the end of the line.
  31 Comments must occur alone on the line.
  32
  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.
  36
  37 A subtree consists of a key followed by ``(``, the subtree is closed by ``)`` on a single line.
  38
  39 Keys of entries and subtrees must be unique in every subtree, including the top-level of a status file.
  40
  41 Status file grammar
  42 ^^^^^^^^^^^^^^^^^^^
  43
  44 ::
  45   STATUS = ELEMENT *
  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-_]+)
  51   VALUE = re([^\n\0]*)
  52   WS = re(['\r\t ']*)
  53
  54 Every ``ELEMENT`` ends with a newline. ``ENTRY`` is a (possibly multiline) **key:value** pair.
  55
  56 ---------------------
  57 Updating status files
  58 ---------------------
  59
  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.
  64
  65
  66 -----------------
  67 Module moe.status
  68 -----------------
  69
  70 .. automodule:: moe.status
  71
  72