123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491 |
- [/==============================================================================
- Copyright (C) 2001-2011 Hartmut Kaiser
- Copyright (C) 2001-2011 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 Generators]
- 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 Generators (`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]
|