[Boost-commit] svn:boost r39823 - in trunk: boost/xpressive libs/xpressive/doc

From: eric_at_[hidden]
Date: 2007-10-08 18:41:00

Author: eric_niebler
Date: 2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
New Revision: 39823
URL: http://svn.boost.org/trac/boost/changeset/39823

Log:
symbols docs, acknowledgement for dave j., doxygen tweaks
Added:
   trunk/libs/xpressive/doc/symbols.qbk   (contents, props changed)
Text files modified: 
   trunk/boost/xpressive/regex_algorithms.hpp    |     8 +++-----                                
   trunk/libs/xpressive/doc/Jamfile.v2           |     3 ++-                                     
   trunk/libs/xpressive/doc/acknowledgements.qbk |    16 +++++++++++-----                        
   trunk/libs/xpressive/doc/actions.qbk          |     7 ++++---                                 
   trunk/libs/xpressive/doc/xpressive.qbk        |     2 ++                                      
   5 files changed, 22 insertions(+), 14 deletions(-)

Modified: trunk/boost/xpressive/regex_algorithms.hpp
==============================================================================
--- trunk/boost/xpressive/regex_algorithms.hpp	(original)
+++ trunk/boost/xpressive/regex_algorithms.hpp	2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
@@ -25,11 +25,9 @@
 #include <boost/xpressive/detail/core/state.hpp>
 #include <boost/xpressive/detail/utility/save_restore.hpp>
 
