hdkv/yuzu
1
Fork 0
Code Issues Pull Requests Releases 1 Activity

early-access version 3088

Browse Source
This commit is contained in:
pineappleEA
2022-11-05 15:35:56 +01:00
parent 4e4fc25ce3
commit b601909c6d
35519 changed files with 5996896 additions and 860 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/action.qbk vendored Executable file
View File

@@ -0,0 +1,119 @@
[/==============================================================================
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:action Semantic Actions with Generators]
[heading Description]
Semantic actions may be attached to any point in the grammar specification.
They allow to call a function or function object in order to provide the value
output by the generator attached to the semantic action. Semantic
actions are associated with a generator using the syntax `g[]`, where `g` is an
arbitrary generator expression.
[heading Header]
// forwards to <boost/spirit/home/karma/action.hpp>
#include <boost/spirit/include/karma_action.hpp>
Also, see __include_structure__.
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`a`, `g`][Instances of a generator, `G`]]
[[`A`] [Attribute type exposed by a generator, `a`]]
[[`fa`] [A (semantic action) function with signature `void(Attrib&, Context&, bool&)`.
The third parameter is a boolean flag that can be set to false to
force the generator to fail. Both `Context` and the boolean flag are
optional. For more information see below.]]
[[`Attrib`][The attribute to be used to generate output from.]]
[[`Context`] [The type of the generator execution context. For more
information see below.]]
]
[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]]
[[`g[fa]`] [Call semantic action, `fa` /before/ invoking `g`. The function
or function object `fa` is expected to provide the value
to generate output from to the generator `g`.]]
]
The possible signatures for functions to be used as semantic actions are:
template <typename Attrib>
void fa(Attrib& attr);
template <typename Attrib, typename Context>
void fa(Attrib& attr, Context& context);
template <typename Attrib, typename Context>
void fa(Attrib& attr, Context& context, bool& pass);
The function or function object is expected to return the value to generate
output from by assigning it to the first parameter, `attr`. Here `Attrib` is
the attribute type of the generator attached to the semantic action.
The type `Context` is the type of the generator execution context. This type is
unspecified and depends on the context the generator is invoked in. The value
`context` is used by semantic actions written using __phoenix__ to access various
context dependent attributes and values. For more information about __phoenix__
placeholder expressions usable in semantic actions see __karma_nonterminal_concept__.
The third parameter, `pass`, can be used by the semantic action to force the
associated generator to fail. If pass is set to `false` the action generator
will immediately return `false` as well, while not invoking `g` and not
generating any output.
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`a[fa]`] [`a: A --> a[fa]: A`]]
]
[heading Complexity]
The complexity of the action generator is defined by the complexity of the
generator the semantic action is attached to and the complexity of the function
or function object used as the semantic action.
[important Please note that the use of semantic actions in __karma__ generally
forces the library to create a /copy/ of the attribute, which might
be a costly operation. Always consider using other means of
associating a value with a particular generator first.]
[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_action]
Some examples:
[reference_karma_action]
More examples for semantic actions can be found here:
[link spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions Examples of Semantic Actions].
[endsect] [/ Action]

155
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/actions.qbk vendored Executable file
View File

@@ -0,0 +1,155 @@
[/==============================================================================
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:semantic_actions Generator Semantic Actions]
In the previous section we mentioned a very important difference between parsers
and generators. While parsers may be used without 'producing' any data,
generators always need data to generate the output from. We mentioned one way
of passing data to the generator by supplying it as a parameter to one of the
main API functions (for instance `generate()` or `generate_delimited()`).
But sometimes this is not possible or not desirable.
Very much like for __qi__ we have semantic actions in __karma__ as well.
Semantic actions may be attached to any point in the grammar specification.
These actions are C++ functions or function objects that are called whenever a
part of the generator is about to be invoked. Say you have a generator `G`,
and a C++ function `F`, you can make the generator call `F` just before it gets
invoked by attaching `F`:
G[F]
The expression above links `F` to the generator, `G`.
Semantic actions in __qi__ are invoked after a parser successfully
matches its input and the matched value is passed into the
semantic action. In __karma__ the opposite happens. Semantic actions are called
before its associated generator is invoked. They may provide the data required
by the generator.
The function/function object signature depends on the type of the generator to
which it is attached. The generator `double_` expects the number to generate.
Thus, if we were to attach a function `F` to `double_`, we need `F` to be
declared as:
void F(double& n);
where the function is expected to initialize the parameter `n` with the value
to generate.
[important Generally, and more formally, the semantic action `F` attached to
a generator `G` needs to take a reference to the generator's
attribute type as its first parameter. For more information about
generator attributes please see the section __karma_attribute__.
In the example above the function F takes a `double&` as its first
parameter as the attribute of the `double_` generator happens to be
a `double`.
]
There are actually 2 more arguments being passed (the generator context and a
reference to a boolean 'pass' parameter). We don't need these, for now, but
we'll see more on these other arguments later. __karma__ allows us to bind a
single argument function, like above. The other arguments are simply ignored.
To sum up, the possible signatures for semantic actions are:
void f(Attrib&);
void f(Attrib&, Context&);
void f(Attrib&, Context&, bool&);
[heading Examples of Semantic Actions]
In the following example we present various ways to attach semantic actions:
* Using a plain function pointer
* Using a simple function object
* Using __boost_bind__ with a plain function
* Using __boost_bind__ with a member function
* Using __boost_lambda__
[import ../../example/karma/actions.cpp]
Let's assume we have:
[karma_tutorial_semantic_action_functions]
Take note that with function objects, we need to have an `operator()` with 3
arguments. Since we don't care about the other two, we can use `unused_type` for
these. We'll see more of `unused_type` elsewhere. Get used to it. `unused_type`
is a Spirit supplied support class. Most of the time it stands for 'I don't
care, just use the appropriate default'.
All following examples generate outputs of the form:
"{integer}"
An integer inside the curly braces.
The first example shows how to attach a plain function:
[karma_tutorial_attach_actions1]
What's new? Well `int_` is the sibling of `double_`. I'm sure you can guess
what this generator does and what type of attribute it expects.
The next example shows how to attach a simple function object:
[karma_tutorial_attach_actions2]
We can use __boost_bind__ to 'bind' member functions:
[karma_tutorial_attach_actions4]
Likewise, we can also use __boost_bind__ to 'bind' plain functions:
[karma_tutorial_attach_actions3]
And last but not least, we can also use __boost_lambda__:
[karma_tutorial_attach_actions5]
There are more ways to bind semantic action functions, but the examples above
are the most common. Attaching semantic actions is the first hurdle one has
to tackle when getting started with generating with Spirit. If you didn't do so
yet, it is probably a good idea to familiarize yourself with the tools behind
it such as __boost_bind__ and __boost_lambda__.
The examples above can be found here: [@../../example/karma/actions.cpp actions.cpp]
[heading Phoenix]
__phoenix__, a companion library bundled with Spirit, is specifically suited
for binding semantic actions. It is like __boost_lambda__ on steroids, with
special custom features that make it easy to integrate semantic actions with
Spirit. If your requirements go beyond simple to moderate generation, I suggest
you use this library. Examples presented henceforth shall be using the Phoenix
library exclusively.
[important There are different ways to write semantic actions for __karma__:
using plain functions, __boost_bind__, __boost_lambda__, or
__phoenix__. The latter three allow you to use special placeholders
to control parameter placement (`_1`, `_2`, etc.). Each of those
libraries has it's own implementation of the placeholders, all
in different namespaces. You have to make sure not to mix
placeholders with a library they don't belong to and not to
use different libraries while writing a semantic action.
Generally, for __boost_bind__, use `::_1`, `::_2`, etc. (yes, these
placeholders are defined in the global namespace).
For __boost_lambda__ use the placeholders defined in the namespace
`boost::lambda`.
For semantic actions written using __phoenix__ use the placeholders
defined in the namespace `boost::spirit`. Please note that all
existing placeholders for your convenience are also available from
the namespace `boost::spirit::karma`.]
[endsect] [/ Semantic Actions]

145
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/auto.qbk vendored Executable file
View File

@@ -0,0 +1,145 @@
[/==============================================================================
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:auto Auto Generator]
[heading Description]
This module includes the description of the `auto_` generator. This generator
can be used to automatically create a generator based on the supplied attribute
type.
[heading Header]
// forwards to <boost/spirit/home/karma/auto.hpp>
#include <boost/spirit/include/karma_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::auto_ // alias: boost::spirit::karma::auto_`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`s`] [A variable instance of any type for which a mapping to a
generator type is defined (the meta function
`traits::create_generator_exists` returns `mpl::true_`) or a
__karma_lazy_argument__ that evaluates to any type for which
a mapping to a generator type is defined (the meta function
`traits::create_generator_exists` returns `mpl::true_`).]]
]
[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]]
[[`auto_`] [Create a generator instance compatible with the
supplied attribute type and use it for output
generation. This generator never fails
(unless the underlying output stream reports an
error).]]
[[`auto_(s)`] [Create a generator instance compatible with the
supplied literal value. This generator never fails
(unless the underlying output stream reports an
error).]]
]
[heading Additional Requirements]
The `auto_` generators can be used to emit output for any data type for which
a mapping to a generator type is defined (the meta function
`traits::create_generator_exists` returns `mpl::true_`).
The following table outlines the predefined mapping rules from the attribute type
to the generator type. These rules are applied recursively to create the generator
type which can be used to generate output from the given attribute type.
[table
[[Attribute type] [Generator type]]
[[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]]
[[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
[[`unsigned short`, `unsigned int`, `unsigned long`]
[`ushort_`, `uint_`, `ulong_`]]
[[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]]
[[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
[[`long long`, `unsigned long long`]
[`long_long`, `ulong_long`]]
[[`bool`] [`bool_`]]
[[Any string (`char const*`, `std::string`, etc.)]
[`string`]]
[[Any (STL) container] [Kleene Star (unary `'*'`)]]
[[Any Fusion sequence] [Sequence operator (`'<<'`)]]
[[`boost::optional<>`] [Optional operator (unary `'-'`)]]
[[`boost::variant<>`] [Alternative operator (`'|'`)]]
]
It is possible to add support for any custom data type by implementing a
specialization of the customization point __customize_create_generator__. This
customization can be used also to redefined any of the predefined mappings.
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`auto_`] [`hold_any`, attribute is mandatory (otherwise
compilation will fail)]]
[[`auto_(s)`] [__unused__]]
]
[important The attribute type `hold_any` exposed by some of the `auto_`
generators is semantically and syntactically equivalent to
the type implemented by __boost_any__. It has been added to /Spirit/
as it has better a performance and a smaller footprint if compared to
__boost_any__.
]
[note In addition to their usual attribute of type `Attrib` all listed generators
accept an instance of a `boost::optional<Attrib>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Attrib` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:The complexity of the `auto_` generator depends on the attribute type. Each
attribute type results in a different generator type to be instantiated which
defines the overall complexity.]
[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_auto]
And a class definition used in the examples:
[reference_karma_complex]
[reference_karma_auto_complex]
Some usage examples of `auto_` generators:
[reference_karma_auto]
[endsect]

443
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/auxiliary.qbk vendored Executable file
View File

@@ -0,0 +1,443 @@
[/==============================================================================
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:auxiliary Auxiliary Generators]
This module includes different auxiliary generators not fitting into any of the
other categories. It includes the `attr_cast`, `eol`, `eps`, and `lazy`
generators.
[heading Module Header]
// forwards to <boost/spirit/home/karma/auxiliary.hpp>
#include <boost/spirit/include/karma_auxiliary.hpp>
Also, see __include_structure__.
[/////////////////////////////////////////////////////////////////////////////]
[section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)]
[heading Description]
The `attr_cast<Exposed, Transformed>()` component invokes the embedded generator
while supplying an attribute of type `Transformed`. The supplied attribute gets created
from the original attribute (of type `Exposed`) passed to this component using the
customization point __customize_transform_attribute__.
[heading Header]
// forwards to <boost/spirit/home/karma/auxiliary/attr_cast.hpp>
#include <boost/spirit/include/karma_attr_cast.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::attr_cast // alias: boost::spirit::karma::attr_cast`]]
]
[heading Synopsis]
template <Exposed, Transformed>
<unspecified> attr_cast(<unspecified>);
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`Exposed`] [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]]
[[`Transformed`][The type of the attribute expected by the embedded
generator `g`.] [__unused_type__]]
]
The `attr_cast` is a function template. It is possible to invoke it using the
following schemes:
attr_cast(g)
attr_cast<Exposed>(g)
attr_cast<Exposed, Transformed>(g)
depending on which of the attribute types can be deduced properly if not
explicitly specified.
[heading Model of]
[:__unary_generator_concept__]
[variablelist Notation
[[`g`] [A generator object.]]
]
[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]]
[[`attr_cast(g)`] [Create a component invoking the
generator `g` while passing an attribute of the type
as normally expected by `g`. The type of the supplied
attribute will be transformed to the type
`g` exposes as its attribute type (by using the
attribute customization point __customize_transform_attribute__).
This generator does not fail unless `g` fails.]]
[[`attr_cast<Exposed>(g)`] [Create a component invoking the
generator `g` while passing an attribute of the type
as normally expected by `g`. The supplied attribute
is expected to be of the type `Exposed`, it will be
transformed to the type `g` exposes as its attribute type
(using the attribute customization point
__customize_transform_attribute__).
This generator does not fail unless `g` fails.]]
[[`attr_cast<Exposed, Transformed>(g)`] [Create a component invoking the
generator `g` while passing an attribute of type
`Transformed`. The supplied attribute is expected
to be of the type `Exposed`, it will be transformed
to the type `Transformed` (using the attribute
customization point __customize_transform_attribute__).
This generator does not fail unless `g` fails.]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`attr_cast(g)`] [`g: A --> attr_cast(g): A`]]
[[`attr_cast<Exposed>(g)`] [`g: A --> attr_cast<Exposed>(g): Exposed`]]
[[`attr_cast<Exposed, Transformed>(g)`]
[`g: A --> attr_cast<Exposed, Transformed>(g): Exposed`]]
]
[heading Complexity]
[:The complexity of this component is fully defined by the complexity of the
embedded generator `g`.]
[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_attr_cast]
The example references data structure `int_data` which needs a specialization of
the customization point __customize_transform_attribute__:
[reference_karma_auxiliary_attr_cast_data1]
Now we use the `attr_cast` pseudo generator to invoke the attribute
transformation:
[reference_karma_attr_cast1]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:eol End of Line Generator (`eol`)]
[heading Description]
The `eol` component generates a single newline character. It is equivalent
to `lit('\n')` or simply '\\n' (please see the [karma_char `char_`] generator
module for more details).
[heading Header]
// forwards to <boost/spirit/home/karma/auxiliary/eol.hpp>
#include <boost/spirit/include/karma_eol.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::eol // alias: boost::spirit::karma::eol`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[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]]
[[`eol`] [Create a component generating a single end of line
character in the output. This generator never fails
(unless the underlying output stream reports an
error).]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`eol`] [__unused__]]
]
[heading Complexity]
[:O(1)]
The complexity is constant as a single character is generated in the 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_eol]
Basic usage of the `eol` generator:
[reference_karma_eol]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:eps Epsilon Generator (`eps`)]
The family of `eps` components allows to create pseudo generators generating
an empty string. This feature is sometimes useful either to force a generator
to fail or to succeed or to insert semantic actions into the generation process.
[heading Description]
The Epsilon (`eps`) is a multi-purpose generator that emits a zero length
string.
[heading Simple Form]
In its simplest form, `eps` creates a component generating an empty string
while always succeeding:
eps // always emits a zero-length string
This form is usually used to trigger a semantic action unconditionally.
For example, it is useful in triggering error messages when a set of
alternatives fail:
r = a | b | c | eps[error()]; // Call error if a, b, and c fail to generate
[heading Semantic Predicate]
The `eps(b)` component generates an empty string as well, but
succeeds only if `b` is `true` and fails otherwise. It's lazy variant `eps(fb)`
is equivalent to `eps(b)` except it evaluates the supplied function `fb` at
generate time, while using the return value as the criteria to succeed.
Semantic predicates allow you to attach a conditional function anywhere
in the grammar. In this role, the epsilon takes a __karma_lazy_argument__ that
returns `true` or `false`. The __karma_lazy_argument__ is typically a test
that is called to resolve ambiguity in the grammar. A generator failure will
be reported when the __karma_lazy_argument__ result evaluates to `false`.
Otherwise an empty string will be emitted. The general form is:
eps_p(fb) << rest;
The __karma_lazy_argument__ `fb` is called to do a semantic test. If the test
returns true, `rest` will be evaluated. Otherwise, the production will return
early without ever touching rest.
[heading Header]
// forwards to <boost/spirit/home/karma/auxiliary/eps.hpp>
#include <boost/spirit/include/karma_eps.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::eps // alias: boost::spirit::karma::eps`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`b`] [A boolean value.]]
[[`fb`] [A __karma_lazy_argument__ that evaluates to a boolean value.]]
]
[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]]
[[`eps`] [Creates a component generating an empty string.
Succeeds always.]]
[[`eps(b)`] [Creates a component generating an empty string.
Succeeds if `b` is `true` (unless the underlying
output stream reports an error).]]
[[`eps(fb)`] [Creates a component generating an empty string.
Succeeds if `fb` returns `true` at generate time
(unless the underlying output stream reports an
error).]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`eps`] [__unused__]]
[[`eps(b)`] [__unused__]]
[[`eps(fb)`] [__unused__]]
]
[heading Complexity]
[:O(1)]
The complexity is constant as no output is generated.
[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_eps]
Basic usage of the `eps` generator:
[reference_karma_eps]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:lazy Lazy Generator (`lazy`)]
[heading Description]
The family of `lazy` components allows to use a dynamically returned generator
component for output generation. It calls the provided function or function
object at generate time using its return value as the actual generator to
produce the output.
[heading Header]
// forwards to <boost/spirit/home/karma/auxiliary/lazy.hpp>
#include <boost/spirit/include/karma_lazy.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lazy // alias: boost::spirit::karma::lazy`]]
]
[heading Model of]
[:__generator_concept__]
[variablelist Notation
[[`fg`] [A function or function object that evaluates to a generator
object (an object exposing the __generator_concept__). This
function will be invoked at generate time.]]
]
The signature of `fg` is expected to be
G f(Unused, Context)
where `G`, the function's return value, is the type of the generator to be
invoked, and `Context` is the generator's __karma_context__ type (The
first argument is __unused__ to make the `Context` the second argument. This
is done for uniformity with __karma_actions__).
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __generator_concept__.
[table
[[Expression] [Semantics]]
[[`fg`] [The __phoenix__ function object `fg` will be
invoked at generate time. It is expected to return a
generator instance. This generator is then invoked
in order to generate the output. This generator will
succeed as long as the invoked generated succeeds as
well (unless the underlying output stream reports
an error).]]
[[`lazy(fg)`] [The function or function object will be invoked at
generate time. It is expected to return a generator
instance (note this version of `lazy` does not
require `fg` to be a __phoenix__ function
object). This generator is then invoked in order to
generate the output. This generator will succeed as
long as the invoked generated succeeds as well (except
if the underlying output stream reports an error).]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`fg`] [The attribute type `G` as exposed by the generator `g`
returned from `fg`.]]
[[`lazy(fg)`] [The attribute type `G` as exposed by the generator `g`
returned from `fg`.]]
]
[heading Complexity]
The complexity of the `lazy` component is determined by the complexity of the
generator returned from `fg`.
[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_lazy]
Basic usage of the `lazy` generator:
[reference_karma_lazy]
[endsect]
[endsect]

