Symbols Generator (symbols)

Symbols Generator (`symbols`)

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.

Header

// forwards to <boost/spirit/home/karma/string/symbols.hpp>
#include <boost/spirit/include/karma_symbols.hpp>

Also, see Include Structure.

Namespace

Name
`boost::spirit::karma::symbols`

Synopsis

template <typename Attrib, typename T, typename Lookup
  , typename CharEncoding, typename Tag>
struct symbols;

Template parameters

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`

Model of

PrimitiveGenerator

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.

Expression Semantics

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

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.

Attributes

The attribute of symbol<Attrib, T> is Attrib.

If the supplied attribute is a Boost.Fusion sequence, then the symbol table generator will use the first element of that Boost.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 Boost.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 (traits::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 traits::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 Boost.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 Boost.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')));

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.

Example

	Note
	The test harness for the example(s) below is presented in the Basics Examples section.

Some includes:

#include <boost/spirit/include/karma.hpp>
#include <boost/spirit/include/support_utree.hpp>
#include <boost/spirit/include/phoenix_core.hpp>
#include <boost/spirit/include/phoenix_operator.hpp>
#include <boost/fusion/include/std_pair.hpp>
#include <iostream>
#include <string>

Some using declarations:

using boost::spirit::karma::symbols;

Basic usage of symbol generators:

symbols<char, char const*> sym;

sym.add
    ('a', "Apple")
    ('b', "Banana")
    ('o', "Orange")
;

test_generator_attr("Banana", sym, 'b');