-#ifdef BOOST_XPRESSIVE_DOXYGEN_INVOKED
-# define BOOST_XPR_NONDEDUCED_TYPE_(x) x
-#else
-# define BOOST_XPR_NONDEDUCED_TYPE_(x) typename mpl::identity<x>::type
-#endif
+/// INTERNAL ONLY
+///
+#define BOOST_XPR_NONDEDUCED_TYPE_(x) typename mpl::identity<x>::type
 
 namespace boost { namespace xpressive
 {

Modified: trunk/libs/xpressive/doc/Jamfile.v2
==============================================================================
--- trunk/libs/xpressive/doc/Jamfile.v2	(original)
+++ trunk/libs/xpressive/doc/Jamfile.v2	2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
@@ -12,7 +12,8 @@
     :
         <doxygen:param>EXTRACT_ALL=YES
         <doxygen:param>"PREDEFINED=\"BOOST_XPRESSIVE_DOXYGEN_INVOKED\" \\
-                                   \"BOOST_DEDUCED_TYPENAME=typename\""
+                                   \"BOOST_DEDUCED_TYPENAME=typename\" \\
+                                   \"BOOST_XPR_NONDEDUCED_TYPE_(X)=X\""
         <doxygen:param>HIDE_UNDOC_MEMBERS=NO
         <doxygen:param>EXTRACT_PRIVATE=NO
         <doxygen:param>ENABLE_PREPROCESSING=YES

Modified: trunk/libs/xpressive/doc/acknowledgements.qbk
==============================================================================
--- trunk/libs/xpressive/doc/acknowledgements.qbk	(original)
+++ trunk/libs/xpressive/doc/acknowledgements.qbk	2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
@@ -18,11 +18,17 @@
 regarding the behavior of nested regex objects, and 
 [@http://boost.org/people/dave_abrahams.htm Dave Abrahams] for his suggestions
 regarding the regex domain-specific embedded language. Noel Belcourt helped
-porting xpressive to the Metrowerks CodeWarrior compiler. Markus Sch'''&ouml;'''pflin
-helped to track down a bug on HP Tru64, and Steven Watanabe suggested the fix.
+porting xpressive to the Metrowerks CodeWarrior compiler. Markus
+Sch'''&ouml;'''pflin helped to track down a bug on HP Tru64, and Steven
+Watanabe suggested the fix.
 
-I would also like to thank
-[@http://boost.org/people/thomas_witt.html Thomas Witt] for acting as
-xpressive's review manager.
+Special thanks are due to David Jenkins who contributed both ideas, code and
+documentation for xpressive's semantic actions, symbol tables and attributes.
+Xpressive's ternary search trie implementation is David's, as is the number
+parser example in [^libs/xpressive/example/numbers.cpp] and the documentation
+for symbol tables and attributes.
+
+Finally, I would like to thank [@http://boost.org/people/thomas_witt.html Thomas Witt]
+for acting as xpressive's review manager.
 
 [endsect]

Modified: trunk/libs/xpressive/doc/actions.qbk
==============================================================================
--- trunk/libs/xpressive/doc/actions.qbk	(original)
+++ trunk/libs/xpressive/doc/actions.qbk	2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
@@ -11,14 +11,14 @@
 
 Imagine you want to parse an input string and build a `std::map<>` from it. For
 something like that, matching a regular expression isn't enough. You want to 
-/do something/ when parts of your regular expression matches. Xpressive lets
+/do something/ when parts of your regular expression match. Xpressive lets
 you attach semantic actions to parts of your static regular expressions. This
 section shows you how.
 
 [h2 Semantic Actions]
 
 Consider the following code, which uses xpressive's semantic actions to parse
-of string of word/integer pairs and stuffs them into a `std::map<>`. It is
+a string of word/integer pairs and stuffs them into a `std::map<>`. It is
 described below.
 
     #include <string>
@@ -85,8 +85,9 @@
 say `ref(result)[s1]`, even though `result` doesn't have an `operator[]` that
 would accept `s1`.]
 
+[h3 Lazy Action Execution]
 
-
+TODO
 
 [endsect]
 

Added: trunk/libs/xpressive/doc/symbols.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/xpressive/doc/symbols.qbk	2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
@@ -0,0 +1,109 @@
+[/
+ / Copyright (c) 2007 David Jenkins
+ /
+ / 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 Symbol Tables and Attributes]
+
+[h2 Overview]
+
+Symbol tables can be built into Xpressive regular expressions with just a 
+`std::map<>`. The map keys are the strings to be matched and the map values are
+the data to be returned to your semantic action. Xpressive attributes, named
+`a1`, `a2`, through `a9`, hold the value corresponding to a matching key so
+that it can be used in a semantic action. A default value can be specified
+for an attribute if a symbol is not found.
+
+[h2 Symbol Tables]
+
+An Xpressive symbol table is just a `std::map<>`, where the key is a string type
+and the value can be anything. For example, the following regular expression
+matches a key from map1 and assigns the corresponding value to the attribute
+`a1`. Then, in the semantic action, it assigns the value stored in attribute
+`a1` to an integer result.
+
+    int result;
+    std::map<std::string, int> map1;
+    // ... (fill the map)
+    sregex rx = ( a1 = map1 ) [ ref(result) = a1 ];
+
+Consider the following example code,
+which translates number names into integers. It is
+described below.
+
+    #include <string>
+    #include <iostream>
+    #include <boost/xpressive/xpressive.hpp>
+    #include <boost/xpressive/regex_actions.hpp>
+    using namespace boost::xpressive;
+
+    int main()
+    {
+        std::map<std::string, int> number_map;
+        number_map["one"] = 1;
+        number_map["two"] = 2;
+        number_map["three"] = 3;
+        // Match a string from number_map
+        // and store the integer value in 'result'
+        // if not found, store -1 in 'result'
+        int result = 0;
+        cregex rx = ((a1 = number_map ) | *_)
+            [ ref(result) = (a1 | -1)];
+
+        regex_match("three", rx);
+        std::cout << result << '\n';
+        regex_match("two", rx);
+        std::cout << result << '\n';
+        regex_match("stuff", rx);
+        std::cout << result << '\n';
+        return 0;
+    }
+
+This program prints the following:
+
+[pre
+3
+2
+-1
+]
+
+First the program builds a number map, with number names as string keys and the
+corresponding integers as values. Then it constructs a static regular
+expression using an attribute `a1` to represent the result of the symbol table
+lookup. In the semantic action, the attribute is assigned to an integer
+variable `result`. If the symbol was not found, a default value of `-1` is
+assigned to `result`. A wildcard, `*_`, makes sure the regex matches even if
+the symbol is not found.
+
+A more complete version of this example can be found in
+[^libs/xpressive/example/numbers.cpp][footnote Many thanks to David Jenkins,
+who contributed this example.]. It translates number names up to "nine hundred
+ninety nine million nine hundred ninety nine thousand nine hundred ninety nine"
+along with some special number names like "dozen".
+
+Symbol table matches are case sensitive by default, but they can be made 
+case-insensitive by enclosing the expression in `icase()`.
+
+[h2 Attributes]
+
+[def __default_value__ '''<replaceable>default-value</replaceable>''']
+
+Up to nine attributes can be used in a regular expression. They are named
+`a1`, `a2`, ..., `a9` in the `boost::xpressive` namespace. The attribute type
+is the same as the second component of the map that is assigned to it. A
+default value for an attribute can be specified in a semantic action with the
+syntax `(a1 | __default_value__)`.
+
+Attributes are properly scoped, so you can do crazy things like:
+`( (a1=sym1) >> (a1=sym2)[ref(x)=a1] )[ref(y)=a1]`. The inner semantic action
+sees the inner `a1`, and the outer semantic action sees the outer one. They can
+even have different types.
+
+[note Xpressive builds a hidden ternary search trie from the map so it can
+search quickly. The hidden ternary search trie is "self adjusting", so after each
+search it restructures itself to improve the efficiency of future searches
+based on the frequency of previous searches.]
+
+[endsect]

Modified: trunk/libs/xpressive/doc/xpressive.qbk
==============================================================================
--- trunk/libs/xpressive/doc/xpressive.qbk	(original)
+++ trunk/libs/xpressive/doc/xpressive.qbk	2007-10-08 18:41:00 EDT (Mon, 08 Oct 2007)
@@ -95,6 +95,8 @@
 
 [include actions.qbk]
 
+[include symbols.qbk]
+
 [include traits.qbk]
 
 [include tips_n_tricks.qbk]