ceph/src/boost/libs/spirit/doc/karma/basics.qbk

   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
  13 Some generators (e.g. primitives and non-terminals) may take in additional
  14 attributes. Such generators take the form:
  15
  16     g(a1, a2,..., aN)
  17
  18 where `g` is a generator. Each of the arguments (a1 ... aN) can either be an
  19 immediate value, or a function, `f`, with signature:
  20
  21     T f(Unused, Context)
  22
  23 where `T`, the function's return value, is compatible with the argument
  24 type expected and `Context` is the generator's __karma_context__ type (The
  25 first argument is __unused__ to make the `Context` the second argument. This
  26 is done for uniformity with __karma_actions__).
  27
  28 [heading Character Encoding Namespace]
  29
  30 Some generators need to know which character set a `char` or `wchar_t` is
  31 operating on. For example, the `alnum` generator works differently with
  32 ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags)
  33 the generator with the character set.
  34
  35 We have a namespace for each character set Spirit will be supporting.
  36 That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
  37 in the future, `unicode`). In each of the character encoding namespaces,
  38 we place tagged versions of generators such as `alnum`, `space` etc.
  39
  40 Example:
  41
  42     using boost::spirit::ascii::space; // use the ASCII space generator
  43
  44 Namespaces:
  45
  46 * boost::spirit::ascii
  47 * boost::spirit::iso8859_1
  48 * boost::spirit::standard
  49 * boost::spirit::standard_wide
  50
  51 For ease of use, the components in this namespaces are also brought into
  52 the 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
  61 All sections in the reference present some real world examples. The
  62 examples use a common test harness to keep the example code as minimal
  63 and direct to the point as possible. The test harness is presented
  64 below.
  65
  66 Some includes:
  67
  68 [reference_karma_includes]
  69
  70 The used output  iterator:
  71
  72 [reference_karma_output_iterator]
  73
  74 Our test functions:
  75
  76 This one tests the generators without attributes.
  77
  78 [reference_karma_test]
  79
  80 These test the generators with one or more user supplied attributes.
  81
  82 [reference_karma_test_attr]
  83 [reference_karma_test_attr2]
  84
  85 This tests the generators with one attribute and while using delimited output.
  86
  87 [reference_karma_test_attr_delim]
  88
  89 The 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
  96 Predefined 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
 102 The namespace `boost::spirit::traits` is open for users to provide their
 103 own specializations. The customization points implemented by __karma__ usable
 104 to customize the behavior of generators are described in the section
 105 __sec_customization_points__.
 106
 107 [endsect]
 108