[Boost-commit] svn:boost r60633 - in trunk: boost/proto libs/proto/doc/reference libs/proto/doc/reference/concepts

Subject: [Boost-commit] svn:boost r60633 - in trunk: boost/proto libs/proto/doc/reference libs/proto/doc/reference/concepts
From: eric_at_[hidden]
Date: 2010-03-15 21:20:58

Author: eric_niebler
Date: 2010-03-15 21:20:57 EDT (Mon, 15 Mar 2010)
New Revision: 60633
URL: http://svn.boost.org/trac/boost/changeset/60633

Log:
add proto::assert_matches function and friends to debug.hpp, flesh out docs for Expr concept
Text files modified: 
   trunk/boost/proto/debug.hpp                      |    42 +++++++++                               
   trunk/libs/proto/doc/reference/concepts/Expr.xml |   123 ++++++++++++++++++----------            
   trunk/libs/proto/doc/reference/debug.xml         |   175 ++++++++++++++++++++++++++++++++++++++++
   3 files changed, 296 insertions(+), 44 deletions(-)

Modified: trunk/boost/proto/debug.hpp
==============================================================================
--- trunk/boost/proto/debug.hpp	(original)
+++ trunk/boost/proto/debug.hpp	2010-03-15 21:20:57 EDT (Mon, 15 Mar 2010)
@@ -14,9 +14,11 @@
 #include <iomanip>
 #include <iostream>
 #include <typeinfo>
+#include <boost/mpl/assert.hpp>
 #include <boost/proto/proto_fwd.hpp>
 #include <boost/proto/expr.hpp>
 #include <boost/proto/traits.hpp>
+#include <boost/proto/matches.hpp>
 #include <boost/proto/detail/dont_care.hpp>
 
 namespace boost { namespace proto
@@ -206,6 +208,46 @@
         functional::display_expr()(expr);
     }
 
+    /// \brief Assert at compile time that a particular expression
+    ///        matches the specified grammar.
+    ///
+    /// \note Equivalent to <tt>BOOST_MPL_ASSERT((proto::matches\<Expr, Grammar\>))</tt>
+    /// \param expr The Proto expression to check againts <tt>Grammar</tt>
+    template<typename Grammar, typename Expr>
+    void assert_matches(Expr const & /*expr*/)
+    {
+        BOOST_MPL_ASSERT((proto::matches<Expr, Grammar>));
+    }
+
+    /// \brief Assert at compile time that a particular expression
+    ///        does not match the specified grammar.
+    ///
+    /// \note Equivalent to <tt>BOOST_MPL_ASSERT_NOT((proto::matches\<Expr, Grammar\>))</tt>
+    /// \param expr The Proto expression to check againts <tt>Grammar</tt>
+    template<typename Grammar, typename Expr>
+    void assert_matches_not(Expr const & /*expr*/)
+    {
+        BOOST_MPL_ASSERT_NOT((proto::matches<Expr, Grammar>));
+    }
+
+    /// \brief Assert at compile time that a particular expression
+    ///        matches the specified grammar.
+    ///
+    /// \note Equivalent to <tt>proto::assert_matches\<Grammar\>(Expr)</tt>
+    /// \param Expr The Proto expression to check againts <tt>Grammar</tt>
+    /// \param Grammar The grammar used to validate Expr.
+    #define BOOST_PROTO_ASSERT_MATCHES(Expr, Grammar)                                               \
+        boost::proto::assert_matches<Grammar>(Expr)
+
+    /// \brief Assert at compile time that a particular expression
+    ///        does not match the specified grammar.
+    ///
+    /// \note Equivalent to <tt>proto::assert_matches_not\<Grammar\>(Expr)</tt>
+    /// \param Expr The Proto expression to check againts <tt>Grammar</tt>
+    /// \param Grammar The grammar used to validate Expr.
+    #define BOOST_PROTO_ASSERT_MATCHES_NOT(Expr, Grammar)                                           \
+        boost::proto::assert_matches_not<Grammar>(Expr)
+
 }}
 
 #endif

