EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/xpressive/doc/static_regexes.qbk

[/
 / Copyright (c) 2008 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 Static Regexes]

[h2 Overview]

The feature that really sets xpressive apart from other C/C++ regular
expression libraries is the ability to author a regular expression using C++
expressions. xpressive achieves this through operator overloading, using a
technique called ['expression templates] to embed a mini-language dedicated
to pattern matching within C++. These "static regexes" have many advantages
over their string-based brethren. In particular, static regexes:

* are syntax-checked at compile-time; they will never fail at run-time due to
  a syntax error.
* can naturally refer to other C++ data and code, including other regexes,
  making it simple to build grammars out of regular expressions and bind
  user-defined actions that execute when parts of your regex match.
* are statically bound for better inlining and optimization. Static regexes
  require no state tables, virtual functions, byte-code or calls through
  function pointers that cannot be resolved at compile time.
* are not limited to searching for patterns in strings. You can declare a
  static regex that finds patterns in an array of integers, for instance.

Since we compose static regexes using C++ expressions, we are constrained by
the rules for legal C++ expressions. Unfortunately, that means that
"classic" regular expression syntax cannot always be mapped cleanly into
C++. Rather, we map the regex ['constructs], picking new syntax that is
legal C++.

[h2 Construction and Assignment]

You create a static regex by assigning one to an object of type _basic_regex_.
For instance, the following defines a regex that can be used to find patterns
in objects of type `std::string`:

    sregex re = '$' >> +_d >> '.' >> _d >> _d;

Assignment works similarly.

[h2 Character and String Literals]

In static regexes, character and string literals match themselves. For
instance, in the regex above, `'$'` and `'.'` match the characters `'$'` and
`'.'` respectively. Don't be confused by the fact that [^$] and [^.] are
meta-characters in Perl. In xpressive, literals always represent themselves.

When using literals in static regexes, you must take care that at least one
operand is not a literal. For instance, the following are ['not] valid
regexes:

    sregex re1 = 'a' >> 'b';         // ERROR!
    sregex re2 = +'a';               // ERROR!

The two operands to the binary `>>` operator are both literals, and the
operand of the unary `+` operator is also a literal, so these statements
will call the native C++ binary right-shift and unary plus operators,
respectively. That's not what we want. To get operator overloading to kick
in, at least one operand must be a user-defined type. We can use xpressive's
`as_xpr()` helper function to "taint" an expression with regex-ness, forcing
operator overloading to find the correct operators. The two regexes above
should be written as:

    sregex re1 = as_xpr('a') >> 'b'; // OK
    sregex re2 = +as_xpr('a');       // OK

[h2 Sequencing and Alternation]

As you've probably already noticed, sub-expressions in static regexes must
be separated by the sequencing operator, `>>`. You can read this operator as
"followed by".

    // Match an 'a' followed by a digit
    sregex re = 'a' >> _d;

Alternation works just as it does in Perl with the `|` operator. You can
read this operator as "or". For example:

    // match a digit character or a word character one or more times
    sregex re = +( _d | _w );

[h2 Grouping and Captures]

In Perl, parentheses `()` have special meaning. They group, but as a
side-effect they also create back\-references like [^$1] and [^$2]. In C++,
parentheses only group \-\- there is no way to give them side\-effects. To
get the same effect, we use the special `s1`, `s2`, etc. tokens. Assigning
to one creates a back-reference. You can then use the back-reference later
in your expression, like using [^\1] and [^\2] in Perl. For example,
consider the following regex, which finds matching HTML tags:

    "<(\\w+)>.*?</\\1>"

In static xpressive, this would be:

    '<' >> (s1= +_w) >> '>' >> -*_ >> "</" >> s1 >> '>'

Notice how you capture a back-reference by assigning to `s1`, and then you
use `s1` later in the pattern to find the matching end tag.

[tip [*Grouping without capturing a back-reference] \n\n In
xpressive, if you just want grouping without capturing a back-reference, you
can just use `()` without `s1`. That is the equivalent of Perl's [^(?:)]
non-capturing grouping construct.]

[h2 Case-Insensitivity and Internationalization]

Perl lets you make part of your regular expression case-insensitive by using
the [^(?i:)] pattern modifier. xpressive also has a case-insensitivity
pattern modifier, called `icase`. You can use it as follows:

    sregex re = "this" >> icase( "that" );

In this regular expression, `"this"` will be matched exactly, but `"that"`
will be matched irrespective of case.

Case-insensitive regular expressions raise the issue of
internationalization: how should case-insensitive character comparisons be
evaluated? Also, many character classes are locale-specific. Which
characters are matched by `digit` and which are matched by `alpha`? The
answer depends on the `std::locale` object the regular expression object is
using. By default, all regular expression objects use the global locale. You
can override the default by using the `imbue()` pattern modifier, as
follows:

    std::locale my_locale = /* initialize a std::locale object */;
    sregex re = imbue( my_locale )( +alpha >> +digit );

This regular expression will evaluate `alpha` and `digit` according to
`my_locale`. See the section on [link boost_xpressive.user_s_guide.localization_and_regex_traits
Localization and Regex Traits] for more information about how to customize
the behavior of your regexes.

[h2 Static xpressive Syntax Cheat Sheet]

The table below lists the familiar regex constructs and their equivalents in
static xpressive.

[def _s1_       [globalref boost::xpressive::s1 s1]]
[def _bos_      [globalref boost::xpressive::bos bos]]
[def _eos_      [globalref boost::xpressive::eos eos]]
[def _b_        [globalref boost::xpressive::_b _b]]
[def _n_        [globalref boost::xpressive::_n _n]]
[def _ln_       [globalref boost::xpressive::_ln _ln]]
[def _d_        [globalref boost::xpressive::_d _d]]
[def _w_        [globalref boost::xpressive::_w _w]]
[def _s_        [globalref boost::xpressive::_s _s]]
[def _alnum_    [globalref boost::xpressive::alnum alnum]]
[def _alpha_    [globalref boost::xpressive::alpha alpha]]
[def _blank_    [globalref boost::xpressive::blank blank]]
[def _cntrl_    [globalref boost::xpressive::cntrl cntrl]]
[def _digit_    [globalref boost::xpressive::digit digit]]
[def _graph_    [globalref boost::xpressive::graph graph]]
[def _lower_    [globalref boost::xpressive::lower lower]]
[def _print_    [globalref boost::xpressive::print print]]
[def _punct_    [globalref boost::xpressive::punct punct]]
[def _space_    [globalref boost::xpressive::space space]]
[def _upper_    [globalref boost::xpressive::upper upper]]
[def _xdigit_   [globalref boost::xpressive::xdigit xdigit]]
[def _set_      [globalref boost::xpressive::set set]]
[def _repeat_   [funcref boost::xpressive::repeat repeat]]
[def _range_    [funcref boost::xpressive::range range]]
[def _icase_    [funcref boost::xpressive::icase icase]]
[def _before_   [funcref boost::xpressive::before before]]
[def _after_    [funcref boost::xpressive::after after]]
[def _keep_     [funcref boost::xpressive::keep keep]]

[table Perl syntax vs. Static xpressive syntax
    [[Perl]               [Static xpressive]                              [Meaning]]
    [[[^.]]               [[globalref boost::xpressive::_ `_`]]           [any character (assuming Perl's /s modifier).]]
    [[[^ab]]              [`a >> b`]                                      [sequencing of [^a] and [^b] sub-expressions.]]
    [[[^a|b]]             [`a | b`]                                       [alternation of [^a] and [^b] sub-expressions.]]
    [[[^(a)]]             [`(_s1_= a)`]                                   [group and capture a back-reference.]]
    [[[^(?:a)]]           [`(a)`]                                         [group and do not capture a back-reference.]]
    [[[^\1]]              [`_s1_`]                                        [a previously captured back-reference.]]
    [[[^a*]]              [`*a`]                                          [zero or more times, greedy.]]
    [[[^a+]]              [`+a`]                                          [one or more times, greedy.]]
    [[[^a?]]              [`!a`]                                          [zero or one time, greedy.]]
    [[[^a{n,m}]]          [`_repeat_<n,m>(a)`]                            [between [^n] and [^m] times, greedy.]]
    [[[^a*?]]             [`-*a`]                                         [zero or more times, non-greedy.]]
    [[[^a+?]]             [`-+a`]                                         [one or more times, non-greedy.]]
    [[[^a??]]             [`-!a`]                                         [zero or one time, non-greedy.]]
    [[[^a{n,m}?]]         [`-_repeat_<n,m>(a)`]                           [between [^n] and [^m] times, non-greedy.]]
    [[[^^]]               [`_bos_`]                                       [beginning of sequence assertion.]]
    [[[^$]]               [`_eos_`]                                       [end of sequence assertion.]]
    [[[^\b]]              [`_b_`]                                         [word boundary assertion.]]
    [[[^\B]]              [`~_b_`]                                        [not word boundary assertion.]]
    [[[^\\n]]             [`_n_`]                                         [literal newline.]]
    [[[^.]]               [`~_n_`]                                        [any character except a literal newline (without Perl's /s modifier).]]
    [[[^\\r?\\n|\\r]]     [`_ln_`]                                        [logical newline.]]
    [[[^\[^\\r\\n\]]]     [`~_ln_`]                                       [any single character not a logical newline.]]
    [[[^\w]]              [`_w_`]                                         [a word character, equivalent to set\[alnum | '_'\].]]
    [[[^\W]]              [`~_w_`]                                        [not a word character, equivalent to ~set\[alnum | '_'\].]]
    [[[^\d]]              [`_d_`]                                         [a digit character.]]
    [[[^\D]]              [`~_d_`]                                        [not a digit character.]]
    [[[^\s]]              [`_s_`]                                         [a space character.]]
    [[[^\S]]              [`~_s_`]                                        [not a space character.]]
    [[[^\[:alnum:\]]]     [`_alnum_`]                                     [an alpha-numeric character.]]
    [[[^\[:alpha:\]]]     [`_alpha_`]                                     [an alphabetic character.]]
    [[[^\[:blank:\]]]     [`_blank_`]                                     [a horizontal white-space character.]]
    [[[^\[:cntrl:\]]]     [`_cntrl_`]                                     [a control character.]]
    [[[^\[:digit:\]]]     [`_digit_`]                                     [a digit character.]]
    [[[^\[:graph:\]]]     [`_graph_`]                                     [a graphable character.]]
    [[[^\[:lower:\]]]     [`_lower_`]                                     [a lower-case character.]]
    [[[^\[:print:\]]]     [`_print_`]                                     [a printing character.]]
    [[[^\[:punct:\]]]     [`_punct_`]                                     [a punctuation character.]]
    [[[^\[:space:\]]]     [`_space_`]                                     [a white-space character.]]
    [[[^\[:upper:\]]]     [`_upper_`]                                     [an upper-case character.]]
    [[[^\[:xdigit:\]]]    [`_xdigit_`]                                    [a hexadecimal digit character.]]
    [[[^\[0-9\]]]         [`_range_('0','9')`]                            [characters in range `'0'` through `'9'`.]]
    [[[^\[abc\]]]         [`as_xpr('a') | 'b' |'c'`]                      [characters `'a'`, `'b'`, or `'c'`.]]
    [[[^\[abc\]]]         [`(_set_= 'a','b','c')`]                        [['same as above]]]
    [[[^\[0-9abc\]]]      [`_set_[ _range_('0','9') | 'a' | 'b' | 'c' ]`] [characters `'a'`, `'b'`, `'c'` or  in range `'0'` through `'9'`.]]
    [[[^\[0-9abc\]]]      [`_set_[ _range_('0','9') | (_set_= 'a','b','c') ]`]  [['same as above]]]
    [[[^\[^abc\]]]        [`~(_set_= 'a','b','c')`]                       [not characters `'a'`, `'b'`, or `'c'`.]]
    [[[^(?i:['stuff])]]   [`_icase_(`[^['stuff]]`)`]                      [match ['stuff] disregarding case.]]
    [[[^(?>['stuff])]]    [`_keep_(`[^['stuff]]`)`]                       [independent sub-expression, match ['stuff] and turn off backtracking.]]
    [[[^(?=['stuff])]]    [`_before_(`[^['stuff]]`)`]                     [positive look-ahead assertion, match if before ['stuff] but don't include ['stuff] in the match.]]
    [[[^(?!['stuff])]]    [`~_before_(`[^['stuff]]`)`]                    [negative look-ahead assertion, match if not before ['stuff].]]
    [[[^(?<=['stuff])]]   [`_after_(`[^['stuff]]`)`]                      [positive look-behind assertion, match if after ['stuff] but don't include ['stuff] in the match. (['stuff] must be constant-width.)]]
    [[[^(?<!['stuff])]]   [`~_after_(`[^['stuff]]`)`]                     [negative look-behind assertion, match if not after ['stuff]. (['stuff] must be constant-width.)]]
    [[[^(?P<['name]>['stuff])]]     [`_mark_tag_ `[^['name]]`(`['n]`);`\n ...\n `(`[^['name]]`= `[^['stuff]]`)`]      [Create a named capture.]]
    [[[^(?P=['name])]]              [`_mark_tag_ `[^['name]]`(`['n]`);`\n ...\n [^['name]]]                           [Refer back to a previously created named capture.]]
]
\n

[endsect]