[Boost-commit] svn:boost r43675 - in branches/release: . libs/xpressive/doc

From: eric_at_[hidden]
Date: 2008-03-17 12:25:52

Author: eric_niebler
Date: 2008-03-17 12:25:52 EDT (Mon, 17 Mar 2008)
New Revision: 43675
URL: http://svn.boost.org/trac/boost/changeset/43675

Log:
Merged revisions 43663 via svnmerge from 
https://svn.boost.org/svn/boost/trunk

........
  r43663 | eric_niebler | 2008-03-16 17:35:04 -0700 (Sun, 16 Mar 2008) | 1 line
  
  document new format flags, and range-based interface for regex_match and regex_search
........

Properties modified: 
   branches/release/   (props changed)
Text files modified: 
   branches/release/libs/xpressive/doc/matching.qbk      |    33 ++++++-----                             
   branches/release/libs/xpressive/doc/substitutions.qbk |   110 +++++++++++++++++++++++++++++++++------ 
   2 files changed, 109 insertions(+), 34 deletions(-)

Modified: branches/release/libs/xpressive/doc/matching.qbk
==============================================================================
--- branches/release/libs/xpressive/doc/matching.qbk	(original)
+++ branches/release/libs/xpressive/doc/matching.qbk	2008-03-17 12:25:52 EDT (Mon, 17 Mar 2008)
@@ -22,10 +22,11 @@
 want to search through the string looking for sub-strings that the regex matches, use the _regex_search_
 algorithm.]
 
-The input can be a `std::string`, a C-style null-terminated string or a pair of iterators. In all cases,
-the type of the iterator used to traverse the input sequence must match the iterator type used to declare
-the regex object. (You can use the table in the [link boost_xpressive.user_s_guide.quick_start.know_your_iterator_type Quick Start] to
-find the correct regex type for your iterator.)
+The input can be a bidirectional range such as `std::string`, a C-style null-terminated string or a pair of
+iterators. In all cases, the type of the iterator used to traverse the input sequence must match the iterator 
+type used to declare the regex object. (You can use the table in the 
+[link boost_xpressive.user_s_guide.quick_start.know_your_iterator_type Quick Start] to find the correct regex
+type for your iterator.)
 
     cregex cre = +_w;  // this regex can match C-style strings
     sregex sre = +_w;  // this regex can match std::strings
@@ -65,9 +66,9 @@
         // should never get here!!!
     }
 
-Click [link boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex here] to see a complete example program that
-shows how to use _regex_match_. And check the _regex_match_ reference to see a complete list of the available
-overloads.
+Click [link boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex here] to see a complete
+example program that shows how to use _regex_match_. And check the _regex_match_ reference to see a complete list
+of the available overloads.
 
 [h2 Searching for Matching Sub-Strings]
 
@@ -75,14 +76,14 @@
 _regex_search_ will try to match the regex at the beginning of the input sequence and scan forward in the
 sequence until it either finds a match or exhausts the sequence.
 
