[Boost-commit] svn:boost r69293 - in trunk/libs/spirit: doc doc/karma doc/qi test/karma test/qi

Subject: [Boost-commit] svn:boost r69293 - in trunk/libs/spirit: doc doc/karma doc/qi test/karma test/qi
From: hartmut.kaiser_at_[hidden]
Date: 2011-02-25 23:07:33

Author: hkaiser
Date: 2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
New Revision: 69293
URL: http://svn.boost.org/trac/boost/changeset/69293

Log:
Spirit: added context to top level APIs, added docs, added tests
Text files modified: 
   trunk/libs/spirit/doc/karma/concepts.qbk     |     4 ++                                      
   trunk/libs/spirit/doc/karma/generate_api.qbk |     6 +++                                     
   trunk/libs/spirit/doc/qi/concepts.qbk        |     4 ++                                      
   trunk/libs/spirit/doc/qi/parse_api.qbk       |     6 +++                                     
   trunk/libs/spirit/doc/spirit2.qbk            |     3 +                                       
   trunk/libs/spirit/doc/what_s_new.qbk         |    66 ++++++++++++++++++++++++++------------- 
   trunk/libs/spirit/test/karma/int2.cpp        |    14 ++++++++                                
   trunk/libs/spirit/test/karma/pattern2.cpp    |    17 ++++++++++                              
   trunk/libs/spirit/test/karma/symbols1.cpp    |     2                                         
   trunk/libs/spirit/test/karma/symbols2.cpp    |     2                                         
   trunk/libs/spirit/test/karma/symbols3.cpp    |     2                                         
   trunk/libs/spirit/test/qi/int3.cpp           |    16 +++++++++                               
   trunk/libs/spirit/test/qi/rule4.cpp          |    17 ++++++++++                              
   13 files changed, 132 insertions(+), 27 deletions(-)

Modified: trunk/libs/spirit/doc/karma/concepts.qbk
==============================================================================
--- trunk/libs/spirit/doc/karma/concepts.qbk	(original)
+++ trunk/libs/spirit/doc/karma/concepts.qbk	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -356,6 +356,10 @@
 attribute. The `_val` placeholder acts like an immutable reference to the
 Nonterminal's attribute.
 
+[note Starting with __spriti__ V2.4.2 (distributed with Boost V1.46) the 
+      placeholder `_val` can be used in semantic actions attached to top level
+      generator components as well. See __generator_api__ for more information.]
+
 [heading `_r1`...`r10`]
 
 The `boost::spirit::_r1`...`boost::spirit::r10` placeholders can be used

Modified: trunk/libs/spirit/doc/karma/generate_api.qbk
==============================================================================
--- trunk/libs/spirit/doc/karma/generate_api.qbk	(original)
+++ trunk/libs/spirit/doc/karma/generate_api.qbk	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -100,6 +100,12 @@
           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
     }}}
 
+[note Starting with __spriti__ V2.4.2 (distributed with Boost V1.46) the 
+      placeholder `_val` can be used in semantic actions attached to top level
+      generator components. In this case `_val` refers to the supplied attribute
+      as a whole. For API functions taking more than one attribute argument
+      `_val` will refer to a Fusion vector or references to the attributes.]
+
 __karma__ generator API functions based on the automatic creation of the 
 matching generator type:
 

Modified: trunk/libs/spirit/doc/qi/concepts.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/concepts.qbk	(original)
+++ trunk/libs/spirit/doc/qi/concepts.qbk	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -340,6 +340,10 @@
 attribute. The `_val` placeholder acts like a mutable reference to the
 Nonterminal's attribute.
 
+[note Starting with __spriti__ V2.4.2 (distributed with Boost V1.46) the 
+      placeholder `_val` can be used in semantic actions attached to top level
+      parser components as well. See __parse_api__ for more information.]
+
 [heading `_r1` ... `r10`]
 
 The `boost::spirit::_r1` ... `boost::spirit::r10` placeholders can be used

Modified: trunk/libs/spirit/doc/qi/parse_api.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/parse_api.qbk	(original)
+++ trunk/libs/spirit/doc/qi/parse_api.qbk	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -103,6 +103,12 @@
           , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN);
     }}}
 
+[note Starting with __spriti__ V2.4.2 (distributed with Boost V1.46) the 
+      placeholder `_val` can be used in semantic actions attached to top level
+      parser components. In this case `_val` refers to the supplied attribute
+      as a whole. For API functions taking more than one attribute argument
+      `_val` will refer to a Fusion vector or references to the attributes.]
+
 __qi__ parser API functions based on the automatic creation of the matching 
 parser type:
 

Modified: trunk/libs/spirit/doc/spirit2.qbk
==============================================================================
--- trunk/libs/spirit/doc/spirit2.qbk	(original)
+++ trunk/libs/spirit/doc/spirit2.qbk	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -114,6 +114,8 @@
 
 [template karma_format[str]     [link spirit.karma.reference.generate_api.stream_api [str]]]
 