108
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/basics.qbk vendored Executable file
View File

@@ -0,0 +1,108 @@
[/==============================================================================
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:basics Generator Basics]
[heading Lazy Argument]
Some generators (e.g. primitives and non-terminals) may take in additional
attributes. Such generators take the form:
g(a1, a2,..., aN)
where `g` is a generator. Each of the arguments (a1 ... aN) can either be an
immediate value, or a function, `f`, with signature:
T f(Unused, Context)
where `T`, the function's return value, is compatible with the argument
type expected and `Context` is the generator's __karma_context__ type (The
first argument is __unused__ to make the `Context` the second argument. This
is done for uniformity with __karma_actions__).
[heading Character Encoding Namespace]
Some generators need to know which character set a `char` or `wchar_t` is
operating on. For example, the `alnum` generator works differently with
ISO8859.1 and ASCII encodings. Where necessary, Spirit encodes (tags)
the generator with the character set.
We have a namespace for each character set Spirit will be supporting.
That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
in the future, `unicode`). In each of the character encoding namespaces,
we place tagged versions of generators such as `alnum`, `space` etc.
Example:
using boost::spirit::ascii::space; // use the ASCII space generator
Namespaces:
* boost::spirit::ascii
* boost::spirit::iso8859_1
* boost::spirit::standard
* boost::spirit::standard_wide
For ease of use, the components in this namespaces are also brought into
the karma sub-namespaces with the same names:
* boost::spirit::karma::ascii
* boost::spirit::karma::iso8859_1
* boost::spirit::karma::standard
* boost::spirit::karma::standard_wide
[heading Examples]
All sections in the reference present some real world examples. The
examples use a common test harness to keep the example code as minimal
and direct to the point as possible. The test harness is presented
below.
Some includes:
[reference_karma_includes]
The used output iterator:
[reference_karma_output_iterator]
Our test functions:
This one tests the generators without attributes.
[reference_karma_test]
These test the generators with one or more user supplied attributes.
[reference_karma_test_attr]
[reference_karma_test_attr2]
This tests the generators with one attribute and while using delimited output.
[reference_karma_test_attr_delim]
The examples of the binary generators use one or more of the following tests.
[reference_karma_binary_test]
[reference_karma_binary_test_attr]
[heading Models]
Predefined models include:
* any literal string, e.g. "Hello, World",
* a pointer/reference to a null-terminated array of characters
* a `std::basic_string<Char>`
The namespace `boost::spirit::traits` is open for users to provide their
own specializations. The customization points implemented by __karma__ usable
to customize the behavior of generators are described in the section
__sec_customization_points__.
[endsect]

508
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/binary.qbk vendored Executable file
View File

@@ -0,0 +1,508 @@
[/==============================================================================
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:binary Binary Generators]
This module includes different generators allowing to output binary data.
It includes generators for default, little, and big endian binary output and
a `pad` generator allowing to control padding of the generated output
stream.
[heading Module Header]
// forwards to <boost/spirit/home/karma/binary.hpp>
#include <boost/spirit/include/karma_binary.hpp>
Also, see __include_structure__.
[/////////////////////////////////////////////////////////////////////////////]
[section:binary_native Binary Native Endianness Generators]
[heading Description]
The binary native endianness generators described in this section are used to
emit binary byte streams laid out conforming to the native endianness (byte
order) of the target architecture.
[heading Header]
// forwards to <boost/spirit/home/karma/binary.hpp>
#include <boost/spirit/include/karma_binary.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::byte_ // alias: boost::spirit::karma::byte_` ]]
[[`boost::spirit::word // alias: boost::spirit::karma::word` ]]
[[`boost::spirit::dword // alias: boost::spirit::karma::dword` ]]
[[`boost::spirit::qword // alias: boost::spirit::karma::qword` ]]
[[`boost::spirit::bin_float // alias: boost::spirit::karma::bin_float` ]]
[[`boost::spirit::bin_double // alias: boost::spirit::karma::bin_double` ]]
]
[note The generators `qword` and `qword(qw)` are only available on
platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
defined (i.e. on platforms having native support for `unsigned long long`
(64 bit) integer types).]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`b`] [A single byte (8 bit binary value) or a __karma_lazy_argument__
that evaluates to a single byte]]
[[`w`] [A 16 bit binary value or a __karma_lazy_argument__ that
evaluates to a 16 bit binary value. This value is always
interpreted using native endianness.]]
[[`dw`] [A 32 bit binary value or a __karma_lazy_argument__ that
evaluates to a 32 bit binary value. This value is always
interpreted using native endianness.]]
[[`qw`] [A 64 bit binary value or a __karma_lazy_argument__ that
evaluates to a 64 bit binary value. This value is always
interpreted using native endianness.]]
[[`f`] [A float binary value or a __karma_lazy_argument__ that
evaluates to a float binary value. This value is always
interpreted using native endianness.]]
[[`d`] [A double binary value or a __karma_lazy_argument__ that
evaluates to a double binary value. This value is always
interpreted using native endianness.]]
]
[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]]
[[`byte_`] [Output the binary representation of the least
significant byte of the mandatory attribute. This
generator never fails (unless the underlying
output stream reports an error).]]
[[`word`] [Output the binary representation of the least
significant 16 bits of the mandatory attribute
in native endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`dword`] [Output the binary representation of the least
significant 32 bits of the mandatory attribute
in native endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`qword`] [Output the binary representation of the least
significant 64 bits of the mandatory attribute
in native endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`bin_float`] [Output the binary representation of the mandatory
float attribute in native endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`bin_double`] [Output the binary representation of the mandatory
double attribute in native endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`byte_(b)`] [Output the binary representation of the least
significant byte of the immediate parameter. This
generator never fails (unless the underlying
output stream reports an error).]]
[[`word(w)`] [Output the binary representation of the least
significant 16 bits of the immediate parameter
in native endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`dword(dw)`] [Output the binary representation of the least
significant 32 bits of the immediate parameter
in native endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`qword(qw)`] [Output the binary representation of the least
significant 64 bits of the immediate parameter
in native endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`bin_float(f)`] [Output the binary representation of the immediate
float parameter in native endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`bin_double(d)`] [Output the binary representation of the immediate
double parameter in native endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`byte_`] [`boost::uint_least8_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`word`] [`boost::uint_least16_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`dword`] [`boost::uint_least32_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`qword`] [`boost::uint_least64_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`bin_float`] [`float`, attribute is mandatory
(otherwise compilation will fail)]]
[[`bin_double`] [`double`, attribute is mandatory
(otherwise compilation will fail)]]
[[`byte_(b)`] [__unused__]]
[[`word(w)`] [__unused__]]
[[`dword(dw)`] [__unused__]]
[[`qword(qw)`] [__unused__]]
[[`bin_float(f)`] [__unused__]]
[[`bin_double(d)`] [__unused__]]
]
[note In addition to their usual attribute of type `Attrib` all listed generators
accept an instance of a `boost::optional<Attrib>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Attrib` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:O(N), where N is the number of bytes emitted by the binary 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_native_binary]
Basic usage of the native binary generators with some results for little endian
platforms:
[reference_karma_native_binary_little]
Basic usage of the native binary generators with some results for big endian
platforms:
[reference_karma_native_binary_big]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:binary_little Binary Little Endianness Generators]
[heading Description]
The little native endianness generators described in this section are used to
emit binary byte streams laid out conforming to the little endianness byte
order.
[heading Header]
// forwards to <boost/spirit/home/karma/binary.hpp>
#include <boost/spirit/include/karma_binary.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::little_word // alias: boost::spirit::karma::little_word` ]]
[[`boost::spirit::little_dword // alias: boost::spirit::karma::little_dword` ]]
[[`boost::spirit::little_qword // alias: boost::spirit::karma::little_qword` ]]
[[`boost::spirit::little_bin_float // alias: boost::spirit::karma::little_bin_float` ]]
[[`boost::spirit::little_bin_double // alias: boost::spirit::karma::little_bin_double` ]]
]
[note The generators `little_qword` and `little_qword(qw)` are only available on
platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
defined (i.e. on platforms having native support for `unsigned long long`
(64 bit) integer types).]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`w`] [A 16 bit binary value or a __karma_lazy_argument__ that
evaluates to a 16 bit binary value. This value is always
interpreted using native endianness.]]
[[`dw`] [A 32 bit binary value or a __karma_lazy_argument__ that
evaluates to a 32 bit binary value. This value is always
interpreted using native endianness.]]
[[`qw`] [A 64 bit binary value or a __karma_lazy_argument__ that
evaluates to a 64 bit binary value. This value is always
interpreted using native endianness.]]
[[`f`] [A float binary value or a __karma_lazy_argument__ that
evaluates to a float binary value. This value is always
interpreted using native endianness.]]
[[`d`] [A double binary value or a __karma_lazy_argument__ that
evaluates to a double binary value. This value is always
interpreted using native endianness.]]
]
[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]]
[[`little_word`] [Output the binary representation of the least
significant 16 bits of the mandatory attribute
in little endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`little_dword`] [Output the binary representation of the least
significant 32 bits of the mandatory attribute
in little endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`little_qword`] [Output the binary representation of the least
significant 64 bits of the mandatory attribute
in little endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`little_bin_float`] [Output the binary representation of the mandatory
float attribute in little endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`little_bin_double`] [Output the binary representation of the mandatory
double attribute in little endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`little_word(w)`] [Output the binary representation of the least
significant 16 bits of the immediate parameter
in little endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`little_dword(dw)`] [Output the binary representation of the least
significant 32 bits of the immediate parameter
in little endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`little_qword(qw)`] [Output the binary representation of the least
significant 64 bits of the immediate parameter
in little endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`little_bin_float(f)`] [Output the binary representation of the immediate
float parameter in little endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`little_bin_double(d)`] [Output the binary representation of the immediate
double parameter in little endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`little_word`] [`boost::uint_least16_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`little_dword`] [`boost::uint_least32_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`little_qword`] [`boost::uint_least64_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`little_bin_float`] [`float`, attribute is mandatory
(otherwise compilation will fail)]]
[[`little_bin_double`] [`double`, attribute is mandatory
(otherwise compilation will fail)]]
[[`little_word(w)`] [__unused__]]
[[`little_dword(dw)`] [__unused__]]
[[`little_qword(qw)`] [__unused__]]
[[`little_bin_float(f)`] [__unused__]]
[[`little_bin_double(d)`] [__unused__]]
]
[heading Complexity]
[:O(N), where N is the number of bytes emitted by the binary 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_little_binary]
Basic usage of the little binary generators:
[reference_karma_little_binary]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:binary_big Binary Big Endianness Generators]
[heading Description]
The big native endianness generators described in this section are used to
emit binary byte streams laid out conforming to the big endianness byte
order.
[heading Header]
// forwards to <boost/spirit/home/karma/binary.hpp>
#include <boost/spirit/include/karma_binary.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::big_word // alias: boost::spirit::karma::big_word` ]]
[[`boost::spirit::big_dword // alias: boost::spirit::karma::big_dword` ]]
[[`boost::spirit::big_qword // alias: boost::spirit::karma::big_qword` ]]
[[`boost::spirit::big_bin_float // alias: boost::spirit::karma::big_bin_float` ]]
[[`boost::spirit::big_bin_double // alias: boost::spirit::karma::big_bin_double` ]]
]
[note The generators `big_qword` and `big_qword(qw)` are only available on
platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
defined (i.e. on platforms having native support for `unsigned long long`
(64 bit) integer types).]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`w`] [A 16 bit binary value or a __karma_lazy_argument__ that
evaluates to a 16 bit binary value. This value is always
interpreted using native endianness.]]
[[`dw`] [A 32 bit binary value or a __karma_lazy_argument__ that
evaluates to a 32 bit binary value. This value is always
interpreted using native endianness.]]
[[`qw`] [A 64 bit binary value or a __karma_lazy_argument__ that
evaluates to a 64 bit binary value. This value is always
interpreted using native endianness.]]
[[`f`] [A float binary value or a __karma_lazy_argument__ that
evaluates to a float binary value. This value is always
interpreted using native endianness.]]
[[`d`] [A double binary value or a __karma_lazy_argument__ that
evaluates to a double binary value. This value is always
interpreted using native endianness.]]
]
[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]]
[[`big_word`] [Output the binary representation of the least
significant 16 bits of the mandatory attribute
in big endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`big_dword`] [Output the binary representation of the least
significant 32 bits of the mandatory attribute
in big endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`big_qword`] [Output the binary representation of the least
significant 64 bits of the mandatory attribute
in big endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`big_bin_float`] [Output the binary representation of the mandatory
float attribute in big endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`big_bin_double`] [Output the binary representation of the mandatory
double attribute in big endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`big_word(w)`] [Output the binary representation of the least
significant 16 bits of the immediate parameter
in big endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`big_dword(dw)`] [Output the binary representation of the least
significant 32 bits of the immediate parameter
in big endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`big_qword(qw)`] [Output the binary representation of the least
significant 64 bits of the immediate parameter
in big endian representation. This generator
never fails (unless the underlying output stream
reports an error).]]
[[`big_bin_float(f)`] [Output the binary representation of the immediate
float parameter in big endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
[[`big_bin_double(d)`] [Output the binary representation of the immediate
double parameter in big endian representation.
This generator never fails (unless the underlying
output stream reports an error).]]
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`big_word`] [`boost::uint_least16_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`big_dword`] [`boost::uint_least32_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`big_qword`] [`boost::uint_least64_t`, attribute is mandatory
(otherwise compilation will fail)]]
[[`big_bin_float`] [`float`, attribute is mandatory
(otherwise compilation will fail)]]
[[`big_bin_double`] [`double`, attribute is mandatory
(otherwise compilation will fail)]]
[[`big_word(w)`] [__unused__]]
[[`big_dword(dw)`] [__unused__]]
[[`big_qword(qw)`] [__unused__]]
[[`big_bin_float(f)`] [__unused__]]
[[`big_bin_double(d)`] [__unused__]]
]
[heading Complexity]
[:O(N), where N is the number of bytes emitted by the binary 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_big_binary]
Basic usage of the big binary generators:
[reference_karma_big_binary]
[endsect]
[endsect]

