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 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 15to be output by the parser attached to the semantic action. Semantic 16actions are associated with a parser using the syntax `p[]`, where `p` is an 17arbitrary 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 24Also, 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 44Semantics of an expression is defined only where it differs from, or is not 45defined 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 55The 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 66The function or function object is expected to return the value to generate 67output from by assigning it to the first parameter, `attr`. Here `Attrib` is 68the attribute type of the parser attached to the semantic action. 69 70The type `Context` is the type of the parser execution context. This type is 71unspecified and depends on the context the parser is invoked in. The value, 72`context` used by semantic actions written using __phoenix__ to access various 73context dependent attributes and values. For more information about __phoenix__ 74placeholder expressions usable in semantic actions see __qi_nonterminal__. 75 76The third parameter, `pass`, can be used by the semantic action to force the 77associated parser to fail. If pass is set to `false` the action parser 78will immediately return `false` as well, while not invoking `p` and not 79generating 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 90The complexity of the action parser is defined by the complexity of the 91parser the semantic action is attached to and the complexity of the function 92or function object used as the semantic action. 93 94[heading Example] 95 96Examples 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 101