817 lines
26 KiB
Plaintext
817 lines
26 KiB
Plaintext
[/==============================================================================
|
|
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:operator Generator Operators]
|
|
|
|
Operators are used as a means for object composition and embedding.
|
|
Simple generators may be composed to form composites through operator
|
|
overloading, crafted to approximate the syntax of __peg__ (PEG). An
|
|
expression such as:
|
|
|
|
a | b
|
|
|
|
yields a new generator type which is a composite of its operands, `a` and
|
|
`b`.
|
|
|
|
This module includes different generators which get instantiated if one of the
|
|
overloaded operators is used with more primitive generator constructs. It
|
|
includes sequences (`a << b`), alternatives (`a | b`), Kleene star (unary `*`),
|
|
plus (unary `+`), optional (unary `-`), lists (`a % b`), and the two predicates, the
|
|
/and/ predicate (unary `&`) and the /not/ predicate (unary `!`).
|
|
|
|
[heading Module Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator.hpp>
|
|
#include <boost/spirit/include/karma_operator.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:sequence Sequence Generator (`a << b`)]
|
|
|
|
[heading Description]
|
|
|
|
Generator sequences are used to consecutively combine different, more primitive
|
|
generators. All generators in a sequence are invoked from left to right as long
|
|
as they succeed.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/sequence.hpp>
|
|
#include <boost/spirit/include/karma_sequence.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__nary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __nary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`a << b`] [The generators `a` and `b` are executed sequentially
|
|
from left to right and as long as they succeed. A
|
|
failed generator stops the execution of the entire
|
|
sequence and makes the sequence fail as well.]]
|
|
]
|
|
|
|
It is important to note, that sequences don't perform any buffering of the
|
|
output generated by its elements. That means that any failing sequence might
|
|
have already generated some output, which is /not/ rolled back.
|
|
|
|
[tip The simplest way to force a sequence to behave as if it did buffering
|
|
is to wrap it into a buffering directive (see __karma_buffer__):
|
|
|
|
``buffer[a << b << c]``
|
|
|
|
which will /not/ generate any output in case of a failing sequence.]
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`a << b` (sequence)]
|
|
[``a: A, b: B --> (a << b): tuple<A, B>
|
|
a: A, b: Unused --> (a << b): A
|
|
a: Unused, b: B --> (a << b): B
|
|
a: Unused, b: Unused --> (a << b): Unused
|
|
|
|
a: A, b: A --> (a << b): vector<A>
|
|
a: vector<A>, b: A --> (a << b): vector<A>
|
|
a: A, b: vector<A> --> (a << b): vector<A>
|
|
a: vector<A>, b: vector<A> --> (a << b): vector<A>``]]
|
|
]
|
|
|
|
[important The table above uses `tuple<A, B>` and `vector<A>` as placeholders
|
|
only.
|
|
|
|
The notation `tuple<A, B>` stands for /any fusion sequence of two
|
|
elements/, where `A` is the type of its first element and `B` is the
|
|
type of its second element.
|
|
|
|
The notation of `vector<A>` stands for /any STL container/ holding
|
|
elements of type `A`.]
|
|
|
|
The attribute composition and propagation rules as shown in the table above make
|
|
sequences somewhat special as they can operate in two modes if all elements have
|
|
the same attribute type: consuming fusion sequences and consuming STL
|
|
containers. The selected mode depends on the type of the attribute supplied.
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the sequence generator is defined by the sum of the
|
|
complexities of its elements. The complexity of the sequence itself is O(N),
|
|
where N is the number of elements in the sequence.]
|
|
|
|
[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_sequence]
|
|
|
|
Basic usage of a sequence:
|
|
|
|
[reference_karma_sequence]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:alternative Alternative Generator (`a | b`)]
|
|
|
|
[heading Description]
|
|
|
|
Generator alternatives are used to combine different, more primitive generators
|
|
into alternatives. All generators in an alternative are invoked from left to
|
|
right until one of them succeeds.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/alternative.hpp>
|
|
#include <boost/spirit/include/karma_alternative.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__nary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __nary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`a | b`] [The generators `a` and `b` are executed sequentially
|
|
from left to right until one of them succeeds. A
|
|
failed generator forces the alternative generator to
|
|
try the next one. The alternative fails as a whole
|
|
only if all elements of the alternative fail. Each
|
|
element of the alternative gets passed the whole
|
|
attribute of the alternative.]]
|
|
]
|
|
|
|
Alternatives intercept and buffer the output of the currently executed element.
|
|
This allows to avoid partial outputs from failing elements as the buffered
|
|
content will be forwarded to the actual output only after an element succeeded.
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`a | b` (alternative)]
|
|
[``a: A, b: B --> (a | b): variant<A, B>
|
|
a: A, b: Unused --> (a | b): A
|
|
a: Unused, b: B --> (a | b): B
|
|
a: Unused, b: Unused --> (a | b): Unused
|
|
a: A, b: A --> (a | b): A``]]
|
|
]
|
|
|
|
[important The table above uses `variant<A, B>` as a placeholder only. The
|
|
notation `variant<A, B>` stands for the type `boost::variant<A, B>`.
|
|
]
|
|
|
|
The attribute handling of Alternatives is special as their behavior is
|
|
not completely defined at compile time. First of all the selected alternative
|
|
element depends on the actual type of the attribute supplied to the alternative
|
|
generator (i.e. what is stored in the variant). The attribute type supplied at
|
|
/runtime/ narrows the set of considered alternatives to those being compatible
|
|
attribute wise. The remaining alternatives are tried sequentially until the
|
|
first of them succeeds. See below for an example of this behavior.
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the alternative generator is defined by the sum of
|
|
the complexities of its elements. The complexity of the alternative itself is
|
|
O(N), where N is the number of elements in the alternative.]
|
|
|
|
[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_alternative]
|
|
|
|
Basic usage of an alternative. While being only the second alternative, the
|
|
`double_` generator is chosen for output formatting because the supplied
|
|
attribute type is not compatible (i.e. not convertible) to the attribute type
|
|
of the `string` alternative.
|
|
|
|
[reference_karma_alternative1]
|
|
|
|
The same formatting rules may be used to output a string. This time we supply
|
|
the string `"example"`, resulting in the first alternative to be chosen for the
|
|
generated output.
|
|
|
|
[reference_karma_alternative2]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:kleene Kleene Star Generator (`*a`)]
|
|
|
|
[heading Description]
|
|
|
|
Kleene star generators are used to repeat the execution of an embedded generator
|
|
zero or more times. Regardless of the success of the embedded generator, the
|
|
Kleene star generator always succeeds.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/kleene.hpp>
|
|
#include <boost/spirit/include/karma_kleene.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__unary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __unary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`*a`] [The generator `a` is executed zero or more times
|
|
depending on the availability of an attribute. The
|
|
execution of `a` stops after the attribute values
|
|
passed to the Kleene star generator are exhausted.
|
|
The Kleene star always succeeds (unless the
|
|
underlying output stream reports an error).]]
|
|
]
|
|
|
|
[note All failing iterations of the embedded generator will consume one element
|
|
from the supplied attribute.]
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`*a` (Kleene star, unary `*`)]
|
|
[``a: A --> *a: vector<A>
|
|
a: Unused --> *a: Unused``]]
|
|
]
|
|
|
|
[important The table above uses `vector<A>` as a placeholder only. The notation
|
|
of `vector<A>` stands for /any STL container/ holding elements of
|
|
type `A`.]
|
|
|
|
The Kleene star generator will execute its embedded generator once for each
|
|
element in the provided container attribute as long as the embedded
|
|
generator succeeds. On each iteration it will pass the next consecutive element
|
|
from the container attribute to the embedded generator. Therefore the number of
|
|
iterations will not be larger than the number of elements in the container
|
|
passed as its attribute. An empty container will make the Kleene star
|
|
generate no output at all.
|
|
|
|
It is important to note, that the Kleene star does not perform any buffering
|
|
of the output generated by its embedded elements. That means that any failing
|
|
element generator might have already generated some output, which is /not/
|
|
rolled back.
|
|
|
|
[tip The simplest way to force a Kleene star to behave as if it did
|
|
buffering is to wrap it into a buffering directive (see
|
|
__karma_buffer__):
|
|
|
|
``buffer[*a]``
|
|
|
|
which will /not/ generate any output in case of a failing generator `*a`.
|
|
The expression:
|
|
|
|
``*(buffer[a])``
|
|
|
|
will not generate any partial output from a generator `a` if it fails
|
|
generating in the middle of its output. The overall expression will
|
|
still generate the output as produced by all successful invocations of
|
|
the generator `a`.]
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the Kleene star generator is defined by the
|
|
complexity of its embedded generator multiplied by the number of executed
|
|
iterations. The complexity of the Kleene star itself is O(N), where N is the
|
|
number of elements in the container passed as its attribute.]
|
|
|
|
[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_kleene]
|
|
|
|
Basic usage of a Kleene star generator:
|
|
|
|
[reference_karma_kleene]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:plus Plus Generator (`+a`)]
|
|
|
|
[heading Description]
|
|
|
|
The Plus generator is used to repeat the execution of an embedded generator
|
|
one or more times. It succeeds if the embedded generator has been successfully
|
|
executed at least once.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/plus.hpp>
|
|
#include <boost/spirit/include/karma_plus.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__unary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __unary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`+a`] [The generator `a` is executed one or more times
|
|
depending on the availability of an attribute. The
|
|
execution of `a` stops after the attribute values
|
|
passed to the plus generator are exhausted.
|
|
The plus generator succeeds as long as its embedded
|
|
generator has been successfully executed at least once
|
|
(unless the underlying output stream reports an
|
|
error).]]
|
|
]
|
|
|
|
[note All failing iterations of the embedded generator will consume one element
|
|
from the supplied attribute. The overall `+a` will succeed as long as at
|
|
least one invocation of the embedded generator will succeed (unless the
|
|
underlying output stream reports an error).]
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`+a` (unary `+`)]
|
|
[``a: A --> +a: vector<A>
|
|
a: Unused --> +a: Unused``]]
|
|
]
|
|
|
|
[important The table above uses `vector<A>` as a placeholder only. The notation
|
|
of `vector<A>` stands for /any STL container/ holding elements of
|
|
type `A`.]
|
|
|
|
The Plus generator will execute its embedded generator once for each
|
|
element in the provided container attribute as long as the embedded
|
|
generator succeeds. On each iteration it will pass the next consecutive element
|
|
from the container attribute to the embedded generator. Therefore the number of
|
|
iterations will not be larger than the number of elements in the container
|
|
passed as its attribute. An empty container will make the plus generator fail.
|
|
|
|
It is important to note, that the plus generator does not perform any buffering
|
|
of the output generated by its embedded elements. That means that any failing
|
|
element generator might have already generated some output, which is /not/
|
|
rolled back.
|
|
|
|
[tip The simplest way to force a plus generator to behave as if it did
|
|
buffering is to wrap it into a buffering directive (see
|
|
__karma_buffer__):
|
|
|
|
``buffer[+a]``
|
|
|
|
which will /not/ generate any output in case of a failing generator `+a`.
|
|
The expression:
|
|
|
|
``+(buffer[a])``
|
|
|
|
will not generate any partial output from a generator `a` if it fails
|
|
generating in the middle of its output. The overall expression will
|
|
still generate the output as produced by all successful invocations of
|
|
the generator `a`.]
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the plus generator is defined by the
|
|
complexity of its embedded generator multiplied by the number of executed
|
|
iterations. The complexity of the plus generator itself is O(N), where N is
|
|
the number of elements in the container passed as its attribute.]
|
|
|
|
[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_plus]
|
|
|
|
Basic usage of a plus generator:
|
|
|
|
[reference_karma_plus1]
|
|
|
|
A more sophisticated use case showing how to leverage the fact that plus is
|
|
failing for empty containers passed as its attribute:
|
|
|
|
[reference_karma_plus2]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:list List Generator (`a % b`)]
|
|
|
|
[heading Description]
|
|
|
|
The list generator is used to repeat the execution of an embedded generator
|
|
and intersperse it with the output of another generator one or more times.
|
|
It succeeds if the embedded generator has been successfully executed at least
|
|
once.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/list.hpp>
|
|
#include <boost/spirit/include/karma_list.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__binary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __binary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`a % b`] [The generator `a` is executed one or more times
|
|
depending on the availability of an attribute. The
|
|
output generated by `a` is interspersed with the output
|
|
generated by `b`. The list generator succeeds if
|
|
its first embedded generator has been
|
|
successfully executed at least once (unless the
|
|
underlying output stream reports an error).]]
|
|
]
|
|
|
|
The list expression `a % b` is a shortcut for `a << *(b << a)`. It is almost
|
|
semantically equivalent, except for the attribute of `b`, which gets ignored
|
|
in the case of the list generator.
|
|
|
|
[note All failing iterations of the embedded generator will consume one element
|
|
from the supplied attribute. The overall `a % b` will succeed as long as at
|
|
least one invocation of the embedded generator, `a`, will succeed (unless
|
|
the underlying output stream reports an error).]
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`a % b` (list)]
|
|
[``a: A, b: B --> (a % b): vector<A>
|
|
a: Unused, b: B --> (a % b): Unused``]]
|
|
]
|
|
|
|
[important The table above uses `vector<A>` as a placeholder only. The notation
|
|
of `vector<A>` stands for /any STL container/ holding elements of
|
|
type `A`.]
|
|
|
|
The list generator will execute its embedded generator once for each
|
|
element in the provided container attribute and as long as the embedded
|
|
generator succeeds. The output generated by its first generator will be
|
|
interspersed by the output generated by the second generator. On each iteration
|
|
it will pass the next consecutive element from the container attribute to the
|
|
first embedded generator. The second embedded generator does not get passed
|
|
any attributes (it gets invoked using an `unused_type` as its attribute).
|
|
Therefore the number of iterations will not be larger than the number of
|
|
elements in the container passed as its attribute. An empty container will make
|
|
the list generator fail.
|
|
|
|
[tip If you want to use the list generator and still allow for an empty
|
|
attribute, you can use the optional operator (see __karma_optional__):
|
|
|
|
``-(a % b)``
|
|
|
|
which will succeed even if the provided container attribute does not
|
|
contain any elements.
|
|
]
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the list generator is defined by the
|
|
complexity of its embedded generators multiplied by the number of executed
|
|
iterations. The complexity of the list generator itself is O(N), where N is
|
|
the number of elements in the container passed as its attribute.]
|
|
|
|
[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_list]
|
|
|
|
Basic usage of a list generator:
|
|
|
|
[reference_karma_list]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:optional Optional Generator (`-a`)]
|
|
|
|
[heading Description]
|
|
|
|
The optional generator is used to conditionally execute an embedded generator.
|
|
It succeeds always.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/optional.hpp>
|
|
#include <boost/spirit/include/karma_optional.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__unary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __unary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`-a`] [The generator `a` is executed depending on the
|
|
availability of an attribute. The optional generator
|
|
succeeds if its embedded generator succeeds
|
|
(unless the underlying output stream reports an
|
|
error).]]
|
|
]
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`-a` (optional, unary `-`)]
|
|
[``a: A --> -a: optional<A>
|
|
a: Unused --> -a: Unused``]]
|
|
]
|
|
|
|
[important The table above uses `optional<A>` as a placeholder only. The
|
|
notation of `optional<A>` stands for the data type
|
|
`boost::optional<A>`.]
|
|
|
|
The optional generator will execute its embedded generator once if the provided
|
|
attribute holds a valid value. It forwards the value held in its attribute
|
|
to the embedded generator.
|
|
|
|
It is important to note, that the optional generator does not perform any
|
|
buffering of the output generated by its embedded elements. That means that any
|
|
failing element might have already generated some output, which is /not/
|
|
rolled back.
|
|
|
|
[tip The simplest way to force a optional generator to behave as if it did
|
|
buffering is to wrap it into a buffering directive (see
|
|
__karma_buffer__):
|
|
|
|
``buffer[-a]``
|
|
|
|
which will /not/ generate any output in case of a failing generator `-a`.
|
|
]
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the optional generator is defined by the
|
|
complexity of its embedded generator. The complexity of the optional
|
|
generator itself is O(1).]
|
|
|
|
[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_optional]
|
|
|
|
Basic usage of an optional generator:
|
|
|
|
[reference_karma_optional1]
|
|
|
|
Usage and result of an empty optional generator:
|
|
|
|
[reference_karma_optional2]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:and_predicate And-Predicate Generator (`&a`)]
|
|
|
|
[heading Description]
|
|
|
|
The and-predicate generator is used to test, whether the embedded generator
|
|
succeeds without generating any output. It succeeds if the embedded generator
|
|
succeeds.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/and_predicate.hpp>
|
|
#include <boost/spirit/include/karma_and_predicate.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__unary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __unary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`&a`] [The generator `a` is executed for the sole purpose of
|
|
testing whether it succeeds. The and-predicate
|
|
generator succeeds if its embedded generator
|
|
succeeds (unless the underlying output stream
|
|
reports an error). The and-predicate never produces
|
|
any output.]]
|
|
]
|
|
|
|
The and generator is implemented by redirecting all output produced by its
|
|
embedded generator into a discarding device.
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`&a` (and-predicate, unary `&`)] [`a: A --> &a: A`]]
|
|
]
|
|
|
|
[note The attribute of the and-predicate is not always `unused_type`, which is
|
|
different from Qi's and-predicate. This is necessary as the generator the
|
|
and predicate is attached to most of the time needs an attribute.
|
|
]
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the and-predicate generator is defined by the
|
|
complexity of its embedded generator. The complexity of the and-predicate
|
|
generator itself is O(1).]
|
|
|
|
[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_and_predicate]
|
|
|
|
Basic usage of an and predicate generator:
|
|
|
|
[reference_karma_and_predicate]
|
|
|
|
[endsect]
|
|
|
|
[/////////////////////////////////////////////////////////////////////////////]
|
|
[section:not_predicate Not-Predicate Generator (`!a`)]
|
|
|
|
[heading Description]
|
|
|
|
The not-predicate generator is used to test, whether the embedded generator
|
|
fails, without generating any output. It succeeds if the embedded generator
|
|
fails.
|
|
|
|
[heading Header]
|
|
|
|
// forwards to <boost/spirit/home/karma/operator/not_predicate.hpp>
|
|
#include <boost/spirit/include/karma_not_predicate.hpp>
|
|
|
|
Also, see __include_structure__.
|
|
|
|
[heading Model of]
|
|
|
|
[:__unary_generator_concept__]
|
|
|
|
[heading Expression Semantics]
|
|
|
|
Semantics of an expression is defined only where it differs from, or is not
|
|
defined in __unary_generator_concept__.
|
|
|
|
[table
|
|
[[Expression] [Semantics]]
|
|
[[`!a`] [The generator `a` is executed for the sole purpose of
|
|
testing whether it succeeds. The not-predicate
|
|
generator succeeds if its embedded generator
|
|
fails (unless the underlying output stream
|
|
reports an error). The not-predicate never produces
|
|
any output.]]
|
|
]
|
|
|
|
The not generator is implemented by redirecting all output produced by its
|
|
embedded generator into a discarding device.
|
|
|
|
[heading Attributes]
|
|
|
|
See __karma_comp_attr_notation__.
|
|
|
|
[table
|
|
[[Expression] [Attribute]]
|
|
[[`!a` (not-predicate, unary `!`)] [`a: A --> !a: A`]]
|
|
]
|
|
|
|
[note The attribute of the not-predicate is not always `unused_type`, which is
|
|
different from Qi's not-predicate. This is necessary as the generator the
|
|
and-predicate is attached to most of the time needs an attribute.
|
|
]
|
|
|
|
[heading Complexity]
|
|
|
|
[:The overall complexity of the not-predicate generator is defined by the
|
|
complexity of its embedded generator. The complexity of the not-predicate
|
|
generator itself is O(1).]
|
|
|
|
[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_not_predicate]
|
|
|
|
Basic usage of a not predicate generator:
|
|
|
|
[reference_karma_not_predicate]
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|