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

    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:char Char]

This module includes different character oriented generators allowing to output
single characters. Currently, it includes literal chars (e.g. `'x'`, `L'x'`), 
`char_` (single characters, ranges and character sets) and the encoding 
specific character classifiers (`alnum`, `alpha`, `digit`, `xdigit`, etc.). 

[heading Module Header]

    // forwards to <boost/spirit/home/karma/char.hpp>
    #include <boost/spirit/include/karma_char.hpp>

Also, see __include_structure__.

[/////////////////////////////////////////////////////////////////////////////]
[section:char_generator Character Generators (`char_`, `lit`)]

[heading Description]

The character generators described in this section are:

The `char_` generator emits single characters. The `char_` generator has an
associated __karma_char_encoding_namespace__. This is needed when doing basic
operations such as forcing lower or upper case and dealing with
character ranges.

There are various forms of `char_`. 

[heading char_]

The no argument form of `char_` emits any character in the associated
__karma_char_encoding_namespace__.

    char_               // emits any character as supplied by the attribute

[heading char_(ch)]

The single argument form of `char_` (with a character argument) emits
the supplied character. 

    char_('x')          // emits 'x'
    char_(L'x')         // emits L'x'
    char_(x)            // emits x (a char)

[heading char_(first, last)]

`char_` with two arguments, emits any character from a range of characters as 
supplied by the attribute.

    char_('a','z')      // alphabetic characters
    char_(L'0',L'9')    // digits

A range of characters is created from a low-high character pair. Such a
generator emits a single character that is in the range, including both
endpoints. Note, the first character must be /before/ the second,
according to the underlying __karma_char_encoding_namespace__.

Character mapping is inherently platform dependent. It is not guaranteed
in the standard for example that `'A' < 'Z'`, that is why in Spirit2, we
purposely attach a specific __karma_char_encoding_namespace__ (such as ASCII,
ISO-8859-1) to the `char_` generator to eliminate such ambiguities.

[note *Sparse bit vectors*

To accommodate 16/32 and 64 bit characters, the char-set statically
switches from a `std::bitset` implementation when the character type is
not greater than 8 bits, to a sparse bit/boolean set which uses a sorted
vector of disjoint ranges (`range_run`). The set is constructed from
ranges such that adjacent or overlapping ranges are coalesced.

`range_runs` are very space-economical in situations where there are lots
of ranges and a few individual disjoint values. Searching is O(log n)
where n is the number of ranges.]

[heading char_(def)]

Lastly, when given a string (a plain C string, a `std::basic_string`,
etc.), the string is regarded as a char-set definition string following
a syntax that resembles posix style regular expression character sets
(except that double quotes delimit the set elements instead of square
brackets and there is no special negation ^ character). Examples:

    char_("a-zA-Z")     // alphabetic characters
    char_("0-9a-fA-F")  // hexadecimal characters
    char_("actgACTG")   // DNA identifiers
    char_("\x7f\x7e")   // Hexadecimal 0x7F and 0x7E

These generators emit any character from a range of characters as 
supplied by the attribute.

[heading lit(ch)]

`lit`, when passed a single character, behaves like the single argument
`char_` except that `lit` does not consume an attribute. A plain
`char` or `wchar_t` is equivalent to a `lit`.

[note `lit` is reused by the [karma_string String Generators], the
      char generators, and the Numeric Generators (see [signed_int signed integer], 
      [unsigned_int unsigned integer], and [real_number real number] generators). In 
      general, a char generator is created when you pass in a
      character, a string generator is created when you pass in a string, and a 
      numeric generator is created when you use a numeric literal. The
      exception is when you pass a single element literal string, e.g.
      `lit("x")`. In this case, we optimize this to create a char generator
      instead of a string generator.] 

Examples:

    'x'
    lit('x')
    lit(L'x')
    lit(c)      // c is a char

[heading Header]

    // forwards to <boost/spirit/home/karma/char/char.hpp>
    #include <boost/spirit/include/karma_char_.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::lit // alias: boost::spirit::karma::lit` ]]
    [[`ns::char_`]]
]

In the table above, `ns` represents a __karma_char_encoding_namespace__. 

[heading Model of]

[:__primitive_generator_concept__]

[variablelist Notation
    [[`ch`, `ch1`, `ch2`]
                  [Character-class specific character (See __char_class_types__),
                   or a __karma_lazy_argument__ that evaluates to a 
                   character-class specific character value]]
    [[`cs`]       [Character-set specifier string (See 
                   __char_class_types__), or a __karma_lazy_argument__ that 
                   evaluates to a character-set specifier string, or a 
                   pointer/reference to a null-terminated array of characters.
                   This string specifies a char-set definition string following 
                   a syntax that resembles posix style regular expression character 
                   sets (except the square brackets and the negation `^` character).]]
    [[`ns`]       [A __karma_char_encoding_namespace__.]]
    [[`cg`]       [A char generator, a char range generator, or a char set generator.]]]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.