Modified: trunk/libs/proto/doc/reference/concepts/Expr.xml
==============================================================================
--- trunk/libs/proto/doc/reference/concepts/Expr.xml	(original)
+++ trunk/libs/proto/doc/reference/concepts/Expr.xml	2010-03-15 21:20:57 EDT (Mon, 15 Mar 2010)
@@ -7,21 +7,21 @@
   Software License, Version 1.0. (See accompanying
   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   -->
-  <param name="Expr" role="expession-type" />
-  <param name="Tag" role="tag-type" />
-  <param name="Domain" role="domain-type" />
-  <param name="N" role="mpl-integral-constant-type" />
+  <param name="Expr" role="expession-type"/>
+  <param name="Tag" role="tag-type"/>
+  <param name="Domain" role="domain-type"/>
+  <param name="N" role="mpl-integral-constant-type"/>
 
   <models-sentence>
-    The type <arg num="1" /> must be a model of <self/>.
+    The type <arg num="1"/> must be a model of <self/>.
   </models-sentence>
 
   <models-sentence>
-    The type <arg num="3" /> must be a model of <conceptname>Domain</conceptname>.
+    The type <arg num="3"/> must be a model of <conceptname>Domain</conceptname>.
   </models-sentence>
 
   <models-sentence>
-    The type <arg num="4" /> must be a model of MPL Integral Constant.
+    The type <arg num="4"/> must be a model of MPL Integral Constant.
   </models-sentence>
 
   <description>
@@ -37,26 +37,32 @@
 
   <notation variables="e">
     <sample-value>
-      <type name="Expr" />
+      <type name="Expr"/>
     </sample-value>
   </notation>
 
   <associated-type name="proto_tag">
-    <get-member-type name="type">
-      <apply-template name="boost::proto::tag_of">
-        <type name="Expr"/>
-      </apply-template>
+    <get-member-type name="proto_tag">
+      <type name="Expr"/>
     </get-member-type>
     <description>
       <simpara>The tag type of the Expr.</simpara>
     </description>
   </associated-type>
 
+  <associated-type name="proto_args">
+    <get-member-type name="proto_args">
+      <type name="Expr"/>
+    </get-member-type>
+    <description>
+      <simpara>A typelist representing either the types of the child nodes, or,
+        if the arity of the Expr is 0, of the value of the terminal.</simpara>
+    </description>
+  </associated-type>
+
   <associated-type name="proto_arity">
-    <get-member-type name="type">
-      <apply-template name="boost::proto::arity_of">
-        <type name="Expr"/>
-      </apply-template>
+    <get-member-type name="proto_arity">
+      <type name="Expr"/>
     </get-member-type>
     <description>
       <simpara>
@@ -66,53 +72,62 @@
     </description>
   </associated-type>
 
-  <associated-type name="proto_domain">
-    <get-member-type name="type">
-      <apply-template name="boost::proto::domain_of">
-        <type name="Expr"/>
-      </apply-template>
+  <associated-type name="proto_base_expr">
+    <get-member-type name="proto_base_expr">
+      <type name="Expr"/>
     </get-member-type>
     <description>
       <simpara>
-        The Domain of the Expr. <computeroutput>proto_domain</computeroutput>
-        models <conceptname>Domain</conceptname>.
+        A typedef for an instantiation of
+        <classname alt="boost::proto::expr"><code>proto::expr&lt;&gt;</code></classname>
+        that is equivalent to Expr. Expression types are equivalent if they have the
+        same <code>proto_tag</code>, <code>proto_args</code>, and <code>proto_arity</code>.
       </simpara>
     </description>
   </associated-type>
 
-  <associated-type name="childN_type">
-    <get-member-type name="type">
-      <apply-template name="boost::proto::result_of::child">
-        <type name="Expr"/>
-        <type name="N"/>
-      </apply-template>
+  <associated-type name="proto_derived_expr">
+    <get-member-type name="proto_derived_expr">
+      <type name="Expr"/>
     </get-member-type>
     <description>
-      <simpara>The Nth child of Expr.</simpara>
+      <simpara>
+        A typedef for <code>Expr</code>.
+      </simpara>
     </description>
   </associated-type>
 
-  <associated-type name="value_type">
-    <get-member-type name="type">
-      <apply-template name="boost::proto::result_of::value">
-        <type name="Expr"/>
-      </apply-template>
+  <associated-type name="proto_domain">
+    <get-member-type name="proto_domain">
+      <type name="Expr"/>
+    </get-member-type>
+    <description>
+      <simpara>
+        The Domain of the Expr. <computeroutput>proto_domain</computeroutput>
+        models <conceptname>Domain</conceptname>.
+      </simpara>
+    </description>
+  </associated-type>
+
+  <associated-type name="proto_childN">
+    <get-member-type name="proto_childN">
+      <type name="Expr"/>
     </get-member-type>
     <description>
-      <simpara>The value of a terminal Expr.
-        Requires <computeroutput>0 == proto_arity::value</computeroutput>.</simpara>
+      <simpara>The type of the Nth child of Expr. Requires 
+        <code>0 == N::value || N::value &lt; proto_arity::value</code></simpara>
     </description>
   </associated-type>
 
   <valid-expression name="Get N-th Child">
     <apply-function name="boost::proto::child&lt; N &gt;">
       <sample-value>
-        <type name="Expr" />
+        <type name="Expr"/>
       </sample-value>
     </apply-function>
     <return-type>
       <require-same-type testable="yes">
-        <type name="childN_type"/>
+        <type name="proto_childN"/>
       </require-same-type>
     </return-type>
     <semantics>Extracts the Nth child from this Expr.
@@ -122,20 +137,40 @@
   <valid-expression name="Get Terminal Value">
     <apply-function name="boost::proto::value">
       <sample-value>
-        <type name="Expr" />
+        <type name="Expr"/>
       </sample-value>
     </apply-function>
     <return-type>
       <require-same-type testable="yes">
-        <type name="value_type"/>
+        <type name="proto_child0"/>
+      </require-same-type>
+    </return-type>
+    <semantics>
+      Extracts the value from a terminal Expr.
+      Requires <computeroutput>0 == proto_arity::value</computeroutput>.
+    </semantics>
+  </valid-expression>
+
+  <valid-expression name="Get Base">
+    <apply-method name="proto_base">
+      <sample-value>
+        <type name="Expr"/>
+      </sample-value>
+    </apply-method>
+    <return-type>
+      <require-same-type testable="yes">
+        <type name="proto_base_expr"/>
       </require-same-type>
     </return-type>
-    <semantics>Extracts the value from a terminal Expr.
-      Requires <computeroutput>0 == proto_arity::value</computeroutput>.</semantics>
+    <semantics>
+        Returns an object of type
+        <classname alt="boost::proto::expr"><code>proto::expr&lt;&gt;</code></classname>
+        that is equivalent to <code>e</code>.
+    </semantics>
   </valid-expression>
 
   <example-model>
-    <type name="boost::proto::literal&lt; int &gt;" />
+    <type name="boost::proto::literal&lt; int &gt;"/>
   </example-model>
 
 </concept>

Modified: trunk/libs/proto/doc/reference/debug.xml
==============================================================================
--- trunk/libs/proto/doc/reference/debug.xml	(original)
+++ trunk/libs/proto/doc/reference/debug.xml	2010-03-15 21:20:57 EDT (Mon, 15 Mar 2010)
@@ -93,6 +93,181 @@
         </notes>
       </overloaded-function>
 
+      <!-- proto::assert_matches -->
+      <function name="assert_matches">
+        <type>void</type>
+        <template>
+          <template-type-parameter name="Grammar"/>
+          <template-type-parameter name="Expr"/>
+        </template>
+        <parameter name="expr">
+          <paramtype>Expr const &amp;</paramtype>
+          <purpose>
+            The Proto expression to check againts <code>Grammar</code>.
+          </purpose>
+        </parameter>
+        <purpose>
+          Assert at compile time that a particular expression
+          matches the specified grammar.
+        </purpose>
+        <notes>
+          <para>
+            Equivalent to <code>BOOST_MPL_ASSERT((<classname alt="proto::matches">proto::matches</classname>&lt;Expr, Grammar&gt;))</code>.
+          </para>
+        </notes>
+        <description>
+          <para>
+            Use <code>proto::assert_matches()</code> to assert at compile-time that
+            an expression matches a grammar. 
+          </para>
+          <para>
+            <emphasis role="bold">Example:</emphasis><programlisting>typedef proto::plus&lt; proto::terminal&lt; int &gt;, proto::terminal&lt; int &gt; &gt; PlusInts;
+
+proto::assert_matches&lt;PlusInts&gt;( <functionname>proto::lit</functionname>(1) + 42 );</programlisting>
+          </para>
+          <para>
+            See also:
+            <itemizedlist>
+              <listitem>
+                <code><functionname>proto::assert_matches_not</functionname>()</code>
+              </listitem>
+              <listitem>
+                <code><macroname>BOOST_PROTO_ASSERT_MATCHES</macroname>()</code>
+              </listitem>
+              <listitem>
+                <code><macroname>BOOST_PROTO_ASSERT_MATCHES_NOT</macroname>()</code>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </description>
+      </function>
+
+      <!-- proto::assert_matches_not -->
+      <function name="assert_matches_not">
+        <type>void</type>
+        <template>
+          <template-type-parameter name="Grammar"/>
+          <template-type-parameter name="Expr"/>
+        </template>
+        <parameter name="expr">
+          <paramtype>Expr const &amp;</paramtype>
+          <purpose>
+            The Proto expression to check againts <code>Grammar</code>.
+          </purpose>
+        </parameter>
+        <purpose>
+          Assert at compile time that a particular expression
+          does not match the specified grammar.
+        </purpose>
+        <notes>
+          <para>
+            Equivalent to <code>BOOST_MPL_ASSERT_NOT((<classname alt="proto::matches">proto::matches</classname>&lt;Expr, Grammar&gt;))</code>.
+          </para>
+        </notes>
+        <description>
+          <para>
+            Use <code>proto::assert_matches_not()</code> to assert at compile-time that
+            an expression does not match a grammar. 
+          </para>
+          <para>
+            <emphasis role="bold">Example:</emphasis><programlisting>typedef proto::plus&lt; proto::terminal&lt; int &gt;, proto::terminal&lt; int &gt; &gt; PlusInts;
+
+proto::assert_matches_not&lt;PlusInts&gt;( <functionname>proto::lit</functionname>("a string") + 42 );</programlisting>
+          </para>
+          <para>
+            See also:
+            <itemizedlist>
+              <listitem>
+                <code><functionname>proto::assert_matches</functionname>()</code>
+              </listitem>
+              <listitem>
+                <code><macroname>BOOST_PROTO_ASSERT_MATCHES</macroname>()</code>
+              </listitem>
+              <listitem>
+                <code><macroname>BOOST_PROTO_ASSERT_MATCHES_NOT</macroname>()</code>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </description>
+      </function>
     </namespace>
   </namespace>
+
+  <macro name="BOOST_PROTO_ASSERT_MATCHES" kind="functionlike">
+    <macro-parameter name="expr"/>
+    <macro-parameter name="Grammar"/>
+    <purpose>
+      Assert at compile time that a particular expression
+      matches the specified grammar.
+    </purpose>
+    <notes>
+      <para>
+        Equivalent to <code><functionname alt="boost::proto::assert_matches">proto::assert_matches</functionname>&lt;Grammar&gt;(expr)</code>.
+      </para>
+    </notes>
+    <description>
+      <para>
+        Use <code>BOOST_PROTO_ASSERT_MATCHES()</code> to assert at compile-time that
+        an expression matches a grammar.
+      </para>
+      <para>
+        <emphasis role="bold">Example:</emphasis><programlisting>typedef <classname alt="boost::proto::plus">proto::plus</classname>&lt; <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt;, <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt; &gt; PlusInts;
+
+BOOST_PROTO_ASSERT_MATCHES( <functionname alt="boost::proto::lit">proto::lit</functionname>(1) + 42, PlusInts );</programlisting>
+      </para>
+      <para>
+        See also:
+        <itemizedlist>
+          <listitem>
+            <code><functionname alt="boost::proto::assert_matches">proto::assert_matches</functionname>()</code>
+          </listitem>
+          <listitem>
+            <code><functionname alt="boost::proto::assert_matches_not">proto::assert_matches_not</functionname>()</code>
+          </listitem>
+          <listitem>
+            <code><macroname>BOOST_PROTO_ASSERT_MATCHES_NOT</macroname>()</code>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </description>
+  </macro>
+
+  <macro name="BOOST_PROTO_ASSERT_MATCHES_NOT" kind="functionlike">
+    <macro-parameter name="expr"/>
+    <macro-parameter name="Grammar"/>
+    <purpose>
+      Assert at compile time that a particular expression
+      does not match the specified grammar.
+    </purpose>
+    <notes>
+      <para>
+        Equivalent to <code><functionname alt="boost::proto::assert_matches_not">proto::assert_matches_not</functionname>&lt;Grammar&gt;(expr)</code>.
+      </para>
+    </notes>
+    <description>
+      <para>
+        Use <code>BOOST_PROTO_ASSERT_MATCHES_NOT()</code> to assert at compile-time that
+        an expression does not match a grammar. 
+      </para>
+      <para>
+        <emphasis role="bold">Example:</emphasis><programlisting>typedef <classname alt="boost::proto::plus">proto::plus</classname>&lt; <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt;, <classname alt="boost::proto::terminal">proto::terminal</classname>&lt; int &gt; &gt; PlusInts;
+
+BOOST_PROTO_ASSERT_MATCHES_NOT( <functionname alt="boost::proto::lit">proto::lit</functionname>("a string") + 42, PlusInts );</programlisting>
+      </para>
+      <para>
+        See also:
+        <itemizedlist>
+          <listitem>
+            <code><functionname alt="boost::proto::assert_matches">proto::assert_matches</functionname>()</code>
+          </listitem>
+          <listitem>
+            <code><functionname alt="boost::proto::assert_matches_not">proto::assert_matches_not</functionname>()</code>
+          </listitem>
+          <listitem>
+            <code><macroname>BOOST_PROTO_ASSERT_MATCHES</macroname>()</code>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </description>
+  </macro>
 </header>