README

==Summary==

YAVL-CPP is a C++ library to help validate YAML files
against a user-provided specification.

The specification file is also written in YAML.

I hesitate to say that this tool checks an input
YAML against a "grammar". I do not think the specification
format I've defined is general enough to be called a
"grammar".

Maybe I should call it a "tree specification" (treespec).

Note: this is not a tool to check if the input file is a valid
YAML; any YAML parser will do that. This library can be
used to check if the input YAML has the tree structure
(i.e., keys, values, types, nesting of keys) that your
application expects. See example below.

The idea is that generation of error messages about
what is wrong with a YAML file can be automated through
this library, so that your processing functions can be
written assuming that the tree generated from the YAML
file conforms to your code's assumptions.

Structures such as lists of lists, maps of lists,
lists etc can be nicely checked. :)

==Example Tree Specification==

{{{
map:
  HEADER:
    map:
      name: [string: ]
      version: [string: ]
      size: [enum: [big, small]]
      pieces:
        map:
          a:
            list: [string: ]
          b:
            list: [uint64: ]
}}}

Notice that HEADER.pieces.a is list nested within
the map HEADER.pieces. You can have arbitrary levels
of nesting, and also do things like maps within lists.

Note: one of the items in the [http://code.google.com/p/yavl-cpp/source/browse/trunk/TODO TODO] is to simplify this
syntax.

==Valid YAML==

{{{
HEADER:
  name: myname
  version: 1.02
  size: big
  pieces:
    a: [hello, world]
    b: [100, 200]
}}}

==Invalid YAML==

{{{
HEADER:
  name: myname
  version: 1.02
  size: xbig
  pieces:
    a: [hello, world]
    b: [x100, 200]
}}}

With the invalid YAML, you'll get an errors that 'xbig'
is not allowed and that 'x100' could not be converted to
a 'long long'.

==Dependencies==

Yavl-cpp uses the excellent [http://code.google.com/p/yaml-cpp/ yaml-cpp] library. Go check
out yaml-cpp just for the heck of it. It's one of the
best designed libraries out there (IMHO). Simple, and to the
point implementation and documentaion.

==Compilation==

Nothing fancy. Just compile in yavl.cpp and all the cpp files of
yaml-cpp with your program. I believe that libraries should pollute
your build process as little as possible (thankfully, so does
yaml-cpp).

Here is how you would compile the example checker program,
example-code/checker.cpp. YAML_CPP_DIR is where you
untarred the yaml-cpp source and YAVL_CPP_DIR is where
you untarred the yavl-cpp source.

{{{
g++ -I$YAML_CPP_DIR/include -I$YAVL_CPP_DIR/src \
  $YAML_CPP_DIR/src/*.cpp \
  $YAVL_CPP_DIR/src/yavl.cpp \
  $YAVL_CPP_DIR/example-code/checker.cpp -o checker
}}}

And run it like this:

{{{
checker $YAVL_CPP_DIR/example-specs/gr3.yaml $YAVL_CPP_DIR/example-specs/y0.gr3.yaml
}}}

==Developer Notes==

What I found interesting about this exercise was how short I was
able to make the checker program by a judicious selection of:

  * problem space restriction
  * treespec language is itself YAML
  
Problem space restriction gave the most bang. Instead of
solving a very general problem, I chose to solve a certain
subset of the problem. I think it's quite a large subset,
so hopefully many people will find this library useful.

By using YAML to encode the treespec, I saved myself the
hassle of writing a parser, and the user of the library
the hassle of learning yet another DSL.

eof