+[__generator_api__              [link spirit.karma.reference.generate_api The Generator API]]
+
 [/ References to classes ]
 
 [def __utree__                  [link spirit.support.utree `utree`]]
@@ -430,6 +432,7 @@
 [template qi_auto[str]              [link spirit.qi.reference.auto [str]]]
 [def __create_parser__              [link spirit.qi.reference.parse_api.create_parser `create_parser`]]
 
+[__parse_api__                      [link spirit.qi.reference.parse_api The Parse API]]
 
 [/ Here we go ]
 

Modified: trunk/libs/spirit/doc/what_s_new.qbk
==============================================================================
--- trunk/libs/spirit/doc/what_s_new.qbk	(original)
+++ trunk/libs/spirit/doc/what_s_new.qbk	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -15,8 +15,39 @@
 
 [heading 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 __qi__ and
+  __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 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 __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.
+
 [heading Bug Fixes in Qi or Karma]
 
+* __qi__ integer literals (like `int_(10)`) do not consume input on failure
+  anymore.
+
 [heading Breaking Changes]
 
 * The __qi__ directive __qi_repeat__ erroneously implemented commit/rollback
@@ -24,6 +55,11 @@
   This behaviour has been removed as it is inconsistent with similar components.
   Existing code relying on this functionality will break. Please refer to the
   __qi__ directive __qi_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_`.
 
 [heading Making Stuff Work]
 
@@ -39,17 +75,6 @@
   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.
-* 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 produced a type `int__type` with a bogus double underscore
-  that is not allowed in C++.
-* 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_`.
 
 [endsect]
 
@@ -61,13 +86,8 @@
 [heading New Features in Qi or Karma]
 
 * Added keyword indexes for __qi__ and __karma__ to the docs.
-* Added __utree__, a generic, hierarchical, and dynamic data structure that can
-  represent abstract syntax trees. It's well integrated with __qi__ and
-  __karma__. It can be passed as an attribute while parsing almost any
-  grammars. At the same time, it can be used as an attribute to generate output
-  from.
 * Introduced a new customization point __customize_assign_to_container_from_value__
-  which is invoked for container attributes whenever a attribute value needs to
+  which is invoked for container attributes whenever an attribute value needs to
   be added to that container.
 * Replaced `proto::lit` (which was used to implement `spirit::lit`) with a
   separate version allowing to distinguish 'lit(foo)' from 'foo'. This should
@@ -102,7 +122,7 @@
   tokens based on a given token id. The difference to `qi::token()` is, that it
   exposes as its attribute the token id of the matched token (instead of the
   iterator_range of the matched input, as `qi::token()` does).
-* Added additional template parameter to the default `lexertl::token<>`
+* Added an additional template parameter to the default `lexertl::token<>`
   definition: the type of the token id. This type defaults to `std::size_t`.
   Any type used as the id type needs to be (explicitly) convertible from
   `std::size_t`.
@@ -132,9 +152,9 @@
 
 [heading Bug Fixes in Lex]
 
-* Fixed a problem in the Lexer giving problems to assign tokens to all lexer
-  states at once. This is now possible by simply using "*" as the state name.
-  For instance this will add the token int_ to all lexer states:
+* Fixed an issue in the Lexer giving problems while assigning tokens to all 
+  lexer states at once. This is now possible by simply using "*" as the state 
+  name. For instance this will add the token int_ to all lexer states:
 ``
     template <typename Lexer>
     struct lexer : lex::lexer<Lexer>
@@ -160,8 +180,8 @@
 
 [heading Known Problems]
 
-* Integer literals (like `int_(10)`) consume input on failure, which can lead to
-  problems with the alternative operator:
+* __qi__ integer literals (like `int_(10)`) consume input on failure, which can 
+  lead to problems with the alternative operator.
 
 [endsect]
 

Modified: trunk/libs/spirit/test/karma/int2.cpp
==============================================================================
--- trunk/libs/spirit/test/karma/int2.cpp	(original)
+++ trunk/libs/spirit/test/karma/int2.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -21,6 +21,7 @@
 #include <boost/spirit/include/karma_numeric.hpp>
 #include <boost/spirit/include/karma_directive.hpp>
 #include <boost/spirit/include/karma_action.hpp>
+#include <boost/spirit/include/karma_rule.hpp>
 #include <boost/spirit/include/karma_phoenix_attributes.hpp>
 
 #include <limits>
@@ -163,6 +164,19 @@
         BOOST_TEST(test_delimited("ff ", lower[lower[hex]], 0xff, char_(' ')));
     }
 
