[boost-doc-zh] r422 committed - 翻译 xpressive 库的 qbk/xml 文件
- From: boost-doc-zh@xxxxxxxxxxxxxx
- To: boost-doc-zh-notify@xxxxxxxxxxxxx
- Date: Mon, 02 Aug 2010 03:49:10 +0000
Revision: 422
Author: alai04
Date: Sun Aug 1 20:47:57 2010
Log: 翻译 xpressive 库的 qbk/xml 文件
http://code.google.com/p/boost-doc-zh/source/detail?r=422
Modified:
/trunk/libs/xpressive/doc/acknowledgements.qbk
/trunk/libs/xpressive/doc/actions.qbk
/trunk/libs/xpressive/doc/concepts.qbk
/trunk/libs/xpressive/doc/dynamic_regexes.qbk
/trunk/libs/xpressive/doc/examples.qbk
/trunk/libs/xpressive/doc/grammars.qbk
/trunk/libs/xpressive/doc/history.qbk
/trunk/libs/xpressive/doc/installation.qbk
/trunk/libs/xpressive/doc/introduction.qbk
/trunk/libs/xpressive/doc/matching.qbk
/trunk/libs/xpressive/doc/named_captures.qbk
/trunk/libs/xpressive/doc/nyi.qbk
/trunk/libs/xpressive/doc/perf.qbk
/trunk/libs/xpressive/doc/preface.qbk
/trunk/libs/xpressive/doc/quick_start.qbk
/trunk/libs/xpressive/doc/regexpp_diffs.qbk
/trunk/libs/xpressive/doc/results.qbk
/trunk/libs/xpressive/doc/static_regexes.qbk
/trunk/libs/xpressive/doc/substitutions.qbk
/trunk/libs/xpressive/doc/symbols.qbk
/trunk/libs/xpressive/doc/tips_n_tricks.qbk
/trunk/libs/xpressive/doc/tokenization.qbk
/trunk/libs/xpressive/doc/tracking_ptr.qbk
/trunk/libs/xpressive/doc/traits.qbk
/trunk/libs/xpressive/doc/xpressive.qbk
=======================================
--- /trunk/libs/xpressive/doc/acknowledgements.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/acknowledgements.qbk Sun Aug 1 20:47:57 2010
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Acknowledgments]
+[section:acknowledgments Acknowledgments]
I am indebted to [@http://boost.org/people/joel_de_guzman.htm Joel de
Guzman]
and [@http://boost.org/people/hartmut_kaiser.htm Hartmut Kaiser] for their
=======================================
--- /trunk/libs/xpressive/doc/actions.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/actions.qbk Sun Aug 1 20:47:57 2010
@@ -5,21 +5,24 @@
/ 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]
+[section:semantic_actions_and_user_defined_assertions 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 match. Xpressive lets
you attach semantic actions to parts of your static regular expressions.
This
-section shows you how.
-
-[h2 Semantic Actions]
+section shows you how.\n
+想象你想分析一个输入串并从中构建一个 `std::map<>`。对于这种事情，仅仅匹配一
个正则表达式是不够的。
+你想要在你的正则表达式部分匹配时做些事情。Xpressive让你可以为你的静态正则表
达式的某个部分添加语义动作。本节将向你展示怎么做。
+
+[h2 Semantic Actions 语义动作]
Consider the following code, which uses xpressive's semantic actions to
parse
a string of word/integer pairs and stuffs them into a `std::map<>`. It is
-described below.
+described below.\n
+我们来看以下代码，它使用xpressive的语义动作来分析一个由单词/整数对组成的
串，并将它们存入一个 `std::map<>`。后文有说明。
#include <string>
#include <iostream>
@@ -51,7 +54,8 @@
return 0;
}
-This program prints the following:
+This program prints the following:\n
+程序输出如下：
[pre
1
@@ -64,10 +68,14 @@
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.
+converting sub-match 2 to an integer.\n
+正则表达式 `pair` 有两部分：模式和动作。其模式部分指出，匹配一个单词并把它
放入子匹配1，然后是一个整数并放入子匹配2，它们之间由
+`"=>"` 分隔。动作部分是由方括号括起来的部分：`[ ref(result)[s1] =
as<int>(s2) ]`。它表示，取出子匹配 1并用它作为 `results`
+map的索引，然后将由子匹配2转换为整数的结果赋给它。
[note To use semantic actions with your static regexes, you must
-`#include <boost/xpressive/regex_actions.hpp>`]
+`#include <boost/xpressive/regex_actions.hpp>`\n
+要对你的静态regex使用语义动作，你必须 `#include
<boost/xpressive/regex_actions.hpp>`]
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
@@ -77,7 +85,12 @@
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.
+insert a new word/integer pair into the map.\n
+这是如何工作的呢？正如这个静态正则表达式后一部分那样，在方括号中的是一个表
达式模板。
+它对动作编码并延后执行它。表达式 `ref(result)` 创建了一个 `result` 对象的延
迟引用。
+较大一些的表达式 `ref(result)[s1]` 则是一个延迟的map索引操作。当这个动作稍
后被执行时，`s1`
+会被第一个 _sub_match_ 所替代。同样，当 `as<int>(s2)` 被执行时，s2 会替换为
第二个 _sub_match_。
+动作 `as<>` 使用Boost.Lexical_cast将它的参数转换为所要求的类型。整个动作的
效果就是，插入一个新的单词/整数对到map中。
[note There is an important difference between the function `boost::ref()`
in
`<boost/ref.hpp>` and `boost::xpressive::ref()` in
@@ -86,26 +99,35 @@
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`.]
+would accept `s1`.\n
+`<boost/ref.hpp>` 中的函数 `boost::ref()` 与
`<boost/xpressive/regex_actions.hpp>` 中的
+`boost::xpressive::ref()` 有很大的差别。前者返回一个简单的
`reference_wrapper<>`，其行为在许多方面都与普通的引用相似。
+相比之下，`boost::xpressive::ref()` 返回一个/延迟/的引用，你可以把它用于延
后执行的表达式之中。
+这正是我们可以写 `ref(result)[s1]` 的原因，即使 `result` 并没有一个接受
`s1` 的 `operator[]`。]
In addition to the sub-match placeholders `s1`, `s2`, etc., you can also
use
the placeholder `_` within an action to refer back to the string matched by
the sub-expression to which the action is attached. For instance, you can
use
the following regex to match a bunch of digits, interpret them as an
integer
-and assign the result to a local variable:
+and assign the result to a local variable:\n
+除了子匹配占位符 `s1`, `s2` 等，你还可以在动作中使用占位符 `_` 来反向引用至
附加该动作的子表达式所匹配的字符串。
+例如，你可以用以下regex来匹配一串数字，把它们解释为整数并把结果赋值给一个局
部变量：
int i = 0;
// Here, _ refers back to all the
// characters matched by (+_d)
sregex rex = (+_d)[ ref(i) = as<int>(_) ];
-[h3 Lazy Action Execution]
+[h3 Lazy Action Execution 延迟的动作执行]
What does it mean, exactly, to attach an action to part of a regular
expression
and perform a match? When does the action execute? If the action is part
of a
repeated sub-expression, does the action execute once or many times? And
if the
sub-expression initially matches, but ultimately fails because the rest of
the
-regular expression fails to match, is the action executed at all?
+regular expression fails to match, is the action executed at all?\n
+把一个动作附加至一个正则表达式的某个部分并执行匹配，其正确的意义是什么？该
动作何时被执行？
+如果这个动作是一个重复的子表达式的一部分，它会被执行一次还是多次？
+还有，如果这个子表达式开始的时候是被匹配的，但是最终却因为正则表达式的其它
部分匹配失败而失败，这个动作还会被执行吗？
The answer is that by default, actions are executed /lazily/. When a
sub-expression
matches a string, its action is placed on a queue, along with the current
@@ -113,10 +135,14 @@
must backtrack, actions are popped off the queue as necessary. Only after
the
entire regex has matched successfully are the actions actually exeucted.
They
are executed all at once, in the order in which they were added to the
queue,
-as the last step before _regex_match_ returns.
+as the last step before _regex_match_ returns.\n
+答案是，缺省地，动作是被/延迟/执行的。当一个子表达式匹配一个字符串时，它的
动作和该动作所引用的所有子匹配的值一起，会被放入一个队列中。
+如果匹配算法必须回溯，该动作会视需要从队列中弹出。只有当整个regex被成功地匹
配，这些动作才会被执行。
+它们会按照它们加入到队列中的顺序，作为 _regex_match_ 返回之前的最后一个步
骤，被一次性地执行。
For example, consider the following regex that increments a counter
whenever
-it finds a digit.
+it finds a digit.\n
+例如，考虑以下regex，它在发现一个数字时递增一个计数器。
int i = 0;
std::string str("1!2!3?");
@@ -129,9 +155,11 @@
The action `++ref(i)` is queued three times: once for each found digit. But
it is only /executed/ twice: once for each digit that precedes a `'!'`
character. When the `'?'` character is encountered, the match algorithm
-backtracks, removing the final action from the queue.
-
-[h3 Immediate Action Execution]
+backtracks, removing the final action from the queue.\n
+动作 `++ref(i)` 将被三次加入队列：每发现一个数字一次。但它仅被/执行/两
次：每个带 `'!'` 字符的数字一次。
+当遇到 `'?'` 字符时，匹配算法会回溯，把最后一个动作移出队列。
+
+[h3 Immediate Action Execution 即时的动作执行]
When you want semantic actions to execute immediately, you can wrap the
sub-expression containing the action in a [^[funcref
boost::xpressive::keep keep()]].
@@ -140,7 +168,11 @@
It is as if the sub-expression in the `keep()` were compiled into an
independent regex object, and matching the `keep()` is like a separate
invocation
of `regex_search()`. It matches characters and executes actions but never
backtracks
-or unwinds. For example, imagine the above example had been written as
follows:
+or unwinds. For example, imagine the above example had been written as
follows:\n
+如果你想让一个语义动作立即执行，你可以把含有该动作的子表达式包入一个
[^[funcref boost::xpressive::keep keep()]] 中。
+`keep()` 关闭了对此子表达式的回溯，不过它也会引起由该子表达式放入队列的所有
动作在 `keep()` 之后执行。
+它就象在 `keep()` 中的子表达式被编译为一个独立的regex对象，匹配该 `keep()`
就象一次 `regex_search()` 的单独调用。
+它匹配字符并执行动作，但不会回溯或展开。例如，想象上述例子被改为如下：
int i = 0;
std::string str("1!2!3?");
@@ -152,20 +184,27 @@
We have wrapped the sub-expression `_d [ ++ref(i) ]` in `keep()`. Now,
whenever
this regex matches a digit, the action will be queued and then immediately
executed before we try to match a `'!'` character. In this case, the action
-executes three times.
+executes three times.\n
+我们把子表达式 `_d [ ++ref(i) ]` 包入 `keep()` 中。现在，当这个regex匹配到
一个数字时，该动作就会被加入队列，然后在我们试图匹配
+`'!'` 字符之前立即执行。在此情况下，该动作被执行三次。
[note Like `keep()`, actions within [^[funcref boost::xpressive::before
before()]]
and [^[funcref boost::xpressive::after after()]] are also executed early
when their
-sub-expressions have matched.]
-
-[h3 Lazy Functions]
+sub-expressions have matched.\n
+和 `keep()` 相似，在 [^[funcref boost::xpressive::before before()]] 和
+[^[funcref boost::xpressive::after after()]] 中的动作也会在它们的子表达式被
匹配时提前执行。]
+
+[h3 Lazy Functions 延迟函数]
So far, we've seen how to write semantic actions consisting of variables
and
operators. But what if you want to be able to call a function from a
semantic
-action? Xpressive provides a mechanism to do this.
+action? Xpressive provides a mechanism to do this.\n
+到目前为止，我们已经看过如何编写一个由变量和操作符组成的语义动作。
+但是如果你想在一个语义动作中调用某个函数，那要怎么做呢？Xpressive提供了一个
机制来实现它。
The first step is to define a function object type. Here, for instance, is
a
-function object type that calls `push()` on its argument:
+function object type that calls `push()` on its argument:\n
+第一步是定义一个函数对象类型。例如，以下是一个对其参数调用 `push()` 的函数
对象类型：
struct push_impl
{
@@ -180,14 +219,17 @@
};
The next step is to use xpressive's `function<>` template to define a
function
-object named `push`:
+object named `push`:\n
+下一步是用xpressive的 `function<>` 模板来定义一个名为 `push` 的函数对象：
// Global "push" function object.
function<push_impl>::type const push = {{}};
The initialization looks a bit odd, but this is because `push` is being
statically initialized. That means it doesn't need to be constructed
-at runtime. We can use `push` in semantic actions as follows:
+at runtime. We can use `push` in semantic actions as follows:\n
+这里的初始化看起来有点奇怪，这是因为 `push` 是被静态初始化的。这意味着它不
需要在运行期进行构造。
+我们可以在语义动作中使用 `push`，如下：
std::stack<int> ints;
// Match digits, cast them to an int
@@ -197,17 +239,22 @@
You'll notice that doing it this way causes member function invocations
to look like ordinary function invocations. You can choose to write your
semantic action in a different way that makes it look a bit more like
-a member function call:
+a member function call:\n
+你会留意到，用这种方法来做会使得成员函数的调用看起来象一个普通函数的调用。
+你可以选择以其它方式来编写你的语义动作，令它看起来更象成员函数调用一点：
sregex rex = (+_d)[ref(ints)->*push(as<int>(_))];
Xpressive recognizes the use of the `->*` and treats this expression
-exactly the same as the one above.
+exactly the same as the one above.\n
+Xpressive会认得 `->*` 并把这个表达式视为与上一个完全一样。
When your function object must return a type that depends on its
arguments, you can use a `result<>` member template instead of the
`result_type` typedef. Here, for example, is a `first` function object
-that returns the `first` member of a `std::pair<>` or _sub_match_:
+that returns the `first` member of a `std::pair<>` or _sub_match_:\n
+如果你的函数对象必须根据其参数决定返回的类型，那么你可以使用 `result<>` 成
员模板来替代 `result_type` typedef。
+例如，以下是一个 `first` 函数对象，它返回一个 `std::pair<>` 或 _sub_match_
的 `first` 成员：
// Function object that returns the
// first element of a pair.
@@ -234,13 +281,16 @@
// of the sub-match referred to by s1.
function<first_impl>::type const first = {{}};
-[h3 Referring to Local Variables]
+[h3 Referring to Local Variables 引用局部变量]
As we've seen in the examples above, we can refer to local variables within
an actions using `xpressive::ref()`. Any such variables are held by
reference
by the regular expression, and care should be taken to avoid letting those
references dangle. For instance, in the following code, the reference to
`i`
-is left to dangle when `bad_voodoo()` returns:
+is left to dangle when `bad_voodoo()` returns:\n
+正如我们在上例中所看到的，我们可以用 `xpressive::ref()` 在一个动作内引用某
个局部变量。
+所有这样的变量都会被正则表达式以引用方式保存，并要小心避免让它们变为悬空的
引用。
+例如，在以下代码中，到 `i` 的引用会在 `bad_voodoo()` 返回时悬空：
sregex bad_voodoo()
{
@@ -254,7 +304,8 @@
When writing semantic actions, it is your responsibility to make sure that
all the references do not dangle. One way to do that would be to make the
-variables shared pointers that are held by the regex by value.
+variables shared pointers that are held by the regex by value.\n
+在编写语义动作时，你要负责确保所有引用不会悬空。一种解决方法是，把变量变为
由regex以值方式持有的共享指针。
sregex good_voodoo(boost::shared_ptr<int> pi)
{
@@ -268,11 +319,16 @@
value. That's not normally necessary because local variables appearing in
actions are held by value by default, but in this case, it is necessary.
Had
we written the action as `++*pi`, it would have executed immediately.
That's
-because `++*pi` is not an expression template, but `++*val(pi)` is.
+because `++*pi` is not an expression template, but `++*val(pi)` is.\n
+在以上代码中，我们用 `xpressive::val()` 来以值方式持有该共享指针。
+通常这是不需要的，因为在动作中出现的局部变量缺省是以值方式持有的，不过在这
个例子中，这样做是必须的。
+如果我们把这个动作写为 `++*pi`，它就会立即执行。这是因为 `++*pi` 不是一个表
达式模板，而 `++*val(pi)` 是。
It can be tedious to wrap all your variables in `ref()` and `val()` in your
semantic actions. Xpressive provides the `reference<>` and `value<>`
templates
-to make things easier. The following table shows the equivalencies:
+to make things easier. The following table shows the equivalencies:\n
+在语义动作中把所有变量都用 `ref()` 和 `val()` 包起来是很乏味的。
+Xpressive提供了 `reference<>` 和 `value<>` 模板，可以使得这件事情容易些。下
表列出这两个模板：
[table reference<> and value<>
[[This ...][... is equivalent to this ...]]
@@ -290,7 +346,9 @@
As you can see, when using `reference<>`, you need to first declare a local
variable and then declare a `reference<>` to it. These two steps can be
combined
-into one using `local<>`.
+into one using `local<>`.\n
+如你所见，使用 `reference<>` 的时候，你要首先声明一个局部变量，然后声明对它
一个 `reference<>`。
+这两个步骤可以用 `local<>` 合并为一步。
[table local<> vs. reference<>
[[This ...][... is equivalent to this ...]]
@@ -301,7 +359,8 @@
sregex rex = +( _d [ ++ri ] >> '!' );``]]
]
-We can use `local<>` to rewrite the above example as follows:
+We can use `local<>` to rewrite the above example as follows:\n
+我们可以用 `local<>` 重写前面的例子，如下：
local<int> i(0);
std::string str("1!2!3?");
@@ -313,9 +372,10 @@
Notice that we use `local<>::get()` to access the value of the local
variable. Also, beware that `local<>` can be used to create a dangling
-reference, just as `reference<>` can.
-
-[h3 Referring to Non-Local Variables]
+reference, just as `reference<>` can.\n
+注意，我们用了 `local<>::get()` 来访问这个局部变量的值。还有，要小心
`local<>` 也可能被用于创建一个悬空的引用，象 `reference<>` 那样。
+
+[h3 Referring to Non-Local Variables 引用非局部变量]
In the beginning of this
section, we used a regex with a semantic action to parse a string of
@@ -327,7 +387,13 @@
the regex object. What we can do instead is define a placeholder and use
that in the semantic action instead of the map itself. Later, when we
call one of the regex algorithms, we can bind the reference to an actual
-map object. The following code shows how.
+map object. The following code shows how.\n
+在本节的开始，我们用一个带语义动作的regex来分析一个由单词/整数对组成的
串，并将它们存入一个 `std::map<>` 中。
+这就要求这个map和这个regex要一起定义，并且在它们的任何一个超出作用域之前使
用。
+如果我们想定义regex一次并用它来填充多个不同的 map，应该怎么办呢？
+我们应该把这个map传入 _regex_match_ 算法，而不是直接在regex对象中嵌入一个引
用。
+我们可以做的是，定义一个占位符并在语义动作当中用它来替换map本身。
+然后，当我们调用某个 regex算法时，我们就可以将这个引用绑定到一个实际的map对
象。以下代码示范了要怎么做。
// Define a placeholder for a map object:
placeholder<std::map<std::string, int> > _map;
@@ -359,7 +425,8 @@
std::cout << result["ccc"] << '\n';
}
-This program displays:
+This program displays:\n
+程序输出：
[pre
1
@@ -372,18 +439,25 @@
it were a map. Then, we define a _match_results_ struct and bind an actual
map
to the placeholder with "`what.let( _map = result );`". The _regex_match_
call
behaves as if the placeholder in the semantic action had been replaced
with a
-reference to `result`.
+reference to `result`.\n
+这里我们用 `placeholder<>` 来定义 `_map`，用于代替 `std::map<>` 变量。我们
在语义动作中可以象用一个map那样使用这个占位符。
+然后，我们定义一个 _match_results_ 结构并用 `"what.let( _map = result );"`
把一个实际的map绑定至这个占位符。
+_regex_match_ 调用的行为就象语义动作中的占位符被替换为 `result` 的一个引用
一样。
[note Placeholders in semantic actions are not /actually/ replaced at
runtime
with references to variables. The regex object is never mutated in any way
during any of the regex algorithms, so they are safe to use in multiple
-threads.]
+threads.\n
+语义动作中的占位符并不是在运行期/真的/被替换为某个变量的引用。
+在任何regex算法执行期间，regex对象都不会被修改，所以它们可以在多线程环境中
安全地使用。]
The syntax for late-bound action arguments is a little different if you are
using _regex_iterator_ or _regex_token_iterator_. The regex iterators
accept
an extra constructor parameter for specifying the argument bindings. There
is
a `let()` function that you can use to bind variables to their
placeholders.
-The following code demonstrates how.
+The following code demonstrates how.\n
+如果你要用 _regex_iterator_ 或 _regex_token_iterator_，那么动作参数的延迟绑
定语法要有一点不同。
+regex迭代器接受一个额外的构造函数参数，以指定要绑定的参数。你可以用一个
`let()` 函数来将变量绑定至它们的占位符。以下代码示范了要怎么做。
// Define a placeholder for a map object:
placeholder<std::map<std::string, int> > _map;
@@ -412,7 +486,8 @@
std::cout << result["bbb"] << '\n';
std::cout << result["ccc"] << '\n';
-This program displays:
+This program displays:\n
+程序输出：
[pre
1
@@ -420,19 +495,24 @@
456
]
-[h2 User-Defined Assertions]
+[h2 User-Defined Assertions 用户自定义断言]
You are probably already familiar with regular expression /assertions/. In
Perl, some examples are the [^^] and [^$] assertions, which you can use to
match the beginning and end of a string, respectively. Xpressive lets you
define your own assertions. A custom assertion is a contition which must be
true at a point in the match in order for the match to succeed. You can
check
-a custom assertion with xpressive's _check_ function.
+a custom assertion with xpressive's _check_ function.\n
+可能你对正则表达式断言已经非常熟悉。在Perl中，可以以 [^^] 和 [^$] 断言为
例，你可以用它们来分别匹配字符串的开始与结尾。
+Xpressive可以让你定义自己的断言。客户化断言是指为了令匹配成功而在匹配点上必
须为真的一个条件。
+你可以用xpressive的 _check_ 函数来检查一个客户化断言。
There are a couple of ways to define a custom assertion. The simplest is to
use a function object. Let's say that you want to ensure that a
sub-expression
matches a sub-string that is either 3 or 6 characters long. The following
-struct defines such a predicate:
+struct defines such a predicate:\n
+有多种方法来下定义一个客户化断言。最简单的方法是用一个函数对象。
+我们假定你要确认某个子表达式匹配一个长度为3或6的子串。以下结构定义了这样的
一个谓词：
// A predicate that is true IFF a sub-match is
// either 3 or 6 characters long.
@@ -444,7 +524,8 @@
}
};
-You can use this predicate within a regular expression as follows:
+You can use this predicate within a regular expression as follows:\n
+你可以在一个正则表达式中用这个谓词，如下：
// match words of 3 characters or 6 characters.
sregex rx = (bow >> +_w >> eow)[ check(three_or_six()) ] ;
@@ -452,26 +533,32 @@
The above regular expression will find whole words that are either 3 or 6
characters long. The `three_or_six` predicate accepts a _sub_match_ that
refers
back to the part of the string matched by the sub-expression to which the
-custom assertion is attached.
+custom assertion is attached.\n
+以上正则表达式将找出长度为3或6个字符的完整单词。谓词 `three_or_six` 接受一
个
+_sub_match_，它引向由该客户化断言所附着的子表达式所匹配的部分字符串。
[note The custom assertion participates in determining whether the match
succeeds or fails. Unlike actions, which execute lazily, custom assertions
-execute immediately while the regex engine is searching for a match.]
+execute immediately while the regex engine is searching for a match.\n
+客户化断言参与了对当前匹配是否成功的判断。与延迟执行的动作不同，客户化断言
是在regex引擎查找到一个匹配时立即执行的。]
Custom assertions can also be defined inline using the same syntax as for
-semantic actions. Below is the same custom assertion written inline:
+semantic actions. Below is the same custom assertion written inline:\n
+客户化断言还可以使用与语义动作相同的语法来内联定义。以下是以内联方式编写的
同一个客户化断言：
// match words of 3 characters or 6 characters.
sregex rx = (bow >> +_w >> eow)[ check(length(_)==3 || length(_)==6)
] ;
In the above, `length()` is a lazy function that calls the `length()`
member
function of its argument, and `_` is a placeholder that receives the
-`sub_match`.
+`sub_match`.\n
+在上例中，`length()` 是一个延迟函数，它调用其参数的 `length()` 成员函
数，而 `_` 是接收 `sub_match` 的占位符。
Once you get the hang of writing custom assertions inline, they can be
very powerful. For example, you can write a regular expression that
only matches valid dates (for some suitably liberal definition of the
-term ["valid]).
+term ["valid]).\n
+一旦学会编写内联式的客户化断言，它们可以非常强大。例如，你可以写一个只匹配
有效日期的正则表达式(对术语["有效]的定义适当宽松了一些)。
int const days_per_month[] =
{31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 31, 31};
@@ -504,7 +591,8 @@
std::cout << what[0] << std::endl;
}
-The above program prints out the following:
+The above program prints out the following:\n
+以上程序输出如下：
[pre
2/28/2006
@@ -513,6 +601,8 @@
Notice how the inline custom assertions are used to range-check the values
for
the month, day and year. The regular expression doesn't match
`"99/99/9999"` or
`"2/30/2006"` because they are not valid dates. (There is no 99th month,
and
-February doesn't have 30 days.)
+February doesn't have 30 days.)\n
+留意这里的内联式客户化断言如何用来对月、日、年的值进行范围检查。该正则表达
式不匹配 `"99/99/9999"`
+或 `"2/30/2006"`，因为它们不是有效的日期。(没有第99个月，二月份也没有30天
)。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/concepts.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/concepts.qbk Sun Aug 1 20:47:57 2010
@@ -5,100 +5,119 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Concepts]
-
-[h2 CharT requirements]
+[section:concepts Concepts 概念]
+
+[h2 CharT requirements CharT的要求]
If type `BidiIterT` is used as a template argument to _basic_regex_, then
`CharT` is
`iterator_traits<BidiIterT>::value_type`. Type `CharT` must have a trivial
default
constructor, copy constructor, assignment operator, and destructor. In
addition
the following requirements must be met for objects; `c` of type `CharT`,
`c1` and `c2` of
-type `CharT const`, and `i` of type `int`:
+type `CharT const`, and `i` of type `int`:\n
+如果类型 `BidiIterT` 被用作 _basic_regex_ 的一个模板参数，则 `CharT` 为
`iterator_traits<BidiIterT>::value_type`。
+类型 `CharT` 必须带有一个平凡的缺省构造函数、复制构造函数、赋值操作符和析构
函数。
+另外，还必须符合以下要求；其中 `c` 的类型为 `CharT`, `c1` 和 `c2` 的类型为
`CharT const`, 而 `i` 的类型为 `int`:
[table CharT Requirements
[
- [[*Expression]]
- [[*Return type]]
- [[*Assertion / Note / Pre- / Post-condition]]
+ [[*Expression 表达式]]
+ [[*Return type 返回类型]]
+ [[*Assertion / Note / Pre- / Post-condition 断言/说明/先验/后验条件
]]
]
[
[`CharT c`]
[`CharT`]
- [Default constructor (must be trivial).]
+ [Default constructor (must be trivial).\n
+ 缺省构造函数(必须是平凡的)。]
]
[
[`CharT c(c1)`]
[`CharT`]
- [Copy constructor (must be trivial).]
+ [Copy constructor (must be trivial).\n
+ 复制构造函数(必须是平凡的)。]
]
[
[`c1 = c2`]
[`CharT`]
- [Assignment operator (must be trivial).]
+ [Assignment operator (must be trivial).\n
+ 赋值操作符(必须是平凡的)。]
]
[
[`c1 == c2`]
[`bool`]
- [`true` if `c1` has the same value as `c2`.]
+ [`true` if `c1` has the same value as `c2`.\n
+ `true` 如果 `c1` 的值与 `c2` 相同。]
]
[
[`c1 != c2`]
[`bool`]
- [`true` if `c1` and `c2` are not equal.]
+ [`true` if `c1` and `c2` are not equal.\n
+ `true` 如果 `c1` 的值与 `c2` 不同。]
]
[
[`c1 < c2`]
[`bool`]
- [`true` if the value of `c1` is less than `c2`.]
+ [`true` if the value of `c1` is less than `c2`.\n
+ `true` 如果 `c1` 的值小于 `c2`。]
]
[
[`c1 > c2`]
[`bool`]
- [`true` if the value of `c1` is greater than `c2`.]
+ [`true` if the value of `c1` is greater than `c2`.\n
+ `true` 如果 `c1` 的值大于 `c2`。]
]
[
[`c1 <= c2`]
[`bool`]
- [`true` if `c1` is less than or equal to `c2`.]
+ [`true` if `c1` is less than or equal to `c2`.\n
+ `true` 如果 `c1` 的值小于等于 `c2`。]
]
[
[`c1 >= c2`]
[`bool`]
- [`true` if `c1` is greater than or equal to `c2`.]
+ [`true` if `c1` is greater than or equal to `c2`.\n
+ `true` 如果 `c1` 的值大于等于 `c2`。]
]
[
[`intmax_t i = c1`]
[`int`]
[
- `CharT` must be convertible to an integral type.
+ `CharT` must be convertible to an integral type.\n
+ `CharT` 必须可以转换为一个整数类型。
]
]
[
[`CharT c(i);`]
[`CharT`]
- [`CharT` must be constructable from an integral type.]
+ [`CharT` must be constructable from an integral type.\n
+ `CharT` 必须可以从一个整数类型构造。]
]
]
-[h2 Traits Requirements]
+[h2 Traits Requirements Traits的要求]
In the following table `X` denotes a traits class defining types and
functions
for the character container type `CharT`; `u` is an object of type `X`;
`v` is an
object of type `const X`; `p` is a value of type `const CharT*`; `I1` and
`I2` are
`Input Iterators`; `c` is a value of type `const CharT`; `s` is an object
of type
`X::string_type`; `cs` is an object of type `const X::string_type`; `b` is
a value of
type `bool`; `i` is a value of type `int`; `F1` and `F2` are values of
type `const CharT*`;
-`loc` is an object of type `X::locale_type`; and `ch` is an object of
`const char`.
+`loc` is an object of type `X::locale_type`; and `ch` is an object of
`const char`.\n
+在下表中，`X` 表示一个traits类，为字符容器类型 `CharT` 定义了相关类型和函
数；`u` 是一个类型为 `X` 的对象；
+`v` 是一个类型为 `const X` 的对象；`p` 是类型为 `const CharT*` 的值；`I1`
和 `I2` 为 `Input Iterators`；
+`c` 是类型为 `const CharT` 的值；`s` 是一个类型为 `X::string_type` 的对
象；`cs` 是一个类型为 `const X::string_type` 的对象；
+`b` 是类型为 `bool` 的值；`i` 是类型为 `int` 的值；`F1` 和 `F2` 是类型为
`const CharT*` 的值；
+`loc` 是一个类型为 `X::locale_type` 的对象；`ch` 是一个类型为 `const char`
的对象。
[table Traits Requirements
[
[
- [*Expression]
+ [*Expression 表达式]
]
[
- [*Return type]
+ [*Return type 返回类型]
]
[
- [*Assertion / Note\n
- Pre / Post condition]
+ [*Assertion / Note 断言/说明\n
+ Pre / Post condition 先验/后验条件]
]
]
[
@@ -109,7 +128,8 @@
`CharT`
]
[
- The character container type used in the implementation of
class template _basic_regex_.
+ The character container type used in the implementation of
class template _basic_regex_.\n
+ 在类模板 _basic_regex_ 的实现中所使用的字符容器类型。
]
]
[
@@ -131,7 +151,8 @@
['Implementation defined]
]
[
- A copy constructible type that represents the locale used by
the traits class.
+ A copy constructible type that represents the locale used by
the traits class.\n
+ 一个表示该traits类所使用的locale的可复制构造类型。
]
]
[
@@ -143,7 +164,8 @@
]
[
A bitmask type representing a particular character
classification. Multiple
- values of this type can be bitwise-or'ed together to
obtain a new valid value.
+ values of this type can be bitwise-or'ed together to
obtain a new valid value.\n
+ 一个表示特定字符分类的掩码类型。可以对该类型的多个值进行位
或操作以得到一个新的有效值。
]
]
[
@@ -154,7 +176,8 @@
`unsigned char`
]
[
- Yields a value between `0` and `UCHAR_MAX` inclusive.
+ Yields a value between `0` and `UCHAR_MAX` inclusive.\n
+ 生成一个在 `0` 到 `UCHAR_MAX` (含)之间的值。
]
]
[
@@ -165,7 +188,8 @@
`CharT`
]
[
- Widens the specified `char` and returns the resulting `CharT`.
+ Widens the specified `char` and returns the resulting
`CharT`.\n
+ 对指定的 `char` 加宽并返回得到的 `CharT`.
]
]
[
@@ -177,7 +201,8 @@
]
[
For any characters `r1` and `r2`, returns `true` if `r1 <= c
&& c <= r2`.
- Requires that `r1 <= r2`.
+ Requires that `r1 <= r2`.\n
+ 对于任意字符 `r1` 和 `r2`，返回 `true` 如果 `r1 <= c && c
<= r2`。要求 `r1 <= r2`.
]
]
[
@@ -190,7 +215,9 @@
[
For characters `r1` and `r2`, returns `true` if there is some
character
`d` for which `v.translate_nocase(d) ==
v.translate_nocase(c)` and
- `r1 <= d && d <= r2`. Requires that `r1 <= r2`.
+ `r1 <= d && d <= r2`. Requires that `r1 <= r2`.\n
+ 对于任意字符 `r1` 和 `r2`，返回 `true` 如果存在某个字符
`d` 满足 `v.translate_nocase(d) == v.translate_nocase(c)`
+ 且 `r1 <= d && d <= r2`。要求 `r1 <= r2`.
]
]
[
@@ -202,7 +229,8 @@
]
[
Returns a character such that for any character `d` that is to
be considered
- equivalent to `c` then `v.translate(c) == v.translate(d)`.
+ equivalent to `c` then `v.translate(c) ==
v.translate(d)`.\n
+ 返回一个字符，满足对于任意被认为等同于 `c` 的字符 `d` 有
`v.translate(c) == v.translate(d)`.
]
]
[
@@ -215,7 +243,8 @@
[
For all characters `C` that are to be considered
equivalent to `c` when comparisons are to be performed without
regard to case,
- then `v.translate_nocase(c) == v.translate_nocase(C)`.
+ then `v.translate_nocase(c) == v.translate_nocase(C)`.\n
+ 对于所有被认为等同于 `c` 的字符 `C`，如果比较操作不考虑大小
写，则 `v.translate_nocase(c) == v.translate_nocase(C)`.
]
]
[
@@ -228,7 +257,9 @@
[
Returns a sort key for the character sequence designated by
the iterator range
`[F1, F2)` such that if the character sequence `[G1, G2)`
sorts before the
- character sequence `[H1, H2)` then `v.transform(G1, G2) <
v.transform(H1, H2)`.
+ character sequence `[H1, H2)` then `v.transform(G1, G2) <
v.transform(H1, H2)`.\n
+ 对于由迭代器区间 `[F1, F2)` 所指定的字符序列，返回一个分类
键，满足如果字符序列 `[G1, G2)`
+ 排在字符序列 `[H1, H2)` 之前，则 `v.transform(G1, G2) <
v.transform(H1, H2)`.
]
]
[
@@ -242,7 +273,9 @@
Returns a sort key for the character sequence designated by
the iterator range
`[F1, F2)` such that if the character sequence `[G1, G2)`
sorts before the
character sequence `[H1, H2)` when character case is not
considered then
- `v.transform_primary(G1, G2) < v.transform_primary(H1,
H2)`.
+ `v.transform_primary(G1, G2) < v.transform_primary(H1,
H2)`.\n
+ 对于由迭代器区间 `[F1, F2)` 所指定的字符序列，返回一个分类
键，满足如果字符序列 `[G1, G2)`
+ 在不考虑大小写时，排在字符序列 `[H1, H2)` 之前，则
`v.transform_primary(G1, G2) < v.transform_primary(H1, H2)`.
]
]
[
@@ -258,7 +291,10 @@
`lookup_classname` can be safely bitwise or'ed together.
Returns `0` if the
character sequence is not the name of a character class
recognized by `X`. The
value returned shall be independent of the case of the
characters in the
- sequence.
+ sequence.\n
+ 将由迭代器区间 `[F1,F2)` 所指定的字符序列转换为一个可以传递
给 `isctype` 的掩码类型。
+ 由 `lookup_classname` 返回值可以安全地进行位或操作。如果该
字符序列不是由 `X`
+ 所承认的字符类的名字，则返回 `0`。返回值应该与序列中的字符
大小写无关。
]
]
[
@@ -272,7 +308,9 @@
Returns a sequence of characters that represents the collating
element
consisting of the character sequence designated by the
iterator range `[F1, F2)`.
Returns an empty string if the character sequence is not a
valid collating
- element.
+ element.\n
+ 返回一个字符序列，表示包含由迭代器区间 `[F1, F2)` 所指定的
字符序列的校对元素。
+ 如果该字符序列不是一个有效的校对元素，则返回一个空串。
]
]
[
@@ -284,7 +322,8 @@
]
[
Returns `true` if character `c` is a member of the character
class designated by
- the iterator range `[F1, F2)`, `false` otherwise.
+ the iterator range `[F1, F2)`, `false` otherwise.\n
+ 如果字符 `c` 是由迭代器区间 `[F1, F2)` 所指定的字符类的成
员，则返回 `true`，否则返回 `false`。
]
]
[
@@ -297,7 +336,9 @@
[
Returns the value represented by the digit `c` in base `i` if
the character `c` is a
valid digit in base `i`; otherwise returns `-1`.\n
- \[Note: the value of `i` will only be `8`, `10`, or `16`.
-end note\]
+ \[Note: the value of `i` will only be `8`, `10`, or `16`.
-end note\]\n
+ 如果字符 `c` 是 `i` 进制的有效数字，返回由数字 `c` 在 `i`
进制中所表示的数值；否则返回 `-1`.\n
+ \[注：`i` 的值只能为 `8`, `10`, 或 `16`. -注完\]
]
]
[
@@ -309,7 +350,8 @@
]
[
Imbues `u` with the locale `loc`, returns the previous
- locale used by `u`.
+ locale used by `u`.\n
+ 将 locale `loc` 注入 `u`，返回 `u` 原来所使用的locale。
]
]
[
@@ -320,14 +362,16 @@
`X::locale_type`
]
[
- Returns the current locale used by `v`.
+ Returns the current locale used by `v`.\n
+ 返回 `v` 当前所使用的locale。
]
]
]
-[h2 Acknowledgements]
+[h2 Acknowledgements 鸣谢]
This section is adapted from the equivalent page in the _regexpp_
documentation and from the
-_proposal_ to add regular expressions to the Standard Library.
+_proposal_ to add regular expressions to the Standard Library.\n
+本节改编自 _regexpp_ 文档中的相同部分以及关于为标准库增加正则表达式的
_proposal_。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/dynamic_regexes.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/dynamic_regexes.qbk Sun Aug 1 20:47:57 2010
@@ -5,60 +5,78 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Dynamic Regexes]
-
-[h2 Overview]
+[section:dynamic_regexes Dynamic Regexes 动态Regexes]
+
+[h2 Overview 概述]
Static regexes are dandy, but sometimes you need something a bit more ...
dynamic. Imagine you are developing
a text editor with a regex search/replace feature. You need to accept a
regular expression from the end user
as input at run-time. There should be a way to parse a string into a
regular expression. That's what xpressive's
dynamic regexes are for. They are built from the same core components as
their static counterparts, but they
-are late-bound so you can specify them at run-time.
-
-[h2 Construction and Assignment]
+are late-bound so you can specify them at run-time.\n
+静态regexes非常漂亮，但有时你还需要更多的 ... 动态。想象你正在开发一个带有
regex查找/替换功能的文本编辑器。
+你需要在运行期从最终用户处输入正则表达式。需要一种方法来将字符串解析为正则
表达式。这正是xpressive的动态regexes要做的。
+它们构建于和静态regex相同核心组件之上，只是它们是后期绑定的，所以你可以在运
行期来指定它们。
+
+[h2 Construction and Assignment 构造与赋值]
There are two ways to create a dynamic regex: with the _regex_compile_
function or with the _regex_compiler_ class template. Use _regex_compile_
if you want the default locale. Use _regex_compiler_ if you need to
specify a different locale. In the section on
[link boost_xpressive.user_s_guide.grammars_and_nested_matches regex
grammars],
-we'll see another use for _regex_compiler_.
-
-Here is an example of using `basic_regex<>::compile()`:
+we'll see another use for _regex_compiler_.\n
+有两种方法创建一个动态regex：用 _regex_compile_ 函数或者用
_regex_compiler_ 类模板。
+如果你想用缺省locale，则使用 _regex_compile_。如果你需要指定不同的
locale，就使用 _regex_compiler_。
+在 [link boost_xpressive.user_s_guide.grammars_and_nested_matches regex 语
法] 一节中，我们将看到 _regex_compiler_ 的另一种用法。
+
+Here is an example of using `basic_regex<>::compile()`:\n
+以下是一个使用 `basic_regex<>::compile()` 的例子：
sregex re = sregex::compile( "this|that", regex_constants::icase );
-Here is the same example using _regex_compiler_:
+Here is the same example using _regex_compiler_:\n
+以下是同一个例子，不过用的是 _regex_compiler_：
sregex_compiler compiler;
sregex re = compiler.compile( "this|that", regex_constants::icase );
-_regex_compile_ is implemented in terms of _regex_compiler_.
-
-[h2 Dynamic xpressive Syntax]
+_regex_compile_ is implemented in terms of _regex_compiler_.\n
+_regex_compile_ 是依据 _regex_compiler_ 实现的。
+
+[h2 Dynamic xpressive Syntax 动态xpressive语法]
Since the dynamic syntax is not constrained by the rules for valid C++
expressions, we are free to use familiar
syntax for dynamic regexes. For this reason, the syntax used by xpressive
for dynamic regexes follows the
lead set by John Maddock's
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm
proposal]
to add regular expressions to the Standard Library. It is essentially the
syntax standardized by
[@http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf
ECMAScript], with minor changes
-in support of internationalization.
+in support of internationalization.\n
+由于动态语法不受有效C++表达式的限制，所以我们可以随意对动态regexes使用我们
所熟悉的语法。
+为此，xpressive对于动态regexes 所使用的语法是遵照 John Maddock 的关于为标准
库增加正则表达式的
+[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm 建议书
] 的。基本上，它是
+[@http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf
ECMAScript]
所标准化的语法，有一点点变化以支持国际化。
Since the syntax is documented exhaustively elsewhere, I will simply refer
you to the existing standards, rather
-than duplicate the specification here.
-
-[h2 Internationalization]
+than duplicate the specification here.\n
+由于这种语法在很多地方都有记载，所以我只会向你指出一些已有的标准，而不再在
此重复这些规范了。
+
+[h2 Internationalization 国际化]
As with static regexes, dynamic regexes support internationalization by
allowing you to specify a different
`std::locale`. To do this, you must use _regex_compiler_. The
_regex_compiler_ class has an `imbue()` function.
After you have imbued a _regex_compiler_ object with a custom
`std::locale`, all regex objects compiled by
-that _regex_compiler_ will use that locale. For example:
+that _regex_compiler_ will use that locale. For example:\n
+和静态regexes相似，动态regexes也是通过让你指定一个不同的 `std::locale` 来支
持国际化。为此，你必须使用 _regex_compiler_。
+_regex_compiler_ 类有一个 `imbue()` 函数。在你向一个 _regex_compiler_ 对象
注入一个定制的 `std::locale` 后，
+所有由该 _regex_compiler_ 编译的regex对象都将使用该locale。例如：
std::locale my_locale = /* initialize your locale object here */;
sregex_compiler compiler;
compiler.imbue( my_locale );
sregex re = compiler.compile( "\\w+|\\d+" );
-This regex will use `my_locale` when evaluating the intrinsic character
sets `"\\w"` and `"\\d"`.
+This regex will use `my_locale` when evaluating the intrinsic character
sets `"\\w"` and `"\\d"`.\n
+这个regex在对基础字符集 `"\\w"` 和 `"\\d"` 求值时将使用 `my_locale`。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/examples.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/examples.qbk Sun Aug 1 20:47:57 2010
@@ -5,16 +5,18 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Examples]
-
-Below you can find six complete sample programs.
+[section:examples Examples 示例]
+
+Below you can find six complete sample programs.\n
+以下你将看到六个完整的示例程序。
\n
----
-[h4 See if a whole string matches a regex]
-
-This is the example from the Introduction. It is reproduced here for your
convenience.
+[h4 See if a whole string matches a regex 检查整个字符串是否匹配一个regex]
+
+This is the example from the Introduction. It is reproduced here for your
convenience.\n
+这是来自于"简介"一节中的示例。为便于查看，在此重复。
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -38,7 +40,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+程序输出如下：
[pre
hello world!
@@ -50,10 +53,12 @@
----
-[h4 See if a string contains a sub-string that matches a regex]
+[h4 See if a string contains a sub-string that matches a regex 检查一个字符
串是否包含匹配某个regex的子串]
Notice in this example how we use custom `mark_tag`s to make the pattern
more readable.
-We can use the `mark_tag`s later to index into the _match_results_.
+We can use the `mark_tag`s later to index into the _match_results_.\n
+请留意在这个例子中，我们是如何使用定制的 `mark_tags` 来使得匹配的模式更可
读。
+我们可以在稍后使用 `mark_tag`s 来对 _match_results_ 进行索引访问。
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -87,7 +92,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+程序输出如下：
[pre
5/30/1973
@@ -101,9 +107,10 @@
----
-[h4 Replace all sub-strings that match a regex]
-
-The following program finds dates in a string and marks them up with
pseudo-HTML.
+[h4 Replace all sub-strings that match a regex 替换匹配某个regex的所有子串]
+
+The following program finds dates in a string and marks them up with
pseudo-HTML.\n
+以下程序在一个字符串中查找日期并用伪-HTML标记它们。
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -126,7 +133,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+程序输出如下：
[pre
I was born on <date>5/30/1973</date> at 7am.
@@ -136,11 +144,12 @@
----
-[h4 Find all the sub-strings that match a regex and step through them one
at a time]
+[h4 Find all the sub-strings that match a regex and step through them one
at a time 查找匹配某个regex的所有子串并每次一个地分步处理它们]
The following program finds the words in a wide-character string.
It uses `wsregex_iterator`. Notice that dereferencing a `wsregex_iterator`
-yields a `wsmatch` object.
+yields a `wsmatch` object.\n
+以下程序在一个宽字符串中查找单词。它使用 `wsregex_iterator`。注意，对
`wsregex_iterator` 的解引用将产生一个 `wsmatch` 对象。
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -166,7 +175,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+程序输出如下：
[pre
This
@@ -179,10 +189,11 @@
----
-[h4 Split a string into tokens that each match a regex]
+[h4 Split a string into tokens that each match a regex 将字符串分拆为匹配某
个regex的记号]
The following program finds race times in a string and displays first
-the minutes and then the seconds. It uses _regex_token_iterator_.
+the minutes and then the seconds. It uses _regex_token_iterator_.\n
+以下程序在字符串中查找比赛时间，并且先显示分钟数再显示秒数。它使用
_regex_token_iterator_.
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -212,7 +223,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+程序输出如下：
[pre
4
@@ -227,11 +239,13 @@
----
-[h4 Split a string using a regex as a delimiter]
+[h4 Split a string using a regex as a delimiter 用一个regex作为分隔符分拆字
符串]
The following program takes some text that has been marked up with html
and strips
out the mark-up. It uses a regex that matches an HTML tag and a
_regex_token_iterator_
-that returns the parts of the string that do ['not] match the regex.
+that returns the parts of the string that do ['not] match the regex.\n
+以下程序接受一些带有html标记的文本，去掉其中的标记。
+它使用一个regex来匹配HTML标签，并用一个 _regex_token_iterator_ 返回字符串中
不匹配该regex的其余部分。
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -259,7 +273,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+程序输出如下：
[pre
{Now }{is the time }{for all good men}{ to come to the aid of their}{
country.}
@@ -269,9 +284,10 @@
----
-[h4 Display a tree of nested results]
-
-Here is a helper class to demonstrate how you might display a tree of
nested results:
+[h4 Display a tree of nested results 显示嵌套结果组成的树]
+
+Here is a helper class to demonstrate how you might display a tree of
nested results:\n
+以下是一个辅助类，示范了如何显示由嵌套结果组成的树：
// Displays nested results to std::cout with indenting
struct output_nested_results
=======================================
--- /trunk/libs/xpressive/doc/grammars.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/grammars.qbk Sun Aug 1 20:47:57 2010
@@ -5,26 +5,34 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Grammars and Nested Matches]
-
-[h2 Overview]
+[section:grammars_and_nested_matches Grammars and Nested Matches 语法和嵌套
匹配]
+
+[h2 Overview 概述]
One of the key benefits of representing regexes as C++ expressions is the
ability to easily refer to other C++
code and data from within the regex. This enables programming idioms that
are not possible with other regular
expression libraries. Of particular note is the ability for one regex to
refer to another regex, allowing you
to build grammars out of regular expressions. This section describes how
to embed one regex in another by value
and by reference, how regex objects behave when they refer to other
regexes, and how to access the tree of results
-after a successful parse.
-
-[h2 Embedding a Regex by Value]
+after a successful parse.\n
+用C ++表达式来表示regex的一个关键优点是，可以很容易地在regex内引用其它C++代
码和数据。
+这样就可以使用一些其它正则表达式库所不能实现的编程技巧。尤其值得注意的
是，可以在一个regex中引用另一个regex，
+你可以从正则表达式来构建语法。本节将介绍如何将一个regex以值方式或引用方式嵌
入到另一个regex中，
+当regex对象引用其它regex时其行为如何，以及在一次成功的语法分析后如何访问结
果树。
+
+[h2 Embedding a Regex by Value 以值方式嵌入一个Regex ]
The _basic_regex_ object has value semantics. When a regex object appears
on the right-hand side in the definition
of another regex, it is as if the regex were embedded by value; that is, a
copy of the nested regex is stored by
the enclosing regex. The inner regex is invoked by the outer regex during
pattern matching. The inner regex
-participates fully in the match, back-tracking as needed to make the match
succeed.
+participates fully in the match, back-tracking as needed to make the match
succeed.\n
+_basic_regex_ 对象是具有值语义的。当一个regex对象出现在另一个regex的定义中
的右侧时，其作用就象是该regex以值方式被嵌入一样；
+即，内嵌的regex 的一份拷贝被外面的regex所保存。在模式匹配时，里面的regex将
被外面的regex调用。
+里面的regex在匹配中要完全参与，视乎成功匹配的需要进行后向跟踪。
Consider a text editor that has a regex-find feature with a whole-word
option. You can implement this with
-xpressive as follows:
+xpressive as follows:\n
+来看一个文本编辑器，它具有regex-查找的功能，并带有一个"完整单词"的选项。你
可以用xpressive实现如下：
find_dialog dlg;
if( dialog_ok == dlg.do_modal() )
@@ -43,32 +51,43 @@
// ... use re ...
}
-Look closely at this line:
+Look closely at this line:\n
+我们来仔细看看这一行：
// wrap the regex in begin-word / end-word assertions
re = bow >> re >> eow;
This line creates a new regex that embeds the old regex by value. Then,
the new regex is assigned back to
the original regex. Since a copy of the old regex was made on the
right-hand side, this works as you might
-expect: the new regex has the behavior of the old regex wrapped in begin-
and end-word assertions.
+expect: the new regex has the behavior of the old regex wrapped in begin-
and end-word assertions.\n
+这一行创建了一个新的regex，它以值方式嵌入了旧的regex。然后，这个新的regex被
赋值回给原来的regex。
+由于在右侧创建了旧regex 的一份拷贝，所以其结果正如你所想：新的regex的行为就
是旧regex被包在 begin- 和 end-word 断言中。
[note Note that `re = bow >> re >> eow` does ['not] define a recursive
regular expression, since regex
objects embed by value by default. The next section shows how to define a
recursive regular expression by
-embedding a regex by reference.]
-
-[h2 Embedding a Regex by Reference]
+embedding a regex by reference.\n
+注意，`re = bow >> re >> eow` 并没有定义一个递归的正则表达式，因为缺省情况
下，regex对象是以值方式嵌入的。
+下一节将示范如何通过以引用方式嵌入regex来定义一个递归的正则表达式。]
+
+[h2 Embedding a Regex by Reference 以引用方式嵌入一个Regex]
If you want to be able to build recursive regular expressions and
context-free grammars, embedding a regex
by value is not enough. You need to be able to make your regular
expressions self-referential. Most regular
-expression engines don't give you that power, but xpressive does.
+expression engines don't give you that power, but xpressive does.\n
+如果你想构建递归的正则表达式和上下文无关的语法，以值方式嵌入regex是不够的。
你要能让你的正则表达式自引用。
+多数正则表达式引擎没有这个能力，但 xpressive 可以。
[tip The theoretical computer scientists out there will correctly point
out that a self-referential
regular expression is not "regular", so in the strict sense, xpressive
isn't really a ['regular] expression engine
at all. But as Larry Wall once said, "the term '''[regular expression]'''
has grown with the capabilities of our
-pattern matching engines, so I'm not going to try to fight linguistic
necessity here."]
+pattern matching engines, so I'm not going to try to fight linguistic
necessity here."\n
+计算机理论科学家会正确地指出，一个自引用的正则表达式并不“正规”，所以在严格
意义上，xpressive实际上并不是一个正则表达式引擎。
+不过正如 Larry Wall 曾说过的，"这个术语'''[正则表达式]'''已随着我们的模式匹
配引擎能力的发展而发展，
+所以我不打算在这里尝试和语言规律相争。" ]
Consider the following code, which uses the `by_ref()` helper to define a
recursive regular expression that
-matches balanced, nested parentheses:
+matches balanced, nested parentheses:\n
+来看以下代码，它用 `by_ref()` 辅助函数定义了一个递归的正则表达式，来匹配成
对的嵌套的括号：
sregex parentheses;
parentheses // A balanced set of
parentheses ...
@@ -86,13 +105,18 @@
Matching balanced, nested tags is an important text processing task, and
it is one that "classic" regular
expressions cannot do. The `by_ref()` helper makes it possible. It allows
one regex object to be embedded
in another ['by reference]. Since the right-hand side holds `parentheses`
by reference, assigning the right-hand
-side back to `parentheses` creates a cycle, which will execute recursively.
-
-[h2 Building a Grammar]
+side back to `parentheses` creates a cycle, which will execute
recursively.\n
+匹配成对的、嵌套的标签是一项重要的文本处理任务，它也是"经典的"正则表达式所
不能完成的任务。
+辅助函数 `by_ref()` 使得它可以实现了。它允许一个regex对象['以引用方式]嵌入
到另一个之中。
+由于赋值操作的右侧以引用方式持有 `parentheses`，所以将右侧部分赋值回
`parentheses` 将创建一个循环，它将递归执行。
+
+[h2 Building a Grammar 构建一种语法]
Once we allow self-reference in our regular expressions, the genie is out
of the bottle and all manner of
fun things are possible. In particular, we can now build grammars out of
regular expressions. Let's have
-a look at the text-book grammar example: the humble calculator.
+a look at the text-book grammar example: the humble calculator.\n
+一旦我们可以在正则表达式中使用自引用，就象魔鬼出了瓶子，各种有趣的事情都可
能发生了。
+尤其是，我们现在可以从正则表达式来构建语法。我们来看一个文本图书的语法例
子：一个简陋的计算器。
sregex group, factor, term, expression;
@@ -105,7 +129,10 @@
mathematical expressions. For example, if the input string were `"foo
9*(10+3) bar"`, this pattern would
match `"9*(10+3)"`. It only matches well-formed mathematical expressions,
where the parentheses are
balanced and the infix operators have two arguments each. Don't try this
with just any regular expression
-engine!
+engine!\n
+以上定义的regex `expression` 做的事情对于一个正则表达式来说是不寻常的：它匹
配数学表达式。
+例如，如果输入的字符串是 `"foo 9*(10+3) bar"`，那么这个模式会匹配
`"9*(10+3)"`。
+它只匹配正确的数学表达式，即括号是成对的，且各个中缀操作符都有两个操作数。
不要用其它任意的正则表达式引擎来尝试它！
Let's take a closer look at this regular expression grammar. Notice that
it is cyclic: `expression` is
implemented in terms of `term`, which is implemented in terms of `factor`,
which is implemented in terms
@@ -114,29 +141,43 @@
that have not yet been initialized. In the above grammar, there is only
one place where we need to reference
a regex object that has not yet been initialized: the definition of
`group`. In that place, we use
`by_ref()` to embed `expression` by reference. In all other places, it is
sufficient to embed the other
-regex objects by value, since they have already been initialized and their
values will not change.
-
-[tip [*Embed by value if possible]
+regex objects by value, since they have already been initialized and their
values will not change.\n
+我们来仔细看一下这个正则表达式语法。注意，它是循环的：`expression` 要依据
`term` 实现，后者要依据 `factor`
+实现，后者再依据 `group` 实现，后者再依据 `expression` 来实现，完成一个循
环。
+通常，定义一个循环语法的方法是，前向声明regex对象并以引用方式将尚未初始化的
它们嵌入到正则表达式中。
+在以上这个语法中，只有一个地方需要引用尚未初始化的regex对象：在 `group` 的
定义中。
+在此，我们使用 `by_ref()` 来以引用方式嵌入 `expression`。
+在所有其它的地方，以值方式嵌入其它regex对象就够了，因为它们都已经完成了初始
化，而且值不会再变了。
+
+[tip [*Embed by value if possible 只要可能就以值方式嵌入]
\n\n
In general, prefer embedding regular expressions by value rather than by
reference. It
involves one less indirection, making your patterns match a little faster.
Besides, value semantics
are simpler and will make your grammars easier to reason about. Don't
worry about the expense of "copying"
-a regex. Each regex object shares its implementation with all of its
copies.]
-
-[h2 Dynamic Regex Grammars]
+a regex. Each regex object shares its implementation with all of its
copies.\n
+通常，应该优先以值的方式而不是引用的方式嵌入正则表达式。这样可以少一层间接
层，使你的模式匹配更快一点。
+此外，值语义更为简单，可以让你的语法更易懂。不要担心"复制"一个regex的开销。
每个regex对象在其所有拷贝间共享其实现。]
+
+[h2 Dynamic Regex Grammars 动态Regex语法]
Using _regex_compiler_, you can also build grammars out of dynamic regular
expressions.
You do that by creating named regexes, and referring to other regexes by
name. Each
_regex_compiler_ instance keeps a mapping from names to regexes that have
been created
-with it.
+with it.\n
+使用 _regex_compiler_，你可以从动态正则表达式来构建语法。为此，你要通过创建
命名regexes，然后以名字来引用至其它regexes。
+每个 _regex_compiler_ 实例会持有一份从名字到它所创建的regexes的映射。
You can create a named dynamic regex by prefacing your regex with
`"(?$name=)"`, where
/name/ is the name of the regex. You can refer to a named regex from
another regex with
`"(?$name)"`. The named regex does not need to exist yet at the time it is
referenced
-in another regex, but it must exist by the time you use the regex.
+in another regex, but it must exist by the time you use the regex.\n
+你可以通过在regex前加上 `"(?$name=)"` 来创建一个命名的动态regex，其中
/name/ 是这个regex的名字。
+你可以用 `"(?$name)"` 来从其它regex引用已命名的regex。在
+被引用至其它regex之时，命名的regex并不需要已经存在，但是在使用该regex时，它
必须是存在的。
Below is a code fragment that uses dynamic regex grammars to implement the
calculator
-example from above.
+example from above.\n
+以下是一段使用动态regex语法来实现以上计算器例子的代码片断。
using namespace boost::xpressive;
using namespace regex_constants;
@@ -167,29 +208,41 @@
As with static regex grammars, nested regex invocations create nested
match results (see /Nested Results/ below). The result is a complete parse
tree
for string that matched. Unlike static regexes, dynamic regexes are always
-embedded by reference, not by value.
-
-[h2 Cyclic Patterns, Copying and Memory Management, Oh My!]
+embedded by reference, not by value.\n
+和静态regex语法一样，嵌套的regex调用创建嵌套的匹配结果(见后文的 /嵌套结果
/)。
+该结果是一个针对被匹配字符串的完整的语法分析树。和静态regexes不同，动态
regexes总是以引用方式嵌入，不使用值方式。
+
+[h2 Cyclic Patterns, Copying and Memory Management, Oh My! 循环的模式，复制
和内存管理，哦！]
The calculator examples above raises a number of very complicated
memory-management issues. Each of the
four regex objects refer to each other, some directly and some indirectly,
some by value and some by
reference. What if we were to return one of them from a function and let
the others go out of scope?
What becomes of the references? The answer is that the regex objects are
internally reference counted,
such that they keep their referenced regex objects alive as long as they
need them. So passing a regex
-object by value is never a problem, even if it refers to other regex
objects that have gone out of scope.
+object by value is never a problem, even if it refers to other regex
objects that have gone out of scope.\n
+以上的计算器例子引起了许多非常复杂的内存管理问题。上面这四个regex对象中的每
一个都引用了另外的regex，有直接的也有间接的，
+有值方式的也有引用方式的。如果我们从一个函数返回了一个这样的regex，又让另一
个被引用的regex离开了作用域，会怎么样呢？
+答案是，regex对象在内部采用了引用计数，这样它们可以按需要保持它们所引用的
regex对象的生存期。
+因此，以值方式传递一个regex对象不会有问题，即使它所引用的其它regex 对象已经
超出了作用域。
Those of you who have dealt with reference counting are probably familiar
with its Achilles Heel: cyclic
references. If regex objects are reference counted, what happens to cycles
like the one created in the
calculator examples? Are they leaked? The answer is no, they are not
leaked. The _basic_regex_ object has some tricky
reference tracking code that ensures that even cyclic regex grammars are
cleaned up when the last external
reference goes away. So don't worry about it. Create cyclic grammars, pass
your regex objects around and
-copy them all you want. It is fast and efficient and guaranteed not to
leak or result in dangling references.
-
-[h2 Nested Regexes and Sub-Match Scoping]
+copy them all you want. It is fast and efficient and guaranteed not to
leak or result in dangling references.\n
+你们当中曾经用过引用计数的人，可能会很熟悉它的致命弱点：循环引用。
+如果regex对象是引用计数的，对于前面的计算器例子中所创建的循环regex会发生什
么？它们会泄露吗？答案是不会的，它们不会泄露。
+_basic_regex_ 对象有一些特殊的引用跟踪代码来确保当最后一个外部引用消失
时，即使是循环的regex语法也会清理干净。所以不需要担心它。
+放心地按你所想的创建循环语法，传递regex对象和复制它们吧。这些是快速和高效
的，并且保证不会泄露或引起悬空的引用。
+
+[h2 Nested Regexes and Sub-Match Scoping 嵌套Regex和子匹配域]
Nested regular expressions raise the issue of sub-match scoping. If both
the inner and outer regex write
to and read from the same sub-match vector, chaos would ensue. The inner
regex would stomp on the
-sub-matches written by the outer regex. For example, what does this do?
+sub-matches written by the outer regex. For example, what does this do?\n
+嵌套的正则表达式带来了子匹配域的问题。如果内层的regex和外层的regex都要写出
到或读入自同一个子匹配向量，混乱就会发生。
+内层的regex将破坏由外层regex写出的子匹配。例如，以下例子会做些什么？
sregex inner = sregex::compile( "(.)\\1" );
sregex outer = (s1= _) >> inner >> s1;
@@ -197,23 +250,32 @@
The author probably didn't intend for the inner regex to overwrite the
sub-match written by the outer
regex. The problem is particularly acute when the inner regex is accepted
from the user as input. The
author has no way of knowing whether the inner regex will stomp the
sub-match vector or not. This is
-clearly not acceptable.
+clearly not acceptable.\n
+作者可能并不是想要内层的regex覆写由外层regex所写出的子匹配。当内层的regex是
由用户输入时，这个问题尤其严重。
+作者没有办法知道内层的 regex是否会破坏子匹配向量。这显然是不可接受的。
Instead, what actually happens is that each invocation of a nested regex
gets its own scope. Sub-matches
belong to that scope. That is, each nested regex invocation gets its own
copy of the sub-match vector to
play with, so there is no way for an inner regex to stomp on the
sub-matches of an outer regex. So, for
-example, the regex `outer` defined above would match `"ABBA"`, as it
should.
-
-[h2 Nested Results]
+example, the regex `outer` defined above would match `"ABBA"`, as it
should.\n
+相反，实际情况是，嵌套regex的每次调用会得到它自己的作用域。子匹配属于该作用
域。
+即，每次嵌套regex的调用会得到它自己的子匹配向量拷贝用以操作，所以内层
regex是没有办法破坏外层regex的子匹配的。
+例如，以上所定义的regex `outer` 会匹配 `"ABBA"`，如其所愿。
+
+[h2 Nested Results 嵌套结果]
If nested regexes have their own sub-matches, there should be a way to
access them after a successful
match. In fact, there is. After a _regex_match_ or _regex_search_, the
_match_results_ struct behaves
like the head of a tree of nested results. The _match_results_ class
provides a `nested_results()`
member function that returns an ordered sequence of _match_results_
structures, representing the
results of the nested regexes. The order of the nested results is the same
as the order in which
-the nested regex objects matched.
-
-Take as an example the regex for balanced, nested parentheses we saw
earlier:
+the nested regex objects matched.\n
+如果嵌套regexes具有它们自己的子匹配，那么就应试有方法在成功匹配后访问它们。
事实上，确实有。在 _regex_match_ 或 _regex_search_
+之后，结构 _match_results_ 的行为类似于嵌套结果树的头部。_match_results_ 类
提供了一个 `nested_results()` 成员函数，它返回一个
+_match_results_ 结构的已排序序列，表示嵌套regexes的结果。嵌套结果的顺序与嵌
套regex对象匹配的顺序相同。
+
+Take as an example the regex for balanced, nested parentheses we saw
earlier:\n
+以我们前面看到过的匹配成对的、嵌套的括号的regex为例：
sregex parentheses;
parentheses = '(' >> *( keep( +~(set='(',')') ) | by_ref(parentheses)
) >> ')';
@@ -233,7 +295,8 @@
output_nested_results() );
}
-This program displays the following:
+This program displays the following:\n
+程序输出如下：
[pre
( a(b)c (c(e)f (g)h )i (j)6 )
@@ -245,21 +308,28 @@
]
Here you can see how the results are nested and that they are stored in
the order in which they
-are found.
+are found.\n
+这里你可以看到这个结果是如何嵌套的，以及它们是按查找的顺序保存的。
[tip See the definition of [link
boost_xpressive.user_s_guide.examples.display_a_tree_of_nested_results
output_nested_results] in the
-[link boost_xpressive.user_s_guide.examples Examples] section.]
-
-[h2 Filtering Nested Results]
+[link boost_xpressive.user_s_guide.examples Examples] section.\n
+请见在 [link boost_xpressive.user_s_guide.examples 示例] 一节中的
+[link
boost_xpressive.user_s_guide.examples.display_a_tree_of_nested_results
output_nested_results] 定义。]
+
+[h2 Filtering Nested Results 过滤嵌套结果]
Sometimes a regex will have several nested regex objects, and you want to
know which result corresponds
to which regex object. That's where `basic_regex<>::regex_id()` and
`match_results<>::regex_id()`
come in handy. When iterating over the nested results, you can compare the
regex id from the results to
-the id of the regex object you're interested in.
+the id of the regex object you're interested in.\n
+有时一个regex有多个嵌套的regex对象，而且你想知道哪个结果对应哪个regex对象。
这时 `basic_regex<>::regex_id()` 和
+`match_results<>::regex_id()` 可以帮上忙。在对嵌套结果进行迭代时，你可以将
结果中的regex id与你所关心的regex对象的id进行比较。
To make this a bit easier, xpressive provides a predicate to make it
simple to iterate over just the
results that correspond to a certain nested regex. It is called
`regex_id_filter_predicate`, and it is
-intended to be used with _iterator_. You can use it as follows:
+intended to be used with _iterator_. You can use it as follows:\n
+为了让这容易一些，xpressive提供了一个谓词，可以很简单地对与特定的嵌套
regex相对应的结果进行迭代。
+这个谓词名为 `regex_id_filter_predicate`，其目的是与 _iterator_ 一起使用。
你可以这样来使用它：
sregex name = +alpha;
sregex integer = +_d;
@@ -297,7 +367,10 @@
where `output_results` is a simple function that takes a `smatch` and
displays the full match.
Notice how we use the `regex_id_filter_predicate` together with
`basic_regex<>::regex_id()` and
`boost::make_filter_iterator()` from the _iterator_ to select only those
results
-corresponding to a particular nested regex. This program displays the
following:
+corresponding to a particular nested regex. This program displays the
following:\n
+其中 `output_results` 是一个简单的函数，它接受一个 `smatch` 并打印全匹配。
留意我们是如何将 `regex_id_filter_predicate` 和
+`basic_regex<>::regex_id()` 以及 _iterator_ 的
`boost::make_filter_iterator()` 一起使用，来选出仅与特定的嵌套regex相对应的
结果。
+程序的输出如下：
[pre
marsha
=======================================
--- /trunk/libs/xpressive/doc/history.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/history.qbk Sun Aug 1 20:47:57 2010
@@ -5,89 +5,122 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Appendix 1: History]
+[section:appendix_1__history Appendix 1: History 附录1：历史]
[h2 Version 2.1.0 6/12/2008]
-New Features:
+New Features:\n
+新特性：
* `skip()` primitive for static regexes, which allows you to specify parts
of
- the input string to ignore during regex matching.
-* Range-based `regex_replace()` algorithm interface.
+ the input string to ignore during regex matching.\n
+ 静态regex的 `skip()` 原语，允许你指定在regex匹配时忽略部分的输入串。
+* Range-based `regex_replace()` algorithm interface.\n
+ 基于区间的 `regex_replace()` 算法接口。
* `regex_replace()` accepts formatter objects and formatter lambda
expressions
- in addition to format strings.
-
-Bugs Fixed:
+ in addition to format strings.\n
+ 除了格式化串以外，`regex_replace()` 还接受格式化器对象和格式化器lambda表
达式。
+
+Bugs Fixed:\n
+缺陷修复：
* Semantic actions in look-aheads, look-behinds and independent
sub-expressions
- execute eagerly instead of causing a crash.
+ execute eagerly instead of causing a crash.\n
+ 在顺序环视、逆序环视中语义动作以及独立子表达式的执行不再导致崩溃。
[h2 Version 2.0.1 10/23/2007]
-Bugs Fixed:
-
-* `sub_match<>` constructor copies singular iterator causing debug assert.
+Bugs Fixed:\n
+缺陷修复：
+
+* `sub_match<>` constructor copies singular iterator causing debug
assert.\n
+ `sub_match<>` 构造函数复制单个迭代器导致调试断言。
[h2 Version 2.0.0, 10/12/2007]
-New Features:
-
-* Semantic actions
-* Custom assertions
-* Named captures
-* Dynamic regex grammars
-* Recursive dynamic regexes with [^(?R)] construct
-* Support for searching non-character data
-* Better errors for invalid static regexes
-* Range-based regex algorithm interface
+New Features:\n
+新特性：
+
+* Semantic actions\n
+ 语义动作
+* Custom assertions\n
+ 定制断言
+* Named captures\n
+ 命名捕获
+* Dynamic regex grammars\n
+ 动态regex语法
+* Recursive dynamic regexes with [^(?R)] construct\n
+ 带 [^(?R)] 结构的递归动态regex
+* Support for searching non-character data\n
+ 支持查找非字符数据
+* Better errors for invalid static regexes\n
+ 对于无效静态regex更好的错误提示
+* Range-based regex algorithm interface\n
+ 基于区间的regex算法接口
* `match_flag_type::format_perl`, `match_flag_type::format_sed`, and
`match_flag_type::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.
+* Version 2 regex traits get `tolower()` and `toupper()`\n
+ regex traits 版本2，带 `tolower()` 和 `toupper()`
+
+Bugs Fixed:\n
+缺陷修复：
+
+* Complementing single-character sets like `~(set='a')` works.\n
+ 单字符集合的取补，如 ~(set='a') 可用了。
[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.
+Bugs Fixed:\n
+缺陷修复：
+
+* Back-references greater than nine work as advertized.\n
+ 大于9个的后向引用可用。
+
+This is the version that shipped as part of Boost 1.34.\n
+这是作为 Boost 1.34 的组成部分交付的版本。
[h2 Version 1.0.1, October 2, 2006]
-Bugs Fixed:
-
-* `match_results::position()` works for nested results.
+Bugs Fixed:\n
+缺陷修复：
+
+* `match_results::position()` works for nested results.\n
+ `match_results::position()` 可用于嵌套结果。
[h2 Version 1.0.0, March 16, 2006]
-Version 1.0!
+Version 1.0!\n
+版本 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.
+2005. Xpressive was accepted into Boost on September 28, 2005.\n
+这个版本为进入 Boost 而进行审查。审查从 September 8, 2005 开始。Xpressive
在 September 28, 2005 被纳入 Boost。
[h2 Version 0.9.3, June 30, 2005]
-New Features:
-
-* TR1-style regex_traits interface
-* Speed enhancements
+New Features:\n
+新特性：
+
+* TR1-style regex_traits interface\n
+ TR1-风格的 regex_traits 接口
+* Speed enhancements\n
+ 速度提高
* `syntax_option_type::ignore_white_space`
[h2 Version 0.9.0, September 2, 2004]
-New Features:
-
-* It sort of works.
+New Features:\n
+新特性：
+
+* It sort of works.\n
+ 初期工作。
[h2 Version 0.0.1, November 16, 2003]
Announcement of xpressive:
-[@http://lists.boost.org/Archives/boost/2003/11/56312.php]
+[@http://lists.boost.org/Archives/boost/2003/11/56312.php]\n
+xpressive 的声
明：[@http://lists.boost.org/Archives/boost/2003/11/56312.php]
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/installation.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/installation.qbk Sun Aug 1 20:47:57 2010
@@ -5,13 +5,15 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Installing xpressive]
-
-[h2 Getting xpressive]
+[section:installing_xpressive Installing xpressive 安装 xpressive]
+
+[h2 Getting xpressive 获得 xpressive]
There are three ways to get xpressive. The first and simplest is to
download
the latest version of Boost. Just go to [@http://sf.net/projects/boost] and
-follow the ["Download] link.
+follow the ["Download] link.\n
+有三种方法获得xpressive。第一种也是最简单的方法是，下载最新版本的Boost。
+访问 [@http://sf.net/projects/boost] 并点击 ["Download] 链接。
The second way is by downloading xpressive.zip at the
[@http://www.boost-consulting.com/vault/index.php?directory=Strings%20-%20Text%20Processing
@@ -20,31 +22,45 @@
documentation in PDF format. This version will always be stable and at
least as
current as the version in the latest Boost release. It may be more recent.
The
version in the File Vault is always guaranteed to work with the latest
official
-Boost release.
+Boost release.\n
+第二种方法是，在 ["Strings - Text Processing] 目录中下载位于
+[@http://www.boost-consulting.com/vault/index.php?directory=Strings%20-%20Text%20Processing
Boost
File Vault] 的 xpressive.zip。
+除了源代码和Boost许可证外，这个存档中还包含了本文档的一份PDF格式的拷贝。
+这个版本是稳定的，至少与最新的 Boost发布包中的版本一致。它有可能是更加新一
点的版本。
+在 File Vault 中的版本保证可以与最新的官方Boost发布包一起使用。
The third way is by directly accessing the Boost Subversion repository.
Just go to [@http://svn.boost.org/trac/boost/] and follow the instructions
there for
-anonymous Subversion access. The version in Boost Subversion is unstable.
-
-[h2 Building with xpressive]
+anonymous Subversion access. The version in Boost Subversion is unstable.\n
+第三种方法是，直接访问Boost Subversion库。只要去到
[@http://svn.boost.org/trac/boost/]
+并按照其中关于匿名访问 Subversion 的指令去做就可以了。Boost Subversion 中的
版本是不稳定的。
+
+[h2 Building with xpressive 用 xpressive 来构建]
Xpressive is a header-only template library, which means you don't need to
alter
your build scripts or link to any separate lib file to use it. All you
need to
do is `#include <boost/xpressive/xpressive.hpp>`. If you are only using
static
regexes, you can improve compile times by only including
`xpressive_static.hpp`.
Likewise, you can include `xpressive_dynamic.hpp` if you only plan on using
-dynamic regexes.
+dynamic regexes.\n
+Xpressive 是一个只含头文件的模板库，这意味着你不需要修改你的构建脚本或链接
任何独立的lib文件就可以使用它。
+你所要做的就是 `#include <boost/xpressive/xpressive.hpp>`。
+如果你只使用静态 regexes，你可以只包含 `xpressive_static.hpp` 以提高编译速
度。
+同样，如果你计划只使用动态regexes，则可以只包含 `xpressive_dynamic.hpp`。
If you would also like to use semantic actions or custom assertions with
your
-static regexes, you will need to additionally include `regex_actions.hpp`.
-
-[h2 Requirements]
-
-Xpressive requires Boost version 1.34.1 or higher.
-
-[h2 Supported Compilers]
-
-Currently, Boost.Xpressive is known to work on the following compilers:
+static regexes, you will need to additionally include
`regex_actions.hpp`.\n
+如果你还想在你的静态regexes中使用语义动作或定制化断言，你就需要另外包含
`regex_actions.hpp`。
+
+[h2 Requirements 要求]
+
+Xpressive requires Boost version 1.34.1 or higher.\n
+Xpressive 要求 Boost 1.34.1 或更高版本。
+
+[h2 Supported Compilers 支持的编译器]
+
+Currently, Boost.Xpressive is known to work on the following compilers:\n
+当前，Boost.Xpressive 已知可在以下编译器中使用：
* Visual C++ 7.1 and higher
* GNU C++ 3.4 and higher
@@ -59,9 +75,12 @@
Check the latest tests results at Boost's
[@http://beta.boost.org/development/tests/trunk/developer/xpressive.html
-Regression Results Page].
+Regression Results Page].\n
+最新的测试结果请查阅 Boost 的
[@http://beta.boost.org/development/tests/trunk/developer/xpressive.html 回
归测试结果页]。
[note Please send any questions, comments and bug reports to eric <at>
-boost-consulting <dot> com.]
+boost-consulting <dot> com.\n
+有任何问题、注解和缺陷报告，请发至 eric@xxxxxxxxxxxxxxxxxxxx。有任何问题、
注解和缺陷报告，请发至
+eric <at> boost-consulting <dot> com。]
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/introduction.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/introduction.qbk Sun Aug 1 20:47:57 2010
@@ -5,22 +5,29 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Introduction]
-
-[h2 What is xpressive?]
+[section:introduction Introduction 简介]
+
+[h2 What is xpressive? xpressive是什么？]
xpressive is a regular expression template library. Regular expressions
(regexes) can be written as strings that are parsed dynamically at runtime
(dynamic regexes), or as ['expression templates][footnote See
[@http://www.osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html
-Expression Templates]] that are parsed at compile-time (static regexes).
+Expression Templates] 参见
[@http://www.osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html
+表达式模板]] that are parsed at compile-time (static regexes).
Dynamic regexes have the advantage that they can be accepted from the user
as input at runtime or read from an initialization file. Static regexes
have several advantages. Since they are C++ expressions instead of
strings, they can be syntax-checked at compile-time. Also, they can
naturally
refer to code and data elsewhere in your program, giving you the ability
to call
back into your code from within a regex match. Finally, since they are
statically
-bound, the compiler can generate faster code for static regexes.
+bound, the compiler can generate faster code for static regexes.\n
+xpressive 是一个正则表达式模板库。正则表达式(regexes)可以以字符串方式编写并
在运行期进行动态的分析(动态regexes)，
+又或者作为 ['表达式模板] 方式编写并在编译期进行分析(静态regexes)。
+动态regexes的优点在于，它们可以在运行期从用户的输入中获得，或者是从一个初始
化文件中读取。
+静态regexes也有多个好处。由于它们是C++表达式而不是字符串，所以它们可以在编
译期进行语法检查。
+同时，它们可以很自然地引用你的程序中任意地方的代码和数据，让你可以在正则表
达式匹配时回调你的代码。
+最后，由于它们是静态绑定的，所以编译器可以为静态regexes生成更快速的代码。
xpressive's dual nature is unique and powerful. Static xpressive is a bit
like the _spirit_fx_. Like _spirit_, you can build grammars with
@@ -32,11 +39,18 @@
dynamic regexes in the same program, and even in the same expression! You
can embed a dynamic regex in a static regex, or /vice versa/, and the
embedded
regex will participate fully in the search, back-tracking as needed to make
-the match succeed.
+the match succeed.\n
+xpressive的双重特点是独特且强大的。静态xpressive有点象 _spirit_fx_。
+和 _spirit_ 一样，你可以用表达式模板为静态regexes构建语法。
+(和 _spirit_ 不同的的，xpressive进行完全的回溯，尝试每一种可能性以找到与你
的模式相匹配的地方)。
+动态xpressive则有点象 _regexpp_。实际上，xpressive的接口对于使用过
_regexpp_ 的任何人都会很熟悉。
+xpressive的创新在于，它可以让你在同一个程序中混用和匹配静态和动态
regexes，甚至是在同一个表达式中！
+你可以在一个静态regex中嵌入一个动态regex，或/反之/，而且嵌入的regex也会完全
参与到为了匹配成功而所需的查找和回溯之中。
[h2 Hello, world!]
-Enough theory. Let's have a look at ['Hello World], xpressive style:
+Enough theory. Let's have a look at ['Hello World], xpressive style:\n
+理论知识已经够了。下面我们来看一个xpressive风格的 ['Hello World]：
#include <iostream>
#include <boost/xpressive/xpressive.hpp>
@@ -60,7 +74,8 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+该程序的输出如下：
[pre
hello world!
@@ -69,17 +84,23 @@
]
The first thing you'll notice about the code is that all the types in
xpressive live in
-the `boost::xpressive` namespace.
+the `boost::xpressive` namespace.\n
+关于这段代码，你应该留意到的第一件事是，xpressive中的所有类型均位于
`boost::xpressive` 名字空间中。
[note Most of the rest of the examples in this document will leave off the
-`using namespace boost::xpressive;` directive. Just pretend it's there.]
+`using namespace boost::xpressive;` directive. Just pretend it's there.\n
+本文档中的其它例子中，多数时候会省略 `using namespace boost::xpressive;` 指
令。你只要当它存在就行了。]
Next, you'll notice the type of the regular expression object is `sregex`.
If you are familiar
with _regexpp_, this is different than what you are used to. The "`s`"
in "`sregex`" stands for
"`string`", indicating that this regex can be used to find patterns in
`std::string` objects.
-I'll discuss this difference and its implications in detail later.
-
-Notice how the regex object is initialized:
+I'll discuss this difference and its implications in detail later.\n
+接着，你应该留意到，正则表达式对象的类型是 `sregex`。如果你熟悉
_regexpp_，就会发现这和以前用过的有所不同。
+"`sregex`" 中的 "`s`" 是代表 "`string`"，表示这个 regex 可被用于在
`std::string` 对象中查找模式。
+稍后我会详细讨论这些差别和它的含义。
+
+Notice how the regex object is initialized:\n
+注意regex对象是如何初始化的：
sregex rex = sregex::compile( "(\\w+) (\\w+)!" );
@@ -89,38 +110,52 @@
a regular expression as a kind of string on steroids. In xpressive,
regular expressions are not
strings; they are little programs in a domain-specific language. Strings
are only one ['representation]
of that language. Another representation is an expression template. For
example, the above line of code
-is equivalent to the following:
+is equivalent to the following:\n
+要从一个字符串创建正则表达式对象，你必须调用一个工厂方法，如
_regex_compile_。
+这是xpressive不同于其它面向对象的正则表达式库的另一个地方。其它的库鼓励你将
正则表达式想象为一种带类固醇的字符串。
+而在xpressive 中，正则表达式不是字符串；它们是一些用领域专用语言编写的小程
序。
+字符串只是这种语言的一种['表示法]。另一种表示法是表达式模板。例如，以上那行
代码等同于：
sregex rex = (s1= +_w) >> ' ' >> (s2= +_w) >> '!';
This describes the same regular expression, except it uses the
domain-specific embedded language
-defined by static xpressive.
+defined by static xpressive.\n
+这种写法定义了一个相同的正则表达式，除了它是用领域专用嵌入式语言来定义静态
xpressive。
As you can see, static regexes have a syntax that is noticeably different
than standard Perl
syntax. That is because we are constrained by C++'s syntax. The biggest
difference is the use
of `>>` to mean "followed by". For instance, in Perl you can just put
sub-expressions next
-to each other:
+to each other:\n
+正如你所见到的，静态regexes具有与标准的Perl语法明显不同的语法。这是因为我们
受到C++语法的约束。
+最大的不同是，使用 `>>` 来表示"后随"。例如，在Perl中你只需把子表达式一个接
一个地写出来：
abc
-But in C++, there must be an operator separating sub-expressions:
+But in C++, there must be an operator separating sub-expressions:\n
+但是在C++中，就必须要用一个操作符来分隔各个子表达式：
a >> b >> c
In Perl, parentheses `()` have special meaning. They group, but as a
side-effect they also create
back-references like [^$1] and [^$2]. In C++, there is no way to overload
parentheses to give them
side-effects. To get the same effect, we use the special `s1`, `s2`, etc.
tokens. Assign to
-one to create a back-reference (known as a sub-match in xpressive).
+one to create a back-reference (known as a sub-match in xpressive).\n
+在Perl中，括号`()`具有特殊的意义。它们负责分组，但是有一个副作用，它们会同
时创建一些反向引用，如 [^$1] 和 [^$2]。
+在C++中，没有办法对括号操作符进行重载以给予它们这些副作用。为了得到相同的效
果，我们使用专用的记号，`s1`, `s2`, 等等。
+赋值给这样的记号就可以创建一个反向引用(在xpressive中称为子匹配)。
You'll also notice that the one-or-more repetition operator `+` has moved
from postfix
-to prefix position. That's because C++ doesn't have a postfix `+`
operator. So:
+to prefix position. That's because C++ doesn't have a postfix `+`
operator. So:\n
+你还应该留意到，一次或多次重复的操作符 `+` 从后缀变为前缀了。这是因为C++没
有后缀的 `+` 操作符。所以：
"\\w+"
-is the same as:
+is the same as:\n
+等同于：
+_w
-We'll cover all the other differences [link
boost_xpressive.user_s_guide.creating_a_regex_object.static_regexes later].
+We'll cover all the other differences [link
boost_xpressive.user_s_guide.creating_a_regex_object.static_regexes
later].\n
+[link boost_xpressive.user_s_guide.creating_a_regex_object.static_regexes
稍后] 我们将讨论其它的差异。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/matching.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/matching.qbk Sun Aug 1 20:47:57 2010
@@ -5,31 +5,41 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Matching and Searching]
-
-[h2 Overview]
+[section Matching and Searching 匹配与查找]
+
+[h2 Overview 概述]
Once you have created a regex object, you can use the _regex_match_ and
_regex_search_ algorithms to find patterns
in strings. This page covers the basics of regex matching and searching.
In all cases, if you are familiar with
-how _regex_match_ and _regex_search_ in the _regexpp_ library work,
xpressive's versions work the same way.
-
-[h2 Seeing if a String Matches a Regex]
-
-The _regex_match_ algorithm checks to see if a regex matches a given input.
+how _regex_match_ and _regex_search_ in the _regexpp_ library work,
xpressive's versions work the same way.\n
+一旦你创建了一个regex对象，你就可以用 _regex_match_ 和 _regex_search_ 算法
来在字符串中查找该模式。
+本节包括了regex匹配与查找的基础。在所有情况下，如果你对于在 Boost.Regex 库
中如何使用 _regex_match_
+和 _regex_search_ 是熟悉的，那么xpressive也是一样的用法。
+
+[h2 Seeing if a String Matches a Regex 查看一个字符串是否匹配一个Regex]
+
+The _regex_match_ algorithm checks to see if a regex matches a given
input.\n
+算法 _regex_match_ 检查一个regex是否匹配一个给定的输入。
[warning The _regex_match_ algorithm will only report success if the regex
matches the ['whole input],
from beginning to end. If the regex matches only a part of the input,
_regex_match_ will return false. If you
want to search through the string looking for sub-strings that the regex
matches, use the _regex_search_
-algorithm.]
+algorithm.\n
+算法 _regex_match_ 只报告一个regex是否匹配整个输入，从头到尾。如果regex只匹
配部分输入，则 _regex_match_ 将返回false。
+如果你要在字符串中查找与regex相匹配的子串，请用 regex_search() 算法。]
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
+type for your iterator.)\n
+输入可能是一个双向区间，如 `std::string`，或是一个C-风格的以空字符结束的字
符串，或是一对迭代器。
+在所有情况下，用于对输入序列进行遍历的迭代器类型必须与用于声明regex对象的迭
代器类型相匹配。
+(你可以用 [link
boost_xpressive.user_s_guide.quick_start.know_your_iterator_type 快速入门]
+一节中的表格来查找与你的迭代器相对应的正确regex类型)。
+
+ cregex cre = +_w; // this regex can match C-style strings 该regex可以
匹配C-风格的字符串
+ sregex sre = +_w; // this regex can match std::strings 该regex可以匹配
std::string
if( regex_match( "hello", cre ) ) // OK
{ /*...*/ }
@@ -37,17 +47,19 @@
if( regex_match( std::string("hello"), sre ) ) // OK
{ /*...*/ }
- if( regex_match( "hello", sre ) ) // ERROR! iterator
mis-match!
+ if( regex_match( "hello", sre ) ) // ERROR! iterator
mis-match! 错误！迭代器不匹配！
{ /*...*/ }
The _regex_match_ algorithm optionally accepts a _match_results_ struct as
an out parameter. If given, the _regex_match_
algorithm fills in the _match_results_ struct with information about which
parts of the regex matched which
-parts of the input.
+parts of the input.\n
+算法 _regex_match_ 选择性地接受一个 _match_results_ 结构作为输出参数。
+如果给出该参数，则 _regex_match_ 算法将与哪部分regex匹配哪部分输入的信息填
入 _match_results_ 结构。
cmatch what;
cregex cre = +(s1= _w);
- // store the results of the regex_match in "what"
+ // store the results of the regex_match in "what" 保存regex_match的结果
到"what"中
if( regex_match( "hello", what, cre ) )
{
std::cout << what[1] << '\n'; // prints "o"
@@ -55,35 +67,48 @@
The _regex_match_ algorithm also optionally accepts a _match_flag_type_
bitmask. With _match_flag_type_, you can
control certain aspects of how the match is evaluated. See the
_match_flag_type_ reference for a complete list
-of the flags and their meanings.
+of the flags and their meanings.\n
+算法 _regex_match_ 还选择性地接受一个 _match_flag_type_ 位掩码。通过
_match_flag_type_，你可以控制匹配如何执行的各个方面。
+相关标志位的完整列表及其含义，请看 _match_flag_type_ 参考。
std::string str("hello");
sregex sre = bol >> +_w;
// match_not_bol means that "bol" should not match at [begin,begin)
+ // match_not_bol 表示 "bol" 并不匹配于 [begin,begin)
if( regex_match( str.begin(), str.end(), sre,
regex_constants::match_not_bol ) )
{
- // should never get here!!!
+ // 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.
-
-[h2 Searching for Matching Sub-Strings]
+of the available overloads.\n
+[link
boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex
这里]
+有一个完整的示例程序，示范如何使用 _regex_match_。查看 _regex_match_ 参考可
以看到其它重载的完整列表。
+
+[h2 Searching for Matching Sub-Strings 匹配子串的查找]
Use _regex_search_ when you want to know if an input sequence contains a
sub-sequence that a regex matches.
_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.
+sequence until it either finds a match or exhausts the sequence.\n
+当你想知道一个输入序列是否包含一个匹配regex的子序列时，使用
_regex_search_。
+_regex_search_ 将尝试在输入序列的开始匹配regex，并向前扫描，直至找到一个匹
配或扫描完整个序列。
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.
+of the search, and a _match_flag_type_ bitmask to control how the match is
evaluated.\n
+在所有其它方面，_regex_search_ 的行为类似于 _regex_match_ ['(见上)]。特别
地，它可以在一个双向区间，如 `std::string`，
+或是一个C-风格的以空字符结束的字符串，或是一对迭代器上操作。同样也是注意确
保你的regex的迭代器类型与输入序列的迭代器类型相匹配。
+和 _regex_match_ 一样，你可以选择性地提供一个 _match_results_ 结构来接收查
找结果，以及提供一个 _match_flag_type_
+位掩码来控制如何进行匹配。
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.
+see a complete list of the available overloads.\n
+[link
boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex
这里]
+有一个完整的示例程序，示范如何使用 _regex_search_。查看 _regex_search_ 参考
可以看到其它重载的完整列表。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/named_captures.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/named_captures.qbk Sun Aug 1 20:47:57 2010
@@ -5,39 +5,48 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Named Captures]
-
-[h2 Overview]
+[section:named_captures Named Captures 命名捕获]
+
+[h2 Overview 概述]
For complicated regular expressions, dealing with numbered captures can be
a
pain. Counting left parentheses to figure out which capture to reference is
no fun. Less fun is the fact that merely editing a regular expression could
cause a capture to be assigned a new number, invaliding code that refers
back
-to it by the old number.
+to it by the old number.\n
+对于复杂的正则表达式，处理编号的捕获会是一种痛苦。计算左括号的数量来确定引
用的是哪个捕获，这并不好玩。
+更不好玩的是，稍微修改一下正则表达式，就可能会导致某个捕获被赋予新的编
号，而令以旧编号来引用它的代码失效。
Other regular expression engines solve this problem with a feature called
/named captures/. This feature allows you to assign a name to a capture,
and
to refer back to the capture by name rather by number. Xpressive also
supports
-named captures, both in dynamic and in static regexes.
-
-[h2 Dynamic Named Captures]
+named captures, both in dynamic and in static regexes.\n
+其它正则表达式引擎是以一种名为 /命名捕获/ 的特性来解决这个问题的。
+这种特性允许你对一个捕获赋予某个名字，而后以名字而非号码来引用该捕获。
Xpressive 也支持命名捕获，在动态和静态正则表达式中均支持。
+
+[h2 Dynamic Named Captures 动态的命名捕获]
For dynamic regular expressions, xpressive follows the lead of other
popular
regex engines with the syntax of named captures. You can create a named
capture
with `"(?P<xxx>...)"` and refer back to that capture with `"(?P=xxx)"`.
Here,
for instance, is a regular expression that creates a named capture and
refers
-back to it:
+back to it:\n
+对于动态的正则表达式，xpressive 参照了其它具有命名捕获语法的正则表达式引
擎。你可以用 `"(?P<xxx>...)"`
+创建一个命名捕获，而后用 `"(?P=xxx)"` 引用该捕获。例如，以下是一个创建了命
名捕获并后向引用它的正则表达式：
// Create a named capture called "char" that matches a single
// character and refer back to that capture by name.
+ // 创建一个名为"char"的命名捕获，匹配单个字符，并通过名字引用该捕获
sregex rx = sregex::compile("(?P<char>.)(?P=char)");
The effect of the above regular expression is to find the first doubled
-character.
+character.\n
+以上正则表达式的作用是找出第一个连续重复的字符。
Once you have executed a match or search operation using a regex with named
captures, you can access the named capture through the _match_results_
object
-using the capture's name.
+using the capture's name.\n
+一旦你用一个带有命名捕获的regex执行一次匹配或搜索操作，你就可以通过
_match_results_ 对象用捕获名来访问这个命名捕获。
std::string str("tweet");
sregex rx = sregex::compile("(?P<char>.)(?P=char)");
@@ -47,7 +56,8 @@
std::cout << "char = " << what["char"] << std::endl;
}
-The above code displays:
+The above code displays:\n
+以上代码输出：
[pre
char = e
@@ -55,7 +65,8 @@
You can also refer back to a named capture from within a substitution
string.
The syntax for that is `"\\g<xxx>"`. Below is some code that demonstrates
how
-to use named captures when doing string substitution.
+to use named captures when doing string substitution.\n
+你也可以从一个替换子串内部引用命名捕获。语法是 `"\\g<xxx>"`。以下是一段代
码，示范了如何在进行字符串替换时使用命名捕获。
std::string str("tweet");
sregex rx = sregex::compile("(?P<char>.)(?P=char)");
@@ -63,26 +74,31 @@
std::cout << str << std::endl;
Notice that you have to specify `format_perl` when using named captures.
Only
-the perl syntax recognizes the `"\\g<xxx>"` syntax. The above code
displays:
+the perl syntax recognizes the `"\\g<xxx>"` syntax. The above code
displays:\n
+注意，在使用命名捕获时，你必须指定 `format_perl`。只有perl语法能识别
`"\\g<xxx>"` 语法。以上代码输出：
[pre
tw\*\*e\*\*t
]
-[h2 Static Named Captures]
+[h2 Static Named Captures 静态命名捕获]
If you're using static regular expressions, creating and using named
captures is even easier. You can use the _mark_tag_ type to create
a variable that you can use like [globalref boost::xpressive::s1 `s1`],
[globalref boost::xpressive::s1 `s2`] and friends, but with a name
that is more meaningful. Below is how the above example would look
-using static regexes:
+using static regexes:\n
+如果你使用的是静态正则表达式，那么创建和使用命名捕获就更容易了。你可以用
_mark_tag_ 类型来创建一个可以象
+[globalref boost::xpressive::s1 `s1`], [globalref boost::xpressive::s1
`s2`] 等那样使用的变量，但变量的名字更有意义。
+以下是上一个例子的静态regex版本：
mark_tag char_(1); // char_ is now a synonym for s1
sregex rx = (char_= _) >> char_;
After a match operation, you can use the `mark_tag` to index into the
-_match_results_ to access the named capture:
+_match_results_ to access the named capture:\n
+在匹配操作之后，你可以用 `mark_tag` 来作为 _match_results_ 的索引，以访问命
名捕获：
std::string str("tweet");
mark_tag char_(1);
@@ -93,14 +109,16 @@
std::cout << what[char_] << std::endl;
}
-The above code displays:
+The above code displays:\n
+以上代码输出：
[pre
char = e
]
When doing string substitutions with _regex_replace_, you can use named
-captures to create /format expressions/ as below:
+captures to create /format expressions/ as below:\n
+在用 _regex_replace_ 进行字符串替换时，你可以用命名捕获来创建如下 /格式表达
式/：
std::string str("tweet");
mark_tag char_(1);
@@ -108,13 +126,15 @@
str = regex_replace(str, rx, "**" + char_ + "**");
std::cout << str << std::endl;
-The above code displays:
+The above code displays:\n
+以上代码输出：
[pre
tw\*\*e\*\*t
]
[note You need to include [^<boost/xpressive/regex_actions.hpp>] to
-use format expressions.]
+use format expressions.\n
+要使用格式表达式，你需要包含 [^<boost/xpressive/regex_actions.hpp>] 。]
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/nyi.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/nyi.qbk Sun Aug 1 20:47:57 2010
@@ -5,24 +5,34 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Appendix 2: Not Yet Implemented]
-
-The following features are planned for xpressive 2.X:
+[section:appendix_2__not_yet_implemented Appendix 2: Not Yet Implemented 附
录2：尚未实现的]
+
+The following features are planned for xpressive 2.X:\n
+以下特性计划在 xpressive 2.X 实现：
* `syntax_option_type::collate`
-* Collation sequences such as [^'''[.a.]''']
-* Equivalence classes like [^'''[=a=]''']
+* Collation sequences such as [^'''[.a.]''']\n
+ 校对序列，如 [^'''[.a.]''']
+* Equivalence classes like [^'''[=a=]''']\n
+ 等价类，如 [^'''[=a=]''']
* Control of nested results generation with `syntax_option_type::nosubs`,
- and a `nosubs()` modifier for static xpressive.
+ and a `nosubs()` modifier for static xpressive.\n
+ 用 `syntax_option_type::nosubs` 控制嵌套结果的生成，以及静态xpressive的
`nosubs()` 修饰符。
Here are some wish-list features. You or your company should
-consider hiring me to implement them!
-
-* Optimized DFA back-end for simple, fast regexing.
+consider hiring me to implement them!\n
+以下是一些希望增加的特性列表。你或你的公司应该考虑雇用我来实现它们！
+
+* Optimized DFA back-end for simple, fast regexing.\n
+ 优化的DFA后端，为了简单、快速的regexing。
* Different regex compiler front ends for basic, extended, awk, grep
- and egrep regex syntax.
-* Fine-grained control over the dynamic regex syntax
-* Optional integration with ICU for full Unicode support.
-* Improved localization support, possibly as a custom facet for
`std::locale`.
+ and egrep regex syntax.\n
+ 用于基本的、扩展的、awk、grep 和 egrep regex 语法的不同的regex编译器前
端。
+* Fine-grained control over the dynamic regex syntax\n
+ 对动态regex语法的细粒度控制
+* Optional integration with ICU for full Unicode support.\n
+ 与ICU的可选集成，以全面支持Unicode。
+* Improved localization support, possibly as a custom facet for
`std::locale`.\n
+ 改进本地化支持，如对 `std::locale` 的一个定制 facet。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/perf.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/perf.qbk Sun Aug 1 20:47:57 2010
@@ -5,29 +5,34 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:perf Appendix 4: Performance Comparison]
+[section:perf Appendix 4: Performance Comparison 附录4：性能比较]
The performance of xpressive is competitive with _regexpp_. I have run
performance
benchmarks comparing static xpressive, dynamic xpressive and _regexpp_ on
two platforms:
gcc (Cygwin) and Visual C++. The tests include short matches and long
searches. For both
platforms, xpressive comes off well on short matches and roughly on par
with _regexpp_ on
-long searches.
+long searches.\n
+xpressive 的性能可以与 _regexpp_ 相比。我在两个平台上运行了性能测试，比较了
静态xpressive、动态xpressive 和 _regexpp_：gcc (Cygwin)
+和 Visual C++。测试包括了短匹配和长查找。在两个平台上，xpressive都在短匹配
上胜出，而在长查找中则大致与 _regexpp_ 相同。
<disclaimer>
As with all benchmarks,
the true test is how xpressive performs with ['your] patterns, ['your]
input, and ['your]
platform, so if performance matters in your application, it's best to run
your own tests.
-</disclaimer>
+</disclaimer>\n
+<disclaimer> 和所有基准测试一样，真实的测试视乎xpressive如何执行['你的]模
式，['你的]输入，和['你的]平台，
+所以，如果性能对于你的应用是至关重要的，最好能运行你自己的测试。
</disclaimer>
[section:perf_gcc xpressive vs. Boost.Regex with GCC (Cygwin)]
-Below are the results of a performance comparison between:
+Below are the results of a performance comparison between:\n
+以下是它们之间的性能比较结果：
* static xpressive
* dynamic xpressive
* _regexpp_
-[variablelist Test Specifications
+[variablelist Test Specifications 测试规范
[[Hardware:] [hyper-threaded 3GHz Xeon with 1Gb RAM]]
[[Operating System:] [Windows XP Pro + Cygwin]]
[[Compiler:] [GNU C++ version 3.4.4 (Cygwin special)]]
@@ -36,34 +41,40 @@
[[xpressive Version:] [0.9.6a]]
]
-[h2 Comparison 1: Short Matches]
+[h2 Comparison 1: Short Matches 比较1：短匹配]
The following tests evaluate the time taken to match the expression to the
input string.
For each result, the top number has been normalized relative to the
fastest time, so 1.0
is as good as it gets. The bottom number (in parentheses) is the actual
time in seconds.
-The best time has been marked in green.
+The best time has been marked in green.\n
+以下测试评估了将正则表达式与输入串进行匹配所花的时间。对于每一个结果，上面
的数字已相对于最快时间进行了规范化，所以1.0是最好的。
+底下的数字(括号上的)是以秒计的实际时间。最佳时间以绿色标出。
[xinclude ../perf/gcc/short_matches.xml]
-[h2 Comparison 2: Long Searches]
+[h2 Comparison 2: Long Searches 比较2：长查找]
The next test measures the time to find ['all] matches in a long English
text. The text is the
[@http://www.gutenberg.org/dirs/3/2/0/3200/3200.zip complete works of Mark
Twain],
from [@http://promo.net/pg/ Project Gutenberg]. The text is 19Mb long. As
above, the top number
-is the normalized time and the bottom number is the actual time. The best
time is in green.
+is the normalized time and the bottom number is the actual time. The best
time is in green.\n
+下一个测试计量在一篇较长的英文中找出['所有]匹配所花的时间。文章是
+[@http://www.gutenberg.org/dirs/3/2/0/3200/3200.zip complete works of Mark
Twain]，来自 [@http://promo.net/pg/ Project Gutenberg]。
+该文章长度为19Mb。同上，上面的数字是规范化的时间，底下的数字则是实际时间。
最佳时间为绿色。
[xinclude ../perf/gcc/long_twain_search.xml]
[endsect]
[section:perf_msvc xpressive vs. Boost.Regex with Visual C++]
-Below are the results of a performance comparison between:
+Below are the results of a performance comparison between:\n
+以下是它们之间的性能比较结果：
* static xpressive
* dynamic xpressive
* _regexpp_
-[variablelist Test Specifications
+[variablelist Test Specifications 测试规范
[[Hardware:] [hyper-threaded 3GHz Xeon with 1Gb RAM]]
[[Operating System:] [Windows XP Pro]]
[[Compiler:] [Visual C++ .NET 2003 (7.1)]]
@@ -72,21 +83,26 @@
[[xpressive Version:] [0.9.6a]]
]
-[h2 Comparison 1: Short Matches]
+[h2 Comparison 1: Short Matches 比较1：短匹配]
The following tests evaluate the time taken to match the expression to the
input string.
For each result, the top number has been normalized relative to the
fastest time, so 1.0
is as good as it gets. The bottom number (in parentheses) is the actual
time in seconds.
-The best time has been marked in green.
+The best time has been marked in green.\n
+以下测试评估了将正则表达式与输入串进行匹配所花的时间。对于每一个结果，上面
的数字已相对于最快时间进行了规范化，所以1.0是最好的。
+底下的数字(括号上的)是以秒计的实际时间。最佳时间以绿色标出。
[xinclude ../perf/msvc/short_matches.xml]
-[h2 Comparison 2: Long Searches]
+[h2 Comparison 2: Long Searches 比较2：长查找]
The next test measures the time to find ['all] matches in a long English
text. The text is the
[@http://www.gutenberg.org/dirs/3/2/0/3200/3200.zip complete works of Mark
Twain],
from [@http://promo.net/pg/ Project Gutenberg]. The text is 19Mb long. As
above, the top number
-is the normalized time and the bottom number is the actual time. The best
time is in green.
+is the normalized time and the bottom number is the actual time. The best
time is in green.\n
+下一个测试计量在一篇较长的英文中找出['所有]匹配所花的时间。文章是
+[@http://www.gutenberg.org/dirs/3/2/0/3200/3200.zip complete works of Mark
Twain]，来自 [@http://promo.net/pg/ Project Gutenberg]。
+该文章长度为19Mb。同上，上面的数字是规范化的时间，底下的数字则是实际时间。
最佳时间为绿色。
[xinclude ../perf/msvc/long_twain_search.xml]
=======================================
--- /trunk/libs/xpressive/doc/preface.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/preface.qbk Sun Aug 1 20:47:57 2010
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Preface]
+[section:preface Preface 前言]
[:['Wife:] New Shimmer is a floor wax!\n
['Husband:] No, new Shimmer is a dessert topping!\n
@@ -16,15 +16,18 @@
['Announcer:] Hey, hey, hey, calm down, you two. New Shimmer is both a
floor wax ['and] a dessert topping!]
[:[*['-- Saturday Night Live]]]
-[h2 Description]
+[h2 Description 描述]
xpressive is an advanced, object-oriented regular expression template
library for C++.
Regular expressions can be written as strings that are parsed at run-time,
or as expression
templates that are parsed at compile-time. Regular expressions can refer
to each other and
to themselves recursively, allowing you to build arbitrarily complicated
grammars out of
-them.
-
-[h2 Motivation]
+them.\n
+xpressive 是一个先进的、面向对象的、用于C++的正则表达式模板库。
+正则表达式可以以字符串方式编写并在运行期分析，也可以以表达式模板方式编写并
在编译期分析。
+正则表达式可以相互引用，或者递归引用其本身，你就可以用它们来构建任意复杂的
语法。
+
+[h2 Motivation 动机]
If you need to manipulate text in C++, you have typically had two disjoint
options: a regular
expression engine or a parser generator. Regular expression engines (like
_regexpp_) are powerful
@@ -34,7 +37,12 @@
tasks have traditionally been handled by parser generators (like the
_spirit_fx_). These
beasts are more powerful but less flexible. They generally don't allow you
to arbitrarily modify
your grammar rules on the fly. In addition, they don't have the exhaustive
backtracking semantics
-of regular expressions, which can make it more challenging to author some
types of patterns.
+of regular expressions, which can make it more challenging to author some
types of patterns.\n
+如果你要在C++中处理文本，通常你有两个不相交的选项：正则表达式引擎或语法分析
生成器。
+正则表达式引擎(如 _regexpp_)更为强大和灵活；文本的模式以字符串方式表示，可
以在运行期指定。
+但是，这意味着语法错误同样要到运行期才能被检测。另外，正则表达式不适合于高
级的文本处理任务，如匹配平衡的、嵌套的标签。
+那些任务传统上都是由语法分析生成器(如 _spirit_fx_)来处理的。这些工具更为强
大，但不够灵活。
+它们通常不允许你随时随意地修改你的语法规则。此外，它们不具备正则表达式的完
全回溯语义，对于某些类型的模式来说，这样对作者更具有挑战性。
xpressive brings these two approaches seamlessly together and occupies a
unique niche in the
world of C++ text processing. With xpressive, you can choose to use it
much as you would use
@@ -44,9 +52,15 @@
both, writing regular expression ['grammars] in which some of the regular
expressions are
statically bound -- hard-coded and syntax\-checked by the compiler \-- and
others are dynamically
bound and specified at runtime. These regular expressions can refer to
each other recursively,
-matching patterns in strings that ordinary regular expressions cannot.
-
-[h2 Influences and Related Work]
+matching patterns in strings that ordinary regular expressions cannot.\n
+xpressive 将这两种方法无缝地集合到一起，在C++的文本处理世界中占据了独特的优
势。
+通过 xpressive，你可以选择更象使用 _regexpp_ 那样去使用它，将正则表达式表示
为字符串。
+或者你也可以象使用 _spirit_ 那样使用它，将你的 regexes 写为C++表达式，获得
一种专用于文本处理的嵌入式语言所带来的所有好处。
+更重要的是，你可以混用这两种方式，从而获得两者的好处，对于那些要静态绑定的
正则表达式编写正则表达式['语法] --
+由编译器进行硬编码和语法检查 -- 其它的则动态绑定并在运行期指定。
+这些正则表达式可以相互递归地引用，在以前的正则表达式不能进行模式匹配的字符
串中进行模式匹配。
+
+[h2 Influences and Related Work 影响和相关工作]
The design of xpressive's interface has been strongly influenced by John
Maddock's
_regexpp_ library and his _proposal_
@@ -54,6 +68,11 @@
inspiration from Joel de Guzman's _spirit_fx_, which served as the model
for static xpressive. Other sources of inspiration are the _perl6_
redesign and _greta_.
(You can read a summary of the changes Perl 6 will bring to regex culture
-[@http://dev.perl.org/perl6/doc/design/syn/S05.html here].)
+[@http://dev.perl.org/perl6/doc/design/syn/S05.html here].)\n
+xpressive 的接口设计受到 John Maddock 的 _regexpp_ 库和他的关于增加正则表达
式到标准库的 _proposal_ 的强烈影响。
+我还从 Joel de Guzman 的 _spirit_fx_ 获得大量灵感，该框架被用作静态
xpressive 的模型。
+其它的灵感来源还有 _perl6_ 的设计和 _greta_。(你可以在
[@http://dev.perl.org/perl6/doc/design/syn/S05.html 这里]
+看到关于 Perl 6 的变化所带来的 regex 文化的总结。)
+
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/quick_start.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/quick_start.qbk Sun Aug 1 20:47:57 2010
@@ -5,34 +5,60 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Quick Start]
+[section:quick_start Quick Start 快速入门]
You don't need to know much to start being productive with xpressive.
Let's begin with
-the nickel tour of the types and algorithms xpressive provides.
-
-[table xpressive's Tool-Box
- [[Tool] [Description]]
- [[_basic_regex_] [Contains a compiled regular
expression. _basic_regex_ is the most important type in xpressive.
Everything you do with xpressive will begin with creating an object of type
_basic_regex_.]]
- [[_match_results_, _sub_match_] [_match_results_ contains the
results of a _regex_match_ or _regex_search_ operation. It acts like a
vector of _sub_match_ objects. A _sub_match_ object contains a marked
sub-expression (also known as a back-reference in Perl). It is basically
just a pair of iterators representing the begin and end of the marked
sub-expression.]]
- [[_regex_match_] [Checks to see if a string matches
a regex. For _regex_match_ to succeed, the ['whole string] must match the
regex, from beginning to end. If you give _regex_match_ a _match_results_,
it will write into it any marked sub-expressions it finds.]]
- [[_regex_search_] [Searches a string to find a
sub-string that matches the regex. _regex_search_ will try to find a match
at every position in the string, starting at the beginning, and stopping
when it finds a match or when the string is exhausted. As with
_regex_match_, if you give _regex_search_ a _match_results_, it will write
into it any marked sub-expressions it finds.]]
- [[_regex_replace_] [Given an input string, a regex,
and a substitution string, _regex_replace_ builds a new string by replacing
those parts of the input string that match the regex with the substitution
string. The substitution string can contain references to marked
sub-expressions.]]
- [[_regex_iterator_] [An STL-compatible iterator that
makes it easy to find all the places in a string that match a regex.
Dereferencing a _regex_iterator_ returns a _match_results_. Incrementing a
_regex_iterator_ finds the next match.]]
- [[_regex_token_iterator_] [Like _regex_iterator_, except
dereferencing a _regex_token_iterator_ returns a string. By default, it
will return the whole sub-string that the regex matched, but it can be
configured to return any or all of the marked sub-expressions one at a
time, or even the parts of the string that ['didn't] match the regex.]]
- [[_regex_compiler_] [A factory for _basic_regex_
objects. It "compiles" a string into a regular expression. You will not
usually have to deal directly with _regex_compiler_ because the
_basic_regex_ class has a factory method that uses _regex_compiler_
internally. But if you need to do anything fancy like create a
_basic_regex_ object with a different `std::locale`, you will need to use a
_regex_compiler_ explicitly.]]
+the nickel tour of the types and algorithms xpressive provides.\n
+要开始使用xpressive，你并不需要知道得太多。让我们来从xpressive所提供的类型
和算法开始来一次简易的浏览。
+
+[table xpressive's Tool-Box xpressive的工具箱
+ [[Tool 工具] [Description 说明]]
+ [[_basic_regex_] [Contains a compiled regular
expression. _basic_regex_ is the most important type in xpressive.
Everything you do with xpressive will begin with creating an object of type
_basic_regex_.\n
+ 含有一个已编译的正则表达式。_basic_regex_ 是xpressive之中最重要的类型。
+ 你用xpressive做的任何事情都要从创建一个类型为 _basic_regex_ 的对象开
始。]]
+ [[_match_results_, _sub_match_] [_match_results_ contains the
results of a _regex_match_ or _regex_search_ operation. It acts like a
vector of _sub_match_ objects. A _sub_match_ object contains a marked
sub-expression (also known as a back-reference in Perl). It is basically
just a pair of iterators representing the begin and end of the marked
sub-expression.\n
+ _match_results_ 含有 _regex_match_ 或 _regex_search_ 操作的结果。它就象
一个存有 _sub_match_ 对象的向量。
+ 一个 _sub_match_ 对象含有一个已标记的子表达式(在Perl中又称为后向引用)。
+ 基本上，它只是一个迭代器对，代表了已标记子表达式的开始和结束。]]
+ [[_regex_match_] [Checks to see if a string matches
a regex. For _regex_match_ to succeed, the ['whole string] must match the
regex, from beginning to end. If you give _regex_match_ a _match_results_,
it will write into it any marked sub-expressions it finds.\n
+ 检查一个字符串是否匹配一个regex。_regex_match_ 要成功，必须是['整个字符
串]从头到尾匹配regex。
+ 如果你给了 _regex_match_ 一个 _match_results_，那么它会将所有找到的带标
记子表达式写入其中。]]
+ [[_regex_search_] [Searches a string to find a
sub-string that matches the regex. _regex_search_ will try to find a match
at every position in the string, starting at the beginning, and stopping
when it finds a match or when the string is exhausted. As with
_regex_match_, if you give _regex_search_ a _match_results_, it will write
into it any marked sub-expressions it finds.\n
+ 查找一个字符串，以发现其中匹配regex的子字符串。_regex_search_ 将尝试在
字符串的每个位置查找匹配，从头部开始，
+ 当找到一个匹配或者整个字符串找完时停止。使用 _regex_match_ 时，如果你给
了 _regex_search_ 一个 _match_results_，
+ 那么它会将所有找到的带标记子表达式写入其中。]]
+ [[_regex_replace_] [Given an input string, a regex,
and a substitution string, _regex_replace_ builds a new string by replacing
those parts of the input string that match the regex with the substitution
string. The substitution string can contain references to marked
sub-expressions.\n
+ 给定一个输入字符串，一个regex和一个替代字符串，_regex_replace_ 通过将输
入字符串中与 regex
+ 相匹配的部分替换为替代字符串来构建一个新的字符串。替代字符串可以含有对
带标记子表达式的引用。]]
+ [[_regex_iterator_] [An STL-compatible iterator that
makes it easy to find all the places in a string that match a regex.
Dereferencing a _regex_iterator_ returns a _match_results_. Incrementing a
_regex_iterator_ finds the next match.\n
+ 一个与STL兼容的迭代器，可以很方便地找到在一个字符串中与某个regex匹配的
所有地方。
+ 解引用一个 _regex_iterator_ 会返回一个 _match_results_。递增一个
_regex_iterator_ 可以找出下一个匹配。]]
+ [[_regex_token_iterator_] [Like _regex_iterator_, except
dereferencing a _regex_token_iterator_ returns a string. By default, it
will return the whole sub-string that the regex matched, but it can be
configured to return any or all of the marked sub-expressions one at a
time, or even the parts of the string that ['didn't] match the regex.\n
+ 类似于 _regex_iterator_，除了一点，解引用一个 _regex_token_iterator_ 会
返回一个字符串。
+ 缺省地，它返回与regex匹配的整个子字符串，不过它也可以被配置为每次返回任
一个或整个带标记子表达式，
+ 或者甚至是['不]匹配 regex的部分字符串。]]
+ [[_regex_compiler_] [A factory for _basic_regex_
objects. It "compiles" a string into a regular expression. You will not
usually have to deal directly with _regex_compiler_ because the
_basic_regex_ class has a factory method that uses _regex_compiler_
internally. But if you need to do anything fancy like create a
_basic_regex_ object with a different `std::locale`, you will need to use a
_regex_compiler_ explicitly.\n
+ 一个用于 _basic_regex_ 对象的工厂。它将一个字符串"编译"为正则表达式。
+ 通常，你不需要直接关心 _regex_compiler_，因为 _basic_regex_ 类有一个工
厂方法，其内部使用了 _regex_compiler_。
+ 不过，如果你需要做一些花哨的东西，如创建一个带有不同 std::locale 的
_basic_regex_ 对象，你就需要显式使用 _regex_compiler_ 了。]]
]
Now that you know a bit about the tools xpressive provides, you can pick
the right tool for you
-by answering the following two questions:
-
-# What ['iterator] type will you use to traverse your data?
-# What do you want to ['do] to your data?
-
-[h2 Know Your Iterator Type]
+by answering the following two questions:\n
+现在你应该对xpressive所提供的工具有了一些了解，你可以通过回答以下两个问题来
找到合适的工具：
+
+# What ['iterator] type will you use to traverse your data?\n
+ 你要用哪种类型的['迭代器]来遍历你的数据？
+# What do you want to ['do] to your data?\n
+ 你要对你的数据['做]什么操作？
+
+[h2 Know Your Iterator Type 弄明白你的迭代器类型]
Most of the classes in xpressive are templates that are parameterized on
the iterator type.
xpressive defines some common typedefs to make the job of choosing the
right types easier.
-You can use the table below to find the right types based on the type of
your iterator.
+You can use the table below to find the right types based on the type of
your iterator.\n
+在xpressive中的多数类都是根据迭代器类型参数化的模板类。xpressive定义了一些
常用的typedefs来让你可以更容易地选择合适的类型。
+你可以用下表基于你的迭代器类型来找到正确的类型。
[table xpressive Typedefs vs. Iterator Types
[[] [std::string::const_iterator] [char
const *] [std::wstring::const_iterator] [wchar_t const *]]
@@ -45,29 +71,35 @@
You should notice the systematic naming convention. Many of these types
are used together, so the
naming convention helps you to use them consistently. For instance, if you
have a `sregex`, you
-should also be using a `smatch`.
+should also be using a `smatch`.\n
+你要留意系统的命名习惯。这些类型经常要一起使用，所以命名习惯可以帮助你一致
地使用它们。
+例如，如果你有一个 `sregex`，你就应该使用 `smatch`。
If you are not using one of those four iterator types, then you can use
the templates directly and
-specify your iterator type.
-
-[h2 Know Your Task]
+specify your iterator type.\n
+如果你用的不是以上四种迭代器类型之一，那么你可以直接用模板并指定你的迭代器
类型。
+
+[h2 Know Your Task 弄明白你的任务]
Do you want to find a pattern once? Many times? Search and replace?
xpressive has tools for all
-that and more. Below is a quick reference:
-
-[table Tasks and Tools
- [[To do
this ...]
[Use this ...]]
- [[__tip__ [link
boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex
See if a whole string matches a
regex]]
[The _regex_match_ algorithm]]
- [[__tip__ [link
boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex
See if a string contains a sub-string that matches a
regex]] [The _regex_search_
algorithm]]
- [[__tip__ [link
boost_xpressive.user_s_guide.examples.replace_all_sub_strings_that_match_a_regex
Replace all sub-strings that match a
regex]]
[The _regex_replace_ algorithm]]
- [[__tip__ [link
boost_xpressive.user_s_guide.examples.find_all_the_sub_strings_that_match_a_regex_and_step_through_them_one_at_a_time
Find all the sub-strings that match a regex and step through them one at a
time]] [The _regex_iterator_ class]]
- [[__tip__ [link
boost_xpressive.user_s_guide.examples.split_a_string_into_tokens_that_each_match_a_regex
Split a string into tokens that each match a
regex]] [The
_regex_token_iterator_ class]]
- [[__tip__ [link
boost_xpressive.user_s_guide.examples.split_a_string_using_a_regex_as_a_delimiter
Split a string using a regex as a
delimiter]]
[The _regex_token_iterator_ class]]
+that and more. Below is a quick reference:\n
+你是不是只想找到一个模式一次？还是多次？是查找还是替换？xpressive 具有所有
这些工具，而且更多。以下是一个快速参考：
+
+[table Tasks and Tools 任务和工具
+ [[To do this ... 要做... ] [Use this ... 就用... ]]
+ [[__tip__ [link
boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex
See if a whole string matches a regex 判断整个字符串是否匹配一个regex]]
[The _regex_match_ algorithm]]
+ [[__tip__ [link
boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex
See if a string contains a sub-string that matches a regex 判断一个字符串是
否包含匹配某个regex的子串]] [The _regex_search_ algorithm]]
+ [[__tip__ [link
boost_xpressive.user_s_guide.examples.replace_all_sub_strings_that_match_a_regex
Replace all sub-strings that match a regex 替换所有匹配regex的子串]] [The
_regex_replace_ algorithm]]
+ [[__tip__ [link
boost_xpressive.user_s_guide.examples.find_all_the_sub_strings_that_match_a_regex_and_step_through_them_one_at_a_time
Find all the sub-strings that match a regex and step through them one at a
time 找到所有匹配regex的子串并逐个处理]] [The _regex_iterator_ class]]
+ [[__tip__ [link
boost_xpressive.user_s_guide.examples.split_a_string_into_tokens_that_each_match_a_regex
Split a string into tokens that each match a regex 将字符串分拆为记号，每个
匹配一个regex]] [The _regex_token_iterator_ class]]
+ [[__tip__ [link
boost_xpressive.user_s_guide.examples.split_a_string_using_a_regex_as_a_delimiter
Split a string using a regex as a delimiter 用regex作为分隔符分拆一个字符串
]] [The _regex_token_iterator_ class]]
]
-These algorithms and classes are described in excruciating detail in the
Reference section.
+These algorithms and classes are described in excruciating detail in the
Reference section.\n
+在参考手册一节中有这些算法和类的详细说明。
[tip Try clicking on a task in the table above to see a complete example
-program that uses xpressive to solve that particular task.]
+program that uses xpressive to solve that particular task.\n
+点击上表中的某个任务，可以看到一个完整的示例程序，使用xpressive来完成特定任
务。]
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/regexpp_diffs.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/regexpp_diffs.qbk Sun Aug 1 20:47:57 2010
@@ -5,39 +5,60 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Appendix 3: Differences from Boost.Regex]
+[section:appendix_3__differences_from_boost_regex Appendix 3: Differences
from Boost.Regex 附录3：与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
and _regexpp_. In particular:\n
-
-* `xpressive::basic_regex<>` is a template on the iterator type, not the
character type.
+由于xpressive的许多用户都很熟悉 _regexpp_ 库，如果我不指出 xpressive 和
_regexpp_ 之间的主要差异，将是失职的。特别是：\n
+
+* `xpressive::basic_regex<>` is a template on the iterator type, not the
character type.\n
+ `xpressive::basic_regex<>` 是基于迭代器类型而不是字符类型的模板。
* `xpressive::basic_regex<>` cannot be constructed directly from a string;
rather, you must use
- `basic_regex::compile()` or `regex_compiler<>` to build a regex object
from a string.
+ `basic_regex::compile()` or `regex_compiler<>` to build a regex object
from a string.\n
+ `xpressive::basic_regex<>` 不能直接从字符串构造；你必须使用
`basic_regex::compile()` 或 `regex_compiler<>` 来从字符串构造一个regex对象。
* `xpressive::basic_regex<>` does not have an `imbue()` member function;
rather, the `imbue()` member
- function is in the `xpressive::regex_compiler<>` factory.
+ function is in the `xpressive::regex_compiler<>` factory.\n
+ `xpressive::basic_regex<>` 没有 `imbue()` 成员函数；`imbue()` 成员函数是
在 `xpressive::regex_compiler<>` 工厂中的。
* `boost::basic_regex<>` has a subset of `std::basic_string<>`'s members.
`xpressive::basic_regex<>`
does not. The members lacking are: `assign()`, `operator[]()`,
`max_size()`, `begin()`, `end()`,
- `size()`, `compare()`, and `operator=(std::basic_string<>)`.
+ `size()`, `compare()`, and `operator=(std::basic_string<>)`.\n
+ `boost::basic_regex<>` 具有 `std::basic_string<>` 成员函数的一个子集。
`xpressive::basic_regex<>` 则没有。
+ 缺少的成员包括有：`assign()`, `operator[]()`, `max_size()`, `begin()`,
`end()`, `size()`, `compare()`,
+ 和 `operator=(std::basic_string<>)`.
* Other member functions that exist in `boost::basic_regex<>` but do not
exist in
`xpressive::basic_regex<>` are: `set_expression()`, `get_allocator()`,
`imbue()`, `getloc()`,
- `getflags()`, and `str()`.
+ `getflags()`, and `str()`.\n
+ 其它在 `boost::basic_regex<>` 中有而在 `xpressive::basic_regex<>` 中没有
的成员函数包括有：
+ `set_expression()`, `get_allocator()`, `imbue()`, `getloc()`,
`getflags()`, 和 `str()`.
* `xpressive::basic_regex<>` does not have a RegexTraits template
parameter. Customization of regex
syntax and localization behavior will be controlled by
`regex_compiler<>` and a custom regex facet
- for `std::locale`.
+ for `std::locale`.\n
+ `xpressive::basic_regex<>` 不带 RegexTraits 模板参数。对regex语法和本地化
行为的定制由 `regex_compiler<>`
+ 和为 `std::locale` 定制的 regex facet 来控制。
* `xpressive::basic_regex<>` and `xpressive::match_results<>` do not have
an Allocator template
- parameter. This is by design.
+ parameter. This is by design.\n
+ `xpressive::basic_regex<>` 和 `xpressive::match_results<>` 不带
Allocator 模板参数。这是设计的原因。
* `match_not_dot_null` and `match_not_dot_newline` have moved from the
`match_flag_type` enum to the
- `syntax_option_type` enum, and they have changed names to `not_dot_null`
and `not_dot_newline`.
+ `syntax_option_type` enum, and they have changed names to `not_dot_null`
and `not_dot_newline`.\n
+ `match_not_dot_null` 和 `match_not_dot_newline` 从 `match_flag_type`
enum 移至 `syntax_option_type` enum，并且改名为
+ `not_dot_null` 和 `not_dot_newline`.
* The following `syntax_option_type` enumeration values are not supported:
`escape_in_lists`,
`char_classes`, `intervals`, `limited_ops`, `newline_alt`, `bk_plus_qm`,
`bk_braces`, `bk_parens`,
`bk_refs`, `bk_vbar`, `use_except`, `failbit`, `literal`, `perlex`,
`basic`, `extended`, `emacs`,
+ `awk`, `grep` ,`egrep`, `sed`, `JavaScript`, `JScript`.\n
+ 以下 syntax_option_type 枚举值不被支持：`escape_in_lists`,
+ `char_classes`, `intervals`, `limited_ops`, `newline_alt`, `bk_plus_qm`,
`bk_braces`, `bk_parens`,
+ `bk_refs`, `bk_vbar`, `use_except`, `failbit`, `literal`, `perlex`,
`basic`, `extended`, `emacs`,
`awk`, `grep` ,`egrep`, `sed`, `JavaScript`, `JScript`.
* The following `match_flag_type` enumeration values are not supported:
`match_not_bob`,
+ `match_not_eob`, `match_perl`, `match_posix`, and `match_extra`.\n
+ 以下 match_flag_type 枚举值不被支持：`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.
+patterns that do not behave pathologically.\n
+还有，在当前的实现中，xpressive中的regex算法不检测反常行为，并以抛出异常的
方式退出。编写无反常行为的高效模式的责任在你。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/results.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/results.qbk Sun Aug 1 20:47:57 2010
@@ -5,45 +5,65 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Accessing Results]
-
-[h2 Overview]
+[section:accessing_results Accessing Results 访问结果]
+
+[h2 Overview 概述]
Sometimes, it is not enough to know simply whether a _regex_match_ or
_regex_search_ was successful or not. If
you pass an object of type _match_results_ to _regex_match_ or
_regex_search_, then after the algorithm has completed
successfully the _match_results_ will contain extra information about
which parts of the regex matched which parts
of the sequence. In Perl, these sub-sequences are called
['back-references], and they are stored in the variables
[^$1], [^$2], etc. In xpressive, they are objects of type _sub_match_, and
they are stored in the _match_results_
-structure, which acts as a vector of _sub_match_ objects.
+structure, which acts as a vector of _sub_match_ objects.\n
+有时，只知道一次 _regex_match_ 或 _regex_search_ 是否成功是不够的。
+如果你将一个 _match_results_ 对象传给 _regex_match_ 或 _regex_search_，那么
在算法成功完成后，这个
+_match_results_ 对象将含有额外的关于哪部分regex匹配到哪部分序列的信息。在
Perl中，这些子序列被称为['后向引用]，
+它们被保存在变量 [^$1], [^$2], 等等之中。在xpressive中，它们是类型为
_sub_match_ 的对象，被保存在 _match_results_
+结构中，该结构起到一个 _sub_match_ 对象向量的作用。
[h2 match_results]
So, you've passed a _match_results_ object to a regex algorithm, and the
algorithm has succeeded. Now you want
to examine the results. Most of what you'll be doing with the
_match_results_ object is indexing into it to access
its internally stored _sub_match_ objects, but there are a few other
things you can do with a _match_results_
-object besides.
-
-The table below shows how to access the information stored in a
_match_results_ object named `what`.
+object besides.\n
+好的，你已经传入一个 _match_results_ 对象给一个regex算法，并且该算法已经完
成了。现在你想检查一下结果。
+你要对 _match_results_ 对象所做的事情，主要就是按索引来访问它内部所保存的
_sub_match_ 对象，不过你还可以对
+_match_results_ 对象做一些其它事情。
+
+The table below shows how to access the information stored in a
_match_results_ object named `what`.\n
+下表列出了如何访问保存在一个名为 `what` 的 _match_results_ 对象中的信息的方
法。
[table match_results<> Accessors
[[Accessor] [Effects]]
- [[`what.size()`] [Returns the number of sub-matches, which is
always greater than zero after a successful match because the full match is
stored in the zero-th sub-match.]]
- [[`what[n]`] [Returns the ['n]-th sub-match.]]
- [[`what.length(n)`] [Returns the length of the ['n]-th sub-match.
Same as `what[n].length()`.]]
- [[`what.position(n)`] [Returns the offset into the input sequence at
which the ['n]-th sub-match begins.]]
- [[`what.str(n)`] [Returns a `std::basic_string<>` constructed
from the ['n]-th sub-match. Same as `what[n].str()`.]]
- [[`what.prefix()`] [Returns a _sub_match_ object which represents
the sub-sequence from the beginning of the input sequence to the start of
the full match.]]
- [[`what.suffix()`] [Returns a _sub_match_ object which represents
the sub-sequence from the end of the full match to the end of the input
sequence.]]
- [[`what.regex_id()`] [Returns the `regex_id` of the _basic_regex_
object that was last used with this _match_results_ object.]]
+ [[`what.size()`] [Returns the number of sub-matches, which is
always greater than zero after a successful match because the full match is
stored in the zero-th sub-match.\n
+ 返回子匹配的数量，匹配成功后该值总是大于零，因为全匹配会被保存在第零个
子匹配中。]]
+ [[`what[n]`] [Returns the ['n]-th sub-match.\n
+ 返回第['n]-个子匹配。]]
+ [[`what.length(n)`] [Returns the length of the ['n]-th sub-match.
Same as `what[n].length()`.\n
+ 返回第['n]-个子匹配的长度。与 `what[n].length()` 相同。]]
+ [[`what.position(n)`] [Returns the offset into the input sequence at
which the ['n]-th sub-match begins.\n
+ 返回第['n]-个子匹配的始端在输入序列中的偏移量。]]
+ [[`what.str(n)`] [Returns a `std::basic_string<>` constructed
from the ['n]-th sub-match. Same as `what[n].str()`.\n
+ 返回一个由第['n]-个子匹配构造的 `std::basic_string<>`。与
`what[n].str()` 相同。]]
+ [[`what.prefix()`] [Returns a _sub_match_ object which represents
the sub-sequence from the beginning of the input sequence to the start of
the full match.\n
+ 返回一个 _sub_match_ 对象，表示从输入序列的始端到全匹配的始端的一个子序
列。]]
+ [[`what.suffix()`] [Returns a _sub_match_ object which represents
the sub-sequence from the end of the full match to the end of the input
sequence.\n
+ 返回一个 _sub_match_ 对象，表示从全匹配的末端到输入序列的末端的一个子序
列。]]
+ [[`what.regex_id()`] [Returns the `regex_id` of the _basic_regex_
object that was last used with this _match_results_ object.\n
+ 返回该 _match_results_ 对象最后使用的 _basic_regex_ 对象的 `regex_id`。
]]
]
There is more you can do with the _match_results_ object, but that will be
covered when we talk about
-[link boost_xpressive.user_s_guide.grammars_and_nested_matches Grammars
and Nested Matches].
+[link boost_xpressive.user_s_guide.grammars_and_nested_matches Grammars
and Nested Matches].\n
+对于 _match_results_ 对象，你还可以做更多的事情，我们讨论
+[link boost_xpressive.user_s_guide.grammars_and_nested_matches 语法和嵌套匹
配] 的时候会提及。
[h2 sub_match]
When you index into a _match_results_ object, you get back a _sub_match_
object. A _sub_match_ is basically a pair
-of iterators. It is defined like this:
+of iterators. It is defined like this:\n
+当你对 _match_results_ 对象求索引时，你会得到一个 _sub_match_ 对象。本质上
一个 _sub_match_ 是一对迭代器。其定义类似于：
template< class BidirectionalIterator >
struct sub_match
@@ -56,22 +76,33 @@
Since it inherits publicaly from `std::pair<>`, _sub_match_ has `first`
and `second` data members of type
`BidirectionalIterator`. These are the beginning and end of the
sub-sequence this _sub_match_ represents.
_sub_match_ also has a Boolean `matched` data member, which is true if
this _sub_match_ participated in the full
-match.
-
-The following table shows how you might access the information stored in a
_sub_match_ object called `sub`.
+match.\n
+由于它公有地继承自 `std::pair<>`，所以 _sub_match_ 有两个类型为
`BidirectionalIterator` 的 `first` 和 `second` 数据成员。
+它们是这个 _sub_match_ 所表示的子序列的始端和末端。_sub_match_ 还有一个布尔
型的 matched 数据成员，如果该 _sub_match_
+参与了全匹配，则为 true。
+
+The following table shows how you might access the information stored in a
_sub_match_ object called `sub`.\n
+表示列出了如何访问保存在一个名为 `sub` 的 _sub_match_ 对象中的信息的方法。
[table sub_match<> Accessors
[[Accessor] [Effects]]
- [[`sub.length()`] [Returns the length of the sub-match. Same as
`std::distance(sub.first,sub.second)`.]]
- [[`sub.str()`] [Returns a `std::basic_string<>` constructed
from the sub-match. Same as
`std::basic_string<char_type>(sub.first,sub.second)`.]]
- [[`sub.compare(str)`] [Performs a string comparison between the
sub-match and `str`, where `str` can be a `std::basic_string<>`, C-style
null-terminated string, or another sub-match. Same as
`sub.str().compare(str)`.]]
+ [[`sub.length()`] [Returns the length of the sub-match. Same as
`std::distance(sub.first,sub.second)`.\n
+ 返回子匹配的长度。与 `std::distance(sub.first,sub.second)` 相同。]]
+ [[`sub.str()`] [Returns a `std::basic_string<>` constructed
from the sub-match. Same as
`std::basic_string<char_type>(sub.first,sub.second)`.\n
+ 返回一个由子匹配构造的 `std::basic_string<>`。与
`std::basic_string<char_type>(sub.first,sub.second)` 相同。]]
+ [[`sub.compare(str)`] [Performs a string comparison between the
sub-match and `str`, where `str` can be a `std::basic_string<>`, C-style
null-terminated string, or another sub-match. Same as
`sub.str().compare(str)`.\n
+ 执行子匹配与 `str` 之间的一次字符串比较，其中 `str` 可以是
`std::basic_string<>`, C-风格的以空字符结尾的字符串，或是另一个子匹配。
+ 与 `sub.str().compare(str)` 相同。]]
]
-[h2 __alert__ Results Invalidation __alert__]
+[h2 __alert__ Results Invalidation 结果失效 __alert__]
Results are stored as iterators into the input sequence. Anything which
invalidates
the input sequence will invalidate the match results. For instance, if you
match a `std::string` object,
the results are only valid until your next call to a non-const member
function of that `std::string` object.
-After that, the results held by the _match_results_ object are invalid.
Don't use them!
+After that, the results held by the _match_results_ object are invalid.
Don't use them!\n
+匹配的结果是保存为输入序列的迭代器的。任何使输入序列失效的事件都会使匹配结
果失效。
+例如，如果你匹配一个 `std::string` 对象，匹配的结果仅在你下一次调用该
`std::string` 对象的非常量成员函数之前是有效的。
+之后，由 _match_results_ 对象所保存的结果就会失效。不要再使用它们！
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/static_regexes.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/static_regexes.qbk Sun Aug 1 20:47:57 2010
@@ -5,54 +5,70 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Static Regexes]
-
-[h2 Overview]
+[section:static_regexes Static Regexes 静态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:
+over their string-based brethren. In particular, static regexes:\n
+真正使得xpressive不同于其它的C/C++正则表达式库的特性是，它可以用C++表达式来
编写一个正则表达式。
+xpressive通过操作符重载来实现这一功能，它使用一种被称为 ['表达式模板] 的技
术来将一个专用于模式匹配的小型语言嵌入到C++中。
+这些"静态regexes"与基于字符串的正则表达式相比，具有多种优点。尤其是，静态
regexes：
* are syntax-checked at compile-time; they will never fail at run-time due
to
- a syntax error.
+ a syntax error.\n
+ 编译期进行语法检查；它们不会在运行期因为语法错误了失败。
* 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.
+ user-defined actions that execute when parts of your regex match.\n
+ 可以自然地引用其它C++数据和代码，包括其它regexes，可以很简单地构建正则表
达式之外的语法和绑定一些用户自定义的动作，
+ 在你的regex部分匹配时去执行。
* 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.
+ function pointers that cannot be resolved at compile time.\n
+ 它们是静态绑定的，可以更好地内联和优化。静态regexes不需要状态表、虚函数、
字节编码或通过不能在编译期进行决议的函数指针进行调用。
* 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.
+ static regex that finds patterns in an array of integers, for instance.\n
+ 它们不限于仅在字符串中进行模式查找。比如，你可以声明一个静态regex来在一个
整数数组中进行模式查找。
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]
+legal C++.\n
+因为我们是用C++表达式来构成静态regexes的，所以我们受制于合法C++表达式的规
则。
+很不幸，这意味着"传统的"正则表达式语法并不总是能清晰地映射到C++中。在一定程
度上，我们映射regex ['结构]，选择新的语法以符合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`:
+in objects of type `std::string`:\n
+你要通过将某个东西赋值给一个 _basic_regex_ 对象来创建一个静态regex。
+例如，以下定义了一个可以用于在 `std::string` 对象中进行模式查找的regex：
sregex re = '$' >> +_d >> '.' >> _d >> _d;
-Assignment works similarly.
-
-[h2 Character and String Literals]
+Assignment works similarly.\n
+赋值操作与之相似。
+
+[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.
+meta-characters in Perl. In xpressive, literals always represent
themselves.\n
+在静态regexes中，字符和字符串文字常量匹配它们自身。例如，上述
regex中，`'$'` 和 `'.'` 分别匹配字符 `'$'` 和 `'.'`。
+不要将这与Perl中的元字符 [^$] 和 [^.] 相混淆。在xpressive中，文字常量总是表
示它们自身。
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:
+regexes:\n
+在静态regexes中使用文字常量时，你必须要小心，至少要有一个操作数不是文字常
量。例如，以下就['不]是有效的regexes：
sregex re1 = 'a' >> 'b'; // ERROR!
sregex re2 = +'a'; // ERROR!
@@ -64,27 +80,33 @@
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:
+should be written as:\n
+二元 `>>` 操作符的两个操作数都是文字常量，而一元 `+` 操作符的操作数也是一个
文字常量，
+所以这两个语句会分别调用C++原本的二元右移操作符和一元加操作符。那不是我们想
要的。
+要触发操作符的重载，必须至少有一个操作数是用户自定义类型。我们可以使用
xpressive和 `as_xpr()`
+辅助函数来将一个表达式"变为"regex-化，迫使操作符重载去查找正确的操作符。以
上两个regexes应写为：
sregex re1 = as_xpr('a') >> 'b'; // OK
sregex re2 = +as_xpr('a'); // OK
-[h2 Sequencing and Alternation]
+[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
+"followed by".\n
+你可能已经留意到，静态regexes中的子表达式必须用序列操作符 `>>` 来分隔。你可
以将这个操作符念成"后随"。
+
+ // Match an 'a' followed by a digit 匹配一个'a'后随一个数字
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
+read this operator as "or". For example:\n
+选择操作则和Perl中一样，使用 `|` 操作符。你可以将这个操作符念成"或"。例如：
+
+ // match a digit character or a word character one or more times 匹配一
个数字或单词字符一次或多次
sregex re = +( _d | _w );
-[h2 Grouping and Captures]
+[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++,
@@ -92,32 +114,42 @@
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:
+consider the following regex, which finds matching HTML tags:\n
+在Perl中，括号 `()` 具有特别的意义。它们进行分组，但是有一个副作用，它们同
时创建后向引用，如 [^$1] 和 [^$2]。
+在C++中，括号只能进行分组 \-\- 无法产生相应的副作用。要得到相同的效果，我们
要使用特殊的记号，如 `s1`, `s2`, 等等。
+每赋值一个就创建一个后向引用。然后你就可以在你的表达式中使用这些后向引
用，和在Perl中使用 [^\1] 和 [^\2] 一样。
+例如，以下regex可以查找成对的HTML标签：
"<(\\w+)>.*?</\\1>"
-In static xpressive, this would be:
+In static xpressive, this would be:\n
+在静态xpressive中，它们可以这样写：
'<' >> (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
+use `s1` later in the pattern to find the matching end tag.\n
+留意你要如何通过赋值给 `s1` 来捕获一个后向引用，以及如何在模式中使用 `s1`
来匹配结束标签。
+
+[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]
+non-capturing grouping construct.\n
+在xpressive中，如果你只是想分组而不捕获后向引用，你可以使用不带 `s1` 的
`()`。这等价于Perl的 [^(?:)] 非捕获分组结构。]
+
+[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:
+pattern modifier, called `icase`. You can use it as follows:\n
+Perl可以让你通过使用 [^(?i:)] 模式修改符来将部分正则表达式变为大小写不敏
感。
+xpressive也有一个大小写不敏感的模式修改符，称为 `icase`。你可以象以下这样使
用它：
sregex re = "this" >> icase( "that" );
In this regular expression, `"this"` will be matched exactly, but `"that"`
-will be matched irrespective of case.
+will be matched irrespective of case.\n
+在这个正则表达式中，`"this"` 将被精确匹配，而 `"that"` 则在匹配时不考虑大小
写。
Case-insensitive regular expressions raise the issue of
internationalization: how should case-insensitive character comparisons be
@@ -126,7 +158,11 @@
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:
+follows:\n
+大小写不敏感的正则表达式引起了一个国际化的问题：大小写不敏感的字符应该如何
比较其相等性？
+而且，许多字符类都是指定locale的。哪些字符匹配 `digit` 而哪些字符匹配
`alpha` 呢？
+答案取决于正则表达式对象所使用的 `std::locale` 对象。缺省地，所有正则表达式
对象使用全局locale。
+你可以用 `imbue()` 模式修改符来覆盖这一缺省值，如下：
std::locale my_locale = /* initialize a std::locale object */;
sregex re = imbue( my_locale )( +alpha >> +digit );
@@ -134,12 +170,15 @@
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 behavior of your regexes.\n
+这个正则表达式将依据 `my_locale` 来求值 `alpha` 和 `digit`。有关如何定制你
的regexes的行为的更多信息，请看
+[link boost_xpressive.user_s_guide.localization_and_regex_traits 本地化和
Regex Traits] 一节。
+
+[h2 Static xpressive Syntax Cheat Sheet 静态 xpressive 语法对照表]
The table below lists the familiar regex constructs and their equivalents
in
-static xpressive.
+static xpressive.\n
+下表列出了常见的regex结构以及在静态xpressive中的等价物。
[def _s1_ [globalref boost::xpressive::s1 s1]]
[def _bos_ [globalref boost::xpressive::bos bos]]
@@ -171,61 +210,115 @@
[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.]]
+ [[Perl] [Static xpressive]
[Meaning 含义]]
+ [[[^.]] [[globalref boost::xpressive::_ `_`]]
[any character (assuming Perl's /s modifier).\n
+ 任意字符(假定有Perl的/s修改符)。]]
+ [[[^ab]] [`a >> b`]
[sequencing of [^a] and [^b] sub-expressions.\n
+ [^a] 和 [^b] 子表达式的顺序序列。]]
+ [[[^a|b]] [`a | b`]
[alternation of [^a] and [^b] sub-expressions.\n
+ [^a] 和 [^b] 子表达式的二选一。]]
+ [[[^(a)]] [`(_s1_= a)`]
[group and capture a back-reference.\n
+ 分组并捕获一个后向引用。]]
+ [[[^(?:a)]] [`(a)`]
[group and do not capture a back-reference.\n
+ 分组但不捕获后向引用。]]
+ [[[^\1]] [`_s1_`]
[a previously captured back-reference.\n
+ 之前捕获的一个后向引用。]]
+ [[[^a*]] [`*a`]
[zero or more times, greedy.\n
+ 零次或多次，贪心式。]]
+ [[[^a+]] [`+a`]
[one or more times, greedy.\n
+ 一次或多次，贪心式。]]
+ [[[^a?]] [`!a`]
[zero or one time, greedy.\n
+ 零次或一次，贪心式。]]
+ [[[^a{n,m}]] [`_repeat_<n,m>(a)`]
[between [^n] and [^m] times, greedy.\n
+ [^n] 至 [^m] 次，贪心式。]]
+ [[[^a*?]] [`-*a`]
[zero or more times, non-greedy.\n
+ 零次或多次，非贪心式。]]
+ [[[^a+?]] [`-+a`]
[one or more times, non-greedy.\n
+ 一次或多次，非贪心式。]]
+ [[[^a??]] [`-!a`]
[zero or one time, non-greedy.\n
+ 零次或一次，非贪心式。]]
+ [[[^a{n,m}?]] [`-_repeat_<n,m>(a)`]
[between [^n] and [^m] times, non-greedy.\n
+ [^n] 至 [^m] 次，非贪心式。]]
+ [[[^^]] [`_bos_`]
[beginning of sequence assertion.\n
+ 序列起点断言。]]
+ [[[^$]] [`_eos_`]
[end of sequence assertion.\n
+ 序列末点断言。]]
+ [[[^\b]] [`_b_`]
[word boundary assertion.\n
+ 单词边界断言。]]
+ [[[^\B]] [`~_b_`]
[not word boundary assertion.\n
+ 非单词边界断言。]]
+ [[[^\\n]] [`_n_`]
[literal newline.\n
+ 字面换行。]]
+ [[[^.]] [`~_n_`]
[any character except a literal newline (without Perl's /s modifier).\n
+ 除字面换行外的任意字符(不带Perl的/s修改符)。]]
+ [[[^\\r?\\n|\\r]] [`_ln_`]
[logical newline.\n
+ 逻辑换行。]]
+ [[[^\[^\\r\\n\]]] [`~_ln_`]
[any single character not a logical newline.\n
+ 非逻辑换行外的任意字符。]]
+ [[[^\w]] [`_w_`]
[a word character, equivalent to set\[alnum | '_'\].\n
+ 一个单词字符，等价于 set\[alnum | '_'\].]]
+ [[[^\W]] [`~_w_`]
[not a word character, equivalent to ~set\[alnum | '_'\].\n
+ 不是一个单词字符，等价于 ~set\[alnum | '_'\].]]
+ [[[^\d]] [`_d_`]
[a digit character.\n
+ 数字字符。]]
+ [[[^\D]] [`~_d_`]
[not a digit character.\n
+ 非数字字符。]]
+ [[[^\s]] [`_s_`]
[a space character.\n
+ 空白字符。]]
+ [[[^\S]] [`~_s_`]
[not a space character.\n
+ 非空白字符。]]
+ [[[^\[:alnum:\]]] [`_alnum_`]
[an alpha-numeric character.\n
+ 字母-数字字符。]]
+ [[[^\[:alpha:\]]] [`_alpha_`]
[an alphabetic character.\n
+ 字母字符。]]
+ [[[^\[:blank:\]]] [`_blank_`]
[a horizontal white-space character.\n
+ 水平空白字符。]]
+ [[[^\[:cntrl:\]]] [`_cntrl_`]
[a control character.\n
+ 控制字符。]]
+ [[[^\[:digit:\]]] [`_digit_`]
[a digit character.\n
+ 数字字符。]]
+ [[[^\[:graph:\]]] [`_graph_`]
[a graphable character.\n
+ 图形字符。]]
+ [[[^\[:lower:\]]] [`_lower_`]
[a lower-case character.\n
+ 小写字符。]]
+ [[[^\[:print:\]]] [`_print_`]
[a printing character.\n
+ 打印字符。]]
+ [[[^\[:punct:\]]] [`_punct_`]
[a punctuation character.\n
+ 标点字符。]]
+ [[[^\[:space:\]]] [`_space_`]
[a white-space character.\n
+ 空白字符。]]
+ [[[^\[:upper:\]]] [`_upper_`]
[an upper-case character.\n
+ 大写字符。]]
+ [[[^\[:xdigit:\]]] [`_xdigit_`]
[a hexadecimal digit character.\n
+ 十六进制数字字符。]]
+ [[[^\[0-9\]]] [`_range_('0','9')`]
[characters in range `'0'` through `'9'`.\n
+ 从 `'0'` 至 `'9'` 间的字符。]]
+ [[[^\[abc\]]] [`as_xpr('a') | 'b' |'c'`]
[characters `'a'`, `'b'`, or `'c'`.\n
+ 字符 `'a'`, `'b'`, 或 `'c'`.]]
+ [[[^\[abc\]]] [`(_set_= 'a','b','c')`]
[['same as above]\n
+ ['同上]]]
+ [[[^\[0-9abc\]]] [`_set_[ _range_('0','9') | 'a' | 'b' | 'c' ]`]
[characters `'a'`, `'b'`, `'c'` or in range `'0'` through `'9'`.\n
+ `'a'`, `'b'`, `'c'` 或 `'0'` 至 `'9'` 间的字符。]]
+ [[[^\[0-9abc\]]] [`_set_[ _range_('0','9') | (_set_= 'a','b','c')
]`] [['same as above]\n
+ ['同上]]]
+ [[[^\[^abc\]]] [`~(_set_= 'a','b','c')`]
[not characters `'a'`, `'b'`, or `'c'`.\n
+ 非 `'a'`, `'b'`, 或 `'c'` 的字符。]]
+ [[[^(?i:['stuff])]] [`_icase_(`[^['stuff]]`)`]
[match ['stuff] disregarding case.\n
+ 忽略大小写匹配 ['stuff].]]
+ [[[^(?>['stuff])]] [`_keep_(`[^['stuff]]`)`]
[independent sub-expression, match ['stuff] and turn off backtracking.\n
+ 独立子表达式，匹配 ['stuff] 并关闭反向跟踪。]]
+ [[[^(?=['stuff])]] [`_before_(`[^['stuff]]`)`]
[positive look-ahead assertion, match if before ['stuff] but don't include
['stuff] in the match.\n
+ 正顺序环视断言，如果在 ['stuff] 之前但不含 stuff 时匹配。]]
+ [[[^(?!['stuff])]] [`~_before_(`[^['stuff]]`)`]
[negative look-ahead assertion, match if not before ['stuff].\n
+ 负顺序环视断言，不在 ['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.)\n
+ 正逆序环视断言，如果在 ['stuff] 之后但不含 ['stuff] 时匹配。(['stuff]
必须是常数宽度)]]
+ [[[^(?<!['stuff])]] [`~_after_(`[^['stuff]]`)`]
[negative look-behind assertion, match if not after ['stuff]. (['stuff]
must be constant-width.)\n
+ 负逆序环视，不在 ['stuff] 之后时匹配。(['stuff] 必须是常数宽度)]]
+ [[[^(?P<['name]>['stuff])]] [`_mark_tag_
`[^['name]]`(`['n]`);`\n ...\n `(`[^['name]]`= `[^['stuff]]`)`]
[Create a named capture.\n
+ 创建一个命名捕获。]]
+ [[[^(?P=['name])]] [`_mark_tag_
`[^['name]]`(`['n]`);`\n ...\n [^['name]]] [Refer
back to a previously created named capture.\n
+ 后向引用至之前创建的某个命名捕获。]]
]
\n
=======================================
--- /trunk/libs/xpressive/doc/substitutions.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/substitutions.qbk Sun Aug 1 20:47:57 2010
@@ -5,11 +5,13 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section String Substitutions]
+[section:string_substitutions 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
-searching and replacing.
+searching and replacing.\n
+正则表达式并不只是擅长查找文本；它们也擅于['操作]文本。而最常见的一种文本操
作任务就是查找并替换。
+xpressive提供了 _regex_replace_ 算法来查找和替换。
[h2 regex_replace()]
@@ -19,7 +21,12 @@
of the same type. Others accept the input as a null terminated string and
return a `std::string`. Still others
accept the input sequence as a pair of iterators and writes the result
into an output iterator. The substitution
may be specified as a string with format sequences or as a formatter
object. Below are some simple examples of
-using string-based substitutions.
+using string-based substitutions.\n
+用 _regex_replace_ 执行查找和替换非常简单。你所需要的就是一个输入序列、一个
regex对象、一个格式化字符串或一个格式化器对象。
+存在多个版本的 _regex_replace_ 算法。有些以双向容器，如 `std::string`，的方
式接受输入序列并在一个相同类型的新容器中返回结果。
+其它的一些版本则以空字符结尾的字符串方式接受输入并返回一个 `std::string`。
+还有一些版本以迭代器对的方式接受输入序列并将结果写出到输出迭代器。
+替代方式可以由一个带格式化序列的字符串或一个格式化器对象来指定。以下是一些
例子，使用了基于字符串的替代。
std::string input("This is his face");
sregex re = as_xpr("his"); // find all occurrences
of "his" ...
@@ -33,117 +40,176 @@
std::ostream_iterator< char > out_iter( std::cout );
regex_replace( out_iter, input.begin(), input.end(), re, format );
-The above program prints out the following:
+The above program prints out the following:\n
+以上程序的输出如下：
[pre
Ther is her face
Ther is her face
]
-Notice that ['all] the occurrences of `"his"` have been replaced with
`"her"`.
+Notice that ['all] the occurrences of `"his"` have been replaced with
`"her"`.\n
+注意，['所有]的 `"his"` 都已替换为 `"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
-to see a complete list of the available overloads.
-
-[h2 Replace Options]
+to see a complete list of the available overloads.\n
+在 [link
boost_xpressive.user_s_guide.examples.replace_all_sub_strings_that_match_a_regex
这里]
+有一个完整的示例程序示范如何使用 _regex_replace_。在 _regex_replace_ 参考手
册中有所有可用重载的完整列表。
+
+[h2 Replace Options 替换的选项]
The _regex_replace_ algorithm takes an optional bitmask parameter to
control the formatting. The
-possible values of the bitmask are:
-
-[table Format Flags
+possible values of the bitmask are:\n
+算法 _regex_replace_ 接受一个可选的位掩码参数来控制格式化。该掩码的可用值如
下：
+
+[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_default`] [Recognize the ECMA-262 format sequences
(see below).\n
+ 使用ECMA-262格式化序列(见后)。]]
+ [[`format_first_only`] [Only replace the first match, not all of
them.\n
+ 只替换第一个匹配而不是所有。]]
[[`format_no_copy`] [Don't copy the parts of the input
sequence that didn't match the regex
- to the output sequence.]]
+ to the output sequence.\n
+ 不将输入序列中不匹配regex的部分复制至输出
序列。]]
[[`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).]]
+ escape sequences.\n
+ 将格式化字符串视为文字值；即不使用任何转义
序列。]]
+ [[`format_perl`] [Recognize the Perl format sequences (see
below).\n
+ 使用Perl格式化序列(见后)。]]
+ [[`format_sed`] [Recognize the sed format sequences (see
below).\n
+ 使用sed格式化序列(见后)。]]
[[`format_all`] [In addition to the Perl format sequences,
recognize some
- Boost-specific format sequences.]]
+ Boost-specific format sequences.\n
+ 除了Perl格式化序列以外，还使用一些Boost特
有的格式化序列。]]
]
These flags live in the `xpressive::regex_constants` namespace. If the
substitution parameter is
a function object instead of a string, the flags `format_literal`,
`format_perl`, `format_sed`, and
-`format_all` are ignored.
-
-[h2 The ECMA-262 Format Sequences]
+`format_all` are ignored.\n
+这些标志位于 `xpressive::regex_constants` 名字空间。如果替代参数是一个函数
对象而不是字符串，则忽略标志
+`format_literal`, `format_perl`, `format_sed`, 和 `format_all`。
+
+[h2 The ECMA-262 Format Sequences ECMA-262格式化序列]
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
+the escape sequences recognized in ECMA-262 mode.\n
+如果你没有指定带有以上任一格式化标志的替换串方言，那么你就是使用由
ECMA-262定义的方言，这是ECMAScript的标准。
+下表列出了在 ECMA-262 模式中使用的转义序列。
+
+[table 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]]
+ [[[^$1], [^$2], etc.] [the corresponding sub-match\n
+ 对应的子匹配]]
+ [[[^$&]] [the full match\n
+ 全匹配]]
+ [[[^$\`]] [the match prefix\n
+ 匹配前缀]]
+ [[[^$']] [the match suffix\n
+ 匹配后缀]]
+ [[[^$$]] [a literal `'$'` character\n
+ `'$'` 字符]]
]
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 The Sed Format Sequences]
+`"$a"` then `"$a"` would be inserted into the output sequence.\n
+任何其它以 `'$'` 开头的序列都只是表示它本身。例如，如果格式化串为 `"$a"`
则 `"$a"` 将被插入到输出序列中。
+
+[h2 The Sed Format Sequences Sed格式化序列]
When specifying the `format_sed` flag to _regex_replace_, the following
escape sequences
-are recognized:
-
-[table Sed Format Escape Sequences
+are recognized:\n
+当指定 `format_sed` 标志给 _regex_replace_ 时，将使用以下转义序列：
+
+[table Sed Format Escape Sequences Sed格式化转义序列
[[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]]]]
+ [[[^\\1], [^\\2], etc.] [The corresponding sub-match\n
+ 对应的子匹配]]
+ [[[^&]] [the full match\n
+ 全匹配]]
+ [[[^\\a]] [A literal `'\a'`\n
+ 文字 `'\a'`]]
+ [[[^\\e]] [A literal `char_type(27)`\n
+ 文字 `char_type(27)`]]
+ [[[^\\f]] [A literal `'\f'`\n
+ 文字 `'\f'`]]
+ [[[^\\n]] [A literal `'\n'`\n
+ 文字 `'\n'`]]
+ [[[^\\r]] [A literal `'\r'`\n
+ 文字 `'\r'`]]
+ [[[^\\t]] [A literal `'\t'`\n
+ 文字 `'\t'`]]
+ [[[^\\v]] [A literal `'\v'`\n
+ 文字 `'\v'`]]
+ [[[^\\xFF]] [A literal `char_type(0xFF)`, where [^['F]] is
any hex digit\n
+ 文字 `char_type(0xFF)`, 其中 [^['F]] 是任意的十六进制数字]]
+ [[[^\\x{FFFF}]] [A literal `char_type(0xFFFF)`, where [^['F]]
is any hex digit\n
+ 文字 `char_type(0xFFFF)`, 其中 [^['F]] 是任意的十六进制数字]]
+ [[[^\\cX]] [The control character [^['X]]\n
+ 控制字符 [^['X]] ]]
]
-[h2 The Perl Format Sequences]
+[h2 The Perl Format Sequences Perl格式化序列 ]
When specifying the `format_perl` flag to _regex_replace_, the following
escape sequences
-are recognized:
-
-[table Perl Format Escape Sequences
+are recognized:\n
+当指定 `format_perl` 标志给 _regex_replace_ 时，使用以下转义序列：
+
+[table Perl Format Escape Sequences Perl 格式化转义序列
[[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/]]
+ [[[^$1], [^$2], etc.] [the corresponding sub-match\n
+ 对应的子匹配]]
+ [[[^$&]] [the full match\n
+ 全匹配]]
+ [[[^$\`]] [the match prefix\n
+ 匹配前缀]]
+ [[[^$']] [the match suffix\n
+ 匹配后缀]]
+ [[[^$$]] [a literal `'$'` character\n
+ 文字 `'$'` 字符]]
+ [[[^\\a]] [A literal `'\a'`\n
+ 文字 `'\a'`]]
+ [[[^\\e]] [A literal `char_type(27)`\n
+ 文字 `'char_type(27)'`]]
+ [[[^\\f]] [A literal `'\f'`\n
+ 文字 `'\f'`]]
+ [[[^\\n]] [A literal `'\n'`\n
+ 文字 `'\n'`]]
+ [[[^\\r]] [A literal `'\r'`\n
+ 文字 `'\r'`]]
+ [[[^\\t]] [A literal `'\t'`\n
+ 文字 `'\t'`]]
+ [[[^\\v]] [A literal `'\v'`\n
+ 文字 `'\v'`]]
+ [[[^\\xFF]] [A literal `char_type(0xFF)`, where [^['F]] is
any hex digit\n
+ 文字 `char_type(0xFF)`, 其中 [^['F]] 是任意的十六进制数字]]
+ [[[^\\x{FFFF}]] [A literal `char_type(0xFFFF)`, where [^['F]]
is any hex digit\n
+ 文字 `char_type(0xFFFF)`, 其中 [^['F]] 是任意的十六进制数字]]
+ [[[^\\cX]] [The control character [^['X]]\n
+ 控制字符 {^['X]]]]
+ [[[^\\l]] [Make the next character lowercase\n
+ 将下一个字符变为小写]]
+ [[[^\\L]] [Make the rest of the substitution lowercase
until the next [^\\E]\n
+ 将剩余替代变为小写，直至下一个 [^\\E]]]
+ [[[^\\u]] [Make the next character uppercase\n
+ 将下一个字符变为大写]]
+ [[[^\\U]] [Make the rest of the substitution uppercase
until the next [^\\E]\n
+ 将剩余替代变为大写，直至下一个 [^\\E]]]
+ [[[^\\E]] [Terminate [^\\L] or [^\\U]\n
+ 结束 [^\\L] 或 [^\\U]]]
+ [[[^\\1], [^\\2], etc.] [The corresponding sub-match\n
+ 对应的子匹配]]
+ [[[^\\g<name>]] [The named backref /name/\n
+ 命名的后向引用 /name/ ]]
]
-[h2 The Boost-Specific Format Sequences]
+[h2 The Boost-Specific Format Sequences Boost特有的格式化序列]
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:
+expressions of the following form are recognized:\n
+当指定 `format_all` 标志给 _regex_replace_ 时，使用的转义序列与前面的
`format_perl` 相同。另外还可以使用以下形式的条件表达式：
[pre
?Ntrue-expression:false-expression
@@ -152,9 +218,11 @@
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 [^\\(].
-
-[h2 Formatter Objects]
+want a literal paren, you must escape it as [^\\(].\n
+其中 /N/ 是一个十进制数字，表示某个子匹配。如果对应的子匹配参与了全匹配，则
该替换为 /true-expression/。
+否则为 /false-expression/。在这个模式下，你可以使用括号 [^()] 来分组。如果
你要一个文字上的括号，你必须用转义序列 [^\\(]。
+
+[h2 Formatter Objects 格式化器对象]
Format strings are not always expressive enough for all your text
substitution
needs. Consider the simple example of wanting to map input strings to
output
@@ -162,7 +230,10 @@
/string/, for this you would use a formatter /object/. Consider the
following
code, which finds embedded environment variables of the form `"$(XYZ)"` and
computes the substitution string by looking up the environment variable in
a
-map.
+map.\n
+格式化串并不总能足够应付你所有的文本替换需要。想象这样一个简单的例子，你想
将输入字符串映射至输出字符串，正如你可能想用环境变量所做的。
+这时不要用格式化/串/，你要用一个格式化器/对象/。
+考虑以下代码，它找出内嵌的形如 `"$(XYZ)"` 的环境变量，并通过在一个map中查找
该环境变量来计算替换的字符串。
#include <map>
#include <string>
@@ -194,7 +265,9 @@
In this case, we use a function, `format_fun()` to compute the
substitution string
on the fly. It accepts a _match_results_ object which contains the results
of the
current match. `format_fun()` uses the first submatch as a key into the
global `env`
-map. The above code displays:
+map. The above code displays:\n
+在这种情况下，我们使用函数 `format_fun()` 来就地计算替换字符串。它接受一个
含有当前匹配结果的 _match_results_ 对象。
+`format_fun()` 使用第一个子匹配作为全局 `env` map的键值。以上代码输出：
[pre
"this" has the value "that"
@@ -203,7 +276,9 @@
The formatter need not be an ordinary function. It may be an object of
class type.
And rather than return a string, it may accept an output iterator into
which it
writes the substitution. Consider the following, which is functionally
equivalent
-to the above.
+to the above.\n
+格式化器不必是一个普通函数。它可以是一个类类型对象。它也不必返回一个字符
串，可以接受一个输出迭代器用以写出替代串。
+参考以下代码，其功能与前面的代码一样。
#include <map>
#include <string>
@@ -248,7 +323,10 @@
that has one of three possible signatures, detailed in the table below. For
the table, `fmt` is a function pointer or function object, `what` is a
_match_results_ object, `out` is an OutputIterator, and `flags` is a value
-of `regex_constants::match_flag_type`:
+of `regex_constants::match_flag_type`:\n
+格式化器必须是一个可调用的对象 -- 函数或函数对象 -- 可以是三个可能的签名之
一，详见下表。
+在下表中，`fmt` 是一个函数指针或函数对象，`what` 是一个 _match_results_ 对
象，`out` 是一个输出迭代器，
+`flags` 是一个类型为 `regex_constants::match_flag_type` 的值：
[table Formatter Signatures
[
@@ -258,25 +336,29 @@
]
[
[`fmt(what)`]
- [Range of characters (e.g. `std::string`) or null-terminated string]
+ [Range of characters (e.g. `std::string`) or null-terminated string\n
+ 字符区间(如 `std::string`)或空字符结尾的字符串]
[The string matched by the regex is replaced with the string returned
by
- the formatter.]
+ the formatter.\n
+ 匹配regex的字符串被替换为由格式化器返回的字符串。]
]
[
[`fmt(what, out)`]
- [OutputIterator]
- [The formatter writes the replacement string into `out` and returns
`out`.]
+ [OutputIterator\n输出迭代器]
+ [The formatter writes the replacement string into `out` and returns
`out`.\n
+ 格式化器将替换串写出至 `out` 并返回 `out`. ]
]
[
[`fmt(what, out, flags)`]
- [OutputIterator]
+ [OutputIterator\n输出迭代器]
[The formatter writes the replacement string into `out` and returns
`out`.
The `flags` parameter is the value of the match flags passed to the
- _regex_replace_ algorithm.]
+ _regex_replace_ algorithm.\n
+ 格式化器将替换串写出至 `out` 并返回 `out`。参数 `flags` 为传给
_regex_replace_ 算法的匹配标志值。]
]
]
-[h2 Formatter Expressions]
+[h2 Formatter Expressions 格式化器表达式]
In addition to format /strings/ and formatter /objects/, _regex_replace_
also
accepts formatter /expressions/. A formatter expression is a lambda
expression
@@ -284,7 +366,10 @@
[link
boost_xpressive.user_s_guide.semantic_actions_and_user_defined_assertions
Semantic Actions], which are covered later. The above example, which uses
_regex_replace_ to substitute strings for environment variables, is
repeated
-here using a formatter expression.
+here using a formatter expression.\n
+除了格式化/串/和格式化器/对象/以外，_regex_replace_ 还接受格式化器表达式。
格式化器表达式是一个生成字符串的lambda表达式。
+它所使用的语法与用于语义动作的语法相同，稍后我们会提及。
+前面那个用 _regex_replace_ 来把环境变量替换为字符串的例子，可以用格式化器表
达式实现如下。
#include <map>
#include <string>
@@ -309,6 +394,8 @@
In the above, the formatter expression is `ref(env)[s1]`. This means to
use the
value of the first submatch, `s1`, as a key into the `env` map. The
purpose of
`xpressive::ref()` here is to make the reference to the `env` local
variable /lazy/
-so that the index operation is deferred until we know what to replace `s1`
with.
+so that the index operation is deferred until we know what to replace `s1`
with.\n
+这里的格式化器表达式是 `ref(env)[s1]`。它表示的是，使用第一个子匹配的值
`s1` 作为 `env` map 的键值来求值。
+这里的 `xpressive::ref()` 的目的是令局部变量 `env` 的引用变为/惰性/的，使得
下标操作可以到我们得知 `s1` 要替换为什么的时候再进行解引用。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/symbols.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/symbols.qbk Sun Aug 1 20:47:57 2010
@@ -5,24 +5,30 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Symbol Tables and Attributes]
-
-[h2 Overview]
+[section:symbol_tables_and_attributes 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]
+for an attribute if a symbol is not found.\n
+可以用 `std::map<>` 在xpressive正则表达式中构建符号表。map的键值是匹配到的
字符串，而map的值则是被返回到你的语义动作的数据。
+Xpressive属性，其命名为 `a1`, `a2`, ... `a9`, 分别存有与匹配键相对应的
值，可以被用于某个语义动作中。
+如果某个符号找不到，可以为属性指定一个缺省值。
+
+[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.
+`a1` to an integer result.\n
+一个xpressive符号表就是一个 `std::map<>`，其键类型为字符串，值类型可以是任
意类型。
+例如，以下正则表达式从map1匹配一个键值，并且将对应的值赋给属性 `a1`。
+然后，在语义动作中，再将保存在属性 `a1` 中的值赋给一个整数结果。
int result;
std::map<std::string, int> map1;
@@ -31,7 +37,8 @@
Consider the following example code,
which translates number names into integers. It is
-described below.
+described below.\n
+看以下代码示例，它将数字名翻译为整数。说明见后。
#include <string>
#include <iostream>
@@ -61,7 +68,8 @@
return 0;
}
-This program prints the following:
+This program prints the following:\n
+该程序输出如下：
[pre
3
@@ -75,18 +83,27 @@
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.
+the symbol is not found.\n
+首先，该程序建立一个数字map，以数字名作为字符串键值，以对应的整数为值。
+然后它构造一个静态正则表达式，用一个属性 `a1` 来表示从符号表中查找得到的结
果。
+在语义动作中，该属性被赋给一个整数变量 `result`。如果没有找到相应符号，则将
缺省值 `-1` 赋给 `result`。
+通配符 `*_` 确保即使找不到相应符号，regex也可以匹配成功。
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
+who contributed this example.\n
+非常感谢 David Jenkins 贡献了这个例子。]. 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".
+along with some special number names like "dozen".\n
+在 [^libs/xpressive/example/numbers.cpp] 中可以找到这个例子的一个更完整的版
本。
+它可以翻译最大至"nine hundred ninety nine million nine hundred ninety nine
thousand
+nine hundred ninety nine"的数字名以及一些特殊的数字名，如 "dozen"。
Symbol table matches are case sensitive by default, but they can be made
-case-insensitive by enclosing the expression in `icase()`.
-
-[h2 Attributes]
+case-insensitive by enclosing the expression in `icase()`.\n
+符号表匹配缺省是大小写敏感的，不过可以通过将表达式放入 `icase()` 中来使它们
变为大小写不敏感。
+
+[h2 Attributes 属性]
[def __default_value__ '''<replaceable>default-value</replaceable>''']
@@ -94,17 +111,23 @@
`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__)`.
+syntax `(a1 | __default_value__)`.\n
+在一个正则表达式中，最多可以使用九个属性。它们分别命名为 `a1`, `a2`, ...,
`a9`，位于 `boost::xpressive` 名字空间中。
+属性的类型与赋值给它的map的第二个元素相同。属性的缺省值可以在语义动作中用语
法 `(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.
+even have different types.\n
+属性是被正确地定域的，所以你可以做出象以下这样的疯狂事情：`( (a1=sym1) >>
(a1=sym2)[ref(x)=a1] )[ref(y)=a1]`。
+内层的语义动作可以看到内层的 `a1`，而外层的语义动作则看到外层的那个。它们甚
至可以具有不同的类型。
[note Xpressive builds a hidden ternary search trie from the map so it can
search quickly. If BOOST_DISABLE_THREADS is defined,
the hidden ternary search trie "self adjusts", so after each
search it restructures itself to improve the efficiency of future searches
-based on the frequency of previous searches.]
+based on the frequency of previous searches.\n
+Xpressive会从map中构建一个隐藏的三元搜索树，以便可以快速地查找。如果定义了
BOOST_DISABLE_THREADS，
+则隐藏的三元搜索树会"自我调整"，在每次搜索后它会基于之前的搜索频率进行重
组，以提高后面的搜索效率。]
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/tips_n_tricks.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/tips_n_tricks.qbk Sun Aug 1 20:47:57 2010
@@ -5,32 +5,39 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:tips_n_tricks Tips 'N Tricks]
-
-Squeeze the most performance out of xpressive with these tips and tricks.
-
-[h2 Compile Patterns Once And Reuse Them]
+[section:tips_n_tricks Tips 'N Tricks 提示与技巧 ]
+
+Squeeze the most performance out of xpressive with these tips and tricks.\n
+以下这些提示和技巧可以将xpressive的最大性能挤压出来。
+
+[h2 Compile Patterns Once And Reuse Them 对模式编译一次并重用它们 ]
Compiling a regex (dynamic or static) is /far/ more expensive than
executing a
match or search. If you have the option, prefer to compile a pattern into
a _basic_regex_ object once and reuse it rather than recreating it over
-and over.
+and over.\n
+编译一个regex (动态或静态的)要比执行一次匹配或查找更为昂贵。
+如果你可以选择，就应该一次性将模式编译到一个 _basic_regex_ 对象中，然后重用
它，而不是反复创建它。
Since _basic_regex_ objects are not mutated by any of the regex
algorithms, they
are completely thread-safe once their initialization (and that of any
grammars of
which they are members) completes. The easiest way to reuse your patterns
is
-to simply make your _basic_regex_ objects "static const".
-
-[h2 Reuse _match_results_ Objects]
+to simply make your _basic_regex_ objects "static const".\n
+由于 _basic_regex_ 对象不会被任何 regex 算法改写，所以一旦这些对象的初始化
(以及它们所含的语法元素)完成，它们就是线程安全的。
+重用你的模式的最容易的方法是，令你的 _basic_regex_ 对象为"static const"。
+
+[h2 Reuse _match_results_ Objects 重用 _match_results_ 对象 ]
The _match_results_ object caches dynamically allocated memory. For this
reason, it is far better to reuse the same _match_results_ object if you
-have to do many regex searches.
+have to do many regex searches.\n
+_match_results_ 对象缓存了动态分配的内存。为此，如果你要进行多个regex搜
索，重用同一个 _match_results_ 对象要好得多。
Caveat: _match_results_ objects are not thread-safe, so don't go wild
-reusing them across threads.
-
-[h2 Prefer Algorithms That Take A _match_results_ Object]
+reusing them across threads.\n
+警告：_match_results_ 对象不是线程安全的，所以不要跨线程重用它们。
+
+[h2 Prefer Algorithms That Take A _match_results_ Object 优先选用带
_match_results_ 对象的算法 ]
This is a corollary to the previous tip. If you are doing multiple
searches,
you should prefer the regex algorithms that accept a _match_results_ object
@@ -38,9 +45,12 @@
each time. If you don't provide a _match_results_ object, a temporary one
will be created for you and discarded when the algorithm returns. Any
memory cached in the object will be deallocated and will have to be
reallocated
-the next time.
-
-[h2 Prefer Algorithms That Accept Iterator Ranges Over Null-Terminated
Strings]
+the next time.\n
+这是前一个提示的必然推论。如果你要进行多次查找，你应该优先选择使用
_match_results_
+对象的regex算法，而且应该重用同一个 _match_results_ 对象。如果你不提供一个
_match_results_ 对象，
+则会为你创建一个临时的对象并在算法返回时丢弃。所有缓存在该对象中的内存将被
释放，在下一次使用时将不得不重新分配。
+
+[h2 Prefer Algorithms That Accept Iterator Ranges Over Null-Terminated
Strings 处理空字符结束的字符串时，优先选用接受迭代器区间的算法]
xpressive provides overloads of the _regex_match_ and _regex_search_
algorithms that operate on C-style null-terminated strings. You should
@@ -48,27 +58,35 @@
null-terminated string to a regex algorithm, the end iterator is calculated
immediately by calling `strlen`. If you already know the length of the
string,
you can avoid this overhead by calling the regex algorithms with a
`[begin, end)`
-pair.
-
-[h2 Use Static Regexes]
+pair.\n
+xpressive为 _regex_match_ 和 _regex_search_ 算法提供了处理C-风格的空字符结
束字符串的多个重载。
+你应该优先选用其中接受迭代器区间的那些重载。如果你传递一个空字符结束的字符
串给一个regex 算法，会即时通过调用 strlen 来计算出结尾迭代器。
+如果你已经知道该字符串的长度，就可以通过以一个 `[begin, end)` 对来调用这个
regex算法，避免这种开销。
+
+[h2 Use Static Regexes 使用静态Regexes ]
On average, static regexes execute about 10 to 15% faster than their
dynamic counterparts. It's worth familiarizing yourself with the static
-regex dialect.
-
-[h2 Understand [^syntax_option_type::optimize]]
+regex dialect.\n
+平均来说，静态regex执行起来比同等的动态regex快10%到15%。熟悉静态regex的写法
非常值得。
+
+[h2 Understand [^syntax_option_type::optimize] 理解
[^syntax_option_type::optimize] ]
The `optimize` flag tells the regex compiler to spend some extra time
analyzing
the pattern. It can cause some patterns to execute faster, but it increases
the time to compile the pattern, and often increases the amount of memory
consumed by the pattern. If you plan to reuse your pattern, `optimize` is
-usually a win. If you will only use the pattern once, don't use `optimize`.
-
-[h1 Common Pitfalls]
-
-Keep the following tips in mind to avoid stepping in potholes with
xpressive.
-
-[h2 Create Grammars On A Single Thread]
+usually a win. If you will only use the pattern once, don't use
`optimize`.\n
+这个 `optimize` 标志告知regex编译器，使用更多的时间去分析这个模式。
+这样可以使得某些模式执行得更快一些，不过它会增加模式编译的时间，而且通常也
会增加该模式所占用的内存。
+如果你计划重用你的模式，通常使用 `optimize` 会更好。如果你只使用该模式一
次，就不要使用 `optimize`.
+
+[h1 Common Pitfalls 常见错误 ]
+
+Keep the following tips in mind to avoid stepping in potholes with
xpressive.\n
+留意以下提示，以避免陷入xpressive的泥沼。
+
+[h2 Create Grammars On A Single Thread 在单个线程中创建语法]
With static regexes, you can create grammars by nesting regexes inside one
another. When compiling the outer regex, both the outer and inner regex
objects,
@@ -76,14 +94,21 @@
modified. For this reason, it's dangerous for global regex objects to
participate
in grammars. It's best to build regex grammars from a single thread. Once
built,
the resulting regex grammar can be executed from multiple threads without
-problems.
-
-[h2 Beware Nested Quantifiers]
+problems.\n
+对于静态regex，你可以通过把regex嵌入另一个regex中来创建语法。
+在编译外层的regex时，外层和内层的regex对象，以及所有它们直接或间接引用到的
regex对象，都会被修改。
+因此，这对于参与到语法中的全局regex对象而言是很危险的。最好是从单个线程中构
建regex语法。
+一旦构建完成，所得到的regex语法就可以在多线程下执行，没有问题。
+
+[h2 Beware Nested Quantifiers 小心嵌套的数量词]
This is a pitfall common to many regular expression engines. Some patterns
can
cause exponentially bad performance. Often these patterns involve one
quantified
term nested withing another quantifier, such as `"(a*)*"`, although in many
cases, the problem is harder to spot. Beware of patterns that have nested
-quantifiers.
+quantifiers.\n
+这是一个很多正则表达式都会犯的错误。有些模式会引起指数级的低性能。
+通常，这些模式含有一个嵌套在另一个数量词中的数量词，如 `"(a*)*"`，在多数情
况下，这个问题很难被指出。
+要当心那些带有嵌套数量词的模式。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/tokenization.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/tokenization.qbk Sun Aug 1 20:47:57 2010
@@ -5,12 +5,14 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section String Splitting and Tokenization]
+[section:string_splitting_and_tokenization String Splitting and
Tokenization 字符串分拆和记号化]
_regex_token_iterator_ is the Ginsu knife of the text manipulation world.
It slices! It dices! This section describes
-how to use the highly-configurable _regex_token_iterator_ to chop up input
sequences.
-
-[h2 Overview]
+how to use the highly-configurable _regex_token_iterator_ to chop up input
sequences.\n
+_regex_token_iterator_ 是文本处理世界中的Ginsu刀。它可以切片！也可以切块！
+本节将描述如何使用高可配置的 _regex_token_iterator_ 来将输入序列剁碎。
+
+[h2 Overview 概述]
You initialize a _regex_token_iterator_ with an input sequence, a regex,
and some optional configuration parameters.
The _regex_token_iterator_ will use _regex_search_ to find the first place
in the sequence that the regex matches. When
@@ -19,13 +21,20 @@
return a string corresponding to a particular marked sub-expression, or
even the part of the sequence that ['didn't] match.
When you increment the _regex_token_iterator_, it will move to the next
token. Which token is next depends on the configuration
parameters. It could simply be a different marked sub-expression in the
current match, or it could be part or all of the
-next match. Or it could be the part that ['didn't] match.
-
-As you can see, _regex_token_iterator_ can do a lot. That makes it hard to
describe, but some examples should make it clear.
-
-[h2 Example 1: Simple Tokenization]
-
-This example uses _regex_token_iterator_ to chop a sequence into a series
of tokens consisting of words.
+next match. Or it could be the part that ['didn't] match.\n
+你要用一个输入序列、一个regex和一些可选的配置参数来初始化
_regex_token_iterator_。_regex_token_iterator_ 会用 _regex_search_
+在输入序列中找到匹配regex的第一个地方。当你对它解引用
时，_regex_token_iterator_ 以 `std::basic_string<>` 的形式返回一个['记号]。
+它返回哪个字符串取决于那些配置参数。缺省下，它返回一个与全匹配相对应的字符
串，不过它也可以返回一个与某个特定子表达式相对应的字符串，
+甚至是不被匹配的那部分串。当你以 _regex_token_iterator_ 进行递增时，它将移
至下一个记号。哪个记号是下一个，也取决于配置参数。
+它可以只是当前匹配中的另一个子表达式，也可以是下一个匹配的部分或全部。或者
可以是不被匹配的部分。
+
+As you can see, _regex_token_iterator_ can do a lot. That makes it hard to
describe, but some examples should make it clear.\n
+如你所见，_regex_token_iterator_ 可以做很多事情。这使得它很难被说得明白，不
过来些例子可以清楚一点。
+
+[h2 Example 1: Simple Tokenization 示例1：简单的记号化]
+
+This example uses _regex_token_iterator_ to chop a sequence into a series
of tokens consisting of words.\n
+这个例子用 _regex_token_iterator_ 来将一个序列分成一系列由单词组成的记号。
std::string input("This is his face");
sregex re = +_w; // find a word
@@ -37,7 +46,8 @@
std::ostream_iterator< std::string > out_iter( std::cout, "\n" );
std::copy( begin, end, out_iter );
-This program displays the following:
+This program displays the following:\n
+程序输出如下：
[pre
This
@@ -46,12 +56,14 @@
face
]
-[h2 Example 2: Simple Tokenization, Reloaded]
+[h2 Example 2: Simple Tokenization, Reloaded 示例2：简单的记号化，再来]
This example also uses _regex_token_iterator_ to chop a sequence into a
series of tokens consisting of words,
but it uses the regex as a delimiter. When we pass a `-1` as the last
parameter to the _regex_token_iterator_
constructor, it instructs the token iterator to consider as tokens those
parts of the input that ['didn't]
-match the regex.
+match the regex.\n
+这个例子也是用 _regex_token_iterator_ 来将一个序列分为一系列由单词组成的记
号，不过它是用regex来作为分隔符。
+当我们传入一个 -1 作为 _regex_token_iterator_ 构造函数的最后一个参数时，它
会令该记号迭代器将输入中不被regex匹配的部分视为记号。
std::string input("This is his face");
sregex re = +_s; // find white space
@@ -63,7 +75,8 @@
std::ostream_iterator< std::string > out_iter( std::cout, "\n" );
std::copy( begin, end, out_iter );
-This program displays the following:
+This program displays the following:\n
+程序输出如下：
[pre
This
@@ -72,12 +85,15 @@
face
]
-[h2 Example 3: Simple Tokenization, Revolutions]
+[h2 Example 3: Simple Tokenization, Revolutions 示例3：简单的记号化，革命]
This example also uses _regex_token_iterator_ to chop a sequence
containing a bunch of dates into a series of
tokens consisting of just the years. When we pass a positive integer
[^['N]] as the last parameter to the
_regex_token_iterator_ constructor, it instructs the token iterator to
consider as tokens only the [^['N]]-th
-marked sub-expression of each match.
+marked sub-expression of each match.\n
+这个例子还是用 _regex_token_iterator_ 来将一个含有多个日期的序列分成一系列
仅由年份组成的记号。
+当我们把一个正整数 [^['N]] 作为 _regex_token_iterator_ 构造函数的最后一个参
数传入时，它会令该记号迭代器仅将每次匹配中的第
+[^['N]]- 个子表达式视为记号。
std::string input("01/02/2003 blahblah 04/23/1999 blahblah
11/13/1981");
sregex re = sregex::compile("(\\d{2})/(\\d{2})/(\\d{4})"); // find a
date
@@ -89,7 +105,8 @@
std::ostream_iterator< std::string > out_iter( std::cout, "\n" );
std::copy( begin, end, out_iter );
-This program displays the following:
+This program displays the following:\n
+程序输出如下：
[pre
2003
@@ -97,12 +114,14 @@
1981
]
-[h2 Example 4: Not-So-Simple Tokenization]
+[h2 Example 4: Not-So-Simple Tokenization 示例4：不太简单的记号化]
This example is like the previous one, except that instead of tokenizing
just the years, this program
turns the days, months and years into tokens. When we pass an array of
integers [^['{I,J,...}]] as the last
parameter to the _regex_token_iterator_ constructor, it instructs the
token iterator to consider as tokens the
-[^['I]]-th, [^['J]]-th, etc. marked sub-expression of each match.
+[^['I]]-th, [^['J]]-th, etc. marked sub-expression of each match.\n
+这个例子与上一个相似，不过它不是仅将年份记号化，它把日、月、年全部放入记号
中。当我们传入一个整数数组 [^['{I,J,...}]] 作为
+_regex_token_iterator_ 构造函数的最后一个参数时，它会令该记号迭代器将每次匹
配中的第 [^['I]]- 个，第 [^['J]]- 个子表达式等等，视为记号。
std::string input("01/02/2003 blahblah 04/23/1999 blahblah
11/13/1981");
sregex re = sregex::compile("(\\d{2})/(\\d{2})/(\\d{4})"); // find a
date
@@ -115,7 +134,8 @@
std::ostream_iterator< std::string > out_iter( std::cout, "\n" );
std::copy( begin, end, out_iter );
-This program displays the following:
+This program displays the following:\n
+程序输出如下：
[pre
02
@@ -132,6 +152,9 @@
The `sub_matches` array instructs the _regex_token_iterator_ to first take
the value of the 2nd sub-match, then
the 1st sub-match, and finally the 3rd. Incrementing the iterator again
instructs it to use _regex_search_ again
to find the next match. At that point, the process repeats -- the token
iterator takes the value of the 2nd
-sub-match, then the 1st, et cetera.
+sub-match, then the 1st, et cetera.\n
+这个 `sub_matches` 数据使得 _regex_token_iterator_ 首先取出第2个子匹配的
值，然后是第1个子匹配，最后是第3个。
+再次递增该迭代器将使它再次调用 _regex_search_ 来查找下一个匹配。然后重复以
上过程 --
+该记号迭代器取出第2个子匹配的值，然后是第1个，依此类推。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/tracking_ptr.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/tracking_ptr.qbk Sun Aug 1 20:47:57 2010
@@ -5,62 +5,86 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Cycle collection with [^tracking_ptr<>]]
+[section:cycle_collection_with___tracking_ptr___ Cycle collection with
[^tracking_ptr<>] 用 [^tracking_ptr<>] 进行循环收集]
In xpressive, regex objects can refer to each other and themselves by
value or by reference.
In addition, they ref-count their referenced regexes to keep them alive.
This creates the possibility
for cyclic reference counts, and raises the possibility of memory leaks.
xpressive avoids leaks
by using a type called `tracking_ptr<>`. This doc describes at a high
level how `tracking_ptr<>`
-works.
-
-[h2 Constraints]
-
-Our solution must meet the following design constraints:
+works.\n
+在xpressive中，regex对象可以以值方式或引用方式相互引用或自身引用。另外，它
们对所引用的regexes进行引用计数以确保它们的生存。
+这样就可能产生循环的引用计数，并可能导致内存泄漏。xpressive通过使用一个名
为 `tracking_ptr<>` 的类型来防止泄漏。
+本文档从较高的层面来说明 `tracking_ptr<>` 是如何工作的。
+
+[h2 Constraints 约束]
+
+Our solution must meet the following design constraints:\n
+我们的解决方案必须符合以下设计约束：
* No dangling references: All objects referred to directly or indirectly
must be kept alive
- as long as the references are needed.
-* No leaks: all objects must be freed eventually.
+ as long as the references are needed.\n
+ 没有悬空的引用：所有被直接或间接的对象必须在引用需要的期间保持生存。
+* No leaks: all objects must be freed eventually.\n
+ 没有泄漏：所有对象最后必须被释放。
* No user intervention: The solution must not require users to explicitly
invoke some cycle
- collection routine.
+ collection routine.\n
+ 没有用户干预：解决方案必须不需要用户显式地执行一些周期性的收集例程。
* Clean-up is no-throw: The collection phase will likely be called from a
destructor, so it
- must never throw an exception under any circumstance.
-
-[h2 Handle-Body Idiom]
+ must never throw an exception under any circumstance.\n
+ 无抛出的清理：收集的阶段通常都是从析构函数调用的，所以在任何情况下都必须
不会抛出异常。
+
+[h2 Handle-Body Idiom 句柄-实体惯用法]
To use `tracking_ptr<>`, you must separate your type into a handle and a
body. In the case of
xpressive, the handle type is called `basic_regex<>` and the body is
called `regex_impl<>`. The
-handle will store a `tracking_ptr<>` to the body.
+handle will store a `tracking_ptr<>` to the body.\n
+要使用 `tracking_ptr<>`，你必须将你的类型分为句柄和实体。对于xpressive，句
柄类型名为 `basic_regex<>`
+而实体类型名为 `regex_impl<>`。句柄将保存一个到实体的 `tracking_ptr<>`。
The body type must inherit from `enable_reference_tracking<>`. This gives
the body the bookkeeping
-data structures that `tracking_ptr<>` will use. In particular, it gives
the body:
-
-# `std::set<shared_ptr<body> > refs_` : collection of bodies to which this
body refers, and
-# `std::set<weak_ptr<body> > deps_` : collection of bodies which refer to
this body.
-
-[h2 References and Dependencies]
+data structures that `tracking_ptr<>` will use. In particular, it gives
the body:\n
+实体类型必须继承自 `enable_reference_tracking<>`。这为实体提供了一些
`tracking_ptr<>` 会用到的簿记数据结构。特定地，实体中有：
+
+# `std::set<shared_ptr<body> > refs_` : collection of bodies to which this
body refers, and\n
+ `std::set<shared_ptr<body> > refs_` : 收集了该实体所引用的实体，和
+# `std::set<weak_ptr<body> > deps_` : collection of bodies which refer to
this body.\n
+ `std::set<weak_ptr<body> > deps_` : 收集了引用了该实体的实体。
+
+[h2 References and Dependencies 引用与依赖]
We refer to (1) above as the "references" and (2) as the "dependencies".
It is crucial to the
understanding of `tracking_ptr<>` to recognize that the set of references
includes both those
objects that are referred to directly as well as those that are referred
to indirectly (that
is, through another reference). The same is true for the set of
dependencies. In other words,
-each body holds a ref-count directly to every other body that it needs.
+each body holds a ref-count directly to every other body that it needs. \n
+我们将以上的(1)称为"引用"，而(2)称为"依赖"。要弄明白 `tracking_ptr<>`，很重
要的一点是，
+要知道这个"引用"集合既包含直接引用的对象，也包含那些间接引用的对象(即通过另
一个引用来引用的)。
+对于"依赖"集合也同样如此。换句话说，每一个实体都持有对它所需的每一个其它实
体的直接引用计数。
Why is this important? Because it means that when a body no longer has a
handle referring
-to it, all its references can be released immediately without fear of
creating dangling references.
-
-References and dependencies cross-pollinate. Here's how it works:
+to it, all its references can be released immediately without fear of
creating dangling references. \n
+为什么这点很重要？因为它意味着当一个实体不再有某个句柄引向它的时候，它的所
有引用物就可以立即释放，而不用害怕会导致悬空的引用。
+
+References and dependencies cross-pollinate. Here's how it works:\n
+引用和依赖是交叉pollinate的。以下是它的工作方式：
# When one object acquires another as a reference, the second object
acquires the first as
- a dependency.
+ a dependency.\n
+ 当一个对象获得另一个对象作为引用时，第二个对象获得第一个对象作为依赖。
# In addition, the first object acquires all of the second object's
references, and the second
- object acquires all of the first object's dependencies.
-# When an object picks up a new reference, the reference is also added to
all dependent objects.
+ object acquires all of the first object's dependencies.\n
+ 此外，第一个对象获得第二个对象的所有引用，且第二个对象获得第一个对象的所
有依赖。
+# When an object picks up a new reference, the reference is also added to
all dependent objects.\n
+ 当一个对象增加一个新的引用时，该引用也会被增加到所有依赖对象中。
# When an object picks up a new dependency, the dependency is also added
to all referenced
- objects.
+ objects.\n
+ 当一个对象增加一个新的依赖时，该依赖也会被增加到所有引用对象中。
# An object is never allowed to have itself as a dependency. Objects may
have themselves as
- references, and often do.
-
-Consider the following code:
+ references, and often do.\n
+ 对象不允许以自己为依赖。但对象可以把自己作为引用，而且经常如此。
+
+Consider the following code:\n
+考虑以下代码：
sregex expr;
{
@@ -70,7 +94,8 @@
expr = term >> *(('+' >> term) | ('-' >> term)); // (4)
} // (5)
-Here is how the references and dependencies propagate, line by line:
+Here is how the references and dependencies propagate, line by line:\n
+以下逐行列出引用和依赖是如何传播的：
[table
[[Expression][Effects]]
@@ -101,16 +126,23 @@
This shows how references and dependencies propagate when creating cycles
of objects. After
line (4), which closes the cycle, every object has a ref-count on every
other object, even
-to itself. So how does this not leak? Read on.
-
-[h2 Cycle Breaking]
+to itself. So how does this not leak? Read on.\n
+这显示了在创建循环对象时，它们的引用和依赖是如何传播的。
+在第(4)行之后，当循环结束时，每个对象都有到每个其它对象的引用计数，甚至是到
它们自身的引用。
+那么，怎样做才能不泄漏呢？继续看下去。
+
+[h2 Cycle Breaking 打破循环]
Now that the bodies have their sets of references and dependencies, the
hard part is done.
All that remains is to decide when and where to break the cycle. That is
the job of `tracking_ptr<>`,
which is part of the handle. The `tracking_ptr<>` holds 2 `shared_ptr`s.
The first, obviously,
is the `shared_ptr<body>` -- the reference to the body to which this
handle refers. The other
`shared_ptr` is used to break the cycle. It ensures that when all the
handles to a body go out
-of scope, the body's set of references is cleared.
+of scope, the body's set of references is cleared.\n
+现在实体中存有它们的引用集合和依赖集合，困难的部分已经完成。剩下的就是决定
何时以及在何处打破这个循环。
+这是 `tracking_ptr<>` 的任务，它是句柄的组成部分。`tracking_ptr<>` 持有2个
` shared_ptr`。
+显然，第一个是 `shared_ptr<body>` -- 到该句柄所引向的实体的引用。另一个
`shared_ptr` 则用于打破循环。
+它确保当指向某个实体的所有句柄离开作用域时，实体的引用集合被清除。
This suggests that more than one handle can refer to a body. In fact,
`tracking_ptr<>` gives
you copy-on-write semantics -- when you copy a handle, the body is shared.
That makes copies
@@ -118,11 +150,17 @@
happens, the ref count to the body might still be greater than 0 because
some other body (or
this body itself!) might be holding a reference to it. However, we are
certain that the cycle-breaker's
ref-count goes to 0 because the cycle-breaker only lives in handles. No
more handles, no more
-cycle-breakers.
+cycle-breakers.\n
+可以有一个以上的句柄引向同一个实体。事实上，`tracking_ptr<>` 具有写时复制的
语义 -- 当你复制一个句柄时，其实体是共享的。
+这样令得复制操作非常高效。最后，指向某个特定实体的所有句柄离开作用域。
+当此事发生时，该实体的引用计数可能还会大于0，因为某些其它的实体(或该实体本
身)可能持有它的引用。
+不过，我们可以肯定循环破坏者的引用计数为0，因为循环破坏者只存在于句柄中。没
有其它句柄，也没有其它循环破坏者。
What does the cycle-breaker do? Recall that the body has a set of
references of type
`std::set<shared_ptr<body> >`. Let's call this type "references_type". The
cycle-breaker is a
-`shared_ptr<references_type>`. It uses a custom deleter, which is defined
as follows:
+`shared_ptr<references_type>`. It uses a custom deleter, which is defined
as follows:\n
+循环破坏者都做些什么呢？记得在实体中有一个引用集合，其类型为
`std::set<shared_ptr<body> >`。
+我们称之为"references_type"。循环破坏者是一个
`shared_ptr<references_type>`。它使用一个定制的删除器，定义如下：
template<typename DerivedT>
struct reference_deleter
@@ -134,11 +172,14 @@
};
The job of to the cycle breaker is to ensure that when the last handle to
a body goes away,
-the body's set of references is cleared. That's it.
+the body's set of references is cleared. That's it.\n
+循环破坏者的任务是确保当一个实体的最后一个句柄离开时，实体的引用集合被清
除。这就是了。
We can clearly see how this guarantees that all bodies are cleaned up
eventually. Once every
handle has gone out of scope, all the bodies' sets of references will be
cleared, leaving none
-with a non-zero ref-count. No leaks, guaranteed.
+with a non-zero ref-count. No leaks, guaranteed.\n
+我们可以清楚地看到，它是如何保证最后所有实体都被清除。
+一旦所有句柄离开作用域，所有实体的引用集合将被清除，不会留下非零引用计数的
东西。保证没有泄漏。
It's a bit harder to see how this guarantees no dangling references.
Imagine that there are 3
bodies: A, B and C. A refers to B which refers to C. Now all the handles
to B go out of scope,
@@ -146,14 +187,20 @@
is being used (indirectly) by A? It doesn't. This situation can never
occur because we propagated
the references and dependencies above such that A will be holding a
reference directly to C
in addition to B. When B's set of references is cleared, no bodies get
deleted, because they
-are all still in use by A.
-
-[h2 Future Work]
+are all still in use by A.\n
+要看出它如何保证不会有悬空引用有一点难度。想象有3个实体：A, B 和 C。A 引用
B，B 引用 C。
+现在B的所有句柄离开了作用域，所以B的引用集合被清除。这是否意味着即使 C 还
被 A (间接)使用着，它也会被删除？
+不会的。这种情况永远不会发生，因为我们传播了引用和依赖，这样A除了持有B的引
用，也直接持有到C的引用。
+当B的引用集合被清除时，没有实体被删除，因为它们全都还被 A 使用着。
+
+[h2 Future Work 未来的工作]
All these `std::set`s and `shared_ptr`s and `weak_ptr`s! Very inefficient.
I used them because
-they were handy. I could probably do better.
-
-Also, some objects stick around longer than they need to. Consider:
+they were handy. I could probably do better.\n
+这些所有的 `std::sets` 和 `shared_ptr`s 和 `weak_ptr`s! 都非常低效。我完全
是因为方便才使用它们的。我可能可以做得更好些。
+
+Also, some objects stick around longer than they need to. Consider:\n
+还有，有些对象存在的时间会比所需的时间长一些。例如：
sregex b;
{
@@ -167,6 +214,8 @@
grow. It never shrinks, even when some references are no longer needed.
For xpressive this
isn't an issue. The graphs of referential objects generally stay small and
isolated. If someone
were to try to use `tracking_ptr<>` as a general
ref-count-cycle-collection mechanism, this problem
-would have to be addressed.
+would have to be addressed.\n
+由于引用和依赖的传播方式，保存引用的 `std::set` 只增不减。即使有些引用已不
再需要，它也不会缩减。对于xpressive来说这不是一个问题。
+对象的引用图通常都很小且相互独立。如果有人试图把 `tracking_ptr<>` 用作通用
的引用计数循环收集机制，这个问题就必须要解决。
[endsect]
=======================================
--- /trunk/libs/xpressive/doc/traits.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/traits.qbk Sun Aug 1 20:47:57 2010
@@ -5,27 +5,34 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Localization and Regex Traits]
-
-[h2 Overview]
+[section:localization_and_regex_traits Localization and Regex Traits 本地化
和Regex Traits ]
+
+[h2 Overview 概述 ]
Matching a regular expression against a string often requires
locale-dependent information. For example,
how are case-insensitive comparisons performed? The locale-sensitive
behavior is captured in a traits class.
xpressive provides three traits class templates: `cpp_regex_traits<>`,
`c_regex_traits<>` and `null_regex_traits<>`.
The first wraps a `std::locale`, the second wraps the global C locale, and
the third is a stub traits type for
use when searching non-character data. All traits templates conform to the
-[link boost_xpressive.user_s_guide.concepts.traits_requirements Regex
Traits Concept].
-
-[h2 Setting the Default Regex Trait]
+[link boost_xpressive.user_s_guide.concepts.traits_requirements Regex
Traits Concept].\n
+将一个正则表达式与一个字符串进行匹配，通常需要与locale有关的信息。例如，如
何执行大小写不敏感的比较？
+与locale有关的行为被收集到一个 traits 类中。xpressive提供了三个traits类模
板：`cpp_regex_traits<>`, `c_regex_traits<>` 和
+`null_regex_traits<>`。第一个包装了一个 `std::locale`，第二个包装了全部 C
locale，第三个则是在进行非字符数据搜索时使用的stub traits类型。
+所有traits模板都符合 [link
boost_xpressive.user_s_guide.concepts.traits_requirements Regex Traits 概念
]。
+
+[h2 Setting the Default Regex Trait 设置缺省的Regex Trait ]
By default, xpressive uses `cpp_regex_traits<>` for all patterns. This
causes all regex objects to use
the global `std::locale`. If you compile with
`BOOST_XPRESSIVE_USE_C_TRAITS` defined, then xpressive will use
-`c_regex_traits<>` by default.
-
-[h2 Using Custom Traits with Dynamic Regexes]
+`c_regex_traits<>` by default.\n
+缺省地，xpressive对所有模式使用 `cpp_regex_traits<>`。这使得所有regex对象都
使用全局的 `std::locale`。
+如果你在编译时定义了 `BOOST_XPRESSIVE_USE_C_TRAITS`，则xpressive将缺省使用
`c_regex_traits<>`。
+
+[h2 Using Custom Traits with Dynamic Regexes 对动态Regex使用定制的Traits ]
To create a dynamic regex that uses a custom traits object, you must use
_regex_compiler_.
-The basic steps are shown in the following example:
+The basic steps are shown in the following example:\n
+要创建一个使用定制的traits对象的动态regex，你必须使用 _regex_compiler_。以
下例子示范了基本的步骤：
// Declare a regex_compiler that uses the global C locale
regex_compiler<char const *, c_regex_traits<char> > crxcomp;
@@ -37,12 +44,14 @@
cregex cpprx = cpprxcomp.compile( "\\w+" );
The `regex_compiler` objects act as regex factories. Once they have been
imbued with a locale,
-every regex object they create will use that locale.
-
-[h2 Using Custom Traits with Static Regexes]
+every regex object they create will use that locale.\n
+`regex_compiler` 对象就象一个regex工厂。一旦它们被注入一个locale，那么他们
所创建的每一个regex对象都将使用那个locale。
+
+[h2 Using Custom Traits with Static Regexes 对静态Regex使用定制的Traits ]
If you want a particular static regex to use a different set of traits,
you can use the special `imbue()`
-pattern modifier. For instance:
+pattern modifier. For instance:\n
+如果你想某个特定的静态regex使用一个不同的traits集，你可以使用特定的
`imbue()` 模式修饰符。例如：
// Define a regex that uses the global C locale
c_regex_traits<char> ctraits;
@@ -57,21 +66,27 @@
sregex cpprx2 = imbue(loc)( +_w );
The `imbue()` pattern modifier must wrap the entire pattern. It is an
error to `imbue` only
-part of a static regex. For example:
+part of a static regex. For example:\n
+`imbue()` 模式修饰符必须将整个模式包起来。只用 `imbue` 包裹一个静态regex的
部分是错误的。例如：
// ERROR! Cannot imbue() only part of a regex
sregex error = _w >> imbue(loc)( _w );
-[h2 Searching Non-Character Data With [^null_regex_traits]]
+[h2 Searching Non-Character Data With [^null_regex_traits] 搜索带
[^null_regex_traits]的非字符数据]
With xpressive static regexes, you are not limitted to searching for
patterns in character sequences.
You can search for patterns in raw bytes, integers, or anything that
conforms to the
[link boost_xpressive.user_s_guide.concepts.chart_requirements Char
Concept]. The `null_regex_traits<>` makes it simple. It is a
stub implementation of the [link
boost_xpressive.user_s_guide.concepts.traits_requirements Regex Traits
Concept]. It recognizes
-no character classes and does no case-sensitive mappings.
+no character classes and does no case-sensitive mappings.\n
+对于xpressive静态regexes，你并没有被限于只能对字符序列进行模式搜索。
+你可以对裸字节、整数或其它任意符合 [link
boost_xpressive.user_s_guide.concepts.chart_requirements Char 概念] 的东西进
行模式搜索。
+`null_regex_traits<>` 令此非常简单。它是 [link
boost_xpressive.user_s_guide.concepts.traits_requirements Regex Traits 概念]
+的一个stub实现。它不识别任何字符类，也没有大小写映射。
For example, with `null_regex_traits<>`, you can write a static regex to
find a pattern in a
-sequence of integers as follows:
+sequence of integers as follows:\n
+例如，使用 `null_regex_traits<>`，你可以写一个如下的静态regex来在一个整数序
列中查找模式：
// some integral data to search
int const data[] = {0, 1, 2, 3, 4, 5, 6};
=======================================
--- /trunk/libs/xpressive/doc/xpressive.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/xpressive/doc/xpressive.qbk Sun Aug 1 20:47:57 2010
@@ -61,11 +61,13 @@
[include preface.qbk]
-[section User's Guide]
+[section:user_s_guide User's Guide 用户指南]
This section describes how to use xpressive to accomplish text
manipulation and
parsing tasks. If you are looking for detailed information regarding
specific
-components in xpressive, check the [link xpressive.reference Reference]
section.
+components in xpressive, check the [link xpressive.reference Reference]
section.\n
+本节描述如何使用 xpressive 来完成文本处理和分析任务。如果你要查找与
xpressive 中特定组件相关的详细信息，请看
+[link xpressive.reference 参考手册] 一节。
[include introduction.qbk]
@@ -73,11 +75,13 @@
[include quick_start.qbk]
-[section Creating a Regex Object]
+[section:creating_a_regex_object Creating a Regex Object 创建一个Regex对象]
When using xpressive, the first thing you'll do is create a _basic_regex_
object. This section goes
over the nuts and bolts of building a regular expression in the two
dialects xpressive supports: static
-and dynamic.
+and dynamic.\n
+使用xpressive时，你要做的第一件事就是，创建一个 _basic_regex_ 对象。
+本节将详细介绍在静态和动态两种xpressive支持下正则表达式的构建。
[include static_regexes.qbk]
@@ -115,7 +119,7 @@
[include acknowledgements.qbk]
-[section Appendices]
+[section:appendices Appendices 附录]
[include history.qbk]
@@ -125,7 +129,7 @@
[include perf.qbk]
-[section Appendix 5: Implementation Notes]
+[section:appendix_5__implementation_notes Appendix 5: Implementation Notes
附录5：实现说明]
[include tracking_ptr.qbk]
Other related posts:
- » [boost-doc-zh] r422 committed - 翻译 xpressive 库的 qbk/xml 文件 - boost-doc-zh
