{"id":1010,"date":"2010-03-03T10:04:35","date_gmt":"2010-03-03T18:04:35","guid":{"rendered":"http:\/\/boost-spirit.com\/home\/?p=1010"},"modified":"2010-08-24T06:25:24","modified_gmt":"2010-08-24T13:25:24","slug":"the-anatomy-of-semantic-actions-in-qi","status":"publish","type":"post","link":"https:\/\/boost-spirit.com\/home\/2010\/03\/03\/the-anatomy-of-semantic-actions-in-qi\/","title":{"rendered":"The Anatomy of Semantic Actions in Qi"},"content":{"rendered":"

The concept of Spirit’s<\/em> semantic actions seems to be easy enough to understand as most people new to the library prefer their usage over applying the built-in attribute propagation rules. That is not surprising. The idea of attaching a function to any point of a grammar which is called whenever the corresponding parser matched is straighforward to grasp. Earlier versions of Spirit<\/em> required a semantic action to conform to a very specific interface. Today’s semantic actions are more flexible and more powerful. Recently, a couple of people asked questions about them. So I decided dedicating this Tip of the Day to the specifics and the usage model of semantic actions in Spirit Qi<\/em>.<\/p>\n

<\/p>\n

All three of Spirit’s<\/em> sub-libraries – Qi<\/em>, Karma<\/em>, and Lex<\/em> \u2013 support semantic actions. In each case they are different and have some specifics. Today I will highlight semantic actions in Qi<\/em>. But I will dedicate later Tips of the Day to semantic actions in Karma<\/em> and\u00a0 Lex<\/em>.<\/p>\n

Semantic actions are functions or function objects attached to some specific part of a grammar. In Qi<\/em> they are invoked after<\/em> the corresponding parser successfully recognizes a portion of the input. Here the semantic action receives the attribute value of the matching parser.<\/p>\n

Semantic Actions \u2013 a General View<\/h5>\n

A semantic action f<\/span> are attached to a Qi<\/em> parser p<\/span> by simply writing:<\/p>\n

\r\np[f]\r\n<\/pre>\n
The function (or function object) f<\/span> has to expose a certain interface allowing Spirit<\/em> to pass the proper argument types. In the simplest case this can be a global function taking no arguments at all.<\/p>\n
\r\nvoid func()\r\n{\r\n    std::cout << "Matched an integer!\\n";\r\n}\r\n\r\nstd::string input("1234");\r\nstd::string::const_iterator begin = input.begin();\r\nstd::string::const_iterator end = input.end();\r\nqi::parse(begin, end, qi::int_[func]);     \/\/ this will call func\r\n<\/pre>\n
Most of the time this is not sufficient as a semantic action is expected to receive the matched attribute value. This is possible by writing:<\/p>\n
\r\nvoid func(int attribute)\r\n{\r\n    std::cout << "Matched integer: " << attribute << "\\n";\r\n}\r\n<\/pre>\n
The type of the expected parameter (in this case the int<\/span>) depends on the parser the semantic action is attached to. The attribute type exposed by the parser has to be convertible to the argument type.<\/p>\n
There are actually 2 more arguments being passed: the parser context and a reference to a boolean ‘hit’ parameter. The parser context is meaningful only if the semantic action is attached somewhere to the right hand side of a rule. We will see more information about this shortly. The boolean value can be set to false inside the semantic action invalidating the match in retrospective, making the parser fail. Qi<\/em> allows us to bind a nullary or a single argument function, like above. The other arguments are simply ignored.<\/p>\n
It is feasible to bind any function object (such as generated by Boost.Bind<\/a> or Boost.Lambda<\/a>) as an semantic action. Even if the documentation shows a couple of examples (see here<\/a>), I would not recommend using those libraries in this context. For me the preferred method of writing semantic actions is to employ Boost.Phoenix<\/a> – a companion library bundled with Spirit<\/em>. It is like Boost.Lambda<\/a> on steroids, with special custom features that make it easy to integrate semantic actions with Spirit. If your requirements go beyond simple parsing, I suggest that you use this library. All the following examples in this article will use Boost.Phoenix<\/a> for semantic actions. But whatever method you use, please let me highlight the following:<\/p>\n
The three libraries allow you to utilize special placeholders to control parameter placement (_1<\/code>, _2<\/code>, etc.). Unfortunately, each of those libraries has it’s own implementation of the placeholders, all in different namespaces. You have to make sure not to mix placeholders with a library they don’t belong to and not to use different libraries while writing a semantic action.<\/p>\n
Generally, for Boost.Bind<\/a>, use ::_1<\/code>, ::_2<\/code>, etc. (yes, these placeholders are defined in the global namespace).<\/p>\n
For Boost.Lambda<\/a> use the placeholders defined in the namespace boost::lambda<\/code>.<\/p>\n
For semantic actions written using Boost.Phoenix<\/a> use the placeholders defined in the namespace boost::spirit<\/code>. Please note that all existing placeholders for your convenience are also available from the namespace boost::spirit::qi<\/code>.<\/p><\/blockquote>\n
The current version of Spirit (V2.2) does not yet support binding a native C++0x lambda function as a semantic action, but this is something we are currently working on. You can expect this to be possible in the near future.<\/p>\n
Writing Phoenix based Semantic Actions<\/h5>\n
Writing a semantic action with Phoenix is beneficial as Spirit<\/em>\u00a0 ‘knows’ about Phoenix. If you write them with the help of Phoenix you can utilize special placeholders Spirit<\/em> provides you with. Those placeholders refer to elements in the context of the current parser execution such as attributes, local variables and inherited attributes of rules, etc. None of the other means of writing semantic actions (using Bind, Lambda, or hand written function objects) gives you direct access to those elements. The following table lists all available placeholders exposed by Spirit (as mentioned earlier, all are defined in the namespace boost::spirit::qi<\/span>). Again, please note, these are only available inside a semantic action and only if the semantic action is written utilizing Phoenix.<\/p>\n\n\n\n\n\n\n\n\n\n
Placeholder<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
_1, _2, ... , _N<\/code><\/td>\nNth attribute of the parser p<\/code><\/td>\n<\/tr>\n
\n
_pass<\/code><\/dt>\n<\/td>\n
Assign false<\/code> to _pass<\/code> to force a generator failure.<\/td>\n<\/tr>\n
\n
_val<\/code><\/dt>\n<\/td>\n
The enclosing rule’s synthesized attribute.<\/td>\n<\/tr>\n
\n
_r1, _r2, ... , _rN<\/code><\/dt>\n<\/td>\n
The enclosing rule’s Nth inherited attribute.<\/td>\n<\/tr>\n
\n
_a, _b, ... , _j<\/code><\/dt>\n<\/td>\n
The enclosing rule’s local variables (_a<\/code> refers to the first).<\/td>\n<\/tr>\n
\u00a0<\/td>\n\u00a0<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Obviously, the placeholders listed in the last three rows of the table are meaningful only if used in a rule definition. As an example, let us rewrite the semantic action from above with Phoenix:<\/p>\n
\r\nstd::string input("1234");\r\nstd::string::const_iterator begin = input.begin();\r\nstd::string::const_iterator end = input.end();\r\nqi::parse(begin, end,\r\n    qi::int_\r\n    [\r\n        std::cout << "Matched integer: " << qi::_1 << "\\n";\r\n    ]\r\n);\r\n<\/pre>\n
One problem with earlier versions of Spirit (i.e. Spirit.Classic<\/em>) was that while parsing sequences of things it was difficult to avoid calling a semantic action prematurely. For instance, in a parser sequence of two integer parsers (int_[f1] >> ‘,’ >> int_[f2]<\/span>) the function f1<\/span> got called immediately after the first integer matched, and even if the second integer parser would fail later on. In the current version of Spirit this is not an issue anymore as it is possible to attach a semantic action to the whole sequence while still referring to the single attributes of the different sequence elements:<\/p>\n
\r\nstd::string input("1234,2345");\r\nstd::string::const_iterator begin = input.begin();\r\nstd::string::const_iterator end = input.end();\r\nqi::parse(begin, end,\r\n    (qi::int_ >> ',' >> qi::int_)\r\n    [\r\n        std::cout << "Matched integers: "\r\n              << qi::_1 << " and " << qi::_2 << "\\n";\r\n    ]\r\n);\r\n<\/pre>\n
Here, qi::_1<\/span> refers to the attribute matched by the first integer parser, and qi::_2<\/span> to the second one.<\/p>\n
Initially I was planning to additionally describe the internal interface of a semantic action. Utilizing this interface allows you to write your own function objects and still to get access to the elements of the parser context mentioned above (attributes, the rule’s local variables and inherited attributes, etc.). But this post already got longer as anticipated, which is why I defer this discussion to a second Tip of the Day. Stay tuned!<\/p>\n
Share this:<\/h3>