Update of /cvsroot/boost/boost/libs/xpressive/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv11916
Modified Files:
acknowledgements.qbk nyi.qbk perf.qbk regexpp_diffs.qbk
xpressive.qbk
Added Files:
actions.qbk history.qbk
Log Message:
add history appendix, begin user doc for semantic actions
--- NEW FILE: actions.qbk ---
[/
/ Copyright (c) 2006 Eric Niebler
/
/ 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 Semantic Actions and User-Defined Assertions]
[h2 Overview]
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
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
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> result;
std::string str("aaa=>1 bbb=>23 ccc=>456");
// Match a word and an integer, separated by =>,
// and then stuff the result into a std::map<>
sregex pair = ( (s1= +_w) >> "=>" >> (s2= +_d) )
[ ref(result)[s1] = as<int>(s2) ];
// Match one or more word/iteger pairs, separated
// by whitespace.
sregex rx = pair >> *(+_s >> pair);
if(regex_match(str, rx))
{
std::cout << result["aaa"] << '\n';
std::cout << result["bbb"] << '\n';
std::cout << result["ccc"] << '\n';
}
return 0;
}
This program prints the following:
[pre
1
23
456
]
The regular expression `pair` has two parts: the pattern and the action. The
pattern says to match a word, capturing it in sub-match 1, and an integer,
capturing it in sub-match 2, separated by `"=>"`. The action is the part in
square brackets: `[ ref(result)[s1] = as<int>(s2) ]`. It says to take sub-match
one and use it to index into the `results` map, and assign to it the result of
converting sub-match 2 to an integer.
How does this work? Just as the rest of the static regular expression, the part
between brackets is an expression template. It encodes the action and executes
it later. The expression `ref(result)` creates a lazy reference to the `result`
object. The larger expression `ref(result)[s1]` is a lazy map index operation.
Later, when this action is getting executed, `s1` gets replaced with the
first _sub_match_. Likewise, when `as<int>(s2)` gets executed, `s2` is replaced
with the second _sub_match_. The `as<>` action converts its argument to the
requested type using Boost.Lexical_cast. The effect of the whole action is to
insert a new word/integer pair into the map.
[note There is an important difference between the function `boost::ref()` in
`<boost/ref.hpp>` and `boost::xpressive::ref()` in
`<boost/xpressive/regex_actions.hpp>`. The first returns a plain
`reference_wrapper<>` which behaves in many respects like an ordinary
reference. By contrast, `boost::xpressive::ref()` returns a /lazy/ reference
that you can use in expressions that are executed lazily. That is why we can
say `ref(result)[s1]`, even though `result` doesn't have an `operator[]` that
would accept `s1`.]
[endsect]
--- NEW FILE: history.qbk ---
[/
/ Copyright (c) 2006 Eric Niebler
/
/ 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 Appendix 1: History]
[h2 Version 2.0.0, ????]
New Features:
* Semantic actions
* Custom assertions
* Better errors for invalid static regexes
* Dynamic regex grammars
* Recursive dynamic regexes with [^(?R)] construct
* Range-based regex algorithm interface
* `format_perl`, `format_sed`, and `format_all`
* `operator+(std::string, sub_match<>)` and variants
* Version 2 regex traits get `tolower()` and `toupper()`
Bugs Fixed:
* Complementing single-character sets like `~(set='a')` works.
[h2 Version 1.0.2, April 27, 2007]
Bugs Fixed:
* Back-references greater than nine work as advertized.
This is the version that shipped as part of Boost 1.34.
[h2 Version 1.0.1, October 2, 2006]
Bugs Fixed:
* `match_results::position()` works for nested results.
[h2 Version 1.0.0, March 16, 2006]
Version 1.0!
[h2 Version 0.9.6, August 19, 2005]
The version reviewed for acceptance into Boost. The review began September 8,
2005. Xpressive was accepted into Boost on September 28, 2005.
[h2 Version 0.9.3, June 30, 2005]
New Features:
* TR1-style regex_traits interface
* Speed enhancements
* `syntax_option_type::ignore_white_space`
[h2 Version 0.9.0, September 2, 2004]
New Features:
* It sort of works.
[h2 Version 0.0.1, November 16, 2003]
Announcement of xpressive:
[EMAIL PROTECTED]://lists.boost.org/Archives/boost/2003/11/56312.php]
[endsect]
Index: acknowledgements.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/xpressive/doc/acknowledgements.qbk,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- acknowledgements.qbk 5 Mar 2007 21:54:01 -0000 1.3
+++ acknowledgements.qbk 2 May 2007 07:35:01 -0000 1.4
@@ -7,14 +7,21 @@
[section Acknowledgments]
-I am indebted to [EMAIL PROTECTED]://boost.org/people/joel_de_guzman.htm Joel
de Guzman] and
[EMAIL PROTECTED]://boost.org/people/hartmut_kaiser.htm Hartmut Kaiser] for
their expert advice
-during the early states of xpressive's development. I am thankful for
[EMAIL PROTECTED]://boost.org/people/john_maddock.htm John Maddock]'s excellent
work on his proposal
-to add regular expressions to the standard library. I'd also like to thank
[EMAIL PROTECTED]://moderncppdesign.com/ Andrei Alexandrescu] for his input
regarding the behavior
-of nested regex objects, and [EMAIL
PROTECTED]://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.
+I am indebted to [EMAIL PROTECTED]://boost.org/people/joel_de_guzman.htm Joel
de Guzman]
+and [EMAIL PROTECTED]://boost.org/people/hartmut_kaiser.htm Hartmut Kaiser]
for their
+expert advice during the early states of xpressive's development. Much of
+static xpressive's syntax is owes a large debt to _spirit_, including the
+syntax for xpressive's semantic actions. I am thankful for
[EMAIL PROTECTED]://boost.org/people/john_maddock.htm John Maddock]'s excellent
work on
+his proposal to add regular expressions to the standard library. I'd also like
+to thank [EMAIL PROTECTED]://moderncppdesign.com/ Andrei Alexandrescu] for his
input
+regarding the behavior of nested regex objects, and
[EMAIL PROTECTED]://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.
+
+I would also like to thank
[EMAIL PROTECTED]://boost.org/people/thomas_witt.html Thomas Witt] for acting as
+xpressive's review manager.
[endsect]
Index: nyi.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/xpressive/doc/nyi.qbk,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- nyi.qbk 5 Mar 2007 21:54:01 -0000 1.3
+++ nyi.qbk 2 May 2007 07:35:01 -0000 1.4
@@ -5,22 +5,14 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Appendix 1: Not Yet Implemented]
-
-The following features of xpressive have not yet been implemented, but are
planned
-for the near future:\n
-\n
-
-* match_flag_type::format_sed
-* match_flag_type::format_perl
-\n
+[section Appendix 2: Not Yet Implemented]
-The following features are planned for xpressive 2.0:\n
+The following features are planned for xpressive 2.X:\n
\n
-* syntax_option_type::collate
-* POSIX collation sequences such as [^'''[.a.]'''] and [^'''[=a=]''']
-* Semantic actions
+* `syntax_option_type::collate`
+* Collation sequences such as [^'''[.a.]''']
+* Equivalence classes like [^'''[=a=]''']
* Fine-grained control over the dynamic regex syntax
* Improved localization support, possibly as a custom facet for `std::locale`
Index: perf.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/xpressive/doc/perf.qbk,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- perf.qbk 5 Mar 2007 21:54:01 -0000 1.2
+++ perf.qbk 2 May 2007 07:35:01 -0000 1.3
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:perf Appendix 3: Performance Comparison]
+[section:perf Appendix 4: Performance Comparison]
The performance of xpressive is competitive with _regexpp_. I have run
performance
benchmarks comparing static xpressive, dynamic xpressive and _regexpp_ on two
platforms:
Index: regexpp_diffs.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/xpressive/doc/regexpp_diffs.qbk,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- regexpp_diffs.qbk 5 Mar 2007 21:54:01 -0000 1.2
+++ regexpp_diffs.qbk 2 May 2007 07:35:01 -0000 1.3
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Appendix 2: Differences from Boost.Regex]
+[section Appendix 3: Differences from Boost.Regex]
Since many of xpressive's users are likely to be familiar with the _regexpp_
library,
I would be remiss if I failed to point out some important differences between
xpressive
@@ -36,7 +36,6 @@
* The following `match_flag_type` enumeration values are not supported:
`match_not_bob`,
`match_not_eob`, `match_perl`, `match_posix`, and `match_extra`.
-
Also, in the current implementation, the regex algorithms in xpressive will
not detect
pathological behavior and abort by throwing an exception. It is up to you to
write efficient
patterns that do not behave pathologically.
Index: xpressive.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/xpressive/doc/xpressive.qbk,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- xpressive.qbk 17 Apr 2007 17:06:51 -0000 1.6
+++ xpressive.qbk 2 May 2007 07:35:01 -0000 1.7
@@ -93,6 +93,8 @@
[include grammars.qbk]
+[include actions.qbk]
+
[include traits.qbk]
[include tips_n_tricks.qbk]
@@ -109,6 +111,8 @@
[section Appendices]
+[include history.qbk]
+
[include nyi.qbk]
[include regexpp_diffs.qbk]
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
