boost_1_45_0/libs/spirit/doc/what_s_new.qbk

[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2010 Hartmut Kaiser

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section What's New]

[/////////////////////////////////////////////////////////////////////////////]
[section:spirit_2_4_1 Spirit V2.4.1] 

[heading What's changed in __qi__ and __karma__ from V2.4 (Boost V1.44.0) to V2.4.1 (Boost V1.45.0)]

[heading Bug Fixes]

* Fixed broken __qi__ debugging facilities for optional attributes.
* The __qi__ auto parsers and __karma__ auto generators will now properly work 
  with `signed char` and `unsigned char` as well.
* Fixed a problem in the multi_pass fixed_queue policy.
* Enabled proper modifier handling for the __qi_skip__ directive.
* Fixed a floating point formating problem in Karma (Trac ticket #4742).
* Fixed a problem in [qi_repeat `repeat`]`[]`, which caused the `first` 
  iterator not to be reset on certain parsing failures (see 
  [@http://stackoverflow.com/questions/4009752/boost-spirit-bug-when-mixing-alternates-with-optionals Stack Overflow]).

[endsect] [/ spirit_2_4_1]

[/////////////////////////////////////////////////////////////////////////////]
[section:spirit_2_4 Spirit V2.4] 

[heading What's changed in __qi__ and __karma__ from V2.3 (Boost V1.43.0) to V2.4 (Boost V1.44.0)]

[heading New Features]

* The customization point __customize_transform_attribute__ now takes an additional template
  parameter `Domain` allowing to better specialize the customization point
  for either `qi::domain` or `karma::domain`. 

[important This is a interface breaking change requiring to modify existing 
           code. If you have a specialization of this customization point in 
           your code you need to add the specialization for the new template 
           parameter, i.e. either `qi::domain` or `karma::domain`.]
* Semantic actions in __qi__ now implicitly invoke the function `pre` of the
  customization point __customize_transform_attribute__ to convert the supplied 
  attribute to the exposed attribute type, as needed. The functions 
  `post` and `fail` of this customization point are not invoked by this 
  component (as this would not make any sense).
* Semantic actions in __karma__ now implicitly invoke the function `pre` of the
  customization point __customize_transform_attribute__ to convert the supplied 
  attribute to the consumed attribute type, as needed. 
* Added the __karma__ __karma_skip__ directive which is semantically equivalent
  to the __karma__ __karma_omit__ directive except that it will not execute the 
  embedded generator.
* Added debug support to __karma__ rules. 
* Added strict mode to __karma__, leaving the current behavior (unchanged) as 
  relaxed mode. Added __karma__ compile time directives `strict[]` and 
  `relaxed[]` allowing to switch between the two.
* Added __karma__ __karma_duplicate__ directive which duplicates the supplied
  attribute to all elements of an embedded generator sequence.

[heading Bug Fixes]

* Components in __qi__ and __karma__ now accept one element Fusion sequences as
  their attributes as long as the element in the Fusion sequence is compatible
  with the component's attribute type.
* The character range parser and generator components can now additionally be 
  written as `char_("a", "z")` instead of `char_('a', 'z')` making it 
  consistent with the syntax of the `char_('a')` component (which can be 
  written as `char_("a")` as well). Please note that the mixed syntax forms,
  i.e. `char_('a', "z")` and `char_("a", 'z')`, are not supported.
* Fixed attribute handling in __karma__ sequences when all elements of that
  sequence consume either the same attribute type or containers of that 
  attribute type and the passed in attribute is a container of that attribute 
  type as well. In this case using a repetitive container was supported only
  when it was the last element of the sequence. Now it is possible to 
  have a [karma_repeat `repeat`]`(num)[a]` generator at any position (well, 
  actually you can have any repetitive container at any position now, but this 
  doesn't always make sense as it normally would eat up all supplied attribute 
  values).
* Fixed debug output for variants where a variant element is an STL sequence.
* Fixed a problem in multi_pass, avoiding to loose a character at end of input
  when switching iterators.

[heading What's changed in __lex__ from V2.3 (Boost V1.43.0) to V2.4 (Boost V1.44.0)]

[heading New Lexer Features]

* The lexer is now well integrated with the debug output generated by Qi's
  simple_trace utility. Tokens are printed as: '<' matched sequence '>'.

[heading Lexer Bug Fixes]

* Fixed a problem with using lex::_val as a rvalue in lexer semantic 
  expressions.
* Token values are now available for introspection (as an iterator_range) 
  inside lexer semantic expressions as well.

[endsect] [/ spirit_2_4]

[/////////////////////////////////////////////////////////////////////////////]
[section:spirit_2_3 Spirit V2.3] 

[heading What's changed in __qi__ and __karma__ from V2.2 (Boost V1.42.0) to V2.3 (Boost V1.43.0)]

[heading New Features]

* The customization point `transform_attribute` now has to implement a third 
  function: `void fail(Exposed&)`, which normally will do nothing. This function
  will be called whenever the right hand side of the `rule` (or the embedded
  parser of `attr_cast`) fail parsing. This change affects /Qi/ only. See
  the description of the __customize_transform_attribute__ for more details.
* Added support for attribute sequences created with `BOOST_FUSION_ADAPT_CLASS` 
  and `BOOST_FUSION_ADAPT_CLASS_NAMED`. This support requires to include the 
  new header file: `#include <boost/spirit/inlcude/support_adapt_class_attributes.hpp>`.
* Added `karma::ostream_iterator` as a counterpart to `qi::istream_iterator` 
  (see new header file: `#include <boost/spirit/home/support/iterators/ostream_iterator.hpp>`).
* Added `qi::hold` allowing to make sure the embedded parser does not touch
  the passed attribute in case it fails parsing.
* Added [qi_no_skip `qi::no_skip`] directive, which is equivalent to 
  `qi::`__qi_lexeme__, except that it does not pre-skip.
* Added [karma_no_delimit `karma::no_delimit`] directive, which is equivalent to 
  `karma::`__karma_verbatim__, except that it does not perform a post-delimiting
  step.
* Added a new input_iterator policy for the `multi_pass` iterator framework
  (named `buffering_input_iterator`) allowing to wrap underlying input 
  iterators which do not store the last character read from the input (such as
  `std::istream_iterator`). This is now used as the default input policy.

[heading Bug Fixes]

* Sequences (in /Qi/ and /Karma/) may now have a component having no attribute 
  even as their last element.
* Sequences (in /Qi/ and /Karma/) can now take one element attribute sequences 
  as their attribute.
* Constructs like `karma::buffer[karma::buffer[...]]` don't result in 
  performing double buffering anymore. The same is true if an alternative is 
  wrapped into a `karma::buffer[]` directive (as for instance: `buffer[a] | b`).
* The __karma__ output iterator (which is used internally, but also is exposed
  when using the stream based API) is now properly copyable (thanks to Jonas 
  Persson for reporting this issue).
* The default `multi_pass` iterator is now usable with underlying input 
  iterators which do not store the last character read from the input (such as
  `std::istream_iterator`). Thanks to Larry Evans and Peter Schueller for 
  independently reporting this problem.
* The directive `karma::omit[]` now does not accept an arbitrary attribute 
  type anymore.
* The __karma__ predicates (the and-predicate and the not-predicate) and the 
  directive `karma::omit[]` now disable output altogether instead of 
  intercepting the output into a buffer which got discarded as before.
* Fixed `karma::rule` to properly handles optional attributes.

[heading What's changed in __lex__ from V2.2 (Boost V1.42.0) to V2.3 (Boost V1.43.0)]

[heading New Lexer Features]

* The library does not minimize the generated lexer tables for dynamic lexers by 
  default anymore. The generated tables will now be minimized for static lexers 
  only.
* The function `lexer<>::init_dfa()` now takes a single boolean parameter 
  (which defaults to `false`) allowing to force minimization of the generated
  lexer tables.

[endsect] [/ spirit_2_3]

[//////////////////////////////////////////////////////////////////////////////]
[section:spirit_2_2 Spirit V2.2] 

[heading What's changed in __qi__ and __karma__ from V2.1 (Boost V1.41.0) to V2.2 (Boost V1.42.0)]

[heading New Features]

* Added `auto_` component in __qi__ and __karma__, added API functions 
  `qi::`__create_parser__ and `karma::`__create_generator__.
* Added `auto_` based overloads for all API functions taking no attributes (see
  [link spirit.qi.reference.parse_api /Qi/ API] and 
  [link spirit.karma.reference.generate_api /Karma/ API]).
* Added [karma_columns `karma::columns`] directive.
* Added `karma::`__karma_symbols__ generator.
* The __qi__ customization point __customize_push_back_container__ now returns 
  a `bool` to report whether the item has been added to the container.
* Added an overload for [karma_maxwidth `karma::maxwidth`] directive allowing 
  to specify an additional parameter (any compatible output iterator) receiving 
  the 'overspilled' output (output not fitting into the maxwidth limit).
* It is now possible to use Phoenix expressions as __karma__ attributes.
* Added [link spirit.support.multi_pass.reading_from_standard_input_streams `basic_istream_iterator<Char, Traits>`]
  usable as an equivalent for `std::istream_iterator` except its a __fwditer__
  allowing to parse directly from any `std::basic_istream`.
* Added `qi::`__qi_matches__ directive.

[heading Bug Fixes]

* Fixed karma::alternatives to work with embedded containers of hold_any (i.e.
  constructs like `*stream | "empty"` (which fixes the Karma example 
  basic_facilities.cpp).
* Fixed numeric __karma__ generators for character types.
* Fixed `qi::repeat[]` for unused attributes.
* Fixed rare compilation problem in `karma::repeat[]`.
* Fixed sequences in __qi__ and __karma__ to compile properly if the attribute 
  is a (STL) container of (STL) containers.
* Fixed a problem in `lex::token_def::what`.
* Fixed __qi__ symbols not to match substrings anymore. Added 
  `qi::symbols::prefix_find` to allow matching of (prefix-) substrings.
* Inherited parameters for rule's usually have to be wrapped in function 
  objects (i.e. `phoenix::val`), for integral values this was not necessary. 
  Now all string types can be passed without being wrapped as well (i.e. 
  `std::string`, `char const*`, etc.).
* Added concept checks to all relevant __qi__ API functions enforcing the 
  iterator to be at least of the type `std::forward_iterator_tag`.
* Fixed the `qi::match` and `qi::phrase_match` set of API functions not to
  internally utilize a `std::stream_iterator` anymore as this iterator is of 
  the type `std::input_iterator_tag` only, which is not sufficient for __qi__.

[endsect] [/ spirit_2_2]

[//////////////////////////////////////////////////////////////////////////////]
[section:spirit_2_1 Spirit V2.1] 

[heading What's changed in __qi__ and __karma__ from V2.0 (Boost V1.37.0) to V2.1 (Boost V1.41.0)]

* __spirit__ is now based on the newest version of __boost_proto__
* `qi::phrase_parse`, `qi::phrase_format` now post-skip by default.
* `karma::generate_delimited` and `karma::format_delimited` now don't do pre-
  delimiting by default.
* Changed parameter sequence of `qi::phrase_parse`, `qi::phrase_match`, 
  `karma::generate_delimited`, and `match_delimited`. The attribute is now 
  always the last parameter.
* Added new overloads of those functions allowing to explicitly specify the
  post-skipping and pre-delimiting behavior.
* Added multi attribute API functions
* Removed `grammar_def<>`
* Removed functions `make_parser()` and `make_generator()`
* Removed `qi::none` and `karma::none`
* Sequences and lists now accept a standard container as their attribute
* The string placeholder terminal now can take other strings as its parameter 
  (i.e. std::string)
* All terminals taking literals now accept a (lazy) function object as well
* All placeholders for terminals and directives (such as `int_`, `double_`, 
  `verbatim`, etc.) were previously defined in the namespace `boost::spirit` 
  only. Now these are additionally imported into the namespaces
  `spirit::qi`, `spirit::karma`, and `spirit::lex` (if they are supported by 
  the corresponding sub-library).
* The terminal placeholders `char_` and `string` are not defined in the
  namespace `boost::spirit` anymore as they have been moved to the 
  character set namespaces, allowing to do proper character set 
  handling based on the used namespace (as `spirit::ascii`, etc.)
* The `uint`, `ushort`, `ulong`, and `byte` terminal placeholders have been 
  renamed to `uint_`, `ushort_`, `ulong_`, and `byte_`.
* `qi::skip[]` now re-enables outer skipper if used inside `lexeme[]`
* Added `karma::maxwidth[]` directive (see [karma_maxwidth `maxwidth`])
* Added `karma::omit[]` allowing to consume the attribute of subject generator 
  without emitting any output (see __karma_omit__).
* Added `karma::buffer[]` allowing to avoid unwanted output to be generated in 
  case of a generator failing in the middle of a sequence (see __karma_buffer__).
* `karma::delimit[]` now re-enables outer delimiter if used inside `verbatim[]`
* Karma: added and-predicate (`operator&()`) and not-predicate (`operator!()`)
  Both now always consume an attribute.
* Karma: changed semantics of `char_()`, `string()`, `int_()` et.al., and 
  `double_()` et.al.: all of these generators now always expose an attribute. 
  If they do not have an associated attribute, they generate their immediate 
  literal. If they have an associated attribute, the generators first test if 
  the attribute value is equal to the immediate literal. They fail and do not 
  generate anything if those are not equal. Otherwise they generate their 
  immediate literal. For more information see for instance [signed_int `int_`].
* `karma::lit()` can now be used to generate integer and floating point numbers
* `qi::rule` and `karma::rule` now can be directly initialized using their copy
  constructor. I.e. this works now: `qi::rule<...> r = ...some parser...;`.
* Added `qi::attr()` exposing its immediate parameter as its attribute. 
* Added boolean parsers and generators (`bool_`, `true_`, `false_`).
* Added `attr_cast<>` enabling in place attribute type conversion in Qi and Karma 
  grammars.
* Almost all Karma generators now accept `optional<>` attributes and will fail
  generating if this is not initialized.
* Qi and Karma rules now automatically detect whether to apply auto-rule 
  semantics or not (no need for using `operator%=()` anymore, even if it's still
  existing). Auto-rule semantics are applied if the right hand side has no
  semantic actions attached to any of the elements. This works for rule 
  initialization and assignment.
* Qi and Karma rules now do intrinsic attribute transformation based on the 
  attribute customization point __customize_transform_attribute__.
* All char_ parsers now always expose an attribute. Earlier `char_(...)` didn't 
  expose an attribute while `char_` did. If you need a literal parser not exposing 
  any attribute use `lit(...)` instead.
* The qi::int_spec, qi::real_spec, karma::int_spec, and karma real_spec types 
  do not exist anymore. These have been replaced with qi::int_parser, 
  qi::real_parser, karma::int_generator, and karma::real_generator.

[heading What's changed in __lex__ from V2.0 (Boost V1.37.0) to V2.1 (Boost V1.41.0)]

Here is a list of changes in __lex__ since version 2.0. __lex__ 2.1 is a 
complete rewrite of the __lex__ distributed with Boost V1.37. As with all
code portions of the __spirit__ library, __lex__ is usable as stand alone piece.
__lex__ now uses the infrastructure provided by __spirit__ version 2.1.

* The lex::lexer_def class has been renamed to lex::lexer, while the original
  class lex::lexer does not exist anymore. This simplifies the creation of
  lexers.
* The lex::lexer class does not have the function `def(Self& self)` anymore, 
  token definitions can be added to the lexer at any time, usually in the 
  constructor of the user defined lexer class:
``
      template <typename Lexer>
      struct example_tokens : lex::lexer<Lexer>
      {
            example_tokens()
            {
                // your token definitions here
                this->self = ...
            }
      };
``
* The new lexer class can now be used directly. The function `make_lexer()` has 
  been removed.
* The `lex::tokenize_and_parse()` and `lex::tokenize_and_phrase_parse()` functions 
  have been changed to match the parameter sequence as implemented by the 
  `qi::parse()` and `qi::phrase_parse()` functions. 
  Both take an arbitrary number of attribute arguments as the last 
  parameters. This argument list is limited by the macro
  `SPIRIT_ARGUMENTS_LIMIT`.
* The `lex::lexertl_lexer`, and `lex::lexertl_token`
  classes have been moved to the `lex::lexertl` namespace and the names have been 
  changed to `lex::lexertl::lexer`, `lex::lexertl::token`. This also applies to 
  the `lex::lexert_actor_lexer`, and the `static_lexertl_*` family of types.
* The class `lex::lexertl_token_set` has been removed. This functionality is now 
  available from the lexer class.
* The __lex__ library has been updated to use the newest version of Ben 
  Hansons __lexertl__ lexer construction library (Boost review pending).
* The `lex::lexer<Lexer>` template constructor now takes an optional parameter
  specifying the `match_flags` to be used for table generation. Currently, there
  are the following flags available:
``
        match_flags::match_default,          // no flags
        match_flags::match_not_dot_newline,  // the regex '.' doesn't match newlines
        match_flags::match_icase             // all matching operations are case insensitive
``
  If no parameter is passed to the constructor, `match_flags::match_default` is 
  used, i.e. the `.` matches newlines and matching is case sensitive.

* The `char_()` and `string()` placeholders can now be used for token 
  definitions and are synonymous with `token_def`. 
* Lexer semantic actions now have to conform to a changed interface (see
  __sec_lex_semactions__ for details).
* Added placeholder symbols usable from the inside of lexer semantic actions 
  while using Phoenix: `lex::_start`, `lex::_end`, `lex::_eoi`, `lex::_state`, 
  `lex::_val`, and `lex::_pass` (see __sec_lex_semactions__ for more details).
* Added (lazy) support functions usable from the inside of lexer semantic
   actions while using Phoenix: `lex::more()`, `lex::less()`, and 
   `lex::lookahead()` (see  __sec_lex_semactions__ for more details).
* Removed `lex::omitted` in favor of `lex::omit` to unify the overall 
  interface.

[endsect] [/ spirit_2_1]

[/////////////////////////////////////////////////////////////////////////////]
[section:spirit_1_x Spirit Classic]

The Spirit V1.8.x code base has been integrated with Spirit V2. It is
now called __classic__. Since the directory structure has changed (the
Spirit Classic headers are now moved to the
'''$BOOST_ROOT/boost/spirit/home/classic''' directory), we created
forwarding headers allowing existing applications to compile without
any change. However, these forwarding headers are deprecated, which
will result in corresponding warnings generated for each of the
headers starting with Boost V1.38. The forwarding headers are expected
to be removed in the future.

The recommended way of using Spirit Classic now is to include header
files from the directory '''$BOOST_ROOT/boost/spirit/include'''. All
Spirit Classic headers in this directory have 'classic_' prefixed to
their name. For example the include

    #include <boost/spirit/core/core.hpp>

now should be written as:

    #include <boost/spirit/include/classic_core.hpp>

To avoid namespace conflicts with the new Spirit V2 library we moved
Spirit Classic into the namespace `boost::spirit::classic`. All
references to the former namespace `boost::spirit` need to be adjusted
as soon as the header names are corrected as described above. As an
alternative you can define the preprocessor constant
`BOOST_SPIRIT_USE_OLD_NAMESPACE`, which will force the Spirit Classic
code to be in the namespace `boost::spirit` as before. This is not
recommended, though, as it may result in naming clashes.

The change of the namespace will be automatically deactivated whenever
the deprecated include files are being used. This ensures full
backwards compatibility for existing applications.

[endsect] [/ spirit_1_x]

[endsect]