-In all other regards, _regex_search_ behaves like _regex_match_ ['(see above)]. In particular, it can operate on `std::string`,
-C-style null-terminated strings or iterator ranges. The same care must be taken to ensure that the iterator
-type of your regex matches the iterator type of your input sequence. As with _regex_match_, you can optionally
-provide a _match_results_ struct to receive the results of the search, and a _match_flag_type_ bitmask to
-control how the match is evaluated.
-
-Click [link boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex here] to see a complete
-example program that shows how to use _regex_search_. And check the _regex_search_ reference to see a complete
-list of the available overloads.
+In all other regards, _regex_search_ behaves like _regex_match_ ['(see above)]. In particular, it can operate
+on a bidirectional range such as `std::string`, C-style null-terminated strings or iterator ranges. The same
+care must be taken to ensure that the iterator type of your regex matches the iterator type of your input 
+sequence. As with _regex_match_, you can optionally provide a _match_results_ struct to receive the results 
+of the search, and a _match_flag_type_ bitmask to control how the match is evaluated.
+
+Click [link boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex here]
+to see a complete example program that shows how to use _regex_search_. And check the _regex_search_ reference to
+see a complete list of the available overloads.
 
 [endsect]

Modified: branches/release/libs/xpressive/doc/substitutions.qbk
==============================================================================
--- branches/release/libs/xpressive/doc/substitutions.qbk	(original)
+++ branches/release/libs/xpressive/doc/substitutions.qbk	2008-03-17 12:25:52 EDT (Mon, 17 Mar 2008)
@@ -7,8 +7,8 @@
 
 [section String Substitutions]
 
-Regular expressions are not only good for searching text; they're good at ['manipulating] it. And one of the most
-common text manipulation tasks is search-and-replace. xpressive provides the _regex_replace_ algorithm for
+Regular expressions are not only good for searching text; they're good at ['manipulating] it. And one of the
+most common text manipulation tasks is search-and-replace. xpressive provides the _regex_replace_ algorithm for
 searching and replacing.
 
 [h2 regex_replace()]
