Re: [Monotone-devel] basic_io inventory

[Thomas Moschny]

On Saturday 28 April 2007, Stephen Leake wrote:
> Is there some documentation on these requirements for basic_io
> parsers? I found basic_io.hh and luaext_parse_basic_io.cc; not many
> comments :). I searched the wiki for "basic_io" and "basic io"; I
> found BasicIoFormalization, which doesn't say much, but hints at
> "formal docs" somewhere.
>
> It does point to an IRC session, which says that stanzas are not
> actually meaningful. Which is a scary concept; it implies that in the
> 'automate inventory' output, the 'path' and 'old_node' lines are
> _not_ related to each other. Which is of course nonsense!

It is not, because all existing commands emit their output in a fixed order; 
so the beginning and end of each stanza, and even different types of stanzas 
can be detected without relying on some amount of whitespace between them, 
and a stable parser should not (need to) do so.

Parsing basic_io typically consists of two steps: First, breaking down the 
input stream into tokens (key tokens followed by zero or more value tokens), 
thereby striping all white space and dequoting string values. Second, reading 
the token stream in an application-dependend manner (see above). In this 
second step, you should have an idea of the meaning and the possible 
orderings of the key tokens. 

Note that basic_io is a low-level format to transport (key,valuelist) pairs, 
nothing more. Nothing is said about the meaning of keys and values. (For 
example the encoding of string values is not defined. From basic_io's pov 
they are byte sequences.) It's up to the application to define their meaning.

- Thomas M.

pgpuPDDZp2Yp5.pgp
Description: PGP signature