| Home | Libraries | People | FAQ | More

### Spirit V2.5

##### What's changed in Spirit.Qi and Spirit.Karma from V2.4.2 (Boost V1.46.0) to V2.5 (Boost V1.47.0)

This version of Spirit now supports the new version of Boost.Phoenix (V3), which has been released as part of Boost V1.47. Please note that this support is purely preliminary and should not be considered production quality. The reason why we are releasing this now is to enable people who want to use the new version of Boost.Phoenix in their code to do so without any conflicts with existing code using Spirit. Generally, no Spirit code needs to be changed. To activate the use of Boost.Phoenix V3 for Spirit you need to define the following preprocessor constant for your builds (before including any of Spirit's include files):

    #define BOOST_SPIRIT_USE_PHOENIX_V3 1

##### New Features in Qi or Karma

- Added `utree`, a generic, hierarchical, and dynamic data structure that can represent abstract syntax trees. It's well integrated with Spirit.Qi and Spirit.Karma. It can be passed as an attribute while parsing to almost any grammar. At the same time, it can be used as an attribute to generate output from.
- Added a new macro `BOOST_SPIRIT_TERMINAL_NAME` which takes in two parameters (the terminal name and its type). Before, there was only one parameter (the terminal name) and the type assumed the terminal name with `_type` appended. This produced invalid C++ identifiers with terminals such as `int_`, which resulted in generated a type `int__type` with a bogus double underscore that is reserved for system use in C++.
- The numeric parsers now allow arbitrary radix from 2..10 and 16
- The placeholder `_val` now can be used in top level semantic actions outside of any right hand side of a rule. Here is an example:

      int i = 0
      BOOST_TEST(test_attr("456", int_[_val = _1], i) && i == 456);

  In this case _val refers to the attribute value, which is passed in to the `parse()` or `phrase_parse()` functions. Similar constructs are now possible in Spirit.Karma as well:

      int i = 123;
      BOOST_TEST(test("123", int_[_1 = _val], i));

  This change unifies the handling of the `_val` placeholder allowing to use it everywhere, not only in semantic actions attached to the right hand sides of a rule.
- Added support for Spirit.Karma unsigned numeric generators with arbitrary radix values in the (inclusive) range from `2` .. `36`.

##### Bug Fixes in Qi or Karma

- Spirit.Qi integer literals (like `int_(10)`) do not consume input on failure anymore.
- Fixed TRAC#5246: mmap_file_iterator Fails to initialize correctly.
- Fixed TRAC#5246: mmap_file_iterator Fails to initialize correctly.
- Fixed a const correctness problem in `karma::real_policies<>` preventing the use of const floating point types with the generator. Thanks to Jeroen Habraken (a.k.a. VeXocide) for reporting it and for submitting a patch and a test.
- Fixed the Spirit.Qi `attr(attrib)` parser, the Spirit.Qi `symbols<>` parser, and the Spirit.Karma `symbols<>` generator to properly handle container attributes. These were broken in Boost V1.46.1 (thanks to Aaron Graham and Joerg Becker for reporting the problems).
- Fixed the `stream` parser to properly adjust the iterator of the underlying input stream in the case when the stream parser component was successful. Thanks to Brian O'Kennedy who reported the problem on Stackoverflow.
- Fixed failing Karma numerics generators when used with adapted ADTs (thanks to Colin Rundel for reporting that problem).

##### Breaking Changes

- The Spirit.Qi directive `repeat` erroneously implemented commit/rollback semantics for its attribute, leaving it untouched if the directive failed. This behaviour has been removed as it is inconsistent with similar components. Existing code relying on this functionality will break. Please refer to the Spirit.Qi directive `hold` to see how to fix your code.
- Added a preprocessor define `BOOST_SPIRIT_NO_PREDEFINED_TERMINALS` to prevent instantiations of predefined terminal objects which slows down compile time a lot. When `BOOST_SPIRIT_NO_PREDEFINED_TERMINALS` is defined, the user instantiates the terminals that he needs. So, instead of writing `using qi::uint_` one writes instead: `qi::uint_type uint_`.

##### New Features in Lex

- Added the possibility to specify a token id while creating a token definition using `lex::char_` and `lex::string`. Both primitives now accept a second parameter which will be interpreted as the requested token id for any token generated from this definition.
- Added a new token type `lex::lexertl::position_token<>`, which is essentially plup-in compatible with the existing `lex::lexertl::token<>` class. However it additionally stores the pair of iterators pointing to the underlying matched input sequence as an iterator_range.

##### Bug Fixes in Lex

- Fixed a problem with associating token definitions with all states (using `"*"` as the state name) when actions were attached to them.

##### Making Stuff Work

- Added the Spirit.Karma customization point `traits::extract_from_container`, which will be invoked instead of the older customization point `traits::extract_from` if the attribute is a container (`traits::is_container` returns `true` for the attribute).
- The type `hold_any` now takes a template argument: `basic_hold_any<Char>`, where `Char` is the character type used for the streaming operators (`operator>>()` and `operator<<()`). The `hold_any` is still available as a `typedef basic_hold_any<char> hold_any`;
- Semantic actions now support attribute compatibility. This is a breaking change but #define BOOST_SPIRIT_ACTIONS_ALLOW_ATTR_COMPAT must be defined in order for the new behavior to kick in. By default, the old behavior is still in place.
- Alternatives now support attribute compatibility.
- The attribute handling for container attributes of sequences and container components (list, Kleene, Plus, and repeat) has been completely rewritten. It now supports many more use cases and behaves much more predictable than the older version. Thanks to Thomas Taylor, Richard Crossley, Semen, Adalberto Castelo, and many others for reporting bugs and helping in making the new code behave as expected.