libs/spirit/doc/karma/directive.qbk
[/==============================================================================
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:directive Generator Directives]
This module includes different generator directives. It includes alignment
directives (`left_align[]`, `center[]`, and `right_align[]`), repetition
(`repeat[]`), directives controlling automatic delimiting (`verbatim[]`,
`no_delimit[]`, and `delimit[]`), controlling case sensitivity (`upper[]` and
`lower[]`), field width (`maxwidth[]`), buffering (`buffer[]`), splitting into
columns (`columns[]`) and attribute handling (`duplicate[]`, `omit[]`, and
`skip[]`).
[heading Module Header]
// forwards to <boost/spirit/home/karma/directive.hpp>
#include <boost/spirit/include/karma_directive.hpp>
Also, see __include_structure__.
[/////////////////////////////////////////////////////////////////////////////]
[section:alignment Alignment Generator Directives (`left_align[]`, `center[]`, `right_align[]`)]
[heading Description]
The alignment directives allow to left align, right align or center output
emitted by other generators into columns of a specified width while using
an arbitrary generator to create the padding.
[heading Header]
For the `left_align[]` directive:
// forwards to <boost/spirit/home/karma/directive/left_alignment.hpp>
#include <boost/spirit/include/karma_left_alignment.hpp>
For the `center[]` directive:
// forwards to <boost/spirit/home/karma/directive/center_alignment.hpp>
#include <boost/spirit/include/karma_center_alignment.hpp>
For the `right_align[]` directive:
// forwards to <boost/spirit/home/karma/directive/right_alignment.hpp>
#include <boost/spirit/include/karma_right_alignment.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::left_align // alias: boost::spirit::karma::left_align` ]]
[[`boost::spirit::center // alias: boost::spirit::karma::center` ]]
[[`boost::spirit::right_align // alias: boost::spirit::karma::right_align` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`pad`] [A generator object, or a __karma_lazy_argument__ that
evaluates to a generator object]]
[[`A`, `Pad`] [Attribute types of the generators `a` and `pad`]]
[[`width`] [Numeric literal, any unsigned integer value, or
a __karma_lazy_argument__ that evaluates to an unsigned
integer value]]]
[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]]
[[`left_align[a]`] [Generate `a` left aligned in a column of
width as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`
(default: 10), while using `space` to emit
the necessary padding. This generator succeeds as
long as its embedded generator `a` does not
fail (unless the underlying output stream
reports an error).]]
[[`left_align(width)[a]`] [Generate `a` left aligned in a column of
the given `width`, while using `space` to emit
the necessary padding. This generator succeeds as
long as its embedded generator `a` does not
fail (unless the underlying output stream
reports an error).]]
[[`left_align(pad)[a]`] [Generate `a` left aligned in a column of
width as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`
(default: 10), while using the generator `pad`
to emit the necessary padding. This generator
succeeds as long as its embedded and padding
generators `a` and `pad` do not fail (except
if the underlying output stream reports an
error).]]
[[`left_align(width, pad)[a]`] [Generate `a` left aligned in a column of
the given `width`, while using the generator
`pad` to emit the necessary padding. This
generator succeeds as long as its embedded
and padding generators `a` and `pad` do not
fail (unless the underlying output stream
reports an error).]]
[[`center[a]`] [Generate `a` centered in a column of
width as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`
(default: 10), while using `space` to emit
the necessary padding. This generator succeeds as
long as its embedded generator `a` does not
fail (unless the underlying output stream
reports an error).]]
[[`center(width)[a]`] [Generate `a` centered in a column of
the given `width`, while using `space` to emit
the necessary padding. This generator succeeds as
long as its embedded generator `a` does not
fail (unless the underlying output stream
reports an error).]]
[[`center(pad)[a]`] [Generate `a` centered in a column of
width as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`
(default: 10), while using the generator `pad`
to emit the necessary padding. This generator
succeeds as long as its embedded and padding
generators `a` and `pad` do not fail (except
if the underlying output stream reports an
error).]]
[[`center(width, pad)[a]`] [Generate `a` centered in a column of
the given `width`, while using the generator
`pad` to emit the necessary padding. This
generator succeeds as long as its embedded
and padding generators `a` and `pad` do not
fail (unless the underlying output stream
reports an error).]]
[[`right_align[a]`] [Generate `a` right aligned in a column of
width as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`
(default: 10), while using `space` to emit
the necessary padding. This generator succeeds as
long as its embedded generator `a` does not
fail (unless the underlying output stream
reports an error).]]
[[`right_align(width)[a]`] [Generate `a` right aligned in a column of
the given `width`, while using `space` to emit
the necessary padding. This generator succeeds as
long as its embedded generator `a` does not
fail (unless the underlying output stream
reports an error).]]
[[`right_align(pad)[a]`] [Generate `a` right aligned in a column of
width as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`
(default: 10), while using the generator `pad`
to emit the necessary padding. This generator
succeeds as long as its embedded and padding
generators `a` and `pad` do not fail (except
if the underlying output stream reports an
error).]]
[[`right_align(width, pad)[a]`] [Generate `a` right aligned in a column of
the given `width`, while using the generator
`pad` to emit the necessary padding. This
generator succeeds as long as its embedded
and padding generators `a` and `pad` do not
fail (unless the underlying output stream
reports an error).]]
]
[note None of the generator directives listed above limits the emitted output
to the respective column width. If the emitted output is longer than
the specified (or implied) column width, the generated output overruns
the column to the right.
If the output needs to be limited to a specified column width, use the
`maxwidth[]` directive, for instance:
``
maxwidth(8)[right_align(12)["1234567890"]]
``
which will output (without the quotes): ``" 123456"``
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`left_align[]`]
[``a: A --> left_align[a]: A
a: Unused --> left_align[a]: Unused``]]
[[`left_align(width)[]`]
[``a: A --> left_align(width)[a]: A
a: Unused --> left_align(width)[a]: Unused``]]
[[`left_align(pad)[]`]
[``a: A, pad: Pad --> left_align(pad)[a]: A
a: Unused, pad: Pad --> left_align(pad)[a]: Unused``]]
[[`left_align(pad, width)[]`]
[``a: A, pad: Pad --> left_align(pad, width)[a]: A
a: Unused, pad: Pad --> left_align(pad, width)[a]: Unused``]]
[[`center[]`]
[``a: A --> center[a]: A
a: Unused --> center[a]: Unused``]]
[[`center(width)[]`]
[``a: A --> center(width)[a]: A
a: Unused --> center(width)[a]: Unused``]]
[[`center(pad)[]`]
[``a: A, pad: Pad --> center(pad)[a]: A
a: Unused, pad: Pad --> center(pad)[a]: Unused``]]
[[`center(pad, width)[]`]
[``a: A, pad: Pad --> center(pad, width)[a]: A
a: Unused, pad: Pad --> center(pad, width)[a]: Unused``]]
[[`right_align[]`]
[``a: A --> right_align[a]: A
a: Unused --> right_align[a]: Unused``]]
[[`right_align(width)[]`]
[``a: A --> right_align(width)[a]: A
a: Unused --> right_align(width)[a]: Unused``]]
[[`right_align(pad)[]`]
[``a: A, pad: Pad --> right_align(pad)[a]: A
a: Unused, pad: Pad --> right_align(pad)[a]: Unused``]]
[[`right_align(pad, width)[]`]
[``a: A, pad: Pad --> right_align(pad, width)[a]: A
a: Unused, pad: Pad --> right_align(pad, width)[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of an alignment generator directive is defined by
the complexity of its embedded and padding generator. The complexity of the
left alignment directive generator itself is O(1). The complexity of the
center and right alignment directive generators is O(N), where `N` is the
number of characters emitted by the embedded and padding generators.]
[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_alignment]
Basic usage of the alignment generators:
[reference_karma_alignment]
[endsect] [/ alignment]
[/////////////////////////////////////////////////////////////////////////////]
[section:repeat Repetition Generator Directive (`repeat[]`)]
[heading Description]
The repetition directive allows to repeat an arbitrary generator expression
while optionally specifying the lower and upper repetition counts. It provides
a more powerful and flexible mechanism for repeating a generator. There are
grammars that are impractical and cumbersome, if not impossible, for the basic
EBNF iteration syntax ([karma_kleene unary `'*'`] and the [karma_plus unary `'+'`])
to specify. Examples:
* A file name may have a maximum of 255 characters only.
* A specific bitmap file format has exactly 4096 RGB color information.
* A 256 bit binary string (1..256 1s or 0s).
[heading Header]
// forwards to <boost/spirit/home/karma/directive/repeat.hpp>
#include <boost/spirit/include/karma_repeat.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::repeat // alias: boost::spirit::karma::repeat` ]]
[[`boost::spirit::inf // alias: boost::spirit::karma::inf` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`num, num1, num2`][Numeric literals, any unsigned integer value, or
a __karma_lazy_argument__ that evaluates to an
unsigned integer value]]
[[`inf`] [Placeholder expression standing for 'no upper repeat
limit']]
]
[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]]
[[`repeat[a]`] [Repeat the generator `a` zero or more times.
This generator succeeds as long as its
embedded generator `a` does not fail (except
if the underlying output stream reports an
error). This variant of `repeat[]` is
semantically equivalent to the
[karma_kleene Kleene Star operator `*a`]]]
[[`repeat(num)[a]`] [Repeat the generator `a` exactly `num`
times. This generator succeeds as long as its
embedded generator `a` does not fail and
as long as the associated attribute
(container) contains at least `num` elements
(unless the underlying output stream
reports an error).]]
[[`repeat(num1, num2)[a]`] [Repeat the generator `a` at least `num1`
times but not more than `num2` times. This
generator succeeds as long as its
embedded generator `a` does not fail and
as long as the associated attribute
(container) contains at least `num1` elements
(unless the underlying output stream
reports an error). If the associated
attribute (container) does contain more
than `num2` elements, this directive
limits the repeat count to `num2`. ]]
[[`repeat(num, inf)[a]`] [Repeat the generator `a` at least `num1`
times. No upper limit for the repeat count
is set. This generator succeeds as long as
its embedded generator `a` does not fail
and as long as the associated attribute
(container) contains at least `num` elements
(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 `repeat[a]` will succeed as long
as the iteration criteria (number of successful invocations of the
embedded generator) is fulfilled (unless the underlying output stream
reports an error).]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`repeat[a]`]
[``a: A --> repeat[a]: vector<A>
a: Unused --> repeat[a]: Unused``]]
[[`repeat(num)[a]`]
[``a: A --> repeat(num)[a]: vector<A>
a: Unused --> repeat(num)[a]: Unused``]]
[[`repeat(num1, num2)[a]`]
[``a: A --> repeat(num1, num2)[a]: vector<A>
a: Unused --> repeat(num1, num2)[a]: Unused``]]
[[`repeat(num, inf)[a]`]
[``a: A --> repeat(num, inf)[a]: vector<A>
a: Unused --> repeat(num, inf)[a]: Unused``]]
]
[important The table above uses `vector<A>` as placeholders only.
The notation of `vector<A>` stands for /any STL container/ holding
elements of type `A`.]
It is important to note, that the `repeat[]` directive 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 `repeat[]` directive to behave as if it did
buffering is to wrap it into a buffering directive (see
__karma_buffer__):
``buffer[repeat[a]]``
which will /not/ generate any output in case of a failing generator
`repeat[a]`. The expression:
``repeat[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 succeeded invocations of
the generator `a`.]
[heading Complexity]
[:The overall complexity of the repetition generator is defined by the
complexity of its embedded generator. The complexity of the repeat itself is
O(N), where N is the number of repetitions to execute.]
[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_repeat]
Basic usage of `repeat` generator directive:
[reference_karma_repeat]
[endsect] [/ repeat]
[/////////////////////////////////////////////////////////////////////////////]
[section:delimit Generator Directives Controlling Automatic Delimiting (`verbatim[]`, `no_delimit[]`, `delimit[]`)]
[heading Description]
The directives `delimit[]`, `no_delimit[]`, and `verbatim[]` can be used to
control automatic delimiting. The directives `verbatim[]` and `no_delimit[]`
disable any automatic delimiting, while the directive `delimit[]` (re-)enables
automatic delimiting.
[heading Header]
For the `verbatim[]` directive:
// forwards to <boost/spirit/home/karma/directive/verbatim.hpp>
#include <boost/spirit/include/karma_verbatim.hpp>
For the `no_delimit[]` directive:
// forwards to <boost/spirit/home/karma/directive/no_delimit.hpp>
#include <boost/spirit/include/karma_no_delimit.hpp>
For the `delimit[]` directive:
// forwards to <boost/spirit/home/karma/directive/delimit.hpp>
#include <boost/spirit/include/karma_delimit.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::verbatim // alias: boost::spirit::karma::verbatim` ]]
[[`boost::spirit::no_delimit // alias: boost::spirit::karma::no_delimit` ]]
[[`boost::spirit::delimit // alias: boost::spirit::karma::delimit` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`d`] [A generator object, or a __karma_lazy_argument__ that
evaluates to a generator object]]
[[`A`, `D`] [Attribute types of the generators `a` and `d`]]]
[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]]
[[`delimit[a]`] [Enable automatic delimiting for the embedded generator
`a` while using the `space` generator as the
delimiting generator. If used inside a `verbatim[]`
directive it re-enables the delimiter generator as used
outside of this `verbatim[]` instead. The directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error).]]
[[`delimit(d)[a]`] [Enable automatic delimiting for the embedded generator
`a` while using the generator `d` as the
delimiting generator. The directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error).]]
[[`verbatim[a]`] [Disable automatic delimiting for the embedded generator
`a`. The directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error). This
directive it has no effect if it is used when no
delimiting is active. When delimiting is active this
directive performs a post-delimit step (which is
different from the behavior of `no_delimit[]`).]]
[[`no_delimit[a]`] [Disable automatic delimiting for the embedded generator
`a`. The directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error). This
directive it has no effect if it is used when no
delimiting is active. When delimiting is active this
directive does not perform a post-delimit step (which is
different from the behavior of `verbatim[]`.]]
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`delimit[a]`]
[``a: A --> delimit[a]: A
a: Unused --> delimit[a]: Unused``]]
[[`delimit(d)[a]`]
[``a: A, d: D --> delimit(d)[a]: A
a: Unused, d: D --> delimit(d)[a]: Unused``]]
[[`verbatim[a]`]
[``a: A --> verbatim[a]: A
a: Unused --> verbatim[a]: Unused``]]
[[`no_delimit[a]`]
[``a: A --> no_delimit[a]: A
a: Unused --> no_delimit[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of the generator directives `delimit[]`, `verbatim[]`,
and `no_delimit[]` is defined by the complexity of its embedded generators.
The complexity of the directives themselves 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_simple]
Some using declarations:
[reference_karma_using_declarations_delimit]
Basic usage of `delimit` generator directive:
[reference_karma_delimit]
[endsect] [/ verbatim/delimit/no_delimit]
[/////////////////////////////////////////////////////////////////////////////]
[section:upperlower Generator Directives Controlling Case Sensitivity (`upper[]`, `lower[]`)]
[heading Description]
The generator directives `ns::lower[]` and `ns::upper[]` force their embedded
generators to emit lower case or upper case only characters based on the
interpretation of the generated characters in the character set defined by
`ns` (see __karma_char_encoding_namespace__).
[heading Header]
// forwards to <boost/spirit/home/karma/directive/upper_lower_case.hpp>
#include <boost/spirit/include/karma_upper_lower_case.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`ns::lower`]]
[[`ns::upper`]]
]
In the table above, `ns` represents a __karma_char_encoding_namespace__.
[heading Model of]
[:The model of `lower[]` and `upper[]` is the model of its subject generator.]
[variablelist Notation
[[`a`] [A generator object]]
[[`A`] [Attribute type of the generator `a`]]
[[`ns`] [A __karma_char_encoding_namespace__.]]]
[heading Expression Semantics]
The `lower[]` and `upper[]` directives have no special generator semantics.
They are pure modifier directives. They indirectly influence the way all
subject generators work. They add information (the `tag::upper` or `tag::lower`)
to the `Modifier` template parameter used while transforming the `proto::expr`
into the corresponding generator expression. This is achieved by the
following specializations:
namespace boost { namespace spirit
{
template <typename CharEncoding>
struct is_modifier_directive<
karma::domain
, tag::char_code<tag::lower, CharEncoding> >
: mpl::true_
{};
template <typename CharEncoding>
struct is_modifier_directive<
karma::domain
, tag::char_code<tag::upper, CharEncoding> >
: mpl::true_
}}
(for more details see the section describing the compilation process of the
__boost_proto__ expression into the corresponding generator expressions).
[table
[[Expression] [Semantics]]
[[`ns::lower[a]`] [Generate `a` as lower case, interpreted in the
character set defined by `ns`. The directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error).]]
[[`ns::upper[a]`] [Generate `a` as upper case, interpreted in the
character set defined by `ns`. The directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error).]]
]
[note If both directives are 'active' with regard to a generator, the
innermost of those directives takes precedence. For instance:
``
generate(sink, ascii::lower['A' << ascii::upper['b']])
``
will generate `"aB"` (without the quotes).
Further, the directives will have no effect on generators emitting
characters not having an upper case or lower case equivalent in the
character set defined by `ns`.
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`ns:lower[a]`]
[``a: A --> ns:lower[a]: A
a: Unused --> ns:lower[a]: Unused``]]
[[`ns:upper[a]`]
[``a: A --> ns:upper[a]: A
a: Unused --> ns:upper[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of the generator directives `ns::lower[]` and `ns::upper[]`
is defined by the complexity of its embedded generators. The directives
themselves are compile time only directives, having no impact on runtime
performance.]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes_simple]
Some using declarations:
[reference_karma_using_declarations_upperlower]
Basic usage of the `upper` and `lower` generator directives:
[reference_karma_upperlower]
[endsect] [/ upper/lower]
[/////////////////////////////////////////////////////////////////////////////]
[section:maxwidth Generator Directives Controlling the Maximum Field Width (`maxwidth[]`)]
[heading Description]
The `maxwidth[]` directive allows to limit (truncate) the overall length of the
output generated by the embedded generator.
[heading Header]
// forwards to <boost/spirit/home/karma/directive/maxwidth.hpp>
#include <boost/spirit/include/karma_maxwidth.hpp>
Also, see __include_structure__.
[table
[[Name]]
[[`boost::spirit::maxwidth // alias: boost::spirit::karma::maxwidth` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`A`] [Attribute type of the generator `a`]]
[[`num`] [Numeric literal, any unsigned integer value, or
a __karma_lazy_argument__ that evaluates to an unsigned
integer value]]]
[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]]
[[`maxwidth[a]`] [Limit the overall length of the emitted output of
the embedded generator (including characters
generated by automatic delimiting) to the number
of characters as defined by the preprocessor constant
`BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`. Any additional
output is truncated. The directive succeeds as long
as the embedded generator succeeded (unless
the underlying output stream reports an error).]]
[[`maxwidth(num)[a]`] [Limit the overall length of the emitted output of
the embedded generator (including characters
generated by automatic delimiting) to the number
of characters as defined by `num`. Any additional
output is truncated. The directive succeeds as long
as the embedded generator succeeded (unless the
underlying output stream reports an error).]]
]
[note The `maxwidth[]` generator directive does not pad the generated output
to fill the specified column width. If the emitted output is shorter
than the specified (or implied) column width, the generated output will
be more narrow than the column width.
If the output needs to always be equal to a specified column width, use
one of the alignment directives `left-align[]`, `center[]`, or
`right_align[]`, for instance:
``
maxwidth(8)[left_align(8)["1234"]]
``
which will output: `"1234 "` (without the quotes).
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`maxwidth[a]`]
[``a: A --> maxwidth[a]: A
a: Unused --> maxwidth[a]: Unused``]]
[[`maxwidth(num)[a]`]
[``a: A --> maxwidth(num)[a]: A
a: Unused --> maxwidth(num)[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of the generator directive `maxwidth[]`
is defined by the complexity of its embedded generator. The complexity of the
directive itself is O(N), where `N` is the number of characters generated
by the maxwidth directive.]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes_simple]
Some using declarations:
[reference_karma_using_declarations_maxwidth]
Basic usage of `maxwidth` generator directive:
[reference_karma_maxwidth]
[endsect] [/ maxwidth]
[/////////////////////////////////////////////////////////////////////////////]
[section:buffer Generator Directive for Temporary Output Buffering (`buffer[]`)]
[heading Description]
All generator components (except the __karma_alternative__ generator) pass
their generated output directly to the underlying output stream. If a generator
fails halfway through, the output generated so far is not 'rolled back'. The
buffering generator directive allows to avoid this unwanted output to be
generated. It temporarily redirects the output produced by the embedded
generator into a buffer. This buffer is flushed to the underlying stream only
after the embedded generator succeeded, but is discarded otherwise.
[heading Header]
// forwards to <boost/spirit/home/karma/directive/buffer.hpp>
#include <boost/spirit/include/karma_buffer.hpp>
Also, see __include_structure__.
[table
[[Name]]
[[`boost::spirit::buffer // alias: boost::spirit::karma::buffer` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`A`] [Attribute type of generator `a`]]]
[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]]
[[`buffer[a]`] [The embedded generator `a` is invoked but its output
is temporarily intercepted and stored in an internal
buffer. If `a` succeeds the buffer content is flushed
to the underlying output stream, otherwise the buffer
content is discarded. The buffer directive succeeds
as long as the embedded generator succeeded (unless
the underlying output stream reports an error).]]
]
[tip If you want to make the buffered generator succeed regardless of the
outcome of the embedded generator, simply wrap the `buffer[a]` into an
additional optional: `-buffer[a]` (see __karma_optional__).]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`buffer[a]`]
[``a: A --> buffer[a]: A
a: Unused --> buffer[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of the buffering generator directive is defined by the
complexity of its embedded generator. The complexity of the buffering
directive generator itself is O(N), where N is the number of characters
buffered.]
[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_buffer]
Basic usage of a buffering generator directive. It shows how the partial
output generated in the first example does not show up in the generated output
as the plus generator fails (no data is available, see __karma_plus__).
[reference_karma_buffer]
[endsect] [/ buffer]
[/////////////////////////////////////////////////////////////////////////////]
[section:omit Generator Directives Consuming Attributes (`omit[]` and `skip[]`)]
[heading Description]
The directives `omit[]` and `skip[]` consumes the attribute type of the
embedded generator without generating any output. The `omit[]` directive
will still execute the embedded generator while discarding the generated output
afterwards. The `skip[]` directive will not execute the embedded generator, but
will use it only to extract the exposed attribute type.
[heading Header]
// forwards to <boost/spirit/home/karma/directive/omit.hpp>
#include <boost/spirit/include/karma_omit.hpp>
Also, see __include_structure__.
[table
[[Name]]
[[`boost::spirit::omit // alias: boost::spirit::karma::omit` ]]
[[`boost::spirit::skip // alias: boost::spirit::karma::skip` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`A`] [Attribute type of generator `a`]]]
[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]]
[[`omit[a]`] [The `omit` directive consumes the attribute type of the
embedded generator `A` without generating any output.
It succeeds always. The embedded generator is executed
and any generated output is discarded.]]
[[`skip[a]`] [The `skip` directive consumes the attribute type of the
embedded generator `A` without generating any output.
It succeeds always. The embedded generator is not
executed.]]
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`omit[a]`]
[``a: A --> omit[a]: A
a: Unused --> omit[a]: Unused``]]
[[`skip[a]`]
[``a: A --> skip[a]: A
a: Unused --> skip[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of the `omit[]` directive depends on the complexity
of the embedded generator. The overall complexity of the `skip[]` generator
directive is O(1) as it does not generate any output.]
[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_omit]
Basic usage of a `omit` generator directive. It shows how it consumes the first
element of the provided attribute without generating anything, leaving the
second element of the attribute to the non-wrapped `double_` generator.
[reference_karma_omit]
Generally, this directive is helpful in situations, where the attribute type
contains more information (elements) than need to be used to generate the
required output. Normally in such situations we would resolve to use semantic
actions to explicitly pass the correct parts of the overall attribute to the
generators. The `omit` directive helps achieving the same without having to use
semantic actions.
Consider the attribute type:
typedef fusion::vector<int, double, std::string> attribute_type;
where we need to generate output only from the first and last element:
typedef std::back_insert:iterator<std::string> iterator_type;
karma::rule<iterator_type, attribute_type()> r;
r = int_[_1 = phoenix::at_c<0>(_val)] << string[_1 = phoenix::at_c<2>(_val)];
std::string str;
iterator_type sink(str);
generate(sink, r, attribute_type(1, 2.0, "example")); // will generate: '1example'
This is error prone and not really readable. The same can be achieved by using
the `omit` directive:
r = int_ << omit[double_] << string;
which is at the same time more readable and more efficient as we don't have to
use semantic actions.
The semantics of using the `skip[]` directive are identical to the `omit[]`
directive, except that it does not actually execute the embedded generator.
For this reason it is usually preferable to utilize the `skip[]` directive
instead of the `omit[]` directive. On the other hand, the `omit[]` directive
is very useful whenever the embedded generator produces side effects (has
semantic actions which need to be executed).
[endsect] [/ omit]
[/////////////////////////////////////////////////////////////////////////////]
[section:duplicate Generator Directive Duplicating Attributes (`duplicate[]`)]
[heading Description]
The directive `duplicate[]` duplicates its attribute to all elements of the
embedded generator if this is a sequence generator. Otherwise it does nothing.
[heading Header]
// forwards to <boost/spirit/home/karma/directive/duplicate.hpp>
#include <boost/spirit/include/karma_duplicate.hpp>
Also, see __include_structure__.
[table
[[Name]]
[[`boost::spirit::duplicate // alias: boost::spirit::karma::duplicate` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`A`] [Attribute type of generator `a`]]]
[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]]
[[`duplicate[a]`] [The `duplicate` directive duplicates the supplied
attribute for all elements of a embedded sequence
generator. For all other types of embedded generators
it has no effect. It succeeds as long as its embedded
generator does not fail.]]
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`duplicate[a]`]
[``a: A --> duplicate[a]: A
a: tuple<A, A, ...> --> duplicate[a]: A
a: Unused --> duplicate[a]: Unused``]]
]
If the embedded generator of the `duplicate[]` directive is a sequence it is
expected that all elements of this sequence expose either the same attribute
type, an compatible attribute type, or `unused`. In this case, the
`duplicate[]` directive exposes the attribute type of its first element. The
behavior of the `duplicate[]` directive is undefined if the elements of an
embedded sequence do not expose the same attributes. Most likely, the
corresponding expression will not compile.
[heading Complexity]
[:The overall complexity of the `duplicate[]` directive depends on the complexity
of the embedded 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_duplicate]
Basic usage of the `duplicate` generators:
[reference_karma_duplicate]
[endsect] [/ duplicate]
[/////////////////////////////////////////////////////////////////////////////]
[section:columns Generator Directive Separating Output Into Columns (`columns[]`)]
[heading Description]
The `columns[]` directive separates the output emitted by the embedded
generator by inserting special column separators.
[heading Header]
// forwards to <boost/spirit/home/karma/directive/columns.hpp>
#include <boost/spirit/include/karma_columns.hpp>
Also, see __include_structure__.
[table
[[Name]]
[[`boost::spirit::columns // alias: boost::spirit::karma::columns` ]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A generator object]]
[[`g`] [A generator object, or a __karma_lazy_argument__ that
evaluates to a generator object, will be used to emit column
separators]]
[[`A`] [Attribute type of generator `a`]
[[`num`] [Numeric literal, any unsigned integer value, or
a __karma_lazy_argument__ that evaluates to an unsigned
integer value defining the number of items to emit in between
the column separators]]]
[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]]
[[`columns[a]`] [The `columns` directive invokes a generator after
each N-th element of the embedded generator has been
emitted. The number of columns is defined by the
preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`.
The column separator used will be `karma::eol`.]]
[[`columns(num)[a]`][The `columns` directive invokes a generator after
each N-th element of the embedded generator has been
emitted. The number of columns is defined by the
argument to the directive `num`.
The column separator used will be `karma::eol`.]]
[[`columns(g)[a]`] [The `columns` directive invokes a generator after
each N-th element of the embedded generator has been
emitted. The number of columns is defined by the
preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`.
The column separator used will be `g`.]]
[[`columns(num, g)[a]`] [The `columns` directive invokes a generator after
each N-th element of the embedded generator has been
emitted. The number of columns is defined by the
argument to the directive `num`.
The column separator used will be `g`.]]
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`columns[a]`]
[``a: A --> columns[a]: A
a: Unused --> columns[a]: Unused``]]
[[`columns(num)[a]`]
[``a: A --> columns(num)[a]: A
a: Unused --> columns(num)[a]: Unused``]]
[[`columns(g)[a]`]
[``a: A --> columns(g)[a]: A
a: Unused --> columns(g)[a]: Unused``]]
[[`columns(num, g)[a]`]
[``a: A --> columns(num, g)[a]: A
a: Unused --> columns(num, g)[a]: Unused``]]
]
[heading Complexity]
[:The overall complexity of the `columns` generator directive depends on the
complexity of the embedded generator. The complexity of the `columns` generator
directive itself is O(N), where `N` is the number of inserted column
separators.]
[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_columns]
Basic usage of the `columns` generators:
[reference_karma_columns]
[endsect] [/ columns]
[/////////////////////////////////////////////////////////////////////////////]
[section:as Generator Directives Forcing Atomic Extraction (`as<T>, as_string[], as_wstring[]`)]
[heading Description]
The `as<T>` class forces the atomic extraction of a container type `T` from it's
consumed attribute. Usually, repetitive generators (such as __karma_kleene__,
etc) or sequences exposing a `vector<A>` will extract elements from the
container supplied as their consumed attribute by looping through the
containers iterators. In some cases, this may be undesirable. The `as<T>`
class creates a directive that will pass an unnamed temporary object of type
`T` to it's subject, if extracting `T` from it's consumed attribute determined
at generation-time to be valid. __customize_valid_as__ is called by `as<T>` to
determine validity; if it returns false, the generator fails. Subsequent
extraction is performed by calling __customize_as__.
[note `T` is required to be a container type. If __customize_is_container__
does not return true for `T`, a compile-time error will occur.]
[heading Header]
// forwards to <boost/spirit/home/karma/directive/as.hpp>
#include <boost/spirit/include/karma_as.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::as_string // alias: boost::spirit::karma::as_string` ]]
[[`boost::spirit::as_wstring // alias: boost::spirit::karma::as_wstring` ]]
]
[heading Synopsis]
template <typename T>
struct as;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`T`] [A container type.] [none]]
]
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`] [A __generator_concept__.]]
[[`attr`] [The attribute supplied to the directive.]]
]
[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]]
[[`as<T>()[a]`] [Extract an instance of `T` from `attr`, and
invoke the subject generator `a`, supplying
the unnamed temporary as it's attribute.]]
[[`as_string[a]`] [Equivalent to `as<std::string>()[a]`]]
[[`as_wstring[a]`] [Equivalent to `as<std::wstring>()[a]`]]
]
[heading Attributes]
See __karma_comp_attr_notation__.
[table
[[Expression] [Attribute]]
[[`as<T>()[a]`] [`a: A --> as<T>()[a]: T`]]
]
[heading Complexity]
[:The complexity is defined by the complexity of the subject generator, `a`, and
the complexity of the extraction unnamed contianer of type `T` from the
attribute `attr`.]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some using declarations:
[reference_karma_using_declarations_as]
Simple usage of `as<T>`, `as_string` and `as_wstring`:
[reference_karma_as]
[endsect] [/ as]
[endsect] [/ directives]
