1[/==============================================================================
2    Copyright (C) 2001-2011 Joel de Guzman
3    Copyright (C) 2001-2011 Hartmut Kaiser
4
5    Distributed under the Boost Software License, Version 1.0. (See accompanying
6    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7===============================================================================/]
8
9[section:basics Generator Basics]
10
11[heading Lazy Argument]
12
13Some generators (e.g. primitives and non-terminals) may take in additional
14attributes. Such generators take the form:
15
16    g(a1, a2,..., aN)
17
18where `g` is a generator. Each of the arguments (a1 ... aN) can either be an
19immediate value, or a function, `f`, with signature:
20
21    T f(Unused, Context)
22
23where `T`, the function's return value, is compatible with the argument
24type expected and `Context` is the generator's __karma_context__ type (The
25first argument is __unused__ to make the `Context` the second argument. This
26is done for uniformity with __karma_actions__).
27
28[heading Character Encoding Namespace]
29
30Some generators need to know which character set a `char` or `wchar_t` is
31operating on. For example, the `alnum` generator works differently with
32ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags)
33the generator with the character set.
34
35We have a namespace for each character set Spirit will be supporting.
36That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
37in the future, `unicode`). In each of the character encoding namespaces,
38we place tagged versions of generators such as `alnum`, `space` etc.
39
40Example:
41
42    using boost::spirit::ascii::space; // use the ASCII space generator
43
44Namespaces:
45
46* boost::spirit::ascii
47* boost::spirit::iso8859_1
48* boost::spirit::standard
49* boost::spirit::standard_wide
50
51For ease of use, the components in this namespaces are also brought into
52the karma sub-namespaces with the same names:
53
54* boost::spirit::karma::ascii
55* boost::spirit::karma::iso8859_1
56* boost::spirit::karma::standard
57* boost::spirit::karma::standard_wide
58
59[heading Examples]
60
61All sections in the reference present some real world examples. The
62examples use a common test harness to keep the example code as minimal
63and direct to the point as possible. The test harness is presented
64below.
65
66Some includes:
67
68[reference_karma_includes]
69
70The used output  iterator:
71
72[reference_karma_output_iterator]
73
74Our test functions:
75
76This one tests the generators without attributes.
77
78[reference_karma_test]
79
80These test the generators with one or more user supplied attributes.
81
82[reference_karma_test_attr]
83[reference_karma_test_attr2]
84
85This tests the generators with one attribute and while using delimited output.
86
87[reference_karma_test_attr_delim]
88
89The examples of the binary generators use one or more of the following tests.
90
91[reference_karma_binary_test]
92[reference_karma_binary_test_attr]
93
94[heading Models]
95
96Predefined models include:
97
98* any literal string, e.g. "Hello, World",
99* a pointer/reference to a null-terminated array of characters
100* a `std::basic_string<Char>`
101
102The namespace `boost::spirit::traits` is open for users to provide their
103own specializations. The customization points implemented by __karma__ usable
104to customize the behavior of generators are described in the section
105__sec_customization_points__.
106
107[endsect]
108
109