ceph/src/boost/libs/xpressive/doc/dynamic_regexes.qbk

   1 [/
   2  / Copyright (c) 2008 Eric Niebler
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section Dynamic Regexes]
   9
  10 [h2 Overview]
  11
  12 Static regexes are dandy, but sometimes you need something a bit more ... dynamic. Imagine you are developing
  13 a text editor with a regex search/replace feature. You need to accept a regular expression from the end user
  14 as input at run-time. There should be a way to parse a string into a regular expression. That's what xpressive's
  15 dynamic regexes are for. They are built from the same core components as their static counterparts, but they
  16 are late-bound so you can specify them at run-time.
  17
  18 [h2 Construction and Assignment]
  19
  20 There are two ways to create a dynamic regex: with the _regex_compile_
  21 function or with the _regex_compiler_ class template. Use _regex_compile_
  22 if you want the default locale. Use _regex_compiler_ if you need to
  23 specify a different locale. In the section on
  24 [link boost_xpressive.user_s_guide.grammars_and_nested_matches regex grammars],
  25 we'll see another use for _regex_compiler_.
  26
  27 Here is an example of using `basic_regex<>::compile()`:
  28
  29     sregex re = sregex::compile( "this|that", regex_constants::icase );
  30
  31 Here is the same example using _regex_compiler_:
  32
  33     sregex_compiler compiler;
  34     sregex re = compiler.compile( "this|that", regex_constants::icase );
  35
  36 _regex_compile_ is implemented in terms of _regex_compiler_.
  37
  38 [h2 Dynamic xpressive Syntax]
  39
  40 Since the dynamic syntax is not constrained by the rules for valid C++ expressions, we are free to use familiar
  41 syntax for dynamic regexes. For this reason, the syntax used by xpressive for dynamic regexes follows the
  42 lead set by John Maddock's [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm proposal]
  43 to add regular expressions to the Standard Library. It is essentially the syntax standardized by
  44 [@http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf ECMAScript], with minor changes
  45 in support of internationalization.
  46
  47 Since the syntax is documented exhaustively elsewhere, I will simply refer you to the existing standards, rather
  48 than duplicate the specification here.
  49
  50 [h2 Internationalization]
  51
  52 As with static regexes, dynamic regexes support internationalization by allowing you to specify a different
  53 `std::locale`. To do this, you must use _regex_compiler_. The _regex_compiler_ class has an `imbue()` function.
  54 After you have imbued a _regex_compiler_ object with a custom `std::locale`, all regex objects compiled by
  55 that _regex_compiler_ will use that locale. For example:
  56
  57     std::locale my_locale = /* initialize your locale object here */;
  58     sregex_compiler compiler;
  59     compiler.imbue( my_locale );
  60     sregex re = compiler.compile( "\\w+|\\d+" );
  61
  62 This regex will use `my_locale` when evaluating the intrinsic character sets `"\\w"` and `"\\d"`.
  63
  64 [endsect]