| Home | Libraries | People | FAQ | More

#### Quick Start

###### Spirit.Karma - what's that?

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:

- Spirit.Karma is the counterpart to Spirit.Qi. Some people say it's the Yin to Spirit.Qi's Yang. Spirit.Karma is generating byte sequences from internal data structures as Spirit.Qi is parsing byte sequences into those (very same) internal data structures.
- Both libraries have an almost identical structure, very similar semantics, and are both built using identical tools. Both libraries implement a language casting the specifics of their domain (parsing and generating) into a simple interface.

Why should you use a generator library for such a simple thing as output generation? Programmers have been using `printf`, `std::stream` formatting, or `boost::format` 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.