[boost-doc-zh] r368 committed - 翻译 program_options, proto 库的xml/qbk文件
- From: boost-doc-zh@xxxxxxxxxxxxxx
- To: boost-doc-zh-notify@xxxxxxxxxxxxx
- Date: Mon, 18 Jan 2010 07:12:05 +0000
Revision: 368
Author: alai04
Date: Sun Jan 17 23:11:16 2010
Log: 翻译 program_options, proto 库的xml/qbk文件
http://code.google.com/p/boost-doc-zh/source/detail?r=368
Modified:
/trunk/index.html
/trunk/libs/program_options/doc/acknowledgements.xml
/trunk/libs/program_options/doc/design.xml
/trunk/libs/program_options/doc/howto.xml
/trunk/libs/program_options/doc/overview.xml
/trunk/libs/program_options/doc/program_options.xml
/trunk/libs/program_options/doc/tutorial.xml
/trunk/libs/proto/doc/acknowledgements.qbk
/trunk/libs/proto/doc/back_end.qbk
/trunk/libs/proto/doc/calculator.qbk
/trunk/libs/proto/doc/conventions.qbk
/trunk/libs/proto/doc/examples.qbk
/trunk/libs/proto/doc/front_end.qbk
/trunk/libs/proto/doc/getting_started.qbk
/trunk/libs/proto/doc/glossary.qbk
/trunk/libs/proto/doc/hello_world.qbk
/trunk/libs/proto/doc/history.qbk
/trunk/libs/proto/doc/implementation.qbk
/trunk/libs/proto/doc/installation.qbk
/trunk/libs/proto/doc/intermediate_form.qbk
/trunk/libs/proto/doc/preface.qbk
/trunk/libs/proto/doc/proto.qbk
/trunk/libs/proto/doc/rationale.qbk
/trunk/libs/proto/doc/resources.qbk
=======================================
--- /trunk/index.html Mon Nov 10 00:52:21 2008
+++ /trunk/index.html Sun Jan 17 23:11:16 2010
@@ -9,7 +9,7 @@
<a href="index.html">
<img src="boost.png" alt="boost.png (6897 bytes)" align="middle"
border="0" height="86" width="277" /></a></td>
<td align="middle" width="337">
- <h2 style="text-align: center;">Release 1.37.0</h2>
+ <h2 style="text-align: center;">Release 1.41.0</h2>
</td>
</tr>
</tbody></table>
=======================================
--- /trunk/libs/program_options/doc/acknowledgements.xml Mon Dec 28
23:05:14 2009
+++ /trunk/libs/program_options/doc/acknowledgements.xml Sun Jan 17
23:11:16 2010
@@ -6,7 +6,7 @@
%entities;
]>
<section>
- <title>Acknowledgements</title>
+ <title>Acknowledgements 鸣谢</title>
<para>I'm very gratefull to all the people who helped with the
development,
by discussion, fixes, and as users. It was pleasant
=======================================
--- /trunk/libs/program_options/doc/design.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/program_options/doc/design.xml Sun Jan 17 23:11:16 2010
@@ -6,53 +6,66 @@
%entities;
]>
<section id="program_options.design">
- <title>Design Discussion</title>
-
- <para>This section focuses on some of the design questions.
+ <title>Design Discussion 设计讨论</title>
+
+ <para>This section focuses on some of the design questions.<sbr/>
+ 本节关注一些设计的问题。
</para>
<section id="program_options.design.unicode">
- <title>Unicode Support</title>
+ <title>Unicode Support Unicode支持</title>
<para>Unicode support was one of the features specifically requested
during the formal review. Throughout this document "Unicode support"
is
a synonym for "wchar_t" support, assuming that "wchar_t" always uses
Unicode encoding. Also, when talking about "ascii" (in lowercase)
we'll
not mean strict 7-bit ASCII encoding, but rather "char" strings in
local
- 8-bit encoding.
+ 8-bit encoding.<sbr/>
+ Unicode 支持是在正式评审时被请求增加的一个特性。在本文档中，"Unicode
支持"
+ 就是 "wchar_t" 支持的同义词，"wchar_t" 总是使用 Unicode 编码。同样，
+ 在谈论 "ascii" (小写)时，我们并不是指7-位 ASCII 编码，而是8位编码
的 "char" 字符串。
</para>
<para>
Generally, "Unicode support" can mean
- many things, but for the program_options library it means that:
+ many things, but for the program_options library it means that:<sbr/>
+ 通常，"Unicode 支持" 可以代表很多事情，但对于
program_options 库而言，它代表：
<itemizedlist>
<listitem>
<para>Each parser should accept either <code>char*</code>
or <code>wchar_t*</code>, correctly split the input into option
- names and option values and return the data.
+ names and option values and return the data.<sbr/>
+ 每个分析器接受 <code>char*</code> 或 <code>wchar_t*</code>,
+ 正确地将输入分解为选项名和选项值并返回数据。
</para>
</listitem>
<listitem>
<para>For each option, it should be possible to specify whether
the conversion
- from string to value uses ascii or Unicode.
+ from string to value uses ascii or Unicode.<sbr/>
+ 对于每个选项，可能要指定是否使用 ascii 或 Unicode 从字符串转换
为值。
</para>
</listitem>
<listitem>
- <para>The library guarantees that:
+ <para>The library guarantees that:<sbr/>
+ 程序库保证：
<itemizedlist>
<listitem>
- <para>ascii input is passed to an ascii value without
change
+ <para>ascii input is passed to an ascii value without
change<sbr/>
+ ascii 输入传递给 ascii 值时不会改变
</para>
</listitem>
<listitem>
- <para>Unicode input is passed to a Unicode value without
change</para>
+ <para>Unicode input is passed to a Unicode value without
change<sbr/>
+ Unicode 输入传递给 Unicode 值时不会改变</para>
</listitem>
<listitem>
<para>ascii input passed to a Unicode value, and Unicode
input
passed to an ascii value will be converted using a
codecvt
- facet (which may be specified by the user).
+ facet (which may be specified by the user).<sbr/>
+ ascii 输入传递给 Unicode 值，以及 Unicode 输入传递给
ascii 值时，
+ 将使用 codecvt facet (可以由用户指定)来转换。
</para>
</listitem>
</itemizedlist>
@@ -71,14 +84,22 @@
Unicode strings, then the author will likely to use ascii options,
which
would make the library unusable inside Unicode
applications. Essentially, it would be necessary to provide two
versions
- of the library -- ascii and Unicode.
+ of the library -- ascii and Unicode.<sbr/>
+ 重点在于存在 "ascii options" 与 "Unicode options" 需要一起处理的可
能。
+ 这有两方面原因。首先，对于一个给定的类型，你可能没有代码来从 Unicode
字符串中取出选项值，
+ 要求写出这样的代码也不太好。其次，想象一个带有一些选项的可重用程序
库，
+ 它要在接口中提供这些选项描述。如果<emphasis>所有</emphasis>选项要么都
是 ascii 要么都是 Unicode,
+ 而该库没有使用 Unicode 字符串，那么作者就很可能会使用 ascii 选项，
+ 这将使得该库不能用于 Unicode 应用。理想的情况是，需要提供两个版本的
库 -- ascii 和 Unicode.
</para>
<para>Another important point is that ascii strings are passed though
without modification. In other words, it's not possible to just
convert
ascii to Unicode and process the Unicode further. The problem is
that the
default conversion mechanism -- the <code>codecvt</code> facet --
might
- not work with 8-bit input without additional setup.
+ not work with 8-bit input without additional setup.<sbr/>
+ 另一个重点是，ascii 串在传递时不会被修改。换句话说，不能将 ascii 转换
为 Unicode 以进一步处理 Unicode.
+ 问题是缺省的转换机制 -- <code>codecvt</code> facet -- 不能在没有额外
设置的情况下用于 8-位的输入。
</para>
<para>The Unicode support outlined above is not complete. For example,
we
@@ -88,13 +109,19 @@
related to internationalization, which has it's own
complexities. E.g. if option names depend on current locale, then all
program parts and other parts which use the name must be
- internationalized too.
+ internationalized too.<sbr/>
+ 以上的 Unicode 支持要点是不完整的。例如，我们不支持 Unicode 选项名。
+ Unicode 支持是困难的，需要一个 Boost-范围的解决方案。甚至于比较两个任
意的 Unicode 串都不简单。
+ 最后，在选项名中使用 Unicode 涉及到国际化，它本身就很复杂。即如果选项
名依赖于当前的 locale,
+ 那么所有的使用该选项名的程序部分都必须被国际化。
</para>
<para>The primary question in implementing the Unicode support is
whether
to use templates and <code>std::basic_string</code> or to use some
internal encoding and convert between internal and external
encodings on
- the interface boundaries.
+ the interface boundaries. <sbr/>
+ 实现 Unicode 支持的主要问题是，使用模板和
<code>std::basic_string</code>，
+ 还是使用一些内部编码以及在接口上对内外部编码间进行转换。
</para>
<para>The choice, mostly, is between code size and execution
@@ -105,27 +132,37 @@
necessarily make conversions in a number of places and will be
somewhat slower.
Since speed is generally not an issue for this library, the second
solution looks more attractive, but we'll take a closer look at
- individual components.
+ individual components.<sbr/>
+ 通常，要在代码大小和执行时间上进行选择。模板的解决方案要么将库代码链
接入每个应用程序来使用库
+ (从而不能共享库), 要么在共享库中提供显式实例化(增加了库的大小)。
+ 而基于内部编码的解决方案则需要在多处进行转换而稍微慢些。由于在本库中
速度不是太大问题，
+ 因此第二个方案看起来更吸引，但是我们再来仔细看看个别组件。
</para>
- <para>For the parsers component, we have three choices:
+ <para>For the parsers component, we have three choices:<sbr/>
+ 对于分析器组件，我们有三种选择：
<itemizedlist>
<listitem>
<para>Use a fully templated implementation: given a string of a
certain type, a parser will return a &parsed_options; instance
with strings of the same type (i.e. the &parsed_options; class
- will be templated).</para>
+ will be templated).<sbr/>
+ 使用完全的模板实现：给定一个指定类型的字符串，分析器返回一个以
相同类型的字符串实例化的
+ &parsed_options; (即 &parsed_options; 类要模板化)。</para>
</listitem>
<listitem>
<para>Use internal encoding: same as above, but strings will be
converted to and
- from the internal encoding.</para>
+ from the internal encoding.<sbr/>
+ 使用内部编码：同上，但字符串需要与内部编码相互转换。</para>
</listitem>
<listitem>
<para>Use and partly expose the internal encoding: same as above,
but the strings in the &parsed_options; instance will be in the
internal encoding. This might avoid a conversion if
&parsed_options; instance is passed directly to other
components,
- but can be also dangerous or confusing for a user.
+ but can be also dangerous or confusing for a user.<sbr/>
+ 使用并部分公开内部编码：同上，但 &parsed_options; 实例中的字符
串使用内部编码。
+ 这可以在将 &parsed_options; 实例直接传给其它组件时避免转换，但
也可能有风险或误导用户。
</para>
</listitem>
</itemizedlist>
@@ -134,7 +171,9 @@
<para>The second solution appears to be the best -- it does not
increase
the code size much and is cleaner than the third. To avoid extra
conversions, the Unicode version of &parsed_options; can also store
- strings in internal encoding.
+ strings in internal encoding.<sbr/>
+ 第二种方案看来最好 -- 它没有增加太多的代码大小，也比第三个更清晰。
+ 为了避免额外的转换，Unicode 版本的 &parsed_options; 也可以保存内部编码
的字符串。
</para>
<para>For the options descriptions component, we don't have much
@@ -143,59 +182,79 @@
interface of the &value_semantic; must work with both. The only way
is
to pass an additional flag telling if strings use ascii or internal
encoding.
The instance of &value_semantic; can then convert into some
- other encoding if needed.
+ other encoding if needed.<sbr/>
+ 对于选项描述组件，我们没有太多的选择。由于要求所有选项要么都使用
ascii 要么都使用 Unicode 不能令人满意，
+ 更好的办法是可以同时使用 ascii 和 Unicode 选项，这要求
&value_semantic; 的接口必须可以同时对两者使用。
+ 唯一的方法是，传递一个额外的标志来表明字符串是使用 ascii 还是内部编
码。
+ &value_semantic; 实例可以在需要时在不同编码间进行转换。
</para>
<para>For the storage component, the only affected function is &store;.
For Unicode input, the &store; function should convert the value to
the
internal encoding. It should also inform the &value_semantic; class
- about the used encoding.
+ about the used encoding.<sbr/>
+ 对于存储器组件，唯一受影响的函数是 &store;. 对于 Unicode 输
入，&store; 函数将选项值转换为内部编码。
+ 它也会将所使用的编码通知 &value_semantic; 类。
</para>
<para>Finally, what internal encoding should we use? The
alternatives are:
<code>std::wstring</code> (using UCS-4 encoding) and
<code>std::string</code> (using UTF-8 encoding). The difference between
- alternatives is:
+ alternatives is:<sbr/>
+ 最后，我们应该使用什么内部编码呢？选择有两
个：<code>std::wstring</code> (使用 UCS-4 编码)
+ 和 <code>std::string</code> (使用 UTF-8 编码)。两者的不同在于：
<itemizedlist>
<listitem>
- <para>Speed: UTF-8 is a bit slower</para>
+ <para>Speed: UTF-8 is a bit slower<sbr/>
+ 速度: UTF-8 稍慢一些</para>
</listitem>
<listitem>
- <para>Space: UTF-8 takes less space when input is ascii</para>
+ <para>Space: UTF-8 takes less space when input is ascii<sbr/>
+ 空间: 在输入为 ascii 时，UTF-8 占的空间更少</para>
</listitem>
<listitem>
<para>Code size: UTF-8 requires additional conversion code.
However,
it allows one to use existing parsers without converting them
to
<code>std::wstring</code> and such conversion is likely to
create a
- number of new instantiations.
+ number of new instantiations.<sbr/>
+ 代码大小 : UTF-8 需要额外的转换代码。但是，它允许使用已有的分析
器而无须转换为
+ <code>std::wstring</code>，而这种转换需要创建大量新实例。
</para>
</listitem>
</itemizedlist>
There's no clear leader, but the last point seems important, so UTF-8
- will be used.
+ will be used. <sbr/>
+ 没有谁明显胜出，但最后一点看起来更重要，因此我们使用了 UTF-8 .
</para>
<para>Choosing the UTF-8 encoding allows the use of existing parsers,
because 7-bit ascii characters retain their values in UTF-8,
so searching for 7-bit strings is simple. However, there are
- two subtle issues:
+ two subtle issues:<sbr/>
+ 选择 UTF-8 编码允许使用已有的分析器，因为 7-位 ascii 字符在 UTF-8 中
保持原值，
+ 因此查找 7-位 字符串非常简单。但是，还是有两个敏感的问题：
<itemizedlist>
<listitem>
<para>We need to assume the character literals use ascii encoding
- and that inputs use Unicode encoding.</para>
+ and that inputs use Unicode encoding.<sbr/>
+ 我们需要假定字符集使用 ascii 编码而输入使用 Unicode 编码</para>
</listitem>
<listitem>
<para>A Unicode character (say '=') can be followed by 'composing
character' and the combination is not the same as just '=', so a
- simple search for '=' might find the wrong character.
+ simple search for '=' might find the wrong character.<sbr/>
+ 一个 Unicode 字符 (如 '=') 可以后跟 'composing character' 且该组
合与单个 '=' 是不同的，
+ 因此简单地查找 '=' 会找到错误的字符
</para>
</listitem>
</itemizedlist>
Neither of these issues appear to be critical in practice, since
ascii is
almost universal encoding and since composing characters
following '=' (and
- other characters with special meaning to the library) are not likely
to appear.
+ other characters with special meaning to the library) are not likely
to appear.<sbr/>
+ 不过在实践中，这些问题都不重要，由于 ascii 几乎是通用的编码，而且
composing characters 跟在 '='
+ (或其它对于本库而言有特殊意义的字符) 后面这种情况非常罕见。
</para>
</section>
=======================================
--- /trunk/libs/program_options/doc/howto.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/program_options/doc/howto.xml Sun Jan 17 23:11:16 2010
@@ -10,7 +10,8 @@
<title>How To</title>
<para>This section describes how the library can be used in specific
- situations.</para>
+ situations.<sbr/>
+ 本节描述本库如何在特定情况下使用。</para>
<!--
@@ -20,11 +21,13 @@
-->
<section>
- <title>Non-conventional Syntax</title>
+ <title>Non-conventional Syntax 非传统语法</title>
<para>Sometimes, standard command line syntaxes are not enough. For
example, the gcc compiler has "-frtti" and -fno-rtti" options, and this
- syntax is not directly supported.
+ syntax is not directly supported.<sbr/>
+ 有时候，标准的命令行语法是不够的。例如，gcc 编译器有 "-frtti" 和
-fno-rtti" 选项，
+ 这种语法不能直接支持。
</para>
<indexterm><primary>additional parser</primary></indexterm>
@@ -33,7 +36,10 @@
command line element, before any processing by the library. If the
additional parser recognises the syntax, it returns the option name and
value, which are used directly. The above example can be handled by the
- following code:
+ following code:<sbr/>
+ 对于这种情况，程序库允许用户提供一个 <firstterm>附加分析器</firstterm>
--
+ 一个在每个命令行元素被程序库处理之前就调用的函数。如果附加分析器认可该
语法，
+ 则返回选项名和选项值。上述例子可以用以下代码处理：
</para>
<para>
@@ -51,18 +57,20 @@
}
</programlisting>
Here's the definition of the additional parser. When parsing the
command
- line, we pass the additional parser:
+ line, we pass the additional parser:<sbr/>
+ 这就是附加分析器的定义。在分析命令行时，我们这样传递附加分析器：
<programlisting>
store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo)
.run(), vm);
</programlisting>
The complete example can be found in the "example/custom_syntax.cpp"
- file.
+ file. <sbr/>
+ 完整的例子请见 "example/custom_syntax.cpp" 文件。
</para>
</section>
<section>
- <title>Response Files</title>
+ <title>Response Files 响应文件</title>
<indexterm><primary>response files</primary></indexterm>
@@ -73,11 +81,15 @@
the command line specifies a name of response file to use, it's
loaded
and parsed in addition to the command line. The library does not
provide direct support for response files, so you'll need to write
some
- extra code.
+ extra code.<sbr/>
+ 有些操作系统对于命令行长度只有很低的限制。对付这些限制的常用方法是使
用 <firstterm>响应文件</firstterm>。
+ 响应文件是采用与命令行相同语法的配置文件。如果命令行指定了响应文件的
名字，则导入该文件并进行命令行分析。
+ 程序库没有提供对响应文件的直接支持，所以你需要编写额外的代码。
</para>
<para>
- First, you need to define an option for the response file:
+ First, you need to define an option for the response file:<sbr/>
+ 首先，你需要为响应文件定义一个选项：
<programlisting>
("response-file", value<string>(),
"can be specified with '@name', too")
@@ -85,7 +97,8 @@
</para>
<para>Second, you'll need an additional parser to support the standard
syntax
- for specifying response files: "@file":
+ for specifying response files: "@file":<sbr/>
+ 其次，你需要一个附加分析器，以支持指定响应文件的标准语法: "@file":
<programlisting><![CDATA[
pair<string, string> at_option_parser(string const&s)
{
@@ -101,36 +114,40 @@
<para>Finally, when the "response-file" option is found, you'll have to
load that file and pass it to the command line parser. This part is the
hardest. We'll use the Boost.Tokenizer library, which works but has
some
- limitations. You might also consider Boost.StringAlgo. The code is:
+ limitations. You might also consider Boost.StringAlgo. The code
is:<sbr/>
+ 最后，如果找到了 "response-file" 选项，你需要导入文件并将它传给命令行分
析器。
+ 这部分是最难的。我们要使用 Boost.Tokenizer 库，该库可用但有点限制。
+ 你也可考虑 Boost.StringAlgo. 代码如下：
<programlisting><![CDATA[
if (vm.count("response-file")) {
- // Load the file and tokenize it
+ // Load the file and tokenize it 导入文件并分解记号
ifstream ifs(vm["response-file"].as<string>().c_str());
if (!ifs) {
cout << "Could no open the response file\n";
return 1;
}
- // Read the whole file into a string
+ // Read the whole file into a string 将整个文件读入到 string
stringstream ss;
ss << ifs.rdbuf();
- // Split the file content
+ // Split the file content 分解文件内容
char_separator<char> sep(" \n\r");
tokenizer<char_separator<char> > tok(ss.str(), sep);
vector<string> args;
copy(tok.begin(), tok.end(), back_inserter(args));
- // Parse the file and store the options
+ // Parse the file and store the options 分析文件并保存选项
store(command_line_parser(args).options(desc).run(), vm);
}
]]>
</programlisting>
The complete example can be found in the "example/response_file.cpp"
- file.
+ file. <sbr/>
+ 完整的例子请见 "example/response_file.cpp" 文件。
</para>
</section>
<section>
- <title>Winmain Command Line</title>
+ <title>Winmain Command Line Winmain命令行</title>
<para>On the Windows operating system, GUI applications receive the
command line as a single string, not split into elements. For that
reason,
@@ -139,34 +156,44 @@
the split command line, but it's not clear if all compilers support the
same mechanism on all versions of the operating system. The
<code>split_winmain</code> function is a portable mechanism provided
- by the library.</para>
-
- <para>Here's an example of use:
+ by the library.<sbr/>
+ 在 Windows 操作系统，GUI 应用以单个字符串接收命令行，而不分解为多个元
素。
+ 由于这个原因，命令行分析器不能直接使用。有一些编译器可以得到分解的命令
行，
+ 但不清楚是否所有编译器在所有版本的操作系统上都支持相同的机制。
+ <code>split_winmain</code> 函数是本库提供的可移植方案。</para>
+
+ <para>Here's an example of use:<sbr/>
+ 下面是一个用例：
<programlisting>
vector<string> args = split_winmain(lpCmdLine);
store(command_line_parser(args).options(desc).run(), vm);
</programlisting>
The function is an overload for <code>wchar_t</code> strings, so can
- also be used in Unicode applications.
+ also be used in Unicode applications.<sbr/>
+ 该函数有一个对于 <code>wchar_t</code> 字符串的重载，因此也可用于
Unicode 应用。
</para>
</section>
<section>
- <title>Option Groups and Hidden Options</title>
+ <title>Option Groups and Hidden Options 选项组和隐藏选项</title>
<para>Having a single instance of the &options_description; class with
all
- the program's options can be problematic:
+ the program's options can be problematic:<sbr/>
+ 用单个 &options_description; 实例处理所有程序选项有以下问题：
<itemizedlist>
<listitem>
<para>Some options make sense only for specific source, for
example,
- configuration files.</para>
+ configuration files.<sbr/>
+ 有些选项只用于特定的源，如配置文件。</para>
</listitem>
<listitem>
- <para>The user would prefer some structure in the generated help
message.</para>
+ <para>The user would prefer some structure in the generated help
message.<sbr/>
+ 用户倾向于生成结构化的帮助信息。</para>
</listitem>
<listitem>
- <para>Some options shouldn't appear in the generated help
message at all.</para>
+ <para>Some options shouldn't appear in the generated help
message at all.<sbr/>
+ 有些选项不应出现在生成的帮助信息中。</para>
</listitem>
</itemizedlist>
</para>
@@ -175,11 +202,15 @@
instances of the &options_description; class, which can be merged in
different combinations. The following example will define three
groups of
options: command line specific, and two options group for specific
program
- modules, only one of which is shown in the generated help message.
+ modules, only one of which is shown in the generated help
message.<sbr/>
+ 为了解决以上问题，本库允许程序员创建多个 &options_description; 实
例，并合并为不同的组合。
+ 在以下例子中定义了三组选项：一个用于命令行指定，另两个用于特定的程序
模块，
+ 其中只有一个会在生成的帮助信息中显示。
</para>
<para>Each group is defined using standard syntax. However, you should
- use reasonable names for each &options_description; instance:
+ use reasonable names for each &options_description; instance:<sbr/>
+ 每个组都使用标准语法定义。但是，你应为每个 &options_description; 实例
取一个合理的名字：
<programlisting><![CDATA[
options_description general("General options");
general.add_options()
@@ -203,21 +234,26 @@
<para>After declaring options groups, we merge them in two
combinations. The first will include all options and be used for
parsing. The
- second will be used for the "--help" option.
+ second will be used for the "--help" option.<sbr/>
+ 声明了选项组之后，我们把它们合并为两个组合。第一个包含所有选项，用于
分析。
+ 第二个则用于 "--help" 选项。
<programlisting>
// Declare an options description instance which will include
// all the options
+// 声明一个选项描述实例，包含所有选项
options_description all("Allowed options");
all.add(general).add(gui).add(backend);
// Declare an options description instance which will be shown
// to the user
+// 声明一个选项描述实例，包含显示给用户的选项
options_description visible("Allowed options");
visible.add(general).add(gui);
</programlisting>
</para>
- <para>What is left is to parse and handle the options:
+ <para>What is left is to parse and handle the options:<sbr/>
+ 剩下就是分析和处理选项：
<programlisting><![CDATA[
variables_map vm;
store(parse_command_line(ac, av, all), vm);
@@ -250,30 +286,37 @@
options in that group are hidden. The user can explicitly force the
display of that options group by passing "--help-module backend"
option. The complete example can be found in the
- "example/option_groups.cpp" file.
+ "example/option_groups.cpp" file.<sbr/>
+ 在分析命令行时，所有选项都可用。但是 "--help" 信息不包含 "Backend
options" 组 --
+ 该组中的选项被隐藏。用户可以通过传入 "--help-module backend" 选项来显
式强制选项组的显示。
+ 完整的例子请见 "example/option_groups.cpp" 文件。
</para>
</section>
<section>
- <title>Custom Validators</title>
+ <title>Custom Validators 定制验证器</title>
<para>By default, the conversion of option's value from string into C++
type is done using iostreams, which sometimes is not convenient. The
library allows the user to customize the conversion for specific
classes. In order to do so, the user should provide suitable
overload of
- the <code>validate</code> function.
+ the <code>validate</code> function.<sbr/>
+ 缺省地，选项值从字符串到C++类型的转换使用 iostreams 来执行，但有时候
会不太方便。
+ 本库允许用户为特定类定制转换的方法。用户要提供 <code>validate</code>
函数的合适重载。
</para>
<para>
- Let's first define a simple class:
+ Let's first define a simple class:<sbr/>
+ 我们首先定义一个简单的类：
<programlisting><![CDATA[
struct magic_number {
public:
magic_number(int n) : n(n) {}
int n;
};
-]]></programlisting> and then overload the <code>validate</code> function:
+]]></programlisting> and then overload the <code>validate</code>
function:<sbr/>
+然后重载 <code>validate</code> 函数：
<programlisting><![CDATA[
void validate(boost::any& v,
const std::vector<std::string>& values,
@@ -284,13 +327,16 @@
using namespace boost::program_options;
// Make sure no previous assignment to 'a' was made.
+ // 确定之前没有对 'a' 赋值
validators::check_first_occurrence(v);
// Extract the first string from 'values'. If there is more than
// one string, it's an error, and exception will be thrown.
+ // 从 'values' 提取第一个串。如果有多于一个串则为错误，抛出异常
const string& s = validators::get_single_string(values);
// Do regex match and convert the interesting part to
// int.
+ // 进行 regex 匹配并将相应部分转换为 int.
smatch match;
if (regex_match(s, match, r)) {
v = any(magic_number(lexical_cast<int>(match[1])));
@@ -304,39 +350,50 @@
the <code>magic_number</code> class. The second is the list of
strings
found in the next occurrence of the option. The remaining two
parameters
are needed to workaround the lack of partial template specialization
and
- partial function template ordering on some compilers.
+ partial function template ordering on some compilers.<sbr/>
+ 该函数带四个参数。第一个为选项值的存储，本例中要么为空，要么包含一个
<code>magic_number</code> 实例。
+ 第二个为下一个选项的字符串列表。剩下的两个参数对于缺乏模板偏特化和函
数模板部分分类的编译器是需要的。
</para>
<para>The function first checks that we don't try to assign to the same
option twice. Then it checks that only a single string was passed
in. Next the string is verified with the help of the Boost.Regex
library. If that test is passed, the parsed value is stored into the
- <code>v</code> variable.
+ <code>v</code> variable.<sbr/>
+ 函数首先检查我们是否试图对同一个选项重复赋值。然后检查传入的单个字符
串。
+ 接着字符串在 Boost.Regex 库的帮助下进行验证。如果测试通过，
+ 分析得到的值被保存在变量 <code>v</code> 中。
</para>
- <para>The complete example can be found in the "example/regex.cpp"
file.
+ <para>The complete example can be found in the "example/regex.cpp"
file.<sbr/>
+ 完整的例子请见 "example/regex.cpp" 文件。
</para>
</section>
<section>
- <title>Unicode Support</title>
-
- <para>To use the library with Unicode, you'd need to:
+ <title>Unicode Support Unicode支持</title>
+
+ <para>To use the library with Unicode, you'd need to:<sbr/>
+ 将本库使用于 Unicode, 你需要：
<itemizedlist>
<listitem>
- <para>Use Unicode-aware parsers for Unicode input</para>
+ <para>Use Unicode-aware parsers for Unicode input<sbr/>
+ 对 Unicode 输入使用 Unicode-aware 的分析器</para>
</listitem>
<listitem>
- <para>Require Unicode support for options which need it</para>
+ <para>Require Unicode support for options which need it<sbr/>
+ 要求选项在需要时支持 Unicode</para>
</listitem>
</itemizedlist>
</para>
<para>Most of the parsers have Unicode versions. For example, the
&parse_command_line; function has an overload which takes
- <code>wchar_t</code> strings, instead of ordinary <code>char</code>.
+ <code>wchar_t</code> strings, instead of ordinary
<code>char</code>.<sbr/>
+ 多数分析器都有 Unicode 版本。例如，&parse_command_line; 函数有一个重
载接受
+ <code>wchar_t</code> 字符串，替代原先的 <code>char</code>.
</para>
<para>Even if some of the parsers are Unicode-aware, it does not mean
you
@@ -346,43 +403,57 @@
ordinary options in that they accept <code>wstring</code> input, and
process it using wide character streams. Creating an Unicode-aware
option
is easy: just use the the <code>wvalue</code> function instead of the
- regular <code>value</code>.
+ regular <code>value</code>.<sbr/>
+ 即使有些分析器是 Unicode-aware 的，但并不意味你需要修改所有选项的定义。
+ 事实上，对于多数选项，如整型的，并不影响。要使用 Unicode 你需要
<emphasis>一些</emphasis> Unicode-aware 选项。
+ 这些选项与原先的不同在于它们接受 <code>wstring</code> 输入，并使用宽字
符流来处理它。
+ 创建一个 Unicode-aware 选项非常容易：只要使用 <code>wvalue</code> 函数
替代通常 <code>value</code> 就行了。
</para>
<para>When an ascii parser passes data to an ascii option, or a Unicode
parser passes data to a Unicode option, the data are not changed at
all. So, the ascii option will see a string in local 8-bit encoding,
and
the Unicode option will see whatever string was passed as the Unicode
- input.
+ input.<sbr/>
+ 当一个 ascii 分析器传递数据给一个 ascii 选项时，或一个 Unicode 分析器
传递数据给一个 Unicode 选项时，
+ 数据不会改变。即 ascii 选项将看到一个本地8位编码的字符串，而 Unicode
选项将看到 Unicode 输入的字符串。
</para>
<para>What happens when Unicode data is passed to an ascii option, and
vice versa? The library automatically performs the conversion from
Unicode to local 8-bit encoding. For example, if command line is in
ascii, but you use <code>wstring</code> options, then the ascii input
- will be converted into Unicode.
+ will be converted into Unicode.<sbr/>
+ 如果将 Unicode 数据传递给 ascii 选项或反之，会如何？本库会自动执行从
Unicode 到本地8位编码的转换。
+ 例如：如果命令行是 ascii 的，而你使用 <code>wstring</code> 选项，则
ascii 输入将被转换为 Unicode.
</para>
<para>To perform the conversion, the library uses the
<code>codecvt<wchar_t,
char></code> locale facet from the global locale. If
you want to work with strings that use local 8-bit encoding (as
opposed to
- 7-bit ascii subset), your application should start with:
+ 7-bit ascii subset), your application should start with:<sbr/>
+ 为了执行转换，本库使用了来自于 global locale 的
<code>codecvt<wchar_t, char></code> locale facet。
+ 如果你想处理使用本地8位编码(不要使用 7-bit ascii 字集)的字符串，你的应
用程序要以这样开始：
<programlisting>
locale::global(locale(""));
</programlisting>
which would set up the conversion facet according to the user's
selected
- locale.
+ locale. <sbr/>
+ 这就设置了转换 facet 依照于用户选择的 locale.
</para>
<para>It's wise to check the status of the C++ locale support on your
- implementation, though. The quick test involves three steps:
+ implementation, though. The quick test involves three steps:<sbr/>
+ 明智的做法是检查一下在你的实现上对 C++ locale 的支持状态。快速的测试
包括以下三步：
<orderedlist>
<listitem>
- <para>Go the the "test" directory and build the "test_convert"
binary.</para>
+ <para>Go the the "test" directory and build the "test_convert"
binary.<sbr/>
+ 进入 "test" 目录，构建 "test_convert" 程序。</para>
</listitem>
<listitem>
<para>Set some non-ascii locale in the environmemt. On Linux,
one can
- run, for example: <screen>
+ run, for example: <sbr/>
+ 在环境中设置某个非-ascii locale. 例如在 Linux 上，你可执行:
<screen>
$ export LC_CTYPE=ru_RU.KOI8-R
</screen>
</para>
@@ -391,7 +462,9 @@
<para>Run the "test_convert" binary with any non-ascii string in
the
selected encoding as its parameter. If you see a list of
Unicode codepoints,
everything's OK. Otherwise, locale support on your system
might be
- broken.</para>
+ broken.<sbr/>
+ 运行 "test_convert" 程序，以一些选定编码的非-ascii 字符串作为参
数。
+ 如果你看到一串 Unicode 编码，则一切OK。否则，表示你的系统上的
locale 支持可能已被破坏。</para>
</listitem>
</orderedlist>
</para>
@@ -399,17 +472,22 @@
</section>
<section>
- <title>Allowing Unknown Options</title>
+ <title>Allowing Unknown Options 允许未知选项</title>
<para>Usually, the library throws an exception on unknown option
names. This
behaviour can be changed. For example, only some part of your
application uses
<libraryname>Program_options</libraryname>, and you wish to pass
unrecognized options to another part of
- the program, or even to another application.</para>
+ the program, or even to another application.<sbr/>
+ 通常，本库在遇到未知选项时会抛出异常。这种行为可以被改变。例如，你的
程序中只有一部分使用
+ <libraryname>Program_options</libraryname>, 而你希望将未能识别的选项
传递给程序的其它部分，
+ 或者甚至是其它程序。</para>
<para>To allow unregistered options on the command line, you need to
use
the &basic_command_line_parser; class for parsing (not
&parse_command_line;)
and call the <methodname
alt="boost::program_options::basic_command_line_parser::allow_unregistered">allow_unregistered</methodname>
- method of that class:
+ method of that class:<sbr/>
+ 要允许在命令行中使用未登记的选项，你需要使用
&basic_command_line_parser; 类来分析 (而不是 &parse_command_line;)，
+ 并且调用该类的 <methodname
alt="boost::program_options::basic_command_line_parser::allow_unregistered">allow_unregistered</methodname>
方法：
<programlisting>
parsed_options parsed =
command_line_parser(argc,
argv).options(desc).allow_unregistered().run();
@@ -419,13 +497,21 @@
an instance of &basic_option; will be added to the result.
The <code>string_key</code> and <code>value</code> fields of the
instance will contain results
of syntactic parsing of the token, the <code>unregistered</code>
field will be set to <code>true</code>,
- and the <code>original_tokens</code> field will contain the token as
it appeared on the command line.
+ and the <code>original_tokens</code> field will contain the token as
it appeared on the command line.<sbr/>
+ 对于每一个看起来象选项，但又没有已知名字的记号，将产生一个
&basic_option; 实例并增加到结果中。
+ 该实例的 <code>string_key</code> 和 <code>value</code> 域中包含了对该
记号进行语法分析的结果，
+ <code>unregistered</code> 域将被设置为 <code>true</code>, 而
<code>original_tokens</code>
+ 域则包含出现在命令行中的记号。
</para>
<para>If you want to pass the unrecognized options further, the
<functionname
alt="boost::program_options::collect_unrecognized">collect_unrecognized</functionname>
function can be used.
The function will collect original tokens for all unrecognized
values, and optionally, all found positional options.
- Say, if your code handles a few options, but does not handles
positional options at all, you can use the function like this:
+ Say, if your code handles a few options, but does not handles
positional options at all, you can use the function like this:<sbr/>
+ 如果你想进一步传递这个未能识别的选项，可以使用
+ <functionname
alt="boost::program_options::collect_unrecognized">collect_unrecognized</functionname>
函数。
+ 该函数收集所有未能识别的原始记号，以及所有位置选项(可选)。即是说，如
果你的代码只处理少数选项，
+ 而不处理位置选项，则你可以这样使用函数：
<programlisting>
vector<string> to_pass_further =
collect_unrecognized(parsed.options, include_positional);
</programlisting>
=======================================
--- /trunk/libs/program_options/doc/overview.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/program_options/doc/overview.xml Sun Jan 17 23:11:16 2010
@@ -6,29 +6,36 @@
%entities;
]>
<section id="program_options.overview">
- <title>Library Overview</title>
+ <title>Library Overview 总述</title>
<para>In the tutorial section, we saw several examples of library usage.
Here we will describe the overall library design including the primary
- components and their function.
+ components and their function.<sbr/>
+ 在上一节“指南”中，我们看到了几个用例。这一节我们将介绍整个库的设计，
+ 包括主要的组件以及它们的作用。
</para>
- <para>The library has three main components:
+ <para>The library has three main components:<sbr/>
+ 本库有三个主要组件：
<itemizedlist>
<listitem>
<para>The options description component, which describes the
allowed options
- and what to do with the values of the options.
+ and what to do with the values of the options.<sbr/>
+ 选项描述组件，描述允许的选项及这些选项的值。
</para>
</listitem>
<listitem>
<para>The parsers component, which uses this information to find
option names
- and values in the input sources and return them.
+ and values in the input sources and return them. <sbr/>
+ 分析器组件，用于从数据输入源中查找选项名字及值，并返回它们。
</para>
</listitem>
<listitem>
<para>The storage component, which provides the
interface to access the value of an option. It also converts the
string
- representation of values that parsers return into desired C++
types.
+ representation of values that parsers return into desired C++
types.<sbr/>
+ 存储器组件，提供读取选项值的接口，同时负责将分析器所返回的、
+ 以字符串方式表示的值转换为需要的C++类型。
</para>
</listitem>
</itemizedlist>
@@ -37,12 +44,17 @@
<para>To be a little more concrete, the <code>options_description</code>
class is from the options description component, the
<code>parse_command_line</code> function is from the parsers component,
and the
- <code>variables_map</code> class is from the storage component. </para>
+ <code>variables_map</code> class is from the storage component. <sbr/>
+ 说得具体些，<code>options_description</code> 类即来自于选项描述组件，
+ <code>parse_command_line</code> 函数则来自于分析器组件，而
<code>variables_map</code>
+ 类则来自于存储器组件。</para>
<para>In the tutorial we've learned how those components can be used by
the
<code>main</code> function to parse the command line and config
file. Before going into the details of each component, a few notes
about
- the world outside of <code>main</code>.
+ the world outside of <code>main</code>.<sbr/>
+ 在上一节，我们已经学习了如何在 <code>main</code> 函数中使用这些组件来分
析命令行以及配置文件。
+ 在进入到这些组件的细节之前，还要注意 <code>main</code> 以外的一些东西。
</para>
<para>
@@ -54,7 +66,12 @@
individual program modules to describe their options and pass them to
the
main module, which will merge all options. Of course, this is only
important when the number of options is large and declaring them in one
- place becomes troublesome.
+ place becomes troublesome.<sbr/>
+ 在 main 以外，存储器组件是最重要的。它提供了一个类，用于保存所有选项
值，
+ 并且这个类可以自由地从你的程序传递到任何需要访问选项的模块。
+ 而其它组件只能在进行分析处理的地方使用。但是，对于独立的程序模块来说，
+ 描述它们自己的选项并传递给主模块也是很有意义的。当然，
+ 这种做法只有在选项数量太多导致在一个地方声明它们很麻烦时才会显得重要。
</para>
<!--
@@ -83,7 +100,7 @@
-->
<section>
- <title>Options Description Component</title>
+ <title>Options Description Component 选项描述组件</title>
<para>The options description component has three main classes:
&option_description;, &value_semantic; and &options_description;. The
@@ -91,14 +108,20 @@
class contains the option's name, description and a pointer to
&value_semantic;,
which, in turn, knows the type of the option's value and can parse
the value,
apply the default value, and so on. The &options_description; class
is a
- container for instances of &option_description;.
+ container for instances of &option_description;.<sbr/>
+ 选项描述组件有三个主要的类：&option_description;, &value_semantic;
和 &options_description;。
+ 前两个一起用于描述单个选项。&option_description; 类包含选项的名字、描
述以及一个指向 &value_semantic; 的指针，
+ 后者知道选项值的类型且可以分析该值，或赋予缺省值。
&options_description; 类则是包含多个 &option_description; 实例的容器。
</para>
<para>For almost every library, those classes could be created in a
conventional way: that is, you'd create new options using
constructors and
then call the <code>add</code> method of &options_description;.
However,
that's overly verbose for declaring 20 or 30 options. This concern
led
- to creation of the syntax that you've already seen:
+ to creation of the syntax that you've already seen:<sbr/>
+ 几乎每个库中的类都是以一种常规的方法来创建的：即使用构造函数来创建一
个新的选项，
+ 然后调用 &options_description; 的 <code>add</code> 方法。但是，如果有
20或30个选项要声明，
+ 这就显得很冗长了。这导致了你已经见过的另一种创建语法：
<programlisting>
options_description desc;
desc.add_options()
@@ -116,7 +139,12 @@
essentially emulates named parameters of the constructor.) Calls to
<code>operator()</code> on the object returned by
<code>add_options</code>
forward arguments to the constructor of the
<code>option_description</code>
- class and add the new instance.
+ class and add the new instance. <sbr/>
+ 对 <code>value</code> 函数的调用创建了一个派生自
<code>value_semantic</code> 类的子类：
+ <code>typed_value</code> 的实例。这个类包含了分析一个特定类型的值的代
码，
+ 以及一组可供用户调用以指定额外信息的方法(实质上它模拟了构造函数的命名
参数)。
+ 在这样一个对象之上调用其 <code>operator()</code>，将通过
<code>add_options</code>
+ 前转参数至 <code>option_description</code> 类的构造函数，并加入新的实
例。
</para>
<para>
@@ -125,7 +153,10 @@
function, and user can write his own function which will return
other subclasses of <code>value_semantic</code> with
different behaviour. For the remainder of this section, we'll talk
only
- about the <code>value</code> function.
+ about the <code>value</code> function.<sbr/>
+ 请注意，除了 <code>value</code>, 库还提供了 <code>bool_switch</code>
函数,
+ 用户可以编写自己的函数来返回 <code>value_semantic</code> 的其它子类，
+ 以实现不同的行为。在本节的剩余部分，我们只讨论 <code>value</code> 函
数。
</para>
<para>The information about an option is divided into syntactic and
@@ -135,47 +166,60 @@
where value is just a vector of strings
(<code>std::vector<std::string></code>). The semantic layer
is responsible for converting the value of the option into more
usable C++
- types.
+ types. <sbr/>
+ 一个选项的信息可分为语法和语义两部分。语法信息包含了选项的名字和用于
指定其值的记号数量。
+ 分析器使用该信息将记号组合为(名字，值)对，其中的值是一个字符串向量
(<code>std::vector<std::string></code>).
+ 语义层面则负责将选项的值转换为更可用的C++类型。
</para>
<para>This separation is an important part of library design. The
parsers
use only the syntactic layer, which takes away some of the freedom to
use overly complex structures. For example, it's not easy to parse
- syntax like: <screen>calc --expression=1 + 2/3</screen> because it's
not
- possible to parse <screen>1 + 2/3</screen> without knowing that it's
a C
+ syntax like: <sbr/>
+ 这种分离是库设计的重要部分。分析器只用于语法层面，这样就没有了使用过
于复杂的结构的自由。
+ 例如，很难分析以下语法：<screen>calc --expression=1 + 2/3</screen>
because it's not
+ possible to parse <sbr/>
+ 因为无法在不知道它是一个C表达式的前提下分析<screen>1 + 2/3</screen>
without knowing that it's a C
expression. With a little help from the user the task becomes
trivial,
- and the syntax clear: <screen>calc --expression="1 + 2/3"</screen>
+ and the syntax clear: <sbr/>
+ 在得到用户的一点帮助后任务会变得容易，语法也更清晰：<screen>calc
--expression="1 + 2/3"</screen>
</para>
<section>
- <title>Syntactic Information</title>
+ <title>Syntactic Information 语法信息</title>
<para>The syntactic information is provided by the
<classname>boost::program_options::options_description</classname>
class
and some methods of the
<classname>boost::program_options::value_semantic</classname> class
- and includes:
+ and includes: <sbr/>
+ 语法信息由
<classname>boost::program_options::options_description</classname> 类和
+ <classname>boost::program_options::value_semantic</classname> 类的
某些方法提供，包括：
<itemizedlist>
<listitem>
<para>
name of the option, used to identify the option inside the
- program,
+ program,<sbr/>
+ 选项名，用于在程序中标识选项，
</para>
</listitem>
<listitem>
<para>
- description of the option, which can be presented to the
user,
+ description of the option, which can be presented to the
user,<sbr/>
+ 选项的描述，用于显示给用户，
</para>
</listitem>
<listitem>
<para>
the allowed number of source tokens that comprise options's
- value, which is used during parsing.
+ value, which is used during parsing.<sbr/>
+ 允许的组成选项值的源记号数量，在分析时使用。
</para>
</listitem>
</itemizedlist>
</para>
- <para>Consider the following example:
+ <para>Consider the following example:<sbr/>
+ 考虑以下例子：
<programlisting>
options_description desc;
desc.add_options()
@@ -190,19 +234,25 @@
For the first option, the user must specify a value, using a single
token. For the third option, the user may either provide a single
token
for the value, or no token at all. For the last option, the value can
- span several tokens. For example, the following command line is OK:
+ span several tokens. For example, the following command line is
OK:<sbr/>
+ 在第一个参数中，我们只指定了选项的名字和描述。因此在被分析的源中不能
指定选项值。
+ 对于第二个选项，用户必须用单个记号指定一个选项值。对于第三个选项，
+ 用户可以提供单个记号表示选项值，也可以没有记号。最后一个选项，选项值
可以跨越多个记号。
+ 例如，如下命令行是可用的：
<screen>
test --help --compression 10 --verbose --email beadle@mars
beadle2@mars
</screen>
</para>
<section>
- <title>Description formatting</title>
+ <title>Description formatting 描述格式化</title>
<para>
Sometimes the description can get rather long, for example, when
several option's values need separate documentation. Below we
- describe some simple formatting mechanisms you can use.
+ describe some simple formatting mechanisms you can use.<sbr/>
+ 有时选项的描述会很长，例如有几个选项值需要分开描述时。
+ 下面我们说明一下你可以使用的一些简单的格式化机制。
</para>
<para>The description string has one or more paragraphs, separated
by
@@ -210,11 +260,14 @@
will compute the indentation for options's description. Each of the
paragraph is output as a separate line with that intentation. If
a paragraph does not fit on one line it is spanned over multiple
- lines (which will have the same indentation).
+ lines (which will have the same indentation).<sbr/>
+ 描述字符串有一个或多个段，以换行符('\n')分隔。在输出一个选项时，程
序库将计算选项描述的缩入量。
+ 每一段被作为带缩入的单独一行输出。如果一段字符不能在一行内输出，则
被分割为多行(各行有相同的缩入量)。
</para>
<para>You may specify additional indent for the first specified by
- inserting spaces at the beginning of a paragraph. For example:
+ inserting spaces at the beginning of a paragraph. For example:
<sbr/>
+ 你可以在段的开始插入空格，这样在该段的第一行就会有额外的缩入。例
如：
<programlisting>
options.add_options()
("help", " A long help msg a long help msg a long help msg a long
help
@@ -222,7 +275,8 @@
;
</programlisting>
will specify a four-space indent for the first line. The output
will
- look like:
+ look like:<sbr/>
+ 在第一行指定了四个空格的缩入。输出如下：
<screen>
--help A long help msg a long
help msg a long help msg
@@ -237,7 +291,8 @@
<para>For the case where line is wrapped, you can want an
additional
indent for wrapped text. This can be done by
inserting a tabulator character ('\t') at the desired position. For
- example:
+ example: <sbr/>
+ 在自动换行时，你可能想要额外的缩入。可以通过在指定地方插入制表符
('\t')达到效果。例如：
<programlisting>
options.add_options()
("well_formated", "As you can see this is a very well formatted
@@ -251,7 +306,8 @@
" This paragraph has a first line indent only,
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
</programlisting>
- will produce:
+ will produce:<sbr/>
+ 将输出：
<screen>
--well_formated As you can see this is a
very well formatted
@@ -283,7 +339,9 @@
paragraph is allowed, otherwisee an exception of type
program_options::error is thrown. Finally, the tabulator is
ignored if
it's is not on the first line of the paragraph or is on the last
- possible position of the first line.
+ possible position of the first line.<sbr/>
+ 制表符在输出前会被删除。每段只允许一个制表符，否则将抛出
program_options::error 异常。
+ 最后，如果制表符不是在段中的第一行或者第一行最后的可能位置上，则将
被忽略。
</para>
</section>
@@ -291,11 +349,12 @@
</section>
<section>
- <title>Semantic Information</title>
+ <title>Semantic Information 语义信息</title>
<para>The semantic information is completely provided by the
<classname>boost::program_options::value_semantic</classname>
class. For
- example:
+ example:<sbr/>
+ 语义信息完全由
<classname>boost::program_options::value_semantic</classname> 类提供。例如：
<programlisting>
options_description desc;
desc.add_options()
@@ -308,28 +367,35 @@
that the second option can appear several times and all instances
should
be merged, and that after parsing is done, the library will call
function <code>&your_function</code>, passing the value of the
- "email" option as argument.
+ "email" option as argument. <sbr/>
+ 这个声明为第一个选项指定了缺省值10，而第二个选项则可以多次出现且所
有实例会被合并，
+ 然后进行分析，程序库会调用函数 <code>&your_function</code>,
把 "email" 选项的值作为参数传入。
</para>
</section>
<section>
- <title>Positional Options</title>
+ <title>Positional Options 位置选项</title>
<para>Our definition of option as (name, value) pairs is simple and
useful, but in one special case of the command line, there's a
problem. A command line can include a <firstterm>positional
option</firstterm>,
- which does not specify any name at all, for example:
+ which does not specify any name at all, for example:<sbr/>
+ 我们把选项定义为 (name, value) 对，这很简单也有用，但是在命令行的一
种特列情形下，会有问题。
+ 命令行可以包含 <firstterm>位置选项</firstterm>, 该选项不需指定名
字，例如：
<screen>
archiver --compression=9 /etc/passwd
</screen>
- Here, the "/etc/passwd" element does not have any option name.
+ Here, the "/etc/passwd" element does not have any option
name.<sbr/>
+ 在此，"/etc/passwd" 并没有选项名。
</para>
<para>One solution is to ask the user to extract positional options
himself and process them as he likes. However, there's a nicer
approach
-- provide a method to automatically assign the names for
positional
options, so that the above command line can be interpreted the
same way
- as:
+ as:<sbr/>
+ 一种解决方案是让用户自己取出位置选项并处理。但是我们有更好的办法 --
+ 提供一个方法自动给位置选项赋上一个名字，即上述命令行可以解释为：
<screen>
archiver --compression=9 --input-file=/etc/passwd
</screen>
@@ -337,27 +403,34 @@
<para>The &positional_options_desc; class allows the command line
parser to assign the names. The class specifies how many
positional options
- are allowed, and for each allowed option, specifies the name. For
example:
+ are allowed, and for each allowed option, specifies the name. For
example:<sbr/>
+ &positional_options_desc; 类允许命令行分析器自动赋上这个名字。
+ 该类指定了可以有多少个位置选项，以及对每个选项指定名字。例如：
<programlisting>
positional_options_description pd; pd.add("input-file", 1);
</programlisting> specifies that for exactly one, first, positional
- option the name will be "input-file".
+ option the name will be "input-file".<sbr/>
+ 指定只有一个位置选项，名字为 "input-file".
</para>
<para>It's possible to specify that a number, or even all positional
options, be
- given the same name.
+ given the same name.<sbr/>
+ 可以指定一定数量的，或者所有的位置选项给予相同名字。
<programlisting>
positional_options_description pd;
pd.add("output-file", 2).add("input-file", -1);
</programlisting>
In the above example, the first two positional options will be
associated
- with name "output-file", and any others with the name "input-file".
+ with name "output-file", and any others with the
name "input-file".<sbr/>
+ 上例中，头两个位置选项与名字 "output-file" 关联，其余则与名
字 "input-file" 关联。
</para>
<warning>
<para>The &positional_options_desc; class only specifies translation
from
position to name, and the option name should still be registered with
- an instance of the &options_description; class.</para>
+ an instance of the &options_description; class.<sbr/>
+ &positional_options_desc; 类只是指定了从位置到名字的翻译，
+ 该选项名还需要通过某个 &options_description; 实例来登记。</para>
</warning>
@@ -368,7 +441,7 @@
</section>
<section>
- <title>Parsers Component</title>
+ <title>Parsers Component 分析器组件</title>
<para>The parsers component splits input sources into (name, value)
pairs.
Each parser looks for possible options and consults the options
@@ -381,7 +454,13 @@
the value cannot be specified by the user, but the presence of the
option implies some value (for example, <code>true</code>). So, the
parser checks that the value is specified when needed and not
specified
- when not needed, and returns new (name, value) pair.
+ when not needed, and returns new (name, value) pair.<sbr/>
+ 分析器组件将输入源分解为 (name, value) 对。每个分析器查找可能的选项，
+ 参考选项描述以确定选项是否可知及如何确定它的值。在最简单的情况下，
+ 选项名是显式给出的，这允许程序库确定选项是否可知的。如果是可知的，
+ 则 value_semantic 实例决定如何得到它的值。(如果不是可知的，则抛出异常
)。
+ 一般的情况是，用户显式指定了该值，或者用户没有指定值，但该选项的存在
暗示了某个值
+ (如 <code>true</code>)。因此，分析器按需要检查选项值并返回新的
(name, value) 对。
</para>
<para>
@@ -390,20 +469,27 @@
The results of parsing are returned as an instance of the
&parsed_options;
class. Typically, that object is passed directly to the storage
component. However, it also can be used directly, or undergo some
additional
- processing.
+ processing. <sbr/>
+ 调用分析器时，你要调用一个函数，传入选项描述及命令行或配置文件或其它
东西。
+ 分析的结果被作为 parsed_options 类的一个实例返回。典型地，这个对象被
直接传递给存储器组件。
+ 但是，也可以直接使用它，或者执行另外的处理。
</para>
<para>
There are three exceptions to the above model -- all related to
traditional usage of the command line. While they require some
support
from the options description component, the additional complexity is
- tolerable.
+ tolerable.<sbr/>
+ 以上模型有三个例外 -- 都与命令行的传统用法相关。它们需要选项描述组件
的支持，
+ 增加的复杂度是可接受的。
<itemizedlist>
<listitem>
<para>The name specified on the command line may be
different from the option name -- it's common to provide
a "short option
name" alias to a longer name. It's also common to allow an
abbreviated name
- to be specified on the command line.
+ to be specified on the command line.<sbr/>
+ 在命令行中指定的名字可能与选项名不同 -- 通常会为一个较长的名字
提供一个 "短选项名"。
+ 同样常见的是在命令行中使用缩写名。
</para>
</listitem>
<listitem>
@@ -411,14 +497,18 @@
tokens. For example, an option "--email-recipient" may be
followed
by several emails, each as a separate command line token. This
behaviour is supported, though it can lead to parsing ambiguities
- and is not enabled by default.
+ and is not enabled by default.<sbr/>
+ 有时候需要用多个记号来指定选项值。例如，选项 "--email-recipient"
可能会后跟多个 emails,
+ 每个都是一个单独的命令行记号。这种行为是被支持的，但是它可能导致
分析歧义，缺省是不激活的。
</para>
</listitem>
<listitem>
<para>The command line may contain positional options -- elements
which don't have any name. The command line parser provides a
mechanism to guess names for such options, as we've seen in the
- tutorial.
+ tutorial.<sbr/>
+ 命令行可能包含位置选项 -- 即没有名字的选项。
+ 命令行分析器提供了一种机制来猜测这些选项的名字，正如我们在指南
中看到的那样。
</para>
</listitem>
</itemizedlist>
@@ -428,26 +518,31 @@
<section>
- <title>Storage Component</title>
-
- <para>The storage component is responsible for:
+ <title>Storage Component 存储器组件</title>
+
+ <para>The storage component is responsible for:<sbr/>
+ 存储器组件负责：
<itemizedlist>
<listitem>
<para>Storing the final values of an option into a special class
and in
- regular variables</para>
+ regular variables<sbr/>
+ 将选项的最终值保存在一个特定类或普通变量中</para>
</listitem>
<listitem>
- <para>Handling priorities among different sources.</para>
+ <para>Handling priorities among different sources.<sbr/>
+ 处理不同源的优先级</para>
</listitem>
<listitem>
<para>Calling user-specified <code>notify</code> functions with
the final
- values of options.</para>
+ values of options.<sbr/>
+ 以选项的最终值调用用户指定的 <code>notify</code> 函数</para>
</listitem>
</itemizedlist>
</para>
- <para>Let's consider an example:
+ <para>Let's consider an example:<sbr/>
+ 我们来看看以下例子：
<programlisting>
variables_map vm;
store(parse_command_line(argc, argv, desc), vm);
@@ -458,57 +553,71 @@
values. The two calls to the <code>store</code> function add values
found on the command line and in the config file. Finally the call to
the <code>notify</code> function runs the user-specified notify
- functions and stores the values into regular variables, if needed.
+ functions and stores the values into regular variables, if
needed.<sbr/>
+ <code>variables_map</code> 类用于保存选项值。对 <code>store</code> 函
数的两次调用将命令行和配置文件中找到的选项值相加。
+ 最后一个对 <code>notify</code> 函数的调用则运行用户指定的通知函数，按
照需要将选项值保存到普通变量中。
</para>
<para>The priority is handled in a simple way: the <code>store</code>
function will not change the value of an option if it's already
assigned. In this case, if the command line specifies the value for
an
- option, any value in the config file is ignored.
+ option, any value in the config file is ignored.<sbr/>
+ 优先级的处理很简单：<code>store</code> 函数不会改变已赋值的选项的值。
+ 在以上例子，对于在命令行有指定值的选项，将在配置文件中忽略。
</para>
<warning>
<para>Don't forget to call the <code>notify</code> function after
you've
- stored all parsed values.</para>
+ stored all parsed values.<sbr/>
+ 在保存了所有分析值后，不要忘记调用 <code>notify</code> 函数。
+</para>
</warning>
</section>
<section>
- <title>Specific parsers</title>
+ <title>Specific parsers 特定分析器</title>
<section>
- <title>Configuration file parser</title>
+ <title>Configuration file parser 配置文件分析器</title>
<para>The &parse_config_file; function implements parsing
of simple INI-like configuration files. Configuration file
- syntax is line based:
+ syntax is line based:<sbr/>
+ &parse_config_file; 函数实现了简单的类INI配置文件的分析。配置文件的语
法是以基于行的：
</para>
<itemizedlist>
- <listitem><para>A line in the form:</para>
+ <listitem><para>A line in the form: <sbr/>
+ 形如这样的行：</para>
<screen>
<replaceable>name</replaceable>=<replaceable>value</replaceable>
</screen>
- <para>gives a value to an option.</para>
+ <para>gives a value to an option.<sbr/>
+ 将一个值赋于一个选项。</para>
</listitem>
- <listitem><para>A line in the form:</para>
+ <listitem><para>A line in the form:<sbr/>
+ 形如这样的行：</para>
<screen>
[<replaceable>section name</replaceable>]
</screen>
- <para>introduces a new section in the configuration file.</para>
+ <para>introduces a new section in the configuration file.<sbr/>
+ 在配置文件中引入一个新的节。</para>
</listitem>
<listitem><para>The <literal>#</literal> character introduces a
- comment that spans until the end of the line.</para>
+ comment that spans until the end of the line.<sbr/>
+ 字符 <literal>#</literal> 引入一段注释，直至行末。</para>
</listitem>
</itemizedlist>
<para>The option names are relative to the section names, so
- the following configuration file part:</para>
+ the following configuration file part:<sbr/>
+ 选项名与节名相关，所以以下配置文件部分：</para>
<screen>
[gui.accessibility]
visual_bell=yes
</screen>
- <para>is equivalent to</para>
+ <para>is equivalent to<sbr/>
+ 等同于</para>
<screen>
gui.accessibility.visual_bell=yes
</screen>
@@ -516,7 +625,7 @@
</section>
<section>
- <title>Environment variables parser</title>
+ <title>Environment variables parser 环境变量</title>
<para><firstterm>Environment variables</firstterm> are string
variables
which are available to all programs via the <code>getenv</code>
function
@@ -528,7 +637,12 @@
dialog, and on Unix —, the <filename>/etc/profile</filename>,
<filename>~/.profile</filename> and
<filename>~/.bash_profile</filename>
files. Because environment variables can be set for the entire
system,
- they are particularly suitable for options which apply to all
programs.
+ they are particularly suitable for options which apply to all
programs.<sbr/>
+ <firstterm>环境变量</firstterm> 是一种字符串变量，它可以在所有程序中
通过 C 运行时库中的 <code>getenv</code> 函数取得。
+ 操作系统允许为给定用户设置初始值，也可以在命令行上修改该值。例如，在
Windows 上你可以用 <filename>autoexec.bat</filename>
+ 文件或(在较新版本中) <filename>Control
Panel/System/Advanced/Environment Variables</filename> 对话框，
+ 而在 Unix 上则是 <filename>/etc/profile</filename>,
<filename>~/.profile</filename> 和
+ <filename>~/.bash_profile</filename> 文件。因为环境变量可以对整个系统
设置，它们特别适用于对所有程序有效的选项。
</para>
<para>The environment variables can be parsed with the
@@ -537,7 +651,10 @@
instance, and the second specifies what variables must be processed,
and
what option names must correspond to it. To describe the second
parameter we need to consider naming conventions for environment
- variables.</para>
+ variables.<sbr/>
+ 环境变量可通过 &parse_environment; 函数来分析。该函数有几个重载版本。
+ 第一个参数都是一个 &options_description; 实例，而第二个参数则指定哪个
要处理以及对应于哪个选项名。
+ 描述第二个参数时我们需要考虑环境变量的命名习惯。</para>
<para>If you have an option that should be specified via environment
variable, you need make up the variable's name. To avoid name
clashes,
@@ -551,7 +668,13 @@
Say, if you pass <literal>BOOST_</literal> as the prefix, and there
are
two variables, <envar>CVSROOT</envar> and
<envar>BOOST_PROXY</envar>, the
first variable will be ignored, and the second one will be converted
to
- option <literal>proxy</literal>.
+ option <literal>proxy</literal>. <sbr/>
+ 如果你有一个选项是由环境变量指定的，你需要起一个变量名。为避免名字冲
突，
+ 我们建议你为环境变量加一个足够独特的前缀。另外，选项名通常用小写，而
环境变量通常用大写。
+ 因此，对于选项名 <literal>proxy</literal>，对应的环境变量可以叫
<envar>BOOST_PROXY</envar>.
+ 在分析时，我们需要执行相反方向的名字转换。这通过将选定的前缀作为第二
个参数传递到 &parse_environment; 函数来完成。
+ 也就是说，如果你将 <literal>BOOST_</literal> 作为前缀传递，且有两个环
境变量, <envar>CVSROOT</envar>
+ 和 <envar>BOOST_PROXY</envar>, 则第一个变量将被略过，而第二个会转换为
选项 <literal>proxy</literal>.
</para>
<para>The above logic is sufficient in many cases, but it is also
@@ -559,17 +682,21 @@
function, any function taking a <code>std::string</code> and
returning
<code>std::string</code>. That function will be called for each
environment variable and should return either the name of the
option, or
- empty string if the variable should be ignored.
+ empty string if the variable should be ignored.<sbr/>
+ 以上逻辑对于多数情况已经足够，但是也可以将一个接受
<code>std::string</code>
+ 且返回 <code>std::string</code> 的函数作为第二参数传递给
parse_environment 函数。
+ 对于每个环境变量，传入的函数将被调用以返回对应的选项名，或者在要忽略
变量时返回空串。
</para>
</section>
</section>
<section>
- <title>Annotated List of Symbols</title>
+ <title>Annotated List of Symbols 符号列表</title>
<para>The following table describes all the important symbols in the
- library, for quick access.</para>
+ library, for quick access.<sbr/>
+ 下表给出了本库所有的重要符号，便于你快速查找。</para>
<informaltable pgwide="1">
@@ -579,58 +706,58 @@
<thead>
<row>
- <entry>Symbol</entry>
- <entry>Description</entry>
+ <entry>Symbol 符号</entry>
+ <entry>Description 描述</entry>
</row>
</thead>
<tbody>
<row>
- <entry namest='c1' nameend='c2'>Options description
component</entry>
+ <entry namest='c1' nameend='c2'>Options description component
选项描述组件</entry>
</row>
<row>
<entry>&options_description;</entry>
- <entry>describes a number of options</entry>
+ <entry>describes a number of options 描述选项的数量</entry>
</row>
<row>
<entry>&value;</entry>
- <entry>defines the option's value</entry>
+ <entry>defines the option's value 定义选项的值</entry>
</row>
<row>
- <entry namest='c1' nameend='c2'>Parsers component</entry>
+ <entry namest='c1' nameend='c2'>Parsers component 分析器组件
</entry>
</row>
<row>
<entry>&parse_command_line;</entry>
- <entry>parses command line (simpified interface)</entry>
+ <entry>parses command line (simpified interface) 分析命令行(简
单接口)</entry>
</row>
<row>
<entry>&basic_command_line_parser;</entry>
- <entry>parses command line (extended interface)</entry>
+ <entry>parses command line (extended interface) 分析命令行(扩展
接口)</entry>
</row>
<row>
<entry>&parse_config_file;</entry>
- <entry>parses config file</entry>
+ <entry>parses config file 分析配置文件</entry>
</row>
<row>
<entry>&parse_environment;</entry>
- <entry>parses environment</entry>
+ <entry>parses environment 分析环境变量</entry>
</row>
<row>
- <entry namest='c1' nameend='c2'>Storage component</entry>
+ <entry namest='c1' nameend='c2'>Storage component 存储器组件
</entry>
</row>
<row>
<entry>&variables_map;</entry>
- <entry>storage for option values</entry>
+ <entry>storage for option values 选项值的存储</entry>
</row>
</tbody>
=======================================
--- /trunk/libs/program_options/doc/program_options.xml Mon Dec 28 23:05:14
2009
+++ /trunk/libs/program_options/doc/program_options.xml Sun Jan 17 23:11:16
2010
@@ -37,33 +37,42 @@
<title>Boost.Program_options</title>
<section>
- <title>Introduction</title>
+ <title>Introduction 简介</title>
<para>The program_options library allows program developers to obtain
<emphasis>program options</emphasis>, that is (name, value) pairs from
the user,
- via conventional methods such as command line and config file.</para>
+ via conventional methods such as command line and config file.<sbr/>
+ program_options 库帮助程序开发者处理 <emphasis>program
options</emphasis>，
+ 即通过传统方法如命令行或配置文件的方式，从用户处获得的 (name, value)
对。</para>
<para>Why would you use such a library, and why is it better than
parsing
- your command line by straightforward hand-written code?
+ your command line by straightforward hand-written code?<sbr/>
+ 为什么你要使用这样一个库呢？为什么说它比你手工编写代码来分析命令行更好
呢？
<itemizedlist>
<listitem>
<para>It's easier. The syntax for declaring options is simple,
and
the library itself is small. Things like conversion of option
values to
desired type and storing into program variables are handled
- automatically.
+ automatically.<sbr/>
+ 它更容易使用。声明选项的语法很简单，库本身也很小。另外，
+ 例如把选项值转换为想要的类型并存入程序变量中，这样的事情都可以自
动处理。
</para>
</listitem>
<listitem>
<para>Error reporting is better. All the problems with the
command line are
reported, while hand-written code can just misparse the input.
In
addition, the usage message can be automatically generated, to
- avoid falling out of sync with the real list of options.</para>
+ avoid falling out of sync with the real list of options.<sbr/>
+ 更好的错误报告。命令行中的所有问题都会被报告，而手写代码可能会
漏掉处理某些输入；
+ 可以自动生成有关用法的提示信息，避免了提示信息与实际选项不同步
的情况。</para>
</listitem>
<listitem>
<para>Options can be read from anywhere. Sooner or later the
command
line will be not enough for your users, and you'll want config
files
or maybe even environment variables. These can be added without
significant
- effort on your part.
+ effort on your part.<sbr/>
+ 可以从任何地方读取选项。命令行的方式迟早会不够用，你可能想使用配
置文件甚至是环境变量。
+ 这些都可以加入进来，并且不影响已有的部分。
</para>
</listitem>
</itemizedlist>
@@ -71,7 +80,8 @@
<para>
Now let's see some examples of the library usage in the <xref
- linkend="program_options.tutorial"/>.
+ linkend="program_options.tutorial"/>.<sbr/>
+ 下面我们进入<xref linkend="program_options.tutorial"/>，来看一些关于
如何使用这个库的例子。
</para>
</section>
=======================================
--- /trunk/libs/program_options/doc/tutorial.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/program_options/doc/tutorial.xml Sun Jan 17 23:11:16 2010
@@ -7,25 +7,29 @@
]>
<section id="program_options.tutorial">
- <title>Tutorial</title>
+ <title>Tutorial 指南</title>
<para>In this section, we'll take a look at the most common usage
scenarios
of the program_options library, starting with the simplest one. The
examples
show only the interesting code parts, but the complete programs can be
found
in the "BOOST_ROOT/libs/program_options/example" directory. Through all
the
- examples, we'll assume that the following namespace alias is in effect:
+ examples, we'll assume that the following namespace alias is in
effect:<sbr/>
+ 在这一节中，我们将看到 program_options 库的一些最常见的用法，我们从最简单
的开始。
+ 这些例子只展示了相关的部分代码，你可以
在 "BOOST_ROOT/libs/program_options/example"
+ 目录下找到完整的程序。在所有这些例子中，我们都假设以下namespace别名有效：
<programlisting>namespace po = boost::program_options;</programlisting>
</para>
<section>
- <title>Getting Started</title>
+ <title>Getting Started 入门</title>
<para>The first example is the simplest possible: it only handles two
options. Here's the source code (the full program is in
- "example/first.cpp"):
+ "example/first.cpp"):<sbr/>
+ 第一个例子是最简单不过的了：它仅处理两个选项。以下是源代码 (完整的程序
在 "example/first.cpp")：
<programlisting>
-// Declare the supported options.
+// Declare the supported options. 声明被支持的选项。
po::options_description desc("Allowed options");
desc.add_options()
("help", "produce help message")
@@ -56,7 +60,10 @@
<code>operator()</code>. Calls to that operator actually declare
options. The parameters are option name, information about value, and
option
description. In this example, the first option has no value, and the
second
- one has a value of type <code>int</code>.
+ one has a value of type <code>int</code>.<sbr/>
+ 最开始，我们用 &options_description; 类来声明了所有允许的选项。该类的
<code>add_options</code> 方法返回一个特定的代理对象，
+ 该对象定义了 <code>operator()</code>。调用该操作符才真正声明了选项。调
用的参数包括：选项名、有关选项值的信息，
+ 以及选项的描述。在本例中，第一个选项没有值，而第二个具有类型为
<code>int</code> 的值。
</para>
<para>After that, an object of class <code>variables_map</code> is
@@ -64,18 +71,25 @@
values of arbitrary types. Next, the calls to <code>store</code>,
<code>parse_command_line</code> and <code>notify</code> functions cause
<code>vm</code> to contain all the options found on the command
- line.</para>
+ line.<sbr/>
+ 之后，声明了一个类型为 <code>variables_map</code> 的对象。这个类用于保
存各选项的值，
+ 它可以将值保存于任意的类型。接着，调用 <code>store</code>,
<code>parse_command_line</code>
+ 和 <code>notify</code> 函数，使得 vm 保存了命令行中发现的所有选项。
</para>
<para>And now, finally, we can use the options as we like. The
<code>variables_map</code> class can be used just like
<code>std::map</code>, except that values stored there must be
retrieved
with the <code>as</code> method shown above. (If the type specified in
the
call to the <code>as</code> method is different from the actually
stored
- type, an exception is thrown.)
+ type, an exception is thrown.)<sbr/>
+ 现在，我们可以随意使用这些选项了。类 <code>variables_map</code> 可以象
<code>std::map</code> 那样使用，
+ 区别仅在于必须使用 <code>as</code> 方法来获取其中保存的值。(如果调用
<code>as</code>
+ 方法时指定的类型不同于实际保存的值类型，将会抛出异常)。
</para>
<para>It's now a good time to try compiling the code yourself, but if
- you're not yet ready, here's an example session:
+ you're not yet ready, here's an example session:<sbr/>
+ 现在你可以试着编译和执行这段代码，如果你还没有环境，可以先看看下面的运
行结果：
<screen>
$<userinput>bin/gcc/debug/first</userinput>
Compression level was not set.
@@ -91,16 +105,20 @@
</section>
<section>
- <title>Option Details</title>
+ <title>Option Details 选项的细节</title>
<para>An option value, surely, can have other types than
<code>int</code>, and
can have other interesting properties, which we'll discuss right now. The
complete version of the code snipped below can be found in
- <filename>example/options_description.cpp</filename>.</para>
+ <filename>example/options_description.cpp</filename>.<sbr/>
+ 事实上，一个选项值可以是 <code>int</code> 以外的类型，也可以带有其它相关
的属性，下面我们来看一下。
+ 以下代码片断的完整版本可以在文件
<filename>example/options_description.cpp</filename> 中找到。</para>
<para>Imagine we're writing a compiler. It should take the optimization
level, a number of include paths, and a number of input files, and
perform some
- interesting work. Let's describe the options:
+ interesting work. Let's describe the options:<sbr/>
+ 想象一下我们正在编写一个编译器。它应该有一个优化级别，一系列的包含路
径，
+ 以及一系列输入文件，然后执行一系列相关的操作。我们来描述一下这些选项：
<programlisting>
int opt;
po::options_description desc("Allowed options");
@@ -116,13 +134,18 @@
</para>
<para>The <literal>"help"</literal> option should be familiar from
- the previous example. It's a good idea to have this option in all cases.
+ the previous example. It's a good idea to have this option in all
cases.<sbr/>
+ <literal>"help"</literal> 选项和上一个例子中的非常相似。通常在多数情况
下，
+ 有这样一个选项是不错的主意。
</para>
<para>The <literal>"optimization"</literal> option shows two new
features. First, we specify
the address of the variable(<code>&opt</code>). After storing
values, that
variable will have the value of the option. Second, we specify a
default
- value of 10, which will be used if no value is specified by the user.
+ value of 10, which will be used if no value is specified by the
user.<sbr/>
+ <literal>"optimization"</literal> 选项展示了两个新的特性。首先，我们指
定了一个变量地址(<code>&opt</code>)。
+ 在保存了相应的选项值后，这个变量将具有该选项的值。其次，我们指定了一个
缺省值 10，
+ 在用户没有指定这个选项时，它就会被使用。
</para>
<para>The <literal>"include-path"</literal> option is an example of the
@@ -130,25 +153,33 @@
class serves only one
source -- the command line. Users typically like to use short option
names
for common options, and the "include-path,I" name specifies that short
- option name is "I". So, both "--include-path" and "-I" can be used.
+ option name is "I". So, both "--include-path" and "-I" can be
used.<sbr/>
+ <literal>"include-path"</literal> 选项目前只展示了一个情况的例子，即
<code>options_description</code>
+ 类的接口只使用一个数据来源 -- 命令行。用户通常喜欢对常用选项使用短的名
字，"include-path,I" 就指定了一个短名 "I"。
+ 因此，"--include-path" 和 "-I" 两者都可以使用。
</para>
<para>Note also that the type of the <literal>"include-path"</literal>
option is <type>std::vector</type>. The library provides special
support for vectors -- it will be possible to specify the option several
- times, and all specified values will be collected in one vector.
+ times, and all specified values will be collected in one vector. <sbr/>
+ 另外，<literal>"include-path"</literal> 选项的类型是
<type>std::vector</type>。
+ 本库对 vectors 提供了特别的支持 -- 它可以多次指定选项，所有指定的值都会被
保存于一个 vector 中。
</para>
<para>The "input-file" option specifies the list of files to
- process. That's okay for a start, but, of course, writing something
like:
+ process. That's okay for a start, but, of course, writing something
like:<sbr/>
+ "input-file" 选项指定了要处理的文件列表。现在可以开始了，不过，象这样
写：
<screen>
<userinput>compiler --input-file=a.cpp</userinput>
</screen>
- is a little non-standard, compared with
+ is a little non-standard, compared with<sbr/>
+ 有点不太标准，更好的写法是：
<screen>
<userinput>compiler a.cpp</userinput>
</screen>
- We'll address this in a moment.
+ We'll address this in a moment.<sbr/>
+ 我们马上来处理这一点。
</para>
<para>
@@ -156,7 +187,10 @@
called "positional options" by this library. They can be handled
too. With a little help from the user, the library can decide
that "a.cpp"
really means the same as "--input-file=a.cpp". Here's the additional
code
- we need:
+ we need:<sbr/>
+ 象上面这样的不带选项名的命令行 tokens，在本库中被称为 "positional
options"。
+ 它们也是可以处理的。通过用户的一点点帮助，程序库可以判定 "a.cpp" 其实就
是
+ "--input-file=a.cpp"。以下是我们要增加了代码：
<programlisting>
po::positional_options_description p;
p.add("input-file", -1);
@@ -174,12 +208,16 @@
&command_line_parser; class to parse the command
line, not the &parse_command_line;
function. The latter is a convenient wrapper for simple cases, but now
we
- need to pass additional information.
+ need to pass additional information.<sbr/>
+ 头两行代码指定所有 positional options 都被转换为 "input-file" 选项。另
外，
+ 我们使用 &command_line_parser; 类来分析命令行，而不是
&parse_command_line; 函数。
+ 后者只能用于简单的情形，而我们现在需要更多的信息。
</para>
<para>By now, all options are described and parsed. We'll save ourselves
the
trouble of implementing the rest of the compiler logic and only
print the
- options:
+ options:<sbr/>
+ 现在，所有选项都已经写好并分析完了。我们不去管其余的编译器逻辑，只是
打印出这些选项就好了：
<programlisting>
if (vm.count("include-path"))
{
@@ -197,7 +235,8 @@
</programlisting>
</para>
- <para>Here's an example session:
+ <para>Here's an example session:<sbr/>
+ 下面是执行的结果：
<screen>
$<userinput>bin/gcc/debug/options_description --help</userinput>
Usage: options_description [options]
@@ -219,26 +258,33 @@
Oops, there's a slight problem. It's still possible to specify the
"--input-file" option, and usage message says so, which can be
confusing
for the user. It would be nice to hide this information, but let's wait
- for the next example.
+ for the next example.<sbr/>
+ 喔，还有一点点问题。由于还是可以指定 "--input-file" 选项，所以用法信息
中也列出来了，
+ 这可能会把用户搞混乱。最好是把这些信息隐藏掉，让我们看看下一个例子。
</para>
</section>
<section>
- <title>Multiple Sources</title>
+ <title>Multiple Sources 多个数据源</title>
<para>It's quite likely that specifying all options to our compiler on
the
command line will annoy users. What if a user installs a new library
and
wants to always pass an additional command line element? What if he has
made some choices which should be applied on every run? It's desirable
to
create a config file with common settings which will be used together
with
- the command line.
+ the command line.<sbr/>
+ 在命令行中指定所有选项可能会让用户很恼火。如果用户安装了一个新的库，
+ 希望某个命令行选项总是被使用，怎么办？又或者如果用户每次编译都要做一些
选择？
+ 最好的方法是让用户可以创建一个配置文件来保存常用的设置，这些设置可以和
命令行一起使用。
</para>
<para>Of course, there will be a need to combine the values from
command
line and config file. For example, the optimization level specified on
the
command line should override the value from the config file. On the
other
- hand, include paths should be combined.
+ hand, include paths should be combined.<sbr/>
+ 当然，我们还要把命令行中的选项值和配置文件中的组合起来。例如，
+ 命令行中指定的优化级别应该覆盖配置文件中的值。另一方面，两处的包含路径
则应该组合起来。
</para>
<para>Let's see the code now. The complete program is in
@@ -248,10 +294,15 @@
not all options are alike. Some options, like "input-file" above,
should
not be presented in an automatic help message. Some options make
sense only
in the config file. Finally, it's nice to have some structure in the
help message,
- not just a long list of options. Let's declare several option groups:
+ not just a long list of options. Let's declare several option
groups:<sbr/>
+ 现在我们来看看代码。完整的程序在 "examples/multiple_sources.cpp"。选
项的定义有两个要注意的地方。
+ 首先，我们声明几个 <code>options_description</code> 类的实例。原因
是，不是所有选项都是相似的。
+ 有些选项不应该自动显示在帮助信息中，如前面的 "input-file"；有些选项则
只在配置文件中有用。
+ 另外，最好在帮助信息中具有一些结构，而不仅仅是选项的一个长长的列表。
我们来声明几个选项组：
<programlisting>
// Declare a group of options that will be
// allowed only on command line
+// 声明一组只可用于命令行的选项
po::options_description generic("Generic options");
generic.add_options()
("version,v", "print version string")
@@ -261,6 +312,7 @@
// Declare a group of options that will be
// allowed both on command line and in
// config file
+// 声明一组可用于命令行和配置文件的选项
po::options_description config("Configuration");
config.add_options()
("optimization",
po::value<int>(&opt)->default_value(10),
@@ -272,6 +324,7 @@
// Hidden options, will be allowed both on command line and
// in config file, but will not be shown to the user.
+// 隐藏选项，可用于命令行和配置文件，但不会显示给用户看
po::options_description hidden("Hidden options");
hidden.add_options()
("input-file", po::value< vector<string> >(),
"input file")
@@ -279,12 +332,15 @@
</programlisting>
Note the call to the <code>composing</code> method in the
declaration of the
"include-path" option. It tells the library that values from
different sources
- should be composed together, as we'll see shortly.
+ should be composed together, as we'll see shortly.<sbr/>
+ 注意，要在 "include-path" 选项的声明中调用 <code>composing</code> 方
法。
+ 它告诉程序库从不同数据源获得的值应该组合起来。
</para>
<para>
The <code>add</code> method of the <code>options_description</code>
- class can be used to further group the options:
+ class can be used to further group the options:<sbr/>
+ <code>options_description</code> 类的 <code>add</code> 方法可用于进一
步把选项集合成组：
<programlisting>
po::options_description cmdline_options;
cmdline_options.add(generic).add(config).add(hidden);
@@ -303,10 +359,15 @@
happens if the same value is specified both on the command line and
in
config file? Usually, the value stored first is preferred. This is
what
happens for the "--optimization" option. For "composing" options,
like
- "include-file", the values are merged.
+ "include-file", the values are merged.<sbr/>
+ 分析及保存选项值则沿用通常的模式，除了一点，要额外调用
<functionname>parse_config_file</functionname>，
+ 以及调用两次 store 函数。如果在命令行和配置文件中都给出了同一个选项的
值，那又该怎么办呢？
+ 通常，最先保存的值会被优先使用，例如对于 "--optimization" 选项就是这
样。而对于 "composing" 选项，
+ 如 "include-file"，选项值会被合并。
</para>
- <para>Here's an example session:
+ <para>Here's an example session:<sbr/>
+ 以下是运行的例子：
<screen>
$<userinput>bin/gcc/debug/multiple_sources</userinput>
Include paths are: /opt
@@ -330,7 +391,9 @@
The first invocation uses values from the configuration file. The
second
invocation also uses values from command line. As we see, the include
paths on the command line and in the configuration file are merged,
- while optimization is taken from the command line.
+ while optimization is taken from the command line.<sbr/>
+ 第一次运行给出了配置文件中的选项值。第三次运行则同时使用了来自命令行
的选项值。
+ 正如我们所看到的，命令行和配置文件中给出的包含路径被合并起来了，而优
化级别则来自于命令行。
</para>
</section>
=======================================
--- /trunk/libs/proto/doc/acknowledgements.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/acknowledgements.qbk Sun Jan 17 23:11:16 2010
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:acknowledgements Appendix D: Acknowledgements]
+[section:acknowledgements Appendix D: Acknowledgements 附录D：鸣谢]
I'd like to thank Joel de Guzman and Hartmut Kaiser for being willing to
take a
chance on using Proto for their work on Spirit-2 and Karma when Proto was
=======================================
--- /trunk/libs/proto/doc/back_end.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/back_end.qbk Sun Jan 17 23:11:16 2010
@@ -7,25 +7,36 @@
[/================================================================================]
[section:back_end Back Ends:
- Making Expression Templates Do Useful Work]
+ Making Expression Templates Do Useful Work 后端：让表达式模板做有用的事
情]
[/================================================================================]
-Now that you've written the front end for your DSEL compiler, and you've
learned a bit about the intermediate form it produces, it's time to think
about what to /do/ with the intermediate form. This is where you put your
domain-specific algorithms and optimizations. Proto gives you two ways to
evaluate and manipulate expression templates: contexts and transforms.
+Now that you've written the front end for your DSEL compiler, and you've
learned a bit about the intermediate form it produces, it's time to think
about what to /do/ with the intermediate form. This is where you put your
domain-specific algorithms and optimizations. Proto gives you two ways to
evaluate and manipulate expression templates: contexts and transforms.\n
+现在你已经为你的DSEL编写了前端，也已经学习了一些关于它所生成的中间格式的知
识，是时候考虑要对这个中间格式/做些/什么了。
+这就是你置入你的领域专用算法和优化的地方。Proto 为你提供了两种方法来对表达
式模板进行求值和处理：上下文和变换。
* A /context/ is like a function object that you pass along with an
expression to
the _eval_ function. It associates behaviors with node types. _eval_
walks the
- expression and invokes your context at each node.
+ expression and invokes your context at each node.\n
+ /上下文/ 类似于一个函数对象，你可以把它与某个表达式一起传递给 _eval_ 函
数。
+ 它将某些行为与节点类型关联起来。_eval_ 对表达式进行遍历并在每个节点处调用
你的上下文。
* A /transform/ is a way to associate behaviors, not with node types in an
expression, but with rules in a Proto grammar. In this way, they are like
- semantic actions in other compiler-construction toolkits.
-
-Two ways to evaluate expressions! How to choose? Since contexts are
largely procedural, they are a bit simpler to understand and debug so they
are a good place to start. But although transforms are more advanced, they
are also more powerful; since they are associated with rules in your
grammar, you can select the proper transform based on the entire
/structure/ of a sub-expression rather than simply on the type of its
top-most node.
-
-Also, transforms have a concise and declarative syntax that can be
confusing at first, but highly expressive and fungible once you become
accustomed to it. And -- this is admittedly very subjective -- the author
finds programming with Proto transforms to be an inordinate amount of
/fun!/ Your mileage may vary.
+ semantic actions in other compiler-construction toolkits.\n
+ /变换/ 是将某些行为与 Proto 语法中的规则而不是与表达式的节点类型相关联的
方法。
+ 使用这种方法，类似于其它编译器构造工具中的语义动作。
+
+Two ways to evaluate expressions! How to choose? Since contexts are
largely procedural, they are a bit simpler to understand and debug so they
are a good place to start. But although transforms are more advanced, they
are also more powerful; since they are associated with rules in your
grammar, you can select the proper transform based on the entire
/structure/ of a sub-expression rather than simply on the type of its
top-most node.\n
+有两种方法对表达式进行求值！如何选择？因为上下文基本上是过程性的，它们对于
理解和调试来说更简单些，所以上下文是一个良好的开端。
+但是，变换更为高级，也更强大；因为它是与你的语法中的规则相关联的，
+你可以基于某个子表达式的整个/结构/而不仅仅是顶层节点的类型来选择正确的变
换。
+
+Also, transforms have a concise and declarative syntax that can be
confusing at first, but highly expressive and fungible once you become
accustomed to it. And -- this is admittedly very subjective -- the author
finds programming with Proto transforms to be an inordinate amount of
/fun!/ Your mileage may vary.\n
+另外，变换具有简明和声明性的语法，刚开始可能会有些混乱，但一旦你熟悉了
它，就会发现它具有高度的表达力和可替代性。
+而且 -- 这一点公认是非常主观的 -- 作者发现，用 Proto 变换来编程具有更多的
/乐趣/！你的感觉可能会有所不同。
[/================================================================================]
[section:expression_evaluation Expression Evaluation:
- Imparting Behaviors with a Context]
+ Imparting Behaviors with a Context 表达式求值：用上下文指定行为]
[/================================================================================]
Once you have constructed a Proto expression tree, either by using Proto's
@@ -34,20 +45,26 @@
a generic expression evaluator. To use _eval_, you'll need to define a
/context/ that tells _eval_ how each node should be evaluated. This section
goes through the nuts and bolts of using _eval_, defining evaluation
contexts,
-and using the contexts that Proto provides.
+and using the contexts that Proto provides.\n
+一旦你用 Proto 的操作符重载或是用 _make_expr_ 及其辅助物构造了一个 Proto 表
达式树，你可能想要实实在在地用它来/做些/什么。
+最简单的方式是使用 `proto::eval()`，它是一个泛型的表达式求值器。要使用
_eval_，你需要定义一个/上下文/，
+告知 _eval_ 如何对每个节点进行求值。本节将介绍使用 _eval_，定义求值上下
文，以及使用 Proto 所提供的上下文等细节。
[note `proto::eval()` is a less powerful but easier-to-use evaluation
technique
than Proto transforms, which are covered later. Although very powerful,
transforms have a steep learning curve and can be more difficult to debug.
`proto::eval()` is a rather weak tree traversal algorithm. Dan Marsden has
been working on a more general and powerful tree traversal library. When
it is
-ready, I anticipate that it will eliminate the need for `proto::eval()`.]
+ready, I anticipate that it will eliminate the need for `proto::eval()`.\n
+`proto::eval()` 是比 Proto 变换稍弱但更易于使用的一种求值技术，稍后我们将会
讨论到 Proto 变换。变换虽然很强大，
+但是却具有陡峭的学习曲线，而且很难调试。`proto::eval()` 则是一种相对较弱的
树遍历算法。
+Dan Marsden 已经在开发一个更为通用和强大的树遍历程序库。当他完成时，我期望
它可以完全替代 `proto::eval()`。]
[/================================================================]
-[section:proto_eval Evaluating an Expression with [^proto::eval()]]
+[section:proto_eval Evaluating an Expression with [^proto::eval()] 用
[^proto::eval()]求值一个表达式]
[/================================================================]
-[:[*Synopsis:]]
+[:[*Synopsis 摘要:]]
namespace proto
{
@@ -56,6 +73,7 @@
// A metafunction for calculating the return
// type of proto::eval() given certain Expr
// and Context types.
+ // 用于计算给定了Expr和Context类型的proto::eval()的返回类型的元
函数
template<typename Expr, typename Context>
struct eval
{
@@ -69,6 +87,7 @@
{
// A callable function object type for evaluating
// a Proto expression with a certain context.
+ // 用于以特定上下文对一个Proto表达式进行求值的可调用函数对象
struct eval : callable
{
template<typename Sig>
@@ -97,24 +116,29 @@
Simply pass the expression and the context to _eval_ and it does the rest
and
returns the result. You can use the `eval<>` metafunction in the
`proto::result_of` namespace to compute the return type of _eval_. The
-following demonstrates a use of _eval_:
+following demonstrates a use of _eval_:\n
+给定一个表达式和一个求值上下文，使用 _eval_ 是很简单的。只要将表达式和上下
文传递给 _eval_ 就可以了，
+它会完成剩余的任务并返回结果。你可以用 `proto::result_of` 名字空间中的
`eval<>` 元函数来计算 _eval_ 的返回类型。
+以下示范了 _eval_ 的使用：
template<typename Expr>
typename proto::result_of::eval<Expr const, MyContext>::type
MyEvaluate(Expr const &expr)
{
- // Some user-defined context type
+ // Some user-defined context type 用户定义的上下文类型
MyContext ctx;
- // Evaluate an expression with the context
+ // Evaluate an expression with the context 以该上下文对一个表达式求
值
return proto::eval(expr, ctx);
}
What _eval_ does is also very simple. It defers most of the work to the
-context itself. Here essentially is the implementation of _eval_:
+context itself. Here essentially is the implementation of _eval_:\n
+_eval_ 所做的也很简单。它将多数工作推给上下文本身。以下是 _eval_ 的实现：
// eval() dispatches to a nested "eval<>" function
// object within the Context:
+ // eval()分派至Context内嵌的一个"eval<>"函数对象：
template<typename Expr, typename Context>
typename Context::template eval<Expr>::result_type
eval(Expr &expr, Context &ctx)
@@ -125,63 +149,75 @@
Really, _eval_ is nothing more than a thin wrapper that dispatches to the
appropriate handler within the context class. In the next section, we'll
see
-how to implement a context class from scratch.
+how to implement a context class from scratch.\n
+其实，_eval_ 只是一个很薄的包装器，将任务分派至上下文类中适当的处理者。
+在下一节中，我们将看到如何从零开始实现一个上下文类。
[endsect]
[/==============================================]
-[section:contexts Defining an Evaluation Context]
+[section:contexts Defining an Evaluation Context 定义一个求值上下文]
[/==============================================]
As we saw in the previous section, there is really not much to the _eval_
function. Rather, all the interesting expression evaluation goes on within
-a context class. This section shows how to implement one from scratch.
-
-All context classes have roughly the following form:
-
- // A prototypical user-defined context.
+a context class. This section shows how to implement one from scratch.\n
+正如我们在上一节中所看到的，对于 _eval_ 函数确实没有更多东西了。相反，
+表达式求值的所有有趣动作都是在上下文类的内部。本节将展示如何如何从零开始实
现一个上下文。
+
+All context classes have roughly the following form:\n
+所有的上下文类都大概是以下形式：
+
+ // A prototypical user-defined context. 一个proto型的用户自定义上下文。
struct MyContext
{
- // A nested eval<> class template
+ // A nested eval<> class template 嵌套的eval<>类模板
template<
typename Expr
, typename Tag = typename proto::tag_of<Expr>::type
>
struct eval;
- // Handle terminal nodes here...
+ // Handle terminal nodes here... 在此处理终结符节点...
template<typename Expr>
struct eval<Expr, proto::tag::terminal>
{
- // Must have a nested result_type typedef.
+ // Must have a nested result_type typedef. 必须有一个嵌套的
result_type typedef.
typedef ... result_type;
// Must have a function call operator that takes
// an expression and the context.
+ // 必须有一个函数调用操作符，接受一个表达式及本上下文。
result_type operator()(Expr &expr, MyContext &ctx) const
{
return ...;
}
};
- // ... other specializations of struct eval<> ...
+ // ... other specializations of struct eval<> 其它的struct eval<>特
化 ...
};
Context classes are nothing more than a collection of specializations of a
nested `eval<>` class template. Each specialization handles a different
-expression type.
+expression type.\n
+上下文类其实就是一组嵌套的 `eval<>` 类型模板的特化。每一个特化处理一种不同
的表达式类型。
In the [link boost_proto.users_guide.getting_started.hello_calculator
Hello Calculator]
section, we saw an example of a user-defined context class for evaluating
calculator expressions. That context class was implemented with the help
of Proto's _callable_context_. If we were to implement it from scratch, it
-would look something like this:
+would look something like this:\n
+在 [link boost_proto.users_guide.getting_started.hello_calculator Hello
Calculator] 一节中，
+我们看过一个用户自定义上下文的例子，用于对计算器表达式进行求值。那个上下文
类是在 Proto 的
+_callable_context_ 的帮助下实现的。如果我们要从零开始实现它，它看起来会是象
这样：
// The calculator_context from the "Hello Calculator" section,
// implemented from scratch.
+ // 从零开始实现"Hello Calculator"一节中的calculator_context。
struct calculator_context
{
// The values with which we'll replace the placeholders
+ // 我们准备用于替换占位符的值。
std::vector<double> args;
template<
@@ -189,12 +225,13 @@
// defaulted template parameters, so we can
// specialize on the expressions that need
// special handling.
+ // 缺省的模板参数，这样我们就可以对需要特殊处理的表达式进行特
化。
, typename Tag = typename proto::tag_of<Expr>::type
, typename Arg0 = typename proto::child_c<Expr, 0>::type
>
struct eval;
- // Handle placeholder terminals here...
+ // Handle placeholder terminals here... 在此处理占位符终结符...
template<typename Expr, int I>
struct eval<Expr, proto::tag::terminal, placeholder<I> >
{
@@ -206,7 +243,7 @@
}
};
- // Handle other terminals here...
+ // Handle other terminals here... 在此处理其它终结符...
template<typename Expr, typename Arg0>
struct eval<Expr, proto::tag::terminal, Arg0>
{
@@ -218,7 +255,7 @@
}
};
- // Handle addition here...
+ // Handle addition here... 在此处理加法...
template<typename Expr, typename Arg0>
struct eval<Expr, proto::tag::plus, Arg0>
{
@@ -232,12 +269,15 @@
};
// ... other eval<> specializations for other node types ...
+ // ...对于其它节点类型的eval<>特化...
};
Now we can use _eval_ with the context class above to evaluate calculator
-expressions as follows:
+expressions as follows:\n
+现在我们可以以这个上下文类来用 proto::eval() 对计算器表达式进行求值，如下：
// Evaluate an expression with a calculator_context
+ // 用一个calculator_context对一个表达式进行求值
calculator_context ctx;
ctx.args.push_back(5);
ctx.args.push_back(6);
@@ -248,32 +288,42 @@
you complete control over how the expression is evaluated. The context
class in
the [link boost_proto.users_guide.getting_started.hello_calculator Hello
Calculator] example
was much simpler. In the next section we'll see the helper class Proto
provides
-to ease the job of implementing context classes.
+to ease the job of implementing context classes.\n
+这种从零开始定义一个上下文的方法是沉闷而冗长的，但是它可以让你完成控制如何
对表达式进行求值。
+在 [link boost_proto.users_guide.getting_started.hello_calculator Hello
Calculator]
+的例子中的上下文类更为简单。在下一节，我们将看到 Proto 所提供的辅助类，它们
可以让实现上下文类的工作变得更为容易。
[endsect]
[/================================================]
-[section:canned_contexts Proto's Built-In Contexts]
+[section:canned_contexts Proto's Built-In Contexts Proto的内建上下文]
[/================================================]
Proto provides some ready-made context classes that you can use as-is, or
that
-you can use to help while implementing your own contexts. They are:
+you can use to help while implementing your own contexts. They are:\n
+Proto 提供了一些可用的上下文类，你可以原样照用，或者用它们来帮助你实现自己
的上下文。它们包括：
[variablelist
[ [[link
boost_proto.users_guide.back_end.expression_evaluation.canned_contexts.default_context
[^default_context]]]
[An evaluation context that assigns the usual C++ meanings to all the
operators. For example, addition nodes are handled by evaluating the
left and right children and then adding the results. The
_default_context_
- uses Boost.Typeof to deduce the types of the expressions it
evaluates.] ]
+ uses Boost.Typeof to deduce the types of the expressions it
evaluates.\n
+ 为所有操作符赋予通常的C++意义的求值上下文。例如，加法节点的处理方法
是，
+ 对左、右子节点求值，然后将结果相加。_default_context_ 使用了
Boost.Typeof
+ 来推断所求值的表达式的类型。] ]
[ [[link
boost_proto.users_guide.back_end.expression_evaluation.canned_contexts.null_context
[^null_context]]]
[A simple context that recursively evaluates children but does not
combine
- the results in any way and returns void.] ]
+ the results in any way and returns void.\n
+ 一个简单的上下文，递归地对子节点进行求值，但不以任何方式对结果进行组
合，返回 void。] ]
[ [[link
boost_proto.users_guide.back_end.expression_evaluation.canned_contexts.callable_context
[^callable_context<>]]]
[A helper that simplifies the job of writing context classes. Rather
than
writing template specializations, with _callable_context_ you write a
function object with an overloaded function call operator. Any
expressions
not handled by an overload are automatically dispatched to a default
- evaluation context that you can specify.] ]
+ evaluation context that you can specify.\n
+ 帮助简化编写上下文类的工作的助手。使用 _callable_context_，不再需要编
写模板特化，
+ 而是以重载的函数调用操作符编写一个函数对象。任何没有被重载进行处理的表
达式将自动分派至你指定的某个缺省求值上下文。] ]
]
[/=========================================]
@@ -284,9 +334,13 @@
meanings to all the operators. For example, addition nodes are handled by
evaluating the left and right children and then adding the results. The
_default_context_ uses Boost.Typeof to deduce the types of the expressions
it
-evaluates.
-
-For example, consider the following "Hello World" example:
+evaluates.\n
+_default_context_ 是一个为所有操作符赋予普通的C++意义的求值上下文。例如，
+加法节点的处理方法是，对左、右子节点求值，然后将结果相加。_default_context_
+使用了 Boost.Typeof 来推断所求值的表达式的类型。
+
+For example, consider the following "Hello World" example:\n
+例如，考虑以下 "Hello World" 示例：
#include <iostream>
#include <boost/proto/proto.hpp>
@@ -301,6 +355,7 @@
{
// Evaluate the expression with default_context,
// to give the operators their C++ meanings:
+ // 以default_context对表达式求值，给予操作符本身的C++意义：
proto::default_context ctx;
proto::eval(expr, ctx);
}
@@ -311,16 +366,18 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+该程序的输出如下：
[pre
hello, world
]
_default_context_ is trivially defined in terms of a `default_eval<>`
-template, as follows:
-
- // Definition of default_context
+template, as follows:\n
+_default_context_ 是很简单地根据一个 `default_eval<>` 模板来定义的，如下：
+
+ // Definition of default_context default_context的定义
struct default_context
{
template<typename Expr>
@@ -335,9 +392,10 @@
There are a bunch of `default_eval<>` specializations, each of which
handles
a different C++ operator. Here, for instance, is the specialization for
binary
-addition:
-
- // A default expression evaluator for binary addition
+addition:\n
+有一组 `default_eval<>` 特化，每一个特化处理一个C++操作符。例如，以下是对二
元加法的特化：
+
+ // A default expression evaluator for binary addition 对二元加法的缺省
表达式求值器
template<typename Expr, typename Context>
struct default_eval<Expr, Context, proto::tag::plus>
{
@@ -366,7 +424,11 @@
directly, so `default_eval<>` uses the Boost.Typeof library to emulate it.
On
some compilers, that may mean that `default_context` either doesn't work or
that it requires you to register your types with the Boost.Typeof library.
-Check the documentation for Boost.Typeof to see.
+Check the documentation for Boost.Typeof to see.\n
+以上代码使用了 `decltype` 来计算函数调用操作符的返回类型。`decltype` 是下一
个C++版本中的新关键字，
+取出任一表达式的类型。多数编译器尚未直接支持 `decltype`，所以
`default_eval<>` 使用 Boost.Typeof 库来模拟它。
+在某些编译器上，这可能意味着 `default_context` 不能工作，或是要求你要将你的
类型注册到 Boost.Typeof 库。
+请查阅 Boost.Typeof 相关文档。
[endsect]
@@ -378,11 +440,15 @@
but does not combine the results in any way and returns void. It is useful
in conjunction with `callable_context<>`, or when defining your own
contexts
which mutate an expression tree in-place rather than accumulate a result,
as
-we'll see below.
-
-_null_context_ is trivially implemented in terms of `null_eval<>` as
follows:
-
- // Definition of null_context
+we'll see below.\n
+_null_context_ 是一个简单的上下文，递归地对子节点进行求值，但不以任何方式对
结果进行组合，返回 void。
+它可以与 `callable_context<>` 一起使用，或是在定义那些要就地修改表达式树而
不是要计算结果的上下文时使用，
+稍后我们将看到相关示例。
+
+_null_context_ is trivially implemented in terms of `null_eval<>` as
follows:\n
+_null_context_ 是很简单地根据 `null_eval<>` 来实现的，如下：
+
+ // Definition of null_context null_context的定义
struct null_context
{
template<typename Expr>
@@ -392,9 +458,10 @@
};
And `null_eval<>` is also trivially implemented. Here, for instance is
-a binary `null_eval<>`:
-
- // Binary null_eval<>
+a binary `null_eval<>`:\n
+`null_eval<>` 的实现也很简单。例如，以上是一个二元的 `null_eval<>`：
+
+ // Binary null_eval<> 二元null_eval<>
template<typename Expr, typename Context>
struct null_eval<Expr, Context, 2>
{
@@ -409,18 +476,21 @@
When would such classes be useful? Imagine you have an expression tree with
integer terminals, and you would like to increment each integer in-place.
You
-might define an evaluation context as follows:
+might define an evaluation context as follows:\n
+这样的类在什么时候有用呢？想象一下，你有一个带整数终结符的表达式树，你想就
地将每个整数加一。
+你可以如下定义一个求值上下文：
struct increment_ints
{
// By default, just evaluate all children by delegating
// to the null_eval<>
+ // 缺省时，委派至null_eval<>时只对子节点求值
template<typename Expr, typename Arg =
proto::result_of::child<Expr>::type>
struct eval
: null_eval<Expr, increment_ints const>
{};
- // Increment integer terminals
+ // Increment integer terminals 将整数终结符加一
template<typename Expr>
struct eval<Expr, int>
{
@@ -434,7 +504,8 @@
};
In the next section on _callable_context_, we'll see an even simpler way to
-achieve the same thing.
+achieve the same thing.\n
+在下一节的 _callable_context_ 中，我们将看到一个完成相同任务的更为简单的方
法。
[endsect]
@@ -446,35 +517,43 @@
classes. Rather than writing template specializations, with
_callable_context_
you write a function object with an overloaded function call operator. Any
expressions not handled by an overload are automatically dispatched to a
-default evaluation context that you can specify.
+default evaluation context that you can specify.\n
+_callable_context_ 是一个帮助简化编写上下文类的工作的助手。使用
_callable_context_，不再需要编写模板特化，
+而是以重载的函数调用操作符编写一个函数对象。任何没有被重载进行处理的表达式
将自动分派至你指定的某个缺省求值上下文。
Rather than an evaluation context in its own right, _callable_context_ is
more
properly thought of as a context adaptor. To use it, you must define your
own
-context that inherits from _callable_context_.
+context that inherits from _callable_context_.\n
+与其说它是一个求值上下文，不如说 _callable_context_ 是一个上下文适配器更为
恰当。
+要使用它，你必须从 _callable_context_ 派生你自己的上下文。
In the [link
boost_proto.users_guide.back_end.expression_evaluation.canned_contexts.null_context
[^null_context]]
section, we saw how to implement an evaluation context that increments all
the
integers within an expression tree. Here is how to do the same thing with
the
-_callable_context_:
+_callable_context_:\n
+在 [link
boost_proto.users_guide.back_end.expression_evaluation.canned_contexts.null_context
[^null_context]] 一节中，
+我们看到了如何实现一个对表达式树中所有整数进行加一运算的求值上下文。以下是
如何用 _callable_context_ 完成相同任务的方法：
// An evaluation context that increments all
- // integer terminals in-place.
+ // integer terminals in-place.\n
+ // 将所有整数终结符就地加一的求值上下文
struct increment_ints
: callable_context<
- increment_ints const // derived context
- , null_context const // fall-back context
+ increment_ints const // derived context 派生的上下文
+ , null_context const // fall-back context 后传的上下文
>
{
typedef void result_type;
- // Handle int terminals here:
+ // Handle int terminals here: 在此处理终结符：
void operator()(proto::tag::terminal, int &i) const
{
++i;
}
};
-With such a context, we can do the following:
+With such a context, we can do the following:\n
+用这个上下文，我们可以做：
literal<int> i = 0, j = 10;
proto::eval( i - j * 3.14, increment_ints() );
@@ -483,7 +562,8 @@
std::cout << "j = " << j.get() << std::endl;
This program outputs the following, which shows that the integers `i` and
`j`
-have been incremented by `1`:
+have been incremented by `1`:\n
+该程序输出如下，其中显示整数 `i` 和 `j` 都加了 `1`:
[pre
i = 1
@@ -496,7 +576,10 @@
fall-back context. For each node in the expression tree being evaluated,
_callable_context_ checks to see if there is an overloaded `operator()` in
the
derived context that accepts it. Given some expression `expr` of type
`Expr`,
-and a context `ctx`, it attempts to call:
+and a context `ctx`, it attempts to call:\n
+在 `increment_ints` 上下文中，我们不需要定义嵌套的 `eval<>` 模板。这是因为
_callable_context_ 已经为我们实现了它们。
+_callable_context_ 带有两个模板参数：派生的上下文和后传的上下文。对于被求值
表达式树中的每个节点，_callable_context_
+检查在派生上下文中是否有一个重载的 `operator()` 接受它。给定类型为 `Expr`
的表达式 `expr`，以及一个上下文 `ctx`，它尝试调用：
ctx(
typename Expr::proto_tag()
@@ -508,25 +591,30 @@
Using function overloading and metaprogramming tricks, _callable_context_
can
detect at compile-time whether such a function exists or not. If so, that
function is called. If not, the current expression is passed to the
fall-back
-evaluation context to be processed.
+evaluation context to be processed.\n
+通过使用函数重载和元编程技巧，_callable_context_ 可以在编译期检测出是否有一
个这样的函数存在。
+如果有，则调用该函数。如果没有，则将当前表达式传递给后传上下文来处理。
We saw another example of the _callable_context_ when we looked at the
simple
calculator expression evaluator. There, we wanted to customize the
evaluation
of placeholder terminals, and delegate the handling of all other nodes to
the
-_default_context_. We did that as follows:
+_default_context_. We did that as follows:\n
+我们来看 _callable_context_ 的另一个例子，我们看一个简单的计算器表达式求值
器。
+我们想定制对占位符终结符的求值，并将所有其它节点的处理委派给
_default_context_。我们可以这样做：
// An evaluation context for calculator expressions that
// explicitly handles placeholder terminals, but defers the
// processing of all other nodes to the default_context.
+ // 一个计算器表达式的求值上下文，显式地处理占位符终结符，而将所有其它节
点的处理交给 default_context.
struct calculator_context
: proto::callable_context< calculator_context const >
{
std::vector<double> args;
- // Define the result type of the calculator.
+ // Define the result type of the calculator. 定义计算器的返回类型。
typedef double result_type;
- // Handle the placeholders:
+ // Handle the placeholders: 处理占位符：
template<int I>
double operator()(proto::tag::terminal, placeholder<I>) const
{
@@ -538,7 +626,9 @@
_callable_context_ uses the _default_context_. With the above
`calculator_context` and a couple of appropriately defined placeholder
terminals, we can evaluate calculator expressions, as demonstrated
-below:
+below:\n
+在这个例子中，我们没有指定后传上下文。为此，_callable_context_ 使用了
_default_context_。
+使用以上 `calculator_context` 以及一些适当定义的占位符终结符，我们可以对计
算器表达式求值，示范如下：
template<int I>
struct placeholder
@@ -555,7 +645,8 @@
double j = proto::eval( (_2 - _1) / _2 * 100, ctx );
std::cout << "j = " << j << std::endl;
-The above code displays the following:
+The above code displays the following:\n
+以上代码输出如下：
[pre
j = 20
@@ -570,39 +661,57 @@
[import ../test/examples.cpp]
[/============================================================================]
-[section:expression_transformation Expression Transformation: Semantic
Actions]
+[section:expression_transformation Expression Transformation: Semantic
Actions 表达式变换：语义动作]
[/============================================================================]
-If you have ever built a parser with the help of a tool like Antlr, yacc
or Boost.Spirit, you might be familiar with /semantic actions/. In addition
to allowing you to define the grammar of the language recognized by the
parser, these tools let you embed code within your grammar that executes
when parts of the grammar participate in a parse. Proto has the equivalent
of semantic actions. They are called /transforms/. This section describes
how to embed transforms within your Proto grammars, turning your grammars
into function objects that can manipulate or evaluate expressions in
powerful ways.
-
-Proto transforms are an advanced topic. We'll take it slow, using examples
to illustrate the key concepts, starting simple.
+If you have ever built a parser with the help of a tool like Antlr, yacc
or Boost.Spirit, you might be familiar with /semantic actions/. In addition
to allowing you to define the grammar of the language recognized by the
parser, these tools let you embed code within your grammar that executes
when parts of the grammar participate in a parse. Proto has the equivalent
of semantic actions. They are called /transforms/. This section describes
how to embed transforms within your Proto grammars, turning your grammars
into function objects that can manipulate or evaluate expressions in
powerful ways.\n
+如果你曾经在某个工具，如 Antlr, yacc 或 Boost.Spirit，的帮助下构建过一个词
法分析器，你可能会知道/语义动作/。
+除了可以让你定义词法分析器所识别的语言的语法之外，这些工具还可以让你将一些
代码嵌入到你的语法中，当这部分语法在分析时可以执行这些代码。
+Proto 也有与语义动作相当的东西。它们被称为/变换/。本节将描述如何将变换嵌入
到你的 Proto 语法中，将你的语法变为函数对象，
+以更强大的方式来操纵表达式和进行求值。
+
+Proto transforms are an advanced topic. We'll take it slow, using examples
to illustrate the key concepts, starting simple.\n
+Proto 变换是一个高级议题。我们会慢慢讲，用一些例子来示范其中的关键概念，先
从简单的开始。
[/==================================]
-[section ["Activating] Your Grammars]
+[section ["Activating] Your Grammars "激活"你的语法]
[/==================================]
-The Proto grammars we've seen so far are static. You can check at
compile-time to see if an expression type matches a grammar, but that's it.
Things get more interesting when you give them runtime behaviors. A grammar
with embedded transforms is more than just a static grammar. It is a
function object that accepts expressions that match the grammar and does
/something/ with them.
-
-Below is a very simple grammar. It matches terminal expressions.
+The Proto grammars we've seen so far are static. You can check at
compile-time to see if an expression type matches a grammar, but that's it.
Things get more interesting when you give them runtime behaviors. A grammar
with embedded transforms is more than just a static grammar. It is a
function object that accepts expressions that match the grammar and does
/something/ with them.\n
+到目前为止，我们见到的 Proto 语法都是静态的。你可以在编译期检查某个表达式类
型是否与语法匹配，仅此而已。
+如果你给予它们运行期行为，则事情会更有趣。嵌入了变换的语法不再仅仅是一个静
态语法而已。它是一个函数对象，
+接受与此语法匹配的表达式，并会对它们做些/事情/。
+
+Below is a very simple grammar. It matches terminal expressions.\n
+以下是一个更深简单的语法。它匹配终结符表达式。
// A simple Proto grammar that matches all terminals
+ // 一个匹配所有终结符的简单的 Proto 语法
proto::terminal< _ >
-Here is the same grammar with a transform that extracts the value from the
terminal:
+Here is the same grammar with a transform that extracts the value from the
terminal:\n
+以下是一个相同的语法，带有一个从终结符取出值的变换：
// A simple Proto grammar that matches all terminals
// *and* a function object that extracts the value from
// the terminal
+ // 一个匹配所有终结符的简单的Proto语法，以及一个从终结符取出值的函数对
象
proto::when<
proto::terminal< _ >
- , proto::_value // <-- Look, a transform!
+ , proto::_value // <-- Look, a transform! 看，这是一个变换！
>
-You can read this as follows: when you match a terminal expression,
extract the value. The type `proto::_value` is a so-called transform. Later
we'll see what makes it a transform, but for now just think of it as a kind
of function object. Note the use of _when_: the first template parameter is
the grammar to match and the second is the transform to execute. The result
is both a grammar that matches terminal expressions and a function object
that accepts terminal expressions and extracts their values.
-
-As with ordinary grammars, we can define an empty struct that inherits
from a grammar+transform to give us an easy way to refer back to the thing
we're defining, as follows:
+You can read this as follows: when you match a terminal expression,
extract the value. The type `proto::_value` is a so-called transform. Later
we'll see what makes it a transform, but for now just think of it as a kind
of function object. Note the use of _when_: the first template parameter is
the grammar to match and the second is the transform to execute. The result
is both a grammar that matches terminal expressions and a function object
that accepts terminal expressions and extracts their values. \n
+你可以之样来读它：当你匹配了一个终结符表达式，取出它的值。类型
`proto::_value` 是一个所谓的变换。
+稍后我们将看到是什么使得它成为一个变换，不过现在我们只把它想象为一种函数对
象。留意 _when_ 的用法：
+第一个模板参数是要匹配的语法，第二个是要执行的变换。其结果既是一个匹配终结
符表达式的语法，
+也是一个接受终结符表达式并返回其值的函数对象。
+
+As with ordinary grammars, we can define an empty struct that inherits
from a grammar+transform to give us an easy way to refer back to the thing
we're defining, as follows:\n
+和普通的语法一样，我们可以定义一个空的结构，派生自一个语法+变换，这样可以很
容易地引用回我们定义的东西，如下：
// A grammar and a function object, as before
+ // 一个语法和一个函数对象，如前
struct Value
: proto::when<
proto::terminal< _ >
@@ -611,48 +720,65 @@
{};
// "Value" is a grammar that matches terminal expressions
+ // ”Value"是一个匹配终结符表达式的语法
BOOST_MPL_ASSERT(( proto::matches< proto::terminal<int>::type, Value >
));
// "Value" also defines a function object that accepts terminals
// and extracts their value.
+ // "Value"也定义了一个接受一个终结符并取出其值的函数对象。
proto::terminal<int>::type answer = {42};
Value get_value;
int i = get_value( answer );
-As already mentioned, `Value` is a grammar that matches terminal
expressions and a function object that operates on terminal expressions. It
would be an error to pass a non-terminal expression to the `Value` function
object. This is a general property of grammars with transforms; when using
them as function objects, expressions passed to them must match the grammar.
-
-Proto grammars are valid TR1-style function objects. That means you can
use `boost::result_of<>` to ask a grammar what its return type will be,
given a particular expression type. For instance, we can access the `Value`
grammar's return type as follows:
+As already mentioned, `Value` is a grammar that matches terminal
expressions and a function object that operates on terminal expressions. It
would be an error to pass a non-terminal expression to the `Value` function
object. This is a general property of grammars with transforms; when using
them as function objects, expressions passed to them must match the
grammar.\n
+前面已经提过，`Value` 是一个匹配终结符表达式的语法，也是一个操作于终结符表
达式之上的函数对象。
+传递一个非终结符表达式给 `Value` 函数对象是错误的。这是带有变换的语法的基本
特性；把它们当作函数对象使用时，
+传递给它们的表达式必须符合相应的语法。
+
+Proto grammars are valid TR1-style function objects. That means you can
use `boost::result_of<>` to ask a grammar what its return type will be,
given a particular expression type. For instance, we can access the `Value`
grammar's return type as follows:\n
+Proto 语法是有效的TR1风格的函数对象。这意味着你可以用 `boost::result_of<>`
来询问某个语法，给定一个特定的表达式类型，
+它的返回类型是什么。例如，我们可以如下获得 `Value` 语法的返回类型：
// We can use boost::result_of<> to get the return type
// of a Proto grammar.
+ // 我们可以用 boost::result_of<> 来获得一个 Proto 语法的返回类型
typedef
typename boost::result_of<Value(proto::terminal<int>::type)>::type
result_type;
// Check that we got the type we expected
+ // 检查我们获得的类型是否所期望的
BOOST_MPL_ASSERT(( boost::is_same<result_type, int> ));
-[note A grammar with embedded transforms is both a grammar and a function
object. Calling these things "grammars with transforms" would get tedious.
We could call them something like "active grammars", but as we'll see
/every/ grammar that you can define with Proto is "active"; that is, every
grammar has some behavior when used as a function object. So we'll continue
calling these things plain "grammars". The term "transform" is reserved for
the thing that is used as the second parameter to the _when_ template.]
+[note A grammar with embedded transforms is both a grammar and a function
object. Calling these things "grammars with transforms" would get tedious.
We could call them something like "active grammars", but as we'll see
/every/ grammar that you can define with Proto is "active"; that is, every
grammar has some behavior when used as a function object. So we'll continue
calling these things plain "grammars". The term "transform" is reserved for
the thing that is used as the second parameter to the _when_ template.\n
+一个带有内嵌变换的语法既是一个语法，也是一个函数对象。把它称为"带变换的语
法"太过麻烦。我们可以称之为"主动语法"，不过，
+就象我们即将看到的那样，你用 Proto 定义的/每一个/语法都是"主动"的；即，每一
个语法被作为函数对象使用时都会有一些行为。
+所以，我们继续把它们称为"语法"就算了。术语"变换"保留作为对 _when_ 模板的第
二个参数的称呼。]
[endsect]
[/=========================================]
-[section Handling Alternation and Recursion]
+[section Handling Alternation and Recursion 处理多选与递归]
[/=========================================]
-Most grammars are a little more complicated than the one in the preceding
section. For the sake of illustration, let's define a rather nonsensical
grammar that matches any expression and recurses to the leftmost terminal
and returns its value. It will demonstrate how two key concepts of Proto
grammars -- alternation and recursion -- interact with transforms. The
grammar is described below.
+Most grammars are a little more complicated than the one in the preceding
section. For the sake of illustration, let's define a rather nonsensical
grammar that matches any expression and recurses to the leftmost terminal
and returns its value. It will demonstrate how two key concepts of Proto
grammars -- alternation and recursion -- interact with transforms. The
grammar is described below.\n
+多数语法要比上一节中的复杂一点。为了示范之用，我们来定义一个荒谬的语法，它
匹配任意的表达式，递归至最左侧的终结符并返回其值。
+它将示范 Proto 语法的两个关键概念 -- 多选与递归 -- 是如何与变换相结合的。该
语法表示如下。
// A grammar that matches any expression, and a function object
// that returns the value of the leftmost terminal.
+ // 一个匹配任意表达式的语法，以及一个返回最左侧终结符的值的函数对象。
struct LeftmostLeaf
: proto::or_<
// If the expression is a terminal, return its value
+ // 如果该表达式是一个终结符，则返回它的值
proto::when<
proto::terminal< _ >
, proto::_value
>
// Otherwise, it is a non-terminal. Return the result
// of invoking LeftmostLeaf on the 0th (leftmost) child.
+ // 否则，它不是一个终结符。返回对第0个(最左边的)子节点调用
LeftmostLeaf的结果。
, proto::when<
_
, LeftmostLeaf( proto::_child0 )
@@ -660,62 +786,87 @@
>
{};
- // A Proto terminal wrapping std::cout
+ // A Proto terminal wrapping std::cout 包装了std::cout的Proto终结符
proto::terminal< std::ostream & >::type cout_ = { std::cout };
// Create an expression and use LeftmostLeaf to extract the
// value of the leftmost terminal, which will be std::cout.
+ // 创建一个表达式并用LeftmostLeaf来取出最左侧终结符的值，即std::cout。
std::ostream & sout = LeftmostLeaf()( cout_ << "the answer: " << 42
<< '\n' );
-We've seen `proto::or_<>` before. Here it is serving two roles. First, it
is a grammar that matches any of its alternate sub-grammars; in this case,
either a terminal or a non-terminal. Second, it is also a function object
that accepts an expression, finds the alternate sub-grammar that matches
the expression, and applies its transform. And since `LeftmostLeaf`
inherits from `proto::or_<>`, `LeftmostLeaf` is also both a grammar and a
function object.
+We've seen `proto::or_<>` before. Here it is serving two roles. First, it
is a grammar that matches any of its alternate sub-grammars; in this case,
either a terminal or a non-terminal. Second, it is also a function object
that accepts an expression, finds the alternate sub-grammar that matches
the expression, and applies its transform. And since `LeftmostLeaf`
inherits from `proto::or_<>`, `LeftmostLeaf` is also both a grammar and a
function object.\n
+前面我们已经见过 `proto::or_<>` 了。在这里它扮演两个角色。首先，它是一个匹
配其任一子语法的语法；在这个例子中，
+即为终结符或非终结符。其次，它也是一个函数对象，接受一个表达式，找出与该表
达式相匹配的子语法，并对它应用变换。
+由于 `LeftmostLeaf` 继承自 `proto::or_<>`，所以 `LeftmostLeaf` 既是一个语
法，也是一个函数对象。
[def _some_transform_ [~some-transform]]
-[note The second alternate uses `proto::_` as its grammar. Recall that
`proto::_` is the wildcard grammar that matches any expression. Since
alternates in `proto::or_<>` are tried in order, and since the first
alternate handles all terminals, the second alternate handles all (and
only) non-terminals. Often enough, `proto::when< _, _some_transform_ >` is
the last alternate in a grammar, so for improved readability, you could use
the equivalent `proto::otherwise< _some_transform_ >`.]
-
-The next section describes this grammar further.
+[note The second alternate uses `proto::_` as its grammar. Recall that
`proto::_` is the wildcard grammar that matches any expression. Since
alternates in `proto::or_<>` are tried in order, and since the first
alternate handles all terminals, the second alternate handles all (and
only) non-terminals. Often enough, `proto::when< _, _some_transform_ >` is
the last alternate in a grammar, so for improved readability, you could use
the equivalent `proto::otherwise< _some_transform_ >`.\n
+第二个选择以 `proto::_` 作为其语法。回想一下，`proto::_` 是匹配任意表达式的
通配语法。由于在 `proto::or_<>` 中的候选项是按顺序尝试的，
+而且第一个候选项对应所有终结符，所以第二个候选项代表所有(也仅仅是)非终结
符。通常来说，`proto::when< _, _some_transform_ >`
+作为语法中的最后一个候选项就足够了，如果要提高可读性，你可以用等价的
`proto::otherwise< _some_transform_ >`. ]
+
+The next section describes this grammar further.\n
+下一节将进一步讨论这个语法。
[endsect]
[/==========================]
-[section Callable Transforms]
+[section Callable Transforms 可调用变换]
[/==========================]
[def __bold_transform__ [*LeftmostLeaf( proto::_child0 )]]
-In the grammar defined in the preceding section, the transform associated
with non-terminals is a little strange-looking:
+In the grammar defined in the preceding section, the transform associated
with non-terminals is a little strange-looking:\n
+在前一节中定义的语法中，与非终结符相关联的变换看起来有些奇怪：
proto::when<
_
- , __bold_transform__ // <-- a "callable" transform
+ , __bold_transform__ // <-- a "callable" transform 一个"可调用"变换
>
-It has the effect of accepting non-terminal expressions, taking the 0th
(leftmost) child and recursively invoking the `LeftmostLeaf` function on
it. But `LeftmostLeaf( proto::_child0 )` is actually a /function type/.
Literally, it is the type of a function that accepts an object of type
`proto::_child0` and returns an object of type `LeftmostLeaf`. So how do we
make sense of this transform? Clearly, there is no function that actually
has this signature, nor would such a function be useful. The key is in
understanding how `proto::when<>` /interprets/ its second template
parameter.
-
-When the second template parameter to _when_ is a function type, _when_
interprets the function type as a transform. In this case, `LeftmostLeaf`
is treated as the type of a function object to invoke, and `proto::_child0`
is treated as a transform. First, `proto::_child0` is applied to the
current expression (the non-terminal that matched this alternate
sub-grammar), and the result (the 0th child) is passed as an argument to
`LeftmostLeaf`.
-
-[note *Transforms are a Domain-Specific Language*
-
-`LeftmostLeaf( proto::_child0 )` /looks/ like an invocation of the
`LeftmostLeaf` function object, but it's not, but then it actually is! Why
this confusing subterfuge? Function types give us a natural and concise
syntax for composing more complicated transforms from simpler ones. The
fact that the syntax is suggestive of a function invocation is on purpose.
It is a domain-specific embedded language for defining expression
transformations. If the subterfuge worked, it may have fooled you into
thinking the transform is doing exactly what it actually does! And that's
the point.]
-
-The type `LeftmostLeaf( proto::_child0 )` is an example of a /callable
transform/. It is a function type that represents a function object to call
and its arguments. The types `proto::_child0` and `proto::_value` are
/primitive transforms/. They are plain structs, not unlike function
objects, from which callable transforms can be composed. There is one other
type of transform, /object transforms/, that we'll encounter next.
+It has the effect of accepting non-terminal expressions, taking the 0th
(leftmost) child and recursively invoking the `LeftmostLeaf` function on
it. But `LeftmostLeaf( proto::_child0 )` is actually a /function type/.
Literally, it is the type of a function that accepts an object of type
`proto::_child0` and returns an object of type `LeftmostLeaf`. So how do we
make sense of this transform? Clearly, there is no function that actually
has this signature, nor would such a function be useful. The key is in
understanding how `proto::when<>` /interprets/ its second template
parameter.\n
+其中含有对于非终结符表达式的动作，取出第0个(最左边)子节点并对其递归调用
`LeftmostLeaf` 函数。但是 `LeftmostLeaf( proto::_child0 )`
+是一个实实在在的/函数类型/啊。从字面上看，它是一个函数的类型，该函数接受一
个类型为 `proto::_child0` 的对象并返回一个类型为
+`LeftmostLeaf` 的对象。那么我们要如何弄清楚这个变换的意思呢？无疑，并没有一
个函数真的具有这个签名，这样的函数也没有用。
+关键在于要弄明白 `proto::when<>` 如何解释它的第二个模板参数。
+
+When the second template parameter to _when_ is a function type, _when_
interprets the function type as a transform. In this case, `LeftmostLeaf`
is treated as the type of a function object to invoke, and `proto::_child0`
is treated as a transform. First, `proto::_child0` is applied to the
current expression (the non-terminal that matched this alternate
sub-grammar), and the result (the 0th child) is passed as an argument to
`LeftmostLeaf`.\n
+如果传递给 _when_ 的第二个模板参数是一个函数类型，则 _when_ 将该函数类型解
释为一个变换。在这个例子中，
+`LeftmostLeaf` 被视为要调用的函数对象的类型，而 `proto::_child0` 则被视为一
个变换。首先，将 `proto::_child0` 应用至当前表达式
+(匹配该被选子语法的非终结符)，然后将结果(第0个子节点)作为参数传递给
`LeftmostLeaf`。
+
+[note *Transforms are a Domain-Specific Language 变换是一种领域专用语言*
+
+`LeftmostLeaf( proto::_child0 )` /looks/ like an invocation of the
`LeftmostLeaf` function object, but it's not, but then it actually is! Why
this confusing subterfuge? Function types give us a natural and concise
syntax for composing more complicated transforms from simpler ones. The
fact that the syntax is suggestive of a function invocation is on purpose.
It is a domain-specific embedded language for defining expression
transformations. If the subterfuge worked, it may have fooled you into
thinking the transform is doing exactly what it actually does! And that's
the point.\n
+`LeftmostLeaf( proto::_child0 )` /看起来/就象对 `LeftmostLeaf` 函数对象的一
次调用，但它不是，然后实际上它就是！为什么说的如此混乱？
+函数类型给了我们一个自然且简洁的语法来从简单的变换组合出复杂的变换。事实
上，这个语法只是某个函数的提示，调用才是目的。
+它是一种用于定义表达式变换的领域专用语言。如果这种托词可以成功，它可能会蒙
蔽你，使你以为变换在做的其实就是它实际上要做的！这就是重点。]
+
+The type `LeftmostLeaf( proto::_child0 )` is an example of a /callable
transform/. It is a function type that represents a function object to call
and its arguments. The types `proto::_child0` and `proto::_value` are
/primitive transforms/. They are plain structs, not unlike function
objects, from which callable transforms can be composed. There is one other
type of transform, /object transforms/, that we'll encounter next.\n
+类型 `LeftmostLeaf( proto::_child0 )` 是 /可调用变换/ 的一个例子。它是一个
函数类型，表示一个要调用的函数对象及其参数。
+类型 `proto::_child0` 和 `proto::_value` 则是 /基本变换/。它们是普通的结
构，不象函数对象，可以由它们组合出可调用变换。
+另外还有一种变换类型，/对象变换/，后面我们将要提到。
[endsect]
[/========================]
-[section Object Transforms]
+[section Object Transforms 对象变换]
[/========================]
-The very first transform we looked at simply extracted the value of
terminals. Let's do the same thing, but this time we'll promote all ints to
longs first. (Please forgive the contrived-ness of the examples so far;
they get more interesting later.) Here's the grammar:
+The very first transform we looked at simply extracted the value of
terminals. Let's do the same thing, but this time we'll promote all ints to
longs first. (Please forgive the contrived-ness of the examples so far;
they get more interesting later.) Here's the grammar:\n
+我们最早见到的一个变换只是取出终结符的值。下面我们再来做同样的事情，不过这
次我们先要将所有 int 提升为 long。
+(请忘记到目前为止的这些例子的做作性；稍后它们会更有趣些)。以下是相应语法：
// A simple Proto grammar that matches all terminals,
// and a function object that extracts the value from
// the terminal, promoting ints to longs:
+ // 一个简单的Proto语法，匹配所有终结符，以及一个从终结符取出值的函数对
象，将int提升为long:
struct ValueWithPomote
: proto::or_<
proto::when<
proto::terminal< int >
- , long(proto::_value) // <-- an "object" transform
+ , long(proto::_value) // <-- an "object" transform 一
个"对象"变换
>
, proto::when<
proto::terminal< _ >
@@ -724,28 +875,40 @@
>
{};
-You can read the above grammar as follows: when you match an int terminal,
extract the value from the terminal and use it to initialize a long;
otherwise, when you match another kind of terminal, just extract the value.
The type `long(proto::_value)` is a so-called /object/ transform. It looks
like the creation of a temporary long, but it's really a function type.
Just as a callable transform is a function type that represents a function
to call and its arguments, an object transforms is a function type that
represents an object to construct and the arguments to its constructor.
+You can read the above grammar as follows: when you match an int terminal,
extract the value from the terminal and use it to initialize a long;
otherwise, when you match another kind of terminal, just extract the value.
The type `long(proto::_value)` is a so-called /object/ transform. It looks
like the creation of a temporary long, but it's really a function type.
Just as a callable transform is a function type that represents a function
to call and its arguments, an object transforms is a function type that
represents an object to construct and the arguments to its constructor.\n
+你可这样来读以上语法：如果你匹配到一个int终结符，就从终结符中取出它的值，并
用它来初始化一个long；否则，如果你匹配到其它类型的终结符，
+则只是取出它的值。类型 `long(proto::_value)` 是一个所谓的 /对象/变换。它看
起来象是创建一个临时的long，其实它是一个函数类型。
+和可调用变换是一个表示了要调用的函数及其参数的函数类型一样，对象变换是一个
表示了要构造的对象及其构造函数的参数的函数类型。
[/================================================]
-[note *Object Transforms vs. Callable Transforms*
-
-When using function types as Proto transforms, they can either represent
an object to construct or a function to call. It is similar to "normal" C++
where the syntax `foo("arg")` can either be interpreted as an object to
construct or a function to call, depending on whether `foo` is a type or a
function. But consider two of the transforms we've seen so far:
+[note *Object Transforms vs. Callable Transforms 对象变换 vs. 可调用变换*
+
+When using function types as Proto transforms, they can either represent
an object to construct or a function to call. It is similar to "normal" C++
where the syntax `foo("arg")` can either be interpreted as an object to
construct or a function to call, depending on whether `foo` is a type or a
function. But consider two of the transforms we've seen so far:\n
+把函数类型用作 Proto 变换时，它们可以表示一个要构造的对象，或者表示一个要调
用的函数。这类似于"普通"的C++，
+语法 `foo("arg")` 可以解释为一个要构造的对象，或者是一个要调用的函数，这取
决于 `foo` 是一个类型还是一个函数。
+不过，考虑一下我们已见到的两个变换：
``
- LeftmostLeaf(proto::_child0) // <-- a callable transform
- long(proto::_value) // <-- an object transform
+ LeftmostLeaf(proto::_child0) // <-- a callable transform 一个可调用变
换
+ long(proto::_value) // <-- an object transform 一个对象变换
``
-Proto can't know in general which is which, so it uses a trait,
`proto::is_callable<>`, to differentiate. `is_callable< long >::value` is
false so `long(proto::_value)` is an object to construct, but `is_callable<
LeftmostLeaf >::value` is true so `LeftmostLeaf(proto::_child0)` is a
function to call. Later on, we'll see how Proto recognizes a type
as "callable".]
+Proto can't know in general which is which, so it uses a trait,
`proto::is_callable<>`, to differentiate. `is_callable< long >::value` is
false so `long(proto::_value)` is an object to construct, but `is_callable<
LeftmostLeaf >::value` is true so `LeftmostLeaf(proto::_child0)` is a
function to call. Later on, we'll see how Proto recognizes a type
as "callable".\n
+Proto 通常并不知道哪个是哪个，所以它使用了
trait，`proto::is_callable<>`，来区分。`is_callable< long >::value` 为
false，
+所以 `long(proto::_value)` 是一个要构造的对象，而 `is_callable<
LeftmostLeaf >::value` 为true，所以 `LeftmostLeaf(proto::_child0)`
+是一个要调用的函数。接着，我们将会看到 Proto 是如何把一个类型识别为"可调
用"的。]
[/================================================]
[endsect]
[/================================]
-[section Example: Calculator Arity]
+[section Example: Calculator Arity 示例：计算器Arity]
[/================================]
-Now that we have the basics of Proto transforms down, let's consider a
slightly more realistic example. We can use transforms to improve the
type-safety of the [link
boost_proto.users_guide.getting_started.hello_calculator calculator DSEL].
If you recall, it lets you write infix arithmetic expressions involving
argument placeholders like `_1` and `_2` and pass them to STL algorithms as
function objects, as follows:
+Now that we have the basics of Proto transforms down, let's consider a
slightly more realistic example. We can use transforms to improve the
type-safety of the [link
boost_proto.users_guide.getting_started.hello_calculator calculator DSEL].
If you recall, it lets you write infix arithmetic expressions involving
argument placeholders like `_1` and `_2` and pass them to STL algorithms as
function objects, as follows:\n
+现在我们已经有了 Proto 变换的基础，让我们来考虑一下更现实一些例子。我们可以
用变换来改进
+[link boost_proto.users_guide.getting_started.hello_calculator calculator
计算器 DSEL] 的类型安全性。
+如果你还记得，它可以让你编写含有参数占位符，如 `_1` 和 `_2`，的中缀算术表达
式，并将表达式作为函数对象传递给STL算法，如下：
double a1[4] = { 56, 84, 37, 69 };
double a2[4] = { 65, 120, 60, 70 };
@@ -753,12 +916,16 @@
// Use std::transform() and a calculator expression
// to calculate percentages given two input sequences:
+ // 用std::transform()和一个计算器表达式对给定的两个输入序列计算百分比：
std::transform(a1, a1+4, a2, a3, (_2 - _1) / _2 * 100);
-This works because we gave calculator expressions an `operator()` that
evaluates the expression, replacing the placeholders with the arguments to
`operator()`. The overloaded `calculator<>::operator()` looked like this:
+This works because we gave calculator expressions an `operator()` that
evaluates the expression, replacing the placeholders with the arguments to
`operator()`. The overloaded `calculator<>::operator()` looked like this:\n
+这可以是因为我们给了计算器表达式一个 `operator()` 来对表达式进行求值并以传
给 `operator()` 的参数替换相应的占位符。
+重载的 `calculator<>::operator()` 看起来如下：
// Overload operator() to invoke proto::eval() with
// our calculator_context.
+ // 重载operator()，以我们的calculator_context调用proto::eval()。
template<typename Expr>
double
calculator<Expr>::operator()(double a1 = 0, double a2 = 0) const
@@ -770,47 +937,72 @@
return proto::eval(*this, ctx);
}
-Although this works, it's not ideal because it doesn't warn users if they
supply too many or too few arguments to a calculator expression. Consider
the following mistakes:
-
- (_1 * _1)(4, 2); // Oops, too many arguments!
- (_2 * _2)(42); // Oops, too few arguments!
-
-The expression `_1 * _1` defines a unary calculator expression; it takes
one argument and squares it. If we pass more than one argument, the extra
arguments will be silently ignored, which might be surprising to users. The
next expression, `_2 * _2` defines a binary calculator expression; it takes
two arguments, ignores the first and squares the second. If we only pass
one argument, the code silently fills in `0.0` for the second argument,
which is also probably not what users expect. What can be done?
-
-We can say that the /arity/ of a calculator expression is the number of
arguments it expects, and it is equal to the largest placeholder in the
expression. So, the arity of `_1 * _1` is one, and the arity of `_2 * _2`
is two. We can increase the type-safety of our calculator DSEL by making
sure the arity of an expression equals the actual number of arguments
supplied. Computing the arity of an expression is simple with the help of
Proto transforms.
+Although this works, it's not ideal because it doesn't warn users if they
supply too many or too few arguments to a calculator expression. Consider
the following mistakes:\n
+虽然这样做可以，但是它还不是完美的，因为如果向计算器表达式提供了过多或过少
的参数，它不会给出警告。考虑以下错误：
+
+ (_1 * _1)(4, 2); // Oops, too many arguments! 喔，太多参数了！
+ (_2 * _2)(42); // Oops, too few arguments! 喔，太少参数了！
+
+The expression `_1 * _1` defines a unary calculator expression; it takes
one argument and squares it. If we pass more than one argument, the extra
arguments will be silently ignored, which might be surprising to users. The
next expression, `_2 * _2` defines a binary calculator expression; it takes
two arguments, ignores the first and squares the second. If we only pass
one argument, the code silently fills in `0.0` for the second argument,
which is also probably not what users expect. What can be done?\n
+表达式 `_1 * _1` 定义了一个单参数的计算器表达式；它接受一个参数并对它求平
方。如果我们传入一个以上的参数，则额外的参数会被悄悄地忽略掉，
+这可能会令用户惊讶。第二个表达式，`_2 * _2` 定义了一个二元计算器表达式；它
接受两个参数，忽略其中第一个而对第二个求平方。
+如果我们只传入一个参数，代码会悄悄地将 `0.0` 填入第二个参数，这同样可能不是
用户想要的。那么可以怎么做呢？
+
+We can say that the /arity/ of a calculator expression is the number of
arguments it expects, and it is equal to the largest placeholder in the
expression. So, the arity of `_1 * _1` is one, and the arity of `_2 * _2`
is two. We can increase the type-safety of our calculator DSEL by making
sure the arity of an expression equals the actual number of arguments
supplied. Computing the arity of an expression is simple with the help of
Proto transforms.\n
+我们可以说，一个计算器表达式的 /arity/ 是它所期望的参数数量，它等于表达式中
最大的占位符。因此，`_1 * _1` 的arity为1，
+而 `_2 * _2` 的arity为2。我们可以通过确认一个表达式的arity是否等于实际提供
的参数数量来提高我们的计算器DSEL的类型安全性。
+有了 Proto 变换的帮助，计算一个表达式的arity很简单。
It's straightforward to describe in words how the arity of an expression
should
-be calculated. Consider that calculator expressions can be made of `_1`,
`_2`, literals, unary expressions and binary expressions. The following
table shows the arities for each of these 5 constituents.
-
-[table Calculator Sub-Expression Arities
- [[Sub-Expression] [Arity]]
- [[Placeholder 1] [`1`]]
- [[Placeholder 2] [`2`]]
- [[Literal] [`0`]]
- [[Unary Expression] [ /arity of the operand/ ]]
- [[Binary Expression] [ /max arity of the two operands/ ]]
+be calculated. Consider that calculator expressions can be made of `_1`,
`_2`, literals, unary expressions and binary expressions. The following
table shows the arities for each of these 5 constituents.\n
+用语言来表达如何计算一个表达式的arity非常简单。考虑到计算器表达式可以由
`_1`, `_2`, 字面值，单参数表达式和二元表达式组成。
+下表展示了这5种情况的arity。
+
+[table Calculator Sub-Expression Arities 计算器子表达式的arity
+ [[Sub-Expression 子表达式] [Arity]]
+ [[Placeholder 1 占位符1] [`1`]]
+ [[Placeholder 2 占位符2] [`2`]]
+ [[Literal 字面值] [`0`]]
+ [[Unary Expression 单参数表达式] [ /arity of the operand 操作数的
arity/ ]]
+ [[Binary Expression 二元表达式] [ /max arity of the two operands 两
个操作数的arity的最大值/ ]]
]
-Using this information, we can write the grammar for calculator
expressions and attach transforms for computing the arity of each
constituent. The code below computes the expression arity as a compile-time
integer, using integral wrappers and metafunctions from the Boost MPL
Library. The grammar is described below.
+Using this information, we can write the grammar for calculator
expressions and attach transforms for computing the arity of each
constituent. The code below computes the expression arity as a compile-time
integer, using integral wrappers and metafunctions from the Boost MPL
Library. The grammar is described below.\n
+使用这些信息，我们可以写出计算器表达式的语法并附上计算每种情形的arity的变
换。以下代码将表达式的arity计算为一个编译期整数，
+使用来自Boost MPL库的整数包装器和元函数。语法描述如下。
[CalcArity]
-When we find a placeholder terminal or a literal, we use an /object
transform/ such as `mpl::int_<1>()` to create a (default-constructed)
compile-time integer representing the arity of that terminal.
-
-For unary expressions, we use `CalcArity(proto::_child)` which is a
/callable transform/ that computes the arity of the expression's child.
-
-The transform for binary expressions has a few new tricks. Let's look more
closely:
+When we find a placeholder terminal or a literal, we use an /object
transform/ such as `mpl::int_<1>()` to create a (default-constructed)
compile-time integer representing the arity of that terminal.\n
+当我们找到一个占位符终结符或一个字面值时，我们使用一个形如
`mpl::int_<1>()` 的/对象变换/ 来创建一个(缺省构造的)编译期整数，
+表示这个终结符的arity。
+
+For unary expressions, we use `CalcArity(proto::_child)` which is a
/callable transform/ that computes the arity of the expression's child.\n
+对于单参数表达式，我们使用 `CalcArity(proto::_child)`，它是一个计算该表达式
的子节点的arity的/可调用变换/。
+
+The transform for binary expressions has a few new tricks. Let's look more
closely:\n
+二元表达式的变换有点诀窍。我们靠近一点来看：
// Compute the left and right arities and
// take the larger of the two.
+ // 计算左、右节点的arity，并取出两者中的较大值。
mpl::max<CalcArity(proto::_left),
CalcArity(proto::_right)>()
-This is an object transform; it default-constructs ... what exactly? The
`mpl::max<>` template is an MPL metafunction that accepts two compile-time
integers. It has a nested `::type` typedef (not shown) that is the maximum
of the two. But here, we appear to be passing it two things that are /not/
compile-time integers; they're Proto callable transforms. Proto is smart
enough to recognize that fact. It first evaluates the two nested callable
transforms, computing the arities of the left and right child expressions.
Then it puts the resulting integers into `mpl::max<>` and evaluates the
metafunction by asking for the nested `::type`. That is the type of the
object that gets default-constructed and returned.
-
-More generally, when evaluating object transforms, Proto looks at the
object type and checks whether it is a template specialization, like
`mpl::max<>`. If it is, Proto looks for nested transforms that it can
evaluate. After any nested transforms have been evaluated and substituted
back into the template, the new template specialization is the result type,
unless that type has a nested `::type`, in which case that becomes the
result.
-
-Now that we can calculate the arity of a calculator expression, let's
redefine the `calculator<>` expression wrapper we wrote in the Getting
Started guide to use the `CalcArity` grammar and some macros from Boost.MPL
to issue compile-time errors when users specify too many or too few
arguments.
+This is an object transform; it default-constructs ... what exactly? The
`mpl::max<>` template is an MPL metafunction that accepts two compile-time
integers. It has a nested `::type` typedef (not shown) that is the maximum
of the two. But here, we appear to be passing it two things that are /not/
compile-time integers; they're Proto callable transforms. Proto is smart
enough to recognize that fact. It first evaluates the two nested callable
transforms, computing the arities of the left and right child expressions.
Then it puts the resulting integers into `mpl::max<>` and evaluates the
metafunction by asking for the nested `::type`. That is the type of the
object that gets default-constructed and returned.\n
+这是一个对象变换；它缺省构造了 ... 什么呢？模板 `mpl::max<>` 是一个MPL元函
数，它接受两个编译期整数。
+它有一个嵌套的 `::type` typedef (未示出)表示这两个整数中的最大者。不过在这
里，我们看到的是，传给它的是两个/不是/编译期整数的东西；
+传入的是 Proto 可调用变换。Proto 是很聪明的，它可以识别出这个事实。它首先对
两个嵌套的可调用变换进行求值，分别计算左、右节点的arity。
+然后将结果整数放入 `mpl::max<>` 并通过询问嵌套的 `::type` 来对元函数求值。
结果就是获得缺省构造并返回的对象类型。
+
+More generally, when evaluating object transforms, Proto looks at the
object type and checks whether it is a template specialization, like
`mpl::max<>`. If it is, Proto looks for nested transforms that it can
evaluate. After any nested transforms have been evaluated and substituted
back into the template, the new template specialization is the result type,
unless that type has a nested `::type`, in which case that becomes the
result.\n
***The diff for this file has been truncated for email.***
=======================================
--- /trunk/libs/proto/doc/calculator.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/calculator.qbk Sun Jan 17 23:11:16 2010
@@ -16,21 +16,26 @@
expressions can do useful work. When we're done, we'll have a
mini-language that
will allow us to declare a lazily-evaluated arithmetic expression, such as
`(_2 - _1) / _2 * 100`, where `_1` and `_2` are placeholders for values to
be
-passed in when the expression is evaluated.
+passed in when the expression is evaluated.\n
+"Hello, world" 的例子不错，不过它没有把你带得很远。下面我们用 Proto 来为惰
性求值计算器构建一个 DSEL (领域专用嵌入式语言)。
+我们将看到如何定义你的小型语言中的终结符，如何用它们来组成更大的表达式，以
及如何定义一个求值上下文使得你的表达式可以做一些有用的事。
+在我们完成了以上工作后，我们就有了一个小型语言，可以让我们声明一个惰性求值
的算术计算器，如 `(_2 - _1) / _2 * 100`，
+其中 `_1` 和 `_2` 为数值占位符，在对该表达式进行求值将传入这些数值。
[/=========================]
-[heading Defining Terminals]
+[heading Defining Terminals 定义终结符]
[/=========================]
The first order of business is to define the placeholders `_1` and `_2`.
For that,
-we'll use the _terminal_ metafunction.
-
- // Define a placeholder type
+we'll use the _terminal_ metafunction.\n
+要做的第一件事是定义占位符 `_1` 和 `_2`。为此，我们要使用 _terminal_ 元函
数。
+
+ // Define a placeholder type 定义一个占位符类型
template<int I>
struct placeholder
{};
- // Define the Protofied placeholder terminals
+ // Define the Protofied placeholder terminals 定义Proto化的占位符终结符
proto::terminal<placeholder<0> >::type const _1 = {{}};
proto::terminal<placeholder<1> >::type const _2 = {{}};
@@ -40,46 +45,59 @@
are essentially initialized at compile time. See the
[link boost_proto.appendices.rationale.static_initialization Static
Initialization] section in the [link boost_proto.appendices.rationale
Rationale]
-appendix for more information.
+appendix for more information.\n
+乍一看，这个初始化有些奇怪，不过这样做是有很好的理由的。这里的对象 `_1` 和
`_2`
+不需要运行期的构造 -- 它们是 ['静态初始化的]，即本质上它们是在编译期初始化
的。
+更多信息请见 [link boost_proto.appendices.rationale 基本原理] 附录中的
+[link boost_proto.appendices.rationale.static_initialization 静态初始化] 一
节。
[/====================================]
-[heading Constructing Expression Trees]
+[heading Constructing Expression Trees 构造表达式树]
[/====================================]
Now that we have terminals, we can use Proto's operator overloads to
combine
these terminals into larger expressions. So, for instance, we can
immediately
-say things like:
-
- // This builds an expression template
+say things like:\n
+现在我们有终结符了，我们可以用 Proto 的操作符重载来把这些终结符组合成更大的
表达式。
+例如，我们可以马上写出：
+
+ // This builds an expression template 构建一个表达式模板
(_2 - _1) / _2 * 100;
This creates an expression tree with a node for each operator. The type of
the
-resulting object is large and complex, but we are not terribly interested
in it right now.
+resulting object is large and complex, but we are not terribly interested
in it right now.\n
+这将构建一个表达式树，其中每个操作符一个节点。结果对象的类型很长很复杂，不
过我们现在还不需要过于担心。
So far, the object is just a tree representing the expression. It has no
behavior. In particular, it is not yet a calculator. Below we'll see how
-to make it a calculator by defining an evaluation context.
+to make it a calculator by defining an evaluation context.\n
+到目前为止，这个对象只是代表这个表达式的一棵树。它没有行为。具体地说，它还
不是一个计算器。
+下面我们将看到如何通过定义一个求值上下文使它变为一个计算器。
[/==================================]
-[heading Evaluating Expression Trees]
+[heading Evaluating Expression Trees 对表达式树求值]
[/==================================]
No doubt you want your expression templates to actually /do/ something. One
approach is to define an ['evaluation context]. The context is like a
function
object that associates behaviors with the node types in your expression
tree.
-The following example should make it clear. It is explained below.
+The following example should make it clear. It is explained below.\n
+毫无疑问，你希望你的表达式模板可以真真正正地/做些/什么。一个方法是定义一个
['求值上下文]。
+这个上下文类似于一个函数对象，把行为关联到你的表达式树中的节点类型上。以下
例子可以清楚地说明这一点。
+我们在后面再作解释。
struct calculator_context
: proto::callable_context< calculator_context const >
{
- // Values to replace the placeholders
+ // Values to replace the placeholders 用于替换占位符的值
std::vector<double> args;
// Define the result type of the calculator.
// (This makes the calculator_context "callable".)
+ // 定义计算器的结果类型。使calculator_context变成"可调用"的。
typedef double result_type;
- // Handle the placeholders:
+ // Handle the placeholders: 对占位符进行处理：
template<int I>
double operator()(proto::tag::terminal, placeholder<I>) const
{
@@ -93,27 +111,34 @@
non-placeholder terminals), Proto will evaluate the expression in
the "default"
way. For example, a binary plus node is evaluated by first evaluating the
left
and right operands and adding the results. Proto's default evaluator uses
the
-_typeof_ library to compute return types.
+_typeof_ library to compute return types.\n
+在 `calculator_context` 中，我们通过定义合适的函数调用操作符重载，指定
Proto 应如何对占位符终结符进行求值。
+对于表达式树中的其它节点(如算术操作或非占位符的终结符)，Proto 将以"缺省"的
方式对表达式进行求值。
+例如，一个二元加法节点的求值方式为，首先求出左、右操作数的值，然后相加得到
结果。
+Proto 的缺省求值器使用了 Boost.Typeof 库来计算返回类型。
Now that we have an evaluation context for our calculator, we can use it to
-evaluate our arithmetic expressions, as below:
+evaluate our arithmetic expressions, as below:\n
+现在我们有一个求值上下文，可用于我们的计算器，我们可以用它来对我们的算术表
达式进行求值，如下：
calculator_context ctx;
ctx.args.push_back(45); // the value of _1 is 45
ctx.args.push_back(50); // the value of _2 is 50
// Create an arithmetic expression and immediately evaluate it
+ // 创建一个算术表达式并立即对它求值
double d = proto::eval( (_2 - _1) / _2 * 100, ctx );
- // This prints "10"
+ // This prints "10" 打印"10"
std::cout << d << std::endl;
Later, we'll see how to define more interesting evaluation contexts and
expression transforms that give you total control over how your expressions
-are evaluated.
+are evaluated.\n
+稍后，我们将看到如何定义更多有趣的求值上下文和表达式变换，让你可以完全地控
制如何对你的表达式进行求值。
[/===================================]
-[heading Customizing Expression Trees]
+[heading Customizing Expression Trees 定制表达式树]
[/===================================]
Our calculator DSEL is already pretty useful, and for many DSEL scenarios,
no more
@@ -121,15 +146,21 @@
calculator expressions overloaded `operator()` so that they could be used
as
function objects. We can do that by creating a calculator /domain/ and
telling
Proto that all expressions in the calculator domain have extra members.
Here is how
-to define a calculator domain:
-
- // Forward-declare an expression wrapper
+to define a calculator domain:\n
+我们的计算器DSEL已经相当有用，对于多数的DSEL情形，没有更多要做的事情。不过
让我们继续前进。
+想象一下，如果所有计算器表达式都重载了 `operator()` 以便可以它们可以象函数
对象那样来使用，
+这该多好。我们可以做到这一点，方法是创建一个计算器/域/并告诉 Proto 计算器域
中的所有表达式都有额外的成员。
+以下是如何定义一个计算器域的方法：
+
+ // Forward-declare an expression wrapper 前向声明一个表达式包装器
template<typename Expr>
struct calculator;
// Define a calculator domain. Expression within
// the calculator domain will be wrapped in the
// calculator<> expression wrapper.
+ // 定义一个计算器域。在此计算器域中的表达式都将被包装在
+ // calculator<> 表达式包装器中。
struct calculator_domain
: proto::domain< proto::generator<calculator> >
{};
@@ -137,11 +168,15 @@
The `calculator<>` type will be an expression wrapper. It will behave just
like the
expression that it wraps, but it will have extra member functions that we
will
define. The `calculator_domain` is what informs Proto about our wrapper.
It is used
-below in the definition of `calculator<>`. Read on for a description.
+below in the definition of `calculator<>`. Read on for a description.\n
+类型 `calculator<>` 是一个表达式包装器。其行为与所包裹的表达式一样，不过它
多了一个我们将要定义的成员函数。
+`calculator_domain` 则用于将我们的包装器告知 Proto。它将在下面的
`calculator<>` 定义中使用。继续看下去。
// Define a calculator expression wrapper. It behaves just like
// the expression it wraps, but with an extra operator() member
// function that evaluates the expression.
+ // 定义一个计算器表达式的包装器。其行为与所包裹的表达式一样，不过它多了
一个
+ // 对表达式进行求值的 operator() 成员函数
template<typename Expr>
struct calculator
: proto::extends<Expr, calculator<Expr>, calculator_domain>
@@ -158,6 +193,7 @@
// Overload operator() to invoke proto::eval() with
// our calculator_context.
+ // 重载 operator()，以我们的 calculator_context 调用 proto::eval()
double operator()(double a1 = 0, double a2 = 0) const
{
calculator_context ctx;
@@ -168,21 +204,29 @@
}
};
-The `calculator<>` struct is an expression /extension/. It uses
`proto::extends<>` to effectively add additional members to an expression
type. When composing larger expressions from smaller ones, Proto notes what
domain the smaller expressions are in. The larger expression is in the same
domain and is automatically wrapped in the domain's extension wrapper.
-
-All that remains to be done is to put our placeholders in the calculator
domain. We do that by wrapping them in our `calculator<>` wrapper, as below:
+The `calculator<>` struct is an expression /extension/. It uses
`proto::extends<>` to effectively add additional members to an expression
type. When composing larger expressions from smaller ones, Proto notes what
domain the smaller expressions are in. The larger expression is in the same
domain and is automatically wrapped in the domain's extension wrapper.\n
+结构 `calculator<>` 是一个表达式 扩展。它用 `proto::extends<>` 来高效地将额
外成员添加到一个表达式类型中。
+当从较小的表达式组成较大的表达式时，Proto 会留意到小表达式是属于哪个域的。
+这样，大表达式将被置于同一个域并自动被包装到该域的扩展包装器中。
+
+All that remains to be done is to put our placeholders in the calculator
domain. We do that by wrapping them in our `calculator<>` wrapper, as
below:\n
+剩下要做的就是将我们的占位符也放入这个计算器域中。我们通过将它们包进我们的
`calculator<>` 包装器中来做到这一点，如下：
// Define the Protofied placeholder terminals, in the
// calculator domain.
+ // 在计算器域中定义Proto化的占位符终结符。
calculator<proto::terminal<placeholder<0> >::type> const _1;
calculator<proto::terminal<placeholder<1> >::type> const _2;
-Any larger expression that contain these placeholders will automatically
be wrapped in the `calculator<>` wrapper and have our `operator()`
overload. That means we can use them as function objects as follows.
+Any larger expression that contain these placeholders will automatically
be wrapped in the `calculator<>` wrapper and have our `operator()`
overload. That means we can use them as function objects as follows.\n
+任何含有这些占位符的较大表达式都将自动被包进 `calculator<>` 包装器中，并且
带有我们的 `operator()` 重载。
+这意味着我们可以象下面那样把它们当作函数对象为使用。
double result = ((_2 - _1) / _2 * 100)(45.0, 50.0);
assert(result == (50.0 - 45.0) / 50.0 * 100));
-Since calculator expressions are now valid function objects, we can use
them with standard algorithms, as shown below:
+Since calculator expressions are now valid function objects, we can use
them with standard algorithms, as shown below:\n
+由于计算器表达式现在已经是有效的函数对象了，所以我们可以将它们用于标准算
法，示范如下：
double a1[4] = { 56, 84, 37, 69 };
double a2[4] = { 65, 120, 60, 70 };
@@ -190,12 +234,14 @@
// Use std::transform() and a calculator expression
// to calculate percentages given two input sequences:
+ // 使用 std::transform() 和一个计算器表达式来计算给定的两个输入序列的百
分比：
std::transform(a1, a1+4, a2, a3, (_2 - _1) / _2 * 100);
-Now, let's use the calculator example to explore some other useful
features of Proto.
+Now, let's use the calculator example to explore some other useful
features of Proto.\n
+现在，我们用这个计算器例子来展示 Proto 的其它一些有用的特性。
[/====================================]
-[heading Detecting Invalid Expressions]
+[heading Detecting Invalid Expressions 检测无效表达式]
[/====================================]
You may have noticed that you didn't have to define an overloaded
`operator-()` or
@@ -203,14 +249,19 @@
operators for you, even though they may not mean anything in your
domain-specific
language. That means it may be possible to create expressions that are
invalid in
your domain. You can detect invalid expressions with Proto by defining the
-/grammar/ of your domain-specific language.
+/grammar/ of your domain-specific language.\n
+你可能已经注意到，你并不需要定义重载的 `operator-()` 或 `operator/()` --
Proto 已经为你定义了。
+实际上，Proto 为你重载了所有的 操作符，即使是它们在你的领域专用语言中并没有
意义。
+这意味着有可能创建一些在你的问题域中是无效的表达式。你可以通过定义你的领域
专用语言的语法来让 Proto 检测无效的表达式。
For simplicity, assume that our calculator DSEL should only allow addition,
subtraction, multiplication and division. Any expression involving any
other
operator is invalid. Using Proto, we can state this requirement by
defining the
-grammar of the calculator DSEL. It looks as follows:
-
- // Define the grammar of calculator expressions
+grammar of the calculator DSEL. It looks as follows:\n
+为简单起见，假设我们的计算器DSEL只允许加、减、乘、除。任何涉及其它操作符的
表达式都是无效的。
+使用 Proto，我们可以通过定义这个计算器DSEL的语法来声明这些要求。如下：
+
+ // Define the grammar of calculator expressions 定义计算器表达式的语法
struct calculator_grammar
: proto::or_<
proto::plus< calculator_grammar, calculator_grammar >
@@ -221,11 +272,18 @@
>
{};
-You can read the above grammar as follows: an expression tree conforms to
the calculator grammar if it is a binary plus, minus, multiplies or divides
node, where both child nodes also conform to the calculator grammar; or if
it is a terminal. In a Proto grammar, _wild_ is a wildcard that matches any
type, so `proto::terminal< proto::_ >` matches any terminal, whether it is
a placeholder or a literal.
-
-[note This grammar is actually a little looser than we would like. Only
placeholders and literals that are convertible to doubles are valid
terminals. Later on we'll see how to express things like that in Proto
grammars.]
-
-Once you have defined the grammar of your DSEL, you can use the _matches_
metafunction to check whether a given expression type conforms to the
grammar. For instance, we might add the following to our
`calculator::operator()` overload:
+You can read the above grammar as follows: an expression tree conforms to
the calculator grammar if it is a binary plus, minus, multiplies or divides
node, where both child nodes also conform to the calculator grammar; or if
it is a terminal. In a Proto grammar, _wild_ is a wildcard that matches any
type, so `proto::terminal< proto::_ >` matches any terminal, whether it is
a placeholder or a literal.\n
+你可以这样来读以上语法：一个表达式树符合这个计算器语法，如果它是一个二元加
法、减法、乘法或除法，且它的两个子树都符合这个计算器语法；
+或者如果它是一个终结符。在 Proto 语法中，_wild_ 是一个匹配任何类型的通配
符，所以 `proto::terminal< proto::_ >` 匹配任何终结符，
+无论它是一个占位符或字面值。
+
+[note This grammar is actually a little looser than we would like. Only
placeholders and literals that are convertible to doubles are valid
terminals. Later on we'll see how to express things like that in Proto
grammars.\n
+这个语法实际上比我们想要的稍微宽松了一些。只有可以转换为 double 的占位符和
字面值才是有效的终结符。
+稍后我们将看到如何在 Proto 语法中来表示这样的情况。]
+
+Once you have defined the grammar of your DSEL, you can use the _matches_
metafunction to check whether a given expression type conforms to the
grammar. For instance, we might add the following to our
`calculator::operator()` overload:\n
+一旦你定义了你的DSEL语法，你就可以使用 _matches_ 元函数来检测一个给定的表达
式类型是否符合该语法。例如，
+我们可以将以下代码增加到我们的 `calculator::operator()` 重载中：
template<typename Expr>
struct calculator
@@ -236,6 +294,7 @@
{
// Check here that the expression we are about to
// evaluate actually conforms to the calculator grammar.
+ // 这里检测我们要求值的表达式实际上是否符合计算器语法。
BOOST_MPL_ASSERT((proto::matches<Expr, calculator_grammar>));
/* ... */
}
@@ -245,13 +304,17 @@
evaluate expressions that conform to the calculator DSEL's grammar. With
Proto
grammars, `proto::matches<>` and `BOOST_MPL_ASSERT()` it is very easy to
give the
users of your DSEL short and readable compile-time errors when they
accidentally
-misuse your DSEL.
+misuse your DSEL.\n
+这行新增的 `BOOST_MPL_ASSERT()` 在编译期确定我们只能对符合计算器DSEL语法的
表达式进行求值。
+通过使用 Proto 语法，`proto::matches<>` 和 `BOOST_MPL_ASSERT()`，可以很容易
地在你的DSEL用户不小心误用了你的DSEL时，
+给出简短易读的编译期错误。
[note `BOOST_MPL_ASSERT()` is part of the Boost Metaprogramming Library.
To use it,
-just `#include <boost/mpl/assert.hpp>`.]
+just `#include <boost/mpl/assert.hpp>`.\n
+`BOOST_MPL_ASSERT()` 是 Boost Metaprogramming 库的一部分。要使用它，只要
`#include <boost/mpl/assert.hpp>`.]
[/=====================================]
-[heading Controlling Operator Overloads]
+[heading Controlling Operator Overloads 控制操作符的重载]
[/=====================================]
Grammars and `proto::matches<>` make it possible to detect when a user has
created
@@ -259,7 +322,11 @@
prevent users from creating invalid expressions in the first place? By
using
grammars and domains together, you can disable any of Proto's operator
overloads
that would create an invalid expression. It is as simple as specifying the
DSEL's
-grammar when you define the domain, as shown below:
+grammar when you define the domain, as shown below:\n
+语法和 `proto::matches<>` 可以在用户创建一个无效表达式时进行检查并引发编译
期错误。
+不过，如果你想在第一时间阻止用户创建无效的表达式工，又应如何呢？通过合用语
法和领域，
+你可以禁止任何可能创建无效表达式的 Proto 操作符重载。这很简单，只要在你定义
领域时指定DSEL的语法就行了，
+示范如下：
// Define a calculator domain. Expression within
// the calculator domain will be wrapped in the
@@ -267,6 +334,8 @@
// NEW: Any operator overloads that would create an
// expression that does not conform to the
// calculator grammar is automatically disabled.
+ // 定义一个计算器域。在该计算器域中的表达式将被包进 calculator<> 表达式
包装器中。
+ // 新增：任何会创建一个不符合计算器语法的操作符重载都会被自动禁止。
struct calculator_domain
: proto::domain< proto::generator<calculator>, calculator_grammar >
{};
@@ -274,16 +343,21 @@
The only thing we changed is we added `calculator_grammar` as the second
template
parameter to the `proto::domain<>` template when defining
`calculator_domain`. With
this simple addition, we disable any of Proto's operator overloads that
would
-create an invalid calculator expression.
+create an invalid calculator expression.\n
+我们唯一修改的地方是，在定义 `calculator_domain` 时增加了
`calculator_grammar` 作为 `proto::domain<>` 模板的第二个模板参数。
+通过这一个简单的添加，我们禁止了任何会创建出无效的计算器表达式的 Proto 操作
符重载。
[/========================]
-[heading ... And Much More]
+[heading ... And Much More ... 还有更多]
[/========================]
Hopefully, this gives you an idea of what sorts of things Proto can do for
you. But
this only scratches the surface. The rest of this users' guide will
describe all
-these features and others in more detail.
-
-Happy metaprogramming!
+these features and others in more detail.\n
+我们希望，以上可以使你了解 Proto 可以为你做什么样的事情。不过，这只仅仅触及
到表面。
+这个用户指南的其余部分将讲述所有这些特性以及其它更多细节。
+
+Happy metaprogramming!\n
+元编程快乐！
[endsect]
=======================================
--- /trunk/libs/proto/doc/conventions.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/conventions.qbk Sun Jan 17 23:11:16 2010
@@ -6,23 +6,27 @@
/]
[/================================]
-[section:naming Naming Conventions]
+[section:naming Naming Conventions 命名约定]
[/================================]
Proto is a large library and probably quite unlike any library you've used
before. Proto uses some consistent naming conventions to make it easier to
-navigate, and they're described below.
+navigate, and they're described below.\n
+Proto 是一个大型库，可能与你所使用过的其它库很不一样。Proto 使用了一些一致
的命名约定，
+使得它更容易操纵，以下对这些命名约定进行说明。
[/================]
-[heading Functions]
+[heading Functions 函数]
[/================]
All of Proto's functions are defined in the `boost::proto` namespace. For
example, there is a function called `value()` defined in `boost::proto`
that
-accepts a terminal expression and returns the terminal's value.
+accepts a terminal expression and returns the terminal's value.\n
+所有的 Proto 函数定义在 `boost::proto` 命名空间内。例如，有一个名为
`value()`
+的函数被定义在 `boost::proto` 中，它接受一个终结符表达式并返回该终结符的
值。
[/====================]
-[heading Metafunctions]
+[heading Metafunctions 元函数]
[/====================]
Proto defines /metafunctions/ that correspond to each of Proto's free
functions.
@@ -30,10 +34,13 @@
Proto's metafunctions live in the `boost::proto::result_of` namespace and
have the same name as the functions to which they correspond. For instance,
there is a class template `boost::proto::result_of::value<>` that you can
-use to compute the return type of the `boost::proto::value()` function.
+use to compute the return type of the `boost::proto::value()` function.\n
+Proto 为每一个 Proto 普通函数定义了一个相对应的 /元函数/。这些元函数用于计
算该函数的返回类型。
+所有的 Proto 元函数位于 `boost::proto::result_of` 名字空间内，并具有与相对
应的函数相同的名字。
+例如，有一个类模板 `boost::proto::result_of::value<>`，你可以用它来计算
`boost::proto::value()` 函数的返回类型。
[/=======================]
-[heading Function Objects]
+[heading Function Objects 函数对象]
[/=======================]
Proto defines /function object/ equivalents of all of its free functions.
(A
@@ -42,10 +49,14 @@
`boost::proto::functional` namespace and have the same name as their
corresponding free functions. For example,
`boost::proto::functional::value`
is a class that defines a function object that does the same thing as the
-`boost::proto::value()` free function.
+`boost::proto::value()` free function.\n
+Proto 为其每一个普通函数定义了等价的 /函数对象/(函数对象是一个定义了
`operator()`
+成员函数的类类型的一个实例)。所有的 Proto 函数对象类型都定义在
`boost::proto::functional`
+名字空间内，并具有与相对应的普通函数相同的名字。例
如，`boost::proto::functional::value`
+是一个类，它定义了一个函数对象，该函数对象与 `boost::proto::value()` 普通函
数完成相同的事情。
[/===========================]
-[heading Primitive Transforms]
+[heading Primitive Transforms 基本变换]
[/===========================]
Proto also defines /primitive transforms/ -- class types that can be used
@@ -53,16 +64,20 @@
Proto's free functions have corresponding primitive transforms. These live
in the `boost::proto` namespace and their names have a leading underscore.
For instance, the transform corresponding to the `value()` function is
-called `boost::proto::_value`.
-
-The following table summarizes the discussion above:
-
-[table Proto Naming Conventions
- [[Entity] [Example] ]
- [[Free Function] [`boost::proto::value()`] ]
- [[Metafunction] [`boost::proto::result_of::value<>`] ]
- [[Function Object] [`boost::proto::functional::value`] ]
- [[Transform] [`boost::proto::_value`] ]
+called `boost::proto::_value`.\n
+Proto 还定义了一些 /基本变换/ -- 可用于组成操纵表达式树所用的较大型变换的类
类型。
+多数的 Proto 普通函数都有相对应的基本变换。这些变换位于 `boost::proto` 名字
空间内，
+它们的名字以下划线打头。例如，与 `value()` 函数相对应的变换名为
`boost::proto::_value`。
+
+The following table summarizes the discussion above:\n
+下表概括了以上的说明：
+
+[table Proto Naming Conventions Proto命名约定
+ [[Entity 实体] [Example 例子] ]
+ [[Free Function 普通函数] [`boost::proto::value()`] ]
+ [[Metafunction 元函数] [`boost::proto::result_of::value<>`] ]
+ [[Function Object 函数对象] [`boost::proto::functional::value`] ]
+ [[Transform 变换] [`boost::proto::_value`] ]
]
[endsect]
=======================================
--- /trunk/libs/proto/doc/examples.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/examples.qbk Sun Jan 17 23:11:16 2010
@@ -20,139 +20,160 @@
[import ../example/mini_lambda.cpp]
[/===============]
-[section Examples]
+[section:examples Examples 示例]
[/===============]
-A code example is worth a thousand words ...
+A code example is worth a thousand words ...\n
+一个代码示例抵得上千言万语...
[/================================================================================]
[section:hello_world Hello World:
- Building an Expression Template and Evaluating It]
+ Building an Expression Template and Evaluating It 构建一个表达式模板并
对它求值]
[/================================================================================]
-A trivial example which builds and expression template and evaluates it.
+A trivial example which builds and expression template and evaluates it.\n
+一个简单的例子，构建一个表达式模板并对它进行求值。
[HelloWorld]
[endsect]
[/==================================================]
-[section:calc1 Calc1: Defining an Evaluation Context]
+[section:calc1 Calc1: Defining an Evaluation Context 定义一个求值上下文]
[/==================================================]
-A simple example that builds a miniature domain-specific embedded language
for lazy arithmetic expressions, with TR1 bind-style argument placeholders.
+A simple example that builds a miniature domain-specific embedded language
for lazy arithmetic expressions, with TR1 bind-style argument
placeholders.\n
+一个简单的例子，构建一个用于惰性算术表达式的微型领域专用嵌入式语言，使用
TR1 bind风格的参数占位符。
[Calc1]
[endsect]
[/============================================================]
-[section:calc2 Calc2: Adding Members Using [^proto::extends<>]]
+[section:calc2 Calc2: Adding Members Using [^proto::extends<>] 用
[^proto::extends<>]增加成员]
[/============================================================]
-An extension of the Calc1 example that uses _extends_ to make calculator
expressions valid function objects that can be used with STL algorithms.
+An extension of the Calc1 example that uses _extends_ to make calculator
expressions valid function objects that can be used with STL algorithms.\n
+对Calc1例子的扩展，使用 proto::extends<> 来让计算器表达式的有效函数对象可以
用于STL算法。
[Calc2]
[endsect]
[/===============================================]
-[section:calc3 Calc3: Defining a Simple Transform]
+[section:calc3 Calc3: Defining a Simple Transform 定义一个简单的变换]
[/===============================================]
-An extension of the Calc2 example that uses a Proto transform to calculate
the arity of a calculator expression and statically assert that the correct
number of arguments are passed.
+An extension of the Calc2 example that uses a Proto transform to calculate
the arity of a calculator expression and statically assert that the correct
number of arguments are passed.\n
+Calc2例子的一个扩展，使用一个Proto变换来计算一个计算器表达式的arity，并静态
地对传入的参数数量进行断言。
[Calc3]
[endsect]
[/==============================================================]
-[section:lazy_vector Lazy Vector: Controlling Operator Overloads]
+[section:lazy_vector Lazy Vector: Controlling Operator Overloads 控制操作符
重载]
[/==============================================================]
-This example constructs a mini-library for linear algebra, using
expression templates to eliminate the need for temporaries when adding
vectors of numbers.
-
-This example uses a domain with a grammar to prune the set of overloaded
operators. Only those operators that produce valid lazy vector expressions
are allowed.
+This example constructs a mini-library for linear algebra, using
expression templates to eliminate the need for temporaries when adding
vectors of numbers.\n
+这个例子构建一个线性代数的小型库，使用了表达式模板来消除数字向量相加时的临
时对象。
+
+This example uses a domain with a grammar to prune the set of overloaded
operators. Only those operators that produce valid lazy vector expressions
are allowed.\n
+这个例子使用了一个带语法的领域来减少操作符的重载。只有那些可以生成有效的惰
性向量表达式的操作符被允许。
[LazyVector]
[endsect]
[/========================================================]
-[section:rgb RGB: Type Manipulations with Proto Transforms]
+[section:rgb RGB: Type Manipulations with Proto Transforms 以Proto变换进行
类型操作]
[/========================================================]
-This is a simple example of doing arbitrary type manipulations with Proto
transforms. It takes some expression involving primary colors and combines
the colors according to arbitrary rules. It is a port of the RGB example
from _PETE_.
+This is a simple example of doing arbitrary type manipulations with Proto
transforms. It takes some expression involving primary colors and combines
the colors according to arbitrary rules. It is a port of the RGB example
from _PETE_.\n
+这是一个简单的例子，以Proto变换进行任意的类型操作。它接受带有三原色的表达
式，并根据任意规则组合成颜色。
+它是对 _PETE_ 中的RGB例子的一个移植。
[RGB]
[endsect]
[/=====================================================]
-[section:tarray TArray: A Simple Linear Algebra Library]
+[section:tarray TArray: A Simple Linear Algebra Library 一个简单的线性代数
库]
[/=====================================================]
-This example constructs a mini-library for linear algebra, using
expression templates to eliminate the need for temporaries when adding
arrays of numbers. It duplicates the TArray example from _PETE_.
+This example constructs a mini-library for linear algebra, using
expression templates to eliminate the need for temporaries when adding
arrays of numbers. It duplicates the TArray example from _PETE_.\n
+这个例子构造了一个线性代数的小型库，使用表达式模板来消除进行数值数组加法时
所需的临时对象。它复制了 _PETE_ 中的TArray例子。
[TArray]
[endsect]
[/========================================================]
-[section:vec3 Vec3: Computing With Transforms and Contexts]
+[section:vec3 Vec3: Computing With Transforms and Contexts 用变换和上下文进
行计算]
[/========================================================]
-This is a simple example using `proto::extends<>` to extend a terminal
type with additional behaviors, and using custom contexts and
`proto::eval()` for evaluating expressions. It is a port of the Vec3
example from _PETE_.
+This is a simple example using `proto::extends<>` to extend a terminal
type with additional behaviors, and using custom contexts and
`proto::eval()` for evaluating expressions. It is a port of the Vec3
example from _PETE_.\n
+这是一个简单的例子，使用 `proto::extends<>` 来扩展一个终结符类型以增加行
为，并使用定制的上下文和 `proto::eval()` 来对表达式求值。
+它是修改自 _PETE_ 中的Vec3例子。
[Vec3]
[endsect]
[/========================================================]
-[section:vector Vector: Adapting a Non-Proto Terminal Type]
+[section:vector Vector: Adapting a Non-Proto Terminal Type 适配一个非
Proto的终结符类型]
[/========================================================]
-This is an example of using `BOOST_PROTO_DEFINE_OPERATORS()` to Protofy
expressions using `std::vector<>`, a non-Proto type. It is a port of the
Vector example from _PETE_.
+This is an example of using `BOOST_PROTO_DEFINE_OPERATORS()` to Protofy
expressions using `std::vector<>`, a non-Proto type. It is a port of the
Vector example from _PETE_.\n
+这个例子使用 `BOOST_PROTO_DEFINE_OPERATORS()` 来Proto化使用了一个非Proto类
型 `std::vector<>` 的表达式。它修改自 _PETE_ 的Vector例子。
+
[Vector]
[endsect]
[/=============================================================]
-[section:mixed Mixed: Adapting Several Non-Proto Terminal Types]
+[section:mixed Mixed: Adapting Several Non-Proto Terminal Types 适配多个非
Proto的终结符类型]
[/=============================================================]
-This is an example of using `BOOST_PROTO_DEFINE_OPERATORS()` to Protofy
expressions using `std::vector<>` and `std::list<>`, non-Proto types. It is
a port of the Mixed example from _PETE_.
+This is an example of using `BOOST_PROTO_DEFINE_OPERATORS()` to Protofy
expressions using `std::vector<>` and `std::list<>`, non-Proto types. It is
a port of the Mixed example from _PETE_.\n
+这是一个使用 `BOOST_PROTO_DEFINE_OPERATORS()` 来对使用了 `std::vector<>`
和 `std::list<>` 这些非Proto类型的表达式进行Proto化的例子。
+它修改自 _PETE_ 的Mixed例子。
[Mixed]
[endsect]
[/=======================================================]
-[section:map_assign Map Assign: An Intermediate Transform]
+[section:map_assign Map Assign: An Intermediate Transform 一个中间变换]
[/=======================================================]
-A demonstration of how to implement `map_list_of()` from the Boost.Assign
library using Proto. `map_list_assign()` is used to conveniently initialize
a `std::map<>`. By using Proto, we can avoid any dynamic allocation while
building the intermediate representation.
+A demonstration of how to implement `map_list_of()` from the Boost.Assign
library using Proto. `map_list_assign()` is used to conveniently initialize
a `std::map<>`. By using Proto, we can avoid any dynamic allocation while
building the intermediate representation.\n
+以下示范如何用Proto从Boost.Assign库实现 `map_list_of()`。
`map_list_assign()` 用于便利地初始化一个 `std::map<>`。
+通过使用Proto，我们可以在构建中间表示方式时避免动态内存分配。
[MapAssign]
[endsect]
[/===========================================================]
-[section:future_group Future Group: A More Advanced Transform]
+[section:future_group Future Group: A More Advanced Transform 更高级的变换]
[/===========================================================]
-An advanced example of a Proto transform that implements Howard Hinnant's
design for /future groups/ that block for all or some asynchronous
operations to complete and returns their results in a tuple of the
appropriate type.
+An advanced example of a Proto transform that implements Howard Hinnant's
design for /future groups/ that block for all or some asynchronous
operations to complete and returns their results in a tuple of the
appropriate type.\n
+一个Proto变换的进阶例子，它实现了Howard Hinnant对于 /future groups/ 的设
计，阻塞至所有或部分异步操作完成，
+并以一个适当类型的tuple来返回操作的结果。
[FutureGroup]
[endsect]
[/========================================================]
-[section:lambda Lambda: A Simple Lambda Library with Proto]
+[section:lambda Lambda: A Simple Lambda Library with Proto 一个使用Proto的
简单Lambda库]
[/========================================================]
-This is an advanced example that shows how to implement a simple lambda
DSEL with Proto, like the Boost.Lambda_library. It uses contexts,
transforms and expression extension.
+This is an advanced example that shows how to implement a simple lambda
DSEL with Proto, like the Boost.Lambda_library. It uses contexts,
transforms and expression extension.\n
+这是一个高级例子，示范如何用Proto实现一个简单的lambda DSEL，类似于
Boost.Lambda库。它使用了上下文、变换和表达式扩展。
[Lambda]
=======================================
--- /trunk/libs/proto/doc/front_end.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/front_end.qbk Sun Jan 17 23:11:16 2010
@@ -7,61 +7,80 @@
[/================================================================================]
[section:front_end Fronts Ends:
- Defining Terminals and Non-Terminals of Your DSEL]
+ Defining Terminals and Non-Terminals of Your DSEL 前端：为你的DSEL定义
终结符和非终结符]
[/================================================================================]
-Here is the fun part: designing your own mini-programming language. In
this section we'll talk about the nuts and bolts of designing a DSEL
interface using Proto. We'll cover the definition of terminals and lazy
functions that the users of your DSEL will get to program with. We'll also
talk about Proto's expression template-building operator overloads, and
about ways to add additional members to expressions within your domain.
+Here is the fun part: designing your own mini-programming language. In
this section we'll talk about the nuts and bolts of designing a DSEL
interface using Proto. We'll cover the definition of terminals and lazy
functions that the users of your DSEL will get to program with. We'll also
talk about Proto's expression template-building operator overloads, and
about ways to add additional members to expressions within your domain.\n
+以下是比较有趣的部分：设计你自己的小型编程语言。在这一节中，我们将讨论使用
Proto 来设计一个DSEL接口的相关细节。
+我们将涵盖终结符定义和惰性函数，它们是你的DSEL用户要用来写程序的。我们也将
讨论 Proto 的表达式模板构建的操作符重载，
+以及为你的领域中的表达式增加成员的方法。
[/=======================]
-[section Making Terminals]
+[section Making Terminals 制造终结符]
[/=======================]
-As we saw with the Calculator example from the Introduction, the simplest
way to get a DSEL up and running is simply to define some terminals, as
follows.
-
- // Define a literal integer Proto expression.
+As we saw with the Calculator example from the Introduction, the simplest
way to get a DSEL up and running is simply to define some terminals, as
follows.\n
+正如我们在"简介"中看到的计算器例子，获得一个DSEL并运行它的最简单方法是定义
一些终结符，如下。
+
+ // Define a literal integer Proto expression. 定义一个字面值整数 Proto
表达式。
proto::terminal<int>::type i = {0};
- // This creates an expression template.
+ // This creates an expression template. 创建一个表达式模板。
i + 1;
-With some terminals and Proto's operator overloads, you can immediately
start creating expression templates.
-
-Defining terminals -- with aggregate initialization -- can be a little
awkward at times. Proto provides an easier-to-use wrapper for literals that
can be used to construct Protofied terminal expressions. It's called
_literal_.
-
- // Define a literal integer Proto expression.
+With some terminals and Proto's operator overloads, you can immediately
start creating expression templates. \n
+有了一些终结符和 Proto 的操作符重载，你就可以马上开始创建表达式模板了。
+
+Defining terminals -- with aggregate initialization -- can be a little
awkward at times. Proto provides an easier-to-use wrapper for literals that
can be used to construct Protofied terminal expressions. It's called
_literal_.\n
+定义终结符 -- 加上初始化 -- 通常有些难看。Proto 为字面值提供了一个更为易用
的包装器，可以用于构造Proto化的终结符表达式工。
+它名为 _literal_。
+
+ // Define a literal integer Proto expression. 定义一个字面值整数 Proto
表达式。
proto::literal<int> i = 0;
// Proto literals are really just Proto terminal expressions.
// For example, this builds a Proto expression template:
+ // Proto 字面值其实就是 Proto 终结符表达式工。例如，以下创建一个 Proto
表达式模板：
i + 1;
-There is also a _lit_ function for constructing a _literal_ in-place. The
above expression can simply be written as:
+There is also a _lit_ function for constructing a _literal_ in-place. The
above expression can simply be written as:\n
+还有一个 _lit_ 函数用于就地构造 _literal_。以上表达式可以简化为：
// proto::lit(0) creates an integer terminal expression
+ // proto::lit(0) 创建一个整数终结符表达式
proto::lit(0) + 1;
[endsect]
[/=================================]
-[section Proto's Operator Overloads]
+[section Proto's Operator Overloads Proto的操作符重载]
[/=================================]
-Once we have some Proto terminals, expressions involving those terminals
build expression trees for us. Proto defines overloads for each of C++'s
overloadable operators in the `boost::proto` namespace. As long as one
operand is a Proto expression, the result of the operation is a tree node
representing that operation.
-
-[note Proto's operator overloads live in the `boost::proto` namespace and
are found via ADL (argument-dependent lookup). That is why expressions must
be "tainted" with Proto-ness for Proto to be able to build trees out of
expressions.]
-
-As a result of Proto's operator overloads, we can say:
+Once we have some Proto terminals, expressions involving those terminals
build expression trees for us. Proto defines overloads for each of C++'s
overloadable operators in the `boost::proto` namespace. As long as one
operand is a Proto expression, the result of the operation is a tree node
representing that operation. \n
+一旦我们有了一些 Proto 终结符之后，包含这些终结符的表达式将会为我们构建相应
的表达式树。
+Proto 在 `boost::proto` 名字空间中为C++的每一个可重载的操作符都定义了重载。
只要有一个操作数是 Proto 表达式，
+操作的结果就是一个表示该操作的树节点。
+
+[note Proto's operator overloads live in the `boost::proto` namespace and
are found via ADL (argument-dependent lookup). That is why expressions must
be "tainted" with Proto-ness for Proto to be able to build trees out of
expressions.\n
+Proto 的操作符重载位于 `boost::proto` 名字空间内，要通过ADL(参数依赖查找)来
查找。这就是为什么表达式必须要被Proto化对象"感染"，
+Proto 才能构建出表达式树的原因。]
+
+As a result of Proto's operator overloads, we can say:\n
+作为 Proto 操作符重载的结果，我们可以写：
-_1; // OK, build a unary-negate tree node
_1 + 42; // OK, build a binary-plus tree node
-For the most part, this Just Works and you don't need to think about it,
but a few operators are special and it can be helpful to know how Proto
handles them.
+For the most part, this Just Works and you don't need to think about it,
but a few operators are special and it can be helpful to know how Proto
handles them.\n
+大多数情况下，都可以正常工作，你无需担心它，不过有少数的操作符比较特殊，知
道 Proto 是如何处理它们的可以有所帮助。
[/=========================================================]
-[heading Assignment, Subscript, and Function Call Operators]
+[heading Assignment, Subscript, and Function Call Operators 赋值、下标和函
数调用操作符]
[/=========================================================]
-Proto also overloads `operator=`, `operator[]`, and `operator()`, but
these operators are member functions of the expression template rather than
free functions in Proto's namespace. The following are valid Proto
expressions:
+Proto also overloads `operator=`, `operator[]`, and `operator()`, but
these operators are member functions of the expression template rather than
free functions in Proto's namespace. The following are valid Proto
expressions:\n
+Proto 也重载了 `operator=`, `operator[]`, 和 `operator()`, 不过这些操作符是
表达式模板的成员函数，
+而不是 Proto 名字空间下的普通函数。以下是有效的 Proto 表达式：
_1 = 5; // OK, builds a binary assign tree node
_1[6]; // OK, builds a binary subscript tree node
@@ -70,9 +89,13 @@
_1(8,9); // OK, builds a ternary function tree node
// ... etc.
-For the first two lines, assignment and subscript, it should be fairly
unsurprising that the resulting expression node should be binary. After
all, there are two operands in each expression. It may be surprising at
first that what appears to be a function call with no arguments, `_1()`,
actually creates an expression node with one child. The child is `_1`
itself. Likewise, the expression `_1(7)` has two children: `_1` and `7`.
-
-Because these operators can only be defined as member functions, the
following expressions are invalid:
+For the first two lines, assignment and subscript, it should be fairly
unsurprising that the resulting expression node should be binary. After
all, there are two operands in each expression. It may be surprising at
first that what appears to be a function call with no arguments, `_1()`,
actually creates an expression node with one child. The child is `_1`
itself. Likewise, the expression `_1(7)` has two children: `_1` and `7`.\n
+头两行，赋值和下标操作，产生的表达式节点是二元的，这应该不足为奇。毕竟，每
个表达式都有两个操作数。
+可能会令人惊奇的首先是不带参数的函数调用，`_1()`, 实际上它将创建一个带有一
个子节点的表达式节点。这个子节点就是 `_1` 本身。
+同样，表达式 `_1(7)` 有两个子节点：`_1` 和 `7`。
+
+Because these operators can only be defined as member functions, the
following expressions are invalid:\n
+因为这些操作符只能被定义为成员函数，所以以下表达式是无效的：
int i;
i = _1; // ERROR: cannot assign _1 to an int
@@ -82,17 +105,21 @@
std::sin(_1); // ERROR: cannot call std::sin() with _1
-Also, C++ has special rules for overloads of `operator->` that make it
useless for building expression templates, so Proto does not overload it.
+Also, C++ has special rules for overloads of `operator->` that make it
useless for building expression templates, so Proto does not overload it.\n
+还有，C++对于 `operator->` 的重载具有特殊的规则，使得它不能用于构建表达式模
板，因此 Proto 没有重载它。
[/==============================]
-[heading The Address-Of Operator]
+[heading The Address-Of Operator 取址操作符]
[/==============================]
-Proto overloads the address-of operator for expression types, so that the
following code creates a new unary address-of tree node:
+Proto overloads the address-of operator for expression types, so that the
following code creates a new unary address-of tree node:\n
+Proto 为表达式类型重载了取址操作符，以下代码将会创建一个新的单参取址操作的
树节点：
&_1; // OK, creates a unary address-of tree node
-It does /not/ return the address of the `_1` object. However, there is
special code in Proto such that a unary address-of node is implicitly
convertible to a pointer to its child. In other words, the following code
works and does what you might expect, but not in the obvious way:
+It does /not/ return the address of the `_1` object. However, there is
special code in Proto such that a unary address-of node is implicitly
convertible to a pointer to its child. In other words, the following code
works and does what you might expect, but not in the obvious way:\n
+它/不是/返回 `_1` 对象的地址。不过，在 Proto 中有特殊的代码，使得一个单参取
址节点可以隐式转换为其子节点的指针。
+换言之，以下代码可以工作且结果如你所想，只不过方式不太明显而已：
typedef
proto::terminal< placeholder<0> >::type
@@ -104,53 +131,73 @@
[endsect]
[/============================]
-[section Making Lazy Functions]
+[section Making Lazy Functions 制造惰性函数]
[/============================]
-If we limited ourselves to nothing but terminals and operator overloads,
our domain-specific embedded languages wouldn't be very expressive. Imagine
that we wanted to extend our calculator DSEL with a full suite of math
functions like `sin()` and `pow()` that we could invoke lazily as follows.
+If we limited ourselves to nothing but terminals and operator overloads,
our domain-specific embedded languages wouldn't be very expressive. Imagine
that we wanted to extend our calculator DSEL with a full suite of math
functions like `sin()` and `pow()` that we could invoke lazily as follows.\n
+如果我们把自己仅限制在终结符和操作符重载上，那么我们的DSEL不会太有表达力。
想象一下，我们想以一整套数学函数，
+如 `sin()` 和 `pow()`，来扩展我们的计算器DSEL，以便我们可以象下面这样对这些
函数进行惰性执行。
// A calculator expression that takes one argument
// and takes the sine of it.
+ // 一个计算器表达式工，带有一个参数和正弦函数。
sin(_1);
-We would like the above to create an expression template representing a
function invocation. When that expression is evaluated, it should cause the
function to be invoked. (At least, that's the meaning of function
invocation we'd like the calculator DSEL to have.) You can define `sin`
quite simply as follows.
+We would like the above to create an expression template representing a
function invocation. When that expression is evaluated, it should cause the
function to be invoked. (At least, that's the meaning of function
invocation we'd like the calculator DSEL to have.) You can define `sin`
quite simply as follows.\n
+我们希望以上代码可以创建一个表示这次函数调用的表达式模板。当对此表达式进行
求值时，将引发对此函数的调用。
+(至少，这是我们所想要的计算器DSEL应具有的函数调用的意义)。你可以象下面这样
非常简单地定义 `sin`。
// "sin" is a Proto terminal containing a function pointer
+ // "sin" 是一个 Proto 终结符，包含一个函数指针
proto::terminal< double(*)(double) >::type const sin = {&std::sin};
-In the above, we define `sin` as a Proto terminal containing a pointer to
the `std::sin()` function. Now we can use `sin` as a lazy function. The
`default_context` that we saw in the Introduction knows how to evaluate
lazy functions. Consider the following:
+In the above, we define `sin` as a Proto terminal containing a pointer to
the `std::sin()` function. Now we can use `sin` as a lazy function. The
`default_context` that we saw in the Introduction knows how to evaluate
lazy functions. Consider the following:\n
+在上述代码中，我们将 `sin` 定义为一个含有一个 `std::sin()` 函数指针的
Proto 终结符。现在我们可以将 `sin` 作为惰性函数来使用。
+我们在"简介"中看到的 `default_context` 知道如何对惰性函数进行求值。考虑以下
代码：
double pi = 3.1415926535;
proto::default_context ctx;
// Create a lazy "sin" invocation and immediately evaluate it
+ // 创建一个惰性"sin"调用并马上对它求值
std::cout << proto::eval( sin(pi/2), ctx ) << std::endl;
-The above code prints out:
+The above code prints out:\n
+以上代码将打印出：
[pre 1]
-It is important to note that there is nothing special about terminals that
contain function pointers. /Any/ Proto expression has an overloaded
function call operator. Consider:
-
- // This compiles!
+It is important to note that there is nothing special about terminals that
contain function pointers. /Any/ Proto expression has an overloaded
function call operator. Consider:\n
+有一点很重要，含有函数指针的终结符并没有什么特殊。/任何/ Proto 表达式都有一
个重载的函数调用操作符。考虑：
+
+ // This compiles! 这是可以编译的！
proto::lit(1)(2)(3,4)(5,6,7,8);
-That may look strange at first. It creates an integer terminal with _lit_,
and then invokes it like a function again and again. What does it mean? To
be sure, the `default_context` wouldn't know what to do with it. The
`default_context` only knows how to evaluate expressions that are
sufficiently C++-like. In the case of function call expressions, the left
hand side must evaluate to something that can be invoked: a pointer to a
function, a reference to a function, or a TR1-style function object. That
doesn't stop you from defining your own evaluation context that gives that
expression a meaning. But more on that later.
+That may look strange at first. It creates an integer terminal with _lit_,
and then invokes it like a function again and again. What does it mean? To
be sure, the `default_context` wouldn't know what to do with it. The
`default_context` only knows how to evaluate expressions that are
sufficiently C++-like. In the case of function call expressions, the left
hand side must evaluate to something that can be invoked: a pointer to a
function, a reference to a function, or a TR1-style function object. That
doesn't stop you from defining your own evaluation context that gives that
expression a meaning. But more on that later.\n
+这看起来很怪异。它首先以 _lit_ 创建一个整数终结符，然后一遍一遍地象函数一样
调用它。这意味着什么呢？可以肯定的是，
+`default_context` 不知道这要做什么。`default_context` 只知道如何完全按C++的
方式来对表达式求值。对于函数调用表达式，
+其左边的操作数必须求值为某种可以调用的东西：函数指针、函数引用或TR1风格的函
数对象。不过这并不妨碍你定义自己的求值上下文，
+来给这个表达式赋予某种意义。那是后话。
[/=======================================]
-[heading Making Lazy Functions, Continued]
+[heading Making Lazy Functions, Continued 制造惰性函数(续)]
[/=======================================]
-Now, what if we wanted to add a `pow()` function to our calculator DSEL
that users could invoke as follows?
+Now, what if we wanted to add a `pow()` function to our calculator DSEL
that users could invoke as follows?\n
+现在，如果我们想把 `pow()` 函数增加到我们的计算器DSEL中，让用户可以象下面那
样来调用，又该如何？
// A calculator expression that takes one argument
// and raises it to the 2nd power
+ // 一个计算器表达式，带有一个参数并计算其平方
pow< 2 >(_1);
-The simple technique described above of making `pow` a terminal containing
a function pointer doesn't work here. If `pow` is an object, then the
expression `pow< 2 >(_1)` is not valid C++. `pow` needs to be a real
function template. But it must be an unusual function; it must return an
expression template.
-
-Before we can write the `pow()` function, we need a function object that
wraps an invocation of `std::pow()`.
-
- // Define a pow_fun function object
+The simple technique described above of making `pow` a terminal containing
a function pointer doesn't work here. If `pow` is an object, then the
expression `pow< 2 >(_1)` is not valid C++. `pow` needs to be a real
function template. But it must be an unusual function; it must return an
expression template.\n
+前面所讲的简单技术，把 `pow` 做成一个含有函数指针的终结符，在这里是不行的。
如果 `pow` 是一个对象，则表达式 `pow< 2 >(_1)`
+不是有效的C++表达式。`pow` 必须是一个真实的函数模板。但是它又必须是一个不平
常的函数；它必须返回一个表达式模板。
+
+Before we can write the `pow()` function, we need a function object that
wraps an invocation of `std::pow()`. \n
+在我们编写 `pow()` 函数之前，我们需要一个函数对象来包装对 `std::pow()` 的调
用。
+
+ // Define a pow_fun function object 定义一个 pow_fun 函数对象
template<int Exp>
struct pow_fun
{
@@ -161,10 +208,13 @@
}
};
-Now, let's try to define a function template that returns an expression
template. We'll use the _function_ metafunction to calculate the type of a
Proto expression that represents a function call. It is analogous to
_terminal_. (We'll see a couple of different ways to solve this problem,
and each will demonstrate another utility for defining Proto front-ends.)
+Now, let's try to define a function template that returns an expression
template. We'll use the _function_ metafunction to calculate the type of a
Proto expression that represents a function call. It is analogous to
_terminal_. (We'll see a couple of different ways to solve this problem,
and each will demonstrate another utility for defining Proto front-ends.)\n
+现在，我们来试一下定义一个返回表达式模板的函数模板。我们将使用
proto::function<> 元函数来计算表示一个函数调用的 Proto 表达式的类型。
+它类似于 _terminal_. (我们将看到解决这一问题的几种不同方法，每一种示范了定
义 Proto 前端的不同工具)。
// Define a lazy pow() function for the calculator DSEL.
// Can be used as: pow< 2 >(_1)
+ // 为计算器DSEL定义一个惰性的 pow() 函数。可以这样来使用：pow<2>(_1)
template<int Exp, typename Arg>
typename proto::function<
typename proto::terminal<pow_fun<Exp> >::type
@@ -183,32 +233,44 @@
return result;
}
-In the code above, notice how the _function_ and _terminal_ metafunctions
are used to calculate the return type: `pow()` returns an expression
template representing a function call where the first child is the function
to call and the second is the argument to the function. (Unfortunately, the
same type calculation is repeated in the body of the function so that we
can initialize a local variable of the correct type. We'll see in a moment
how to avoid that.)
-
-[note As with _function_, there are metafunctions corresponding to all of
the overloadable C++ operators for calculating expression types.]
-
-With the above definition of the `pow()` function, we can create
calculator expressions like the one below and evaluate them using the
`calculator_context` we implemented in the Introduction.
-
- // Initialize a calculator context
+In the code above, notice how the _function_ and _terminal_ metafunctions
are used to calculate the return type: `pow()` returns an expression
template representing a function call where the first child is the function
to call and the second is the argument to the function. (Unfortunately, the
same type calculation is repeated in the body of the function so that we
can initialize a local variable of the correct type. We'll see in a moment
how to avoid that.)\n
+在以上代码中，留意 _function_ 和 _terminal_ 元函数是如何用于计算返回类型
的：`pow()` 返回一个表示函数调用的表达式模板，
+其第一个子节点为要调用的函数，第二个为该函数的参数。(不幸的是，在函数体
中，为了可以初始化一个正确类型的局部变量，
+我们重复了相同的类型计算。待会我们将看到如何避免这一点)。
+
+[note As with _function_, there are metafunctions corresponding to all of
the overloadable C++ operators for calculating expression types.\n
+跟 _function_ 相似，对于所有可重载的C++操作符，都有相应的元函数用于计算得到
表达式的类型。]
+
+With the above definition of the `pow()` function, we can create
calculator expressions like the one below and evaluate them using the
`calculator_context` we implemented in the Introduction.\n
+有了以上的 `pow()` 函数定义，我们就可以象下面那样创建计算器表达式，并使用我
们在"简介"中实现的 `calculator_context` 来进行求值。
+
+ // Initialize a calculator context 初始化一个计算器上下文
calculator_context ctx;
ctx.args.push_back(3); // let _1 be 3
// Create a calculator expression that takes one argument,
// adds one to it, and raises it to the 2nd power; and then
// immediately evaluate it using the calculator_context.
+ // 创建一个带一个参数的计算器表达式，将参数加一，再求平方；然后马上使用
+ // calculator_context 对它进行求值。
assert( 16 == proto::eval( pow<2>( _1 + 1 ), ctx ) );
[/=========================================]
-[heading Protofying Lazy Function Arguments]
+[heading Protofying Lazy Function Arguments 将惰性函数的参数Proto化]
[/=========================================]
-Above, we defined a `pow()` function template that returns an expression
template representing a lazy function invocation. But if we tried to call
it as below, we'll run into a problem.
+Above, we defined a `pow()` function template that returns an expression
template representing a lazy function invocation. But if we tried to call
it as below, we'll run into a problem.\n
+前面，我们定义了一个 `pow()` 函数模板，它返回一个表达式模板，以表示一个惰性
函数的调用。
+但是，如果我们试着按以下方式调用它，就是遇到问题。
// ERROR: pow() as defined above doesn't work when
// called with a non-Proto argument.
+ // 错误：前面所定义的pow()在使用非Proto化的参数时不能工作
pow< 2 >( 4 );
-Proto expressions can only have other Proto expressions as children. But
if we look at `pow()`'s function signature, we can see that if we pass it a
non-Proto object, it will try to make it a child.
+Proto expressions can only have other Proto expressions as children. But
if we look at `pow()`'s function signature, we can see that if we pass it a
non-Proto object, it will try to make it a child.\n
+Proto 表达式只能以其它 Proto 表达式作为子节点。但如果我们看一下 `pow()` 的
函数签名，我们可以看到，
+如果我们传给它一个非Proto化的对象，它会尝试把它当成子节点。
template<int Exp, typename Arg>
typename proto::function<
@@ -217,11 +279,15 @@
>::type const
pow(Arg const &arg)
-What we want is a way to make `Arg` into a Proto terminal if it is not a
Proto expression already, and leave it alone if it is. For that, we can use
_as_child_. The following implementation of the `pow()` function handles
all argument types, expression templates or otherwise.
+What we want is a way to make `Arg` into a Proto terminal if it is not a
Proto expression already, and leave it alone if it is. For that, we can use
_as_child_. The following implementation of the `pow()` function handles
all argument types, expression templates or otherwise.\n
+我们想要的就是，当 `Arg` 不是一个 Proto 表达式时，把它放入一个 Proto 终结符
中，而如果它已经是一个 Proto 表达式则保留它。
+为此，我们可以使用 _as_child_。以下的 `pow()` 函数实现可以处理所有参数类
型，包括表达式模板或其它类型。
// Define a lazy pow() function for the calculator DSEL. Use
// proto::as_child() to Protofy the argument, but only if it
// is not a Proto expression type to begin with!
+ // 为计算器DSEL定义一个惰性pow()函数。用proto::as_child()来对参数
+ // 进行Proto化，仅当参数不是Proto表达式类型时才进行！
template<int Exp, typename Arg>
typename proto::function<
typename proto::terminal<pow_fun<Exp> >::type
@@ -240,76 +306,105 @@
return result;
}
-Notice how we use the `proto::result_of::as_child<>` metafunction to
calculate the return type, and the `proto::as_child()` function to actually
normalize the argument.
+Notice how we use the `proto::result_of::as_child<>` metafunction to
calculate the return type, and the `proto::as_child()` function to actually
normalize the argument.\n
+留意一下我们是如何使用 `proto::result_of::as_child<>` 元函数来计算返回类型
的，以及如何用 `proto::as_child()` 函数来实际地规范参数。
[/=====================================================]
-[heading Lazy Functions Made Simple With [^make_expr()]]
+[heading Lazy Functions Made Simple With [^make_expr()] 用 [^make_expr()]
简化惰性函数]
[/=====================================================]
-The versions of the `pow()` function we've seen above are rather verbose.
In the return type calculation, you have to be very explicit about wrapping
non-Proto types. Worse, you have to restate the return type calculation in
the body of `pow()` itself. Proto provides a helper for building expression
templates directly that handles these mundane details for you. It's called
_make_expr_. We can redefine `pow()` with it as below.
+The versions of the `pow()` function we've seen above are rather verbose.
In the return type calculation, you have to be very explicit about wrapping
non-Proto types. Worse, you have to restate the return type calculation in
the body of `pow()` itself. Proto provides a helper for building expression
templates directly that handles these mundane details for you. It's called
_make_expr_. We can redefine `pow()` with it as below.\n
+上面我们看到的这个版本的 `pow()` 函数真的很冗长。在计算返回类型时，你必须非
常明确地包装非Proto类型。更糟的是，
+你必须在 `pow()` 的函数体中再计算一次这个返回类型。Proto 提供了一个辅助工具
直接构建表达式模板，代你处理这些麻烦的细节。
+这个工具名为 _make_expr_。我们可以如下重新定义 `pow()`。
// Define a lazy pow() function for the calculator DSEL.
// Can be used as: pow< 2 >(_1)
+ // 为计算器DSEL定义一个惰性pow()函数。可以这样使用它：pow<2>(_1)
template<int Exp, typename Arg>
typename proto::result_of::make_expr<
- proto::tag::function // Tag type
- , pow_fun<Exp> // First child (by value)
- , Arg const & // Second child (by reference)
+ proto::tag::function // Tag type 标签类型
+ , pow_fun<Exp> // First child (by value) 第一个子节点(传值)
+ , Arg const & // Second child (by reference) 第二个子节点
(传引用)
>::type const
pow(Arg const &arg)
{
return proto::make_expr<proto::tag::function>(
- pow_fun<Exp>() // First child (by value)
- , boost::ref(arg) // Second child (by reference)
+ pow_fun<Exp>() // First child (by value) 第一个子节点(传值)
+ , boost::ref(arg) // Second child (by reference) 第二个子节点
(传引用)
);
}
-There are some things to notice about the above code. We use
`proto::result_of::make_expr<>` to calculate the return type. The first
template parameter is the tag type for the expression node we're building
-- in this case, `proto::tag::function`, which is the tag type Proto uses
for function call expressions.
-
-Subsequent template parameters to `proto::result_of::make_expr<>`
represent children nodes. If a child type is not already a Proto
expression, it is made into a terminal with _as_child_. A type such as
`pow_fun<Exp>` results in terminal that is held by value, whereas a type
like `Arg const &` (note the reference) indicates that the result should be
held by reference.
-
-In the function body is the runtime invocation of _make_expr_. It closely
mirrors the return type calculation. _make_expr_ requires you to specify
the node's tag type as a template parameter. The arguments to the function
become the node's children. When a child should be stored by value, nothing
special needs to be done. When a child should be stored by reference, you
must use the `boost::ref()` function to wrap the argument. Without this
extra information, the _make_expr_ function couldn't know whether to store
a child by value or by reference.
+There are some things to notice about the above code. We use
`proto::result_of::make_expr<>` to calculate the return type. The first
template parameter is the tag type for the expression node we're building
-- in this case, `proto::tag::function`, which is the tag type Proto uses
for function call expressions.\n
+以上代码中有一些地方要注意。我们使用了 `proto::result_of::make_expr<>` 来计
算返回的类型。
+第一个模板参数是我们要构建的表达式节点的标签类型 -- 在这个例子中是
`proto::tag::function`，它是 Proto 中用于函数调用表达式的标签类型。
+
+Subsequent template parameters to `proto::result_of::make_expr<>`
represent children nodes. If a child type is not already a Proto
expression, it is made into a terminal with _as_child_. A type such as
`pow_fun<Exp>` results in terminal that is held by value, whereas a type
like `Arg const &` (note the reference) indicates that the result should be
held by reference.\n
+`proto::result_of::make_expr<>` 接下来的模板参数代表两个子节点。如果某个子
节点类型不是 Proto 表达式，
+那么就用 _as_child_ 将它放入一个终结符中。象 `pow_fun<Exp>` 这样的类型在终
结符中会以值的方式保存，
+而象 `Arg const &` (注意这个引用)这样的类型则表示其结果以引用的方式保存。
+
+In the function body is the runtime invocation of _make_expr_. It closely
mirrors the return type calculation. _make_expr_ requires you to specify
the node's tag type as a template parameter. The arguments to the function
become the node's children. When a child should be stored by value, nothing
special needs to be done. When a child should be stored by reference, you
must use the `boost::ref()` function to wrap the argument. Without this
extra information, the _make_expr_ function couldn't know whether to store
a child by value or by reference.\n
+在函数体中，是 _make_expr_ 的运行期调用。它与返回类型的计算几乎一样。
_make_expr_ 要求你将节点的标签类型指定为一个模板参数。
+传递给函数的参数变为节点的子节点。当一个子节点要以值的方式保存时，不需要做
特殊处理。当一个子节点要以引用的方式保存时，
+你必须用 `boost::ref()` 函数来包装这个参数。如果没有这些额外的信息，
+_make_expr_ 函数就不可能知道要以值的方式还是引用的方式来保存子节点。
[endsect]
[/==============================================]
-[section Adding Members by Extending Expressions]
+[section Adding Members by Extending Expressions 通过扩展表达式增加成员]
[/==============================================]
-In this section, we'll see how to associate Proto expressions with a
/domain/, how to add members to expressions within a domain, and how to
control which operators are overloaded in a domain.
+In this section, we'll see how to associate Proto expressions with a
/domain/, how to add members to expressions within a domain, and how to
control which operators are overloaded in a domain.\n
+在这一节中，我们将看到如何把 Proto 表达式与一个/领域/关联起来，如果往领域内
的表达式增加成员，以及如何一个领域中哪些操作符被重载。
[/==============]
-[section Domains]
+[section Domains 领域]
[/==============]
-In the [link boost_proto.users_guide.getting_started.hello_calculator
Hello Calculator] section, we looked into making calculator expressions
directly usable as lambda expressions in calls to STL algorithms, as below:
+In the [link boost_proto.users_guide.getting_started.hello_calculator
Hello Calculator] section, we looked into making calculator expressions
directly usable as lambda expressions in calls to STL algorithms, as
below:\n
+在 [link boost_proto.users_guide.getting_started.hello_calculator Hello
Calculator] 一节中，
+我们已经看到可以在调用STL算法时直接创建计算器表达式并象 lambda 表达式那样使
用它，如下：
double data[] = {1., 2., 3., 4.};
// Use the calculator DSEL to square each element ... HOW?
+ // 使用计算器DSEL对每个元素计算平方 ... 如何？
std::transform( data, data + 4, data, _1 * _1 );
-The difficulty, if you recall, was that by default Proto expressions don't
have interesting behaviors of their own. They're just trees. In particular,
the expression `_1 * _1` won't have an `operator()` that takes a double and
returns a double like `std::transform()` expects -- unless we give it one.
To make this work, we needed to define an expression wrapper type that
defined the `operator()` member function, and we needed to associate the
wrapper with the calculator /domain/.
-
-In Proto, the term /domain/ refers to a type that associates expressions
in that domain to an expression /generator/. The generator is just a
function object that accepts an expression and does something to it, like
wrapping it in an expression wrapper.
-
-You can also use a domain to associate expressions with a grammar. When
you specify a domain's grammar, Proto ensures that all the expressions it
generates in that domain conform to the domain's grammar. It does that by
disabling any operator overloads that would create invalid expressions.
+The difficulty, if you recall, was that by default Proto expressions don't
have interesting behaviors of their own. They're just trees. In particular,
the expression `_1 * _1` won't have an `operator()` that takes a double and
returns a double like `std::transform()` expects -- unless we give it one.
To make this work, we needed to define an expression wrapper type that
defined the `operator()` member function, and we needed to associate the
wrapper with the calculator /domain/.\n
+如果你还记得，难点在于缺省情况下 Proto 表达式并不关心它们自己的行为。它们仅
仅是一些树。具体地说，
+表达式 `_1 * _1` 并不象 `std::transform()` 所期望那样带有一个 `operator()`
来接受一个 double 并返回一个 double -- 除非我们给它一个。
+要让它能用，我们必须定义一个表达式包装器类型，其中定义了 `operator()` 成员
函数，然后我们必须把这个包装器关联到这个计算器/领域/。
+
+In Proto, the term /domain/ refers to a type that associates expressions
in that domain to an expression /generator/. The generator is just a
function object that accepts an expression and does something to it, like
wrapping it in an expression wrapper.\n
+在 Proto 中，术语 /领域/ 是指一个类型，用于把该领域中的表达式关联至一个表达
式/生成器/。这个生成器是一个函数对象，
+它接受一个表达式并对它做一些事情，如把表达式包入一个表达式包装器。
+
+You can also use a domain to associate expressions with a grammar. When
you specify a domain's grammar, Proto ensures that all the expressions it
generates in that domain conform to the domain's grammar. It does that by
disabling any operator overloads that would create invalid expressions.\n
+你也可以用一个领域来将表达式与某种语法关联起来。当你指定一个领域语
法，Proto 将确保它在此领域中生成的表达式都符合该领域的语法。
+它是通过禁止掉一些可能创建无效表达式的操作符重载来实现这一点的。
[endsect]
[/==================================================]
-[section:extends The [^extends<>] Expression Wrapper]
+[section:extends The [^extends<>] Expression Wrapper [^extends<>]表达式包装
器]
[/==================================================]
-The first step to giving your calculator expressions extra behaviors is to
define a calculator domain. All expressions within the calculator domain
will be imbued with calculator-ness, as we'll see.
+The first step to giving your calculator expressions extra behaviors is to
define a calculator domain. All expressions within the calculator domain
will be imbued with calculator-ness, as we'll see.\n
+要给你的计算器表达式赋予额外的行为，第一步是定义一个计算器域。在这个计算器
域中的所有表达式都将被注入计算器的特征，如后所见。
// A type to be used as a domain tag (to be defined below)
+ // 一个被用作为领域标签的类型(稍后定义)
struct calculator_domain;
-We use this domain type when extending the _expr_ type, which we do with
the _extends_ class template. Here is our expression wrapper, which imbues
an expression with calculator-ness. It is described below.
+We use this domain type when extending the _expr_ type, which we do with
the _extends_ class template. Here is our expression wrapper, which imbues
an expression with calculator-ness. It is described below.\n
+当我们用 _extends_ 类模板扩展 _expr_ 类型时，将会使用这个领域类型。。以下是
我们的表达式包装器，它向一个表达式注入计算器特征。说明如下。
// The calculator<> expression wrapper makes expressions
// function objects.
+ // calculator<> 表达式包装器把表达式变为函数对象。
template< typename Expr >
struct calculator
: proto::extends< Expr, calculator< Expr >, calculator_domain >
@@ -324,103 +419,143 @@
// This is usually needed because by default, the compiler-
// generated assignment operator hides extends<>::operator=
+ // 缺省情况下通常都需要这个，因为编译器生成的赋值操作符会隐藏
extends<>::operator=
using base_type::operator =;
typedef double result_type;
// Hide base_type::operator() by defining our own which
// evaluates the calculator expression with a calculator context.
+ // 定义我们自己的 operator() 来隐藏 base_type::operator()，用一个计
算器上下文来对计算器表达式求值。
result_type operator()( double d1 = 0.0, double d2 = 0.0 ) const
{
// As defined in the Hello Calculator section.
+ // 和 Hello Calculator 一节中的定义一样。
calculator_context ctx;
// ctx.args is a vector<double> that holds the values
// with which we replace the placeholders (e.g., _1 and _2)
// in the expression.
- ctx.args.push_back( d1 ); // _1 gets the value of d1
- ctx.args.push_back( d2 ); // _2 gets the value of d2
-
- return proto::eval(*this, ctx ); // evaluate the expression
+ // ctx.args 是一个 vector<double>，保存了我们用于替换表达式中的
占位符(如 _1 和 _2)的值。
+ ctx.args.push_back( d1 ); // _1 gets the value of d1 _1获得
d1的值
+ ctx.args.push_back( d2 ); // _2 gets the value of d2 _2获得
d2的值
+
+ return proto::eval(*this, ctx ); // evaluate the expression 对
表达式求值
}
};
-We want calculator expressions to be function objects, so we have to
define an `operator()` that takes and returns doubles. The `calculator<>`
wrapper above does that with the help of the _extends_ template. The first
template to _extends_ parameter is the expression type we are extending.
The second is the type of the wrapped expression. The third parameter is
the domain that this wrapper is associated with. A wrapper type like
`calculator<>` that inherits from _extends_ behaves just like the
expression type it has extended, with any additional behaviors you choose
to give it.
-
-[note [*Why not just inherit from [^proto::expr<>]?]
-
-You might be thinking that this expression extension business is
unnecessarily complicated. After all, isn't this why C++ supports
inheritance? Why can't [^calculator<Expr>] just inherit from [^Expr]
directly? The reason is because [^Expr], which presumably is an
instantiation of _expr_, has expression template-building operator
overloads that will be incorrect for derived types. They will store `*this`
by reference to `proto::expr<>`, effectively slicing off any derived parts.
_extends_ gives your derived types operator overloads that don't slice off
your additional members.]
-
-Although not strictly necessary in this case, we bring
`extends<>::operator=` into scope with a `using` declaration. This is
really only necessary if you want expressions like `_1 = 3` to create a
lazily evaluated assignment. _extends_ defines the appropriate `operator=`
for you, but the compiler-generated `calculator<>::operator=` will hide it
unless you make it available with the `using` declaration.
-
-Note that in the implementation of `calculator<>::operator()`, we evaluate
the expression with the `calculator_context` we defined earlier. As we saw
before, the context is what gives the operators their meaning. In the case
of the calculator, the context is also what defines the meaning of the
placeholder terminals.
-
-Now that we have defined the `calculator<>` expression wrapper, we need to
wrap the placeholders to imbue them with calculator-ness:
+We want calculator expressions to be function objects, so we have to
define an `operator()` that takes and returns doubles. The `calculator<>`
wrapper above does that with the help of the _extends_ template. The first
template to _extends_ parameter is the expression type we are extending.
The second is the type of the wrapped expression. The third parameter is
the domain that this wrapper is associated with. A wrapper type like
`calculator<>` that inherits from _extends_ behaves just like the
expression type it has extended, with any additional behaviors you choose
to give it.\n
+我们希望计算器表达式是一个函数对象，因此我们必须定义一个 `operator()` 来接
受和返回 doubles。上面这个 `calculator<>` 包装器在
+_extends_ 模板的帮助下完成此事。传给 _extends_ 的第一个模板参数是我们要扩展
的表达式类型。第二个是被包装表达式的类型。
+第三个参数是该包装器所关联的领域。象 `calculator<>` 这样的派生自 _extends_
的包装器类型，
+其行为是与其所扩展的表达式类型一样，再加上你选择给予它的其它行为。
+
+[note [*Why not just inherit from [^proto::expr<>]? 为什么不仅仅从
[^proto::expr<>] 继承?]
+
+You might be thinking that this expression extension business is
unnecessarily complicated. After all, isn't this why C++ supports
inheritance? Why can't [^calculator<Expr>] just inherit from [^Expr]
directly? The reason is because [^Expr], which presumably is an
instantiation of _expr_, has expression template-building operator
overloads that will be incorrect for derived types. They will store `*this`
by reference to `proto::expr<>`, effectively slicing off any derived parts.
_extends_ gives your derived types operator overloads that don't slice off
your additional members.\n
+你也许会认为这个表达式扩展有点不必要地复杂化了。毕竟，这难道不是C++要支持继
承的的原因吗？为什么 [^calculator<Expr>] 不能仅仅直接从
+[^Expr] 派生？原因是，因为 [^Expr] 是 _expr_ 的一个实例，它具有表达式模板构
建的操作符重载，这对于派生类型是不正确的。
+它们会以引用方式保存 `*this`，指向 `proto::expr<>`，有效地切割掉派生类的其
它部分。
+_extends_ 为你的派生类给出了不会切割掉其它成员的操作符重载。]
+
+Although not strictly necessary in this case, we bring
`extends<>::operator=` into scope with a `using` declaration. This is
really only necessary if you want expressions like `_1 = 3` to create a
lazily evaluated assignment. _extends_ defines the appropriate `operator=`
for you, but the compiler-generated `calculator<>::operator=` will hide it
unless you make it available with the `using` declaration.\n
+虽然在这里不是严格必需，但是我们还是用一个 `using` 声明将
`extends<>::operator=` 带入此作用域。实际上，
+只有当你想要象 `_1 = 3` 这样的表达式可以创建一个惰性求值的赋值操作时，才需
要这样做。虽然 _extends_ 为你定义了适当的 `operator=`，
+但是编译器所生成的 `calculator<>::operator=` 会隐藏它，除非你用 `using` 声
明来使之可见。
+
+Note that in the implementation of `calculator<>::operator()`, we evaluate
the expression with the `calculator_context` we defined earlier. As we saw
before, the context is what gives the operators their meaning. In the case
of the calculator, the context is also what defines the meaning of the
placeholder terminals.\n
+注意，在 `calculator<>::operator()` 的实现中，我们用早先定义的
`calculator_context` 来对表达式进行求值。
+如前所述，上下文是给表达式赋予某种意义的。在这个计算器的例子中，上下文定义
了占位符终结符的意义。
+
+Now that we have defined the `calculator<>` expression wrapper, we need to
wrap the placeholders to imbue them with calculator-ness:\n
+现在我们已经定义了 `calculator<>` 表达式包装器，我们需要对占位符进行包
装，为它们注入计算器特征：
calculator< proto::terminal< placeholder<0> >::type > const _1;
calculator< proto::terminal< placeholder<1> >::type > const _2;
[/=======================================================]
-[heading Retaining POD-ness with [^BOOST_PROTO_EXTENDS()]]
+[heading Retaining POD-ness with [^BOOST_PROTO_EXTENDS()] 用
[^BOOST_PROTO_EXTENDS()] 保留POD性质]
[/=======================================================]
To use _extends_, your extension type must derive from _extends_.
Unfortunately, that means that your extension type is no longer POD and its
instances cannot be /statically initialized/. (See the [link
boost_proto.appendices.rationale.static_initialization Static
-Initialization] section in the [link boost_proto.appendices.rationale
Rationale] appendix for why this matters.) In particular, as defined above,
the global placeholder objects `_1` and `_2` will need to be initialized at
runtime, which could lead to subtle order of initialization bugs.
-
-There is another way to make an expression extension that doesn't
sacrifice POD-ness : the _EXTENDS_ macro. You can use it much like you use
_extends_. We can use _EXTENDS_ to keep `calculator<>` a POD and our
placeholders statically initialized.
+Initialization] section in the [link boost_proto.appendices.rationale
Rationale] appendix for why this matters.) In particular, as defined above,
the global placeholder objects `_1` and `_2` will need to be initialized at
runtime, which could lead to subtle order of initialization bugs.\n
+要使用 _extends_，你的扩展类型必须派生自 _extends_。不幸的是，这意味着你的
扩展类型不再是POD，且其实例不能被/静态初始化/。
+(为什么会这样，请见附录 [link boost_proto.appendices.rationale 原理] 中
+[link boost_proto.appendices.rationale.static_initialization 静态初始化] 一
节)。具体地说，按以上定义，
+全局占位符 `_1` 和 `_2` 必须在运行期初始化，这有可能导致微妙的初始化顺序问
题。
+
+There is another way to make an expression extension that doesn't
sacrifice POD-ness : the _EXTENDS_ macro. You can use it much like you use
_extends_. We can use _EXTENDS_ to keep `calculator<>` a POD and our
placeholders statically initialized.\n
+有另一个方法可以让表达式扩展无需牺牲POD特性：宏 _EXTENDS_。你可以象使用
_extends_ 那样使用它。
+我们可以用 _EXTENDS_ 来使 `calculator<>` 保持为一个 POD 且我们的占位符可以
被静态初始化。
// The calculator<> expression wrapper makes expressions
// function objects.
+ // calculator<> 表达式包装器把表达式变为函数对象。
template< typename Expr >
struct calculator
{
// Use BOOST_PROTO_EXTENDS() instead of proto::extends<> to
// make this type a Proto expression extension.
+ // 使用 BOOST_PROTO_EXTENDS() 代替 proto::extends<> 来让这个类型成
为Proto表达式扩展。
BOOST_PROTO_EXTENDS(Expr, calculator<Expr>, calculator_domain)
typedef double result_type;
result_type operator()( double d1 = 0.0, double d2 = 0.0 ) const
{
- /* ... as before ... */
+ /* ... as before 如前 ... */
}
};
-With the new `calculator<>` type, we can redefine our placeholders to be
statically initialized:
+With the new `calculator<>` type, we can redefine our placeholders to be
statically initialized:\n
+用这个新的 `calculator<>` 类型，我们可以重新定义我们的占位符，并进行静态初
始化：
calculator< proto::terminal< placeholder<0> >::type > const _1 =
{{{}}};
calculator< proto::terminal< placeholder<1> >::type > const _2 =
{{{}}};
-We need to make one additional small change to accommodate the POD-ness of
our expression extension, which we'll describe below in the section on
expression generators.
-
-What does _EXTENDS_ do? It defines a data member of the expression type
being extended; some nested typedefs that Proto requires; `operator=`,
`operator[]` and `operator()` overloads for building expression templates;
and a nested `result<>` template for calculating the return type of
`operator()`. In this case, however, the `operator()` overloads and the
`result<>` template are not needed because we are defining our own
`operator()` in the `calculator<>` type. Proto provides additional macros
for finer control over which member functions are defined. We could improve
our `calculator<>` type as follows:
+We need to make one additional small change to accommodate the POD-ness of
our expression extension, which we'll describe below in the section on
expression generators.\n
+我们还需要一个小的修改来提供我们的表达式扩展的POD性，我们将在本节稍后的表达
生成器中描述这一点。
+
+What does _EXTENDS_ do? It defines a data member of the expression type
being extended; some nested typedefs that Proto requires; `operator=`,
`operator[]` and `operator()` overloads for building expression templates;
and a nested `result<>` template for calculating the return type of
`operator()`. In this case, however, the `operator()` overloads and the
`result<>` template are not needed because we are defining our own
`operator()` in the `calculator<>` type. Proto provides additional macros
for finer control over which member functions are defined. We could improve
our `calculator<>` type as follows:\n
+_EXTENDS_ 究竟做了些什么呢？它定义了一个要扩展的表达式类型的数据成员；一些
Proto 所需的嵌套 typedef；重载 `operator=`, `operator[]`
+和 `operator()` 以构建表达式模板；以及一个嵌套的 `result<>` 模板用于计算
`operator()` 的返回类型。不过在这个例子中，
+并不需要 `operator()` 重载和 `result<>` 模板，因为我们在 `calculator<>` 类
型中定义了我们自己的 `operator()`。
+Proto 提供了其它的宏，以便更好地控制哪些成员函数要定义。我们可以如下改进我
们的 `calculator<>` 类型：
// The calculator<> expression wrapper makes expressions
// function objects.
+ // calculator<> 表达式包装器把表达式变为函数对象。
template< typename Expr >
struct calculator
{
// Use BOOST_PROTO_BASIC_EXTENDS() instead of proto::extends<> to
// make this type a Proto expression extension:
+ // 使用 BOOST_PROTO_EXTENDS() 代替 proto::extends<> 来让这个类型成
为Proto表达式扩展。
BOOST_PROTO_BASIC_EXTENDS(Expr, calculator<Expr>,
calculator_domain)
// Define operator[] to build expression templates:
+ // 定义 operator[] 来构建表达式模板：
BOOST_PROTO_EXTENDS_SUBSCRIPT()
// Define operator= to build expression templates:
+ // 定义 operator= 来构建表达式模板：
BOOST_PROTO_EXTENDS_ASSIGN()
typedef double result_type;
result_type operator()( double d1 = 0.0, double d2 = 0.0 ) const
{
- /* ... as before ... */
+ /* ... as before 如前 ... */
}
};
-Notice that we are now using _BASIC_EXTENDS_ instead of _EXTENDS_. This
just adds the data member and the nested typedefs but not any of the
overloaded operators. Those are added separately with _EXTENDS_ASSIGN_ and
_EXTENDS_SUBSCRIPT_. We are leaving out the function call operator and the
nested `result<>` template that could have been defined with Proto's
_EXTENDS_FUNCTION_ macro.
-
-In summary, here are the macros you can use to define expression
extensions, and a brief description of each.
+Notice that we are now using _BASIC_EXTENDS_ instead of _EXTENDS_. This
just adds the data member and the nested typedefs but not any of the
overloaded operators. Those are added separately with _EXTENDS_ASSIGN_ and
_EXTENDS_SUBSCRIPT_. We are leaving out the function call operator and the
nested `result<>` template that could have been defined with Proto's
_EXTENDS_FUNCTION_ macro.\n
+注意，现在我们用 _BASIC_EXTENDS_ 来替代 _EXTENDS_。它只增加数据成员和嵌套
typedefs 而不重载任何操作符。
+操作符是通过 _EXTENDS_ASSIGN_ 和 _EXTENDS_SUBSCRIPT_ 单独添加的。我们省去了
函数调用操作符和嵌套的 `result<>` 模板，
+它们可以用 Proto 的 _EXTENDS_FUNCTION_ 宏来定义。
+
+In summary, here are the macros you can use to define expression
extensions, and a brief description of each.\n
+总之，以下是你可以用来定义表达式扩展的宏，以及各个宏的简要说明。
[def __expression__ [~expression]]
[def __extension__ [~extension]]
@@ -428,36 +563,43 @@
[def __extends__ [macroref BOOST_PROTO_EXTENDS]]
[def __basic_extends__ [macroref BOOST_PROTO_BASIC_EXTENDS]]
-[table Expression Extension Macros
- [[Macro]
- [Purpose]]
+[table Expression Extension Macros 表达式扩展宏
+ [[Macro 宏]
+ [Purpose 用途]]
[[``__basic_extends__(
__expression__
, __extension__
, __domain__
)``]
- [Defines a data member of type `__expression__` and some nested typedefs
that Proto requires.]]
+ [Defines a data member of type `__expression__` and some nested typedefs
that Proto requires.\n
+ 定义一个类型为 `__expression__` 的数据成员以及 Proto 所需的一些嵌套
typedefs。]]
[[_EXTENDS_ASSIGN_]
- [Defines `operator=`. Only valid when preceded by _BASIC_EXTENDS_.]]
+ [Defines `operator=`. Only valid when preceded by _BASIC_EXTENDS_.\n
+ 定义 `operator=`。仅当在 _BASIC_EXTENDS_ 之后有效。]]
[[_EXTENDS_SUBSCRIPT_]
- [Defines `operator[]`. Only valid when preceded by _BASIC_EXTENDS_.]]
+ [Defines `operator[]`. Only valid when preceded by _BASIC_EXTENDS_.\n
+ 定义 `operator[]`。仅当在 _BASIC_EXTENDS_ 之后有效。]]
[[_EXTENDS_FUNCTION_]
- [Defines `operator()` and a nested `result<>` template for return type
calculation. Only valid when preceded by _BASIC_EXTENDS_.]]
+ [Defines `operator()` and a nested `result<>` template for return type
calculation. Only valid when preceded by _BASIC_EXTENDS_.\n
+ 定义 `operator()` 和嵌套的 `result<>` 模板用于返回类型计算。仅当在
_BASIC_EXTENDS_ 之后有效。]]
[[``__extends__(
__expression__
, __extension__
, __domain__
)``]
- [Equivalent to:``
+ [Equivalent to:\n
+ 相当于：``
__basic_extends__(__expression__, __extension__, __domain__)
_EXTENDS_ASSIGN_
_EXTENDS_SUBSCRIPT_
_EXTENDS_FUNCTION_``]]
]
-[warning [*Argument-Dependent Lookup and _EXTENDS_]
-
-Proto's operator overloads are defined in the `boost::proto` namespace and
are found by argument-dependent lookup (ADL). This usually just works
because expressions are made up of types that live in the `boost::proto`
namespace. However, sometimes when you use _EXTENDS_ that is not the case.
Consider:
+[warning [*Argument-Dependent Lookup and _EXTENDS_ 实参依赖查找ADL与
_EXTENDS_]
+
+Proto's operator overloads are defined in the `boost::proto` namespace and
are found by argument-dependent lookup (ADL). This usually just works
because expressions are made up of types that live in the `boost::proto`
namespace. However, sometimes when you use _EXTENDS_ that is not the case.
Consider:\n
+Proto的操作符重载是定义在 `boost::proto` 名字空间中的，要通过ADL来查找。通
常这没问题，因为表达式是由 `boost::proto`
+名字空间中的类型所组成的。但是，有时当你使用 _EXTENDS_ 时，情况就不是这样
了。考虑：
`` template<class T>
struct my_complex
@@ -473,13 +615,17 @@
{
my_complex<int> c0, c1;
- c0 + c1; // ERROR: operator+ not found
+ c0 + c1; // ERROR: operator+ not found 错误：operator+未被找到
}
``
-The problem has to do with how argument-dependent lookup works. The type
`my_complex<int>` is not associated in any way with the `boost::proto`
namespace, so the operators defined there are not considered. (Had we
inherited from _extends_ instead of used _EXTENDS_, we would have avoided
the problem because inheriting from a type in `boost::proto` namespace is
enough to get ADL to kick in.)
-
-So what can we do? By adding an extra dummy template parameter that
defaults to a type in the `boost::proto` namespace, we can trick ADL into
finding the right operator overloads. The solution looks like this:
+The problem has to do with how argument-dependent lookup works. The type
`my_complex<int>` is not associated in any way with the `boost::proto`
namespace, so the operators defined there are not considered. (Had we
inherited from _extends_ instead of used _EXTENDS_, we would have avoided
the problem because inheriting from a type in `boost::proto` namespace is
enough to get ADL to kick in.)\n
+这个问题必须了解ADL是如何工作的。类型 `my_complex<int>` 与 `boost::proto`
名字空间没有任何关联，所以定义在那里的操作符运算不会被考虑。
+(如果我们从 _extends_ 而不是 _EXTENDS_ 派生，则可以避免这个问题，因为派生自
一个位于 `boost::proto` 名字空间的类型，足以让ADL找到它)。
+
+So what can we do? By adding an extra dummy template parameter that
defaults to a type in the `boost::proto` namespace, we can trick ADL into
finding the right operator overloads. The solution looks like this:\n
+那么我们可以做什么呢？通过增加一个额外的哑模板参数，该参数缺省为某个位于
`boost::proto` 名字空间的类型，
+我们就可以令ADL找到正确的操作符重载。这个办法就象这样：
`` template<class T, class Dummy = proto::is_proto_expr>
struct my_complex
@@ -495,62 +641,85 @@
{
my_complex<int> c0, c1;
- c0 + c1; // OK, operator+ found now!
+ c0 + c1; // OK, operator+ found now! 好的，现在可以找到
operator+了！
}
``
-The type [classref boost::proto::is_proto_expr `proto::is_proto_expr`] is
nothing but an empty struct, but by making it a template parameter we make
`boost::proto` an associated namespace of `my_complex<int>`. Now ADL can
successfully find Proto's operator overloads.
+The type [classref boost::proto::is_proto_expr `proto::is_proto_expr`] is
nothing but an empty struct, but by making it a template parameter we make
`boost::proto` an associated namespace of `my_complex<int>`. Now ADL can
successfully find Proto's operator overloads.\n
+类型 [classref boost::proto::is_proto_expr `proto::is_proto_expr`] 只是一个
空的结构，但通过将它作为一个模板参数，我们可以令
+`boost::proto` 名字空间与 `my_complex<int>` 联系起来。现在ADL就可以成功地找
到Proto的操作符重载了。
]
[endsect]
[/============================]
-[section Expression Generators]
+[section Expression Generators 表达式生成器]
[/============================]
-The last thing that remains to be done is to tell Proto that it needs to
wrap all of our calculator expressions in our `calculator<>` wrapper. We
have already wrapped the placeholders, but we want /all/ expressions that
involve the calculator placeholders to be calculators. We can do that by
specifying an expression generator when we define our `calculator_domain`,
as follows:
+The last thing that remains to be done is to tell Proto that it needs to
wrap all of our calculator expressions in our `calculator<>` wrapper. We
have already wrapped the placeholders, but we want /all/ expressions that
involve the calculator placeholders to be calculators. We can do that by
specifying an expression generator when we define our `calculator_domain`,
as follows:\n
+最后剩下要做的一件事就是，告知 Proto 它必须将我们所有的计算器表达式包入
`calculator<>` 包装器。我们已经包装了占位符，
+但是我们想要包含了这个计算器占位符的/所有/表达式都是计算器。我们可以通过在
定义我们的 `calculator_domain`
+时指定一个表达式生成器来实现这一点，如下：
// Define the calculator_domain we forward-declared above.
// Specify that all expression in this domain should be wrapped
// in the calculator<> expression wrapper.
+ // 定义我们先前已声明的 calculator_domain。指定该领域内的所有表达式都
+ // 要被包入 calculator<> 表达式包装器中。
struct calculator_domain
: proto::domain< proto::generator< calculator > >
{};
-The first template parameter to `proto::domain<>` is the
generator. "Generator" is just a fancy name for a function object that
accepts an expression and does something to it. `proto::generator<>` is a
very simple one --- it wraps an expression in the wrapper you specify.
`proto::domain<>` inherits from its generator parameter, so all domains are
themselves function objects.
-
-If we used _EXTENDS_ to keep our expression extension type POD, then we
need to use `proto::pod_generator<>` instead of `proto::generator<>`, as
follows:
+The first template parameter to `proto::domain<>` is the
generator. "Generator" is just a fancy name for a function object that
accepts an expression and does something to it. `proto::generator<>` is a
very simple one --- it wraps an expression in the wrapper you specify.
`proto::domain<>` inherits from its generator parameter, so all domains are
themselves function objects.\n
+传给 `proto::domain<>` 的第一个模板参数是生成器。"生成器" 是一个函数对象的
特别名字，这个函数对象接受一个表达式并对它做一些事情。
+`proto::generator<>` 是一个非常简单的生成器 --- 它把一个表达式包入你指定的
某个包装器。`proto::domain<>` 派生自它的生成器参数，
+因此所有领域本身都是函数对象。
+
+If we used _EXTENDS_ to keep our expression extension type POD, then we
need to use `proto::pod_generator<>` instead of `proto::generator<>`, as
follows:\n
+如果我们使用 _EXTENDS_ 来让我们的表达式扩展类型保持为 POD，则我们需要用
`proto::pod_generator<>` 代替 `proto::generator<>`，如下：
// If calculator<> uses BOOST_PROTO_EXTENDS() instead of
// use proto::extends<>, use proto::pod_generator<> instead
// of proto::generator<>.
+ // 如果 calculator<> 使用 BOOST_PROTO_EXTENDS() 代替 proto::extends()，
+ // 则使用 proto::pod_generator<> 代替 proto::generator<>。
struct calculator_domain
: proto::domain< proto::pod_generator< calculator > >
{};
[def __Domain__ [~Domain]]
-After Proto has calculated a new expression type, it checks the domains of
the child expressions. They must match. Assuming they do, Proto creates
the new expression and passes it to `__Domain__::operator()` for any
additional processing. If we don't specify a generator, the new expression
gets passed through unchanged. But since we've specified a generator
above, `calculator_domain::operator()` returns `calculator<>` objects.
-
-Now we can use calculator expressions as function objects to STL
algorithms, as follows:
+After Proto has calculated a new expression type, it checks the domains of
the child expressions. They must match. Assuming they do, Proto creates
the new expression and passes it to `__Domain__::operator()` for any
additional processing. If we don't specify a generator, the new expression
gets passed through unchanged. But since we've specified a generator
above, `calculator_domain::operator()` returns `calculator<>` objects.\n
+在 Proto 计算出一个新的表达式类型后，它要检查其子表达式的领域。它们必须相互
匹配。如果确实如此，则 Proto 创建新的表达式并将它传递给
+`__Domain__::operator()` 进行其它处理。如果我们不指定生成器，则新的表达式将
被原样传递。不过由于我们指定了上面的生成器，
+所以 `calculator_domain::operator()` 将返回 `calculator<>` 对象。
+
+Now we can use calculator expressions as function objects to STL
algorithms, as follows:\n
+现在我们可以把计算器表达式作为函数对象用于STL算法了，如下：
double data[] = {1., 2., 3., 4.};
// Use the calculator DSEL to square each element ... WORKS! :-)
+ // 使用计算器DSEL将每个元素求平方 ... 可用！:-)
std::transform( data, data + 4, data, _1 * _1 );
[endsect]
[/==========================================================]
-[section:inhibiting_overloads Controlling Operator Overloads]
+[section:inhibiting_overloads Controlling Operator Overloads 控制操作符重载
]
[/==========================================================]
By default, Proto defines every possible operator overload for Protofied
-expressions. This makes it simple to bang together a DSEL. In some cases,
however, the presence of Proto's promiscuous overloads can lead to
confusion or worse. When that happens, you'll have to disable some of
Proto's overloaded operators. That is done by defining the grammar for your
domain and specifying it as the second parameter of the _domain_ template.
-
-In the [link boost_proto.users_guide.getting_started.hello_calculator
Hello Calculator] section, we saw an example of a Proto grammar, which is
repeated here:
+expressions. This makes it simple to bang together a DSEL. In some cases,
however, the presence of Proto's promiscuous overloads can lead to
confusion or worse. When that happens, you'll have to disable some of
Proto's overloaded operators. That is done by defining the grammar for your
domain and specifying it as the second parameter of the _domain_ template.\n
+缺省情况下，Proto 为Proto化的表达式定义了每一个可能的操作符重载。这样可以简
化 bang together a DSEL。但是，在某些情况下，
+Proto 的混杂重载可能导致混乱或更糟的结果。这时，你必须禁止 Proto 重载某些操
作符。实现的方法是，
+为你的领域定义语法并将该语法指定为 _domain_ 模板的第二个参数。
+
+In the [link boost_proto.users_guide.getting_started.hello_calculator
Hello Calculator] section, we saw an example of a Proto grammar, which is
repeated here:\n
+在 [link boost_proto.users_guide.getting_started.hello_calculator Hello
Calculator] 一节中，我们已看过一个 Proto 语法的例子，重复如下：
// Define the grammar of calculator expressions
+ // 定义计算器表达式的语法
struct calculator_grammar
: proto::or_<
proto::plus< calculator_grammar, calculator_grammar >
@@ -561,61 +730,81 @@
>
{};
-We'll have much more to say about grammars in subsequent sections, but for
now, we'll just say that the `calculator_grammar` struct describes a subset
of all expression types -- the subset that comprise valid calculator
expressions. We would like to prohibit Proto from creating a calculator
expression that does not conform to this grammar. We do that by changing
the definition of the `calculator_domain` struct.
+We'll have much more to say about grammars in subsequent sections, but for
now, we'll just say that the `calculator_grammar` struct describes a subset
of all expression types -- the subset that comprise valid calculator
expressions. We would like to prohibit Proto from creating a calculator
expression that does not conform to this grammar. We do that by changing
the definition of the `calculator_domain` struct.\n
+在后续章节中，我们将会讲述关于语法的更多内容，不过现在，我们只讲一下
`calculator_grammar` 结构，它描述了所有表达式类型的一个子集 --
+这个子集组成了有效的计算器表达式。我们要禁止 Proto 创建一个不符合该语法的计
算器表达式。我们通过修改 `calculator_domain`
+结构的定义来实现这一点。
[def __calculator_grammar__ [*calculator_grammar]]
// Define the calculator_domain. Expressions in the calculator
// domain are wrapped in the calculator<> wrapper, and they must
// conform to the calculator_grammar:
+ // 定义 calculator_domain。计算器领域中的表达式要被包入 calculator<> 包
装器，
+ // 且必须符合 calculator_grammar：
struct calculator_domain
: proto::domain< proto::generator< calculator >,
__calculator_grammar__ >
{};
-The only new addition is `calculator_grammar` as the second template
parameter to the _domain_ template. That has the effect of disabling any of
Proto's operator overloads that would create an invalid calculator
expression.
-
-Another common use for this feature would be to disable Proto's unary
`operator&` overload. It may be surprising for users of your DSEL that they
cannot take the address of their expressions! You can very easily disable
Proto's unary `operator&` overload for your domain with a very simple
grammar, as below:
+The only new addition is `calculator_grammar` as the second template
parameter to the _domain_ template. That has the effect of disabling any of
Proto's operator overloads that would create an invalid calculator
expression.\n
+新增的部分是把 `calculator_grammar` 作为第二个模板参数传给 _domain_ 模板。
其结果是禁止任何会创建无效计算器表达式的 Proto 操作符重载。
+
+Another common use for this feature would be to disable Proto's unary
`operator&` overload. It may be surprising for users of your DSEL that they
cannot take the address of their expressions! You can very easily disable
Proto's unary `operator&` overload for your domain with a very simple
grammar, as below:\n
+这一特性的另外一个常见用途是，禁止 Proto 的单参数 `operator&` 重载。可能会
令你的DSEL用户意外的是，他们不能获得他们的表达式的地址！
+你可以用非常简单的语法很容易地为你的领域禁止掉 Proto 的单参数 `operator&`
重载，如下：
// For expressions in my_domain, disable Proto's
// unary address-of operator.
+ // 对于 my_domain 中的表达式，禁止 Proto 的单参数求址操作符。
struct my_domain
: proto::domain<
proto::generator< my_wrapper >
// A simple grammar that matches any expression that
// is not a unary address-of expression.
+ // 一个简单的语法，匹配所有不是单参数求址表达式的表达式。
, proto::not_< proto::address_of< _ > >
>
{};
-The type `proto::not_< proto::address_of< _ > >` is a very simple grammar
that matches all expressions except unary address-of expressions. In the
section describing Proto's intermediate form, we'll have much more to say
about grammars.
+The type `proto::not_< proto::address_of< _ > >` is a very simple grammar
that matches all expressions except unary address-of expressions. In the
section describing Proto's intermediate form, we'll have much more to say
about grammars.\n
+类型 `proto::not_< proto::address_of< _ > >` 是一个非常简单的语法，它匹配除
了单参数求址表达式以外的所有表达式。
+在讲述 Proto 中间格式的一节中，我们将讲述关于语法的更多内容。
[endsect]
[endsect]
-[section:define_operators Adapting Existing Types to Proto]
-
-The preceding discussions of defining Proto front ends have all made a big
assumption: that you have the luxury of defining everything from scratch.
What happens if you have existing types, say a matrix type and a vector
type, that you would like to treat as if they were Proto terminals? Proto
usually trades only in its own expression types, but with
_DEFINE_OPERATORS_, it can accomodate your custom terminal types, too.
-
-Let's say, for instance, that you have the following types and that you
can't modify then to make them ["native] Proto terminal types.
+[section:define_operators Adapting Existing Types to Proto 将已有类型适配至
Proto]
+
+The preceding discussions of defining Proto front ends have all made a big
assumption: that you have the luxury of defining everything from scratch.
What happens if you have existing types, say a matrix type and a vector
type, that you would like to treat as if they were Proto terminals? Proto
usually trades only in its own expression types, but with
_DEFINE_OPERATORS_, it can accomodate your custom terminal types, too. \n
+前面对于定义Proto前端的讨论，有一个很大的假定：你从零开始定义所有的东西。如
果你已经有了一些类型，比如说某个矩阵或向量的类型，
+你想将它们视为Proto终结符，要怎么办呢？通常Proto只处理它自己的表达式类
型，不过通过 _DEFINE_OPERATORS_, 就可以容纳你的定制类型。
+
+Let's say, for instance, that you have the following types and that you
can't modify then to make them ["native] Proto terminal types.\n
+我们来看一下，例如你有以下类型且不能修改以令它们成为["原生]的Proto终结符类
型。
namespace math
{
- // A matrix type ...
+ // A matrix type ... 一个矩阵类型
struct matrix { /*...*/ };
- // A vector type ...
+ // A vector type ... 一个向量类型
struct vector { /*...*/ };
}
-You can non-intrusively make objects of these types Proto terminals by
defining the proper operator overloads using _DEFINE_OPERATORS_. The basic
procedure is as follows:
-
-# Define a trait that returns true for your types and false for all others.
+You can non-intrusively make objects of these types Proto terminals by
defining the proper operator overloads using _DEFINE_OPERATORS_. The basic
procedure is as follows:\n
+通过用 _DEFINE_OPERATORS_ 定义正确的操作符重载，你可以非介入式地令这些类型
的对象成为Proto终结符。基本的过程如下：
+
+# Define a trait that returns true for your types and false for all
others.\n
+ 定义一个trait，对你的类型返回true而对其它类型返回false。
# Reopen the namespace of your types and use _DEFINE_OPERATORS_ to define
a set of
operator overloads, passing the name of the trait as the first macro
parameter,
- and the name of a Proto domain (e.g., _default_domain_) as the second.
-
-The following code demonstrates how it works.
+ and the name of a Proto domain (e.g., _default_domain_) as the second.\n
+ 重新打开你的类型所在的名字空间，并用 _DEFINE_OPERATORS_ 来定义一组操作符
重载，
+ 传入这个trait的名字作为第一个宏参数，以及Proto域名(如 _default_domain_)作
为第二个参数。
+
+The following code demonstrates how it works.\n
+以下代码示范了如何实现。
namespace math
{
@@ -625,12 +814,14 @@
{};
// OK, "matrix" is a custom terminal type
+ // 好的，"matrix"是一个定制的终结符类型
template<>
struct is_terminal<matrix>
: mpl::true_
{};
// OK, "vector" is a custom terminal type
+ // 好的，"vector"是一个定制的终结符类型
template<>
struct is_terminal<vector>
: mpl::true_
@@ -639,44 +830,56 @@
// Define all the operator overloads to construct Proto
// expression templates, treating "matrix" and "vector"
// objects as if they were Proto terminals.
+ // 定义所有操作符重载为构造Proto表达式模板，将"matrix"和
+ // "vector"对象视为Proto终结符。
BOOST_PROTO_DEFINE_OPERATORS(is_terminal, proto::default_domain)
}
-The invocation of the _DEFINE_OPERATORS_ macro defines a complete set of
operator overloads that treat `matrix` and `vector` objects as if they were
Proto terminals. And since the operators are defined in the same namespace
as the `matrix` and `vector` types, the operators will be found by
argument-dependent lookup. With the code above, we can now construct
expression templates with matrices and vectors, as shown below.
+The invocation of the _DEFINE_OPERATORS_ macro defines a complete set of
operator overloads that treat `matrix` and `vector` objects as if they were
Proto terminals. And since the operators are defined in the same namespace
as the `matrix` and `vector` types, the operators will be found by
argument-dependent lookup. With the code above, we can now construct
expression templates with matrices and vectors, as shown below.\n
+_DEFINE_OPERATORS_ 宏的调用定义了一组完整的操作符重载，将 `matrix` 和
`vector` 对象视作为Proto终结符。而且由于这些操作符都是定义在与
+`matrix` 和 `vector` 类型同一个的名字空间，所以这些操作符可以被ADL所找到。
通过以上代码，我们就可以用矩阵和向量来构建表达式模板了，
+如下所示。
math::matrix m1;
math::vector v1;
proto::literal<int> i(0);
- m1 * 1; // custom terminal and literals are OK
- m1 * i; // custom terminal and Proto expressions are OK
- m1 * v1; // two custom terminals are OK, too.
+ m1 * 1; // custom terminal and literals are OK 定制的终结符和字面
值，可以
+ m1 * i; // custom terminal and Proto expressions are OK 定制的终结符和
Proto表达式，可以
+ m1 * v1; // two custom terminals are OK, too. 两个定制的终结符，也可以
[endsect]
[/=======================================================================]
-[section:code_repetition Generating Repetitive Code with the Preprocessor]
+[section:code_repetition Generating Repetitive Code with the Preprocessor
用预处理器生成重复代码]
[/=======================================================================]
-Sometimes as a DSEL designer, to make the lives of your users easy, you
have to make your own life hard. Giving your users natural and flexible
syntax often involves writing large numbers of repetitive function
overloads. It can be enough to give you repetitive stress injury! Before
you hurt yourself, check out the macros Proto provides for automating many
repetitive code-generation chores.
-
-Imagine that we are writing a lambda DSEL, and we would like to enable
syntax for constructing temporary objects of any type using the following
syntax:
+Sometimes as a DSEL designer, to make the lives of your users easy, you
have to make your own life hard. Giving your users natural and flexible
syntax often involves writing large numbers of repetitive function
overloads. It can be enough to give you repetitive stress injury! Before
you hurt yourself, check out the macros Proto provides for automating many
repetitive code-generation chores.\n
+有时候，作为一个DSEL设计者，为了使你的用户更方便，你必须辛苦一点。为了给予
用户自然而灵活的语法，通常需要编写大量重复的函数重载。
+这会给你足够的重复性压力伤害！在你伤害自己之前，看看Proto提供了哪些宏来自动
完成重复代码的生成。
+
+Imagine that we are writing a lambda DSEL, and we would like to enable
syntax for constructing temporary objects of any type using the following
syntax:\n
+想象我们正在编写一个lambda DSEL，我们希望能够用以下语法构建任意类型的临时对
象：
// A lambda expression that takes two arguments and
// uses them to construct a temporary std::complex<>
+ // 一个带两个参数的lambda表达式，用它们来构建一个临时的 std::complex<>
construct< std::complex<int> >( _1, _2 )
-For the sake of the discussion, imagine that we already have a function
object template `construct_impl<>` that accepts arguments and constructs
new objects from them. We would want the above lambda expression to be
equivalent to the following:
+For the sake of the discussion, imagine that we already have a function
object template `construct_impl<>` that accepts arguments and constructs
new objects from them. We would want the above lambda expression to be
equivalent to the following:\n
+为便于讨论，假设我们已经有一个函数对象模板 `construct_impl<>`，它接受多个参
数并从中构建新对象。我们希望以上lambda表达式等同于：
// The above lambda expression should be roughly equivalent
// to the following:
+ // 以上lambda表达式大致相当于：
proto::make_expr<proto::tag::function>(
- construct_impl<std::complex<int> >() // The function to invoke
lazily
- , boost::ref(_1) // The first argument to the
function
- , boost::ref(_2) // The second argument to the
function
+ construct_impl<std::complex<int> >() // The function to invoke
lazily 延迟调用的函数
+ , boost::ref(_1) // The first argument to the
function 传给函数的第一个参数
+ , boost::ref(_2) // The second argument to the
function 传给函数的第二个参数
);
-We can define our `construct()` function template as follows:
+We can define our `construct()` function template as follows:\n
+我们可以如下定义我们自己的 `construct()` 函数模板：
template<typename T, typename A0, typename A1>
typename proto::result_of::make_expr<
@@ -694,9 +897,12 @@
);
}
-This works for two arguments, but we would like it to work for any number
of arguments, up to (_MAX_ARITY_ - 1). (Why "- 1"? Because one child is
taken up by the `construct_impl<T>()` terminal leaving room for only
(_MAX_ARITY_ - 1) other children.)
-
-For cases like this, Proto provides the _REPEAT_ and _REPEAT_FROM_TO_
macros. To use it, we turn the function definition above into a macro as
follows:
+This works for two arguments, but we would like it to work for any number
of arguments, up to (_MAX_ARITY_ - 1). (Why "- 1"? Because one child is
taken up by the `construct_impl<T>()` terminal leaving room for only
(_MAX_ARITY_ - 1) other children.)\n
+它用于两个参数的情况，但我们也希望它可以用于最多 (_MAX_ARITY_ - 1) 个参数的
情况。(为什么要 "- 1"？因为 `construct_impl<T>()`
+已占用了一个子节点，只剩下 (_MAX_ARITY_ - 1) 个空间给其它子节点)。
+
***The diff for this file has been truncated for email.***
=======================================
--- /trunk/libs/proto/doc/getting_started.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/getting_started.qbk Sun Jan 17 23:11:16 2010
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:getting_started Getting Started]
+[section:getting_started Getting Started 入门]
[include installation.qbk]
=======================================
--- /trunk/libs/proto/doc/glossary.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/glossary.qbk Sun Jan 17 23:11:16 2010
@@ -6,7 +6,7 @@
/]
[/===============]
-[section Glossary]
+[section:glossary Glossary 术语]
[/===============]
[def _T_ [~T]]
@@ -14,78 +14,108 @@
[template anchor[x] '''<anchor
id="boost_proto.users_guide.glossary.'''[x]'''" />''']
[variablelist
- [ [ [anchor callable_transform] callable transform]
+ [ [ [anchor callable_transform] callable transform 可调用变换]
[A transform of the form `R(A0,A1,...)` (i.e., a function type) where
`proto::is_callable<R>::value` is `true`. `R` is treated as a
polymorphic
function object and the arguments are treated as transforms that
yield the
- arguments to the function object.] ]
- [ [ [anchor context] context]
+ arguments to the function object.\n
+ 一种形如 `R(A0,A1,...)` (即一个函数类型)的变换，其中
`proto::is_callable<R>::value` 为 `true`。
+ `R` 被视为一个多态函数对象，其它参数则被视为产生该函数对象各个实参的
变换。] ]
+ [ [ [anchor context] context 上下文]
[In Proto, the term /context/ refers to an object that can be
passed, along
with an expression to evaluate, to the `proto::eval()` function.
The context
determines how the expression is evaluated. All context structs
define a
nested `eval<>` template that, when instantiated with a node tag
type (e.g.,
`proto::tag::plus`), is a binary polymorphic function object that
accepts an
expression of that type and the context object. In this way,
contexts
- associate behaviors with expression nodes.] ]
- [ [ [anchor domain] domain]
+ associate behaviors with expression nodes.\n
+ 在Proto中，术语/上下文/是指这样一个对象，它可以和一个要求值的表达式
一起，被传递给 `proto::eval()` 函数。
+ 上下文决定了表达式如何被求值。所有上下文结构都定义了一个嵌套的
`eval<>` 模板，当用一个节点标签类型
+ (如 `proto::tag::plus`)对该模板进行实例化时，它是一个二元多态函数对
象。接受一个相关类型的表达式以及该上下文对象。
+ 上下文正是以此种方式将行为与表达式节点关联起来。] ]
+ [ [ [anchor domain] domain 领域]
[In Proto, the term /domain/ refers to a type that associates
expressions
within that domain with a /generator/ for that domain and
optionally a
/grammar/ for the domain. Domains are used primarily to imbue
expressions
within that domain with additional members and to restrict Proto's
operator
overloads such that expressions not conforming to the domain's
grammar are
never created. Domains are empty structs that inherit from
- `proto::domain<>`.]]
- [ [ [anchor dsel] domain-specific embedded language]
+ `proto::domain<>`.\n
+ 在Proto中，术语/领域/是指这样一个类型，它以该领域的一个/生成器/以及
一个可选的该领域/语法/，将表达式关联至该领域内。
+ 领域主要用于通过为表达式增加某些成员，以及限制某些Proto的操作符重载
以令不符合该领域语法的表达式不可创建，
+ 来将表达式注入到领域中。领域是继承自 `proto::domain<>` 的空结构。]]
+ [ [ [anchor dsel] domain-specific embedded language 领域专用嵌入式语言]
[A domain-specific language implemented as a library. The language
in which
the library is written is called the "host" language, and the
language
- implemented by the library is called the "embedded" language.]]
- [ [ [anchor dsl] domain-specific language]
+ implemented by the library is called the "embedded" language.\n
+ 一种领域专用语言被实现为一个库。编写该库的语言称为"宿主"语言，而该库
所实现的语言则称为"嵌入"语言。]]
+ [ [ [anchor dsl] domain-specific language 领域专用语言]
[A programming language that targets a particular problem space by
providing
programming idioms, abstractions and constructs that match the
constructs
- within that problem space.]]
- [ [ [anchor expression] expression]
+ within that problem space.\n
+ 针对特定问题空间的一种编程语言，提供编程惯用法、抽象和结构，与问题空
间中的结构相匹配。]]
+ [ [ [anchor expression] expression 表达式]
[In Proto, an /expression/ is a heterogeneous tree where each node
is either
an instantiation of `boost::proto::expr<>` or some type that is an
extension
(via `boost::proto::extends<>` or `BOOST_PROTO_EXTENDS()`) of such
an
- instantiation.]]
- [ [ [anchor expression_template] expression template]
+ instantiation.\n
+ 在Proto中，一个/表达式/是一棵异构树，其中每个节点，要么是
`boost::proto::expr<>` 的一个实例，
+ 要么是此种实例的一个扩展类型(通过 `boost::proto::extends<>` 或
`BOOST_PROTO_EXTENDS()` 扩展)。]]
+ [ [ [anchor expression_template] expression template 表达式模板]
[A C++ technique using templates and operator overloading to cause
expressions to build trees that represent the expression for lazy
evaluation
later, rather than evaluating the expression eagerly. Some C++
libraries use
- expression templates to build domain-specific embedded languages.]]
- [ [ [anchor generator] generator]
+ expression templates to build domain-specific embedded languages.\n
+ 一种C++技巧，使用模板和操作符重载来使得表达式不会引起立即求值，而是
构造出一棵代表了将该表达式延迟求值的树。
+ 有些C++库使用表达式模板来构建领域专用嵌入式语言。]]
+ [ [ [anchor generator] generator 生成器]
[In Proto, a /generator/ is a unary polymorphic function object that
you
specify when defining a /domain/. After constructing a new
expression, Proto
passes the expression to your domain's generator for further
processing.
Often, the generator wraps the expression in an extension wrapper
that adds
- additional members to it.]]
- [ [ [anchor grammar] grammar]
+ additional members to it.\n
+ 在Proto中，/生成器/是一个你在定义/领域/时要指定的单参多态函数对象。
在构造出一个新的表达式后，
+ Proto将该表达式传递给你的领域的生成器进行下一步处理。通常，生成器将
表达式包装进一个扩展包装器，
+ 为它增加新的成员。]]
+ [ [ [anchor grammar] grammar 语法]
[In Proto, a /grammar/ is a type that describes a subset of Proto
expression
types. Expressions in a domain must conform to that domain's
grammar. The
`proto::matches<>` metafunction evaluates whether an expression
type matches
a grammar. Grammars are either primitives such as `proto::_`,
composites
such as `proto::plus<>`, control structures such as `proto::or_<>`,
or some
- type derived from a grammar.]]
- [ [ [anchor object_transform] object transform]
+ type derived from a grammar.\n
+ 在Proto中，/语法/是一个类型，它描述了Proto表达式类型的一个子集。一个
领域中的表达式必须符合该领域的语法。
+ `proto::matches<>` 元函数用于评估一个表达式类型是否匹配某个语法。语
法或者是一个象 `proto::_` 这样的原词，
+ 或是象 `proto::plus<>` 这样的组合，或是象 `proto::or_<>` 这样的控制
结构，或是派生自某个语法的其它类型。]]
+ [ [ [anchor object_transform] object transform 对象变换]
[A transform of the form `R(A0,A1,...)` (i.e., a function type) where
`proto::is_callable<R>::value` is `false`. `R` is treated as the
type of an
object to construct and the arguments are treated as transforms
that yield
- the parameters to the constructor.]]
- [ [ [anchor polymorphic_function_object] polymorphic function object]
+ the parameters to the constructor.\n
+ 一个形如 `R(A0,A1,...)` (即一个函数类型)的变换，其中
`proto::is_callable<R>::value` 为 `false`。
+ `R` 被视为一个要构造的对象的类型，其它参数被视为生成该构造函数各个参
数的变换。]]
+ [ [ [anchor polymorphic_function_object] polymorphic function object 多态
函数对象]
[An instance of a class type with an overloaded function call
operator and a
nested `result_type` typedef or `result<>` template for calculating
the
- return type of the function call operator.]]
- [ [ [anchor primitive_transform] primitive transform]
+ return type of the function call operator.\n
+ 一个带有重载的函数调用操作符以及内嵌的 `result_type` typedef 或用于
计算该函数调用操作符的返回类型的
+ `result<>` 模板的类类型的实例。]]
+ [ [ [anchor primitive_transform] primitive transform 基本变换]
[A type that defines a kind of polymorphic function object that
takes three
arguments: expression, state, and data. Primitive transforms can be
used to
- compose callable transforms and object transforms.]]
- [ [ [anchor transform] transform]
+ compose callable transforms and object transforms.\n
+ 一个类型，定义了一种多态函数对象，该函数对象接受三个参数：表达式、状
态和数据。
+ 基本变换可以用于组成可调用变换和对象变换。]]
+ [ [ [anchor transform] transform 变换]
[Transforms are used to manipulate expression trees. They come in
three
flavors: primitive transforms, callable transforms, or object
transforms. A
transform `_T_` can be made into a ternary polymorphic function
object with
`proto::when<>`, as in `proto::when<proto::_, _T_>`. Such a
function object
accepts /expression/, /state/, and /data/ parameters, and computes
a result
- from them.]]
+ from them.\n
+ 变换用于操纵表达式树。它们有三种形式：基本变换、可调用变换或对象变
换。
+ 变换 `_T_` 可以用 `proto::when<>` 制成一个三元多态函数对象，如
`proto::when<proto::_, _T_>`。
+ 这样一个函数对象接受 /expression/, /state/, 和 /data/ 参数，并由它们
计算出结果。]]
]
[endsect]
=======================================
--- /trunk/libs/proto/doc/hello_world.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/hello_world.qbk Sun Jan 17 23:11:16 2010
@@ -10,7 +10,8 @@
[/==================]
Below is a very simple program that uses Proto to build an expression
template
-and then execute it.
+and then execute it.\n
+以下是一个非常简单的程序，它使用 Proto 来构建一个表达式模板，然后执行它。
#include <iostream>
#include <boost/proto/proto.hpp>
@@ -32,20 +33,25 @@
return 0;
}
-This program outputs the following:
+This program outputs the following:\n
+该程序的输出如下：
[pre
hello, world
]
This program builds an object representing the output operation and passes
-it to an `evaluate()` function, which then executes it.
+it to an `evaluate()` function, which then executes it.\n
+这个程序构建了一个表示输出操作的对象，并将它传递给一个 `evaluate()` 函
数，后者对该操作进行执行。
The basic idea of expression templates is to overload all the operators so
that, rather than evaluating the expression immediately, they build a
tree-like
representation of the expression so that it can be evaluated later. For
each
operator in an expression, at least one operand must be Protofied in order
-for Proto's operator overloads to be found. In the expression ...
+for Proto's operator overloads to be found. In the expression ...\n
+表达式模板的基本意思是重载所有操作符，不再立即对表达式进行求值，而对该表达
式构建一个树型的表示，
+以便在晚些时候进行求值。对于表达式中的每一个操作符，必须至少要有一个操作数
是Proto化的，
+这样才可以找到 Proto 的操作符重载。在表达式 ...
cout_ << "hello" << ',' << " world"
@@ -53,7 +59,10 @@
`std::cout`. The presence of `cout_` "infects" the expression, and brings
Proto's tree-building operator overloads into consideration. Any literals
in
the expression are then Protofied by wrapping them in a Proto terminal
before
-they are combined into larger Proto expressions.
+they are combined into larger Proto expressions.\n
+... 中，Proto化的子表达式是 `cout_`，它是 `std::cout` 的Proto化产物。
`cout_` 的出现"感染"了整个表达式，
+进而带来 Proto 的操作符重载，进行表达式树的构建。在这个表达式中的任何字面值
都随后被Proto化，
+它们被包装为一个 Proto 终结符，然后被组装进更大的 Proto 表达式中。
Once Proto's operator overloads have built the expression tree, the
expression
can be lazily evaluated later by walking the tree. That is what
`proto::eval()`
@@ -61,10 +70,14 @@
customizable via a /context/ parameter. The use of _default_context_
assigns
the standard meanings to the operators in the expression. (By using a
different
context, you could give the operators in your expressions different
semantics.
-By default, Proto makes no assumptions about what operators actually
/mean/.)
+By default, Proto makes no assumptions about what operators actually
/mean/.)\n
+一旦 Proto 的操作符重载构建了这棵表达式树，这个表达式就可以在晚些时候通过遍
历来进行惰性求值。
+这正是 `proto::eval()` 所做的事情。它是一个通用的表达式树遍历求值器，其行为
可以通过一个 /上下文/ 参数来进行定制。
+_default_context_ 的使用为表达式中的操作符赋予了标准意义(通过使用不同的上下
文，
+你可以为表达式中的操作符赋予不同的语义。缺省情况下，Proto 对于操作符的实际
/意义/不作任何假设)。
[/==============================]
-[heading Proto Design Philosophy]
+[heading Proto Design Philosophy Proto的设计哲学]
[/==============================]
Before we continue, let's use the above example to illustrate an important
@@ -73,12 +86,19 @@
any particular domain or application, nor does it have any particular
meaning
or behavior on its own, until it is evaluated in a /context/. Expression
templates are really just heterogeneous trees, which might mean something
in
-one domain, and something else entirely in a different one.
+one domain, and something else entirely in a different one.\n
+在我们继续往下之前，我们用上述例子来说明 Proto 的一个非常重要的设计原则。
+在 ['hello world] 例子中所创建的表达式模板完全是通用和抽象的。
+它没有以任何方式与任何特定的问题域或应用相结合，本身也没有任何特定的含义或
行为，
+直至它在一个/上下文/中被求值。表达式模板只是一个异类树，可能在某个问题域中
具有某种意义，
+而在另一个问题域中则具有完全不同的意义。
As we'll see later, there is a way to create Proto expression trees that
are
['not] purely abstract, and that have meaning and behaviors independent of
any
context. There is also a way to control which operators are overloaded for
your
particular domain. But that is not the default behavior. We'll see later
why
-the default is often a good thing.
+the default is often a good thing.\n
+正如我们稍后将看到的，可以有方法创建['非]纯抽象的 Proto 表达式树，它具有独
立于上下文的意义和行为。
+也有方法为你的特定问题域控制对哪些操作符进行重载。不过这些不是缺省的行为。
稍后我们将看到为什么缺省值通常是好事。
[endsect]
=======================================
--- /trunk/libs/proto/doc/history.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/history.qbk Sun Jan 17 23:11:16 2010
@@ -5,59 +5,73 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:history Appendix A: History]
+[section:history Appendix A: History 附录A：历史]
[variablelist
[
[August 11, 2008]
- [Proto v4 is merged to Boost trunk with more powerful transform
protocol.]
+ [Proto v4 is merged to Boost trunk with more powerful transform
protocol.\n
+ Proto v4 合并至 Boost 主干，具有更强大的变换协议。]
]
[
[April 7, 2008]
- [Proto is accepted into Boost.]
+ [Proto is accepted into Boost.\n
+ Proto 被接受进入 Boost。]
]
[
[March 1, 2008]
- [Proto's Boost review begins.]
+ [Proto's Boost review begins.\n
+ Proto 的 Boost 评审开始。]
]
[
[January 11, 2008]
[Boost.Proto v3 brings separation of grammars and transforms and a
- "round" lambda syntax for defining transforms in-place.]
+ "round" lambda syntax for defining transforms in-place.\n
+ Boost.Proto v3 将语法和变换分离，并带有一个就地定义变换的"round"
lambda 语法。]
]
[
[April 15, 2007]
[Boost.Xpressive is ported from Proto compilers to Proto transforms.
- Support for old Proto compilers is dropped.]
+ Support for old Proto compilers is dropped.\n
+ Boost.Xpressive 从 Proto 编译器修改为 Proto 变换。不再支持旧的 Proto
编译器。]
]
[
[April 4, 2007]
- [Preliminary submission of Proto to Boost.]
+ [Preliminary submission of Proto to Boost.\n
+ 给 Boost 的 Proto 初步提交物。]
]
[
[December 11, 2006]
[The idea for transforms that decorate grammar rules is born in a
private
email discussion with Joel de Guzman and Hartmut Kaiser. The first
- transforms are committed to CVS 5 days later on December 16.]
+ transforms are committed to CVS 5 days later on December 16.\n
+ 在 Joel de Guzman 和 Hartmut Kaiser 的一封私人邮件讨论中，诞生了用变换
来装饰语法规则的想法。
+ 5天后，12月16日，第一个变换被提交到CVS上。]
]
[
[November 1, 2006]
[The idea for `proto::matches<>` and the whole grammar facility is
hatched during a discussion with Hartmut Kaiser on the spirit-devel
list.
The first version of `proto::matches<>` is checked into CVS 3 days
later.
- Message is
[@http://osdir.com/ml/parsers.spirit.devel/2006-11/msg00003.html here].]
+ Message is
[@http://osdir.com/ml/parsers.spirit.devel/2006-11/msg00003.html here].\n
+ Hartmut Kaiser 在 spirit-devel 列表上的讨论中，提出了
`proto::matches<>` 和整个语法工具的想法。
+ 3天后，`proto::matches<>` 的第一个版本签入至CVS。相关信息在
+ [@http://osdir.com/ml/parsers.spirit.devel/2006-11/msg00003.html 此处
]。]
]
[
[October 28, 2006]
[Proto is reborn, this time with a uniform expression types that are
POD.
- Announcement is
[@http://lists.boost.org/Archives/boost/2006/10/112453.php here].]
+ Announcement is
[@http://lists.boost.org/Archives/boost/2006/10/112453.php here].\n
+ Proto 重生，这次将表达式类型为统一为POD。相关声明在
[@http://lists.boost.org/Archives/boost/2006/10/112453.php 此处]。 ]
]
[
[April 20, 2005]
[Proto is born as a major refactorization of Boost.Xpressive's
meta-programming. Proto offers expression types, operator overloads
and
"compilers", an early formulation of what later became transforms.
- Announcement is
[@http://lists.boost.org/Archives/boost/2005/04/85256.php here].]
+ Announcement is
[@http://lists.boost.org/Archives/boost/2005/04/85256.php here].\n
+ Proto 作为 Boost.Xpressive 元编程的主要重构物诞生了。Proto 提供了表达
式类型、操作符重载和"编译器"--变换的早期形式。
+ 相关声明在 [@http://lists.boost.org/Archives/boost/2005/04/85256.php
此处]。]
]
]
=======================================
--- /trunk/libs/proto/doc/implementation.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/implementation.qbk Sun Jan 17 23:11:16 2010
@@ -5,26 +5,32 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:implementation Appendix C: Implementation Notes]
-
-[section:sfinae Quick-n-Dirty Type Categorization]
+[section:implementation Appendix C: Implementation Notes 附录C：实现说明]
+
+[section:sfinae Quick-n-Dirty Type Categorization 快速而难看的类型分类]
Much has already been written about dispatching on type traits using
SFINAE (Substitution Failure Is Not An Error) techniques in C++. There
is a Boost library, Boost.Enable_if, to make the technique idiomatic.
Proto dispatches on type traits extensively, but it doesn't use
`enable_if<>` very often. Rather, it dispatches based on the presence
-or absence of nested types, often typedefs for void.
+or absence of nested types, often typedefs for void.\n
+很多人都写过使用C++中的SFINAE(替换失败并非错误)技术按类型traits进行分派的代
码。
+有一个Boost库，Boost.Enable_if，使这一技术成为惯用法。Proto大量地使用了按类
型traits进行分派，
+但是它并不经常使用 `enable_if<>`。相以，它基于嵌套类型的存在与否来进行分
派，
+这个嵌套类型通常被 typedef 为 void。
Consider the implementation of `is_expr<>`. It could have been written
-as something like this:
+as something like this:\n
+想一下 `is_expr<>` 的实现。它可以写成象以下这样：
template<typename T>
struct is_expr
: is_base_and_derived<proto::some_expr_base, T>
{};
-Rather, it is implemented as this:
+Rather, it is implemented as this:\n
+更好的方法是实现为这样：
template<typename T, typename Void = void>
struct is_expr
@@ -38,29 +44,39 @@
This relies on the fact that the specialization will be preferred
if `T` has a nested `proto_is_expr_` that is a typedef for `void`.
-All Proto expression types have such a nested typedef.
+All Proto expression types have such a nested typedef.\n
+这依赖于一个事实，即如果 `T` 带有一个嵌套的 `proto_is_expr_`，它可以
typedef 为 `void`，
+则会优选模板的特化版。所有Proto表达式类型都带有这样的一个嵌套typedef。
Why does Proto do it this way? The reason is because, after running
extensive benchmarks while trying to improve compile times, I have
found that this approach compiles faster. It requires exactly one
template instantiation. The other approach requires at least 2:
`is_expr<>` and `is_base_and_derived<>`, plus whatever templates
-`is_base_and_derived<>` may instantiate.
+`is_base_and_derived<>` may instantiate.\n
+为什么Proto要以这种方法来实现呢？原因是，在进行了旨在改进编译时间的性能测试
后，
+我发现这种方式的编译更快。它只需要一个模板实例化。另外一种方法则至少需要
2个：
+`is_expr<>` 和 `is_base_and_derived<>`，而且模板 `is_base_and_derived<>` 还
可能进行其它的实例化。
[endsect]
-[section:function_arity Detecting the Arity of Function Objects]
+[section:function_arity Detecting the Arity of Function Objects 检测函数对
象的arity]
In several places, Proto needs to know whether or not a function
object `Fun` can be called with certain parameters and take a
fallback action if not. This happens in _callable_context_ and
in the _call_ transform. How does Proto know? It involves some
-tricky metaprogramming. Here's how.
+tricky metaprogramming. Here's how.\n
+Proto的多处地方需要知道一个函数对象 `Fun` 是否可以用指定的参数来调用，
+如果不行的话则需要进行回退。这在 _callable_context_ 和 _call_ 变换中都有发
生。
+Proto是如何知道的呢？这里有一些巧妙的元编程。下面来说一下。
Another way of framing the question is by trying to implement
the following `can_be_called<>` Boolean metafunction, which
checks to see if a function object `Fun` can be called with
-parameters of type `A` and `B`:
+parameters of type `A` and `B`:\n
+构思这一问题的另一个方法是，尝试实现以下 `can_be_called<>` 布尔元函数，
+它检查某个函数对象 `Fun` 是否可以用类型为 `A` 和 `B` 的参数来调用：
template<typename Fun, typename A, typename B>
struct can_be_called;
@@ -68,7 +84,9 @@
First, we define the following `dont_care` struct, which has an
implicit conversion from anything. And not just any implicit
conversion; it has a ellipsis conversion, which is the worst possible
-conversion for the purposes of overload resolution:
+conversion for the purposes of overload resolution:\n
+首先，我们定义以下 `dont_care` 结构，它带有一个自任何类型的隐式转换。
+而且不仅是任意的隐式转换；它还有一个带省略号的转换，这是在重载解析中最坏情
况下的可选转换：
struct dont_care
{
@@ -77,7 +95,9 @@
We also need some private type known only to us with an overloaded
comma operator (!), and some functions that detect the presence of
-this type and return types with different sizes, as follows:
+this type and return types with different sizes, as follows:\n
+我们还需要一些东西，只有我们自己知道的带有一个逗号操作符重载(!)的私有类型，
+一些函数用于检测该类型是否出现并返回不同大小的类型，如下：
struct private_type
{
@@ -93,7 +113,8 @@
yes_type is_private_type(private_type const &);
Next, we implement a binary function object wrapper with a very
-strange conversion operator, whose meaning will become clear later.
+strange conversion operator, whose meaning will become clear later.\n
+接着，我们实现一个二元函数包装器，它带有一个非常奇特的转换操作符，其意义稍
后就会弄清楚。
template<typename Fun>
struct funwrap2 : Fun
@@ -104,7 +125,8 @@
};
With all of these bits and pieces, we can implement `can_be_called<>` as
-follows:
+follows:\n
+有了所有这些东西，我们就可以如下实现 `can_be_called<>` 了：
template<typename Fun, typename A, typename B>
struct can_be_called
@@ -124,13 +146,19 @@
our own binary function overload, but doing it in such a way that we can
detect whether our overload was selected or not. And we rig it so that
our overload is selected if there is really no better option. What follows
-is a description of how `can_be_called<>` works.
+is a description of how `can_be_called<>` works.\n
+其中的思想是，通过增加我们自己的二元函数重载，使得 `fun(a,b)` 总是可以被编
译，不过，
+这样一来我们就可以检测到我们的重载是否被选中。而我们把它装配成只有在没有更
好的选择时，
+才选中我们的重载。以下说明 `can_be_called<>` 如何工作。
We wrap `Fun` in a type that has an implicit conversion to a pointer to
a binary function. An object `fun` of class type can be invoked as
`fun(a, b)` if it has such a conversion operator, but since it involves
a user-defined conversion operator, it is less preferred than an
-overloaded `operator()`, which requires no such conversion.
+overloaded `operator()`, which requires no such conversion.\n
+我们将 `Fun` 包入一个类型，该类型带有一个到二元函数指针的隐式转换。如果一个
类类型带有这样的一个转换操作符，
+则这个类类型的对象 `fun` 就可以用 `fun(a, b)` 来调用，不过，由于其中包含了
一次用户自定义的转换操作符，
+所以它不如一个重载的 `operator()` 优先，因为后者不需要转换。
The function pointer can accept any two arguments by virtue
of the `dont_care` type. The conversion sequence for each argument is
@@ -138,28 +166,42 @@
conversion through an ellipsis, and a user-defined conversion to
`dont_care`. In total, it means that `funwrap2<Fun>()(a, b)` will
always compile, but it will select our overload only if there really is
-no better option.
+no better option.\n
+由于 `dont_care` 类型，这个函数指针可以接受任意类型的两个参数。每个参数的转
换序列都可以保证是最坏情况下的可选转换序列：
+一个通过省略号进行的隐式转换，和一个到 `dont_care` 的用户自定义转换。总的来
说，这意味着 `funwrap2<Fun>()(a, b)` 总是可以被编译，
+不过仅当没有更好的选择时，它才会选择我们的重载。
If there is a better option --- for example if `Fun` has an overloaded
function call operator such as `void operator()(A a, B b)` --- then
`fun(a, b)` will resolve to that one instead. The question now is how
-to detect which function got picked by overload resolution.
+to detect which function got picked by overload resolution.\n
+如果有一个更好的选择 --- 例如，如果 `Fun` 带有一个重载的函数调用操作符，
+如 `void operator()(A a, B b)` --- 则 `fun(a, b)` 将被决议为那个选择。
+现在的问题是，如何通过重载决议来检测哪一个函数被选中。
Notice how `fun(a, b)` appears in `can_be_called<>`: `(fun(a, b), 0)`.
Why do we use the comma operator there? The reason is because we are
using this expression as the argument to a function. If the return type
of `fun(a, b)` is `void`, it cannot legally be used as an argument to
-a function. The comma operator sidesteps the issue.
+a function. The comma operator sidesteps the issue.\n
+留意在 `can_be_called<>` 中的 `fun(a, b)` 是如何出现的：`(fun(a, b), 0)`。
+为什么我们要用逗号操作符？原因是，我们要把这个表达式作为一个函数的参数来使
用。
+如果 `fun(a, b)` 的返回类型为 `void`，它就不能合法地作为一个函数的参数来使
用。
+逗号操作符回避了这个问题。
This should also make plain the purpose of the overloaded comma operator
in `private_type`. The return type of the pointer to function is
`private_type`. If overload resolution selects our overload, then the
type of `(fun(a, b), 0)` is `private_type`. Otherwise, it is `int`.
That fact is used to dispatch to either overload of `is_private_type()`,
-which encodes its answer in the size of its return type.
+which encodes its answer in the size of its return type.\n
+在 `private_type` 中重载逗号操作符的目的就很显而易见了。这个函数指针的返回
类型是 `private_type`。
+如果重载决议选中了我们的重载，则 `(fun(a, b), 0)` 的类型为 `private_type`。
否则，其类型为 `int`。
+这一事实用于分派 `is_private_type()` 的重载，后者将答案写在返回类型的大小
中。
That's how it works with binary functions. Now repeat the above process
-for functions up to some predefined function arity, and you're done.
+for functions up to some predefined function arity, and you're done.\n
+以上就是如何使用这一方法对二元函数进行判断。现在，可以重复以上过程直至某个
预定义的函数airty为止。
[endsect]
=======================================
--- /trunk/libs/proto/doc/installation.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/installation.qbk Sun Jan 17 23:11:16 2010
@@ -6,11 +6,11 @@
/]
[/=======================]
-[section Installing Proto]
+[section Installing Proto 安装 Proto]
[/=======================]
[/====================]
-[heading Getting Proto]
+[heading Getting Proto 获取 Proto]
[/====================]
You can get Proto by downloading [^proto.zip] from
@@ -18,36 +18,45 @@
by downloading Boost (Proto is in version 1.37 and later),
or by accessing Boost's SVN repository on SourceForge.net. Just go to
[@http://svn.boost.org/trac/boost/wiki/BoostSubversion]
-and follow the instructions there for anonymous SVN access.
+and follow the instructions there for anonymous SVN access.\n
+你可以通过从
[@http://www.boost-consulting.com/vault/index.php?directory=Template%20Metaprogramming]
+下载 [^proto.zip] 获得 Proto，也可以通过下载 Boost (Proto 在版本 1.37 及后
续版本中)，或访问位于 SourceForge.net
+的 Boost's SVN 版本库来获取。请到
[@http://svn.boost.org/trac/boost/wiki/BoostSubversion] 查阅进行匿名 SVN 访
问的指令。
[/==========================]
-[heading Building with Proto]
+[heading Building with Proto 用 Proto 来构建]
[/==========================]
Proto 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/proto/proto.hpp>`. Or, you might decide to just
include the core of Proto (`#include <boost/proto/core.hpp>`) and whichever
-contexts and transforms you happen to use.
+contexts and transforms you happen to use.\n
+Proto 是一个只有头文件的模板库，这意味着你在使用它的时候不需要修改你的构建
脚本或链接任何独立的库文件来。
+你需要做的只是 `#include <boost/proto/proto.hpp>`。或者，你也可以决定只包
含 Proto 的核心
+(`#include <boost/proto/core.hpp>`)以及你想要使用的上下文和变换。
[/===================]
-[heading Requirements]
+[heading Requirements 要求]
[/===================]
Proto depends on Boost. You must use either Boost version 1.34.1 or higher,
-or the version in SVN trunk.
+or the version in SVN trunk.\n
+Proto 依赖于 Boost。你必须使用 Boost 版本 1.34.1 或更高版本，或是 SVN
trunk 中的版本。
[/==========================]
-[heading Supported Compilers]
+[heading Supported Compilers 支持的编译器]
[/==========================]
-Currently, Boost.Proto is known to work on the following compilers:
+Currently, Boost.Proto is known to work on the following compilers:\n
+目前已知 Boost.Proto 可以使用以下编译器：
* Visual C++ 7.1 and higher
* GNU C++ 3.4 and higher
* Intel on Linux 8.1 and higher
* Intel on Windows 9.1 and higher
-[note Please send any questions, comments and bug reports to eric <at>
boostpro <dot> com.]
+[note Please send any questions, comments and bug reports to eric <at>
boostpro <dot> com.\n
+有任何问题、建议和缺陷，请报告至 eric@xxxxxxxxxxxx。]
[endsect]
=======================================
--- /trunk/libs/proto/doc/intermediate_form.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/intermediate_form.qbk Sun Jan 17 23:11:16 2010
@@ -20,33 +20,40 @@
[/================================================================================]
[section:intermediate_form Intermediate Form:
- Understanding and Introspecting Expressions]
+ Understanding and Introspecting Expressions 中间格式：理解和窥探表达式]
[/================================================================================]
-By now, you know a bit about how to build a front-end for your
DSEL "compiler" -- you can define terminals and functions that generate
expression templates. But we haven't said anything about the expression
templates themselves. What do they look like? What can you do with them? In
this section we'll see.
+By now, you know a bit about how to build a front-end for your
DSEL "compiler" -- you can define terminals and functions that generate
expression templates. But we haven't said anything about the expression
templates themselves. What do they look like? What can you do with them? In
this section we'll see.\n
+现在，你已经知道如何为你的DSEL"编译器"构建一个前端 -- 你可以定义终结符和生
成表达式模板的函数。
+不过我们还没有讲到关于表达式模板本身的东西。它们看起来是怎样的呢？你可以对
它们做些什么呢？在本节中，我们将会看到这些内容。
[/=========================]
-[heading The [^expr<>] Type]
+[heading The [^expr<>] Type 类型[^expr<>]]
[/=========================]
-All Proto expressions are an instantiation of a template called _expr_ (or
a wrapper around such an instantiation). When we define a terminal as
below, we are really initializing an instance of the _expr_ template.
-
- // Define a placeholder type
+All Proto expressions are an instantiation of a template called _expr_ (or
a wrapper around such an instantiation). When we define a terminal as
below, we are really initializing an instance of the _expr_ template.\n
+所有 Proto 表达式都是一个名为 _expr_ 的模板的实例(或是包含该实例的一个包装
器)。当我们如下定义一个终结符时，
+我们实际上是初始化了一个 _expr_ 模板的实例。
+
+ // Define a placeholder type 定义一个占位符类型
template<int I>
struct placeholder
{};
- // Define the Protofied placeholder terminal
+ // Define the Protofied placeholder terminal 定义Proto化的占位符终结符
proto::terminal< placeholder<0> >::type const _1 = {{}};
-The actual type of `_1` looks like this:
+The actual type of `_1` looks like this:\n
+`_1` 的实际类型如下：
proto::expr< proto::tag::terminal, proto::term< placeholder<0> >, 0 >
The _expr_ template is the most important type in Proto. Although you will
rarely need to deal with it directly, it's always there behind the scenes
holding your expression trees together. In fact, _expr_ /is/ the expression
-tree -- branches, leaves and all.
+tree -- branches, leaves and all.\n
+_expr_ 模板是 Proto 中最重要的类型。虽然你很少要直接处理它，但是它总是在幕
后把你的表达式树保持在一起。
+事实上，_expr_ /就是/表达式树 -- 分支、叶子和所有。
The _expr_ template makes up the nodes in expression trees. The first
template
parameter is the node type; in this case, `proto::tag::terminal`. That
means
@@ -54,9 +61,14 @@
is a list of child types, or in the case of terminals, the terminal's value
type. Terminals will always have only one type in the type list. The last
parameter is the arity of the expression. Terminals have arity 0, unary
-expressions have arity 1, etc.
-
-The _expr_ struct is defined as follows:
+expressions have arity 1, etc.\n
+_expr_ 模板负责拼凑表达式树中的节点。第一个模板参数是节点的类型；在这个例子
中是 `proto::tag::terminal`。
+这意味着 `_1` 是表达式树中的一个叶节点。第二个模板参数是一个子节点类型的列
表，或者在终结符的情况下，
+为终结符的值类型。在这个类型列表中，终结符永远只有一个类型。最后一个参数是
表达式的arity。
+终结符的arity为0，单参数表达式的arity为1，等等。
+
+The _expr_ struct is defined as follows:\n
+_expr_ 结构定义如下：
template< typename Tag, typename Args, long Arity = Args::arity >
struct expr;
@@ -75,10 +87,14 @@
initialized with the initializer `{{}}`. The outer braces are the
initializer
for the _expr_ struct, and the inner braces are for the member `_1.child0`
which
is of type `placeholder<0>`. Note that we use braces to initialize
`_1.child0`
-because `placeholder<0>` is also an aggregate.
+because `placeholder<0>` is also an aggregate.\n
+_expr_ 结构没有定义构造函数，或其它任何东西，以防止被静态初始化。所有
_expr_ 对象都使用带花括号的 ['聚集初始化] 来初始化。
+在我们的例子中，`_1` 用初始化器 `{{}}` 来初始化。外面一层花括号是用于
_expr_ 结构的初始化器，
+里面一层花括号则是用于成员 `_1.child0`，其类型为 `placeholder<0>`。注意，我
们使用花括号来初始化 `_1.child0`，
+因为 `placeholder<0>` 也是一个聚集。
[/================================]
-[heading Building Expression Trees]
+[heading Building Expression Trees 构建表达式树]
[/================================]
The `_1` node is an instantiation of _expr_, and expressions containing
@@ -86,9 +102,13 @@
won't have to bother yourself with the actual types that Proto generates.
These are details, but you're likely to encounter these types in compiler
error messages, so it's helpful to be familiar with them. The types look
-like this:
-
- // The type of the expression -_1
+like this:\n
+节点 `_1` 是 _expr_ 的一个实例，包含 `_1` 的表达式也是 _expr_ 的实例。
+要有效地使用 Proto，你并不必操心 Proto 生成的实际类型。 它们只是实现细节而
已，
+不过你很可能会在编译器的错误信息中碰到这些类型，所以，熟悉一下它们也是很有
用的。
+这些类型就象以下这样：
+
+ // The type of the expression -_1 表达式 -_1 的类型
typedef
proto::expr<
proto::tag::negate
@@ -105,7 +125,7 @@
negate_placeholder_type x = -_1;
- // The type of the expression _1 + 42
+ // The type of the expression _1 + 42 表达式 _1 + 42 的类型
typedef
proto::expr<
proto::tag::plus
@@ -127,22 +147,31 @@
placeholder_plus_int_type y = _1 + 42;
-There are a few things to note about these types:
+There are a few things to note about these types:\n
+对于这些类型，有几点要注意：
* Terminals have arity zero, unary expressions have arity one and binary
- expressions have arity two.
+ expressions have arity two.\n
+ 终结符的arity为0，单参数表达式的arity为1，二元表达式的arity为2。
* When one Proto expression is made a child node of another Proto
expression,
it is held by reference, ['even if it is a temporary object]. This last
- point becomes important later.
+ point becomes important later.\n
+ 当一个 Proto 表达式作为另一个 Proto 表达式的子节点时，它是以引用方式被持
有的，
+ ['即使它是一个临时对象]。最后一点很重要。
* Non-Proto expressions, such as the integer literal, are turned into Proto
expressions by wrapping them in new `expr<>` terminal objects. These new
wrappers are not themselves held by reference, but the object wrapped
/is/.
Notice that the type of the Protofied `42` literal is `int const &` --
held
- by reference.
+ by reference.\n
+ 非 Proto 表达式，如整数字面值，通过把它们包入一个新的 `expr<>` 终结符对象
变为 Proto 表达式。
+ 这些新的包装器本身不是以引用方式持有的，但被包装的对象/是/。注意，Proto化
的 `42`
+ 字面值的类型是 `int const &` -- 是以引用方式持有的。
The types make it clear: everything in a Proto expression tree is held by
reference. That means that building an expression tree is exceptionally
cheap.
-It involves no copying at all.
+It involves no copying at all.\n
+很显然：在一个 Proto 表达式树中的任何东西都是以引用方式持有的。
+这意味着构建一个表达式树代价非常低。它根本不进行复制。
[note An astute reader will notice that the object `y` defined above will
be
left holding a dangling reference to a temporary int. In the sorts of
@@ -151,27 +180,35 @@
this dangling reference situation often doesn't arise, but it is certainly
something to be aware of. Proto provides utilities for deep-copying
expression
trees so they can be passed around as value types without concern for
dangling
-references.]
+references.\n
+聪明的读者可能会注意到，上面所定义的对象 `y` 会持有一个对临时 int 的悬空引
用。
+在各种使用 Proto 的高性能应用程序中，典型的方法是在任何一个临时对象离开其范
围之前，
+对一个表达式树构建并求值完成，所以这种悬空引用的情形通常不会发生，但这一点
还是必须要知道的。
+Proto 提供了对表达式树进行深复制的工具，所以表达式树可以作为值类型进行传递
而无需担心悬空的引用。]
[/========================================================]
-[section:left_right_child Accessing Parts of an Expression]
+[section:left_right_child Accessing Parts of an Expression 访问子节点]
[/========================================================]
After assembling an expression into a tree, you'll naturally want to be
able to do the reverse, and access a node's children. You may even want
to be able to iterate over the children with algorithms from the
-Boost.Fusion library. This section shows how.
+Boost.Fusion library. This section shows how.\n
+把一个表达式组装成一棵树之后，很自然你会想能够做相反的动作，访问某个子节
点。
+甚至你可能会想能够用 Boost.Fusion 库的算法来遍历子节点。本节将展示如何实现
这一点。
[/==========================================]
-[heading Getting Expression Tags and Arities]
+[heading Getting Expression Tags and Arities 获取表达式的标签和Arity]
[/==========================================]
-Every node in an expression tree has both a /tag/ type that describes the
node, and an /arity/ corresponding to the number of child nodes it has. You
can use the _tag_of_ and _arity_of_ metafunctions to fetch them. Consider
the following:
+Every node in an expression tree has both a /tag/ type that describes the
node, and an /arity/ corresponding to the number of child nodes it has. You
can use the _tag_of_ and _arity_of_ metafunctions to fetch them. Consider
the following:\n
+表达式树中每个节点都有一个用于描述该节点的 /标签/ 类型，以及一个对应于其子
节点数量的 /arity/。你可以用 _tag_of_ 和 _arity_of_
+元函数来获得它们。如：
template<typename Expr>
void check_plus_node(Expr const &)
{
- // Assert that the tag type is proto::tag::plus
+ // Assert that the tag type is proto::tag::plus 标签类型应为
proto::tab::plus
BOOST_STATIC_ASSERT((
boost::is_same<
typename proto::tag_of<Expr>::type
@@ -179,38 +216,48 @@
>::value
));
- // Assert that the arity is 2
+ // Assert that the arity is 2 arity应为2
BOOST_STATIC_ASSERT( proto::arity_of<Expr>::value == 2 );
}
// Create a binary plus node and use check_plus_node()
// to verify its tag type and arity:
+ // 创建一个二元加节点并用 check_plus_node() 来验证它的标签类型和arity：
check_plus_node( proto::lit(1) + 2 );
-For a given type `Expr`, you could access the tag and arity directly as
`Expr::proto_tag` and `Expr::proto_arity`, where `Expr::proto_arity` is an
MPL Integral Constant.
+For a given type `Expr`, you could access the tag and arity directly as
`Expr::proto_tag` and `Expr::proto_arity`, where `Expr::proto_arity` is an
MPL Integral Constant.\n
+对于一个给定的类型 `Expr`，你可以直接通过 `Expr::proto_tag` 和
`Expr::proto_arity` 访问它的标签和arity，其中 `Expr::proto_arity`
+是一个MPL整型常量。
[/==============================]
-[heading Getting Terminal Values]
+[heading Getting Terminal Values 获取终结符的值]
[/==============================]
-There is no simpler expression than a terminal, and no more basic
operation than extracting its value. As we've already seen, that is what
_value_ is for.
+There is no simpler expression than a terminal, and no more basic
operation than extracting its value. As we've already seen, that is what
_value_ is for.\n
+没有比终结符更简单的表达式，也没有比获取终结符的值更基本的操作。正如我们已
经看到的，这正是 _value_ 的作用。
proto::terminal< std::ostream & >::type cout_ = {std::cout};
- // Get the value of the cout_ terminal:
+ // Get the value of the cout_ terminal: 获取 cout_ 终结符的值：
std::ostream & sout = proto::value( cout_ );
- // Assert that we got back what we put in:
+ // Assert that we got back what we put in: 我们取回的与放入的应该一致：
assert( &sout == &std::cout );
-To compute the return type of the _value_ function, you can use
_result_of_value_. When the parameter to _result_of_value_ is a
non-reference type, the result type of the metafunction is the type of the
value as suitable for storage by value; that is, top-level reference and
qualifiers are stripped from it. But when instantiated with a reference
type, the result type has a reference /added/ to it, yielding a type
suitable for storage by reference. If you want to know the actual type of
the terminal's value including whether it is stored by value or reference,
you can use `fusion::result_of::value_at<Expr, 0>::type`.
-
-The following table summarizes the above paragraph.
-
-[def _unless_ [footnote If `T` is a reference-to-function type, then the
result type is simply `T`.]]
-
-[table Accessing Value Types
- [[Metafunction Invocation][When the Value Type Is ...][The Result
Is ...]]
+To compute the return type of the _value_ function, you can use
_result_of_value_. When the parameter to _result_of_value_ is a
non-reference type, the result type of the metafunction is the type of the
value as suitable for storage by value; that is, top-level reference and
qualifiers are stripped from it. But when instantiated with a reference
type, the result type has a reference /added/ to it, yielding a type
suitable for storage by reference. If you want to know the actual type of
the terminal's value including whether it is stored by value or reference,
you can use `fusion::result_of::value_at<Expr, 0>::type`.\n
+要计算 _value_ 函数的返回类型，你可以用 _result_of_value_。如果
_result_of_value_ 的参数是一个非引用类型，
+则该元函数的结果类型为该值的类型，适合以值方式保存；即顶层引用和限定符将被
剥除。但如果是以一个引用类型实例化的，
+则结果类型也带有/所添加的/引用，以得到一个适合以引用方式保存的类型。如果你
想知道终结符值的真实类型，
+包括它是以值方式还是引用方式保存的，你可以用
`fusion::result_of::value_at<Expr, 0>::type`。
+
+The following table summarizes the above paragraph.\n
+下表总结了以上内容。
+
+[def _unless_ [footnote If `T` is a reference-to-function type, then the
result type is simply `T`.\n
+如果`T`是函数引用类型，则结果类型就是`T`。]]
+
+[table Accessing Value Types 访问值类型
+ [[Metafunction Invocation 元函数调用][When the Value Type Is ... 值类型
为...][The Result Is ... 结果为...]]
[[`proto::result_of::value<Expr>::type`][`T`][``typename
boost::remove_const<
typename boost::remove_reference<T>::type
>::type _unless_``]]
@@ -222,20 +269,24 @@
]
[/================================]
-[heading Getting Child Expressions]
+[heading Getting Child Expressions 获取子表达式]
[/================================]
-Each non-terminal node in an expression tree corresponds to an operator in
an expression, and the children correspond to the operands, or arguments of
the operator. To access them, you can use the _child_c_ function template,
as demonstrated below:
+Each non-terminal node in an expression tree corresponds to an operator in
an expression, and the children correspond to the operands, or arguments of
the operator. To access them, you can use the _child_c_ function template,
as demonstrated below:\n
+表达式树中的每一个非终结符节点对应于表达式中的一个操作符，而子节点则对应于
操作数或操作符的参数。要访问它们，
+你可以用 _child_c_ 函数模板，示范如下：
proto::terminal<int>::type i = {42};
- // Get the 0-th operand of an addition operation:
+ // Get the 0-th operand of an addition operation: 取出加法操作的第0个操
作数：
proto::terminal<int>::type &ri = proto::child_c<0>( i + 2 );
- // Assert that we got back what we put in:
+ // Assert that we got back what we put in: 断言我们取回了所放入的：
assert( &i == &ri );
-You can use the _result_of_child_c_ metafunction to get the type of the
Nth child of an expression node. Usually you don't care to know whether a
child is stored by value or by reference, so when you ask for the type of
the Nth child of an expression `Expr` (where `Expr` is not a reference
type), you get the child's type after references and cv-qualifiers have
been stripped from it.
+You can use the _result_of_child_c_ metafunction to get the type of the
Nth child of an expression node. Usually you don't care to know whether a
child is stored by value or by reference, so when you ask for the type of
the Nth child of an expression `Expr` (where `Expr` is not a reference
type), you get the child's type after references and cv-qualifiers have
been stripped from it.\n
+你可以用 _result_of_child_c_ 元函数取出某个表达式节点的第N个子节点的类型。
通常你不必关心一个子节点是以值方式还是以引用方式保存的，
+因此当你询问一个表达式 `Expr` (其中 `Expr` 不是引用类型)的第N个子节点的类型
时，你所得到的子节点类型是在引用和cv限定符被摘取之后的类型。
template<typename Expr>
void test_result_of_child_c(Expr const &expr)
@@ -245,6 +296,8 @@
// Since Expr is not a reference type,
// result_of::child_c<Expr, 0>::type is a
// non-cv qualified, non-reference type:
+ // 因为Expr不是引用类型，所以result_of::child_c<Expr, 0>::type
+ // 是一个非cv限定的非引用类型：
BOOST_MPL_ASSERT((
boost::is_same< type, proto::terminal<int>::type >
));
@@ -259,10 +312,13 @@
the child is actually stored by reference or not. If you need to know
exactly
how the child is stored in the node, whether by reference or by value, you
can
use `fusion::result_of::value_at<Expr, N>::type`. The following table
summarizes
-the behavior of the _result_of_child_c_ metafunction.
-
-[table Accessing Child Types
- [[Metafunction Invocation][When the Child Is ...][The Result Is ...]]
+the behavior of the _result_of_child_c_ metafunction.\n
+但是，如果你询问的是 `Expr &` 或 `Expr const &` (留意其中的引用)的第N个子节
点的类型，则结果类型将会是一个引用，
+无论这个子节点实际上是否以引用的方式保存。如果你需要精确地知道子节点是如何
保存的，是值方式还是引用方式，
+你可以用 `fusion::result_of::value_at<Expr, N>::type`。下表总结了
_result_of_child_c_ 元函数的行为。
+
+[table Accessing Child Types 访问子节点的类型
+ [[Metafunction Invocation 元函数调用][When the Child Is ... 子节点
为...][The Result Is ... 结果为...]]
[[`proto::result_of::child_c<Expr, N>::type`][`T`][``typename
boost::remove_const<
typename boost::remove_reference<T>::type
>::type``]]
@@ -274,71 +330,93 @@
]
[/=======================]
-[heading Common Shortcuts]
+[heading Common Shortcuts 常用缩写]
[/=======================]
-Most operators in C++ are unary or binary, so accessing the only operand,
or the left and right operands, are very common operations. For this
reason, Proto provides the _child_, _left_, and _right_ functions. _child_
and _left_ are synonymous with `proto::child_c<0>()`, and _right_ is
synonymous with `proto::child_c<1>()`.
-
-There are also _result_of_child_, _result_of_left_, and _result_of_right_
metafunctions that merely forward to their _result_of_child_c_ counterparts.
+Most operators in C++ are unary or binary, so accessing the only operand,
or the left and right operands, are very common operations. For this
reason, Proto provides the _child_, _left_, and _right_ functions. _child_
and _left_ are synonymous with `proto::child_c<0>()`, and _right_ is
synonymous with `proto::child_c<1>()`.\n
+C++中的多数操作符都是单参数或双参数的。因此，访问唯一的操作数，或访问左、右
操作数，是非常常见的操作。为此，Proto 提供了 _child_,
+_left_, 和 _right_ 函数。_child_ 和 _left_ 相当于 `child_c<0>()`，而
_right_ 则相当于 `child_c<1>()`。
+
+There are also _result_of_child_, _result_of_left_, and _result_of_right_
metafunctions that merely forward to their _result_of_child_c_
counterparts.\n
+还有，_result_of_child_, _result_of_left_, and _result_of_right_ 元函数只是
前转至相应的 _result_of_child_c_。
[endsect]
[/===============================]
-[section Deep-copying Expressions]
+[section Deep-copying Expressions 表达式的深拷贝]
[/===============================]
-When you build an expression template with Proto, all the intermediate
child nodes are held /by reference/. The avoids needless copies, which is
crucial if you want your DSEL to perform well at runtime. Naturally, there
is a danger if the temporary objects go out of scope before you try to
evaluate your expression template. This is especially a problem in C++0x
with the new `decltype` and `auto` keywords. Consider:
-
- // OOPS: "ex" is left holding dangling references
+When you build an expression template with Proto, all the intermediate
child nodes are held /by reference/. The avoids needless copies, which is
crucial if you want your DSEL to perform well at runtime. Naturally, there
is a danger if the temporary objects go out of scope before you try to
evaluate your expression template. This is especially a problem in C++0x
with the new `decltype` and `auto` keywords. Consider:\n
+当你用Proto构建一个表达式模板时，所有中间的子节点都是/以引用方式/持有的。这
避免了不必要的复制，如果你希望你的DSEL运行得好，
+这是至关重要的。当然，如果临时对象在你尝试对表达式模板进行求值之前超出了范
围，就会有危险。在带有新的 `decltype` 和 `auto`
+关键字的C++0x中尤其成问题。考虑：
+
+ // OOPS: "ex" is left holding dangling references 哎呀："ex"将持有悬空
引用
auto ex = proto::lit(1) + 2;
-The problem can happen in today's C++ also if you use `BOOST_TYPEOF()` or
`BOOST_AUTO()`, or if you try to pass an expression template outside the
scope of its constituents.
-
-In these cases, you want to deep-copy your expression template so that all
intermediate nodes and the terminals are held /by value/. That way, you can
safely assign the expression template to a local variable or return it from
a function without worrying about dangling references. You can do this with
_deep_copy_ as fo
-llows:
-
- // OK, "ex" has no dangling references
+The problem can happen in today's C++ also if you use `BOOST_TYPEOF()` or
`BOOST_AUTO()`, or if you try to pass an expression template outside the
scope of its constituents.\n
+如果你使用 `BOOST_TYPEOF()` 或 `BOOST_AUTO()`，或者如果你试图传送一个表达式
模板到它的组成成份的范围之外，
+这个问题也会发生在当前的C++中。
+
+In these cases, you want to deep-copy your expression template so that all
intermediate nodes and the terminals are held /by value/. That way, you can
safely assign the expression template to a local variable or return it from
a function without worrying about dangling references. You can do this with
_deep_copy_ as follows:\n
+在这种情况下，你希望对表达式模板进行深拷贝，令所有中间节点和终结符/以值方式
/持有。这样，你就可以安全地将表达式模板赋值到局部变量，
+或者从某个函数返回它，而无须担心悬空引用。你可以如下进行 _deep_copy_：
+
+ // OK, "ex" has no dangling references 好的，"ex"没有悬空引用
auto ex = proto::deep_copy( proto::lit(1) + 2 );
-If you are using _typeof_, it would look like this:
+If you are using _typeof_, it would look like this:\n
+如果你使用 _typeof_，看起来就象这样：
// OK, use BOOST_AUTO() and proto::deep_copy() to
// store an expression template in a local variable
+ // 好的，使用 BOOST_AUTO() 和 proto::deep_copy() 来
+ // 将一个表达式模板保存在局部变量中
BOOST_AUTO( ex, proto::deep_copy( proto::lit(1) + 2 ) );
-For the above code to work, you must include the [headerref
boost/proto/proto_typeof.hpp] header, which also defines the _AUTO_ macro
which automatically deep-copies its argument. With _AUTO_, the above code
can be writen as:
+For the above code to work, you must include the [headerref
boost/proto/proto_typeof.hpp] header, which also defines the _AUTO_ macro
which automatically deep-copies its argument. With _AUTO_, the above code
can be writen as:\n
+为了使以上代码可以工作，你必须包含 [headerref
boost/proto/proto_typeof.hpp] 头文件，其中还将定义 _AUTO_ 宏以自动对参数进行
深拷贝。
+有了 _AUTO_，以上代码可以写为：
// OK, BOOST_PROTO_AUTO() automatically deep-copies
// its argument:
+ // 好的，BOOST_PROTO_AUTO() 自动对参数进行深拷贝：
BOOST_PROTO_AUTO( ex, proto::lit(1) + 2 );
-When deep-copying an expression tree, all intermediate nodes and all
terminals are stored by value. The only exception is terminals that are
function references, which are left alone.
-
-[note _deep_copy_ makes no exception for arrays, which it stores by value.
That can potentially cause a large amount of data to be copied.]
+When deep-copying an expression tree, all intermediate nodes and all
terminals are stored by value. The only exception is terminals that are
function references, which are left alone.\n
+当深拷贝一个表达式树时，所有中间节点以及所有终结符都以值方式保存。唯一的例
外是函数引用终结符，它们会单独保留。
+
+[note _deep_copy_ makes no exception for arrays, which it stores by value.
That can potentially cause a large amount of data to be copied.\n
+_deep_copy_ 对于以值方式保存的数组可能并不适用。这有可能引起大量数据的复
制。]
[endsect]
[/============================]
-[section Debugging Expressions]
+[section Debugging Expressions 调试表达式]
[/============================]
-Proto provides a utility for pretty-printing expression trees that comes
in very handy when you're trying to debug your DSEL. It's called
_display_expr_, and you pass it the expression to print and optionally, an
`std::ostream` to which to send the output. Consider:
-
- // Use display_expr() to pretty-print an expression tree
+Proto provides a utility for pretty-printing expression trees that comes
in very handy when you're trying to debug your DSEL. It's called
_display_expr_, and you pass it the expression to print and optionally, an
`std::ostream` to which to send the output. Consider:\n
+Proto提供了一个整齐地打印表达式树的工具，在你想调试你的DSEL时非常适用。它
叫 _display_expr_，你向它传入要打印的表达式，
+以及一个可选的用于输出的 `std::ostream`。考虑：
+
+ // Use display_expr() to pretty-print an expression tree 使用
display_expr()来打印表达式树
proto::display_expr(
proto::lit("hello") + 42
);
-The above code writes this to `std::cout`:
+The above code writes this to `std::cout`:\n
+上述代码将以下内容写至 `std::cout`：
[pre plus(
terminal(hello)
, terminal(42)
)]
-In order to call _display_expr_, all the terminals in the expression must
be Streamable (that is, they can be written to a `std::ostream`). In
addition, the tag types must all be Streamable as well. Here is an example
that includes a custom terminal type and a custom tag:
-
- // A custom tag type that is Streamable
+In order to call _display_expr_, all the terminals in the expression must
be Streamable (that is, they can be written to a `std::ostream`). In
addition, the tag types must all be Streamable as well. Here is an example
that includes a custom terminal type and a custom tag:\n
+为了调用 _display_expr_，表达式中的所有终结符都必须是可流的(即它们可被写出
至某个 `std::ostream`)。另外，标签类型必须也都是可流的。
+以下是一个例子，包含了一个定制的终结符类型和一个定制的标签：
+
+ // A custom tag type that is Streamable 定制标签类型是可流的
struct MyTag
{
friend std::ostream &operator<<(std::ostream &s, MyTag)
@@ -347,7 +425,7 @@
}
};
- // Some other Streamable type
+ // Some other Streamable type 一些其它的可流类型
struct MyTerminal
{
friend std::ostream &operator<<(std::ostream &s, MyTerminal)
@@ -360,12 +438,14 @@
{
// Display an expression tree that contains a custom
// tag and a user-defined type in a terminal
+ // 显示一棵包含有定制标签和用户自定义类型终结符的表达式树
proto::display_expr(
proto::make_expr<MyTag>(MyTerminal()) + 42
);
}
-The above code prints the following:
+The above code prints the following:\n
+上述代码输出如下：
[pre plus(
MyTag(
@@ -377,15 +457,17 @@
[endsect]
[/=============================================================]
-[section:tags_and_metafunctions Operator Tags and Metafunctions]
+[section:tags_and_metafunctions Operator Tags and Metafunctions 操作符标签
和元函数]
[/=============================================================]
-The following table lists the overloadable C++ operators, the Proto tag
types for each, and the name of the metafunctions for generating the
corresponding Proto expression types. And as we'll see later, the
metafunctions are also usable as grammars for matching such nodes, as well
as pass-through transforms.
-
-[table Operators, Tags and Metafunctions
- [[Operator]
- [Proto Tag]
- [Proto Metafunction]]
+The following table lists the overloadable C++ operators, the Proto tag
types for each, and the name of the metafunctions for generating the
corresponding Proto expression types. And as we'll see later, the
metafunctions are also usable as grammars for matching such nodes, as well
as pass-through transforms.\n
+下表列出了可重载的C++操作符、各个 Proto 标签类型，以及生成相应的 Proto 表达
式类型的元函数名字。我们稍后将看到，
+这些元函数也可用作匹配这些节点的语法，以及传递给变换操作。
+
+[table Operators, Tags and Metafunctions 操作符，标签和元函数
+ [[Operator 操作符]
+ [Proto Tag Proto标签]
+ [Proto Metafunction Proto元函数]]
[[unary `+`]
[`proto::tag::unary_plus`]
@@ -567,10 +649,14 @@
[endsect]
[/======================================]
-[section Expressions as Fusion Sequences]
+[section Expressions as Fusion Sequences 作为Fusion序列的表达式]
[/======================================]
-Boost.Fusion is a library of iterators, algorithms, containers and
adaptors for manipulating heterogeneous sequences. In essence, a Proto
expression is just a heterogeneous sequence of its child expressions, and
so Proto expressions are valid Fusion random-access sequences. That means
you can apply Fusion algorithms to them, transform them, apply Fusion
filters and views to them, and access their elements using `fusion::at()`.
The things Fusion can do to heterogeneous sequences are beyond the scope of
this users' guide, but below is a simple example. It takes a lazy function
invocation like `fun(1,2,3,4)` and uses Fusion to print the function
arguments in order.
+Boost.Fusion is a library of iterators, algorithms, containers and
adaptors for manipulating heterogeneous sequences. In essence, a Proto
expression is just a heterogeneous sequence of its child expressions, and
so Proto expressions are valid Fusion random-access sequences. That means
you can apply Fusion algorithms to them, transform them, apply Fusion
filters and views to them, and access their elements using `fusion::at()`.
The things Fusion can do to heterogeneous sequences are beyond the scope of
this users' guide, but below is a simple example. It takes a lazy function
invocation like `fun(1,2,3,4)` and uses Fusion to print the function
arguments in order.\n
+Boost.Fusion 是一个迭代器、算法、容器和适配器的库，用于对异类型序列进行操
作。本质上，Proto 表达式节点也是其子节点的一个异类型序列，
+所以Proto表达式是有效 Fusion 随机访问序列。这意味着你可以对它们应用 Fusion
算法、转换它们，应用 Fusion 过滤器和查看它们，
+以及使用 `fusion::at()` 访问它们的元素。这些 Fusion 可以对异类型序列的事情
已经超出本用户指南的讨论范围，下面给出一个简单的例子。
+该例子接受一个类似于 `fun(1,2,3,4)` 的惰性函数调用，并使用 Fusion 来按顺序
打印函数的参数。
struct display
{
@@ -599,7 +685,10 @@
define function objects that correspond to Proto's free functions. So
`proto::functional::value()` creates a function object that is equivalent
to
the `proto::value()` function. The above invocation of `fusion::for_each()`
-displays the following:
+displays the following:\n
+回想一下"简介"中的介绍，`proto::functional` 名字空间中的类型定义了与 Proto
普通函数相对应的函数对象。
+因此 `proto::functional::value()` 创建一个等价于 `proto::value()` 函数的函
数对象。
+以上 `fusion::for_each()` 调用将显示以下内容：
[pre
1
@@ -608,17 +697,19 @@
4
]
-Terminals are also valid Fusion sequences. They contain exactly one
element: their value.
+Terminals are also valid Fusion sequences. They contain exactly one
element: their value.\n
+终结符也是有效的 Fusion 序列。它们包含恰好一个元素：它们的值。
[/========================================]
-[heading Flattening Proto Expression Tress]
+[heading Flattening Proto Expression Tress 将 Proto 表达式树摊平]
[/========================================]
-Imagine a slight variation of the above example where, instead of
iterating over the arguments of a lazy function invocation, we would like
to iterate over the terminals in an addition expression:
+Imagine a slight variation of the above example where, instead of
iterating over the arguments of a lazy function invocation, we would like
to iterate over the terminals in an addition expression:\n
+想象一下以上例子的轻微变化，不遍历惰性函数调用的参数，而是遍历另一个表达式
中的终结符：
proto::terminal<int>::type const _1 = {1};
- // ERROR: this doesn't work! Why?
+ // ERROR: this doesn't work! Why? 错误：不能这样做！为什么？
fusion::for_each(
fusion::transform(
_1 + 2 + 3 + 4
@@ -627,11 +718,15 @@
, display()
);
-The reason this doesn't work is because the expression `_1 + 2 + 3 + 4`
does not describe a flat sequence of terminals --- it describes a binary
tree. We can treat it as a flat sequence of terminals, however, using
Proto's _flatten_ function. _flatten_ returns a view which makes a tree
appear as a flat Fusion sequence. If the top-most node has a tag type `T`,
then the elements of the flattened sequence are the child nodes that do
/not/ have tag type `T`. This process is evaluated recursively. So the
above can correctly be written as:
+The reason this doesn't work is because the expression `_1 + 2 + 3 + 4`
does not describe a flat sequence of terminals --- it describes a binary
tree. We can treat it as a flat sequence of terminals, however, using
Proto's _flatten_ function. _flatten_ returns a view which makes a tree
appear as a flat Fusion sequence. If the top-most node has a tag type `T`,
then the elements of the flattened sequence are the child nodes that do
/not/ have tag type `T`. This process is evaluated recursively. So the
above can correctly be written as:\n
+不能这样做的原因是，因为表达式 `_1 + 2 + 3 + 4` 并不表示为各个终结符的一个
扁平序列 --- 它表示为一个二叉树。不过，
+我们可以通过用 Proto 的 _flatten_ 函数将它视为终结符的扁平序列。_flatten_
返回一个视图，使一棵树看起来象一个扁平的 Fusion 序列。
+如果最顶部的节点具有标签类型 `T`，则扁平化序列的元素为那些/不/具有标签类型
`T` 的子节点。这个过程是递归进行的。
+所以以上例子可以正确地写为：
proto::terminal<int>::type const _1 = {1};
- // OK, iterate over a flattened view
+ // OK, iterate over a flattened view 好的，遍历一个扁平视图
fusion::for_each(
fusion::transform(
proto::flatten(_1 + 2 + 3 + 4)
@@ -640,7 +735,8 @@
, display()
);
-The above invocation of `fusion::for_each()` displays the following:
+The above invocation of `fusion::for_each()` displays the following:\n
+以上 `fusion::for_each()` 调用将显示如下：
[pre
1
@@ -652,25 +748,34 @@
[endsect]
[/============================================================================]
-[section:expression_introspection Expression Introspection: Defining a
Grammar]
+[section:expression_introspection Expression Introspection: Defining a
Grammar 表达式的内部：定义一个语法]
[/============================================================================]
-Expression trees can have a very rich and complicated structure. Often,
you need to know some things about an expression's structure before you can
process it. This section describes the tools Proto provides for peering
inside an expression tree and discovering its structure. And as you'll see
in later sections, all the really interesting things you can do with Proto
begin right here.
+Expression trees can have a very rich and complicated structure. Often,
you need to know some things about an expression's structure before you can
process it. This section describes the tools Proto provides for peering
inside an expression tree and discovering its structure. And as you'll see
in later sections, all the really interesting things you can do with Proto
begin right here.\n
+表达式树可以具有非常大而复杂的结构。通常，在你可以处理一个表达式结构之
前，你需要了解关于它的一些事情。本节描述 Proto 所提供的一些工具，
+用于窥探表达式树的内部和发现其结构。在后面的章节中你将看到，你可以用 Proto
所做的真正有趣的事情从这里才开始。
[/===============================================]
-[section:patterns Finding Patterns in Expressions]
+[section:patterns Finding Patterns in Expressions 发现表达式中的模式]
[/===============================================]
-Imagine your DSEL is a miniature I/O facility, with iostream operations
that execute lazily. You might want expressions representing input
operations to be processed by one function, and output operations to be
processed by a different function. How would you do that?
-
-The answer is to write patterns (a.k.a, /grammars/) that match the
structure of input and output expressions. Proto provides utilities for
defining the grammars, and the _matches_ template for checking whether a
given expression type matches the grammar.
-
-First, let's define some terminals we can use in our lazy I/O expressions:
+Imagine your DSEL is a miniature I/O facility, with iostream operations
that execute lazily. You might want expressions representing input
operations to be processed by one function, and output operations to be
processed by a different function. How would you do that?\n
+想象你的DSEL是一个微型的I/O工具，可以延迟执行 iostream 操作。你可能想让表示
输入操作的表达式可以被某个函数处理，
+而表示输出操作的则被另一个函数处理。你要怎样做呢？
+
+The answer is to write patterns (a.k.a, /grammars/) that match the
structure of input and output expressions. Proto provides utilities for
defining the grammars, and the _matches_ template for checking whether a
given expression type matches the grammar.\n
+答案是编写匹配输入和输出表达式结构的模式(也称/语法/)。Proto 提供了定义语法
的工具，
+以及用于检查一个给定的表达式类型是否匹配该语法的 _matches_ 模板。
+
+First, let's define some terminals we can use in our lazy I/O
expressions:\n
+首先，我们来定义一些要在我们的惰性I/O表达式中使用的终结符：
proto::terminal< std::istream & >::type cin_ = { std::cin };
proto::terminal< std::ostream & >::type cout_ = { std::cout };
-Now, we can use `cout_` instead of `std::cout`, and get I/O expression
trees that we can execute later. To define grammars that match input and
output expressions of the form `cin_ >> i` and `cout_ << 1` we do this:
+Now, we can use `cout_` instead of `std::cout`, and get I/O expression
trees that we can execute later. To define grammars that match input and
output expressions of the form `cin_ >> i` and `cout_ << 1` we do this: \n
+现在，我们可以用 `cout_` 替代 `std::cout`，并得到可以延迟执行的I/O表达式
树。要定义匹配形如 `cin_ >> i` 和 `cout_ << 1`
+的输入输出表达式的语法，我们可以这样做：
struct Input
: proto::shift_right< proto::terminal< std::istream & >, proto::_ >
@@ -685,11 +790,17 @@
grammar, as are `proto::shift_right<>` and `proto::shift_left<>`. The
newcomer
here is `_` in the `proto` namespace. It is a wildcard that matches
anything.
The `Input` struct is a grammar that matches any right-shift expression
that
-has a `std::istream` terminal as its left operand.
+has a `std::istream` terminal as its left operand.\n
+之前我们已见过模板 `proto::terminal<>`，但是我们在这里使用它并没有访问嵌套
的 `::type`。
+象这样使用时，语法非常简单，如 `proto::shift_right<>` 和
`proto::shift_left<>`。
+这里新出现的是位于 `proto` 名字空间中的 `_`。它是一个可以匹配任何东西的通配
符。
+结构 `Input` 就是一个可以匹配任何以一个 `std::istream` 终结符作为左操作数的
右移表达式的语法。
We can use these grammars together with the _matches_ template to query at
compile time whether a given I/O expression type is an input or output
-operation. Consider the following:
+operation. Consider the following:\n
+我们可以将这些语法和 _matches_ 模板一起使用，在编译期查询一个给定的I/O表达
式类型是否为输入或输出操作。
+考虑以下代码：
template< typename Expr >
void input_output( Expr const & expr )
@@ -714,14 +825,16 @@
return 0;
}
-This program prints the following:
+This program prints the following:\n
+该程序输出如下：
[pre
Output!
Input!
]
-If we wanted to break the `input_output()` function into two functions,
one that handles input expressions and one for output expressions, we can
use `boost::enable_if<>`, as follows:
+If we wanted to break the `input_output()` function into two functions,
one that handles input expressions and one for output expressions, we can
use `boost::enable_if<>`, as follows:\n
+如果我们想将 `input_output()` 函数分开为两个函数，一个处理输入表达式，另一
个处理输出表达式，我们可以用 `boost::enable_if<>`，如下：
template< typename Expr >
typename boost::enable_if< proto::matches< Expr, Input > >::type
@@ -737,13 +850,18 @@
std::cout << "Output!\n";
}
-This works as the previous version did. However, the following does not
compile at all:
+This works as the previous version did. However, the following does not
compile at all:\n
+这一个和前一个版本结果一样。不过，以下代码就不能通过编译：
input_output( cout_ << 1 << 2 ); // oops!
-What's wrong? The problem is that this expression does not match our
grammar. The expression groups as if it were written like `(cout_ << 1) <<
2`. It will not match the `Output` grammar, which expects the left operand
to be a terminal, not another left-shift operation. We need to fix the
grammar.
-
-We notice that in order to verify an expression as input or output, we'll
need to recurse down to the bottom-left-most leaf and check that it is a
`std::istream` or `std::ostream`. When we get to the terminal, we must stop
recursing. We can express this in our grammar using _or_. Here are the
correct `Input` and `Output` grammars:
+What's wrong? The problem is that this expression does not match our
grammar. The expression groups as if it were written like `(cout_ << 1) <<
2`. It will not match the `Output` grammar, which expects the left operand
to be a terminal, not another left-shift operation. We need to fix the
grammar.\n
+有什么错吗？问题在于，这个表达式不能匹配我们的语法。这个表达式组和以下写法
一样：`(cout_ << 1) << 2`。它不能匹配 `Output` 语法，
+后者要求左操作数是一个终结符，而不是另一个左移操作。我们要修正这个语法。
+
+We notice that in order to verify an expression as input or output, we'll
need to recurse down to the bottom-left-most leaf and check that it is a
`std::istream` or `std::ostream`. When we get to the terminal, we must stop
recursing. We can express this in our grammar using _or_. Here are the
correct `Input` and `Output` grammars:\n
+我们注意到，为了检验一个表达式是输入还是输出，我们需要向下递归至最左下方的
叶子并检查它是 `std::istream` 还是 `std::ostream`。
+当我们得到终结符时，我们必须停止递归。我们可以在我们的语法中用 _or_ 来表示
这一点。以下是正确的 `Input` 和 `Output` 语法：
struct Input
: proto::or_<
@@ -759,37 +877,56 @@
>
{};
-This may look a little odd at first. We seem to be defining the `Input`
and `Output` types in terms of themselves. This is perfectly OK, actually.
At the point in the grammar that the `Input` and `Output` types are being
used, they are /incomplete/, but by the time we actually evaluate the
grammar with _matches_, the types will be complete. These are recursive
grammars, and rightly so because they must match a recursive data structure!
-
-Matching an expression such as `cout_ << 1 << 2` against the `Output`
grammar procedes as follows:
+This may look a little odd at first. We seem to be defining the `Input`
and `Output` types in terms of themselves. This is perfectly OK, actually.
At the point in the grammar that the `Input` and `Output` types are being
used, they are /incomplete/, but by the time we actually evaluate the
grammar with _matches_, the types will be complete. These are recursive
grammars, and rightly so because they must match a recursive data
structure!\n
+乍一看，这有点怪。看起来，我们是在用 `Input` 和 `Output` 类型来定义它们本
身。事实上这是完全可以的。在这个语法中，
+到使用 `Input` 和 `Output` 类型的地方为止，它们还是/不完整/的，但是到我们使
用 _matches_ 对该语法进行求值时，
+这两个类型已经是完整的了。这是递归语法，也是正确的，因为它们必须匹配一个递
归的数据结构！
+
+Matching an expression such as `cout_ << 1 << 2` against the `Output`
grammar procedes as follows:\n
+用 `Output` 语法匹配形如 `cout_ << 1 << 2` 的表达式，过程如下：
# The first alternate of the _or_ is tried first. It will fail, because the
expression `cout_ << 1 << 2` does not match the grammar
`proto::shift_left<
- proto::terminal< std::ostream & >, proto::_ >`.
+ proto::terminal< std::ostream & >, proto::_ >`.\n
+ 首先尝试 _or_ 的第一个选择。这会失败，因为表达式 `cout_ << 1 << 2` 不能匹
配语法
+ `proto::shift_left< proto::terminal< std::ostream & >, proto::_ >`。
# Then the second alternate is tried next. We match the expression against
`proto::shift_left< Output, proto::_ >`. The expression is a left-shift,
so we
- next try to match the operands.
-# The right operand `2` matches `proto::_` trivially.
+ next try to match the operands.\n
+ 然后尝试第二个选择。我们用 `proto::shift_left< Output, proto::_ >` 来匹配
这个表达式。
+ 这个表达式是一个左移操作，所以我们先尝试操作数。
+# The right operand `2` matches `proto::_` trivially.\n
+ 右操作数 `2` 可以匹配 `proto::_`。
# To see if the left operand `cout_ << 1` matches `Output`, we must
recursively
evaluate the `Output` grammar. This time we succeed, because `cout_ <<
1` will
- match the first alternate of the _or_.
-
-We're done -- the grammar matches successfully.
+ match the first alternate of the _or_.\n
+ 现在看左操作数 `cout_ << 1` 是否能匹配 `Output`，我们必须递归求值
`Output` 语法。
+ 这一次我们成功了，因为 `cout_ << 1` 将匹配 _or_ 的第一个选择。
+
+We're done -- the grammar matches successfully.\n
+匹配完成 -- 这个语法可以成功地匹配。
[endsect]
[/===========================================]
-[section Fuzzy and Exact Matches of Terminals]
+[section Fuzzy and Exact Matches of Terminals 终结符的模糊匹配和精确匹配]
[/===========================================]
-The terminals in an expression tree could be const or non-const
references, or they might not be references at all. When writing grammars,
you usually don't have to worry about it because _matches_ gives you a
little wiggle room when matching terminals. A grammar such as
`proto::terminal<int>` will match a terminal of type `int`, `int &`, or
`int const &`.
-
-You can explicitly specify that you want to match a reference type. If you
do, the type must match exactly. For instance, a grammar such as
`proto::terminal<int &>` will only match an `int &`. It will not match an
`int` or an `int const &`.
-
-The table below shows how Proto matches terminals. The simple rule is: if
you want to match only reference types, you must specify the reference in
your grammar. Otherwise, leave it off and Proto will ignore const and
references.
-
-[table proto::matches<> and Reference / CV-Qualification of Terminals
- [[Terminal] [Grammar] [Matches?]]
+The terminals in an expression tree could be const or non-const
references, or they might not be references at all. When writing grammars,
you usually don't have to worry about it because _matches_ gives you a
little wiggle room when matching terminals. A grammar such as
`proto::terminal<int>` will match a terminal of type `int`, `int &`, or
`int const &`.\n
+一棵表达式树中的终结符可以是const的或非const的引用，或者根本不是引用。在编
写语法时，你通常不需要担心这一点，
+因为 _matches_ 在匹配终结符时给了你一点宽松的空间。一个形如
`proto::terminal<int>` 的语法可以匹配类型为
+`int`, `int &`, 或 `int const &` 的终结符。
+
+You can explicitly specify that you want to match a reference type. If you
do, the type must match exactly. For instance, a grammar such as
`proto::terminal<int &>` will only match an `int &`. It will not match an
`int` or an `int const &`.\n
+你可以明确指定你要匹配的引用类型。如果你这样做了，类型将必须精确匹配。例
如，一个形如 `proto::terminal<int &>` 的语法只能匹配一个
+`int &`。它不能匹配 `int` 或 `int const &`。
+
+The table below shows how Proto matches terminals. The simple rule is: if
you want to match only reference types, you must specify the reference in
your grammar. Otherwise, leave it off and Proto will ignore const and
references.\n
+下表展示了 Proto 是如何匹配终结符的。简单的规则是：如果你想只匹配引用类
型，你必须在你的语法中指定引用。否则，不用指定它，
+而 Proto 将忽略 const 和引用。
+
+[table proto::matches<> and Reference / CV-Qualification of Terminals
proto::matches<>和终结符的引用/CV限定
+ [[Terminal 终结符] [Grammar 语法] [Matches? 是否匹配？]]
[[T] [T] [yes]]
[[T &] [T] [yes]]
[[T const &] [T] [yes]]
@@ -801,9 +938,15 @@
[[T const &] [T const &] [yes]]
]
-This begs the question: What if you want to match an `int`, but not an
`int &` or an `int const &`? For forcing exact matches, Proto provides the
_exact_ template. For instance, `proto::terminal< proto::exact<int> >`
would only match an `int` held by value.
-
-Proto gives you extra wiggle room when matching array types. Array types
match themselves or the pointer types they decay to. This is especially
useful with character arrays. The type returned by
`proto::as_expr("hello")` is `proto::terminal<char const[6]>::type`. That's
a terminal containing a 6-element character array. Naturally, you can match
this terminal with the grammar `proto::terminal<char const[6]>`, but the
grammar `proto::terminal<char const *>` will match it as well, as the
following code fragment illustrates.
+This begs the question: What if you want to match an `int`, but not an
`int &` or an `int const &`? For forcing exact matches, Proto provides the
_exact_ template. For instance, `proto::terminal< proto::exact<int> >`
would only match an `int` held by value.\n
+这里回避了一个问题：如果你想匹配一个 `int`，而不匹配 `int &` 或 `int const
&`，该怎么办？为了强制精确的匹配，
+Proto 提供了 _exact_ 模板。例如，`proto::terminal< proto::exact<int> >` 将
只匹配一个以值方式保存的 `int`。
+
+Proto gives you extra wiggle room when matching array types. Array types
match themselves or the pointer types they decay to. This is especially
useful with character arrays. The type returned by
`proto::as_expr("hello")` is `proto::terminal<char const[6]>::type`. That's
a terminal containing a 6-element character array. Naturally, you can match
this terminal with the grammar `proto::terminal<char const[6]>`, but the
grammar `proto::terminal<char const *>` will match it as well, as the
following code fragment illustrates.\n
+在匹配数组类型时，Proto 为你提供了更为宽松的空间。数组类型可以匹配它们本身
或它们退化的指针类型。这对于字符数组尤其有用。
+由 `proto::as_expr("hello")` 所返回的类型为 `proto::terminal<char
const[6]>::type`。这是一个包含6个元素的字符数组的终结符。
+自然，你可以用语法 `proto::terminal<char const[6]>` 来匹配这个终结符，不过
语法 `proto::terminal<char const *>` 也可以匹配它，
+如以下代码片断所示。
struct CharString
: proto::terminal< char const * >
@@ -813,7 +956,8 @@
BOOST_MPL_ASSERT(( proto::matches< char_array, CharString > ));
-What if we only wanted `CharString` to match terminals of exactly the type
`char const *`? You can use _exact_ here to turn off the fuzzy matching of
terminals, as follows:
+What if we only wanted `CharString` to match terminals of exactly the type
`char const *`? You can use _exact_ here to turn off the fuzzy matching of
terminals, as follows:\n
+如果我们想 `CharString` 只精确匹配类型为 `char const *` 的终结符，该如
何？你可以用 _exact_ 来关闭对终结符的模糊匹配，如下：
struct CharString
: proto::terminal< proto::exact< char const * > >
@@ -825,19 +969,28 @@
BOOST_MPL_ASSERT(( proto::matches< char_string, CharString > ));
BOOST_MPL_ASSERT_NOT(( proto::matches< char_array, CharString > ));
-Now, `CharString` does not match array types, only character string
pointers.
-
-The inverse problem is a little trickier: what if you wanted to match all
character arrays, but not character pointers? As mentioned above, the
expression `as_expr("hello")` has the type `proto::terminal< char const[ 6
] >::type`. If you wanted to match character arrays of arbitrary size, you
could use `proto::N`, which is an array-size wildcard. The following
grammar would match any string literal: `proto::terminal< char const[
proto::N ] >`.
-
-Sometimes you need even more wiggle room when matching terminals. For
example, maybe you're building a calculator DSEL and you want to allow any
terminals that are convertible to `double`. For that, Proto provides the
_convertible_to_ template. You can use it as: `proto::terminal<
proto::convertible_to< double > >`.
-
-There is one more way you can perform a fuzzy match on terminals. Consider
the problem of trying to match a `std::complex<>` terminal. You can easily
match a `std::complex<float>` or a `std::complex<double>`, but how would
you match any instantiation of `std::complex<>`? You can use `proto::_`
here to solve this problem. Here is the grammar to match any
`std::complex<>` instantiation:
+Now, `CharString` does not match array types, only character string
pointers.\n
+现在，`CharString` 将不能匹配数组类型，只能匹配字符串指针。
+
+The inverse problem is a little trickier: what if you wanted to match all
character arrays, but not character pointers? As mentioned above, the
expression `as_expr("hello")` has the type `proto::terminal< char const[ 6
] >::type`. If you wanted to match character arrays of arbitrary size, you
could use `proto::N`, which is an array-size wildcard. The following
grammar would match any string literal: `proto::terminal< char const[
proto::N ] >`.\n
+相反的问题则有点微妙：如果你想匹配所有字符数组而不想匹配字符指针呢？如上所
述，表达式 `as_expr("hello")` 具有
+`proto::terminal< char const[ 6 ] >::type` 的类型。如果你想匹配任意大小的字
符数组，你可以用 `proto::N`，它是一个数组大小通配符。
+以下语法将匹配任何字符串字面值：`proto::terminal< char const[ proto::N ]
`。
+
+Sometimes you need even more wiggle room when matching terminals. For
example, maybe you're building a calculator DSEL and you want to allow any
terminals that are convertible to `double`. For that, Proto provides the
_convertible_to_ template. You can use it as: `proto::terminal<
proto::convertible_to< double > >`.\n
+有时候，在匹配终结符时你需要更多的空间。例如，也许你正在构建一个计算器
DSEL，你想允许任何可以转换为 `double` 的终结符。为此，Proto 提供了
_convertible_to_ 模板。你可以这样来使用它：`proto::terminal<
proto::convertible_to< double > >`。
+
+There is one more way you can perform a fuzzy match on terminals. Consider
the problem of trying to match a `std::complex<>` terminal. You can easily
match a `std::complex<float>` or a `std::complex<double>`, but how would
you match any instantiation of `std::complex<>`? You can use `proto::_`
here to solve this problem. Here is the grammar to match any
`std::complex<>` instantiation:\n
+你还有一个方法可以对终结符执行模糊匹配。考虑这样一个问题，你尝试匹配一个
`std::complex<>` 终结符。
+你可以很容易地匹配一个 `std::complex<float>` 或 `std::complex<double>`，但
是你如何匹配任意的 `std::complex<>` 实例呢？
+你可以用 `proto::_` 来解决这个问题。以下是匹配任意的 `std::complex<>` 实
例：
struct StdComplex
: proto::terminal< std::complex< proto::_ > >
{};
-When given a grammar like this, Proto will deconstruct the grammar and the
terminal it is being matched against and see if it can match all the
constituents.
+When given a grammar like this, Proto will deconstruct the grammar and the
terminal it is being matched against and see if it can match all the
constituents.\n
+当给出这样一个语法时，Proto 将解构要匹配的语法和终结符，看看它是否可以匹配
所有要素。
[endsect]
@@ -845,13 +998,19 @@
[section:if_and_not [^if_<>], [^and_<>], and [^not_<>]]
[/====================================================]
-We've already seen how to use expression generators like
`proto::terminal<>` and `proto::shift_right<>` as grammars. We've also seen
_or_, which we can use to express a set of alternate grammars. There are a
few others of interest; in particular, _if_, _and_ and _not_.
-
-The _not_ template is the simplest. It takes a grammar as a template
parameter and logically negates it; `not_<Grammar>` will match any
expression that `Grammar` does /not/ match.
-
-The _if_ template is used together with a Proto transform that is
evaluated against expression types to find matches. (Proto transforms will
be described later.)
-
-The _and_ template is like _or_, except that each argument of the _and_
must match in order for the _and_ to match. As an example, consider the
definition of `CharString` above that uses _exact_. It could have been
written without _exact_ as follows:
+We've already seen how to use expression generators like
`proto::terminal<>` and `proto::shift_right<>` as grammars. We've also seen
_or_, which we can use to express a set of alternate grammars. There are a
few others of interest; in particular, _if_, _and_ and _not_.\n
+我们已经看到如何把象 `proto::terminal<>` 和 `proto::shift_right<>` 这样的表
达式生成器作为语法使用。我们也看到了 _or_，
+我们可以用它来表达一组N选1的语法。还有另外几个有趣的模板：_if_, _and_ 和
_not_。
+
+The _not_ template is the simplest. It takes a grammar as a template
parameter and logically negates it; `not_<Grammar>` will match any
expression that `Grammar` does /not/ match.\n
+_not_ 模板最为简单。它接受一个语法作为模板参数，并在逻辑上否定
它；`not_<Grammar>` 将匹配 `Grammar` /不能/匹配的任意表达式。
+
+The _if_ template is used together with a Proto transform that is
evaluated against expression types to find matches. (Proto transforms will
be described later.)\n
+_if_ 模板与一个 Proto 变换一起使用，该变换对表达式类型进行求值以发现匹配
(Proto 变换将在稍后讨论)。
+
+The _and_ template is like _or_, except that each argument of the _and_
must match in order for the _and_ to match. As an example, consider the
definition of `CharString` above that uses _exact_. It could have been
written without _exact_ as follows:\n
+_and_ 模板类似于 _or_，不过 _and_ 的每个参数必须都匹配，_and_ 才能匹配。例
如，考虑前面那个使用 _exact_ 的 `CharString` 定义。
+它可以不用 _exact_，改写为：
struct CharString
: proto::and_<
@@ -860,21 +1019,31 @@
>
{};
-This says that a `CharString` must be a terminal, /and/ its value type
must be the same as `char const *`. Notice the template argument of _if_:
`boost::is_same< proto::_value, char const * >()`. This is Proto transform
that compares the value type of a terminal to `char const *`.
-
-The _if_ template has a couple of variants. In addition to
`if_<Condition>` you can also say `if_<Condition, ThenGrammar>` and
`if_<Condition, ThenGrammar, ElseGrammar>`. These let you select one
sub-grammar or another based on the `Condition`.
+This says that a `CharString` must be a terminal, /and/ its value type
must be the same as `char const *`. Notice the template argument of _if_:
`boost::is_same< proto::_value, char const * >()`. This is Proto transform
that compares the value type of a terminal to `char const *`.\n
+这是说，一个 `CharString` 必须是一个终结符，/且/它的值类型必须与 `char
const *` 相同。注意，_if_ 的模板参数：
+`boost::is_same< proto::_value, char const * >()`。这是一个 Proto 变换，它
将一个终结符的值类型与 `char const *` 进行比较。
+
+The _if_ template has a couple of variants. In addition to
`if_<Condition>` you can also say `if_<Condition, ThenGrammar>` and
`if_<Condition, ThenGrammar, ElseGrammar>`. These let you select one
sub-grammar or another based on the `Condition`.\n
+_if_ 模板有几个变体。除了 `if_<Condition>`，你还可以用 `if_<Condition,
ThenGrammar>` 和 `if_<Condition, ThenGrammar, ElseGrammar>`。
+它们让你基于 `Condition` 选择某个子语法或另一个子语法。
[endsect]
[/=======================================================]
-[section:switch Improving Compile Times With [^switch_<>]]
+[section:switch Improving Compile Times With [^switch_<>] 用[^switch_<>]改
进编译时间]
[/=======================================================]
-When your Proto grammar gets large, you'll start to run into some
scalability problems with _or_, the construct you use to specify alternate
sub-grammars. First, due to limitations in C++, _or_ can only accept up to
a certain number of sub-grammars, controlled by the
`BOOST_PROTO_MAX_LOGICAL_ARITY` macro. This macro defaults to eight, and
you can set it higher, but doing so will aggravate another scalability
problem: long compile times. With _or_, alternate sub-grammars are tried in
order -- like a series of cascading `if`'s -- leading to lots of
unnecessary template instantiations. What you would prefer instead is
something like `switch` that avoids the expense of cascading `if`'s. That's
the purpose of _switch_; although less convenient than _or_, it improves
compile times for larger grammars and does not have an arbitrary fixed
limit on the number of sub-grammars.
-
-Let's illustrate how to use _switch_ by first writing a big grammar with
_or_ and then translating it to an equivalent grammar using _switch_:
-
- // Here is a big, inefficient grammar
+When your Proto grammar gets large, you'll start to run into some
scalability problems with _or_, the construct you use to specify alternate
sub-grammars. First, due to limitations in C++, _or_ can only accept up to
a certain number of sub-grammars, controlled by the
`BOOST_PROTO_MAX_LOGICAL_ARITY` macro. This macro defaults to eight, and
you can set it higher, but doing so will aggravate another scalability
problem: long compile times. With _or_, alternate sub-grammars are tried in
order -- like a series of cascading `if`'s -- leading to lots of
unnecessary template instantiations. What you would prefer instead is
something like `switch` that avoids the expense of cascading `if`'s. That's
the purpose of _switch_; although less convenient than _or_, it improves
compile times for larger grammars and does not have an arbitrary fixed
limit on the number of sub-grammars. \n
+当你的 Proto 语法变大时，你将会开始陷入到 _or_ 所带来的一些可扩展性问题，它
是你用于指定可选子语法的结构。首先，由于C++的限制，
+_or_ 最多只能接受某个特定数量的子语法，这个数量由
`BOOST_PROTO_MAX_LOGICAL_ARITY` 宏控制。这个宏缺省为8，你可以设高一点，
+但是这样做会加剧另一个可扩展性问题：更长的编译时间。使用 _or_ 时，侯选的子
语法是按顺序尝试的 -- 就象一系列层叠的 `if` --
+导致了大量无用的模板实例化。你应该用一些类似于 `switch` 的东西来避免这些层
叠 `if` 的代价。这正是 _switch_ 的目的；
+虽然它不如 _or_ 方便，但是它在使用大量语法时改进了编译的时间，而且对于子语
法的数量也没有一个固定的限制。
+
+Let's illustrate how to use _switch_ by first writing a big grammar with
_or_ and then translating it to an equivalent grammar using _switch_:\n
+我们来示范一下如何使用 _switch_，首先写用 _or_ 写一个大语法，然后将它翻译为
使用 _switch_ 等价语法：
+
+ // Here is a big, inefficient grammar 以下是一个大的、低效的语法
struct ABigGrammar
: proto::or_<
proto::terminal<int>
@@ -892,23 +1061,27 @@
>
{};
-The above might be the grammar to a more elaborate calculator DSEL. Notice
that since there are more than eight sub-grammars, we had to chain the
sub-grammars with a nested _or_ -- not very nice.
-
-The idea behind _switch_ is to dispatch based on an expression's tag type
to a sub-grammar that handles expressions of that type. To use _switch_,
you define a struct with a nested `case_<>` template, specialized on tag
types. The above grammar can be expressed using _switch_ as follows. It is
described below.
+The above might be the grammar to a more elaborate calculator DSEL. Notice
that since there are more than eight sub-grammars, we had to chain the
sub-grammars with a nested _or_ -- not very nice.\n
+以上是为一个更为精细的计算器DSEL所编写的语法。注意，由于超过了8个子语法，所
以我们必须用嵌套的 _or_ 来串起这些子语法 -- 不够漂亮。
+
+The idea behind _switch_ is to dispatch based on an expression's tag type
to a sub-grammar that handles expressions of that type. To use _switch_,
you define a struct with a nested `case_<>` template, specialized on tag
types. The above grammar can be expressed using _switch_ as follows. It is
described below.\n
+在 _switch_ 背后的想法是，基于一个表达式的标签类型来分派到处理该类型的表达
式的子语法。要使用 _switch_，你要定义一个结构，
+该结构要有一个以标签类型作为参数的嵌套 `case_<>` 模板。上述语法可以用
_switch_ 表示如下。后面我们再讨论它。
// Redefine ABigGrammar more efficiently using proto::switch_<>
+ // 用 proto::switch_<> 重新定义一个更高效的 ABigGrammar
struct ABigGrammar;
struct ABigGrammarCases
{
- // The primary template matches nothing:
+ // The primary template matches nothing: 主模板不匹配东西：
template<typename Tag>
struct case_
: proto::not_<_>
{};
};
- // Terminal expressions are handled here
+ // Terminal expressions are handled here 终结符表达式在此处理
template<>
struct ABigGrammarCases::case_<proto::tag::terminal>
: proto::or_<
@@ -917,7 +1090,7 @@
>
{};
- // Non-terminals are handled similarly
+ // Non-terminals are handled similarly 非终结符类似地处理
template<>
struct ABigGrammarCases::case_<proto::tag::unary_plus>
: proto::unary_plus<ABigGrammar>
@@ -960,15 +1133,20 @@
// Define ABigGrammar in terms of ABigGrammarCases
// using proto::switch_<>
+ // 用 proto::switch_<> 根据 ABigGrammarCases 定义 ABigGrammar
struct ABigGrammar
: proto::switch_<ABigGrammarCases>
{};
-Matching an expression type `E` against `proto::switch_<C>` is equivalent
to matching it against `C::case_<E::proto_tag>`. By dispatching on the
expression's tag type, we can jump to the sub-grammar that handles
expressions of that type, skipping over all the other sub-grammars that
couldn't possibly match. If there is no specialization of `case_<>` for a
particular tag type, we select the primary template. In this case, the
primary template inherits from `proto::not_<_>` which matches no
expressions.
-
-Notice the specialization that handles terminals:
-
- // Terminal expressions are handled here
+Matching an expression type `E` against `proto::switch_<C>` is equivalent
to matching it against `C::case_<E::proto_tag>`. By dispatching on the
expression's tag type, we can jump to the sub-grammar that handles
expressions of that type, skipping over all the other sub-grammars that
couldn't possibly match. If there is no specialization of `case_<>` for a
particular tag type, we select the primary template. In this case, the
primary template inherits from `proto::not_<_>` which matches no
expressions.\n
+用 `proto::switch_<C>` 匹配某个表达式类型 `E`，相当于用
`C::case_<E::proto_tag>` 来匹配它。通过按表达式的标签类型来分派，
+我们可以跳至处理该类型的表达式的子语法，跳过其它所有不可能匹配的子语法。如
果某个特定标签类型没有相应的 `case_<>` 特化，
+则我们选择主模板。在这个例子中，主模板派生自 `proto::not_<_>`，它不匹配任何
表达式。
+
+Notice the specialization that handles terminals:\n
+留意处理终结符的特化：
+
+ // Terminal expressions are handled here 终结符表达式在此处理
template<>
struct ABigGrammarCases::case_<proto::tag::terminal>
: proto::or_<
@@ -977,9 +1155,11 @@
>
{};
-The `proto::tag::terminal` type by itself isn't enough to select an
appropriate sub-grammar, so we use _or_ to list the alternate sub-grammars
that match terminals.
-
-[note You might be tempted to define your `case_<>` specializations /in
situ/ as follows:
+The `proto::tag::terminal` type by itself isn't enough to select an
appropriate sub-grammar, so we use _or_ to list the alternate sub-grammars
that match terminals.\n
+类型 `proto::tag::terminal` 本身不足以选择一个合适的子语法，所以我们用
_or_ 来列出匹配终结符的候选子语法。
+
+[note You might be tempted to define your `case_<>` specializations /in
situ/ as follows:\n
+你可能会象下面这样/在原地/定义你的 `case_<>` 特化：
``
struct ABigGrammarCases
@@ -987,62 +1167,75 @@
template<typename Tag>
struct case_ : proto::not_<_> {};
- // ERROR: not legal C++
+ // ERROR: not legal C++ 错误：不是合法的C++
template<>
struct case_<proto::tag::terminal>
/* ... */
};
``
-Unfortunately, for arcane reasons, it is not legal to define an explicit
nested specialization /in situ/ like this. It is, however, perfectly legal
to define /partial/ specializations /in situ/, so you can add a extra dummy
template parameter that has a default, as follows:
+Unfortunately, for arcane reasons, it is not legal to define an explicit
nested specialization /in situ/ like this. It is, however, perfectly legal
to define /partial/ specializations /in situ/, so you can add a extra dummy
template parameter that has a default, as follows:\n
+不幸的是，由于某些原因，象这样/在原地/定义一个显式的嵌套特化是不合法的。但
是，/在原地/定义/偏/特化则是合法的，
+所以你可以象下面这样增加一个有缺省值的哑模板参数：
``
struct ABigGrammarCases
{
// Note extra "Dummy" template parameter here:
+ // 注意这里加了一个"哑"的模板参数：
template<typename Tag, int Dummy = 0>
struct case_ : proto::not_<_> {};
// OK: "Dummy" makes this a partial specialization
// instead of an explicit specialization.
+ // 可以："哑"参数使得这是一个偏特化而不是显式特化。
template<int Dummy>
struct case_<proto::tag::terminal, Dummy>
/* ... */
};
``
-You might find this cleaner than defining explicit `case_<>`
specializations outside of their enclosing struct.
+You might find this cleaner than defining explicit `case_<>`
specializations outside of their enclosing struct.\n
+也许你会发现这种方法比在结构外部定义显式的 `case_<>` 特化更为清晰。
]
***The diff for this file has been truncated for email.***
=======================================
--- /trunk/libs/proto/doc/preface.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/preface.qbk Sun Jan 17 23:11:16 2010
@@ -5,65 +5,91 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section Preface]
+[section:perface Preface 前言]
[:["There are more things in heaven and earth, Horatio, than are dreamt of
in your
philosophy.]]
[:[*['-- William Shakespeare]]]
-[heading Description]
+[heading Description 概述]
Proto is a framework for building Domain Specific Embedded Languages in
C++. It provides tools for constructing, type-checking, transforming and
executing ['expression templates][footnote See
[@http://www.osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html
Expression Templates]].
-More specifically, Proto provides:
-
-* An expression tree data structure.
-* A mechanism for giving expressions additional behaviors and members.
-* Operator overloads for building the tree from an expression.
-* Utilities for defining the grammar to which an expression must conform.
-* An extensible mechanism for immediately executing an expression template.
-* An extensible set of tree transformations to apply to expression trees.
-
-[heading Motivation]
-
-Expression Templates are an advanced technique that C++ library developers
use to define embedded mini-languages that target specific problem domains.
The technique has been used to create efficient and easy-to-use libraries
for linear algebra as well as to define C++ parser generators with a
readable syntax. But developing such a library involves writing an
inordinate amount of unreadable and unmaintainable template mumbo-jumbo.
Boost.Proto eases the development of [link
boost_proto.users_guide.glossary.dsel domain-specific embedded languages
(DSELs)]. Use Proto to define the primitives of your mini-language and let
Proto handle the operator overloading and the construction of the
expression parse tree. Immediately evaluate the expression tree by passing
it a function object. Or transform the expression tree by defining the
grammar of your mini-language, decorated with an assortment of tree
transforms provided by Proto or defined by you. Then use the grammar to
give your users short and readable syntax errors for invalid expressions!
No more mumbo-jumbo -- an expression template library developed with Proto
is declarative and readable.
-
-In short, Proto is a DSEL for defining DSELs.
+More specifically, Proto provides:\n
+Proto 是一个在C++中构建专用领域嵌入式语言的框架。它提供了构造、类型检查、转
化和执行 ['表达式模板] 的工具。具体地说，Proto 提供了：
+
+* An expression tree data structure.\n
+ 一个表达式树的数据结构。
+* A mechanism for giving expressions additional behaviors and members.\n
+ 一个为给定的表达式添加行为和成员的机制。
+* Operator overloads for building the tree from an expression.\n
+ 从一个表达式构建表达式树所需的操作符重载。
+* Utilities for defining the grammar to which an expression must conform.\n
+ 对表达式必须遵守的语法进行定义的工具。
+* An extensible mechanism for immediately executing an expression
template.\n
+ 一个可扩展的机制，用于立即执行一个表达式模板。
+* An extensible set of tree transformations to apply to expression trees.\n
+ 一个应用于表达式树的，可扩展的树转化操作集。
+
+[heading Motivation 动机]
+
+Expression Templates are an advanced technique that C++ library developers
use to define embedded mini-languages that target specific problem domains.
The technique has been used to create efficient and easy-to-use libraries
for linear algebra as well as to define C++ parser generators with a
readable syntax. But developing such a library involves writing an
inordinate amount of unreadable and unmaintainable template mumbo-jumbo.
Boost.Proto eases the development of [link
boost_proto.users_guide.glossary.dsel domain-specific embedded languages
(DSELs)]. Use Proto to define the primitives of your mini-language and let
Proto handle the operator overloading and the construction of the
expression parse tree. Immediately evaluate the expression tree by passing
it a function object. Or transform the expression tree by defining the
grammar of your mini-language, decorated with an assortment of tree
transforms provided by Proto or defined by you. Then use the grammar to
give your users short and readable syntax errors for invalid expressions!
No more mumbo-jumbo -- an expression template library developed with Proto
is declarative and readable.\n
+表达式模板是一种高级技术，C++库开发者所使用它来定义以某个特定问题域为目标的
嵌入式小型语言。该技术已被用于创建高效且易用的线性代数库，
+还被用于以可读的语法来定义 C++ 分析器的生成器。但是，开发这样一个库需要编写
大量难以阅读且难以维护的模板。Boost.Proto 使得
+[link boost_proto.users_guide.glossary.dsel 专用领域嵌入式语言(DSELs)] 的开
发变得容易。使用 Proto 来定义你的小型语言的基本组件，
+并让 Proto 处理操作符的重载和表达式分析树的构造。通过将表达式树传递给一个函
数对象，可以立即对它进行求值。
+或者通过定义定义你的小型语言的语法，再以由 Proto 所提供的或由你定义的各种各
样的树变换操作来对表达式树进行变换。然后，
+使用该语法给你的用户带来对无效表达式的简短易读的语法错误提示！没有更多的繁
文缛节了 --
+用 Proto 开发出来的表达式模板库是具有宣示性和可读性的。
+
+In short, Proto is a DSEL for defining DSELs.\n
+简而言之，Proto 是一个用于定义 DSELs 的 DSEL。
[/====================================]
-[heading How to Use This Documentation]
+[heading How to Use This Documentation 如何使用本文档]
[/====================================]
-This documentation makes use of the following naming and formatting
conventions.
-
-* Code is in `fixed width font` and is syntax-highlighted.
-* Replaceable text that you will need to supply is in [~italics].
+This documentation makes use of the following naming and formatting
conventions.\n
+本文档使用了以下命名约定和格式约定。
+
+* Code is in `fixed width font` and is syntax-highlighted.\n
+ 代码采用 `fixed width font` 并具有语法高亮。
+* Replaceable text that you will need to supply is in [~italics].\n
+ 要由你提供的可替换文本采用 [~italics]。
* If a name refers to a free function, it is specified like this:
`free_function()`; that is, it is in code font and its name is followed
by `()`
- to indicate that it is a free function.
+ to indicate that it is a free function.\n
+ 如果某个名字代表一个普通函数，则写为：`free_function()`; 即采用代码的字体
并在名字后跟 `()` 以表示它是一个普通函数。
* If a name refers to a class template, it is specified like this:
`class_template<>`; that is, it is in code font and its name is followed
by `<>`
- to indicate that it is a class template.
+ to indicate that it is a class template.\n
+ 如果某个名字代表一个类模板，则写为：`class_template<>`; 即采用代码的字体
并在名字后跟 `<>` 以表示它是一个类模板。
* If a name refers to a function-like macro, it is specified like this:
`MACRO()`;
that is, it is uppercase in code font and its name is followed by `()` to
indicate that it is a function-like macro. Object-like macros appear
without the
- trailing `()`.
+ trailing `()`.\n
+ 如果某个名字代表一个类似于函数的宏，则写为：`MACRO()`; 即采用代码字体的大
写并在名字后跟 `()` 以表示它是一个类似于函数的宏。
+ 类似于对象的宏则没有后面的 `()`。
* Names that refer to /concepts/ in the generic programming sense are
- specified in CamelCase.
+ specified in CamelCase.\n
+ 代表泛型编程意义上的 /概念/ 的名字则以 CamelCase 表示。
[note In addition, notes such as this one specify non-essential
information that
-provides additional background or rationale.]
-
-Finally, you can mentally add the following to any code fragments in this
document:
-
- // Include all of Proto
+provides additional background or rationale.\n
+此外，象这样的备注则用于指定非必要的信息，以提供额外的背景或原理的说明。]
+
+Finally, you can mentally add the following to any code fragments in this
document:\n
+最后，在本文档中的所有代码片断中，你都可以认为已经增加了以下代码：
+
+ // Include all of Proto 包含Proto的所有
#include <boost/proto/proto.hpp>
- // Create some namespace aliases
+ // Create some namespace aliases 创建一些名字空间别名
namespace mpl = boost::mpl;
namespace fusion = boost::fusion;
namespace proto = boost::proto;
// Allow unqualified use of Proto's wildcard pattern
+ // 允许不加限定词地使用Proto的通配符模式
using proto::_;
[endsect]
=======================================
--- /trunk/libs/proto/doc/proto.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/proto.qbk Sun Jan 17 23:11:16 2010
@@ -231,31 +231,43 @@
[include preface.qbk]
[/===============================]
-[section:users_guide Users' Guide]
+[section:users_guide Users' Guide 用户指南]
[/===============================]
[/===========================================================]
-[heading Compilers, Compiler Construction Toolkits, and Proto]
+[heading Compilers, Compiler Construction Toolkits, and Proto 编译器，编译
器构造工具，和 Proto]
[/===========================================================]
-Most compilers have front ends and back ends. The front end parses the
text of an input program into some intermediate form like an abstract
syntax tree, and the back end takes the intermediate form and generates an
executable from it.
-
-A library built with Proto is essentially a compiler for a domain-specific
embedded language (DSEL). It also has a front end, an intermediate form,
and a back end. The front end is comprised of the symbols (a.k.a.,
terminals), members, operators and functions that make up the user-visible
aspects of the DSEL. The back end is made of evaluation contexts and
transforms that give meaning and behavior to the expression templates
generated by the front end. In between is the intermediate form: the
expression template itself, which is an abstract syntax tree in a very real
sense.
-
-To build a library with Proto, you will first decide what your interface
will be; that is, you'll design a programming language for your domain and
build the front end with tools provided by Proto. Then you'll design the
back end by writing evaluation contexts and/or transforms that accept
expression templates and do interesting things with them.
-
-This users' guide is organized as follows. After a [link
boost_proto.users_guide.getting_started Getting Started guide], we'll cover
the tools Proto provides for defining and manipulating the three major
parts of a compiler:
+Most compilers have front ends and back ends. The front end parses the
text of an input program into some intermediate form like an abstract
syntax tree, and the back end takes the intermediate form and generates an
executable from it.\n
+多数编译器都具有前端和后端。前端负责将输入的程序进行解析为一些中间格式，如
抽象语法树，而后端则接受这些中间格式并由它生成一个可执行文件。
+
+A library built with Proto is essentially a compiler for a domain-specific
embedded language (DSEL). It also has a front end, an intermediate form,
and a back end. The front end is comprised of the symbols (a.k.a.,
terminals), members, operators and functions that make up the user-visible
aspects of the DSEL. The back end is made of evaluation contexts and
transforms that give meaning and behavior to the expression templates
generated by the front end. In between is the intermediate form: the
expression template itself, which is an abstract syntax tree in a very real
sense.\n
+一个以 Proto 构建的库实质上是某种领域专用嵌入式语言(DSEL)的编译器。它也有前
端、中间格式和后端。前端由符号(又称终结符)、成员、
+操作符以及弥补DSEL的用户可见性方面的函数组成。后端则由求值上下文和变换构
成，为前端所生成的表达式模板赋予意义和行为。
+在两者中间则是中间格式：表达式模板本身，它是非常现实的意义下的抽象语法树。
+
+To build a library with Proto, you will first decide what your interface
will be; that is, you'll design a programming language for your domain and
build the front end with tools provided by Proto. Then you'll design the
back end by writing evaluation contexts and/or transforms that accept
expression templates and do interesting things with them.\n
+要用 Proto 来构建一个库，你首先要决定你的接口是什么样的；即你要为你的问题域
设计一个编程语言，并使用 Proto 所提供的工具构建前端。
+然后，你要通过编写求值上下文和/或接受表达式模板并对它们做一些有意义的事情的
变换操作来设计后端。
+
+This users' guide is organized as follows. After a [link
boost_proto.users_guide.getting_started Getting Started guide], we'll cover
the tools Proto provides for defining and manipulating the three major
parts of a compiler:\n
+这个用户指南组织如下。在一个 [link boost_proto.users_guide.getting_started
入门指南] 之后，我们将介绍 Proto 所提供的工具，
+它们用于定义和操纵一个编译器的三个主要部分：
[variablelist
- [[[link boost_proto.users_guide.front_end Front Ends]]
- [How to define the aspects of your DSEL with which your users will
interact directly.]]
- [[[link boost_proto.users_guide.intermediate_form Intermediate Form]]
- [What Proto expression templates look like, how to discover their
structure and access their constituents.]]
- [[[link boost_proto.users_guide.back_end Back Ends]]
- [How to define evaluation contexts and transforms that make expression
templates do interesting things.]]
+ [[[link boost_proto.users_guide.front_end Front Ends 前端]]
+ [How to define the aspects of your DSEL with which your users will
interact directly.\n
+ 如何定义你的DSEL与用户直接交互的外貌。]]
+ [[[link boost_proto.users_guide.intermediate_form Intermediate Form 中间
格式]]
+ [What Proto expression templates look like, how to discover their
structure and access their constituents.\n
+ Proto 表达式模板看起来是什么样的，如何发现其结构及访问其中的要素。]]
+ [[[link boost_proto.users_guide.back_end Back Ends 后端]]
+ [How to define evaluation contexts and transforms that make expression
templates do interesting things.\n
+ 如何定义求值上下文和变换，让表达式模板做有意义的事。]]
]
-After that, you may be interested in seeing some [link
boost_proto.users_guide.examples Examples] to get a better idea of how the
pieces all fit together.
+After that, you may be interested in seeing some [link
boost_proto.users_guide.examples Examples] to get a better idea of how the
pieces all fit together.\n
+在此之后，你将看到一些 [link boost_proto.users_guide.examples 例子]，可以对
这部组成部分如何很好地合起来有更好的认识。
[include getting_started.qbk]
@@ -276,7 +288,7 @@
[xinclude reference.xml]
[/=================]
-[section Appendices]
+[section:appendices Appendices 附录]
[/=================]
[include history.qbk]
=======================================
--- /trunk/libs/proto/doc/rationale.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/rationale.qbk Sun Jan 17 23:11:16 2010
@@ -5,13 +5,14 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[section:rationale Appendix B: Rationale]
+[section:rationale Appendix B: Rationale 附录B：基本原理]
[/==================================================]
-[section:static_initialization Static Initialization]
+[section:static_initialization Static Initialization 静态初始化]
[/==================================================]
-Proto expression types are PODs (Plain Old Data), and do not have
constructors. They are brace-initialized, as follows:
+Proto expression types are PODs (Plain Old Data), and do not have
constructors. They are brace-initialized, as follows:\n
+Proto 表达式类型是POD(旧的平面数据)，不带构造函数。它们可以用花括号来初始
化，如下：
terminal<int>::type const _i = {1};
@@ -21,12 +22,16 @@
`_2` from the Boost Lambda Library. Were these object to require run-time
initialization, it might be possible to use these objects before they are
initialized. That would be bad. Statically initialized objects cannot be
misused
-that way.
+that way.\n
+其原因是，这样象上面的 `_i` 这样的表达式对象就可以['被静态初始化]。为什么静
态初始化这么重要？
+许多领域专用嵌入式语言的终结符很可能是全局的常量对象，如 Bosot Lambda 库中
的 `_1` 和 `_2`。
+如果这些对象要在运行期初始化的话，对象就可能会在初始化之前被使用。这是有问
题的。
+静态初始化的对象不会发生这种问题。
[endsect]
[/=========================================================]
-[section:preprocessor Why Not Reuse MPL, Fusion, et cetera?]
+[section:preprocessor Why Not Reuse MPL, Fusion, et cetera? 为何不重用
MPL, Fusion 等？]
[/=========================================================]
Anyone who has peeked at Proto's source code has probably wondered, "Why
all the
@@ -38,13 +43,21 @@
possible. That is achieved by prefering preprocessor metaprogramming to
template
metaprogramming. Expanding a macro is far more efficient than
instantiating a
template. In some cases, the "clean" version takes 10x longer to compile
than the
-"dirty" version.
+"dirty" version.\n
+任何一个看过Proto源代码的人都可能会觉得奇怪，"为什么到处是难看的预处理器语
句？
+不能使用象MPL和Fusion这样的库来实现得更漂亮吗？"答案是，Proto可以用这些方法
来实现，
+事实上也曾经如此。问题是模板元编程(TMP)需要较长的编译时间。作为其它重度使用
TMP的库的构建基础，
+Proto本身应该尽可能轻量。这需要通过预处理器元编程而不是模板元编程来实现。
+展开一个宏要比实例化一个模板高效得多。在某些情形下，"漂亮"版要比"难看"版多
花10倍以上的编译时间。
The "clean and slow" version of Proto can still be found at
http://svn.boost.org/svn/boost/branches/proto/v3. Anyone who is interested
can
download it and verify that it is, in fact, unusably slow to compile. Note
that
this branch's development was abandoned, and it does not conform exactly
with
-Proto's current interface.
+Proto's current interface.\n
+"漂亮且慢"的Proto版本仍然可以在
http://svn.boost.org/svn/boost/branches/proto/v3 中找到。
+有兴趣的读者可以下载它，并且看看它在编译时是否不一般地慢。注意，这一分支的
开发已经不再继续，
+它并不完全符合当前的Proto接口。
[endsect]
=======================================
--- /trunk/libs/proto/doc/resources.qbk Mon Dec 28 23:05:14 2009
+++ /trunk/libs/proto/doc/resources.qbk Sun Jan 17 23:11:16 2010
@@ -6,7 +6,7 @@
/]
[/=========================================]
-[section:resources Background and Resources]
+[section:resources Background and Resources 背景和资源]
[/=========================================]
Proto was initially developed as part of _xpressive_ to simplify the job of
@@ -14,32 +14,42 @@
of matching a regular expression. Since then, Proto has found application
in the
redesigned and improved Spirit-2 and the related Karma library. As a
result of
these efforts, Proto evolved into a generic and abstract grammar and tree
-transformation framework applicable in a wide variety of DSEL scenarios.
+transformation framework applicable in a wide variety of DSEL scenarios.\n
+起初，Proto是作为 _xpressive_ 的一部分来开发的，目的是简化把一个表达式模板
转换为一个与正则表达式能力相当的、
+可执行的有限状态机的工作。此后，我们发现Proto也可以在对 Spirit-2以及相关的
Karma库的重新设计和改进中得以应用。
+由于这些努力，Proto进化为一个通用且抽象的语法及树变换框架，可以应用于广泛的
DSEL设计与开发中。
The grammar and tree transformation framework is modeled on Spirit's
grammar and
semantic action framework. The expression tree data structure is similar
to Fusion
data structures in many respects, and is interoperable with Fusion's
iterators and
-algorithms.
+algorithms.\n
+这个语法和树变换的框架模仿了Spirit的语法和语义动作框架。其中的表达式树结构
在许多方面类似于Fusion数据结构，
+并且可以与Fusion的迭代器及算法相互操作。
The syntax for the grammar-matching features of `proto::matches<>` is
inspired by
-MPL's lambda expressions.
+MPL's lambda expressions.\n
+用于 `proto::matches<>` 的语法匹配特性的语法，其灵感来自于MPL的lambda表达
式。
The idea for using function types for Proto's composite transforms is
inspired by Aleksey Gurtovoy's
-[@http://lists.boost.org/Archives/boost/2002/11/39718.php "round" lambda]
notation.
+[@http://lists.boost.org/Archives/boost/2002/11/39718.php "round" lambda]
notation.\n
+用函数类型来进行Proto的变换组合这一思想，其灵感来自于Aleksey Gurtovoy的
+[@http://lists.boost.org/Archives/boost/2002/11/39718.php "round" lambda]
记号。
[/=================]
-[heading References]
+[heading References 参考文献]
[/=================]
[:[#boost_proto.users_guide.resources.SYB]Ren, D. and Erwig, M. 2006. A
generic recursion toolbox for Haskell or: scrap your boilerplate
systematically. In ['Proceedings of the 2006 ACM SIGPLAN Workshop on
Haskell] (Portland, Oregon, USA, September 17 - 17, 2006). Haskell '06.
ACM, New York, NY, 13-24. DOI=[@http://doi.acm.org/10.1145/1159842.1159845]]
[/======================]
-[heading Further Reading]
+[heading Further Reading 更进一步的读物]
[/======================]
A technical paper about an earlier version of Proto was accepted into the
[@http://lcsd.cs.tamu.edu/2007/ ACM SIGPLAN Symposium on Library-Centric
Software
Design LCSD'07], and can be found at
[@http://lcsd.cs.tamu.edu/2007/final/1/1_Paper.pdf].
-The tree transforms described in that paper differ from what exists today.
+The tree transforms described in that paper differ from what exists
today.\n
+有关Proto早期版本的一篇技术论文被收录在 [@http://lcsd.cs.tamu.edu/2007/
ACM SIGPLAN Symposium on Library-Centric Software
+Design LCSD'07]，可以在
[@http://lcsd.cs.tamu.edu/2007/final/1/1_Paper.pdf] 中找到。在该论文中所描述
的树变换与现在的实现有所不同。
[endsect]
Other related posts:
- » [boost-doc-zh] r368 committed - 翻译 program_options, proto 库的xml/qbk文件 - boost-doc-zh
