proto/doc/reference/transform/when.xml

<?xml version="1.0" encoding="utf-8"?>
<header name="boost/proto/transform/when.hpp">
  <para>
    Definition of the
    <computeroutput>
      <classname alt="boost::proto::when">proto::when&lt;&gt;</classname>
    </computeroutput> and
    <computeroutput>
      <classname alt="boost::proto::otherwise">proto::otherwise&lt;&gt;</classname>
    </computeroutput> transforms.
  </para>
  <namespace name="boost">
    <namespace name="proto">
      <struct name="when">
        <template>
          <template-type-parameter name="Grammar"/>
          <template-type-parameter name="PrimitiveTransform">
            <default>Grammar</default>
          </template-type-parameter>
        </template>
        <purpose>A grammar element and a <conceptname>PrimitiveTransform</conceptname> that associates
          a transform with the grammar.</purpose>
        <description>
          <para>
            Use <computeroutput>proto::when&lt;&gt;</computeroutput> to override a grammar's default
            transform with a custom transform. It is for used when composing larger transforms by
            associating smaller transforms with individual rules in your grammar, as in the following
            transform which counts the number of terminals in an expression.
            <programlisting>// Count the terminals in an expression tree.
// Must be invoked with initial state == mpl::int_&lt;0&gt;().
struct CountLeaves :
  <classname>proto::or_</classname>&lt;
    proto::when&lt;<classname>proto::terminal</classname>&lt;<classname>proto::_</classname>&gt;, mpl::next&lt;<classname>proto::_state</classname>&gt;()&gt;,
    proto::otherwise&lt;<classname>proto::fold</classname>&lt;<classname>proto::_</classname>, <classname>proto::_state</classname>, CountLeaves&gt; &gt;
  &gt;
{};</programlisting>
          </para>
          <para>
            In <computeroutput>proto::when&lt;G, T&gt;</computeroutput>, when <computeroutput>T</computeroutput>
            is a class type it is a <conceptname>PrimitiveTransform</conceptname> and the following equivalencies hold:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <computeroutput>boost::result_of&lt;proto::when&lt;G,T&gt;(E,S,V)&gt;::type</computeroutput> is the same as
                <computeroutput>boost::result_of&lt;T(E,S,V)&gt;::type</computeroutput>.
              </para>
            </listitem>
            <listitem>
              <para>
                <computeroutput>proto::when&lt;G,T&gt;()(e,s,v)</computeroutput> is the same as
                <computeroutput>T()(e,s,v)</computeroutput>.
              </para>
            </listitem>
          </itemizedlist>
        </description>
        <inherit><type>PrimitiveTransform</type></inherit>
        <typedef name="proto_base_expr">
          <type>typename Grammar::proto_base_expr</type>
        </typedef>
      </struct>

      <struct-specialization name="when">
        <template>
          <template-type-parameter name="Grammar"/>
          <template-type-parameter name="Fun"/>
        </template>
        <specialization>
          <template-arg>Grammar</template-arg>
          <template-arg>Fun *</template-arg>
        </specialization>
        <inherit><classname>proto::when</classname>&lt; Grammar, Fun &gt;</inherit>
        <purpose>A specialization that treats function pointer <conceptname>Transform</conceptname>s as if they
          were function type <conceptname>Transform</conceptname>s.</purpose>
        <description>
          <para>
            This specialization requires that <computeroutput>Fun</computeroutput> is actually a function type.
          </para>
          <para>
            This specialization is required for nested transforms such as
            <computeroutput>proto::when&lt;G, T0(T1(_))&gt;</computeroutput>. In C++, functions that are used
            as parameters to other functions automatically decay to funtion pointer types. In other words, the
            type <computeroutput>T0(T1(_))</computeroutput> is indistinguishable from
            <computeroutput>T0(T1(*)(_))</computeroutput>. This specialization is required to handle these
            nested function pointer type transforms properly.
          </para>
        </description>
      </struct-specialization>

      <struct-specialization name="when">
        <template>
          <template-type-parameter name="Grammar"/>
          <template-type-parameter name="R"/>
          <template-type-parameter name="A" pack="1"/>
        </template>
        <specialization>
          <template-arg>Grammar</template-arg>
          <template-arg>R(A...)</template-arg>
        </specialization>
        <inherit><classname>proto::transform</classname>&lt; when&lt;Grammar, R(A...)&gt; &gt;</inherit>
        <purpose>A grammar element and a <conceptname>PrimitiveTransform</conceptname> that associates a
          transform with the grammar. </purpose>
        <description>
          <para>
            Use <computeroutput>proto::when&lt;&gt;</computeroutput> to override a grammar's default
            transform with a custom transform. It is for use when composing larger transforms by associating
            smaller transforms with individual rules in your grammar.
          </para>
          <para>
            The <computeroutput>when&lt;G, R(A...)&gt;</computeroutput> form accepts either a
            <conceptname>CallableTransform</conceptname> or an <conceptname>ObjectTransform</conceptname> as its
            second parameter. <computeroutput>proto::when&lt;&gt;</computeroutput> uses
            <computeroutput><classname>proto::is_callable</classname>&lt;R&gt;::value</computeroutput> to
            distinguish between the two, and uses
            <computeroutput><classname>proto::call&lt;&gt;</classname></computeroutput> to evaluate
            <conceptname>CallableTransform</conceptname>s and
            <computeroutput><classname>proto::make&lt;&gt;</classname></computeroutput> to evaluate
            <conceptname>ObjectTransform</conceptname>s.
          </para>
        </description>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
          <typedef name="call_">
            <purpose>For exposition only</purpose>
            <type><classname>proto::call</classname>&lt;R(A...)&gt;</type>
          </typedef>
          <typedef name="make_">
            <purpose>For exposition only</purpose>
            <type><classname>proto::make</classname>&lt;R(A...)&gt;</type>
          </typedef>
          <typedef name="which">
            <purpose>For exposition only</purpose>
            <type>typename mpl::if_&lt;<classname>proto::is_callable</classname>&lt;R&gt;,call_,make_&gt;::type</type>
          </typedef>
          <typedef name="result_type">
            <type>typename boost::result_of&lt;which(Expr, State, Data)&gt;::type</type>
          </typedef>
          <method-group name="public member functions">
            <method name="operator()" cv="const">
              <type>result_type</type>
              <parameter name="expr">
                <paramtype>typename impl::expr_param</paramtype>
                <description>
                  <para>The current expression </para>
                </description>
              </parameter>
              <parameter name="state">
                <paramtype>typename impl::state_param</paramtype>
                <description>
                  <para>The current state </para>
                </description>
              </parameter>
              <parameter name="data">
                <paramtype>typename impl::data_param</paramtype>
                <description>
                  <para>An arbitrary data </para>
                </description>
              </parameter>
              <description>
                <para>
                  Evaluate <computeroutput>R(A...)</computeroutput> as a transform either with
                  <computeroutput><classname>proto::call&lt;&gt;</classname></computeroutput> or with
                  <computeroutput><classname>proto::make&lt;&gt;</classname></computeroutput> depending
                  on whether <computeroutput><classname>proto::is_callable</classname>&lt;R&gt;::value</computeroutput>
                  is <computeroutput>true</computeroutput> or <computeroutput>false</computeroutput>.
                </para>
              </description>
              <requires>
                <para>
                  <computeroutput><classname>proto::matches</classname>&lt;Expr, Grammar&gt;::value</computeroutput>
                  is <computeroutput>true</computeroutput>.
                </para>
              </requires>
              <returns>
                <para>
                  <computeroutput>which()(expr, state, data)</computeroutput>
                </para>
              </returns>
            </method>
          </method-group>
        </struct>
        <typedef name="proto_base_expr">
          <type>typename Grammar::proto_base_expr</type>
        </typedef>
      </struct-specialization>
      
      <struct name="otherwise">
        <template>
          <template-type-parameter name="Fun"/>
        </template>
        <inherit><classname>proto::when</classname>&lt; <classname>proto::_</classname>, Fun &gt;</inherit>
        <purpose>
          Syntactic sugar for <computeroutput><classname>proto::when</classname>&lt; <classname>proto::_</classname>, Fun &gt;</computeroutput>,
          for use in grammars to handle all the cases not yet handled.
        </purpose>
        <description>
          <para>
            Use <computeroutput>proto::otherwise&lt;T&gt;</computeroutput> in your grammars as a synonym for
            <computeroutput><classname>proto::when</classname>&lt; <classname>proto::_</classname>, Fun &gt;</computeroutput>
            as in the following transform which counts the number of terminals in an expression.
          </para>
          <para>
            <programlisting>// Count the terminals in an expression tree.
// Must be invoked with initial state == mpl::int_&lt;0&gt;().
struct CountLeaves :
  <classname>proto::or_</classname>&lt;
    proto::when&lt;<classname>proto::terminal</classname>&lt;<classname>proto::_</classname>&gt;, mpl::next&lt;<classname>proto::_state</classname>&gt;()&gt;,
    proto::otherwise&lt;<classname>proto::fold</classname>&lt;<classname>proto::_</classname>, <classname>proto::_state</classname>, CountLeaves&gt; &gt;
  &gt;
{};</programlisting>
          </para>
        </description>
      </struct>
    </namespace>
  </namespace>
</header>