+    ///////////////////////////////////////////////////////////////////////////
+    {
+        using boost::spirit::karma::int_;
+        using boost::spirit::karma::_1;
+        using boost::spirit::karma::_val;
+        using boost::spirit::karma::space;
+
+        int i = 123;
+        int j = 456;
+        BOOST_TEST(test("123", int_[_1 = _val], i));
+        BOOST_TEST(test_delimited("456 ", int_[_1 = _val], j, space));
+    }
+
     return boost::report_errors();
 }
 

Modified: trunk/libs/spirit/test/karma/pattern2.cpp
==============================================================================
--- trunk/libs/spirit/test/karma/pattern2.cpp	(original)
+++ trunk/libs/spirit/test/karma/pattern2.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -133,6 +133,23 @@
         BOOST_TEST(test_delimited("12.4 ", d, v, space));
     }
 
+    ///////////////////////////////////////////////////////////////////////////
+    {
+        using boost::spirit::karma::int_;
+        using boost::spirit::karma::_1;
+        using boost::spirit::karma::_val;
+        using boost::spirit::karma::space;
+        using boost::spirit::karma::space_type;
+
+        karma::rule<outiter_type, int()> r1 = int_;
+        karma::rule<outiter_type, space_type, int()> r2 = int_;
+
+        int i = 123;
+        int j = 456;
+        BOOST_TEST(test("123", r1[_1 = _val], i));
+        BOOST_TEST(test_delimited("456 ", r2[_1 = _val], j, space));
+    }
+
     return boost::report_errors();
 }
 

Modified: trunk/libs/spirit/test/karma/symbols1.cpp
==============================================================================
--- trunk/libs/spirit/test/karma/symbols1.cpp	(original)
+++ trunk/libs/spirit/test/karma/symbols1.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -1,4 +1,4 @@
-//  Copyright (c) 2001-2010 Hartmut Kaiser
+//  Copyright (c) 2001-2011 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)

Modified: trunk/libs/spirit/test/karma/symbols2.cpp
==============================================================================
--- trunk/libs/spirit/test/karma/symbols2.cpp	(original)
+++ trunk/libs/spirit/test/karma/symbols2.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -1,4 +1,4 @@
-//  Copyright (c) 2001-2010 Hartmut Kaiser
+//  Copyright (c) 2001-2011 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)

Modified: trunk/libs/spirit/test/karma/symbols3.cpp
==============================================================================
--- trunk/libs/spirit/test/karma/symbols3.cpp	(original)
+++ trunk/libs/spirit/test/karma/symbols3.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -1,4 +1,4 @@
-//  Copyright (c) 2001-2010 Hartmut Kaiser
+//  Copyright (c) 2001-2011 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)

Modified: trunk/libs/spirit/test/qi/int3.cpp
==============================================================================
--- trunk/libs/spirit/test/qi/int3.cpp	(original)
+++ trunk/libs/spirit/test/qi/int3.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -8,6 +8,7 @@
 =============================================================================*/
 
 #include "int.hpp"
+#include <boost/spirit/include/qi_rule.hpp>
 
 int
 main()
@@ -135,7 +136,20 @@
         BOOST_TEST(n == 456);
         BOOST_TEST(!test("   456", int_(654)[ref(n) = _1], space));
     }
-    
+
+    ///////////////////////////////////////////////////////////////////////////
+    {
+        using boost::spirit::qi::int_;
+        using boost::spirit::qi::_1;
+        using boost::spirit::qi::_val;
+        using boost::spirit::qi::space;
+
+        int i = 0;
+        int j = 0;
+        BOOST_TEST(test_attr("456", int_[_val = _1], i) && i == 456);
+        BOOST_TEST(test_attr("   456", int_[_val = _1], j, space) && j == 456);
+    }
+
     ///////////////////////////////////////////////////////////////////////////
     //  parameterized lazy tests
     ///////////////////////////////////////////////////////////////////////////

Modified: trunk/libs/spirit/test/qi/rule4.cpp
==============================================================================
--- trunk/libs/spirit/test/qi/rule4.cpp	(original)
+++ trunk/libs/spirit/test/qi/rule4.cpp	2011-02-25 23:07:14 EST (Fri, 25 Feb 2011)
@@ -166,6 +166,23 @@
         BOOST_TEST(test_attr("1", r, v) && at_c<0>(v) == 1);
     }
 
+    ///////////////////////////////////////////////////////////////////////////
+    {
+        using boost::spirit::qi::int_;
+        using boost::spirit::qi::_1;
+        using boost::spirit::qi::_val;
+        using boost::spirit::qi::space;
+        using boost::spirit::qi::space_type;
+
+        rule<const char*, int()> r1 = int_;
+        rule<const char*, int(), space_type> r2 = int_;
+
+        int i = 0;
+        int j = 0;
+        BOOST_TEST(test_attr("456", r1[_val = _1], i) && i == 456);
+        BOOST_TEST(test_attr("   456", r2[_val = _1], j, space) && j == 456);
+    }
+
     return boost::report_errors();
 }