root/juggler/tags/1.0_alpha_02/Config/FileFormats.txt

Description of File Formats for Config and ChunkDesc files.

- Notes on parsing:

Reserved words/tokens:

in Config files:
   end
   true
   false
   yes
   no
in ChunkDesc files:
   chunk
   end
   string
   double
   int 
   boolean
1. In order to have words that the parser will think are tokens interpreted 
   as strings, surround them with quotes ("").  This is also necessary
   in order to have strings with whitespace considered as single strings.
2. bug - there's no way to include quotes inside a quoted string. (Is this
   possible in non-quoted strings?).


II.  Description of ChunkDesc (ConfigChunk Description) files.

   A ChunkDesc file includes descriptions of different kinds of
ConfigChunks.  It is a way to configure the configuration system itself.
For example, here are two entries that you might find in a ChunkDesc file:

        chunk flockobirds
          port string 1 port "serial port address"
          offset double 3 offset "tracker coord offset from origin"
          baudrate int 1 baud "serial port rate"
          end

        chunk display
          name string 1 name "descriptive name"
          origin double 3 origin "other help text"
          size int 2 size ""
          SGIpipe int 1 SGIpipe ""
          xdisplay string 1 xdisplay ""
          stereo bool 1 stereo ""
          lowerleft double 3 lowerleft ""
          lowerright double 3 lowerright ""
          upperleft double 3 upperleft ""
          end

   The first entry defines a chunk type called "flockobirds" that contains
three properties ("port", "offset", and "baudrate").  The second defines
a chunktype called "display" which contains 9 properties.
   Each property has a type - for example, the values that "port" can take
will be strings, such as "/dev/ttyd45", while baudrate will always have
integer values.
   It is possible for a property to have a set of values.  For example,
the "display" chunk's "lowerleft", "lowerright", and "upperleft" 
properties are meant to represent positions in 3d space.  These can be 
represented by a sequence of three doubles for the x, y, and z coordinates.
The number of values a property supports is listed directly to the right
of the type - the "3" in the line for "lowerleft", or the "1" for "stereo."
If a property might have a variable number of entries (perhaps as a list
of active displays, or such), use the number -1.
   The fourth word on each property line is the actual token to be used to
represent this property when reading/writing config files.  Most often this
will be the same as the name of the property (which is used internally for
querying a ConfigChunk), but the options is provided to make the config
files more flexible or readable.
   The last thing on a property line is a help string.  If the help string 
contains spaces or is empty, it must be in quotes. 

   For int type properties, there is also an optional set of enumeration
values, which can be placed between the token name and the help string. 
For example:

        chunk C2Setup
          ActiveWalls int -1 ActiveWalls { front back left right top 
                bottom } "list of walls to show"

   then in a config file, instead of having to say "ActiveWalls { 0 3 4 }"
you can say, more intuitively, "ActiveWalls { front right top }".  Values
in an enum start at 0, but can also be explicitly stated:

          ActiveWalls int -1 ActiveWalls { front=3 back left right=0 } ""

then the values assigned to each enumeration item will be 3,4,5, and 0, 
from left to right.

   In addition to the explicitly listed properties, every chunktype has a 
property called "type", which has a single string value.  This provides a
way to query for the type of the ConfigChunk.  For our examples above, the
values of the "type" property would be "flockobirds" and "display", 
respectively.
   Once all the properties for a particular chunk have been listed, the
symbol "end" is used to close the description.

   Here's the standard form of a ConfigDesc entry:

        chunk <typename>
          <property1> <type> <numentries> <token>
          <property2> ...
          ...
          <propertyn> ...
          end

   <Typename> can be any string value (that hasn't already been defined as a
typename).  <Propertyx> can be any string, except "type" (and all the
property names for a given chunk type should be unique).  <Numentries> is
an integer, greater than 0 or -1.  <Token> is any string (although all tokens
in a given chunk type should be unique).

   A ChunkDesc file is simply zero or more of these entries, followed by
a final "end".


III. Description of ConfigChunk files

   A config file is zero or more ConfigChunk entries terminated with the word
"end".  Here are some example chunks:

display
  name "c2 rear wall"
  XDisplay ":0.0"
  stereo false
  sgipipe 1
  size { 9 12 }
  lowerleft { 3.4 6.555 9.9 }
  origin { 3.3 1.0 5.5 }
  end

display
  name "c2 Front Wall"
  XDisplay ":0.0"
  stereo true
  end

c2setup
  c2width 3.3
  walls { front left right top bottom }
  c2height 3.5
  end

end