[Boost-commit] svn:boost r62964 - in trunk/libs/proto/doc: . reference

Subject: [Boost-commit] svn:boost r62964 - in trunk/libs/proto/doc: . reference
From: eric_at_[hidden]
Date: 2010-06-14 22:07:24

Author: eric_niebler
Date: 2010-06-14 22:07:23 EDT (Mon, 14 Jun 2010)
New Revision: 62964
URL: http://svn.boost.org/trac/boost/changeset/62964

Log:
make the reference agree with the implementation about the behavior of deduce_domain, as_child, as_expr, make_expr and unpack_expr
Text files modified: 
   trunk/libs/proto/doc/propdocs.sh             |     2                                         
   trunk/libs/proto/doc/reference/domain.xml    |    16 ---                                     
   trunk/libs/proto/doc/reference/make_expr.xml |   158 +++++++++++++++++++++++++++------------ 
   3 files changed, 114 insertions(+), 62 deletions(-)

Modified: trunk/libs/proto/doc/propdocs.sh
==============================================================================
--- trunk/libs/proto/doc/propdocs.sh	(original)
+++ trunk/libs/proto/doc/propdocs.sh	2010-06-14 22:07:23 EDT (Mon, 14 Jun 2010)
@@ -1,3 +1,5 @@
 #!/bin/sh
 
 rsync --delete --rsh=ssh --recursive -p html/* eric_niebler,boost-sandbox_at_[hidden]:/home/groups/b/bo/boost-sandbox/htdocs/libs/proto/doc/html
+
+rsync --delete --rsh=ssh --recursive -p src/* eric_niebler,boost-sandbox_at_[hidden]:/home/groups/b/bo/boost-sandbox/htdocs/libs/proto/doc/src

Modified: trunk/libs/proto/doc/reference/domain.xml
==============================================================================
--- trunk/libs/proto/doc/reference/domain.xml	(original)
+++ trunk/libs/proto/doc/reference/domain.xml	2010-06-14 22:07:23 EDT (Mon, 14 Jun 2010)
@@ -108,7 +108,7 @@
               expressions in this domain. The resulting expression object is suitable for storage
               in a local variable. In that scenario, it is usually preferable to return
               expressions by value; and, in the case of objects that are not yet Proto expressions,
-              to wrap they by value (if possible) in a new Proto terminal expression. (Contrast
+              to wrap them by value (if possible) in a new Proto terminal expression. (Contrast
               this description with the description for
               <computeroutput><classname>proto::domain::as_child</classname></computeroutput>.)
             </para>
@@ -126,7 +126,7 @@
               <computeroutput>T</computeroutput>:
               <itemizedlist>
                 <listitem>
-                  If <computeroutput>T</computeroutput> is not a Proto expression type the resulting
+                  If <computeroutput>T</computeroutput> is not a Proto expression type, the resulting
                   terminal is calculated as follows:
                   <itemizedlist>
                     <listitem>
@@ -144,11 +144,6 @@
                   term&lt; <replaceable>A</replaceable> &gt; &gt;::make(t))</computeroutput>.
                 </listitem>
                 <listitem>
-                  If <computeroutput>T</computeroutput> is a Proto expression type and its generator 
-                  type is different from <computeroutput>Generator</computeroutput>, the result is
-                  <computeroutput>Generator()(t)</computeroutput>.
-                </listitem>
-                <listitem>
                   Otherwise, the result is <computeroutput>t</computeroutput> converted to an
                   (un-const) rvalue.
                 </listitem>
@@ -205,17 +200,12 @@
               <computeroutput>T</computeroutput>:
               <itemizedlist>
                 <listitem>
-                  If <computeroutput>T</computeroutput> is not a Proto expression type the resulting
+                  If <computeroutput>T</computeroutput> is not a Proto expression type, the resulting
                   terminal is
                   <computeroutput>Generator()(<replaceable>E</replaceable>&lt;tag::terminal, 
                   term&lt; <computeroutput>T &amp;</computeroutput> &gt; &gt;::make(t))</computeroutput>.
                 </listitem>
                 <listitem>
-                  If <computeroutput>T</computeroutput> is a Proto expression type and its generator 
-                  type is different from <computeroutput>Generator</computeroutput>, the result is
-                  <computeroutput>Generator()(t)</computeroutput>.
-                </listitem>
-                <listitem>
                   Otherwise, the result is the lvalue <computeroutput>t</computeroutput>.
                 </listitem>
               </itemizedlist>

Modified: trunk/libs/proto/doc/reference/make_expr.xml
==============================================================================
--- trunk/libs/proto/doc/reference/make_expr.xml	(original)
+++ trunk/libs/proto/doc/reference/make_expr.xml	2010-06-14 22:07:23 EDT (Mon, 14 Jun 2010)
@@ -167,14 +167,35 @@
             <type><replaceable>domain-deduced-from-child-types</replaceable></type>
             <description>
               <para>
-                For each <computeroutput>x</computeroutput> in <computeroutput>[0,N)</computeroutput>
-                (proceeding in order beginning with <computeroutput>x=0</computeroutput>), if
-                <computeroutput><classname>proto::domain_of</classname>&lt;A<subscript>x</subscript>&gt;::type</computeroutput> is not
-                <computeroutput><classname>proto::default_domain</classname></computeroutput>, then
-                <computeroutput>D</computeroutput> is
-                <computeroutput><classname>proto::domain_of</classname>&lt;A<subscript>x</subscript>&gt;::type</computeroutput>. 
-                Otherwise, <computeroutput>D</computeroutput> is
-                <computeroutput><classname>proto::default_domain</classname></computeroutput>.
+                In this specialization, Proto uses the domains of the child expressions to compute the
+                domain of the parent. It is done in such a way that (A) expressions in domains
+                that share a common super-domain are interoperable, and (B) expressions that are in
+                the default domain (or a sub-domain thereof) are interoperable with <emphasis>all</emphasis>
+                expressions. The rules are thus:
+                <itemizedlist>
+                  <listitem>
+                    A sub-domain is <emphasis>stronger</emphasis> than its super-domain.
+                  </listitem>
+                  <listitem>
+                    For each child, define a set of domains <emphasis>S<subscript>N</subscript></emphasis>
+                    that includes the child's domain and all its super-domains.
+                  </listitem>
+                  <listitem>
+                    Define a set <emphasis>I</emphasis> that is the intersection of all the individual sets
+                    <emphasis>S<subscript>N</subscript></emphasis>. If <emphasis>I</emphasis> is empty,
+                    it is an error.
+                  </listitem>
+                  <listitem>
+                    If any elements in <emphasis>I</emphasis> are <emphasis>not</emphasis> sub-domains of
+                    <computeroutput><classname>proto::default_domain</classname></computeroutput>,
+                    then remove from <emphasis>I</emphasis> all the elements that <emphasis>are</emphasis>
+                    sub-domains of <computeroutput><classname>proto::default_domain</classname></computeroutput>.
+                  </listitem>
+                  <listitem>
+                    The common domain <computeroutput>D</computeroutput> is the strongest domain in set
+                    <emphasis>I</emphasis>.
+                  </listitem>
+                </itemizedlist>
               </para>
             </description>
           </typedef>
@@ -206,18 +227,42 @@
           <typedef name="type">
             <description>
               <para>
+                Let <computeroutput><replaceable>WRAP&lt;X&gt;</replaceable></computeroutput> be defined such that:
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      If <computeroutput>X</computeroutput> is <computeroutput>Y &amp;</computeroutput>
+                      or (possibly cv-qualified) <computeroutput>boost::reference_wrapper&lt;Y&gt;</computeroutput>,
+                      then <computeroutput><replaceable>WRAP&lt;X&gt;</replaceable></computeroutput> is equivalent to
+                      <computeroutput><classname>proto::result_of::as_child</classname>&lt;Y, Domain&gt;</computeroutput>.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
+                      Otherwise, <computeroutput><replaceable>WRAP&lt;X&gt;</replaceable></computeroutput> is equivalent to
+                      <computeroutput><classname>proto::result_of::as_expr</classname>&lt;X, Domain&gt;</computeroutput>.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </para>
+              <para>
+                If <computeroutput><classname>proto::wants_basic_expr</classname>&lt;typename Domain::proto_generator&gt;::value</computeroutput>
+                is true, then let <computeroutput><replaceable>E</replaceable></computeroutput> be
+                <computeroutput><classname>proto::basic_expr</classname></computeroutput>; otherwise,
+                let <computeroutput><replaceable>E</replaceable></computeroutput> be
+                <computeroutput><classname>proto::expr</classname></computeroutput>.
+              </para>
+              <para>
                 If <computeroutput>Tag</computeroutput> is
                 <computeroutput><classname>proto::tag::terminal</classname></computeroutput>, then
                 <computeroutput>type</computeroutput> is a typedef for
-                <computeroutput>boost::result_of&lt;Domain(typename <classname>proto::base_expr</classname>&lt;
-                Domain, <classname>proto::tag::terminal</classname>, <classname>proto::term</classname>&lt;
-                A<subscript>0</subscript> &gt; &gt;::type)&gt;::type</computeroutput>.
+                <computeroutput>typename <replaceable>WRAP&lt;A<subscript>0</subscript>&gt;</replaceable>::type</computeroutput>.
               </para>
               <para>
                 Otherwise, <computeroutput>type</computeroutput> is a typedef for
-                <computeroutput>boost::result_of&lt;Domain(typename <classname>proto::base_expr</classname>&lt;
-                Domain, Tag, <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname>&lt;
-                typename <classname>proto::result_of::as_child</classname>&lt;A&gt;::type...&gt; &gt;::type)&gt;::type</computeroutput>
+                <computeroutput>boost::result_of&lt;Domain(<replaceable>E</replaceable>&lt;
+                Tag, <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname>&lt;
+                typename <replaceable>WRAP&lt;A&gt;</replaceable>::type...&gt; &gt;)&gt;::type</computeroutput>
               </para>
             </description>
             <type><emphasis>see-below</emphasis></type>
@@ -329,10 +374,8 @@
           <para>
             This function template may be invoked either with or without specifying a
             <computeroutput>Domain</computeroutput> template parameter. If no domain is specified, the domain
-            is deduced by examining in order the domains of the given arguments and taking the first that is
-            not <computeroutput><classname>proto::default_domain</classname></computeroutput>, if any such
-            domain exists, or <computeroutput><classname>proto::default_domain</classname></computeroutput>
-            otherwise.
+            is deduced by examining domains of the given arguments. The procedure used is described in the
+            reference for <computeroutput><classname>proto::result_of::make_expr</classname>&lt;&gt;</computeroutput>.
           </para>
           <para>
             Let <computeroutput><replaceable>WRAP</replaceable>(x)</computeroutput> be defined such that:
@@ -351,21 +394,29 @@
                 </para>
               </listitem>
             </itemizedlist>
-            Let <computeroutput><replaceable>MAKE</replaceable>&lt;Tag&gt;(a...)</computeroutput> be defined as
-            <computeroutput><classname>proto::base_expr</classname>&lt;Domain, Tag,
-            <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname>&lt;A...&gt; &gt;::make(a...)</computeroutput>
-            where
-            <computeroutput>A<subscript>x</subscript></computeroutput> is the type of 
-            <computeroutput>a<subscript>x</subscript></computeroutput>.
           </para>
           <para>
+            If <computeroutput><classname>proto::wants_basic_expr</classname>&lt;typename Domain::proto_generator&gt;::value</computeroutput>
+            is true, then let <computeroutput><replaceable>E</replaceable></computeroutput> be
+            <computeroutput><classname>proto::basic_expr</classname></computeroutput>; otherwise,
+            let <computeroutput><replaceable>E</replaceable></computeroutput> be
+            <computeroutput><classname>proto::expr</classname></computeroutput>.
+          </para>
+          <para>
+            Let <computeroutput><replaceable>MAKE</replaceable>(Tag, b...)</computeroutput> be defined as
+            <computeroutput><replaceable>E</replaceable>&lt;Tag,
+            <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname>&lt;decltype(b)...&gt; &gt;::make(b...)</computeroutput>.
+          </para>
+          <para>
+            If <computeroutput>Tag</computeroutput> is
+            <computeroutput><classname>proto::tag::terminal</classname></computeroutput>, then return
+            <computeroutput><replaceable>WRAP</replaceable>(a<subscript>0</subscript>)</computeroutput>.
           </para>
-        </description>
-        <returns>
           <para>
-            <computeroutput>Domain()(<replaceable>MAKE</replaceable>&lt;Tag&gt;(<replaceable>WRAP</replaceable>(a)...))</computeroutput>.
+            Otherwise, return
+            <computeroutput>Domain()(<replaceable>MAKE</replaceable>(Tag, <replaceable>WRAP</replaceable>(a)...))</computeroutput>.
           </para>
-        </returns>
+        </description>
       </overloaded-function>
 
       <!-- proto::unpack_expr() -->
@@ -399,47 +450,56 @@
         <description>
           <para>
             This function template may be invoked either with or without specifying a
-            <computeroutput>Domain</computeroutput> argument. If no domain is specified, the domain is
-            deduced by examining in order the domains of the elements of <computeroutput>sequence</computeroutput>
-            and taking the first that is not
-            <computeroutput><classname>proto::default_domain</classname></computeroutput>, if any such domain
-            exists, or <computeroutput><classname>proto::default_domain</classname></computeroutput> otherwise.
+            <computeroutput>Domain</computeroutput> argument. If no domain is specified, the domain
+            is deduced by examining domains of each element of the sequence. The procedure used is
+            described in the reference for
+            <computeroutput><classname>proto::result_of::make_expr</classname>&lt;&gt;</computeroutput>.
           </para>
           <para>
             Let <computeroutput>s</computeroutput> be a Fusion Random Access Sequence equivalent to
             <computeroutput>sequence</computeroutput>.
-            Let <computeroutput><replaceable>WRAP</replaceable>&lt;N&gt;(s)</computeroutput>, where
-            <computeroutput>s</computeroutput> has type <computeroutput>S</computeroutput>, be defined such that:
+            Let <computeroutput><replaceable>WRAP</replaceable>(N, s)</computeroutput> be defined such that:
             <itemizedlist>
               <listitem>
                 <para>
-                  If <computeroutput>fusion::result_of::value_at_c&lt;S,N&gt;::type</computeroutput> is a reference,
-                  <computeroutput><replaceable>WRAP</replaceable>&lt;N&gt;(s)</computeroutput> is equivalent to
+                  If <computeroutput>fusion::result_of::value_at_c&lt;decltype(s),N&gt;::type</computeroutput> is a reference type
+                  or an instantiation of <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>,
+                  <computeroutput><replaceable>WRAP</replaceable>(N, s)</computeroutput> is equivalent to
                   <computeroutput><functionname>proto::as_child</functionname>&lt;Domain&gt;(fusion::at_c&lt;N&gt;(s))</computeroutput>.
                 </para>
               </listitem>
               <listitem>
                 <para>
-                  Otherwise, <computeroutput><replaceable>WRAP</replaceable>&lt;N&gt;(s)</computeroutput> is equivalent to
+                  Otherwise, <computeroutput><replaceable>WRAP</replaceable>(N, s)</computeroutput> is equivalent to
                   <computeroutput><functionname>proto::as_expr</functionname>&lt;Domain&gt;(fusion::at_c&lt;N&gt;(s))</computeroutput>.
                 </para>
               </listitem>
             </itemizedlist>
-            Let <computeroutput><replaceable>MAKE</replaceable>&lt;Tag&gt;(a...)</computeroutput> be defined as
-            <computeroutput><classname>proto::base_expr</classname>&lt;Domain, Tag,
-            <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname>&lt;A...&gt; &gt;::make(a...)</computeroutput>
-            where
-            <computeroutput>A<subscript>x</subscript></computeroutput> is the type of 
-            <computeroutput>a<subscript>x</subscript></computeroutput>.
           </para>
-        </description>
-        <returns>
           <para>
-            <computeroutput>Domain()(<replaceable>MAKE</replaceable>&lt;Tag&gt;(<replaceable>WRAP</replaceable>&lt;0&gt;(s),...
-            <replaceable>WRAP</replaceable>&lt;<replaceable>N</replaceable>-1&gt;(s)))</computeroutput>, where
+            If <computeroutput><classname>proto::wants_basic_expr</classname>&lt;typename Domain::proto_generator&gt;::value</computeroutput>
+            is true, then let <computeroutput><replaceable>E</replaceable></computeroutput> be
+            <computeroutput><classname>proto::basic_expr</classname></computeroutput>; otherwise,
+            let <computeroutput><replaceable>E</replaceable></computeroutput> be
+            <computeroutput><classname>proto::expr</classname></computeroutput>.
+          </para>
+          <para>
+            Let <computeroutput><replaceable>MAKE</replaceable>(Tag, b...)</computeroutput> be defined as
+            <computeroutput><replaceable>E</replaceable>&lt;Tag,
+            <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname>&lt;decltype(b)...&gt; &gt;::make(b...)</computeroutput>.
+          </para>
+          <para>
+            If <computeroutput>Tag</computeroutput> is
+            <computeroutput><classname>proto::tag::terminal</classname></computeroutput>, then return
+            <computeroutput><replaceable>WRAP</replaceable>(0, s)</computeroutput>.
+          </para>
+          <para>
+            Otherwise, return
+            <computeroutput>Domain()(<replaceable>MAKE</replaceable>(Tag, <replaceable>WRAP</replaceable>(0, s),...
+            <replaceable>WRAP</replaceable>(<replaceable>N</replaceable>-1, s)))</computeroutput>, where
             <replaceable>N</replaceable> is the size of <computeroutput>Sequence</computeroutput>.
           </para>
-        </returns>
+        </description>
       </overloaded-function>
     </namespace>
   </namespace>