[table
    [[Expression]           [Description]]
    [[`ch`]                 [Generate the character literal `ch`. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`lit(ch)`]            [Generate the character literal `ch`. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`ns::char_`]          [Generate the character provided by a mandatory 
                             attribute interpreted in the character set defined 
                             by `ns`. This generator never fails (unless the 
                             underlying output stream reports an error).]]
    [[`ns::char_(ch)`]      [Generate the character `ch` as provided by the 
                             immediate literal value the generator is initialized 
                             from. If this generator has an associated attribute 
                             it succeeds only as long as the attribute is equal 
                             to the immediate literal (unless the underlying 
                             output stream reports an error). Otherwise this 
                             generator fails and does not generate any output.]]
    [[`ns::char_("c")`]     [Generate the character `c` as provided by the 
                             immediate literal value the generator is initialized 
                             from. If this generator has an associated attribute 
                             it succeeds only as long as the attribute is equal 
                             to the immediate literal (unless the underlying 
                             output stream reports an error). Otherwise this 
                             generator fails and does not generate any output.]]
    [[`ns::char_(ch1, ch2)`][Generate the character provided by a mandatory 
                             attribute interpreted in the character set defined 
                             by `ns`. The generator succeeds as long as the 
                             attribute belongs to the character range `[ch1, ch2]` 
                             (unless the underlying output stream reports an 
                             error). Otherwise this generator fails and does not 
                             generate any output.]]
    [[`ns::char_(cs)`]      [Generate the character provided by a mandatory 
                             attribute interpreted in the character set defined 
                             by `ns`. The generator succeeds as long as the 
                             attribute belongs to the character set `cs` 
                             (unless the underlying output stream reports an 
                             error). Otherwise this generator fails and does not 
                             generate any output.]]
    [[`~cg`]                [Negate `cg`. The result is a negated char generator 
                             that inverts the test condition of the character
                             generator it is attached to.]]
]

A character `ch` is assumed to belong to the character range defined by
`ns::char_(ch1, ch2)` if its character value (binary representation) 
interpreted in the character set defined by `ns` is not smaller than the 
character value of `ch1` and not larger then the character value of `ch2` (i.e. 
`ch1 <= ch <= ch2`).

The `charset` parameter passed to `ns::char_(charset)` must be a string
containing more than one character. Every single character in this string is 
assumed to belong to the character set defined by this expression. An exception 
to this is the `'-'` character which has a special meaning if it is not 
specified as the first and not the last character in `charset`. If the `'-'` 
is used in between to characters it is interpreted as spanning a character 
range. A character `ch` is considered to belong to the defined character set 
`charset` if it matches one of the characters as specified by the string 
parameter described above. For example

[table
    [[Example]              [Description]]
    [[`char_("abc")`]       ['a', 'b', and 'c']]
    [[`char_("a-z")`]       [all characters (and including) from 'a' to 'z']]
    [[`char_("a-zA-Z")`]    [all characters (and including) from 'a' to 'z' and 'A' and 'Z']]
    [[`char_("-1-9")`]      ['-' and all characters (and including) from '1' to '9']]
]

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`ch`]                 [__unused__]]
    [[`lit(ch)`]            [__unused__]]
    [[`ns::char_`]          [`Ch`, attribute is mandatory (otherwise compilation 
                             will fail). `Ch` is the character type of the 
                             __karma_char_encoding_namespace__, `ns`.]]
    [[`ns::char_(ch)`]      [`Ch`, attribute is optional, if it is supplied, the 
                             generator compares the attribute with `ch` and 
                             succeeds only if both are equal, failing otherwise.
                             `Ch` is the character type of the 
                             __karma_char_encoding_namespace__, `ns`.]]
    [[`ns::char_("c")`]     [`Ch`, attribute is optional, if it is supplied, the 
                             generator compares the attribute with `c` and 
                             succeeds only if both are equal, failing otherwise.
                             `Ch` is the character type of the 
                             __karma_char_encoding_namespace__, `ns`.]]
    [[`ns::char_(ch1, ch2)`][`Ch`, attribute is mandatory (otherwise compilation 
                             will fail), the generator succeeds if the attribute 
                             belongs to the character range `[ch1, ch2]` 
                             interpreted in the character set defined by `ns`.
                             `Ch` is the character type of the 
                             __karma_char_encoding_namespace__, `ns`.]]
    [[`ns::char_(cs)`]      [`Ch`, attribute is mandatory (otherwise compilation 
                             will fail), the generator succeeds if the attribute 
                             belongs to the character set `cs`, interpreted 
                             in the character set defined by `ns`.
                             `Ch` is the character type of the 
                             __karma_char_encoding_namespace__, `ns`.]]
    [[`~cg`]                [Attribute of `cg`]]
]

[note  In addition to their usual attribute of type `Ch` all listed generators 
       accept an instance of a `boost::optional<Ch>` as well. If the 
       `boost::optional<>` is initialized (holds a value) the generators behave 
       as if their attribute was an instance of `Ch` and emit the value stored
       in the `boost::optional<>`. Otherwise the generators will fail.]

[heading Complexity]

[:O(1)]

