120 lines
4.3 KiB
Plaintext
120 lines
4.3 KiB
Plaintext
[/==============================================================================
|
|
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]
|
|
|