[Monotone-commits-diffs] net.venge.monotone.levitte.formats-manual: 1d61e7b0ae0973d12baff83659dcc4b6abeeae35

[code]

revision:            1d61e7b0ae0973d12baff83659dcc4b6abeeae35
date:                2010-12-02T16:00:23
author:              Richard Levitte <address@hidden>
branch:              net.venge.monotone.levitte.formats-manual
changelog:
Place format descriptions (for now just basic_io) in its own chapter

manifest:
format_version "1"

new_manifest [ccbb452a6af10f55fb3e7f86f6baf888303ccf14]

old_revision [31cec226a449bda9ebcf1a4739229a88fbe32f18]

patch "monotone.texi"
 from [fcbb03be116d85a953e1075fd67b3e779b7e3c01]
   to [4692fc59af895390bbb91d6c8dfd03d729dc4d21]
============================================================
--- monotone.texi	fcbb03be116d85a953e1075fd67b3e779b7e3c01
+++ monotone.texi	4692fc59af895390bbb91d6c8dfd03d729dc4d21
@@ -6859,51 +6859,9 @@ @section Automation
 also give useful chatter on @code{stderr}, including warnings and error
 messages.
 
address@hidden @code{basic_io} Format
+Many commands produce output in a format called basic_io, for more
+information, @pxref{Formats}.
 
-Many commands produce output in a format called basic_io. At the most basic
-level this is a stream of three token types, separated by whitespace; a
address@hidden matches @code{/[a-z_]+/} (a word consisting of lowercase letters
-and underscores), a @code{string} matches @code{/"([^\\]|\\\\|\\")*"/} (a pair
-of double-quotes containing arbitrary characters, with only backslash and
-double-quote escaped with a backslash), and a @code{hex} matches
address@hidden/address@hidden@}\]/} (40 lowercase hex digits enclosed by square
-brackets; this will necessarily change in some manner when we eventually move
-to a stronger hash than sha1). Each @code{symbol} is followed by zero or more
address@hidden and/or @code{hex}es.
-
-While the above is all that is strictly necessary to parse basic_io, there is
-some formatting of the stream which may be helpful when parsing and is required
-(but not always verified) when producing basic_io for consumption by monotone:
address@hidden
address@hidden
-Each @code{symbol} begins a new line.
address@hidden
-Tokens on the same line are separated by a single space.
address@hidden
-Lines are grouped into logical @code{stanza}s, separated by a single empty line.
-Each stanza then describes a particular item, with the different lines
-(@code{symbol}s followed by @code{string} and @code{hex} values) describing
-different aspects of that item.
address@hidden
address@hidden in a stanza are right-aligned with each other; each @code{symbol}
-other than the longest is preceeded by spaces. The longest @code{symbol} in a
-stanza is not preceeded by spaces, even if there are longer @code{symbol}s in
-other stanzas.
address@hidden
-Lines within stanzas have a consistent order, although some may be
-optional in some commands.
address@hidden
-Stanzas typically have no defined order, although some commands define
-a partial order to aid in parsing.
-
-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.
address@hidden itemize
-
 @subsection Automation Commands
 
 @ftable @command
@@ -8223,7 +8181,7 @@ @subsection Automation Commands
 
 @end table
 
address@hidden mtn automate stdio
address@hidden@item mtn automate stdio
 
 @table @strong
 @item Arguments:
@@ -11090,7 +11048,88 @@ @section GIT
 @end ftable
 
 
address@hidden    Lua Reference, Special Topics, Command Reference, Top
address@hidden    Formats, Lua Reference, Command Reference, Top
address@hidden Formats
+
+Monotone uses two well defined formats to output or to accept input of
+data (mostly structured), @code{basic_io} and @code{stdio}.
address@hidden is often used to represent data or for configuration,
+while @code{stdio} is used for communication with @code{automate stdio}.
+
+The @code{stdio} format is not described here.  For information on it,
+please @pxref{mtn-au-stdio,,@code{mtn automate stdio}}.
+
address@hidden @code{basic_io} Format
+
address@hidden is a very simple format, yet expressive, and can be
+described with the following ABNF (see RFC 2234) specification:
+
address@hidden
address@hidden
+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.
address@hidden verbatim
address@hidden display
+
+In essence, it's a stream of items, where each item is a @code{symbol}
+followed by zero or more @code{string}s and @code{hex}es.
+
+There is an idea of stanzas, which is a group of items that logically
+belongs together.  However, stanzas aren't defined in the
address@hidden 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 @file{read-permissions} file that's read by the
+default definition of the @code{get_netsync_read_permitted} lua hook.
+
+Monotone will format its output in @code{basic_io} as follows:
address@hidden
address@hidden
+Each @code{symbol} begins a new line.
address@hidden
+Tokens on the same line are separated by a single space.
address@hidden
+Lines are grouped into logical @code{stanza}s, separated by a single empty line.
+Each stanza then describes a particular item, with the different lines
+(@code{symbol}s followed by @code{string} and @code{hex} values) describing
+different aspects of that item.
address@hidden
address@hidden in a stanza are right-aligned with each other; each @code{symbol}
+other than the longest is preceeded by spaces. The longest @code{symbol} in a
+stanza is not preceeded by spaces, even if there are longer @code{symbol}s in
+other stanzas.
address@hidden
+Lines within stanzas have a consistent order, although some may be
+optional in some commands.
address@hidden itemize
+
address@hidden    Lua Reference, Special Topics, Formats, Top
 @chapter Lua Reference
 
 Monotone makes use of the @uref{http://www.lua.org, Lua} programming