]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
13 | Semantic actions may be attached to any point in the grammar specification. | |
14 | They allow to call a function or function object in order to provide the value | |
15 | output by the generator attached to the semantic action. Semantic | |
16 | actions are associated with a generator using the syntax `g[]`, where `g` is an | |
17 | arbitrary 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 | ||
24 | Also, 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 | ||
44 | Semantics of an expression is defined only where it differs from, or is not | |
45 | defined 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 | ||
54 | The 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 | ||
65 | The function or function object is expected to return the value to generate | |
66 | output from by assigning it to the first parameter, `attr`. Here `Attrib` is | |
67 | the attribute type of the generator attached to the semantic action. | |
68 | ||
69 | The type `Context` is the type of the generator execution context. This type is | |
70 | unspecified 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 | |
72 | context dependent attributes and values. For more information about __phoenix__ | |
73 | placeholder expressions usable in semantic actions see __karma_nonterminal_concept__. | |
74 | ||
75 | The third parameter, `pass`, can be used by the semantic action to force the | |
76 | associated generator to fail. If pass is set to `false` the action generator | |
77 | will immediately return `false` as well, while not invoking `g` and not | |
78 | generating 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 | ||
89 | The complexity of the action generator is defined by the complexity of the | |
90 | generator the semantic action is attached to and the complexity of the function | |
91 | or 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 | ||
103 | Some includes: | |
104 | ||
105 | [reference_karma_includes] | |
106 | ||
107 | Some using declarations: | |
108 | ||
109 | [reference_karma_using_declarations_action] | |
110 | ||
111 | Some examples: | |
112 | ||
113 | [reference_karma_action] | |
114 | ||
115 | More 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 |