]>
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 Parsers] | |
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 | to be output by the parser attached to the semantic action. Semantic | |
16 | actions are associated with a parser using the syntax `p[]`, where `p` is an | |
17 | arbitrary parser expression. | |
18 | ||
19 | [heading Header] | |
20 | ||
21 | // forwards to <boost/spirit/home/qi/action.hpp> | |
22 | #include <boost/spirit/include/qi_action.hpp> | |
23 | ||
24 | Also, see __include_structure__. | |
25 | ||
26 | [heading Model of] | |
27 | ||
28 | [:__unary_parser_concept__] | |
29 | ||
30 | [variablelist Notation | |
31 | [[`a`, `p`][Instances of a parser, `P`]] | |
32 | [[`A`] [Attribute type exposed by a parser, `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 parser to fail. Both `Context` and the boolean flag are | |
36 | optional. For more information see below.]] | |
37 | [[`Attrib`][The attribute obtained from the parse.]] | |
38 | [[`Context`] [The type of the parser 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_parser_concept__. | |
46 | ||
47 | [table | |
48 | [[Expression] [Semantics]] | |
49 | [[`p[fa]`] [If `p` is successful, call semantic action, `fa`. The function | |
50 | or function object `fa` is provided the attribute value | |
51 | parsed by the parser `p`, plus some more context information | |
52 | and a mutable bool flag which can be used to fail parsing.]] | |
53 | ] | |
54 | ||
55 | The possible signatures for functions to be used as semantic actions are: | |
56 | ||
57 | template <typename Attrib> | |
58 | void fa(Attrib& attr); | |
59 | ||
60 | template <typename Attrib, typename Context> | |
61 | void fa(Attrib& attr, Context& context); | |
62 | ||
63 | template <typename Attrib, typename Context> | |
64 | void fa(Attrib& attr, Context& context, bool& pass); | |
65 | ||
66 | The function or function object is expected to return the value to generate | |
67 | output from by assigning it to the first parameter, `attr`. Here `Attrib` is | |
68 | the attribute type of the parser attached to the semantic action. | |
69 | ||
70 | The type `Context` is the type of the parser execution context. This type is | |
71 | unspecified and depends on the context the parser is invoked in. The value, | |
72 | `context` used by semantic actions written using __phoenix__ to access various | |
73 | context dependent attributes and values. For more information about __phoenix__ | |
74 | placeholder expressions usable in semantic actions see __qi_nonterminal__. | |
75 | ||
76 | The third parameter, `pass`, can be used by the semantic action to force the | |
77 | associated parser to fail. If pass is set to `false` the action parser | |
78 | will immediately return `false` as well, while not invoking `p` and not | |
79 | generating any output. | |
80 | ||
81 | [heading Attributes] | |
82 | ||
83 | [table | |
84 | [[Expression] [Attribute]] | |
85 | [[`a[fa]`] [`a: A --> a[fa]: A`]] | |
86 | ] | |
87 | ||
88 | [heading Complexity] | |
89 | ||
90 | The complexity of the action parser is defined by the complexity of the | |
91 | parser the semantic action is attached to and the complexity of the function | |
92 | or function object used as the semantic action. | |
93 | ||
94 | [heading Example] | |
95 | ||
96 | Examples for semantic actions can be found here: | |
97 | [link spirit.qi.tutorials.semantic_actions.examples_of_semantic_actions Examples of Semantic Actions]. | |
98 | ||
99 | [endsect] [/ Action] | |
100 |