X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=t%2Fdoc%2Fstatus.rst;h=873824a7332ebbb95e7de6df608c2c4321ff6435;hb=52fca60abc79162929e0ee815e8d116d7b8c15cd;hp=0953181cf46f9738dc031b134e1e933226e28b81;hpb=3b2c0c783bf7284037f4c5c5ffd6582ee7b1f89c;p=moe.git diff --git a/t/doc/status.rst b/t/doc/status.rst index 0953181..873824a 100644 --- a/t/doc/status.rst +++ b/t/doc/status.rst @@ -6,8 +6,8 @@ Moe status files ================ -.. contents:: - :local: +.. contents:: + :local: ------------------- Status files syntax @@ -16,27 +16,27 @@ Status files syntax The status files hold and transmit status information of a single task (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 ``_`` +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. +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). -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 subtrees must be unique in every subtree, including the top-level of a status file. Status file grammar ^^^^^^^^^^^^^^^^^^^ @@ -47,12 +47,12 @@ 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