README

0  QUICKSTART

libyaml++ is a C++ library for reading and writing YAML streams.  To build,
run from your Linux command shell:

 ~$ tar xzf libyamlpp.tar.gz
 ~$ cd libyamlpp
 libyamlpp$ ./build.sh

Next, see USING LIBYAML++ for sample code.


1  INTRODUCTION

libyaml++ is a C++ library for reading and writing YAML streams.  YAML stands
for YAML Ain't a Markup Language.  It is a portable data-serialization
protocol, designed primarily for readability by humans.  YAML plays well as a
protocol for message-based distributed processing systems.

YAML is somewhat comparable with XML in that it can be used as a protocol for
serializing structured, hierarchical documents.  XML, however, was designed to
be backwards-compatible with SGML, the Standard Generalized Markup Language,
which in turn was designed primarily to store structured documents.  YAML
therefore has more freedom of design.  When compared to XML, YAML elevates
its design goals to support data streams that show a balance between a
flexible syntax and readability.


2  DIRECTORY TREE STRUCTURE

This distribution consists of three components.  The first and most important
component is the library's source code, and it is placed under the src/
subdirectory.  The second component is the demo application, which demonstrates
the library's capabilities and use and is located, obviously enough, in the
demo/ subdirectory.  The last component is the testing code, which tests the
source code of the library and is located in the test/ subdirectory.


3  BUILDING

The The easiest way to build libyaml++ is using the build.sh script in the
distribution's root directory.  It will set up your system for building
libyaml++ as well as its unit-tests.  The build.sh script assumes you are using
Linux though, along with a number of specific tools installed, such as wget,
GNU utilities, bash and others.  Internet connection is required as well if you
do not have GoogleTest and Boost.Build installed, is the script will attempt to
download and install these in a temporal directory in this case..  An
alternative way is to build the library manually.  If you intened to hack on
the code we recommend you set yourself up properly: install Boost.BuildV2 and
GoogleTest in a convenient directory in your system and use bjam for the build.

We will cover in this section all approaches mentioned above.


3.1  BUILDING USING BUILD.SH

From the command prompt of your Linux box run:

 ~$ cd libyamlpp
 libyamlpp$ ./build.sh

The build.sh script can take any target as a command-line parameter, so you may
for example run

 libyamlpp$ ./build.sh demo check

to build the demo and check targets, for the demonstration application and
unit-tests, repectively.  The build.sh script can also take a special
command-line argument, wipeclean, which will wipe clean any files and
directories it may have created:

 libyamlpp$ ./build.sh wipeclean

The above command will leave nothing but the original libyaml++ distribution
has.  Make sure you pass no other command-line argument when running the above
command.


3.2  USING BOOST.BUILD

Boost.Build doesn't usually come by default in an operating-system's install.
So first, make sure you have Boost.BuildV2, and Boost.Jam on which Boost.Build
depends, installed.  Once that is set up, running the build is a matter of a
single command.


3.2.1  SETTING-UP BOOST.BUILD

If you run a Debian-based Linux distribution, this may simply be a matter of

 #$ sudo apt-get install boost-build

Other Linux distributions have their own package management system, so read the
appropriate manual pages.  If that fails or if you don't have a package
management system, get Boost.Build from
http://www.boost.org/doc/tools/build/index.html and following the instructions
at http://www.boost.org/doc/tools/build/doc/html/bbv2/installation.html.
Installing Boost.Build is a fairly straightforward procedure that consists
mainly of four steps:

 1. Copy the extracted Boost.Build distribution into a directory reachable by
    your operating-system's PATH.
 2. Configure Boost.Build by choosing your compiler of choice in the
    site-config.jam file in Boost.Build's root directory.  It should be a
    matter of uncommenting a line such as

    using gcc ;

 3. Copy the bjam binary into a directory reachable by your operating-system's
    PATH.
 4. export BOOST_BUILD_PATH=/path/to/boost-build

