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< <replaceable>A</replaceable> > >::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><tag::terminal,
term< <computeroutput>T &</computeroutput> > >::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><A<subscript>x</subscript>>::type</computeroutput> is not
- <computeroutput><classname>proto::default_domain</classname></computeroutput>, then
- <computeroutput>D</computeroutput> is
- <computeroutput><classname>proto::domain_of</classname><A<subscript>x</subscript>>::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<X></replaceable></computeroutput> be defined such that:
+ <itemizedlist>
+ <listitem>
+ <para>
+ If <computeroutput>X</computeroutput> is <computeroutput>Y &</computeroutput>
+ or (possibly cv-qualified) <computeroutput>boost::reference_wrapper<Y></computeroutput>,
+ then <computeroutput><replaceable>WRAP<X></replaceable></computeroutput> is equivalent to
+ <computeroutput><classname>proto::result_of::as_child</classname><Y, Domain></computeroutput>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Otherwise, <computeroutput><replaceable>WRAP<X></replaceable></computeroutput> is equivalent to
+ <computeroutput><classname>proto::result_of::as_expr</classname><X, Domain></computeroutput>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ If <computeroutput><classname>proto::wants_basic_expr</classname><typename Domain::proto_generator>::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<Domain(typename <classname>proto::base_expr</classname><
- Domain, <classname>proto::tag::terminal</classname>, <classname>proto::term</classname><
- A<subscript>0</subscript> > >::type)>::type</computeroutput>.
+ <computeroutput>typename <replaceable>WRAP<A<subscript>0</subscript>></replaceable>::type</computeroutput>.
</para>
<para>
Otherwise, <computeroutput>type</computeroutput> is a typedef for
- <computeroutput>boost::result_of<Domain(typename <classname>proto::base_expr</classname><
- Domain, Tag, <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname><
- typename <classname>proto::result_of::as_child</classname><A>::type...> >::type)>::type</computeroutput>
+ <computeroutput>boost::result_of<Domain(<replaceable>E</replaceable><
+ Tag, <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname><
+ typename <replaceable>WRAP<A></replaceable>::type...> >)>::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><></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><Tag>(a...)</computeroutput> be defined as
- <computeroutput><classname>proto::base_expr</classname><Domain, Tag,
- <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname><A...> >::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><typename Domain::proto_generator>::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><Tag,
+ <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname><decltype(b)...> >::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><Tag>(<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><></computeroutput>.
</para>
<para>
Let <computeroutput>s</computeroutput> be a Fusion Random Access Sequence equivalent to
<computeroutput>sequence</computeroutput>.
- Let <computeroutput><replaceable>WRAP</replaceable><N>(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<S,N>::type</computeroutput> is a reference,
- <computeroutput><replaceable>WRAP</replaceable><N>(s)</computeroutput> is equivalent to
+ If <computeroutput>fusion::result_of::value_at_c<decltype(s),N>::type</computeroutput> is a reference type
+ or an instantiation of <computeroutput>boost::reference_wrapper<></computeroutput>,
+ <computeroutput><replaceable>WRAP</replaceable>(N, s)</computeroutput> is equivalent to
<computeroutput><functionname>proto::as_child</functionname><Domain>(fusion::at_c<N>(s))</computeroutput>.
</para>
</listitem>
<listitem>
<para>
- Otherwise, <computeroutput><replaceable>WRAP</replaceable><N>(s)</computeroutput> is equivalent to
+ Otherwise, <computeroutput><replaceable>WRAP</replaceable>(N, s)</computeroutput> is equivalent to
<computeroutput><functionname>proto::as_expr</functionname><Domain>(fusion::at_c<N>(s))</computeroutput>.
</para>
</listitem>
</itemizedlist>
- Let <computeroutput><replaceable>MAKE</replaceable><Tag>(a...)</computeroutput> be defined as
- <computeroutput><classname>proto::base_expr</classname><Domain, Tag,
- <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname><A...> >::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><Tag>(<replaceable>WRAP</replaceable><0>(s),...
- <replaceable>WRAP</replaceable><<replaceable>N</replaceable>-1>(s)))</computeroutput>, where
+ If <computeroutput><classname>proto::wants_basic_expr</classname><typename Domain::proto_generator>::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><Tag,
+ <classname alt="proto::listN">proto::list<emphasis>N</emphasis></classname><decltype(b)...> >::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>