{"id":854,"date":"2010-01-14T07:11:15","date_gmt":"2010-01-14T15:11:15","guid":{"rendered":"http:\/\/boost-spirit.com\/home\/2010\/01\/14\/why-might-i-want-to-use-the-directive-qiraw\/"},"modified":"2010-01-18T19:10:08","modified_gmt":"2010-01-19T03:10:08","slug":"why-might-i-want-to-use-the-directive-qiraw","status":"publish","type":"post","link":"http:\/\/boost-spirit.com\/home\/2010\/01\/14\/why-might-i-want-to-use-the-directive-qiraw\/","title":{"rendered":"Why might I want to use the directive qi::raw[ ]?"},"content":{"rendered":"

Over at the Freenet #boost IRC channel somebody (I think it was @VeXocide) suggested to write a ‘Tip of the Day’ about the Qi<\/em> directive raw[]<\/span>. I was told this ‘was a major stumbling stone’ while learning Qi<\/em>. I always appreciate to get suggestions for articles, so here we go\u2026<\/p>\n

<\/p>\n

For those of you following the discussions around Spirit, the raw[]<\/span> directive might be somewhat surprising. Almost every introduction talks about Spirit<\/em> as being fully attributed. That means that every component exposes its own, specific attribute type representing the matched input (in Qi<\/em>) or the data to emit output for (in Karma<\/em>). This is a major change from earlier Spirit<\/em> versions (we call those Classic<\/em> today) which created so called transduction parsers. Transduction parsers ‘return’ a pair of pointers (iterators) to the matched portion of the input without attempting to convert it to any specific result type.<\/p>\n

The directive qi::raw[]<\/span> reintroduces transduction parsing into Qi<\/em>. It is doing that by exposing as its attribute the pair of iterators to the input sequence matched by its embedded parser. To be concise, it exposes an instance\u00a0 of a boost::iterator_range<Iterator><\/span> containing the two iterators (where Iterator<\/span> is the type of the underlying input stream as passed to qi::parse<\/span>).<\/p>\n

Here is an example matching any valid C++ identifier:<\/p>\n

\r\nnamespace qi = boost::spirit::qi;\r\nstd::string input("abc123_");\r\nstd::string::const_iterator b = input.begin();\r\nstd::string ident;\r\nqi::parse(b, input.end(),\r\n    qi::raw[(qi::alpha | '_') >> *(qi::alnum | '_')], ident);\r\n<\/pre>\n
This example works as expected as the std::string<\/span> attribute (the variable ident<\/span>) is compatible with the raw[]<\/span> component (the std::string<\/span> implements a similar constructor as the iterator_range<\/span> natively supported by raw[]<\/span>). The embedded parser will match the C++ identifier without any attribute conversion as the raw[]<\/span> invokes it with an attribute of the type unused_type<\/span>, effectively disabling attribute handling. If the embedded parser succeeds the iterators pointing to the matched input sequence are used to initialize the std::string<\/span> passed in as the attribute. Voila!<\/p>\n
In this example it would be just more complex (but still possible) to write a parser expression utilizing Spirit’s<\/em> built in attribute propagation rules. At least you would need to write char_(‘_’)<\/span> instead of the plain ‘_’<\/span>. Sometimes though, for other use cases,\u00a0 it is a lot more difficult or just impossible to employ the attribute magic. That is where raw[]<\/span> really shines. It allows to embed complex parser expressions without having to worry about attribute matching and propagation. The embedded parser will run as fast as possible as it is invoked in ‘match mode’ only, which skips attribute conversion.<\/p>\n
Share this:<\/h3>