...one of the most highly
regarded and expertly designed C++ library projects in the
world. — Herb Sutter and Andrei
Throughout the description of Spirit.Karma we will try to align ourselves very much with the documentation for Spirit.Qi. The reasons are many fold:
Why should you use a generator library for such a simple thing as output
generation? Programmers have been using
std::stream formatting, or
for quite some time. The answer is - yes, for simple output formatting
tasks those familiar tools might be a quick solution. But experience shows:
as soon as the formatting requirements are becoming more complex output
generation is getting more and more challenging in terms of readability,
maintainability, and flexibility of the code. Last, but not least, it turns
out that code using Spirit.Karma runs much faster
than equivalent code using either of the 'straight' methods mentioned above
(see here for some numbers: Performance
of Numeric Generators)
You might argue that more complex tasks require more complex tools. But this turns out not to be the case! The whole Spirit library is designed to be simple to use, while being scalable from trivial to very complicated applications.
In terms of development simplicity and ease in deployment, the same is true for Spirit.Karma as has been described elsewhere in this documentation for Spirit.Qi: the entire library consists of only header files, with no libraries to link against or build. Just put the spirit distribution in your include path, compile and run. Code size? Very tight, essentially comparable to hand written code.
The Spirit.Karma tutorials are built in a walk through style, starting with elementary things growing step by step in complexity. And again: keep in mind output generation is the exact opposite of parsing. Everything you already learnt about parsing using Spirit.Qi is applicable to generating formatted output using Spirit.Karma. All you have to do is to look at Spirit.Karma as being a mirror image of Spirit.Qi.