| [/============================================================================== |
| 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 |
| to be output by the parser attached to the semantic action. Semantic |
| actions are associated with a parser using the syntax `p[]`, where `p` is an |
| arbitrary parser expression. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/action.hpp> |
| #include <boost/spirit/include/qi_action.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Model of] |
| |
| [:__unary_parser_concept__] |
| |
| [variablelist Notation |
| [[`a`, `p`][Instances of a parser, `P`]] |
| [[`A`] [Attribute type exposed by a parser, `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 parser to fail. Both `Context` and the boolean flag are |
| optional. For more information see below.]] |
| [[`Attrib`][The attribute obtained from the parse.]] |
| [[`Context`] [The type of the parser 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_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`p[fa]`] [If `p` is successful, call semantic action, `fa`. The function |
| or function object `fa` is provided the attribute value |
| parsed by the parser `p`, plus some more context information |
| and a mutable bool flag which can be used to fail parsing.]] |
| ] |
| |
| 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 parser attached to the semantic action. |
| |
| The type `Context` is the type of the parser execution context. This type is |
| unspecified and depends on the context the parser is invoked in. The value, |
| `context` 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 __qi_nonterminal__. |
| |
| The third parameter, `pass`, can be used by the semantic action to force the |
| associated parser to fail. If pass is set to `false` the action parser |
| will immediately return `false` as well, while not invoking `p` and not |
| generating any output. |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`a[fa]`] [`a: A --> a[fa]: A`]] |
| ] |
| |
| [heading Complexity] |
| |
| The complexity of the action parser is defined by the complexity of the |
| parser the semantic action is attached to and the complexity of the function |
| or function object used as the semantic action. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| [reference_qi_action] |
| |
| More examples for semantic actions can be found here: |
| [link spirit.qi.tutorials.semantic_actions.examples_of_semantic_actions Examples of Semantic Actions]. |
| |
| [endsect] [/ Action] |
| |