5 Formats

Monotone uses three formats to output or to accept input of data (mostly structured), basic_io, stdio, and packet. basic_io is often used to represent data or for configuration, while stdio is used for communication with automate stdio.

The stdio format is not described here. For information on it, see mtn automate stdio.

The packet format is not described here; see Packet I/O. For examples, see mtn automate packet_for_fdelta, mtn automate packet_for_fdata.

5.1 basic_io Format

basic_io is a very simple format, yet expressive, and can be described with the following ABNF (see RFC 2234) specification:

basic_io = *( item )

    item = *sp symbol *sp *( string / hexid ) *sp
           ; a symbol followed by zero or more strings and/or hexes.

  symbol = 1*( lcalpha / "_" )
           ; One or more letters or underscores.
  string = DQUOTE *( charnqnb / "\" "\" / "\" DQUOTE ) DQUOTE
           ; A series of any character, enclosed with double quotes
           ; To include a double quote or a backslash in the string,
           ; escape it with a backslash.
   hexid = "[" 40HEXDIG "]"
           ; 40 hexadecimal characters enclosed in brackets.
           ; Note: the amount might change as we move away from sha1.

      sp = ( WSP CR LF )
charnqnb = %x01-21 / %x23-5B / %x5D-FF
           ; All characters except NUL (%x00) , " (%x22) and \ (%x5C).
 lcalpha = %x61-7A
           ; Lower case a-z.

In essence, it’s a stream of items, where each item is a symbol followed by zero or more strings and hexes.

There is an idea of stanzas, which is a group of items that logically belongs together. However, stanzas aren’t defined in the basic_io syntax, and are instead defined in terms of order and sequence for what symbols may be part of the stream, how they may appear, and how many and what arguments should follow them. This is defined by each command or program using this format.

For example, revisions have associated data; the structure is header stanzas followed by a list of changes vs. each parent revision, with each change represented by a separate stanza; reordering the stanzas could cause a particular change to be interpreted against the wrong parent.

Another example is the read-permissions file that’s read by the default definition of the get_netsync_read_permitted Lua hook.

Monotone will format its output in basic_io as follows:

• Each symbol begins a new line.
• Tokens on the same line are separated by a single space.
• Lines are grouped into logical stanzas, separated by a single empty line. Each stanza then describes a particular item, with the different lines (symbols followed by string and hex values) describing different aspects of that item.
• symbols in a stanza are right-aligned with each other; each symbol other than the longest is preceeded by spaces. The longest symbol in a stanza is not preceeded by spaces, even if there are longer symbols in other stanzas.
• Lines within stanzas have a consistent order, although some may be optional in some commands.