[Boost-commit] svn:boost r64584 - trunk/libs/proto/doc

Subject: [Boost-commit] svn:boost r64584 - trunk/libs/proto/doc
From: eric_at_[hidden]
Date: 2010-08-03 18:55:27

Author: eric_niebler
Date: 2010-08-03 18:54:38 EDT (Tue, 03 Aug 2010)
New Revision: 64584
URL: http://svn.boost.org/trac/boost/changeset/64584

Log:
add release notes for Boost.1.44
Text files modified: 
   trunk/libs/proto/doc/history.qbk       |     5 +                                       
   trunk/libs/proto/doc/proto.qbk         |     6 +                                       
   trunk/libs/proto/doc/release_notes.qbk |   124 ++++++++++++++++++++++++++++++++++++++++
   3 files changed, 135 insertions(+), 0 deletions(-)

Modified: trunk/libs/proto/doc/history.qbk
==============================================================================
--- trunk/libs/proto/doc/history.qbk	(original)
+++ trunk/libs/proto/doc/history.qbk	2010-08-03 18:54:38 EDT (Tue, 03 Aug 2010)
@@ -9,6 +9,11 @@
 
 [variablelist
 [
+    [August ??, 2010]
+    [Boost 1.44: Proto gets sub-domains and per-domain control of _as_expr_
+    and _as_child_ to meet the needs of Phoenix3.]
+]
+[
     [August 11, 2008]
     [Proto v4 is merged to Boost trunk with more powerful transform protocol.]
 ]

Modified: trunk/libs/proto/doc/proto.qbk
==============================================================================
--- trunk/libs/proto/doc/proto.qbk	(original)
+++ trunk/libs/proto/doc/proto.qbk	2010-08-03 18:54:38 EDT (Tue, 03 Aug 2010)
@@ -167,6 +167,12 @@
   [classref boost::proto::reverse_fold `proto::reverse_fold<>`]]
 [def _reverse_fold_tree_pt_ 
   [classref boost::proto::reverse_fold_tree `proto::reverse_fold_tree<>`]]
+[def _generator_ 
+  [classref boost::proto::generator `proto::generator<>`]]
+[def _pod_generator_ 
+  [classref boost::proto::pod_generator `proto::pod_generator<>`]]
+[def _deduce_domain_ 
+  [classref boost::proto::deduce_domain `proto::deduce_domain`]]
 [def _lazy_pt_ 
   [classref boost::proto::lazy `proto::lazy<>`]]
 [def _SYB_ 

Modified: trunk/libs/proto/doc/release_notes.qbk
==============================================================================
--- trunk/libs/proto/doc/release_notes.qbk	(original)
+++ trunk/libs/proto/doc/release_notes.qbk	2010-08-03 18:54:38 EDT (Tue, 03 Aug 2010)
@@ -11,6 +11,8 @@
 [heading Boost 1.44]
 [/=================]
 
+[*Behavior Change: proto::and_<>]
+
 In Boost 1.44, the behavior of _and_ as a transform changed. Previously, it only
 applied the transform associated with the last grammar in the set. Now, it applies
 all the transforms but only returns the result of the last. That makes it behave
@@ -22,6 +24,128 @@
 
   (G0()(e), G1()(e), G2()(e))
 
+[*Behavior Change: proto::as_expr() and proto::as_child()]
+
+The functions _as_expr_ and _as_child_ are used to guarantee that an
+object is a Proto expression by turning it into one if it is not already,
+using an optionally specified domain. In previous releases, when these
+functions were passed a Proto expression in a domain different to the one
+specified, they would apply the specified domain's generator, resulting in
+a twice-wrapped expression. This behavior was surprising to some users.
+
+The new behavior of these two functions is to always leave Proto expressions
+alone, regardless of the expressions' domains.
+
+[*Behavior Change: proto::(pod_)generator<> and proto::basic_expr<>]
+
+Users familiar with Proto's extension mechanism have probably used either
+_generator_ or _pod_generator_ with a wrapper template when defining their
+domain. In the past, Proto would instantiate your wrapper template with
+instances of _expr_. In Boost 1.44, Proto now instantiates your wrapper
+template with instances of a new type: _basic_expr_.
+
+For instance:
+
+  // An expression wrapper
+  template<class Expr>
+  struct my_expr_wrapper;
+  
+  // A domain
+  struct my_domain
+    : proto::domain< proto::generator< my_expr_wrapper > >
+  {};
+  
+  template<class Expr>
+  struct my_expr_wrapper
+    : proto::extends<Expr, my_expr_wrapper<Expr>, my_domain>
+  {
+    // Before 1.44, Expr was an instance of proto::expr<>
+    // In 1.44, Expr is an instance of proto::basic_expr<>
+  };
+
+The motivation for this change was to improve compile times. _expr_ is an
+expensive type to instantiate because it defines a host of member functions.
+When defining your own expression wrapper, the instance of _expr_ sits as a
+hidden data member function in your wrapper and the members of _expr_ go
+unused. Therefore, the cost of those member functions is wasted. In contrast,
+_basic_expr_ is a very lightweight type with no member functions at all.
+
+The vast majority of programs should recompile without any source changes.
+However, if somewhere you are assuming that you will be given instances
+specifically of _expr_, your code will break.
+
+[*New Feature: Sub-domains]
+
+In Boost 1.44, Proto introduces an important new feature called
+"sub-domains". This gives you a way to spcify that one domain is
+compatible with another such that expressions in one domain can
+be freely mixed with expressions in another. You can define one
+domain to be the sub-domain of another by using the third template
+parameter of _domain_.
+
+For instance:
+
+  // Not shown: define some expression
+  // generators genA and genB
+
+  struct A
+    : proto::domain< genA, proto::_ >
+  {};
+
+  // Define a domain B that is the sub-domain
+  // of domain A.
+  struct B
+    : proto::domain< genB, proto::_, A >
+  {};
+
+Expressions in domains `A` and `B` can have different wrappers
+(hence, different interfaces), but they can be combined into larger
+expressions. Without a sub-domain relationship, this would have
+been an error. The domain of the resulting expression in this case
+would be `A`.
+
+The complete description of sub-domains can be found in the reference
+sections for _domain_ and _deduce_domain_.
+
+[*New Feature: Domain-specific as_expr() and as_child()]
+
+Proto has always allowed users to customize expressions post-hoc by
+specifying a Generator when defining their domain. But it has never
+allowed users to control how Proto assembles sub-expressions in the
+first place. As of Boost 1.44, users now have this power.
+
+Users defining their own domain can now specify how _as_expr_ and
+_as_child_ work in their domain. They can do this easily by defining
+nested class templates named `as_expr` and/or `as_child` within their
+domain class.
+
+For example:
+
+  struct my_domain
+    : proto::domain< my_generator >
+  {
+    typedef
+        proto::domain< my_generator >
+    base_domain;
+
+    // For my_domain, as_child does the same as
+    // what as_expr does by default.
+    template<class T>
+    struct as_child
+      : base_domain::as_child<T>
+    {};
+  };
+
+In the above example, `my_domain::as_child<>` simply defers to
+`proto::domain::as_expr<>`. This has the nice effect of causing
+all terminals to be captured by value instead of by reference,
+and to likewise store child expressions by value. The result is
+that expressions in `my_domain` are safe to store in `auto`
+variables because they will not have dangling references to
+intermediate temporary expressions. (Naturally, it also means that
+expression construction has extra runtime overhead of copying that
+the compiler may or may not be able to optimize away.)
+
 [/=================]
 [heading Boost 1.43]
 [/=================]