libs/spirit/doc/karma/string.qbk
[/==============================================================================
Copyright (C) 2001-2011 Joel de Guzman
Copyright (C) 2001-2011 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:string String Generators]
This module includes different string oriented generators allowing to output
character sequences. It includes the `symbols` generator and variants of the
`string` generator.
[heading Module Header]
// forwards to <boost/spirit/home/karma/string.hpp>
#include <boost/spirit/include/karma_string.hpp>
Also, see __include_structure__.
[section:string String Generators (`string`, `lit`)]
[heading Description]
The string generators described in this section are:
The `string` generator emits a string of characters. The `string` generator
is implicitly verbatim: the `delimit` parser is not applied in between
characters of the string. The `string` generator has an associated
__karma_char_encoding_namespace__. This is needed when doing basic operations
such as forcing lower or upper case. Examples:
string("Hello")
string(L"Hello")
string(s) // s is a std::string
`lit`, like `string`, also emits a string of characters. The main
difference is that `lit` does not consumes an attribute. A plain
string like `"hello"` or a `std::basic_string` is equivalent to a `lit`.
Examples:
"Hello"
lit("Hello")
lit(L"Hello")
lit(s) // s is a std::string
[heading Header]
// forwards to <boost/spirit/home/karma/string/lit.hpp>
#include <boost/spirit/include/karma_string.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lit // alias: boost::spirit::karma::lit`]]
[[`ns::string`]]
]
In the table above, `ns` represents a __karma_char_encoding_namespace__ used by the
corresponding string generator.
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`s`] [Character-class specific string (See __char_class_types__),
or a __karma_lazy_argument__ that evaluates to a
character-class specific string value]]
[[`S`] [The type of a character-class specific string `s`.]]
[[`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] [Description]]
[[`s`] [Generate the string literal `s`. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`lit(s)`] [Generate the string literal `s`. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`ns::string`] [Generate the string 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::string(s)`] [Generate the string `s` as provided by the
immediate literal value the generator is initialized
from. If this generator has an associated attribute
it succeeds only if 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.]]
]
[note The generators `lit(s)` and `string(s)` can be initialized either
using a string literal value (i.e. `"abc"`), or using a
`std::basic_string<char_type, ...>`, where `char_type` is the required
value type of the underlying character sequence.]
[caution The generator `string(s)` up to version 2.4.1 of Spirit has an
undocumented feature. Given argument `s` generator succeeds as long as
`s` is a prefix of given attribute. This problem has been fixed in
Spirit V2.4.2.]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`s`] [__unused__]]
[[`lit(s)`] [__unused__]]
[[`ns::string`] [`S`, attribute is mandatory (otherwise compilation
will fail)]]
[[`ns::string(s)`] [`S`, attribute is optional, if it is supplied, the
generator compares the attribute with `s` and
succeeds only if both are equal, failing otherwise]]
]
[note In addition to their usual attribute of type `S` all listed generators
accept an instance of a `boost::optional<S>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `S` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:O(N), where N is the number of characters emitted by the string generator]
[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_string]
Basic usage of `string` generators:
[reference_karma_string]
[endsect]
[/------------------------------------------------------------------------------]
[section:symbols Symbols Generator (`symbols`)]
[heading Description]
The class `symbols` implements an 'inverse' symbol table: an associative
container (or map) of key-value pairs where the values are (most of the time)
strings. It maps the value to be generated (the key) to any other value which
will be emitted instead of the original key.
The Karma symbol table class `symbols` is-a generator, an instance of which may
be used anywhere in the grammar specification. It is an example of a
dynamic generator. A dynamic generator is characterized by its ability to
modify its behavior at run time. Initially, an empty symbols object
will emit nothing. At any time, symbols may be added, thus, dynamically
altering its behavior.
[heading Header]
// forwards to <boost/spirit/home/karma/string/symbols.hpp>
#include <boost/spirit/include/karma_symbols.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::symbols`]]
]
[heading Synopsis]
template <typename Attrib, typename T, typename Lookup
, typename CharEncoding, typename Tag>
struct symbols;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`Attrib`] [The type of the original attribute to be used as
the key into the symbol generator (the symbol).] [`char`]]
[[`T`] [The data type associated
with each key.] [__unused_type__]]
[[`Lookup`] [The symbol search implementation]
[if T is `unused_type`, `std::set<Attrib>`,
and `std::map<Attrib, T>` otherwise]]
[[`CharEncoding`] [Used for character set selection, normally not
used by end user.] [__unused_type__]]
[[`Tag`] [Used for character set selection, normally not
used by end user.] [__unused_type__]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`Sym`] [A `symbols` type.]]
[[`Attrib`] [An attribute type.]]
[[`T`] [A data type.]]
[[`sym`, `sym2`][`symbols` objects.]]
[[`sseq`] [An __stl__ container of strings.]]
[[`dseq`] [An __stl__ container of data with `value_type` `T`.]]
[[`s1`...`sN`] [A __string__.]]
[[`d1`...`dN`] [Objects of type `T`.]]
[[`f`] [A callable function or function object.]]
[[`f`, `l`] [`ForwardIterator` first/last pair.]]
]
[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]]
[[`Sym()`] [Construct an empty symbols object instance named `"symbols"`.]]
[[`Sym(name)`] [Construct an empty symbols object instance named `name`.]]
[[`Sym(sym2)`] [Copy construct a symbols from `sym2` (Another `symbols` object).]]
[[`Sym(sseq)`] [Construct symbols from `sseq` (An __stl__ container of
symbols of type `Attrib`) named `"symbols"`.]]
[[`Sym(sseq, name)`] [Construct symbols from `sseq` (an __stl__ container of
symbols of type `Attrib`) named `name`.]]
[[`Sym(sseq, dseq)`] [Construct symbols from `sseq` and `dseq`
(An __stl__ container of symbols of type `Attrib` and an
__stl__ container of data with `value_type` `T`)
which is named `"symbols"`.]]
[[`Sym(sseq, dseq, name)`] [Construct symbols from `sseq` and `dseq`
(An __stl__ container of symbols of type `Attrib` and an
__stl__ container of data with `value_type` `T`)
which is named `name`.]]
[[`sym = sym2`] [Assign `sym2` to `sym`.]]
[[`sym = s1, s2, ..., sN`] [Assign one or more symbols (`s1`...`sN`) to `sym`. The
associated data values of type `T` are default constructed.]]
[[`sym += s1, s2, ..., sN`] [Add one or more symbols (`s1`...`sN`) to `sym`. The
associated data values of type `T` are default constructed.]]
[[`sym.add(s1)(s2)...(sN)`] [Add one or more symbols (`s1`...`sN`) to `sym`. The
associated data values of type `T` are default constructed.]]
[[`sym.add(s1, d1)(s2, d2)...(sN, dN)`]
[Add one or more symbols (`s1`...`sN`)
with associated data (`d1`...`dN`) to `sym`.]]
[[`sym -= s1, s2, ..., sN`] [Remove one or more symbols (`s1`...`sN`) from `sym`.]]
[[`sym.remove(s1)(s2)...(sN)`] [Remove one or more symbols (`s1`...`sN`) from `sym`.]]
[[`sym.clear()`] [Erase all of the symbols in `sym`.]]
[[`sym.at(s)`] [Return a reference to the object associated
with symbol, `s`. If `sym` does not already
contain such an object, `at` inserts the default
object `T()`.]]
[[`sym.find(s)`] [Return a pointer to the object associated
with symbol, `s`. If `sym` does not already
contain such an object, `find` returns a null
pointer.]]
[[`sym.for_each(f)`] [For each symbol in `sym` `s` invoke
`f(typename Lookup::value_type)`.]]
[[`sym.name()`] [Retrieve the current name of the symbols object.]]
[[`sym.name(name)`] [Set the current name of the symbols object to be `name`.]]
]
The symbols generator uses the supplied attribute as the key to be looked up
in the internal associative container. If the key exists the generator emits
the associated value and succeeds (unless the underlying output stream reports
an error). If the value type stored in the symbol generator is __unused_type__
it will emit the key instead. If the key does not exist the generator fails
while not emitting anything.
[heading Attributes]
The attribute of `symbol<Attrib, T>` is `Attrib`.
If the supplied attribute is a __fusion__ sequence, then the symbol table
generator will use the first element of that __fusion__ sequence as the key
to be used for lookup. The type of that first element needs to be convertible
to `Attrib`. In this case the second element of the __fusion__ sequence is used
as the attribute while calling a generator derived from the value stored in the
symbol table for the found entry.
If the supplied attribute is a container type (__customize_is_container__
resolves to `mpl::true_`), then the symbol table generator will use the first
element stored in that container as the key to be used for lookup. The
`value_type` (returned by __customize_container_value__) has to be convertible
to `Attrib`. In this case the second element stored in that container is used
as the attribute while calling a generator derived from the value stored in the
symbol table for the found entry.
If the supplied attribute is not a __fusion__ sequence and not a container
type, the supplied attribute is directly used as the key for item lookup. The
attribute is used as the attribute while calling a generator derived from the
value stored in the symbol table for the found entry.
In any case, because the supplied key (i.e. either the first element of the
__fusion__ sequence, the first container element, or the attribute otherwise)
is passed as the attribute to a generator derived from the value
stored in the symbol table for the found entry, the symbol table may store
generators, which will produce output based on that value. For instance:
// The symbol table maps a single character key to a rule<>
// The rule<> exposes an attribute of char as well
rule<output_iterator_type, char()> r1 = char_;
symbols<char, rule<output_iterator_type, char()> > sym;
sym.add
('j', r1.alias())
('h', r1.alias())
('t', r1.alias())
('k', r1.alias())
;
// Supplying a fusion vector as the attribute will use the first element
// (the 'j') as the key to be looked up, while the second element (the 'J')
// is passed on as the attribute to the rule<> stored in the symbol table.
// Consequently, the example generates a single 'J'.
BOOST_ASSERT(test("J", sym, make_vector('j', 'J')));
[heading Complexity]
The default implementation uses a `std::map<>` or a `std::set<>` with a
complexity of:
[:O(log n)]
Where n is the number of stored symbols.
[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_symbols]
Basic usage of `symbol` generators:
[reference_karma_symbols]
[endsect] [/ symbols]
[endsect]