Further details are given in the link above.


3.2.2  BUILDING USING BOOST.BUILD

To build libyaml++, from the libyaml++ distribution's root directory run the
command:

 libyamlpp$ bjam release

This will build libyaml++ and place the resultant binary in a directory
structure under src/bin/release/.  The exact heirarchy structure will depend on
your system.  Our system, for example, will place the resultant binary in
src/bin/release/gcc/libyaml++.so.  Your environment may be, for example, in
src/bin/release/msvc/libyaml++.so.

To build the demo application, run the following command from the project
distribution's root directory:

 libyamlpp$ bjam demo release

Again, the exact location of the resultant binary will depend on your system
but will be somewhere under demo/bin/release/.  In our case it is in
demo/bin/release/gcc/libyaml++-demo.

To build the test suites, run

 libyamlpp$ bjam check

This will also run the tests once they are built.


3.3  TESTING

The source code comes with a set of tests that attempt to find bugs or issues
with the library.  These tests rely on the Google Test framework, so you must
have that set up to run them.


3.3.1  SETTING-UP GOOGLETEST

Get GoogleTest from http://code.google.com/p/googletest/.  We used GoogleTest
v1.1.0 successfully.  Extract the distribution package in a directory of your
choice, and build it.  To install GoogleTest in your home directory on a Unix
machine the following commands will do:

 ~$ tar jxf gtest-1.1.0.tar.bz2
 ~$ cd gtest-1.1.0
 gtest-1.1.0$ ./configure --prefix=$HOME/usr
 gtest-1.1.0$ make
 gtest-1.1.0$ make install

Next, you must make sure that

 a. the C++ preprocessor can find the gtest headers
 b. the linker can find the gtest library when linking the libyaml++ tests
 c. the runtime evironment can find the shared library when the tests are run

To accomodate for this on a Unix platform using gcc for the build and assuming
the above commands were used for installing GoogleTest, add the following three
environment variables to your shell's startup file, such as ~/.bashrc:

 export CPLUS_INCLUDE_PATH=$HOME/usr/include:$CPLUS_INCLUDE_PATH
 export LIBRARY_PATH=$HOME/usr/lib:$LIBRARY_PATH
 export LD_LIBRARY_PATH=$HOME/usr/lib:$LD_LIBRARY_PATH


3.3.2  RUNNING THE TESTS

Once GoogleTest is set up you may run the tests.  From the commandline and from
within the project's root directory, run:

 libyamlpp$ bjam check


4  USING LIBYAML++

[ NOTE:  as our library is not fully implemented yet, the following section
describes what is being constantly changed.  Thus, when we describe how our
yet-to-be-born library is used either the text is hypothetical or is outdated
and needs to be revised. ]

To use libyaml++, you need either a C++ compiler or to know how to write one.
We recommed the former.  Put the binaries somewhere reachable by your compiler
and linker's search paths.

 #include <fstream>
 #include <algorithm>
 #include <tr1/memory>
 #include <yaml++.h>

 using namespace std;
 using namespace std::tr1;

 void play_with_node(shared_ptr<node> nd) { }

 shared_ptr<node> return_some_node() { }

 int main(int argc, char* argv)
 {
     // to read yaml and do something with it:
     ifstream the_file("/home/me/teh_file.yaml");

     // NOTE:  The following are hypothetical ideas, as none of this is not
     //        implemented yet.  We have two solutions in mind.  The first:
     for_each(istream_iterator<yaml::node>(the_file),
              istream_iterator<yaml::node>(),
              play_with_node);

     // the second hypothetical solution is:
     shard_ptr<yaml::node> data = yaml::load(the_file); // loads an istream
     for_each(data.begin(), data.end(), play_with_node);

     // do stuff with data

     shared_ptr<node> my_data;
     generate_n(back_inserter(my_data), 42, return_some_node);
     cout << yaml::dump(my_data);  // dumps a string
 }