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 A status file records all status information on a single submission.
  17
  18 It 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 always uses 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 of subtrees must be unique in every subtree, including the top level of the status file.
  40
  41 Status file grammar
  42 ^^^^^^^^^^^^^^^^^^^
  43
  44 ::
  45
  46   STATUS = ELEMENT *
  47   ELEMENT = WS '\n' | COMMENT | ENTRY | SUBTREE
  48   SUBTREE = WS KEY '(' WS '\n' STATUS ')' WS '\n'
  49   ENTRY = WS KEY WS ':' VALUE '\n' ( WS ':' VALUE '\n' )*
  50   COMMENT = WS re('#[^\n\0]*\n'
  51   KEY = re([a-zA-Z0-9-_]+)
  52   VALUE = re([^\n\0]*)
  53   WS = re(['\r\t ']*)
  54
  55 Every ``ELEMENT`` ends with a newline. ``ENTRY`` is a (possibly multiline) **key:value** pair.
  56
  57 ---------------------
  58 Updating status files
  59 ---------------------
  60
  61 A common operation is to update status file *A* with *B*. This proceeds level-by level starting with the top levels
  62 of *A* and *B*. The result is a union of the entries, entries of *B* overwriting the corresponding entries of *A*.
  63 Any subtrees with matching names are updated recursively. A subtree of *A* and an entry of *B* of the same name
  64 (or vice versa) are not allowed.
  65
  66
  67 -----------------
  68 Module moe.status
  69 -----------------
  70
  71 .. automodule:: moe.status
  72
  73 .. autoexception:: InvalidStatusFile
  74
  75 .. autoclass:: Status
  76   :members:
  77   :exclude-members: do_read, read_val
  78
  79
  80