491
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/char.qbk vendored Executable file
View File

@@ -0,0 +1,491 @@
[/==============================================================================
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]

298
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/complex.qbk vendored Executable file
View File

@@ -0,0 +1,298 @@
[/==============================================================================
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:karma_complex Complex - A first more complex generator]
In this section we will develop a generator for complex numbers, allowing to
represent a `std::complex` either as `(real, imag)` (where `real` and `imag`
are the real and imaginary parts of the complex number) or as a simple `real`
if the imaginary part happens to be equal to zero. This example will highlight
the power of __karma__ allowing to combine compile time definition of
formatting rules with runtime based decisions which of the rules to apply.
Also this time, we're using __phoenix__ to do the semantic actions.
Our goal is to allow for two different output formats to be applied depending
on whether the imaginary part of the complex number is zero or not. Let's write
both as a set of alternatives:
'(' << double_ << ", " << double_ << ')'
| double_
where the first alternative should be used for numbers having a non-zero
imaginary part, while the second is for real numbers. Generally, alternatives
are tried in the sequence of their definition as long until one of the
expressions (as delimited by `'|'`) succeeds. If no generator expression
succeeds the whole alternative fails.
If we left this formatting grammar as is our generator would always choose
the first alternative. We need to add some additional rules allowing to make the
first alternative fail. So, if the first alternative fails the second one will
be chosen instead. The decision about whether to choose the first alternative
has to be made at runtime as only then we actually know the value of the
imaginary part of the complex number. __karma__ provides us with with a
primitive generator `eps()`, which is usable as a semantic predicate. It has
the property to 'succeed' generating only if its argument is true (while it
never generates any output on its own).
double imag = ...; // imaginary part
eps(imag != 0) << '(' << double_ << ", " << double_ << ')'
| double_
If one of the generator elements of a sequence fails the whole sequence will
fail. This is exactly what we need, forcing the second alternative to be chosen
for complex numbers with imaginary parts equal to zero.
[import ../../example/karma/complex_number.cpp]
Now on to the full example, this time with the proper semantic actions (the
complete cpp file for this example can be found here:
[@../../example/karma/complex_number.cpp complex_number.cpp]).
We will use the `std::complex` type for this and all subsequent related
examples. And here you can see the full code of the generator allowing to
output a complex number either as a pair of numbers (if the imaginary part is
non-zero) or as a single number (if the complex is a real number):
[tutorial_karma_complex_number]
The `double_` generators have this semantic action attached:
_1 = n
which passes `n` to the first element of the s generator's attached
semantic action. Remember, semantic actions in __karma__ are called
before the corresponding generator is invoked and they are expected
to provide the generator with the data to be used. The semantic action
above assigns the value to be generated (`n`) to the generator (actually,
the attribute of `double_`). `_1` is a Phoenix placeholder referring to
the attribute of the semantic action's attached generator. If you need
more information about semantic actions, you may want to read about them
in this section: __karma_actions__.
These semantic actions are easy to understand but have the unexpected side
effect of being slightly less efficient than it could be. In addition they tend
to make the formatting grammar less readable. We will see in one of the next
sections how it is possible to use other, built-in features of __karma__ to get
rid of the semantic actions altogether. When writing your grammars in Spirit
you should always try to avoid semantic actions which is often possible.
Semantic actions are really powerful tools but grammars tend to be more
efficient and readable without them.
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:karma_easier_complex Complex - Made easier]
[import ../../example/karma/complex_number_easier.cpp]
In the previous section we showed how to format a complex number (i.e.
a pair of doubles). In this section we will build on this example with the goal
to avoid using semantic actions in the format specification. Let's have a look
at the resulting code first, trying to understand it afterwards (the full source
file for this example can be found here:
[@../../example/karma/complex_number_easier.cpp complex_number_easier.cpp]):
[tutorial_karma_complex_number_easier]
Let's cover some basic library features first.
[heading Making Numeric Generators Fail]
All __karma_numeric__ (such as `double_`, et.al.) take the value to
emit from an attached attribute.
double d = 1.5;
generate(out, double_, d); // will emit '1.5' (without the quotes)
Alternatively, they may be initialized from a literal value. For instance, to
emit a constant `1.5` you may write:
generate(out, double_(1.5)); // will emit '1.5' as well (without the quotes)
The difference to a simple `1.5` or `lit(1.5)` is that the `double_(1.5)`
consumes an attribute if one is available. Additionally, it compares its
immediate value to the value of the supplied attribute, and fails if those are
not equal.
double d = 1.5;
generate(out, double_(1.5), d); // will emit '1.5' as long as d == 1.5
This feature, namely to succeed generating only if the attribute matches the
immediate value, enables numeric generators to be used to dynamically control
the way output is generated.
[note Quite a few generators will fail if their immediate value is not equal
to the supplied attribute. Among those are all __karma_char__ and
all [karma_string String Generators]. Generally,
all generators having a sibling created by a variant of `lit()` belong
into this category.]
[heading Predicates - The Conditionals for Output Generators]
In addition to the __karma_eps__ generator mentioned earlier __karma__ provides
two special operators enabling dynamic flow control: the
__karma_and_predicate__ and the __karma_not_predicate__. The main property of
both predicates is to discard all output emitted by the attached generator.
This is equivalent to the behavior of predicates used for
parsing. There the predicates do not consume any input allowing to look ahead
in the input stream. In Karma, the and predicate succeeds as long as its
associated generator succeeds, while the not predicate succeeds only if its
associated generator fails.
[note The generator predicates in __karma__ consume an attribute, if
available. This makes them behave differently from predicates in __qi__,
where they do not expose any attribute. This is because predicates
allow to make decisions based on data available only at runtime. While
in __qi__ during parsing the decision is made based on looking ahead
a few more input tokens, in __karma__ the criteria has to be supplied
by the user. The simplest way to do this is by providing an attribute.]
As an example, the following generator succeeds generating
double d = 1.0;
BOOST_ASSERT(generate(out, &double_(1.0), d)); // succeeds as d == 1.0
while this one will fail:
double d = 1.0;
BOOST_ASSERT(!generate(out, !double_(1.0), d)); // fails as d == 1.0
Neither of these will emit any output. The predicates discard everything
emitted by the generators to which they are applied.
[heading Ignoring Supplied Attributes]
Sometimes it is desirable to 'skip' (i.e. ignore) a provided attribute. This
happens for instance in alternative generators, where some of the alternatives
need to extract only part of the overall attribute passed to the alternative
generator. __karma__ has a special pseudo generator for that: the directive
__karma_omit__`[]`. This directive consumes an attribute of the type defined by its
embedded generator but it does not emit any output.
[note The __karma__ __karma_omit__ directive does the 'opposite' of the
directive of the same name in __qi__. While the __qi_omit__ in __qi__
consumes input without exposing an attribute, its __karma__ counterpart
consumes an attribute without emitting any output.
]
[heading Putting everything together]
Very similar to our first example earlier we use two alternatives to allow for
the two different output formats depending on whether the imaginary part of the
complex number is equal to zero or not. The first alternative is executed if the
imaginary part is not zero, the second alternative otherwise. This time we make
the decision during runtime using the __karma_not_predicate__ combined with the
feature of many Karma primitive generators to /fail/ under certain conditions.
Here is the first alternative again for your reference:
!double_(0.0) << '(' << double_ << ", " << double_ << ')'
The generator `!double_(0.0)` does several things. First, because of the
__karma_not_predicate__, it succeeds only if the `double_(0.0)` generator
/fails/, making the whole first alternative fail otherwise. Second, the
`double_(0.0)` generator succeeds only if the value of its attribute is equal
to its immediate parameter (i.e. in this case `0.0`). And third, the
not predicate does not emit any output (regardless whether it succeeds or
fails), discarding any possibly emitted output from the `double_(0.0)`.
As we pass the imaginary part of the complex number as the attribute value for
the `!double_(0.0)`, the overall first alternative will be chosen only if
it is not equal to zero (the `!double_(0.0)` does not fail). That is exactly
what we need!
Now, the second alternative has to emit the real part of the complex
number only. In order to simplify the overall grammar we strive to unify the
attribute types of all alternatives. As the attribute type exposed by the first
alternative is `tuple<double, double, double>`, we need to skip the first and
last element of the attribute (remember, we pass the real part as the second
attribute element). We achieve this by using the `omit[]` directive:
omit[double_] << double_ << omit[double_]
The overall attribute of this expression is `tuple<double, double, double>`,
but the `omit[]` 'eats up' the first and the last element. The output emitted
by this expression consist of a single generated double representing the second
element of the tuple, i.e. the real part of our complex number.
[important Generally, it is preferable to use generator constructs not
requiring semantic actions. The reason is that semantic actions
often use constructs like: `double_[_1 = c.real()]`. But this
assignment is a real one! The data is in fact /copied/ to the
attribute value of the generator attached to the action. On the
other hand, grammars without any semantic actions usually don't
have to copy the attributes, making them more efficient.]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:karma_adapted_complex Complex - Fully Integrated]
[import ../../example/karma/complex_number_adapt.cpp]
Until now, we have been working around the fact that `std::complex<>` is not
a native __fusion__ sequence. We have not been able to use it with the same
simplicity and natural grace of a `fusion::tuple<>` or a similar __fusion__
data structure. Fortunately, starting with Boost V1.43 it is possible to
adapt any data structure (not only, as before, structures with publicly
accessible members) as a __fusion__ sequence. All we have to do is to employ one
of the new `BOOST_FUSION_ADAPT_ADT` macros.
[heading Adapting a Class As a Fusion Sequence]
Let us start with the code again, following up with the explanations afterwards.
Wouldn't it be optimal if we could pass our instance of a `std::complex<>`
directly to /Karma's/ `generate()` function:
[tutorial_karma_complex_number_adapt]
Indeed, this is possible! All we have to supply to make this work is a magic
incantation (somewhere in the global namespace):
[tutorial_karma_complex_number_adapt_class]
Most of the formatting grammar itself has not changed from the last section. We
still utilize a very similar scheme. We have an alternative providing the
formatting rules for our both use cases: one for the full complex format and
one for complex numbers with a zero imaginary part. But instead of selecting
the required alternative by comparing the imaginary part to zero in the grammar
we assume to receive a boolean attribute carrying this information:
&true_ << "(" << double_ << ", " << double_ << ")"
This reads as: 'if the first (boolean) element of the supplied fusion sequence
is `true`, proceed as specified, else select the next alternative'. The next
alternative now accounts for the boolean element as well, but is otherwise
(almost) unchanged from the last section's example.
Now it should be clear why our adapt construct above exposes a three element
__fusion__ sequence: a boolean and two double values (the real and the
imaginary part of the complex number). We want it to match the requirements of
our formatting grammar, which expects those exact values. The
`BOOST_FUSION_ADAPT_ADT` macro allows us to specify an arbitrary accessor
construct, not necessarily limited to just calling a member function of the
object instance (represented by `obj` in the context of this macro). This
allows us to nicely encapsulate the decision logic into the class adaptation.
Here is the last new bit of information. If you look closely you realize the
second alternative to be 'shorter' than the first one. It consumes only
two elements of the supplied fusion sequence: it ignores the boolean and uses
the real part of the complex number to generate its output. If there are more
elements in our attribute than needed, we now can safely omit them from the
grammar (which is a new 'feature' added to __spirit__ in V1.43 as well).
Note, we could have written the alternative as
&false_ << double_
but this would have been a bit less efficient as we needed to compare the
boolean value again, while the final solution provided will just ignore it.
[endsect]

435
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/concepts.qbk vendored Executable file
View File