The complexity of `ch`, `lit(ch)`, `ns::char_`, `ns::char_(ch)`, and 
`ns::char_("c")` is constant as all generators emit exactly one character per 
invocation.

The character range generator (`ns::char_(ch1, ch2)`) additionally requires 
constant lookup time for the verification whether the attribute belongs to
the character range.

The character set generator (`ns::char_(cs)`) additionally requires 
O(log N) lookup time for the verification whether the attribute belongs to
the character set, where N is the number of characters in the character set.

[heading Example]

[note The test harness for the example(s) below is presented in the
      __karma_basics_examples__ section.]

Some includes:

[reference_karma_includes]

Some using declarations:

[reference_karma_using_declarations_char]

Basic usage of `char_` generators:

[reference_karma_char]

[endsect]

[/////////////////////////////////////////////////////////////////////////////]
[section:char_class Character Classification (`alnum`, `digit`, etc.)]

[heading Description]

The library has the full repertoire of single character generators for
character classification. This includes the usual `alnum`, `alpha`,
`digit`, `xdigit`, etc. generators. These generators have an associated
__karma_char_encoding_namespace__. This is needed when doing basic operations
such as forcing lower or upper case. 

[heading Header]

    // forwards to <boost/spirit/home/karma/char/char_class.hpp>
    #include <boost/spirit/include/karma_char_class.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`ns::alnum`]]
    [[`ns::alpha`]]
    [[`ns::blank`]]
    [[`ns::cntrl`]]
    [[`ns::digit`]]
    [[`ns::graph`]]
    [[`ns::lower`]]
    [[`ns::print`]]
    [[`ns::punct`]]
    [[`ns::space`]]
    [[`ns::upper`]]
    [[`ns::xdigit`]]
]

In the table above, `ns` represents a __karma_char_encoding_namespace__ used by the 
corresponding character class generator. All listed generators have a mandatory 
attribute `Ch` and will not compile if no attribute is associated.


[heading Model of]

[:__primitive_generator_concept__]

[variablelist Notation
    [[`ns`]       [A __karma_char_encoding_namespace__.]]]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.

[table
    [[Expression]       [Semantics]]
    [[`ns::alnum`]      [If the mandatory attribute satisfies the concept of 
                         `std::isalnum` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::alpha`]      [If the mandatory attribute satisfies the concept of 
                         `std::isalpha` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::blank`]      [If the mandatory attribute satisfies the concept of 
                         `std::isblank` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::cntrl`]      [If the mandatory attribute satisfies the concept of 
                         `std::iscntrl` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::digit`]      [If the mandatory attribute satisfies the concept of 
                         `std::isdigit` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::graph`]      [If the mandatory attribute satisfies the concept of 
                         `std::isgraph` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::print`]      [If the mandatory attribute satisfies the concept of 
                         `std::isprint` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::punct`]      [If the mandatory attribute satisfies the concept of 
                         `std::ispunct` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::xdigit`]      [If the mandatory attribute satisfies the concept of 
                         `std::isxdigit` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::lower`]      [If the mandatory attribute satisfies the concept of 
                         `std::islower` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::upper`]      [If the mandatory attribute satisfies the concept of 
                         `std::isupper` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.]]
    [[`ns::space`]      [If the optional attribute satisfies the concept of 
                         `std::isspace` in the __karma_char_encoding_namespace__
                         the generator succeeds after emitting 
                         its attribute (unless the underlying output stream 
                         reports an error). This generator fails otherwise 
                         while not generating anything.If no attribute is 
                         supplied this generator emits a single space 
                         character in the character set defined by `ns`.]]
]

Possible values for `ns` are described in the section __karma_char_encoding_namespace__.

[note   The generators `alpha` and `alnum` might seem to behave unexpected if 
        used inside a `lower[]` or `upper[]` directive. Both directives 
        additionally apply the semantics of `std::islower` or `std::isupper`
        to the respective character class. Some examples:
``
    std::string s;
    std::back_insert_iterator<std::string> out(s);
    generate(out, lower[alpha], 'a');               // succeeds emitting 'a'
    generate(out, lower[alpha], 'A');               // fails 
``
        The generator directive `upper[]` behaves correspondingly.
]

[heading Attributes]

[:All listed character class generators can take any attribute `Ch`. All 
  character class generators (except `space`) require an attribute and will
  fail compiling otherwise.]

[note  In addition to their usual attribute of type `Ch` all listed generators 
       accept an instance of a `boost::optional<Ch>` as well. If the 
       `boost::optional<>` is initialized (holds a value) the generators behave 
       as if their attribute was an instance of `Ch` and emit the value stored
       in the `boost::optional<>`. Otherwise the generators will fail.]

[heading Complexity]

[:O(1)]

The complexity is constant as the generators emit not more than one character 
per invocation.

[heading Example]

[note The test harness for the example(s) below is presented in the
      __karma_basics_examples__ section.]

Some includes:

[reference_karma_includes]

Some using declarations:

[reference_karma_using_declarations_char_class]

Basic usage of an `alpha` generator:

[reference_karma_char_class]

[endsect]

[endsect]