3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Appendices</title>
5 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8 <link rel="up" href="../proto.html" title="Chapter 23. Boost.Proto">
9 <link rel="prev" href="../Transform.html" title="Concept Transform">
10 <link rel="next" href="../boost_random.html" title="Chapter 24. Boost.Random">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15 <td align="center"><a href="../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="../Transform.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../proto.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../boost_random.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
27 <a name="proto.appendices"></a><a class="link" href="appendices.html" title="Appendices">Appendices</a>
28 </h2></div></div></div>
29 <div class="toc"><dl class="toc">
30 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.release_notes">Appendix A: Release
32 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.history">Appendix B: History</a></span></dt>
33 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.rationale">Appendix C: Rationale</a></span></dt>
34 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.implementation">Appendix D: Implementation
36 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.acknowledgements">Appendix E:
37 Acknowledgements</a></span></dt>
40 <div class="titlepage"><div><div><h3 class="title">
41 <a name="boost_proto.appendices.release_notes"></a><a class="link" href="appendices.html#boost_proto.appendices.release_notes" title="Appendix A: Release Notes">Appendix A: Release
43 </h3></div></div></div>
45 <a name="boost_proto.appendices.release_notes.h0"></a>
46 <span class="phrase"><a name="boost_proto.appendices.release_notes.boost_1_51"></a></span><a class="link" href="appendices.html#boost_proto.appendices.release_notes.boost_1_51">Boost
50 <span class="bold"><strong>Unpacking Expressions</strong></span>
53 In Boost 1.51, Proto got simple unpacking patterns. When working with Proto
54 transforms, unpacking expressions are useful for unpacking the children of
55 an expression into a function call or an object constructor, while optionally
56 applying some transformations to each child in turn.
59 See the <a class="link" href="users_guide.html#boost_proto.users_guide.back_end.expression_transformation.unpacking_expressions" title="Unpacking Expressions">Unpacking
60 Expressions</a> section for more information.
63 <a name="boost_proto.appendices.release_notes.h1"></a>
64 <span class="phrase"><a name="boost_proto.appendices.release_notes.boost_1_44"></a></span><a class="link" href="appendices.html#boost_proto.appendices.release_notes.boost_1_44">Boost
68 <span class="bold"><strong>Behavior Change: proto::and_<></strong></span>
71 In Boost 1.44, the behavior of <code class="computeroutput"><a class="link" href="../boost/proto/and_.html" title="Struct template and_">proto::and_<></a></code>
72 as a transform changed. Previously, it only applied the transform associated
73 with the last grammar in the set. Now, it applies all the transforms but
74 only returns the result of the last. That makes it behave like C++'s comma
75 operator. For example, a grammar such as:
77 <pre class="programlisting"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">and_</span><span class="special"><</span> <span class="identifier">G0</span><span class="special">,</span> <span class="identifier">G1</span><span class="special">,</span> <span class="identifier">G2</span> <span class="special">></span>
80 when evaluated with an expression <code class="computeroutput"><span class="identifier">e</span></code>
81 now behaves like this:
83 <pre class="programlisting"><span class="special">((</span><span class="keyword">void</span><span class="special">)</span><span class="identifier">G0</span><span class="special">()(</span><span class="identifier">e</span><span class="special">),</span> <span class="special">(</span><span class="keyword">void</span><span class="special">)</span><span class="identifier">G1</span><span class="special">()(</span><span class="identifier">e</span><span class="special">),</span> <span class="identifier">G2</span><span class="special">()(</span><span class="identifier">e</span><span class="special">))</span>
85 <div class="note"><table border="0" summary="Note">
87 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
88 <th align="left">Note</th>
90 <tr><td align="left" valign="top"><p>
91 Why the void casts? It's to avoid argument-dependent lookup, which might
92 find an overloaded comma operator.
96 <span class="bold"><strong>Behavior Change: proto::as_expr() and proto::as_child()</strong></span>
99 The functions <code class="computeroutput"><a class="link" href="../boost/proto/as_expr_idp227626032.html" title="Function as_expr">proto::as_expr()</a></code> and <code class="computeroutput"><a class="link" href="../boost/proto/as_child_idp227648000.html" title="Function as_child">proto::as_child()</a></code>
100 are used to guarantee that an object is a Proto expression by turning it
101 into one if it is not already, using an optionally specified domain. In previous
102 releases, when these functions were passed a Proto expression in a domain
103 different to the one specified, they would apply the specified domain's generator,
104 resulting in a twice-wrapped expression. This behavior was surprising to
108 The new behavior of these two functions is to always leave Proto expressions
109 alone, regardless of the expressions' domains.
112 <span class="bold"><strong>Behavior Change: proto::(pod_)generator<> and
113 proto::basic_expr<></strong></span>
116 Users familiar with Proto's extension mechanism have probably used either
117 <code class="computeroutput"><a class="link" href="../boost/proto/generator.html" title="Struct template generator">proto::generator<></a></code> or <code class="computeroutput"><a class="link" href="../boost/proto/pod_generator.html" title="Struct template pod_generator">proto::pod_generator<></a></code>
118 with a wrapper template when defining their domain. In the past, Proto would
119 instantiate your wrapper template with instances of <code class="computeroutput"><a class="link" href="../boost/proto/expr.html" title="Struct template expr">proto::expr<></a></code>.
120 In Boost 1.44, Proto now instantiates your wrapper template with instances
121 of a new type: <code class="computeroutput"><a class="link" href="../boost/proto/basic_expr.html" title="Struct template basic_expr">proto::basic_expr<></a></code>.
126 <pre class="programlisting"><span class="comment">// An expression wrapper</span>
127 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Expr</span><span class="special">></span>
128 <span class="keyword">struct</span> <span class="identifier">my_expr_wrapper</span><span class="special">;</span>
130 <span class="comment">// A domain</span>
131 <span class="keyword">struct</span> <span class="identifier">my_domain</span>
132 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">domain</span><span class="special"><</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">generator</span><span class="special"><</span> <span class="identifier">my_expr_wrapper</span> <span class="special">></span> <span class="special">></span>
133 <span class="special">{};</span>
135 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Expr</span><span class="special">></span>
136 <span class="keyword">struct</span> <span class="identifier">my_expr_wrapper</span>
137 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">extends</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">,</span> <span class="identifier">my_expr_wrapper</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">>,</span> <span class="identifier">my_domain</span><span class="special">></span>
138 <span class="special">{</span>
139 <span class="comment">// Before 1.44, Expr was an instance of proto::expr<></span>
140 <span class="comment">// In 1.44, Expr is an instance of proto::basic_expr<></span>
141 <span class="special">};</span>
144 The motivation for this change was to improve compile times. <code class="computeroutput"><a class="link" href="../boost/proto/expr.html" title="Struct template expr">proto::expr<></a></code>
145 is an expensive type to instantiate because it defines a host of member functions.
146 When defining your own expression wrapper, the instance of <code class="computeroutput"><a class="link" href="../boost/proto/expr.html" title="Struct template expr">proto::expr<></a></code>
147 sits as a hidden data member function in your wrapper and the members of
148 <code class="computeroutput"><a class="link" href="../boost/proto/expr.html" title="Struct template expr">proto::expr<></a></code> go unused. Therefore,
149 the cost of those member functions is wasted. In contrast, <code class="computeroutput"><a class="link" href="../boost/proto/basic_expr.html" title="Struct template basic_expr">proto::basic_expr<></a></code>
150 is a very lightweight type with no member functions at all.
153 The vast majority of programs should recompile without any source changes.
154 However, if somewhere you are assuming that you will be given instances specifically
155 of <code class="computeroutput"><a class="link" href="../boost/proto/expr.html" title="Struct template expr">proto::expr<></a></code>, your code will break.
158 <span class="bold"><strong>New Feature: Sub-domains</strong></span>
161 In Boost 1.44, Proto introduces an important new feature called "sub-domains".
162 This gives you a way to spcify that one domain is compatible with another
163 such that expressions in one domain can be freely mixed with expressions
164 in another. You can define one domain to be the sub-domain of another by
165 using the third template parameter of <code class="computeroutput"><a class="link" href="../boost/proto/domain.html" title="Struct template domain">proto::domain<></a></code>.
170 <pre class="programlisting"><span class="comment">// Not shown: define some expression</span>
171 <span class="comment">// generators genA and genB</span>
173 <span class="keyword">struct</span> <span class="identifier">A</span>
174 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">domain</span><span class="special"><</span> <span class="identifier">genA</span><span class="special">,</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">_</span> <span class="special">></span>
175 <span class="special">{};</span>
177 <span class="comment">// Define a domain B that is the sub-domain</span>
178 <span class="comment">// of domain A.</span>
179 <span class="keyword">struct</span> <span class="identifier">B</span>
180 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">domain</span><span class="special"><</span> <span class="identifier">genB</span><span class="special">,</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">_</span><span class="special">,</span> <span class="identifier">A</span> <span class="special">></span>
181 <span class="special">{};</span>
184 Expressions in domains <code class="computeroutput"><span class="identifier">A</span></code>
185 and <code class="computeroutput"><span class="identifier">B</span></code> can have different
186 wrappers (hence, different interfaces), but they can be combined into larger
187 expressions. Without a sub-domain relationship, this would have been an error.
188 The domain of the resulting expression in this case would be <code class="computeroutput"><span class="identifier">A</span></code>.
191 The complete description of sub-domains can be found in the reference sections
192 for <code class="computeroutput"><a class="link" href="../boost/proto/domain.html" title="Struct template domain">proto::domain<></a></code> and <code class="computeroutput"><a class="link" href="../boost/proto/deduce_domain.html" title="Struct deduce_domain">proto::deduce_domain</a></code>.
195 <span class="bold"><strong>New Feature: Domain-specific as_expr() and as_child()</strong></span>
198 Proto has always allowed users to customize expressions post-hoc by specifying
199 a Generator when defining their domain. But it has never allowed users to
200 control how Proto assembles sub-expressions in the first place. As of Boost
201 1.44, users now have this power.
204 Users defining their own domain can now specify how <code class="computeroutput"><a class="link" href="../boost/proto/as_expr_idp227626032.html" title="Function as_expr">proto::as_expr()</a></code>
205 and <code class="computeroutput"><a class="link" href="../boost/proto/as_child_idp227648000.html" title="Function as_child">proto::as_child()</a></code> work in their domain. They
206 can do this easily by defining nested class templates named <code class="computeroutput"><span class="identifier">as_expr</span></code> and/or <code class="computeroutput"><span class="identifier">as_child</span></code>
207 within their domain class.
212 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_domain</span>
213 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">domain</span><span class="special"><</span> <span class="identifier">my_generator</span> <span class="special">></span>
214 <span class="special">{</span>
215 <span class="keyword">typedef</span>
216 <span class="identifier">proto</span><span class="special">::</span><span class="identifier">domain</span><span class="special"><</span> <span class="identifier">my_generator</span> <span class="special">></span>
217 <span class="identifier">base_domain</span><span class="special">;</span>
219 <span class="comment">// For my_domain, as_child does the same as</span>
220 <span class="comment">// what as_expr does by default.</span>
221 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
222 <span class="keyword">struct</span> <span class="identifier">as_child</span>
223 <span class="special">:</span> <span class="identifier">base_domain</span><span class="special">::</span><span class="identifier">as_expr</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span>
224 <span class="special">{};</span>
225 <span class="special">};</span>
228 In the above example, <code class="computeroutput"><span class="identifier">my_domain</span><span class="special">::</span><span class="identifier">as_child</span><span class="special"><></span></code> simply defers to <code class="computeroutput"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">domain</span><span class="special">::</span><span class="identifier">as_expr</span><span class="special"><></span></code>. This has the nice effect of causing
229 all terminals to be captured by value instead of by reference, and to likewise
230 store child expressions by value. The result is that expressions in <code class="computeroutput"><span class="identifier">my_domain</span></code> are safe to store in <code class="computeroutput"><span class="keyword">auto</span></code> variables because they will not have
231 dangling references to intermediate temporary expressions. (Naturally, it
232 also means that expression construction has extra runtime overhead of copying
233 that the compiler may or may not be able to optimize away.)
236 <a name="boost_proto.appendices.release_notes.h2"></a>
237 <span class="phrase"><a name="boost_proto.appendices.release_notes.boost_1_43"></a></span><a class="link" href="appendices.html#boost_proto.appendices.release_notes.boost_1_43">Boost
241 In Boost 1.43, the recommended usage of <code class="computeroutput"><a class="link" href="../boost/proto/extends.html" title="Struct template extends">proto::extends<></a></code>
242 changed slightly. The new usage looks like this:
244 <pre class="programlisting"><span class="comment">// my_expr is an expression extension of the Expr parameter</span>
245 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Expr</span><span class="special">></span>
246 <span class="keyword">struct</span> <span class="identifier">my_expr</span>
247 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">extends</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">,</span> <span class="identifier">my_expr</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">>,</span> <span class="identifier">my_domain</span><span class="special">></span>
248 <span class="special">{</span>
249 <span class="identifier">my_expr</span><span class="special">(</span><span class="identifier">Expr</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">expr</span> <span class="special">=</span> <span class="identifier">Expr</span><span class="special">())</span>
250 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">extends</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">,</span> <span class="identifier">my_expr</span><span class="special">,</span> <span class="identifier">my_domain</span><span class="special">>(</span><span class="identifier">expr</span><span class="special">)</span>
251 <span class="special">{}</span>
253 <span class="comment">// NEW: use the following macro to bring</span>
254 <span class="comment">// proto::extends::operator= into scope.</span>
255 <span class="identifier">BOOST_PROTO_EXTENDS_USING_ASSIGN</span><span class="special">(</span><span class="identifier">my_expr</span><span class="special">)</span>
256 <span class="special">};</span>
259 The new thing is the use of the <code class="literal"><code class="computeroutput"><a class="link" href="../BOOST_PROTO_EXTENDS_USING_ASSIGN.html" title="Macro BOOST_PROTO_EXTENDS_USING_ASSIGN">BOOST_PROTO_EXTENDS_USING_ASSIGN</a></code>()</code>
260 macro. To allow assignment operators to build expression trees, <code class="computeroutput"><a class="link" href="../boost/proto/extends.html" title="Struct template extends">proto::extends<></a></code> overloads the assignment
261 operator. However, for the <code class="computeroutput"><span class="identifier">my_expr</span></code>
262 template, the compiler generates a default copy assignment operator that
263 hides the ones in <code class="computeroutput"><a class="link" href="../boost/proto/extends.html" title="Struct template extends">proto::extends<></a></code>. This is often not desired
264 (although it depends on the syntax you want to allow).
267 Previously, the recommended usage was to do this:
269 <pre class="programlisting"><span class="comment">// my_expr is an expression extension of the Expr parameter</span>
270 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Expr</span><span class="special">></span>
271 <span class="keyword">struct</span> <span class="identifier">my_expr</span>
272 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">extends</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">,</span> <span class="identifier">my_expr</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">>,</span> <span class="identifier">my_domain</span><span class="special">></span>
273 <span class="special">{</span>
274 <span class="identifier">my_expr</span><span class="special">(</span><span class="identifier">Expr</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">expr</span> <span class="special">=</span> <span class="identifier">Expr</span><span class="special">())</span>
275 <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">extends</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">,</span> <span class="identifier">my_expr</span><span class="special">,</span> <span class="identifier">my_domain</span><span class="special">>(</span><span class="identifier">expr</span><span class="special">)</span>
276 <span class="special">{}</span>
278 <span class="comment">// OLD: don't do it like this anymore.</span>
279 <span class="keyword">using</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">extends</span><span class="special"><</span><span class="identifier">Expr</span><span class="special">,</span> <span class="identifier">my_expr</span><span class="special">,</span> <span class="identifier">my_domain</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=;</span>
280 <span class="special">};</span>
283 While this works in the majority of cases, it still doesn't suppress the
284 implicit generation of the default assignment operator. As a result, expressions
285 of the form <code class="computeroutput"><span class="identifier">a</span> <span class="special">=</span>
286 <span class="identifier">b</span></code> could either build an expression
287 template or do a copy assignment depending on whether the types of <code class="computeroutput"><span class="identifier">a</span></code> and <code class="computeroutput"><span class="identifier">b</span></code>
288 happen to be the same. That can lead to subtle bugs, so the behavior was
292 The <code class="literal"><code class="computeroutput"><a class="link" href="../BOOST_PROTO_EXTENDS_USING_ASSIGN.html" title="Macro BOOST_PROTO_EXTENDS_USING_ASSIGN">BOOST_PROTO_EXTENDS_USING_ASSIGN</a></code>()</code>
293 brings into scope the assignment operators defined in <code class="computeroutput"><a class="link" href="../boost/proto/extends.html" title="Struct template extends">proto::extends<></a></code>
294 as well as suppresses the generation of the copy assignment operator.
297 Also note that the <code class="computeroutput"><a class="link" href="../boost/proto/literal.html" title="Struct template literal">proto::literal<></a></code> class template, which
298 uses <code class="computeroutput"><a class="link" href="../boost/proto/extends.html" title="Struct template extends">proto::extends<></a></code>, has been chaged to use
299 <code class="literal"><code class="computeroutput"><a class="link" href="../BOOST_PROTO_EXTENDS_USING_ASSIGN.html" title="Macro BOOST_PROTO_EXTENDS_USING_ASSIGN">BOOST_PROTO_EXTENDS_USING_ASSIGN</a></code>()</code>.
300 The implications are highlighted in the sample code below:
302 <pre class="programlisting"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">literal</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">a</span><span class="special">(</span><span class="number">1</span><span class="special">),</span> <span class="identifier">b</span><span class="special">(</span><span class="number">2</span><span class="special">);</span> <span class="comment">// two non-const proto literals</span>
303 <span class="identifier">proto</span><span class="special">::</span><span class="identifier">literal</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="keyword">const</span> <span class="identifier">c</span><span class="special">(</span><span class="number">3</span><span class="special">);</span> <span class="comment">// a const proto literal</span>
305 <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">b</span><span class="special">;</span> <span class="comment">// No-op. Builds an expression tree and discards it.</span>
306 <span class="comment">// Same behavior in 1.42 and 1.43.</span>
308 <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">c</span><span class="special">;</span> <span class="comment">// CHANGE! In 1.42, this performed copy assignment, causing</span>
309 <span class="comment">// a's value to change to 3. In 1.43, the behavior is now</span>
310 <span class="comment">// the same as above: build and discard an expression tree.</span>
313 <div class="section">
314 <div class="titlepage"><div><div><h3 class="title">
315 <a name="boost_proto.appendices.history"></a><a class="link" href="appendices.html#boost_proto.appendices.history" title="Appendix B: History">Appendix B: History</a>
316 </h3></div></div></div>
317 <div class="variablelist">
318 <p class="title"><b></b></p>
319 <dl class="variablelist">
320 <dt><span class="term">August 13, 2010</span></dt>
322 Boost 1.44: Proto gets sub-domains and per-domain control of <code class="computeroutput"><a class="link" href="../boost/proto/as_expr_idp227626032.html" title="Function as_expr">proto::as_expr()</a></code> and <code class="computeroutput"><a class="link" href="../boost/proto/as_child_idp227648000.html" title="Function as_child">proto::as_child()</a></code> to meet the needs
325 <dt><span class="term">August 11, 2008</span></dt>
327 Proto v4 is merged to Boost trunk with more powerful transform protocol.
329 <dt><span class="term">April 7, 2008</span></dt>
331 Proto is accepted into Boost.
333 <dt><span class="term">March 1, 2008</span></dt>
335 Proto's Boost review begins.
337 <dt><span class="term">January 11, 2008</span></dt>
339 Boost.Proto v3 brings separation of grammars and transforms and a "round"
340 lambda syntax for defining transforms in-place.
342 <dt><span class="term">April 15, 2007</span></dt>
344 Boost.Xpressive is ported from Proto compilers to Proto transforms.
345 Support for old Proto compilers is dropped.
347 <dt><span class="term">April 4, 2007</span></dt>
349 Preliminary submission of Proto to Boost.
351 <dt><span class="term">December 11, 2006</span></dt>
353 The idea for transforms that decorate grammar rules is born in a private
354 email discussion with Joel de Guzman and Hartmut Kaiser. The first
355 transforms are committed to CVS 5 days later on December 16.
357 <dt><span class="term">November 1, 2006</span></dt>
359 The idea for <code class="computeroutput"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">matches</span><span class="special"><></span></code> and the whole grammar facility
360 is hatched during a discussion with Hartmut Kaiser on the spirit-devel
361 list. The first version of <code class="computeroutput"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">matches</span><span class="special"><></span></code> is checked into CVS 3 days
362 later. Message is <a href="http://osdir.com/ml/parsers.spirit.devel/2006-11/msg00003.html" target="_top">here</a>.
364 <dt><span class="term">October 28, 2006</span></dt>
366 Proto is reborn, this time with a uniform expression types that are
367 POD. Announcement is <a href="http://lists.boost.org/Archives/boost/2006/10/112453.php" target="_top">here</a>.
369 <dt><span class="term">April 20, 2005</span></dt>
371 Proto is born as a major refactorization of Boost.Xpressive's meta-programming.
372 Proto offers expression types, operator overloads and "compilers",
373 an early formulation of what later became transforms. Announcement
374 is <a href="http://lists.boost.org/Archives/boost/2005/04/85256.php" target="_top">here</a>.
379 <div class="section">
380 <div class="titlepage"><div><div><h3 class="title">
381 <a name="boost_proto.appendices.rationale"></a><a class="link" href="appendices.html#boost_proto.appendices.rationale" title="Appendix C: Rationale">Appendix C: Rationale</a>
382 </h3></div></div></div>
383 <div class="toc"><dl class="toc">
384 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.rationale.static_initialization">Static
385 Initialization</a></span></dt>
386 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.rationale.preprocessor">Why
387 Not Reuse MPL, Fusion, et cetera?</a></span></dt>
389 <div class="section">
390 <div class="titlepage"><div><div><h4 class="title">
391 <a name="boost_proto.appendices.rationale.static_initialization"></a><a class="link" href="appendices.html#boost_proto.appendices.rationale.static_initialization" title="Static Initialization">Static
393 </h4></div></div></div>
395 Proto expression types are PODs (Plain Old Data), and do not have constructors.
396 They are brace-initialized, as follows:
398 <pre class="programlisting"><span class="identifier">terminal</span><span class="special"><</span><span class="keyword">int</span><span class="special">>::</span><span class="identifier">type</span> <span class="keyword">const</span> <span class="identifier">_i</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">};</span>
401 The reason is so that expression objects like <code class="computeroutput"><span class="identifier">_i</span></code>
402 above can be <span class="emphasis"><em>statically initialized</em></span>. Why is static
403 initialization important? The terminals of many embedded domain-specific
404 languages are likely to be global const objects, like <code class="computeroutput"><span class="identifier">_1</span></code>
405 and <code class="computeroutput"><span class="identifier">_2</span></code> from the Boost Lambda
406 Library. Were these object to require run-time initialization, it might
407 be possible to use these objects before they are initialized. That would
408 be bad. Statically initialized objects cannot be misused that way.
411 <div class="section">
412 <div class="titlepage"><div><div><h4 class="title">
413 <a name="boost_proto.appendices.rationale.preprocessor"></a><a class="link" href="appendices.html#boost_proto.appendices.rationale.preprocessor" title="Why Not Reuse MPL, Fusion, et cetera?">Why
414 Not Reuse MPL, Fusion, et cetera?</a>
415 </h4></div></div></div>
417 Anyone who has peeked at Proto's source code has probably wondered, "Why
418 all the dirty preprocessor gunk? Couldn't this have been all implemented
419 cleanly on top of libraries like MPL and Fusion?" The answer is that
420 Proto could have been implemented this way, and in fact was at one point.
421 The problem is that template metaprogramming (TMP) makes for longer compile
422 times. As a foundation upon which other TMP-heavy libraries will be built,
423 Proto itself should be as lightweight as possible. That is achieved by
424 prefering preprocessor metaprogramming to template metaprogramming. Expanding
425 a macro is far more efficient than instantiating a template. In some cases,
426 the "clean" version takes 10x longer to compile than the "dirty"
430 The "clean and slow" version of Proto can still be found at http://svn.boost.org/svn/boost/branches/proto/v3.
431 Anyone who is interested can download it and verify that it is, in fact,
432 unusably slow to compile. Note that this branch's development was abandoned,
433 and it does not conform exactly with Proto's current interface.
437 <div class="section">
438 <div class="titlepage"><div><div><h3 class="title">
439 <a name="boost_proto.appendices.implementation"></a><a class="link" href="appendices.html#boost_proto.appendices.implementation" title="Appendix D: Implementation Notes">Appendix D: Implementation
441 </h3></div></div></div>
442 <div class="toc"><dl class="toc">
443 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.implementation.sfinae">Quick-n-Dirty
444 Type Categorization</a></span></dt>
445 <dt><span class="section"><a href="appendices.html#boost_proto.appendices.implementation.function_arity">Detecting
446 the Arity of Function Objects</a></span></dt>
448 <div class="section">
449 <div class="titlepage"><div><div><h4 class="title">
450 <a name="boost_proto.appendices.implementation.sfinae"></a><a class="link" href="appendices.html#boost_proto.appendices.implementation.sfinae" title="Quick-n-Dirty Type Categorization">Quick-n-Dirty
451 Type Categorization</a>
452 </h4></div></div></div>
454 Much has already been written about dispatching on type traits using SFINAE
455 (Substitution Failure Is Not An Error) techniques in C++. There is a Boost
456 library, Boost.Enable_if, to make the technique idiomatic. Proto dispatches
457 on type traits extensively, but it doesn't use <code class="computeroutput"><span class="identifier">enable_if</span><span class="special"><></span></code> very often. Rather, it dispatches
458 based on the presence or absence of nested types, often typedefs for void.
461 Consider the implementation of <code class="computeroutput"><span class="identifier">is_expr</span><span class="special"><></span></code>. It could have been written as
464 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span>
465 <span class="keyword">struct</span> <span class="identifier">is_expr</span>
466 <span class="special">:</span> <span class="identifier">is_base_and_derived</span><span class="special"><</span><span class="identifier">proto</span><span class="special">::</span><span class="identifier">some_expr_base</span><span class="special">,</span> <span class="identifier">T</span><span class="special">></span>
467 <span class="special">{};</span>
470 Rather, it is implemented as this:
472 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Void</span> <span class="special">=</span> <span class="keyword">void</span><span class="special">></span>
473 <span class="keyword">struct</span> <span class="identifier">is_expr</span>
474 <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">false_</span>
475 <span class="special">{};</span>
477 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span>
478 <span class="keyword">struct</span> <span class="identifier">is_expr</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T</span><span class="special">::</span><span class="identifier">proto_is_expr_</span><span class="special">></span>
479 <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span>
480 <span class="special">{};</span>
483 This relies on the fact that the specialization will be preferred if <code class="computeroutput"><span class="identifier">T</span></code> has a nested <code class="computeroutput"><span class="identifier">proto_is_expr_</span></code>
484 that is a typedef for <code class="computeroutput"><span class="keyword">void</span></code>.
485 All Proto expression types have such a nested typedef.
488 Why does Proto do it this way? The reason is because, after running extensive
489 benchmarks while trying to improve compile times, I have found that this
490 approach compiles faster. It requires exactly one template instantiation.
491 The other approach requires at least 2: <code class="computeroutput"><span class="identifier">is_expr</span><span class="special"><></span></code> and <code class="computeroutput"><span class="identifier">is_base_and_derived</span><span class="special"><></span></code>, plus whatever templates <code class="computeroutput"><span class="identifier">is_base_and_derived</span><span class="special"><></span></code>
495 <div class="section">
496 <div class="titlepage"><div><div><h4 class="title">
497 <a name="boost_proto.appendices.implementation.function_arity"></a><a class="link" href="appendices.html#boost_proto.appendices.implementation.function_arity" title="Detecting the Arity of Function Objects">Detecting
498 the Arity of Function Objects</a>
499 </h4></div></div></div>
501 In several places, Proto needs to know whether or not a function object
502 <code class="computeroutput"><span class="identifier">Fun</span></code> can be called with
503 certain parameters and take a fallback action if not. This happens in
504 <code class="computeroutput"><a class="link" href="../boost/proto/context/callable_context.html" title="Struct template callable_context">proto::callable_context<></a></code>
505 and in the <code class="computeroutput"><a class="link" href="../boost/proto/call.html" title="Struct template call">proto::call<></a></code> transform. How does
506 Proto know? It involves some tricky metaprogramming. Here's how.
509 Another way of framing the question is by trying to implement the following
510 <code class="computeroutput"><span class="identifier">can_be_called</span><span class="special"><></span></code>
511 Boolean metafunction, which checks to see if a function object <code class="computeroutput"><span class="identifier">Fun</span></code> can be called with parameters of
512 type <code class="computeroutput"><span class="identifier">A</span></code> and <code class="computeroutput"><span class="identifier">B</span></code>:
514 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Fun</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">A</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">B</span><span class="special">></span>
515 <span class="keyword">struct</span> <span class="identifier">can_be_called</span><span class="special">;</span>
518 First, we define the following <code class="computeroutput"><span class="identifier">dont_care</span></code>
519 struct, which has an implicit conversion from anything. And not just any
520 implicit conversion; it has a ellipsis conversion, which is the worst possible
521 conversion for the purposes of overload resolution:
523 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">dont_care</span>
524 <span class="special">{</span>
525 <span class="identifier">dont_care</span><span class="special">(...);</span>
526 <span class="special">};</span>
529 We also need some private type known only to us with an overloaded comma
530 operator (!), and some functions that detect the presence of this type
531 and return types with different sizes, as follows:
533 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">private_type</span>
534 <span class="special">{</span>
535 <span class="identifier">private_type</span> <span class="keyword">const</span> <span class="special">&</span><span class="keyword">operator</span><span class="special">,(</span><span class="keyword">int</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
536 <span class="special">};</span>
538 <span class="keyword">typedef</span> <span class="keyword">char</span> <span class="identifier">yes_type</span><span class="special">;</span> <span class="comment">// sizeof(yes_type) == 1</span>
539 <span class="keyword">typedef</span> <span class="keyword">char</span> <span class="special">(&</span><span class="identifier">no_type</span><span class="special">)[</span><span class="number">2</span><span class="special">];</span> <span class="comment">// sizeof(no_type) == 2</span>
541 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span>
542 <span class="identifier">no_type</span> <span class="identifier">is_private_type</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&);</span>
544 <span class="identifier">yes_type</span> <span class="identifier">is_private_type</span><span class="special">(</span><span class="identifier">private_type</span> <span class="keyword">const</span> <span class="special">&);</span>
547 Next, we implement a binary function object wrapper with a very strange
548 conversion operator, whose meaning will become clear later.
550 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Fun</span><span class="special">></span>
551 <span class="keyword">struct</span> <span class="identifier">funwrap2</span> <span class="special">:</span> <span class="identifier">Fun</span>
552 <span class="special">{</span>
553 <span class="identifier">funwrap2</span><span class="special">();</span>
554 <span class="keyword">typedef</span> <span class="identifier">private_type</span> <span class="keyword">const</span> <span class="special">&(*</span><span class="identifier">pointer_to_function</span><span class="special">)(</span><span class="identifier">dont_care</span><span class="special">,</span> <span class="identifier">dont_care</span><span class="special">);</span>
555 <span class="keyword">operator</span> <span class="identifier">pointer_to_function</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
556 <span class="special">};</span>
559 With all of these bits and pieces, we can implement <code class="computeroutput"><span class="identifier">can_be_called</span><span class="special"><></span></code> as follows:
561 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Fun</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">A</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">B</span><span class="special">></span>
562 <span class="keyword">struct</span> <span class="identifier">can_be_called</span>
563 <span class="special">{</span>
564 <span class="keyword">static</span> <span class="identifier">funwrap2</span><span class="special"><</span><span class="identifier">Fun</span><span class="special">></span> <span class="special">&</span><span class="identifier">fun</span><span class="special">;</span>
565 <span class="keyword">static</span> <span class="identifier">A</span> <span class="special">&</span><span class="identifier">a</span><span class="special">;</span>
566 <span class="keyword">static</span> <span class="identifier">B</span> <span class="special">&</span><span class="identifier">b</span><span class="special">;</span>
568 <span class="keyword">static</span> <span class="keyword">bool</span> <span class="keyword">const</span> <span class="identifier">value</span> <span class="special">=</span> <span class="special">(</span>
569 <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">no_type</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">is_private_type</span><span class="special">(</span> <span class="special">(</span><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">),</span> <span class="number">0</span><span class="special">)</span> <span class="special">))</span>
570 <span class="special">);</span>
572 <span class="keyword">typedef</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">bool_</span><span class="special"><</span><span class="identifier">value</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span>
573 <span class="special">};</span>
576 The idea is to make it so that <code class="computeroutput"><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">)</span></code> will
577 always compile by adding our own binary function overload, but doing it
578 in such a way that we can detect whether our overload was selected or not.
579 And we rig it so that our overload is selected if there is really no better
580 option. What follows is a description of how <code class="computeroutput"><span class="identifier">can_be_called</span><span class="special"><></span></code> works.
583 We wrap <code class="computeroutput"><span class="identifier">Fun</span></code> in a type that
584 has an implicit conversion to a pointer to a binary function. An object
585 <code class="computeroutput"><span class="identifier">fun</span></code> of class type can be
586 invoked as <code class="computeroutput"><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">)</span></code> if it has such a conversion operator,
587 but since it involves a user-defined conversion operator, it is less preferred
588 than an overloaded <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code>, which requires no such conversion.
591 The function pointer can accept any two arguments by virtue of the <code class="computeroutput"><span class="identifier">dont_care</span></code> type. The conversion sequence
592 for each argument is guaranteed to be the worst possible conversion sequence:
593 an implicit conversion through an ellipsis, and a user-defined conversion
594 to <code class="computeroutput"><span class="identifier">dont_care</span></code>. In total,
595 it means that <code class="computeroutput"><span class="identifier">funwrap2</span><span class="special"><</span><span class="identifier">Fun</span><span class="special">>()(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">)</span></code>
596 will always compile, but it will select our overload only if there really
600 If there is a better option --- for example if <code class="computeroutput"><span class="identifier">Fun</span></code>
601 has an overloaded function call operator such as <code class="computeroutput"><span class="keyword">void</span>
602 <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">B</span> <span class="identifier">b</span><span class="special">)</span></code> ---
603 then <code class="computeroutput"><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">)</span></code> will resolve to that one instead. The
604 question now is how to detect which function got picked by overload resolution.
607 Notice how <code class="computeroutput"><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">)</span></code> appears in <code class="computeroutput"><span class="identifier">can_be_called</span><span class="special"><></span></code>: <code class="computeroutput"><span class="special">(</span><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">),</span> <span class="number">0</span><span class="special">)</span></code>.
608 Why do we use the comma operator there? The reason is because we are using
609 this expression as the argument to a function. If the return type of <code class="computeroutput"><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">)</span></code> is <code class="computeroutput"><span class="keyword">void</span></code>,
610 it cannot legally be used as an argument to a function. The comma operator
614 This should also make plain the purpose of the overloaded comma operator
615 in <code class="computeroutput"><span class="identifier">private_type</span></code>. The return
616 type of the pointer to function is <code class="computeroutput"><span class="identifier">private_type</span></code>.
617 If overload resolution selects our overload, then the type of <code class="computeroutput"><span class="special">(</span><span class="identifier">fun</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
618 <span class="identifier">b</span><span class="special">),</span>
619 <span class="number">0</span><span class="special">)</span></code>
620 is <code class="computeroutput"><span class="identifier">private_type</span></code>. Otherwise,
621 it is <code class="computeroutput"><span class="keyword">int</span></code>. That fact is used
622 to dispatch to either overload of <code class="computeroutput"><span class="identifier">is_private_type</span><span class="special">()</span></code>, which encodes its answer in the size
626 That's how it works with binary functions. Now repeat the above process
627 for functions up to some predefined function arity, and you're done.
631 <div class="section">
632 <div class="titlepage"><div><div><h3 class="title">
633 <a name="boost_proto.appendices.acknowledgements"></a><a class="link" href="appendices.html#boost_proto.appendices.acknowledgements" title="Appendix E: Acknowledgements">Appendix E:
635 </h3></div></div></div>
637 I'd like to thank Joel de Guzman and Hartmut Kaiser for being willing to
638 take a chance on using Proto for their work on Spirit-2 and Karma when Proto
639 was little more than a vision. Their requirements and feedback have been
643 Thanks also to Thomas Heller and again to Hartmut for their feedback and
644 suggestions during the redesign of Phoenix. That effort yielded several valuable
645 advanced features such as sub-domains, external transforms, and per-domain
646 <code class="computeroutput"><span class="identifier">as_child</span></code> customization.
649 Thanks to Daniel James for providing a patch to remove the dependence on
650 deprecated configuration macros for C++0x features.
653 Thanks to Joel Falcou and Christophe Henry for their enthusiasm, support,
654 feedback, and humor; and for volunteering to be Proto's co-maintainers.
657 Thanks to Dave Abrahams for an especially detailed review, and for making
658 a VM with msvc-7.1 available so I could track down portability issues on
662 Many thanks to Daniel Wallin who first implemented the code used to find
663 the common domain among a set, accounting for super- and sub-domains. Thanks
664 also to Jeremiah Willcock, John Bytheway and Krishna Achuthan who offered
665 alternate solutions to this tricky programming problem.
668 Thanks also to the developers of <a href="http://acts.nersc.gov/formertools/pete/index.html" target="_top">PETE</a>.
669 I found many good ideas there.
673 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
674 <td align="left"></td>
675 <td align="right"><div class="copyright-footer">Copyright © 2008 Eric Niebler<p>
676 Distributed under the Boost Software License, Version 1.0. (See accompanying
677 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
682 <div class="spirit-nav">
683 <a accesskey="p" href="../Transform.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../proto.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../boost_random.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>