@@ -40,19 +40,40 @@
 
 Notice that ['all] the occurrences of `"his"` have been replaced with `"her"`.
 
-Click [link boost_xpressive.user_s_guide.examples.replace_all_sub_strings_that_match_a_regex here] to see a complete
-example program that shows how to use _regex_replace_. And check the _regex_replace_ reference
+Click [link boost_xpressive.user_s_guide.examples.replace_all_sub_strings_that_match_a_regex here] to see
+a complete example program that shows how to use _regex_replace_. And check the _regex_replace_ reference
 to see a complete list of the available overloads.
 
-[h2 The Format String]
+[h2 Replace Options]
 
-As with Perl, you can refer to sub-matches in the format string. The table below shows the escape sequences
-xpressive recognizes in the format string.
+The _regex_replace_ algorithm takes an optional bitmask parameter to control the formatting. The
+possible values of the bitmask are:
+
+[table Format Flags
+    [[Flag]                     [Meaning]]
+    [[`format_default`]         [Recognize the ECMA-262 format sequences (see below).]]
+    [[`format_first_only`]      [Only replace the first match, not all of them.]]
+    [[`format_no_copy`]         [Don't copy the parts of the input sequence that didn't match the regex
+                                 to the output sequence.]]
+    [[`format_literal`]         [Treat the format string as a literal; that is, don't recognize any
+                                 escape sequences.]]
+    [[`format_perl`]            [Recognize the Perl format sequences (see below).]]
+    [[`format_sed`]             [Recognize the sed format sequences (see below).]]
+    [[`format_all`]             [In addition to the Perl format sequences, recognize some
+                                 Boost-specific format sequences.]]
+]
+
+These flags live in the `regex_constants` namespace.
+
+[h2 The ECMA-262 Format Sequences]
+
+When you haven't specified a substitution string dialect with one of the format flags above, 
+you get the dialect defined by ECMA-262, the standard for ECMAScript. The table below shows
+the escape sequences recognized in ECMA-262 mode.
 
 [table Format Escape Sequences
     [[Escape Sequence]      [Meaning]]
-    [[[^$1]]                [the first sub-match]]
-    [[[^$2]]                [the second sub-match (etc.)]]
+    [[[^$1], [^$2], etc.]   [the corresponding sub-match]]
     [[[^$&]]                [the full match]]
     [[[^$\`]]               [the match prefix]]
     [[[^$']]                [the match suffix]]
@@ -62,18 +83,71 @@
 Any other sequence beginning with `'$'` simply represents itself. For example, if the format string were
 `"$a"` then `"$a"` would be inserted into the output sequence.
 
-[h2 Replace Options]
+[h2 The Sed Format Sequences]
 
-The _regex_replace_ algorithm takes an optional bitmask parameter to control the formatting. The
-possible values of the bitmask are:
+When specifying the `format_sed` flag to _regex_replace_, the following escape sequences
+are recognized:
 
-[table Format Flags
-    [[Flag]                     [Meaning]]
-    [[`format_first_only`]      [Only replace the first match, not all of them.]]
-    [[`format_no_copy`]         [Don't copy the parts of the input sequence that didn't match the regex to the output sequence.]]
-    [[`format_literal`]         [Treat the format string as a literal; that is, don't recognize any escape sequences.]]
+[table Sed Format Escape Sequences
+    [[Escape Sequence]      [Meaning]]
+    [[[^\\1], [^\\2], etc.] [The corresponding sub-match]]
+    [[[^&]]                 [the full match]]
+    [[[^\\a]]               [A literal `'\a'`]]
+    [[[^\\e]]               [A literal `char_type(27)`]]
+    [[[^\\f]]               [A literal `'\f'`]]
+    [[[^\\n]]               [A literal `'\n'`]]
+    [[[^\\r]]               [A literal `'\r'`]]
+    [[[^\\t]]               [A literal `'\t'`]]
+    [[[^\\v]]               [A literal `'\v'`]]
+    [[[^\\xFF]]             [A literal `char_type(0xFF)`, where [^['F]] is any hex digit]]
+    [[[^\\x{FFFF}]]         [A literal `char_type(0xFFFF)`, where [^['F]] is any hex digit]]
+    [[[^\\cX]]              [The control character [^['X]]]]
 ]
 
-These flags live in the `regex_constants` namespace.
+[h2 The Perl Format Sequences]
+
+When specifying the `format_perl` flag to _regex_replace_, the following escape sequences
+are recognized:
+
+[table Perl Format Escape Sequences
+    [[Escape Sequence]      [Meaning]]
+    [[[^$1], [^$2], etc.]   [the corresponding sub-match]]
+    [[[^$&]]                [the full match]]
+    [[[^$\`]]               [the match prefix]]
+    [[[^$']]                [the match suffix]]
+    [[[^$$]]                [a literal `'$'` character]]
+    [[[^\\a]]               [A literal `'\a'`]]
+    [[[^\\e]]               [A literal `char_type(27)`]]
+    [[[^\\f]]               [A literal `'\f'`]]
+    [[[^\\n]]               [A literal `'\n'`]]
+    [[[^\\r]]               [A literal `'\r'`]]
+    [[[^\\t]]               [A literal `'\t'`]]
+    [[[^\\v]]               [A literal `'\v'`]]
+    [[[^\\xFF]]             [A literal `char_type(0xFF)`, where [^['F]] is any hex digit]]
+    [[[^\\x{FFFF}]]         [A literal `char_type(0xFFFF)`, where [^['F]] is any hex digit]]
+    [[[^\\cX]]              [The control character [^['X]]]]
+    [[[^\\l]]               [Make the next character lowercase]]
+    [[[^\\L]]               [Make the rest of the substitution lowercase until the next [^\\E]]]
+    [[[^\\u]]               [Make the next character uppercase]]
+    [[[^\\U]]               [Make the rest of the substitution uppercase until the next [^\\E]]]
+    [[[^\\E]]               [Terminate [^\\L] or [^\\U]]]
+    [[[^\\1], [^\\2], etc.] [The corresponding sub-match]]
+    [[[^\\g<name>]]         [The named backref /name/]]
+]
+
+[h2 The Boost-Specific Format Sequences]
+
+When specifying the `format_all` flag to _regex_replace_, the escape sequences
+recognized are the same as those above for `format_perl`. In addition, conditional
+expressions of the following form are recognized:
+
+[pre
+?Ntrue-expression:false-expression
+]
+
+where /N/ is a decimal digit representing a sub-match. If the corresponding sub-match
+participated in the full match, then the substitution is /true-expression/. Otherwise,
+it is /false-expression/. In this mode, you can use parens [^()] for grouping. If you
+want a literal paren, you must escape it as [^\\(].
 
 [endsect]