@@ -0,0 +1,435 @@
[/==============================================================================
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 Generator Concepts]
__karma__ generators fall into a couple of generalized __concepts__. The
/Generator/ is the most fundamental concept. All __karma__ generators are
models of the /Generator/ concept. /PrimitiveGenerator/, /UnaryGenerator/,
/BinaryGenerator/, /NaryGenerator/, and /Nonterminal/ are all refinements of
the /Generator/ concept.
The following sections provide details on these concepts.
[/////////////////////////////////////////////////////////////////////////////]
[section Generator]
[heading Description]
The /Generator/ is the most fundamental concept. A Generator has a member
function, `generate`, that accepts an `OutputIterator` and
returns bool as its result. The iterator receives the data being generated.
The Generator's `generate` member function returns `true` if the generator
succeeds. Each Generator can represent a specific pattern or algorithm, or it
can be a more complex generator formed as a composition of other Generators.
[variablelist Notation
[[`g`] [A `Generator`.]]
[[`G`] [A `Generator` type.]]
[[`OutIter`] [An `OutputIterator` type.]]
[[`sink`] [An `OutputIterator` instance.]]
[[`Context`] [The generator's __karma_context__ type.]]
[[`context`] [The generator's __karma_context__, or __unused__.]]
[[`delimit`] [A delimiter Generator, or __unused__.]]
[[`attrib`] [A __karma_compatible_attribute__, or __unused__.]]
]
[heading Valid Expressions]
In the expressions below, the behavior of the generator, `g`, as well as how
`delimit` and `attrib` are handled by `g`, are left unspecified in the base
`Generator` concept. These are specified in subsequent, more refined concepts
and by the actual models thereof.
For any Generator the following expressions must be valid:
[table
[[Expression] [Semantics] [Return type]]
[[
``g.generate(sink, context, delimit, attrib)``]
[Generate the output sequence by inserting the
generated characters/tokens into `sink`. Use the
`delimit` generator for delimiting. Return
`true` if successful, otherwise
return `false`.] [`bool`]]
[[`g.what(context)`] [Get information about a Generator.] [__info__]]
]
[heading Type Expressions]
[table
[[Expression] [Description]]
[[`G::template attribute<Context>::type`] [The Generator's attribute.]]
[[`traits::is_generator<G>::type`] [Metafunction that evaluates to `mpl::true_` if
a certain type, `G` is a Generator, `mpl::false_`
otherwise (See __mpl_boolean_constant__).]]
[[`G::properties`] [An `mpl::int_` (See __mpl_int_constant__) holding
a value from the `karma::generator_properties`
enumeration. The default value is
`generator_properties::no_properties`]]
]
[heading Postcondition]
Upon return from `g.generate` the following post conditions should hold:
* On successful generation, `sink` receives the generated characters/tokens
sequence.
* No pre-delimits: `delimit` characters/tokens will not be emitted in front of
any other output.
* The attribute `attrib` has not been modified.
[heading Models]
All generators in __karma__ are models of the /Generator/ concept.
[endsect] [/ Generator Concept]
[/////////////////////////////////////////////////////////////////////////////]
[section PrimitiveGenerator]
[heading Description]
/PrimitiveGenerator/ is the most basic building block that the client uses
to build more complex generators.
[heading Refinement of]
[:__generator_concept__]
[heading Post-delimit]
Before exiting the `generate` member function, a PrimitiveGenerator is required
to do a post-delimit. This will generate a single delimiting character/token
sequence. Only PrimitiveGenerator's are required to perform this post-delimit.
This is typically carried out through a call to `karma::delimit_out`:
karma::delimit_out(sink, delimit);
[heading Type Expressions]
[table
[[Expression] [Description]]
[[`traits::is_primitive_generator<G>::type`] [Metafunction that evaluates to `mpl::true_` if
a certain type, `G`, is a PrimitiveGenerator, `mpl::false_`
otherwise (See __mpl_boolean_constant__).]]
]
[heading Models]
The following generators conform to this model:
* __karma_eol__,
* __karma_eps__,
* [link spirit.karma.reference.numeric Numeric generators],
* [karma_char Character generators].
__fixme__ Add more links to /PrimitiveGenerator/ models here.
[endsect] [/ PrimitiveGenerator Concept]
[/////////////////////////////////////////////////////////////////////////////]
[section UnaryGenerator]
[heading Description]
/UnaryGenerator/ is a composite generator that has a single subject. The
UnaryGenerator may change the behavior of its subject following the
__delegate_pattern__.
[heading Refinement of]
[:__generator_concept__]
[variablelist Notation
[[`g`] [A UnaryGenerator.]]
[[`G`] [A UnaryGenerator type.]]
]
[heading Valid Expressions]
In addition to the requirements defined in __generator_concept__, for any
UnaryGenerator the following must be met:
[table
[[Expression] [Semantics] [Return type]]
[[`g.subject`] [Subject generator.] [__generator_concept__]]
]
[heading Type Expressions]
[table
[[Expression] [Description]]
[[`G::subject_type`] [The subject generator type.]]
[[`traits::is_unary_generator<G>::type`] [Metafunction that evaluates to `mpl::true_` if
a certain type, `G` is a UnaryGenerator, `mpl::false_`
otherwise (See __mpl_boolean_constant__).]]
]
[heading Invariants]
For any UnaryGenerator, `G`, the following invariant always holds:
* `traits::is_generator<G::subject_type>::type` evaluates to `mpl::true_`
[heading Models]
The following generators conform to this model:
* [karma_kleene Kleene Star (unary `*`)] operator,
* __karma_plus__ operator,
* __karma_optional__ operator,
* __karma_and_predicate__ and __karma_not_predicate__ operators,
* [karma_align `left_align`], [karma_align `center`], and [karma_align `right_align`] directives,
* [karma_repeat `repeat`] directive,
* __karma_verbatim__ directive,
* [karma_delimit `delimit`] directive,
* [karma_upperlower `lower`] and [karma_upperlower `upper`] directives,
* [karma_maxwidth `maxwidth`] directive,
* __karma_buffer__ directive,
* __karma_omit__ directive.
__fixme__ Add more links to models of UnaryGenerator concept
[endsect] [/ UnaryGenerator Concept]
[/////////////////////////////////////////////////////////////////////////////]
[section BinaryGenerator]
[heading Description]
/BinaryGenerator/ is a composite generator that has a two subjects, `left` and
`right`. The BinaryGenerator allows its subjects to be treated in the same
way as a single instance of a __generator_concept__ following the
__composite_pattern__.
[heading Refinement of]
[:__generator_concept__]
[variablelist Notation
[[`g`] [A BinaryGenerator.]]
[[`G`] [A BinaryGenerator type.]]
]
[heading Valid Expressions]
In addition to the requirements defined in __generator_concept__, for any
BinaryGenerator the following must be met:
[table
[[Expression] [Semantics] [Return type]]
[[`g.left`] [Left generator.] [__generator_concept__]]
[[`g.right`] [Right generator.] [__generator_concept__]]
]
[heading Type Expressions]
[table
[[Expression] [Description]]
[[`G::left_type`] [The left generator type.]]
[[`G::right_type`] [The right generator type.]]
[[`traits::is_binary_generator<G>::type`] [Metafunction that evaluates to `mpl::true_` if
a certain type, `G` is a BinaryGenerator, `mpl::false_`
otherwise (See __mpl_boolean_constant__).]]
]
[heading Invariants]
For any BinaryGenerator, `G`, the following invariants always hold:
* `traits::is_generator<G::left_type>::type` evaluates to `mpl::true_`
* `traits::is_generator<G::right_type>::type` evaluates to `mpl::true_`
[heading Models]
The following generators conform to this model:
* __karma_list__.
__fixme__ Add more links to models of BinaryGenerator concept
[endsect] [/ BinaryGenerator Concept]
[/////////////////////////////////////////////////////////////////////////////]
[section NaryGenerator]
[heading Description]
/NaryGenerator/ is a composite generator that has one or more subjects. The
NaryGenerator allows its subjects to be treated in the same way as a single
instance of a __generator_concept__ following the __composite_pattern__.
[heading Refinement of]
[:__generator_concept__]
[variablelist Notation
[[`g`] [A NaryGenerator.]]
[[`G`] [A NaryGenerator type.]]
]
[heading Valid Expressions]
In addition to the requirements defined in __generator_concept__, for any
NaryGenerator the following must be met:
[table
[[Expression] [Semantics] [Return type]]
[[`g.elements`] [The tuple of elements.] [A __fusion__ Sequence of __generator_concept__ types.]]
]
[heading Type Expressions]
[table
[[Expression] [Description]]
[[`g.elements_type`] [Elements tuple type.]]
[[`traits::is_nary_generator<G>::type`] [Metafunction that evaluates to `mpl::true_` if
a certain type, `G` is a NaryGenerator, `mpl::false_`
otherwise (See __mpl_boolean_constant__).]]
]
[heading Invariants]
For each element, `E`, in any NaryGenerator, `G`, the following
invariant always holds:
* `traits::is_generator<E>::type` evaluates to `mpl::true_`
[heading Models]
The following generators conform to this model:
* __karma_sequence__,
* __karma_alternative__.
__fixme__ Add more links to models of NaryGenerator concept
[endsect] [/ NaryGenerator Concept]
[/////////////////////////////////////////////////////////////////////////////]
[section Nonterminal]
[heading Description]
A Nonterminal is a symbol in a __peg__ production that represents a
grammar fragment. Nonterminals may self reference to specify recursion.
This is one of the most important concepts and the reason behind the
word "recursive" in recursive descent generation.
[heading Refinement of]
[:__generator_concept__]
[heading Signature]
Nonterminals can have both consumed and inherited attributes. The
Nonterminal's /Signature/ specifies both the consumed and inherited
attributes. The specification uses the function declarator syntax:
RT(A0, A1, A2, ..., AN)
where `RT` is the Nonterminal's consumed attribute and `A0` ... `AN`
are the Nonterminal's inherited attributes.
The default value is `void()` (no consumed and inherited attributes).
[heading Attributes]
The Nonterminal models a C++ function. The Nonterminal's consumed attribute is
analogous to the function return value as it is the type -exposed- by the
Nonterminal. Its inherited attributes are analogous to function arguments.
The inherited attributes (arguments) can be passed in just like any
__karma_lazy_argument__, e.g.:
r(expr) // Evaluate expr at parse time and pass the result to the Nonterminal r
[heading `_val`]
The `boost::spirit::karma::_val` placeholder can be used in __phoenix__
semantic actions anywhere in the Nonterminal's definition. This
__phoenix__ placeholder refers to the Nonterminal's (consumed)
attribute. The `_val` placeholder acts like an immutable reference to the
Nonterminal's attribute.
[note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the
placeholder `_val` can be used in semantic actions attached to top level
generator components as well. See __generator_api__ for more information.]
[heading `_r1`...`r10`]
The `boost::spirit::_r1`...`boost::spirit::r10` placeholders can be used
in __phoenix__ semantic actions anywhere in the Nonterminal's
definition. These __phoenix__ placeholders refer to the Nonterminal's
inherited attributes.
[heading Locals]
Nonterminals can have local variables that will be created on the stack
at runtime. A locals descriptor added to the Nonterminal declaration
will give the Nonterminal local variables:
template <typename T0, typename T1, typename T2, ..., typename TN>
struct locals;
where `T0` ... `TN` are the types of local variables accessible in your
__phoenix__ semantic actions using the placeholders:
* `boost::spirit::_a`
* `boost::spirit::_b`
* `boost::spirit::_c`
* `boost::spirit::_d`
* `boost::spirit::_e`
* `boost::spirit::_f`
* `boost::spirit::_g`
* `boost::spirit::_h`
* `boost::spirit::_i`
* `boost::spirit::_j`
which correspond to the Nonterminal's local variables `T0` ... `T9`.
[variablelist Notation
[[`x`] [A Nonterminal]]
[[`X`] [A Nonterminal type]]
[[`arg1`, `arg2`, ..., `argN`] [__karma_lazy_arguments__ that evaluate to each of
the Nonterminal's inherited attributes.]]
]
[heading Valid Expressions]
In addition to the requirements defined in __generator_concept__, for any
Nonterminal the following must be met:
[table
[[Expression] [Semantics] [Return type]]
[[`x`] [In a generator expression, invoke Nonterminal `x`] [`X`]]
[[`x(arg1, arg2, ..., argN)`][In a generator expression, invoke Nonterminal `x`
passing in inherited attributes
`arg1`...`argN`] [`X`]]
[[`x.name(name)`] [Set the name of a Nonterminal] [`void`]]
[[`x.name()`] [Get the name of a Nonterminal] [`std::string`]]
]
[heading Type Expressions]
[table
[[Expression] [Description]]
[[`X::sig_type`] [The Signature of `X`: In a function signature form
as described above in the Signature paragraph.]]
[[`X::locals_type`] [The local variables of `X`: An __mpl_fwd_sequence__.]]
]
[heading Models]
* __karma_rule__
* __karma_grammar__
[endsect]
[endsect]

1307
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/directive.qbk vendored Executable file
View File

File diff suppressed because it is too large Load Diff

394
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/generate_api.qbk vendored Executable file
View File

@@ -0,0 +1,394 @@
[/==============================================================================
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:generate_api Generator API]
[//////////////////////////////////////////////////////////////////////////////]
[section:iterator_api Iterator Based Generator API]
[heading Description]
The library provides a couple of free functions to make generating a snap.
These generator functions have two forms. The first form, `generate`,
concatenates the output generated by the involved components without inserting
any output in between. The second `generate_delimited` intersperses the output
generated by the involved components using the given delimiter generator.
Both versions can take in attributes by (constant) reference that hold the
attribute values to output.
[heading Header]
// forwards to <boost/spirit/home/karma/generate.hpp>
#include <boost/spirit/include/karma_generate.hpp>
For variadic attributes:
// forwards to <boost/spirit/home/karma/generate_attr.hpp>
#include <boost/spirit/include/karma_generate_attr.hpp>
The variadic attributes version of the API allows one or more
attributes to be passed into the `generate` functions. The functions taking two
or more attributes are usable when the generator expression is a
__karma_sequence__ only. In this case each of the
attributes passed have to match the corresponding part of the sequence.
For the API functions deducing the correct (matching) generator type from the
supplied attribute type:
// forwards to <boost/spirit/home/karma/detail/generate_auto.hpp>
#include <boost/spirit/include/karma_generate_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::generate` ]]
[[`boost::spirit::karma::generate_delimited` ]]
[[`boost::spirit::karma::delimit_flag::predelimit` ]]
[[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
]
[heading Synopsis]
namespace boost { namespace spirit { namespace karma
{
template <typename OutputIterator, typename Expr>
inline bool
generate(
OutputIterator& sink
, Expr const& expr);
template <typename OutputIterator, typename Expr
, typename Attr1, typename Attr2, ..., typename AttrN>
inline bool
generate(
OutputIterator& sink
, Expr const& expr
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename OutputIterator, typename Expr, typename Delimiter>
inline bool
generate_delimited(
OutputIterator& sink
, Expr const& expr
, Delimiter const& delimiter
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename OutputIterator, typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline bool
generate_delimited(
OutputIterator& sink
, Expr const& expr
, Delimiter const& delimiter
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename OutputIterator, typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline bool
generate_delimited(
OutputIterator& sink
, Expr const& expr
, Delimiter const& delimiter
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
}}}
[note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the
placeholder `_val` can be used in semantic actions attached to top level
generator components. In this case `_val` refers to the supplied attribute
as a whole. For API functions taking more than one attribute argument
`_val` will refer to a Fusion vector or references to the attributes.]
__karma__ generator API functions based on the automatic creation of the
matching generator type:
namespace boost { namespace spirit { namespace karma
{
template <typename OutputIterator, typename Attr, typename Delimiter>
inline bool
generate_delimited(
OutputIterator& sink
, Attr const& attr
, Delimiter const& delimiter
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename OutputIterator, typename Attr>
inline bool
generate(
OutputIterator& sink
, Attr const& attr);
}}}
All functions above return `true` if none of the involved generator components
failed, and `false` otherwise. If during the process of the output generation
the underlying output stream reports an error, the return value will be `false`
as well.
The maximum number of supported arguments is limited by the preprocessor
constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
[note The variadic functions with two or more attributes internally combine
(constant) references to all passed attributes into a `fusion::vector`
and forward this as a combined attribute to the corresponding function
taking one attribute.]
The `generate_delimited` functions not taking an explicit `delimit_flag` as one
of their arguments don't invoke the passed delimiter before starting to generate
output from the generator expression. This can be enabled by using the other
version of that function while passing `delimit_flag::predelimit` to the
corresponding argument.
[heading Template parameters]
[table
[[Parameter] [Description]]
[[`OutputIterator`] [__outputiter__ receiving the generated output.]]
[[`Expr`] [An expression that can be converted to a Karma generator.]]
[[`Delimiter`] [Generator used to delimit the output of the expression components.]]
[[`Attr`] [An attribute type utilized to create the corresponding
generator type from.]]
[[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
]
[endsect] [/ Iterator Based Generator API]
[//////////////////////////////////////////////////////////////////////////////]
[section:stream_api Stream Based Generator API]
[heading Description]
The library provides a couple of Standard IO __iomanip__ allowing to integrate
__karma__ output generation facilities with Standard output streams.
These generator manipulators have two forms. The first form, `format`,
concatenates the output generated by the involved components without inserting
any output in between. The second, `format_delimited`, intersperses the output
generated by the involved components using the given delimiter generator.
Both versions can take in attributes by (constant) reference that hold the
attribute values to output.
[heading Header]
// forwards to <boost/spirit/home/karma/stream/format_manip.hpp>
#include <boost/spirit/include/karma_format.hpp>
For variadic attributes:
// forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp>
#include <boost/spirit/include/karma_format_attr.hpp>
The variadic attributes version of the API allows one or more
attributes to be passed into the `format` manipulators. The manipulators taking
two or more attributes are usable when the generator expression is a
__karma_sequence__ only. In this case each of the attributes passed have to
match the corresponding part of the sequence.
For the API functions deducing the correct (matching) generator type from the
supplied attribute type:
// forwards to <boost/spirit/home/karma/format_auto.hpp>
#include <boost/spirit/include/karma_format_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::format` ]]
[[`boost::spirit::karma::format_delimited` ]]
[[`boost::spirit::karma::delimit_flag::predelimit` ]]
[[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
]
[heading Synopsis]
namespace boost { namespace spirit { namespace karma
{
template <typename Expr>
inline <unspecified>
format(
Expr const& xpr);
template <typename Expr
, typename Attr1, typename Attr2, ..., typename AttrN>
inline <unspecified>
format(
Expr const& xpr
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename Expr, typename Delimiter>
inline <unspecified>
format_delimited(
Expr const& expr
, Delimiter const& d
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline <unspecified>
format_delimited(
Expr const& expr
, Delimiter const& d
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline <unspecified>
format_delimited(
Expr const& expr
, Delimiter const& d
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
}}}
__karma__ generator API functions based on the automatic creation of the
matching generator type:
namespace boost { namespace spirit { namespace karma
{
template <typename Attr, typename Delimiter>
inline <unspecified>
format_delimited(
Attr const& attr
, Delimiter const& d
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename Attr>
inline <unspecified>
format(
Attr const& xpr);
}}}
All functions above return a standard IO stream manipulator instance (see
__iomanip__), which when streamed to an output stream will result in generating
the output as emitted by the embedded __karma__ generator expression. Any error
occurring during the invocation of the __karma__ generators will be reflected
in the streams status flag (`std::ios_base::failbit` will be set).
The maximum number of supported arguments is limited by the preprocessor
constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
[note The variadic manipulators with two or more attributes internally combine
(constant) references to all passed attributes into a `fusion::vector`
and forward this as a combined attribute to the corresponding manipulator
taking one attribute.]
The `format_delimited` manipulators not taking an explicit `delimit_flag` as one
of their arguments don't invoke the passed delimiter before starting to generate
output from the generator expression. This can be enabled by using the other
version of that manipulator while passing `delimit_flag::predelimit` to the
corresponding argument.
[heading Template parameters]
[table
[[Parameter] [Description]]
[[`Expr`] [An expression that can be converted to a Karma generator.]]
[[`Delimiter`] [Generator used to delimit the output of the expression components.]]
[[`Attr`] [An attribute type utilized to create the corresponding
generator type from.]]
[[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
]
[endsect] [/ Stream Based Generator API]
[//////////////////////////////////////////////////////////////////////////////]
[section:create_generator API for Automatic Generator Creation]
[heading Description]
The library implements a special API returning a generator instance for a
supplied attribute type. This function finds the best matching generator type
for the attribute based on a set of simple matching rules (as outlined in the
table below) applied recursively to the attribute type. The returned generator
can be utilized to emit output for the provided attribute.
[heading Header]
// forwards to <boost/spirit/home/karma/auto.hpp>
#include <boost/spirit/include/karma_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::create_generator`]]
[[`boost::spirit::traits::create_generator_exists`]]
]
[heading Synopsis]
namespace boost { namespace spirit { namespace karma
{
template <typename Attr>
inline <unspecified>
create_generator();
}}}
The returned instance can be directly passed as the generator (or the
delimiting generator) to any of the __karma__ API functions. Additionally it
can be assigned to a rule as the rules right hand side expression. This
function will return a valid generator type only if the meta function
`traits::create_generator_exists` returns `mpl::true_`. Otherwise it will fail
compiling.
namespace boost { namespace spirit { namespace traits
{
template <typename Attr>
struct create_generator_exists;
}}}
The meta function evaluates to `mpl::true_` if `create_generator` would return
a valid generator for the given type `Attr`.
The following table outlines the mapping rules from the attribute type to the
generator type. These rules are applied recursively to create the generator
type which can be used to generate output from the given attribute type.
[table
[[Attribute type] [Generator type]]
[[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]]
[[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
[[`unsigned short`, `unsigned int`, `unsigned long`]
[`ushort_`, `uint_`, `ulong_`]]
[[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]]
[[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
[[`long long`, `unsigned long long`]
[`long_long`, `ulong_long`]]
[[`bool`] [`bool_`]]
[[Any string (`char const*`, `std::string`, etc.)]
[`string`]]
[[Any (STL) container] [Kleene Star (unary `'*'`)]]
[[Any Fusion sequence] [Sequence operator (`'<<'`)]]
[[`boost::optional<>`] [Optional operator (unary `'-'`)]]
[[`boost::variant<>`] [Alternative operator (`'|'`)]]
]
[important The mapping for the generators `long_long` and `ulong_long` are only
available on platforms where the preprocessor constant
`BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native
support for `long long` and `unsigned long long` (64 bit) signed and
unsigned integer types).]
[heading Template parameters]
[table
[[Parameter] [Description]]
[[`Attr`] [An attribute type utilized to create the corresponding
generator type from.]]
]
[endsect] [/ API for Automatic Generator Creation]
[endsect]

267
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/nonterminal.qbk vendored Executable file
View File

@@ -0,0 +1,267 @@
[/==============================================================================
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:nonterminal Nonterminal Generators]
[heading Module Headers]
// forwards to <boost/spirit/home/karma/nonterminal.hpp>
#include <boost/spirit/include/karma_nonterminal.hpp>
Also, see __include_structure__.
[//////////////////////////////////////////////////////////////////////////////]
[section:rule Generator Rule]
[heading Description]
The rule is a polymorphic generator that acts as a named place-holder
capturing the behavior of a PEG expression assigned to it. Naming a
__peg__ expression allows it to be referenced later and makes it
possible for the rule to call itself. This is one of the most important
mechanisms and the reason behind the word "recursive" in recursive
descent output generation.
[heading Header]
// forwards to <boost/spirit/home/karma/nonterminal/rule.hpp>
#include <boost/spirit/include/karma_rule.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::rule`]]
]
[heading Synopsis]
template <typename OutputIterator, typename A1, typename A2, typename A3>
struct rule;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`OutputIterator`] [The underlying output iterator
type that the rule is
expected to work on.] [none]]
[[`A1`, `A2`, `A3`] [Either `Signature`,
`Delimiter` or `Locals` in
any order. See table below.] [See table below.]]
]
Here is more information about the template parameters:
[table
[[Parameter] [Description] [Default]]
[[`Signature`] [Specifies the rule's consumed
(value to output) and inherited
(arguments) attributes. More on
this here: __karma_nonterminal_concept__.]
[__unused_type__.
When `Signature` defaults
to __unused_type__, the effect
is the same as specifying a signature
of `void()` which is also equivalent
to `unused_type()`]]
[[`Delimiter`] [Specifies the rule's delimiter
generator. Specify this if you
want the rule to delimit the
generated output.] [__unused_type__]]
[[`Locals`] [Specifies the rule's local
variables. See __karma_nonterminal_concept__.]
[__unused_type__]]
]
[heading Model of]
[:__karma_nonterminal_concept__]
[variablelist Notation
[[`r, r2`] [Rules]]
[[`g`] [A generator expression]]
[[`OutputIterator`] [The underlying output iterator type that the rule is
expected to work on.]]
[[`A1`, `A2`, `A3`] [Either `Signature`, `Delimiter` or `Locals` in
any order.]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __karma_nonterminal_concept__.
[table
[[Expression] [Description]]
[[
``rule<OutputIterator, A1, A2, A3>
r(name);``]
[Rule declaration. `OutputIterator` is required.
`A1, A2, A3` are optional and can be specified in any order.
`name` is an optional string that gives the rule
its name, useful for debugging.]]
[[
``rule<OutputIterator, A1, A2, A3>
r(r2);``] [Copy construct rule `r` from rule `r2`.]]
[[`r = r2;`] [Assign rule `r2` to `r`.]]
[[`r.alias()`] [Return an alias of `r`. The alias is a generator that
holds a reference to `r`. Reference semantics.]]
[[`r.copy()`] [Get a copy of `r`.]]
[[`r = g;`] [Rule definition]]
[[`r %= g;`] [Auto-rule definition. The attribute of `g` should be
compatible with the consumed attribute of `r`.]]
[[`r.name()`] [Retrieve the current name of the rule object.]]
[[`r.name(name)`] [Set the current name of the rule object to be `name`.]]
]
[heading Attributes]
[:The rule's generator attribute is `RT`: The consumed attribute of the
rule. See __karma_nonterminal_attribute__]
[heading Complexity]
[:The complexity is defined by the complexity of the RHS generator, `g`]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
[karma_reference_rule]
[endsect] [/ Rule]
[////////////////////////////////////////////////////////////////////////////////]
[section:grammar Generator Grammar]
[heading Description]
The grammar encapsulates a set of __karma_rules__ (as well as primitive
generators (__primitive_generator_concept__) and sub-grammars). The grammar is
the main mechanism for modularization and composition. Grammars can be
composed to form more complex grammars.
[heading Header]
// forwards to <boost/spirit/home/karma/nonterminal/grammar.hpp>
#include <boost/spirit/include/karma_grammar.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::grammar`]]
]
[heading Synopsis]
template <typename OutputIterator, typename A1, typename A2, typename A3>
struct grammar;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`OutputIterator`] [The underlying output iterator
type that the rule is
expected to work on.] [none]]
[[`A1`, `A2`, `A3`] [Either `Signature`,
`Delimiter` or `Locals` in
any order. See table below.] [See table below.]]
]
Here is more information about the template parameters:
[table
[[Parameter] [Description] [Default]]
[[`Signature`] [Specifies the grammar's synthesized
(return value) and inherited
attributes (arguments). More on
this here: __karma_nonterminal_concept__.]
[__unused_type__.
When `Signature` defaults
to __unused_type__, the effect
is the same as specifying a signature
of `void()` which is also equivalent
to `unused_type()`]]
[[`Delimiter`] [Specifies the grammar's delimiter
generator. Specify this if you
want the grammar to delimit the
generated output.] [__unused_type__]]
[[`Locals`] [Specifies the grammar's local
variables. See __karma_nonterminal_concept__.]
[__unused_type__]]
]
[heading Model of]
[:__karma_nonterminal_concept__]
[variablelist Notation
[[`g`] [A grammar]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is not
defined in __karma_nonterminal_concept__.
[table
[[Expression] [Semantics]]
[[
``
template <typename OutputIterator>
struct my_grammar : grammar<OutputIterator, A1, A2, A3>
{
my_grammar() : my_grammar::base_type(start, name)
{
// Rule definitions
start = /* ... */;
}
rule<OutputIterator, A1, A2, A3> start;
// more rule declarations...
};
``
] [Grammar definition. `name` is an optional string that gives the
grammar its name, useful for debugging.]]
]
[note The template parameters of a grammar and its start rule (the rule passed
to the grammar's base class constructor) must match, otherwise you will
see compilation errors.]
[heading Attributes]
[:The generator attribute of the grammar is `RT`, its consumed attribute. See
__karma_nonterminal_attribute__]
[heading Complexity]
[:The complexity is defined by the complexity of the its definition.]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
[karma_reference_grammar_using]
[karma_reference_grammar_definition]
[karma_reference_grammar]
[endsect] [/ Grammar]
[endsect]

108
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/num_list.qbk vendored Executable file
View File

@@ -0,0 +1,108 @@
[/==============================================================================
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:num_list Number List - Printing Numbers From a std::vector]
[heading Using the List Operator]
The C++ Standard library lacks an important feature, namely the support for
any formatted output of containers. Sure, it's fairly easy to write a custom
routine to output a specific container, but doing so over and over again is
tedious at best. In this section we will demonstrate some more of the
capabilities of __karma__ for generating output from arbitrary STL containers.
We will build on the example presented in an earlier section (see
[link spirit.karma.tutorials.warming_up Warming Up]).
The full source code of the example shown in this section can be found here:
[@../../example/karma/num_list2.cpp num_list2.cpp].
[import ../../example/karma/num_list2.cpp]
This time we take advantage of Karma's __karma_list__ operator. The semantics
of the list operator are fully equivalent to the semantics of the sequence
we used before. The generator expression
double_ << *(',' << double_)
is semantically equivalent to the generator expression
double_ % ','
simplifying the overall code. The list operator's attribute is compatible with
any STL container as well. For a change we use a `std::vector<double>`
instead of the `std::list<double>` we used before. Additionally, the routine
`generate_numbers` takes the container as a template parameter, so it will now
work with any STL container holding `double` numbers.
[tutorial_karma_numlist2]
[note Despite the container being a template parameter, the __karma__
formatting expression (`double_ % ','`) does not depend on the actual
type of the passed container. The only precondition to be met here is
that the elements stored in the container have to be convertible to
`double`.]
[heading Generate Output from Arbitrary Data]
The output routine developed above is still not generically usable for all types
of STL containers and for arbitrary elements stored in them. In order to be
usable the items stored in the container still need to be convertible to a
`double`. Fortunately __karma__ is capable to output arbitrary
data types while using the same format description expression. It implements
the [karma_stream `stream`] generators which are able to consume any attribute
type as long as a matching standard streaming operator is defined. I.e.
for any attribute type `Attrib` a function:
std::ostream& operator<< (std::ostream&, Attrib const&);
needs to be available. The [karma_stream `stream`] generator will use the
standard streaming operator to generate the output.
The following example modifies the code shown above to utilize the
[karma_stream `stream`] operator, which makes it compatible with almost any
data type. We implement a custom data type `complex` to demonstrate this. The
example shows how it is possible to integrate this (or any other) custom data
type into the __karma__ generator framework.
[import ../../example/karma/num_list3.cpp]
This is the custom data structure together with the required standard streaming
operator:
[tutorial_karma_numlist3_complex]
And this is the actual call to generate the output from a vector of those. This
time we interleave the generated output with newline breaks (see
__karma_eol__), putting each complex number onto a separate line:
[tutorial_karma_numlist3]
The code shown is fully generic and can be used with any STL container as long
as the data items stored in that container implement the standard streaming
operator.
The full source code of the example presented in this section can be found here:
[@../../example/karma/num_list3.cpp num_list3.cpp].
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:num_matrix Matrix of Numbers - Printing Numbers From a Matrix]
In this section we will discuss the possibilities of __karma__ when it comes to
generating output from more complex - but still regular - data structures.
For simplicity we will use a `std::vector<std::vector<int> >` as a poor
man's matrix representation. But even if the data structure seems to be very
simple, the presented principles are applicable to more complex, or custom
data structures as well. The full source code of the example discussed in this
section can be found here: [@../../example/karma/num_matrix.cpp num_matrix.cpp].
[import ../../example/karma/num_matrix.cpp]
[endsect]

1369
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/numeric.qbk vendored Executable file
View File

File diff suppressed because it is too large Load Diff

169
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/numeric_performance.qbk vendored Executable file
View File

@@ -0,0 +1,169 @@
[/==============================================================================
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:numeric_performance Performance of Numeric Generators]
[section:int_performance Comparing the performance of a single int_ generator]
These performance measurements are centered around default formatting of a
single `int` integer number using different libraries and methods.
The overall execution times for those examples are compared below. We compare
using `sprintf`, C++ iostreams, __boost_format__, and __karma__.
For the full source code of the performance test please see here:
[@../../workbench/karma/int_generator.cpp int_generator.cpp]. All the
measurements have been done by executing `1e7` iterations for each
formatting type (NUMITERATIONS is set to `1e7` in the code shown below).
[import ../../workbench/karma/int_generator.cpp]
Code used to measure the performance for `ltoa`:
[karma_int_performance_ltoa]
Code used to measure the performance for standard C++ iostreams:
[karma_int_performance_iostreams]
Code used to measure the performance for __boost_format__:
[karma_int_performance_format]
Code used to measure the performance for __karma__ using a plain character buffer:
[karma_int_performance_plain]
The following table shows the overall performance results collected
while using different compilers. All times are in seconds measured for `1e7`
iterations (platform: Windows7, Intel Core Duo(tm) Processor, 2.8GHz, 4GByte RAM).
For a more readable comparison of the results see this
[link spirit.karma.int_performance figure].
[table Performance comparison for a single int (all times in [s], `1e7` iterations)
[[Library] [gcc 4.4.0 (32 bit)] [VC++ 10 (32 bit)] [Intel 11.1 (32 bit)] [gcc 4.4.0 (64 bit)] [VC++ 10 (64 bit)] [Intel 11.1 (64 bit)]]
[[ltoa] [1.542] [0.895] [0.884] [1.163] [1.099] [0.906]]
[[iostreams] [6.548] [13.727] [11.898] [3.464] [8.316] [8.115]]
[[__boost_format__] [16.998] [21.813] [20.477] [17.464] [14.662] [13.646]]
[[__karma__ int_] [1.421] [0.744] [0.697] [1.072] [0.953] [0.606]]
]
[fig int_performance.png..Performance comparison for a single int..spirit.karma.int_performance]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:double_performance Comparing the performance of a single double_ generator]
These performance measurements are centered around default formatting of a
single `double` floating point number using different libraries and methods.
The overall execution times for those examples are compared below. We compare
using `sprintf`, C++ iostreams, __boost_format__, and __karma__.
For the full source code of the performance test please see here:
[@../../workbench/karma/double_performance.cpp double_performance.cpp]. All the
measurements have been done by executing `1e6` iterations for each
formatting type (NUMITERATIONS is set to `1e6` in the code shown below).
[import ../../workbench/karma/double_performance.cpp]
Code used to measure the performance for `sprintf`:
[karma_double_performance_printf]
Code used to measure the performance for standard C++ iostreams:
[karma_double_performance_iostreams]
Code used to measure the performance for __boost_format__:
[karma_double_performance_format]
The following code shows the common definitions used by all __karma__ performance
measurements as listed below:
[karma_double_performance_definitions]
Code used to measure the performance for __karma__ using a plain character buffer:
[karma_double_performance_plain]
The following table shows the overall performance results collected
while using different compilers. All times are in seconds measured for `1e6`
iterations (platform: Windows7, Intel Core Duo(tm) Processor, 2.8GHz, 4GByte RAM).
For a more readable comparison of the results see this
[link spirit.karma.double_performance figure].
[table Performance comparison for a single double (all times in [s], `1e6` iterations)
[[Library] [gcc 4.4.0 (32 bit)] [VC++ 10 (32 bit)] [Intel 11.1 (32 bit)] [gcc 4.4.0 (64 bit)] [VC++ 10 (64 bit)] [Intel 11.1 (64 bit)]]
[[sprintf] [0.755] [0.965] [0.880] [0.713] [0.807] [0.694]]
[[iostreams] [2.316] [2.624] [1.964] [1.634] [1.468] [1.354]]
[[__boost_format__] [3.188] [3.737] [2.878] [3.217] [2.672] [2.011]]
[[__karma__ double_] [0.813] [0.561] [0.368] [0.426] [0.260] [0.218]]
]
[fig double_performance.png..Performance comparison for a single double..spirit.karma.double_performance]
[endsect]
[////////////////////////////////////////////////////////////////////////////]
[section:format_performance Comparing the performance of a sequence of several generators]
These performance measurements are centered around formatting of a sequence of
different items, including 2 `double` floating point numbers using different
libraries and methods. The overall execution times for those examples are
compared below. We compare using `sprintf`, C++ iostreams, __boost_format__,
and __karma__.
For the full source code of the performance test please see here:
[@../../workbench/karma/format_performance.cpp format_performance.cpp]. All the
measurements have been done by doing `1e6` iterations for each formatting
type (NUMITERATIONS is set to `1e6`).
[import ../../workbench/karma/format_performance.cpp]
Code used to measure the performance for sprintf:
[karma_format_performance_printf]
Code used to measure the performance for standard iostreams:
[karma_format_performance_iostreams]
Code used to measure the performance for __boost_format__:
[karma_format_performance_format]
The following code shows the common definitions used by all __karma__
performance measurements as listed below:
[karma_format_performance_definitions]
Code used to measure the performance for __karma__ using a plain character
buffer:
[karma_format_performance_plain]
The following table shows the overall performance results collected
while using different compilers. All times are in seconds measured for `1e6`
iterations (platform: Windows7, Intel Core Duo(tm) Processor, 2.8GHz, 4GByte RAM).
For a more readable comparison of the results see this
[link spirit.karma.format_performance figure].
[table Performance comparison for a sequence of several items (all times in [s], `1e6` iterations)
[[Library] [gcc 4.4.0 (32 bit)] [VC++ 10 (32 bit)] [Intel 11.1 (32 bit)] [gcc 4.4.0 (64 bit)] [VC++ 10 (64 bit)] [Intel 11.1 (64 bit)]]
[[sprintf] [1.725] [1.892] [1.903] [1.469] [1.608] [1.493]]
[[iostreams] [4.827] [5.287] [4.444] [3.112] [3.319] [2.877]]
[[__boost_format__] [5.881] [7.089] [5.801] [5.455] [5.254] [4.164]]
[[__karma__] [1.942] [1.242] [0.999] [1.334] [0.758] [0.686]]
]
[fig format_performance.png..Performance comparison for a sequence of several items..spirit.karma.format_performance]
[endsect]
[endsect]

816
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/operator.qbk vendored Executable file
View File

@@ -0,0 +1,816 @@
[/==============================================================================
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]

687
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/quick_reference.qbk vendored Executable file
View File

@@ -0,0 +1,687 @@
[/==============================================================================
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)
===============================================================================/]
This quick reference section is provided for convenience. You can use
this section as sort of a "cheat-sheet" on the most commonly used Karma
components. It is not intended to be complete, but should give you an
easy way to recall a particular component without having to dig up on
pages upon pages of reference documentation.
[/////////////////////////////////////////////////////////////////////////////]
[section Common Notation]
[variablelist Notation
[[`G`] [Generator type]]
[[`g, a, b, c, d`] [Generator objects]]
[[`A, B, C, D`] [Attribute types of generators `a`, `b`, `c`, and `d`]]
[[`I`] [The iterator type used for generation]]
[[`Unused`] [An `unused_type`]]
[[`Context`] [The enclosing rule's `Context` type]]
[[`attrib`] [An attribute value]]
[[`Attrib`] [An attribute type]]
[[`b`] [A boolean expression]]
[[`B`] [A type to be interpreted in boolean expressions]]
[[`fg`] [A (lazy generator) function with signature `G(Unused, Context)`]]
[[`fa`] [A (semantic action) function with signature `void(Attrib&, Context, bool&)`.
The third parameter is a boolean flag that can be set to false to
force the generator to fail. Both `Context` and the boolean flag are
optional.]]
[[`outiter`] [An output iterator to receive the generated output]]
[[`Ch`] [Character-class specific character type (See __char_class_types__)]]
[[`ch, ch2`] [Character-class specific character (See __char_class_types__)]]
[[`charset`] [Character-set specifier string (example: `"a-z0-9"`)]]
[[`str`] [Character-class specific string (See __char_class_types__)]]
[[`Str`] [Attribute of `str`: `std::basic_string<T>` where `T` is the underlying character type of `str`]]
[[`num`] [Numeric literal, any integer or real number type]]
[[`Num`] [Attribute of `num`: any integer or real number type]]
[[`tuple<>`] [Used as a placeholder for a fusion sequence]]
[[`vector<>`] [Used as a placeholder for an STL container]]
[[`variant<>`] [Used as a placeholder for a boost::variant]]
[[`optional<>`] [Used as a placeholder for a boost::optional]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:primitive_generators Karma Generators]
[section:char Character Generators]
See here for more information about __karma_char__.
[table
[[Expression] [Attribute] [Description]]
[[[karma_char `ch`]] [`Unused`] [Generate `ch`]]
[[[karma_char `lit(ch)`]] [`Unused`] [Generate `ch`]]
[[[karma_char `char_`]] [`Ch`] [Generate character supplied as the attribute]]
[[[karma_char `char_(ch)`]] [`Ch`] [Generate `ch`,
if an attribute is supplied it must match]]
[[[karma_char `char_("c")`]] [`Ch`] [Generate a single char string literal, `c`,
if an attribute is supplied it must match]]
[[[karma_char `char_(ch, ch2)`]][`Ch`] [Generate the character supplied as the attribute,
if it belongs to the character range from
`ch` to `ch2`]]
[[[karma_char `char_(charset)`]][`Ch`] [Generate the character supplied as the attribute,
if it belongs to the character set `charset`]]
[[[karma_char_class `alnum`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isalnum` in
the character set defined by `NS`]]
[[[karma_char_class `alpha`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isalpha` in
the character set defined by `NS`]]
[[[karma_char_class `blank`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isblank` in
the character set defined by `NS`]]
[[[karma_char_class `cntrl`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::iscntrl` in
the character set defined by `NS`]]
[[[karma_char_class `digit`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isdigit` in
the character set defined by `NS`]]
[[[karma_char_class `graph`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isgraph` in
the character set defined by `NS`]]
[[[karma_char_class `print`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isprint` in
the character set defined by `NS`]]
[[[karma_char_class `punct`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::ispunct` in
the character set defined by `NS`]]
[[[karma_char_class `space`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isspace`, or
a single space character in the character set
defined by `NS`]]
[[[karma_char_class `xdigit`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isxdigit` in
the character set defined by `NS`]]
[[[karma_char_class `lower`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::islower` in
the character set defined by `NS`]]
[[[karma_char_class `upper`]] [`Ch`] [Generate the character supplied as the attribute
if it satisfies the concept of `std::isupper` in
the character set defined by `NS`]]
]
[endsect]
[section:string String Generators]
See here for more information about [karma_string String Generators].
[table
[[Expression] [Attribute] [Description]]
[[[karma_string `str`]] [`Unused`] [Generate `str`]]
[[[karma_string `lit(str)`]] [`Unused`] [Generate `str`]]
[[[karma_string `string`]] [`Str`] [Generate string supplied as the attribute]]
[[[karma_string `string(str)`]] [`Str`] [Generate `str`,
if an attribute is supplied it must match]]
[[[karma_symbols `symbols<Attr, T>`]][`Attr`] [Declare a symbol table, `sym`. `Attr` is the
The type of the original attribute to be used
as the key into the symbol generator.
`T` is the data type associated with each key.]]
[[
``
sym.add
(attr1, val1)
(attr2, val2)
/*...more...*/
;
``
]
[N/A] [Add symbols into a symbol table, `sym`.
val1 and val2 are optional data of type `T`,
the data type associated with each key.]]
[[`sym`] [`T`] [Emits entries in the symbol table, `sym`. If
attribute is found in the symbol table,
the corresponding value is emitted. If `sym`
does not store values, the original attribute
is emitted.]]
]
[endsect]
[section:real_number Real Number Generators]
See here for more information about __karma_numeric__.
[table
[[Expression] [Attribute] [Description]]
[[[real_number `lit(num)`]] [`Unused`] [Generate `num`]]
[[[real_number `float_`]] [`float`] [Generate a real number from a `float`]]
[[[real_number `float_(num)`]] [`float`] [Generate `num` as a real number from a `float`,
if an attribute is supplied it must match `num`]]
[[[real_number `double_`]] [`double`] [Generate a real number from a `double`]]
[[[real_number `double_(num)`]] [`double`] [Generate a `num` as a real number from a `double`,
if an attribute is supplied it must match `num`]]
[[[real_number `long_double`]] [`long double`] [Generate a real number from a `long double`]]
[[[real_number `long_double(num)`]] [`long double`] [Generate `num` as a real number from a `long double`,
if an attribute is supplied it must match `num`]]
[[[real_number ``real_generator<
Num, Policies
>()``]]
[`Num`] [Generate a real number `Num` using
the supplied real number formatting policies]]
[[[real_number ``real_generator<
Num, Policies
>()(num)``]]
[`Num`] [Generate real number `num` as a `Num`
using the supplied real number formatting
policies, if an attribute is supplied it must
match]]
]
[endsect]
[section:signed_int Integer Generators]
[table
[[Expression] [Attribute] [Description]]
[[[signed_int `lit(num)`]] [`Unused`] [Generate `num`]]
[[[signed_int `short_`]] [`short`] [Generate a short integer]]
[[[signed_int `short_(num)`]] [`short`] [Generate `num` as a short integer,
if an attribute is supplied it must match]]
[[[signed_int `int_`]] [`int`] [Generate an int]]
[[[signed_int `int_(num)`]] [`int`] [Generate `num` as an int,
if an attribute is supplied it must match]]
[[[signed_int `long_`]] [`long`] [Generate a long integer]]
[[[signed_int `long_(num)`]] [`long`] [Generate `num` as long integer,
if an attribute is supplied it must match]]
[[[signed_int `long_long`]] [`long long`] [Generate a long long]]
[[[signed_int `long_long(num)`]] [`long long`] [Generate `num` as a long long,
if an attribute is supplied it must match]]
[[[signed_int ``int_generator<
Num, Radix, force_sign
>()``]]
[`Num`] [Generate a `Num`]]
[[[signed_int ``int_generator<
Num, Radix, force_sign
>()(num)``]]
[`Num`] [Generate a `num` as a `Num`,
if an attribute is supplied it must match]]
]
[endsect]
[section:unsigned_int Unsigned Integer Generators]
[table
[[Expression] [Attribute] [Description]]
[[[unsigned_int `lit(num)`]] [`Unused`] [Generate `num`]]
[[[unsigned_int `ushort_`]] [`unsigned short`] [Generate an unsigned short integer]]
[[[unsigned_int `ushort_(num)`]] [`unsigned short`] [Generate `num` as an unsigned short integer,
if an attribute is supplied it must match]]
[[[unsigned_int `uint_`]] [`unsigned int`] [Generate an unsigned int]]
[[[unsigned_int `uint_(num)`]] [`unsigned int`] [Generate `num` as an unsigned int,
if an attribute is supplied it must match]]
[[[unsigned_int `ulong_`]] [`unsigned long`] [Generate an unsigned long integer]]
[[[unsigned_int `ulong_(num)`]] [`unsigned long`] [Generate `num` as an unsigned long integer,
if an attribute is supplied it must match]]
[[[unsigned_int `ulong_long`]] [`unsigned long long`] [Generate an unsigned long long]]
[[[unsigned_int `ulong_long(num)`]] [`unsigned long long`] [Generate `num` as an unsigned long long,
if an attribute is supplied it must match]]
[[[unsigned_int `bin`]] [`unsigned int`] [Generate a binary integer from an `unsigned int`]]
[[[unsigned_int `oct`]] [`unsigned int`] [Generate an octal integer from an `unsigned int`]]
[[[unsigned_int `hex`]] [`unsigned int`] [Generate a hexadecimal integer from an `unsigned int`]]
[[[unsigned_int ``uint_generator<
Num, Radix
>()``]]
[`Num`] [Generate an unsigned `Num`]]
[[[unsigned_int ``uint_generator<
Num, Radix
>()(num)``]]
[`Num`] [Generate an unsigned `num` as a `Num`,
if an attribute is supplied it must match]]
]
[endsect]
[section:boolean Boolean Generators]
[table
[[Expression] [Attribute] [Description]]
[[[boolean `lit(num)`]] [`Unused`] [Generate `num`]]
[[[boolean `bool_`]] [`bool`] [Generate a boolean]]
[[[boolean `bool_(b)`]] [`bool`] [Generate `b` as a boolean,
if an attribute is supplied it must match]]
[[[boolean ``bool_generator<
B, Policies
>()``]]
[`B`] [Generate a boolean of type `B`]]
[[[boolean ``bool_generator<
B, Policies
>()(b)``]]
[`B`] [Generate a boolean `b` as a `B`,
if an attribute is supplied it must match]]
]
[endsect]
[section:stream Stream Generators]
See here for more information about [karma_stream Stream Generators].
[table
[[Expression] [Attribute] [Description]]
[[[karma_stream `stream`]] [`hold_any`] [Generate narrow character (`char`) based output
using the matching streaming `operator<<()`]]
[[[karma_stream `stream(s)`]] [`Unused`] [Generate narrow character (`char`) based output
from the immediate argument `s` using the matching
streaming `operator<<()`]]
[[[karma_stream `wstream`]] [`whold_any`] [Generate wide character (`wchar_t`) based output
using the matching streaming `operator<<()`]]
[[[karma_stream `wstream(s)`]] [`Unused`] [Generate wide character (`wchar_t`) based output
from the immediate argument `s` using the matching
streaming `operator<<()`]]
[
[[karma_stream ``stream_generator<
Char
>()``]] [`basic_hold_any<Char>`] [Generate output based on the given character type
(`Char`) using the matching streaming `operator<<()`]]
[
[[karma_stream ``stream_generator<
Char
>()(s)``]] [`Unused`] [Generate output based on the given character type
`Char` from the immediate argument `s` using the
matching streaming `operator<<()`]]
]
[endsect]
[section:binary Binary Generators]
See here for more information about __karma_binary__.
[table
[[Expression] [Attribute] [Description]]
[[[karma_native_binary `byte_`]] [8 bits native endian] [Generate an 8 bit binary]]
[[[karma_native_binary `word`]] [16 bits native endian] [Generate a 16 bit binary in native endian representation]]
[[[karma_big_binary `big_word`]] [16 bits big endian] [Generate a 16 bit binary in big endian representation]]
[[[karma_little_binary `little_word`]] [16 bits little endian] [Generate a 16 bit binary in little endian representation]]
[[[karma_native_binary `dword`]] [32 bits native endian] [Generate a 32 bit binary in native endian representation]]
[[[karma_big_binary `big_dword`]] [32 bits big endian] [Generate a 32 bit binary in big endian representation]]
[[[karma_little_binary `little_dword`]][32 bits little endian] [Generate a 32 bit binary in little endian representation]]
[[[karma_native_binary `qword`]] [64 bits native endian] [Generate a 64 bit binary in native endian representation]]
[[[karma_big_binary `big_qword`]] [64 bits big endian] [Generate a 64 bit binary in big endian representation]]
[[[karma_little_binary `little_qword`]][64 bits little endian] [Generate a 64 bit binary in little endian representation]]
[[`pad(num)`] [`Unused`] [Generate additional null bytes allowing to align generated
output with memory addresses divisible by `num`.]]
]
[endsect]
[section:auxiliary Auxiliary Generators]
See here for more information about __karma_auxiliary__.
[table
[[Expression] [Attribute] [Description]]
[[[karma_attr_cast `attr_cast<Exposed>(a)`]] [`Exposed`] [Invoke `a` while supplying an attribute of type `Exposed`.]]
[[__karma_eol__] [`Unused`] [Generate the end of line (`\n`)]]
[[__karma_eps__] [`Unused`] [Generate an empty string]]
[[__karma_feps__] [`Unused`] [If `b` is true, generate an empty string]]
[[[karma_lazy `lazy(fg)`]]
[Attribute of `G` where `G`
is the return type of `fg`] [Invoke `fg` at generation time, returning a generator
`g` which is then called to generate.]]
[[[karma_lazy `fg`]] [see [karma_lazy `lazy(fg)`] above] [Equivalent to [karma_lazy `lazy(fg)`]]]
]
[endsect]
[section:auto Auto Generators]
See here for more information about [karma_auto Auto Generators].
[table
[[Expression] [Attribute] [Description]]
[[[karma_auto `auto_`]] [`hold_any`] [Generate output using a generator
created from the supplied attribute type
using the __create_generator__ API function.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:operators Generator Operators]
See here for more information about __karma_operator__.
[table
[[Expression] [Attribute] [Description]]
[[[link spirit.karma.reference.operator.not_predicate `!a`]]
[`A`] [Not predicate. Ensure that `a` does not succeed
generating, but don't create any output]]
[[[link spirit.karma.reference.operator.and_predicate `&a`]]
[`A`] [And predicate. Ensure that `a` does succeed
generating, but don't create any output]]
[[[link spirit.karma.reference.operator.optional `-a`]]
[`optional<A>`] [Optional. Generate `a` zero or one time]]
[[[link spirit.karma.reference.operator.kleene `*a`]]
[`vector<A>`] [Kleene. Generate `a` zero or more times]]
[[[link spirit.karma.reference.operator.plus `+a`]]
[`vector<A>`] [Plus. Generate `a` one or more times]]
[[[link spirit.karma.reference.operator.alternative `a | b`]]
[`variant<A, B>`] [Alternative. Generate `a` or `b`]]
[[[link spirit.karma.reference.operator.sequence `a << b`]]
[`tuple<A, B>`] [Sequence. Generate `a` followed by `b`]]
[[[link spirit.karma.reference.operator.list `a % b`]]
[`vector<A>`] [List. Generate `a` delimited `b` one or more times]]
]
[:For more information about the attribute propagation rules implemented by the
compound generators please see __sec_karma_compound__.]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:directives Generator Directives]
See here for more information about __karma_directive__.
[table
[[Expression] [Attribute] [Description]]
[[[karma_upperlower `lower`]`[a]`] [`A`] [Generate `a` as lower case]]
[[[karma_upperlower `upper`]`[a]`] [`A`] [Generate `a` as upper case]]
[[[karma_align `left_align`]`[a]`] [`A`] [Generate `a` left aligned in column of width
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`]]
[[[karma_align `left_align`]`(num)[a]`] [`A`] [Generate `a` left aligned in column of width `num`]]
[[[karma_align `left_align`]`(g)[a]`] [`A`] [Generate `a` left aligned in column of width
`BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to
generate the necessary padding]]
[[[karma_align `left_align`]`(num, g)[a]`][`A`] [Generate `a` left aligned in column of width `num`
while using `g` to generate the necessary
padding]]
[[[karma_align `center`]`[a]`] [`A`] [Generate `a` centered in column of width
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`]]
[[[karma_align `center`]`(num)[a]`] [`A`] [Generate `a` centered in column of width `num`]]
[[[karma_align `center`]`(g)[a]`] [`A`] [Generate `a` centered in column of width
`BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to
generate the necessary padding]]
[[[karma_align `center`]`(num, g)[a]`] [`A`] [Generate `a` centered in column of width `num`
while using `g` to generate the necessary
padding]]
[[[karma_align `right_align`]`[a]`] [`A`] [Generate `a` right aligned in column of width
`BOOST_KARMA_DEFAULT_FIELD_LENGTH`]]
[[[karma_align `right_align`]`(num)[a]`] [`A`] [Generate `a` right aligned in column of width `num`]]
[[[karma_align `right_align`]`(g)[a]`] [`A`] [Generate `a` right aligned in column of width
`BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to
generate the necessary padding]]
[[[karma_align `right_align`]`(num, g)[a]`][`A`][Generate `a` right aligned in column of width `num`
while using `g` to generate the necessary
padding]]
[[[karma_maxwidth `maxwidth`]`[a]`] [`A`] [Generate `a` truncated to column of width
`BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`]]
[[[karma_maxwidth `maxwidth`]`(num)[a]`] [`A`] [Generate `a` truncated to column of width `num`]]
[[[karma_repeat `repeat`]`[a]`] [`vector<A>`] [Repeat `a` zero or more times]]
[[[karma_repeat `repeat`]`(num)[a]`] [`vector<A>`] [Repeat `a` `num` times]]
[[[karma_repeat `repeat`]`(num1, num2)[a]`] [`vector<A>`] [Repeat `a` `num1` to `num2` times]]
[[[karma_repeat `repeat`]`(num, inf)[a]`] [`vector<A>`] [Repeat `a` `num` or more times]]
[[__karma_verbatim__`[a]`][`A`] [Disable delimited generation for `a`. Performs post delimiting.]]
[[[karma_delimit `delimit`]`[a]`] [`A`] [Reestablish the delimiter that got inhibited by verbatim]]
[[[karma_delimit `delimit`]`(d)[a]`] [`A`] [Use `d` as a delimiter for generating `a`]]
[[[karma_no_delimit `no_delimit`]`[a]`] [`A`] [Disable delimited generation for `a`. No post-delimiting step performed.]]
[[__karma_as__`()[a]`] [`A`] [Force atomic output from arbitrary attribute types]]
[[__karma_as_string__`[a]`] [`A`] [Force atomic output from string attributes]]
[[__karma_as_wstring__`[a]`] [`A`] [Force atomic output from wide character string attributes]]
[[__karma_omit__`[a]`] [`A`] [Consume the attribute type of `a` without generating anything.
The embedded generator will be always executed.]]
[[__karma_skip__`[a]`] [`A`] [Consume the attribute type of `a` without generating anything.
The embedded generator will never be executed.]]
[[__karma_duplicate__`[a]`] [`A`] [The supplied attribute will be duplicated and passed unchanged to
all embedded elements of a sequence.]]
[[__karma_buffer__`[a]`][`A`] [Temporarily intercept the output generated by `a`,
flushing it only after `a` succeeded]]
[[[karma_columns `columns`]`[a]`] [`A`] [Generate `a` split into
`BOOST_KARMA_DEFAULT_COLUMNS` number of columns using
`karma::eol` as column delimiter]]
[[[karma_columns `columns`]`(num)[a]`] [`A`] [Generate `a` split into
`num` number of columns using
`karma::eol` as column delimiter]]
[[[karma_columns `columns`]`(g)[a]`] [`A`] [Generate `a` split into
`BOOST_KARMA_DEFAULT_COLUMNS` number of columns using
`g` as column delimiter]]
[[[karma_columns `columns`]`(num, g)[a]`][`A`][Generate `a` split into
`num` number of columns using
`g` as column delimiter]]
]
[endsect]
[section:action Generator Semantic Actions]
[table
[[Expression] [Attribute] [Description]]
[[`g[fa]`] [Attribute of `g`] [Call semantic action `fa` before invoking `g`]]
]
[endsect]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section Compound Attribute Rules]
[heading Notation]
The notation we use is of the form:
a: A, b: B, ... --> composite-expression: composite-attribute
`a`, `b`, etc. are the operands. `A`, `B`, etc. are the operand's
attribute types. `composite-expression` is the expression involving the
operands and `composite-attribute` is the resulting attribute type of
the composite expression.
For instance:
a: A, b: B --> (a << b): tuple<A, B>
which reads as: given, `a` and `b` are generators, and `A` is the type
of the attribute of `a`, and `B` is the type of the attribute of `b`, then the
type of the attribute of `a << b` will be `tuple<A, B>`.
[important In the attribute tables, we will use `vector<A>` and
`tuple<A, B...>` as placeholders only. The notation of `vector<A>`
stands for ['any __stl__ container] holding elements of type `A` and the
notation `tuple<A, B...>` stands for ['any __fusion__ sequence] holding
`A`, `B`, ... etc. elements. The notation of `variant<A, B, ...>` stands for
['a __boost_variant__] capable of holding `A`, `B`, ... etc. elements. Finally,
`Unused` stands for __unused_type__. ]
[heading Compound Generator Attribute Types]
[table
[[Expression] [Attribute]]
[[__karma_sequence__ (`a << b`)]
[``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>``]]
[[__karma_alternative__ (`a | b`)]
[``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``]]
[[[karma_kleene Kleene (`*a`)]]
[``a: A --> *a: vector<A>
a: Unused --> *a: Unused``]]
[[__karma_plus__ (`+a`)]
[``a: A --> +a: vector<A>
a: Unused --> +a: Unused``]]
[[__karma_list__ (`a % b`)]
[``a: A, b: B --> (a % b): vector<A>
a: Unused, b: B --> (a % b): Unused``]]
[[[karma_repeat Repetition] (`repeat[]`)]
[``a: A --> repeat(...,...)[a]: vector<A>
a: Unused --> repeat(...,...)[a]: Unused``]]
[[__karma_optional__ (`-a`)]
[``a: A --> -a: optional<A>
a: Unused --> -a: Unused``]]
[[__karma_and_predicate__ (`&a`)] [`a: A --> &a: A`]]
[[__karma_not_predicate__ (`!a`)] [`a: A --> !a: A`]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:non_terminals Nonterminals]
See here for more information about __karma_nonterminal__.
[variablelist Notation
[[`RT`] [Synthesized attribute. The rule or grammar's return type.]]
[[`Arg1`, `Arg2`, `ArgN`] [Inherited attributes. Zero or more arguments.]]
[[`L1`, `L2`, `LN`] [Zero or more local variables.]]
[[`r, r2`] [Rules]]
[[`g`] [A grammar]]
[[`p`] [A generator expression]]
[[`my_grammar`] [A user defined grammar]]
]
[variablelist Terminology
[[Signature] [`RT(Arg1, Arg2, ... ,ArgN)`. The signature specifies
the synthesized (return value) and inherited (arguments)
attributes.]]
[[Locals] [`locals<L1, L2, ..., LN>`. The local variables.]]
[[Delimiter] [The delimit-generator type]]
]
[variablelist Template Arguments
[[`Iterator`] [The iterator type you will use for parsing.]]
[[`A1`, `A2`, `A3`] [Can be one of 1) Signature 2) Locals 3) Delimiter.]]
]
[table
[[Expression] [Description]]
[[`rule<OutputIterator, A1, A2, A3> r(name);`] [Rule declaration. `OutputIterator` is required.
`A1, A2, A3` are optional and can be specified in any order.
`name` is an optional string that gives the rule
its name, useful for debugging.]]
[[`rule<OutputIterator, A1, A2, A3> r(r2);`] [Copy construct rule `r` from rule `r2`.]]
[[`r = r2;`] [Assign rule `r2` to `r`. `boost::shared_ptr` semantics.]]
[[`r.alias()`] [Return an alias of `r`. The alias is a generator that
holds a reference to `r`. Reference semantics.]]
[[`r.copy()`] [Get a copy of `r`.]]
[[`r.name(name)`] [Set the name of a rule]]
[[`r.name()`] [Get the name of a rule]]
[[debug(r)] [Debug rule `r`]]
[[`r = g;`] [Rule definition]]
[[`r %= g;`] [Auto-rule definition. The attribute of `g` should be
compatible with the synthesized attribute of `r`. When `g`
is successful, its attribute is automatically propagated
to `r`'s synthesized attribute.]]
[[
``
template <typename OutputIterator>
struct my_grammar : grammar<OutputIterator, A1, A2, A3>
{
my_grammar() : my_grammar::base_type(start, name)
{
// Rule definitions
start = /* ... */;
}
rule<OutputIterator, A1, A2, A3> start;
// more rule declarations...
};
``
] [Grammar definition. `name` is an optional string that gives the
grammar its name, useful for debugging.]]
[[my_grammar<OutputIterator> g] [Instantiate a grammar]]
[[`g.name(name)`] [Set the name of a grammar]]
[[`g.name()`] [Get the name of a grammar]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:semantic_actions Generator Semantic Actions]
Semantic Actions may be attached to any generator as follows:
g[f]
where `f` is a function with the signatures:
void f(Attrib&);
void f(Attrib&, Context&);
void f(Attrib&, Context&, bool&);
You can use __boost_bind__ to bind member functions. For function
objects, the allowed signatures are:
void operator()(Attrib&, unused_type, unused_type) const;
void operator()(Attrib&, Context&, unused_type) const;
void operator()(Attrib&, Context&, bool&) const;
The `unused_type` is used in the signatures above to signify 'don't
care'.
For more information see __karma_actions__.
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section Phoenix]
__phoenix__ makes it easier to attach semantic actions. You just
inline your lambda expressions:
g[phoenix-lambda-expression]
__karma__ provides some __phoenix__ placeholders to access important
information from the `Attrib` and `Context` that are otherwise fiddly to extract.
[variablelist Spirit.Karma specific Phoenix placeholders
[[`_1, _2, ... , _N`] [Nth attribute of `g`]]
[[`_val`] [The enclosing rule's synthesized attribute.]]
[[`_r1, _r2, ... , _rN`] [The enclosing rule's Nth inherited attribute.]]
[[`_a, _b, ... , _j`] [The enclosing rule's local variables (`_a` refers to the first).]]
[[`_pass`] [Assign `false` to `_pass` to force a generator failure.]]
]
[important All placeholders mentioned above are defined in the namespace
`boost::spirit` and, for your convenience, are available in the
namespace `boost::spirit::karma` as well.]
For more information see __karma_actions__.
[endsect]

223
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/stream.qbk vendored Executable file
View File

@@ -0,0 +1,223 @@
[/==============================================================================
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:stream Stream Generators]
This module includes the description of the different variants of the `stream`
generator. It can be used to utilize existing streaming operators
(`operator<<(std::ostream&, ...)`) for output generation.
[heading Header]
// forwards to <boost/spirit/home/karma/stream.hpp>
#include <boost/spirit/include/karma_stream.hpp>
Also, see __include_structure__.
[section:stream Stream Generators (`stream`, `wstream`, etc.)]
[heading Description]
The `stream_generator` is a primitive which allows to use pre-existing standard
streaming operators for output generation integrated with __karma__. It
provides a wrapper generator dispatching the value to output to the stream
operator of the corresponding type. Any value `a` to be formatted using the
`stream_generator` will result in invoking the standard streaming operator
for its type `A`, for instance:
std::ostream& operator<< (std::ostream&, A const&);
[heading Header]
// forwards to <boost/spirit/home/karma/stream.hpp>
#include <boost/spirit/include/karma_stream.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::stream // alias: boost::spirit::karma::stream`]]
[[`boost::spirit::wstream // alias: boost::spirit::karma::wstream`]]
]
[heading Synopsis]
template <typename Char>
struct stream_generator;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`Char`] [The character type to use to generate
the output. This type will be used while
assigning the generated characters to the
underlying output iterator.] [`char`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`s`] [A variable instance of any type with a defined matching
streaming `operator<<()` or a __karma_lazy_argument__ that
evaluates to any type with a defined matching streaming
`operator<<()`.]]
]
[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]]
[[`stream`] [Call the streaming `operator<<()` for the type
of the mandatory attribute. The output emitted
by this operator will be the result of the
`stream` generator. This generator never fails
(unless the underlying output stream reports an
error). The character type of the I/O ostream
is assumed to be `char`.]]
[[`stream(s)`] [Call the streaming `operator<<()` for the type
of the immediate value `s`. The output emitted
by this operator will be the result of the
`stream` generator. This generator never fails
(unless the underlying output stream reports an
error). The character type of the I/O ostream
is assumed to be `char`.]]
[[`wstream`] [Call the streaming `operator<<()` for the type
of the mandatory attribute. The output emitted
by this operator will be the result of the
`stream` generator. This generator never fails
(unless the underlying output stream reports an
error). The character type of the I/O ostream
is assumed to be `wchar_t`.]]
[[`wstream(s)`] [Call the streaming `operator<<()` for the type
of the immediate value `s`. The output emitted
by this operator will be the result of the
`stream` generator. This generator never fails
(unless the underlying output stream reports an
error). The character type of the I/O ostream
is assumed to be `wchar_t`.]]
]
All generators listed in the table above are predefined specializations of the
`stream_generator<Char>` basic stream generator type described below. It is
possible to directly use this type to create stream generators using an
arbitrary underlying character type.
[table
[[Expression] [Semantics]]
[
[``stream_generator<
Char
>()``] [Call the streaming `operator<<()` for the type
of the mandatory attribute. The output emitted
by this operator will be the result of the
`stream` generator. This generator never fails
(unless the underlying output stream reports an
error). The character type of the I/O ostream
is assumed to be `Char`]]
[
[``stream_generator<
Char
>()(s)``] [Call the streaming `operator<<()` for the type
of the immediate value `s`. The output emitted
by this operator will be the result of the
`stream` generator. This generator never fails
(unless the underlying output stream reports an
error). The character type of the I/O ostream
is assumed to be `Char`.]]
]
[heading Additional Requirements]
All of the stream generators listed above require the type of the value to
generate output for (either the immediate value or the associated attribute) to
implement a streaming operator conforming to the usual I/O streams conventions
(where `attribute_type` is the type of the value to generate output for):
template <typename Ostream>
Ostream& operator<< (Ostream& os, attribute_type const& attr)
{
// type specific output generation
return os;
}
This operator will be called by the stream generators to gather the output for
the attribute of type `attribute_type`. All data streamed into the given
`Ostream` will end up being generated by the corresponding stream generator
instance.
[note If the `stream` generator is invoked inside a [karma_format `format`]
(or [karma_format `format_delimited`]) stream manipulator the `Ostream`
passed to the `operator<<()` will have registered (imbued) the same
standard locale instance as the stream the [karma_format `format`] (or
[karma_format `format_delimited`]) manipulator has been used with.
This ensures all facets registered (imbued) with the original I/O
stream object are used during output generation.
]
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`stream`] [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
[[`stream(s)`] [__unused__]]
[[`wstream`] [`whold_any`, attribute is mandatory (otherwise compilation will fail)]]
[[`wstream(s)`] [__unused__]]
[[`stream_generator<Char>()`] [`basic_hold_any<Char>`, attribute is mandatory (otherwise compilation will fail)]]
[[`stream_generator<Char>()(s)`] [__unused__]]
]
[important The attribute type `hold_any` exposed by some of the stream
generators is semantically and syntactically equivalent to
the type implemented by __boost_any__. It has been added to /Spirit/
as it has better a performance and a smaller footprint if compared to
__boost_any__.
]
[note In addition to their usual attribute of type `Attrib` all listed generators
accept an instance of a `boost::optional<Attrib>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Attrib` 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 stream 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_stream]
And a class definition used in the examples:
[reference_karma_complex]
[reference_karma_stream_complex]
Basic usage of `stream` generators:
[reference_karma_stream]
[endsect]
[endsect]

358
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/string.qbk vendored Executable file
View File

@@ -0,0 +1,358 @@
[/==============================================================================
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]

53
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/tutorial_intro.qbk vendored Executable file
View File

@@ -0,0 +1,53 @@
[/==============================================================================
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 Quick Start]
[heading Spirit.Karma - what's that?]
Throughout the description of __karma__ we will try to align ourselves very
much with the documentation for __qi__. The reasons are many fold:
* __karma__ is the counterpart to __qi__. Some people say it's the Yin to
__qi__'s Yang. __karma__ is generating byte sequences from internal data
structures as __qi__ is parsing byte sequences into those (very same) internal
data structures.
* Both libraries have an almost identical structure, very similar semantics,
and are both built using identical tools. Both libraries implement a language
casting the specifics of their domain (parsing and generating) into a simple
interface.
Why should you use a generator library for such a simple thing as output
generation? Programmers have been using `printf`, `std::stream` formatting, or
`boost::format` for quite some time. The answer is - yes, for simple output
formatting tasks those familiar tools might be a quick solution. But experience
shows: as soon as the formatting requirements are becoming more complex output
generation is getting more and more challenging in terms of readability,
maintainability, and flexibility of the code. Last, but not least, it turns out
that code using __karma__ runs much faster than equivalent code using either
of the 'straight' methods mentioned above (see here for some numbers:
__sec_karma_numeric_performance__)
You might argue that more complex tasks require more complex tools. But this
turns out not to be the case! The whole Spirit library is designed to be simple
to use, while being scalable from trivial to very complicated applications.
In terms of development simplicity and ease in deployment, the same is true for
__karma__ as has been described elsewhere in this documentation for __qi__: the
entire library consists of only header files, with no libraries to link against
or build. Just put the spirit distribution in your include path, compile and
run. Code size? Very tight, essentially comparable to hand written code.
The __karma__ tutorials are built in a walk through style, starting with
elementary things growing step by step in complexity. And again: keep in mind
output generation is the exact opposite of parsing. Everything you already
learnt about parsing using __qi__ is applicable to generating formatted output
using __karma__. All you have to do is to look at __karma__ as being a
mirror image of __qi__.
[endsect] [/Quick Start]

176
externals/vcpkg/buildtrees/boost-spirit/src/ost-1.79.0-858439c8d4.clean/doc/karma/warming_up.qbk vendored Executable file
View File

@@ -0,0 +1,176 @@
[/==============================================================================
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 Warming up]
Learning how to use __karma__ is really simple. We will start from trivial
examples, ramping up as we go.
[heading Trivial Example #1 Generating a number]
Let's create a generator that will output a floating-point number:
double_
Easy huh? The above code actually instantiates a Spirit floating point
generator (a built-in generator). Spirit has many pre-defined generators and
consistent naming conventions will help you finding your way through the maze.
Especially important to note is that things related to identical entities (as
in this case, floating point numbers) are named identically in __karma__ and in
__qi__. Actually, both libraries are using the very same variable instance to
refer to a floating point generator or parser: `double_`.
[heading Trivial Example #2 Generating two numbers]
Now, let's create a generator that will output a line consisting of two
floating-point numbers.
double_ << double_
Here you see the familiar floating-point numeric generator `double_` used twice,
once for each number. If you are used to see the `'>>'` operator for concatenating
two parsers in __qi__ you might wonder, what's that `'<<'` operator doing in
there? We decided to distinguish generating and parsing of sequences the same
way as the std::stream libraries do: we use operator `'>>'` for input (parsing),
and operator `'<<'` for output (generating). Other than that there is no
significant difference. The above program creates a generator from two simpler
generators, glueing them together with the sequence operator. The result is a
generator that is a composition of smaller generators. Whitespace between
numbers can implicitly be inserted depending on how the generator is invoked
(see below).
[note When we combine generators, we end up with a "bigger" generator, but
it's still a generator. Generators can get bigger and bigger, nesting more
and more, but whenever you glue two generators together, you end up with one
bigger generator. This is an important concept.
]
[heading Trivial Example #3 Generating one or more numbers]
Now, creating output for two numbers is not too interesting. Let's create a
generator that will output zero or more floating-point numbers in a row.
*double_
This is like a regular-expression Kleene Star. We moved the `*` to the front for
the same reasons we did in __qi__: we must work with the syntax rules of C++.
But if you know regular expressions (and for sure you remember those C++ syntax
rules) it will start to look very familiar in a matter of a very short time.
Any expression that evaluates to a generator may be used with the Kleene Star.
Keep in mind, though, that due to C++ operator precedence rules you may need
to put the expression in parentheses for complex expressions. As above,
whitespace can be inserted implicitly in between the generated numbers, if
needed.
[heading Trivial Example #4 Generating a comma-delimited list of numbers]
We follow the lead of __qi__'s warming up section and will create a generator
that produces a comma-delimited list of numbers.
double_ << *(lit(',') << double_)
Notice `lit(',')`. It is a literal character generator that simply generates
the comma `','`. In this case, the Kleene Star is modifying a more complex
generator, namely, the one generated by the expression:
(lit(',') << double_)
Note that this is a case where the parentheses are necessary. The Kleene Star
encloses the complete expression above, repeating the whole pattern in the
generated output zero or more times.
[heading Let's Generate!]
We're done with defining the generator. All that's left is to invoke the
generator to do its work. For now, we will use the `generate_delimited` function.
One overload of this function accepts four arguments:
# An output iterator accepting the generated characters
# The generator expression
# Another generator called the delimiting generator
# The data to format and output
While comparing this minimal example with an equivalent parser example we
notice a significant difference. It is possible (and actually, it makes a lot
of sense) to use a parser without creating any internal representation of the
parsed input (i.e. without 'producing' any data from the parsed input). Using
a parser in this mode checks the provided input against
the given parser expression allowing to verify whether the input is parsable.
For generators this mode doesn't make any sense. What is output generation
without generating any output? So we always will have to supply the data the
output should be generated from. In our example we supply a list of `double`
numbers as the last parameter to the function `generate_delimited` (see code
below).
In this example, we wish to delimit the generated numbers by spaces. Another
generator named `space` is included in Spirit's repertoire of predefined
generators. It is a very trivial generator that simply produces spaces. It is
the equivalent to writing `lit(' ')`, or simply `' '`. It has been
implemented for similarity with the corresponding predefined `space` parser.
We will use `space` as our delimiter. The delimiter is the one responsible for
inserting characters in between generator elements such as the `double_` and
`lit`.
Ok, so now let's generate (for the complete source code of this example please
refer to [@../../example/karma/num_list1.cpp num_list1.cpp]).
[import ../../example/karma/num_list1.cpp]
[tutorial_karma_numlist1]
[note You might wonder how a `vector<double>`, which is actually a single data
structure, can be used as an argument (we call it attribute) to a sequence
of generators. This seems to be counter intuitive and doesn't match with
your experience of using `printf`, where each formatting placeholder has
to be matched with a corresponding argument. Well, we will explain this
behavior in more detail later in this tutorial. For now just consider
this to be a special case, implemented on purpose to allow more flexible
output formatting of STL containers: sequences accept a single container
attribute if all elements of this sequence accept attributes compatible
with the elements held by this container.]
The generate function returns `true` or `false` depending on the result of the
output generation. As outlined in different places of this documentation, a
generator may fail for different reasons. One of the possible reasons is an
error in the underlying output iterator (memory exhausted or disk full, etc.).
Another reason might be that the data doesn't match the requirements of a
particular generator.
[note `char` and `wchar_t` operands
The careful reader may notice that the generator expression has `','` instead
of `lit(',')` as the previous examples did. This is ok due to C++ syntax
rules of conversion. Spirit provides `<<` operators that are overloaded to
accept a `char` or `wchar_t` argument on its left or right (but not both).
An operator may be overloaded if at least one of its parameters is a
user-defined type. In this case, the `double_` is the 2nd argument to
`operator<<`, and so the proper overload of `<<` is used, converting `','`
into a character literal generator.
The problem with omitting the `lit` should be obvious: `'a' << 'b'` is not a
spirit generator, it is a numeric expression, left-shifting the ASCII (or
another encoding) value of `'a'` by the ASCII value of `'b'`. However, both
`lit('a') << 'b'` and `'a' << lit('b')` are Spirit sequence generators
for the letter `'a'` followed by `'b'`. You'll get used to it, sooner or
later.
]
Note that we inlined the generator directly in the call to `generate_delimited`.
Upon calling this function, the expression evaluates into a temporary,
unnamed generator which is passed into the `generate_delimited` function,
used, and then destroyed.
Here, we chose to make the generate function generic by making it a template,
parameterized by the output iterator type. By doing so, it can put the generated
data into any STL conforming output iterator.
[endsect] [/ Warming up]