[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2010 Hartmut Kaiser

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section:karma_basics Basics]

[heading Lazy Argument]

Some generators (e.g. primitives and non-terminals) may take in additional
attributes. Such generators take the form:

    g(a1, a2,..., aN)

where `g` is a generator. Each of the arguments (a1 ... aN) can either be an
immediate value, or a function, `f`, with signature:

    T f(Unused, Context)

where `T`, the function's return value, is compatible with the argument
type expected and `Context` is the generator's __karma_context__ type (The 
first argument is __unused__ to make the `Context` the second argument. This
is done for uniformity with __karma_actions__).

[heading Character Encoding Namespace]

Some generators need to know which character set a `char` or `wchar_t` is
operating on. For example, the `alnum` generator works differently with
ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags)
the generator with the character set. 

We have a namespace for each character set Spirit will be supporting.
That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
in the future, `unicode`). In each of the character encoding namespaces,
we place tagged versions of generators such as `alnum`, `space` etc. 

Example:

    using boost::spirit::ascii::space; // use the ASCII space generator

Namespaces:

* boost::spirit::ascii
* boost::spirit::iso8859_1
* boost::spirit::standard
* boost::spirit::standard_wide

For ease of use, the components in this namespaces are also brought into
the karma sub-namespaces with the same names:

* boost::spirit::karma::ascii
* boost::spirit::karma::iso8859_1
* boost::spirit::karma::standard
* boost::spirit::karma::standard_wide

[heading Examples]

All sections in the reference present some real world examples. The
examples use a common test harness to keep the example code as minimal
and direct to the point as possible. The test harness is presented
below.

Some includes:

[reference_karma_includes]

The used output  iterator:

[reference_karma_output_iterator]

Our test functions:

This one tests the generators without attributes.

[reference_karma_test]

These test the generators with one or more user supplied attributes.

[reference_karma_test_attr]
[reference_karma_test_attr2]

This tests the generators with one attribute and while using delimited output.

[reference_karma_test_attr_delim]

The examples of the binary generators use one or more of the following tests.

[reference_karma_binary_test]
[reference_karma_binary_test_attr]

[heading Models]

Predefined models include:

* any literal string, e.g. "Hello, World", 
* a pointer/reference to a null-terminated array of characters
* a `std::basic_string<Char>`

The namespace `boost::spirit::traits` is open for users to provide their
own specializations. The customization points implemented by __karma__ usable
to customize the behavior of generators are described in the section 
__sec_customization_points__.

[endsect]