1<?xml version="1.0" encoding="utf-8"?> 2<!-- 3 Copyright 2012 Eric Niebler 4 5 Distributed under the Boost 6 Software License, Version 1.0. (See accompanying 7 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 8 --> 9<header name="boost/proto/context/callable.hpp"> 10 <para>Definintion of <computeroutput><classname alt="boost::proto::context::callable_context">proto::context::callable_context<></classname></computeroutput>, 11 an evaluation context for <computeroutput><functionname alt="boost::proto::eval">proto::eval()</functionname></computeroutput> 12 that fans out each node and calls the derived context type with the expressions constituents. If the derived context 13 doesn't have an overload that handles this node, fall back to some other context. </para> 14 <namespace name="boost"> 15 <namespace name="proto"> 16 <namespace name="context"> 17 <struct name="callable_eval"> 18 <template> 19 <template-type-parameter name="Expr"/> 20 <template-type-parameter name="Context"/> 21 </template> 22 <purpose>A BinaryFunction that accepts a Proto expression and a callable context and calls 23 the context with the expression tag and children as arguments, effectively fanning the 24 expression out. </purpose> 25 <description> 26 <para> 27 <computeroutput>proto::context::callable_eval<></computeroutput> requires that 28 <computeroutput>Context</computeroutput> is a <conceptname>PolymorphicFunctionObject</conceptname> 29 that can be invoked with <computeroutput>Expr</computeroutput>'s tag and children as 30 expressions, as follows: 31 <programlisting>context(typename Expr::proto_tag(), <functionname>proto::child_c</functionname><0>(expr), ... <functionname>proto::child_c</functionname><N>(expr))</programlisting> 32 </para> 33 </description> 34 <typedef name="result_type"> 35 <type>typename boost::result_of< 36 Context( 37 typename Expr::proto_tag, 38 typename proto::result_of::child_c<0>::type, 39 ... 40 typename proto::result_of::child_c<N>::type, 41 )>::type 42 </type> 43 </typedef> 44 45 <method-group name="public member functions"> 46 <method name="operator()" cv="const"> 47 <type>result_type</type> 48 <parameter name="expr"> 49 <paramtype>Expr &</paramtype> 50 <description> 51 <para>The current expression </para> 52 </description> 53 </parameter> 54 <parameter name="context"> 55 <paramtype>Context &</paramtype> 56 <description> 57 <para>The callable evaluation context </para> 58 </description> 59 </parameter> 60 <returns> 61 <para> 62 <computeroutput> 63 context(typename Expr::proto_tag(), 64 <functionname>proto::child_c</functionname><0>(expr),... 65 <functionname>proto::child_c</functionname><N>(expr)) 66 </computeroutput> 67 </para> 68 </returns> 69 </method> 70 </method-group> 71 </struct> 72 73 <struct name="callable_context"> 74 <template> 75 <template-type-parameter name="Context"/> 76 <template-type-parameter name="DefaultCtx"> 77 <default><classname>proto::context::default_context</classname></default> 78 </template-type-parameter> 79 </template> 80 <purpose>An evaluation context adaptor that makes authoring a context a simple matter of 81 writing function overloads, rather then writing template specializations.</purpose> 82 <description> 83 <para> 84 <computeroutput>proto::callable_context<></computeroutput> is a base class that 85 implements the context protocol by passing fanned-out expression nodes to the derived 86 context, making it easy to customize the handling of expression types by writing function 87 overloads. Only those expression types needing special handling require explicit handling. 88 All others are dispatched to a user-specified default context, 89 <computeroutput>DefaultCtx</computeroutput>. 90 </para> 91 <para> 92 <computeroutput>proto::callable_context<></computeroutput> is defined simply as: 93 </para> 94 <para> 95 <programlisting>template<typename Context, typename DefaultCtx = default_context> 96struct callable_context { 97 template<typename Expr, typename ThisContext = Context> 98 struct eval : 99 mpl::if_< 100 is_expr_handled_<Expr, Context>, // For exposition 101 <classname>proto::context::callable_eval</classname><Expr, ThisContext>, 102 typename DefaultCtx::template eval<Expr, Context> 103 >::type 104 {}; 105};</programlisting> 106 </para> 107 <para> 108 The Boolean metafunction <computeroutput>is_expr_handled_<></computeroutput> uses 109 metaprogramming tricks to determine whether <computeroutput>Context</computeroutput> has 110 an overloaded function call operator that accepts the fanned-out constituents of an 111 expression of type <computeroutput>Expr</computeroutput>. If so, the handling of the 112 expression is dispatched to 113 <computeroutput><classname>proto::context::callable_eval<></classname></computeroutput>. 114 If not, it is dispatched to the user-specified <computeroutput>DefaultCtx</computeroutput>. 115 </para> 116 <para> 117 <emphasis role="bold">Example:</emphasis> 118 </para> 119 <para> 120 <programlisting>// An evaluation context that increments all 121// integer terminals in-place. 122struct increment_ints : 123 <classname>proto::context::callable_context</classname>< 124 increment_ints const // derived context 125 <classname>proto::context::null_context</classname> const // fall-back context 126 > 127{ 128 typedef void result_type; 129 130 // Handle int terminals here: 131 void operator()(proto::tag::terminal, int &i) const 132 { 133 ++i; 134 } 135};</programlisting> 136 </para> 137 <para> 138 With <computeroutput>increment_ints</computeroutput>, we can do the following: 139 </para> 140 <para> 141 <programlisting><classname>proto::literal</classname><int> i = 0, j = 10; 142proto::eval( i - j * 3.14, increment_ints() ); 143 144assert( i.get() == 1 && j.get() == 11 );</programlisting> 145 </para> 146 </description> 147 <struct name="eval"> 148 <template> 149 <template-type-parameter name="Expr"/> 150 <template-type-parameter name="ThisContext"> 151 <default>Context</default> 152 </template-type-parameter> 153 </template> 154 <description> 155 <para> 156 A BinaryFunction that accepts an <computeroutput>Expr</computeroutput> and a 157 <computeroutput>Context</computeroutput>, and either fans out the expression and passes 158 it to the context, or else hands off the expression to <computeroutput>DefaultCtx</computeroutput>. 159 </para> 160 <para> 161 If <computeroutput>Context</computeroutput> is a <conceptname>PolymorphicFunctionObject</conceptname> 162 such that it can be invoked with the tag and children of <computeroutput>Expr</computeroutput>, as 163 <computeroutput>ctx(typename Expr::proto_tag(), child_c<0>(expr),... child_c<N>(expr))</computeroutput>, 164 then <computeroutput>eval<Expr, ThisContext></computeroutput> inherits from 165 <computeroutput><classname>proto::context::callable_eval</classname><Expr, ThisContext></computeroutput>. 166 Otherwise, <computeroutput>eval<Expr, ThisContext></computeroutput> inherits from 167 <computeroutput>DefaultCtx::eval<Expr, Context></computeroutput>. 168 </para> 169 </description> 170 <inherit><type><replaceable>see-below</replaceable></type></inherit> 171 </struct> 172 </struct> 173 </namespace> 174 </namespace> 175 </namespace> 176</header> 177