| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 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] |
| |
| [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] |
| |