1[/============================================================================== 2 Copyright (C) 2001-2011 Joel de Guzman 3 Copyright (C) 2001-2011 Hartmut Kaiser 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8 9[section:action Semantic Actions with Generators] 10 11[heading Description] 12 13Semantic actions may be attached to any point in the grammar specification. 14They allow to call a function or function object in order to provide the value 15output by the generator attached to the semantic action. Semantic 16actions are associated with a generator using the syntax `g[]`, where `g` is an 17arbitrary generator expression. 18 19[heading Header] 20 21 // forwards to <boost/spirit/home/karma/action.hpp> 22 #include <boost/spirit/include/karma_action.hpp> 23 24Also, see __include_structure__. 25 26[heading Model of] 27 28[:__unary_generator_concept__] 29 30[variablelist Notation 31 [[`a`, `g`][Instances of a generator, `G`]] 32 [[`A`] [Attribute type exposed by a generator, `a`]] 33 [[`fa`] [A (semantic action) function with signature `void(Attrib&, Context&, bool&)`. 34 The third parameter is a boolean flag that can be set to false to 35 force the generator to fail. Both `Context` and the boolean flag are 36 optional. For more information see below.]] 37 [[`Attrib`][The attribute to be used to generate output from.]] 38 [[`Context`] [The type of the generator execution context. For more 39 information see below.]] 40] 41 42[heading Expression Semantics] 43 44Semantics of an expression is defined only where it differs from, or is not 45defined in __unary_generator_concept__. 46 47[table 48 [[Expression] [Semantics]] 49 [[`g[fa]`] [Call semantic action, `fa` /before/ invoking `g`. The function 50 or function object `fa` is expected to provide the value 51 to generate output from to the generator `g`.]] 52] 53 54The possible signatures for functions to be used as semantic actions are: 55 56 template <typename Attrib> 57 void fa(Attrib& attr); 58 59 template <typename Attrib, typename Context> 60 void fa(Attrib& attr, Context& context); 61 62 template <typename Attrib, typename Context> 63 void fa(Attrib& attr, Context& context, bool& pass); 64 65The function or function object is expected to return the value to generate 66output from by assigning it to the first parameter, `attr`. Here `Attrib` is 67the attribute type of the generator attached to the semantic action. 68 69The type `Context` is the type of the generator execution context. This type is 70unspecified and depends on the context the generator is invoked in. The value 71`context` is used by semantic actions written using __phoenix__ to access various 72context dependent attributes and values. For more information about __phoenix__ 73placeholder expressions usable in semantic actions see __karma_nonterminal_concept__. 74 75The third parameter, `pass`, can be used by the semantic action to force the 76associated generator to fail. If pass is set to `false` the action generator 77will immediately return `false` as well, while not invoking `g` and not 78generating any output. 79 80[heading Attributes] 81 82[table 83 [[Expression] [Attribute]] 84 [[`a[fa]`] [`a: A --> a[fa]: A`]] 85] 86 87[heading Complexity] 88 89The complexity of the action generator is defined by the complexity of the 90generator the semantic action is attached to and the complexity of the function 91or function object used as the semantic action. 92 93[important Please note that the use of semantic actions in __karma__ generally 94 forces the library to create a /copy/ of the attribute, which might 95 be a costly operation. Always consider using other means of 96 associating a value with a particular generator first.] 97 98[heading Example] 99 100[note The test harness for the example(s) below is presented in the 101 __karma_basics_examples__ section.] 102 103Some includes: 104 105[reference_karma_includes] 106 107Some using declarations: 108 109[reference_karma_using_declarations_action] 110 111Some examples: 112 113[reference_karma_action] 114 115More examples for semantic actions can be found here: 116[link spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions Examples of Semantic Actions]. 117 118[endsect] [/ Action] 119 120