1 [/==============================================================================
2 Copyright (C) 2001-2010 Joel de Guzman
3 Copyright (C) 2001-2005 Dan Marsden
4 Copyright (C) 2001-2010 Thomas Heller
6 Distributed under the Boost 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 ===============================================================================/]
10 [section:actor Actors in Detail]
14 The main concept is the `Actor`. An `Actor` is a model of the __PFO__ concept
15 (that can accept 0 to N arguments (where N is a predefined maximum).
17 An `Actor` contains a valid Phoenix Expression, a call to one of the function
18 call operator overloads, starts the evaluation process.
20 [note You can set `BOOST_PHOENIX_LIMIT`, the predefined maximum arity an
21 actor can take. By default, `BOOST_PHOENIX_LIMIT` is set to 10.]
23 The `actor` template class models the `Actor` concept:
25 template <typename Expr>
28 template <typename Sig>
31 typename result_of::actor<Expr>::type
34 template <typename T0>
35 typename result_of::actor<Expr, T0 &>::type
36 operator()(T0& _0) const;
38 template <typename T0>
39 typename result_of::actor<Expr, T0 const &>::type
40 operator()(T0 const & _0) const;
45 [table Actor Concept Requirements
51 [`actor(arg0, arg1, ..., argN)`]
52 [Function call operators to start the evaluation]
55 [`boost::result_of<Actor<Expr>(Arg0, Arg1, ..., ArgN)>::type`]
56 [Result of the evaluation]
59 [`result_of::actor<Expr, Arg0, Arg1, ..., ArgN>::type`]
60 [Result of the evaluation]
64 [heading Function Call Operators]
66 There are 2*N function call operators for 0 to N arguments (N == `BOOST_PHOENIX_LIMIT`).
67 The actor class accepts the arguments and forwards the arguments to the default
70 Additionally, there exist function call operators accepting permutations of const
71 and non-const references. These operators are created for all N <=
72 `BOOST_PHOENIX_PERFECT_FORWARD_LIMIT` (which defaults to 3).
74 [def $http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm]
76 [note *Forwarding Function Problem*
78 There is a known issue with current C++ called the "__forwarding__".
79 The problem is that given an arbitrary function `F`, using current C++
80 language rules, one cannot create a forwarding function `FF` that
81 transparently assumes the arguments of `F`.
86 On an actor function call, before calling the evaluation function, the actor created a *context*.
87 This context consists of an `Environment` and an `Action` part. These contain all information
88 necessary to evaluate the given expression.
90 [table Context Concept Requirements
96 [`result_of::context<Env, Actions>::type`]
101 [A Context containing environment `e` and actions `a`]
104 [`result_of::env<Context>::type`]
105 [Type of the contained Environment]
112 [`result_of::actions<Context>::type`]
113 [Type of the contained Actions]
121 [heading Environment]
123 The Environment is a model of __random_access__.
125 The arguments passed to the actor's function call operator are collected inside the Environment:
127 [$images/funnel_in.png]
129 Other parts of the library (e.g. the scope module) extends the `Environment`
130 concept to hold other information such as local variables, etc.
134 Actions is the part of Phoenix which are responsible for giving the actual expressions
135 a specific behaviour. During the traversal of the Phoenix Expression Tree these actions
136 are called whenever a specified rule in the grammar matches.
140 template <typename Rule>
144 The nested `when` template is required to be __proto_primitive_transform__. No
145 worries, you don't have to learn __proto__ just yet! Phoenix provides some wrappers
146 to let you define simple actions without the need to dive deep into proto.
148 Phoenix ships with a predefined `default_actions` class that evaluates the expressions with
151 struct default_actions
153 template <typename Rule, typename Dummy = void>
155 : proto::_default<meta_grammar>
159 For more information on how to use the default_actions class and how to attach custom actions
160 to the evaluation process, see [link phoenix.inside.actions more on actions].
166 template <typename Expr, typename Context>
167 __unspecified__ operator()(Expr &, Context &);
170 evaluator const eval = {};
172 The evaluation of a Phoenix expression is started by a call to the function call operator of
175 The evaluator is called by the `actor` function operator overloads after the context is built up.
176 For reference, here is a typical `actor::operator()` that accepts two arguments:
178 template <typename T0, typename T1>
179 typename result_of::actor<Expr, T0 &, T1 &>::type
180 operator()(T0 &t0, T1 &t1) const
182 fusion::vector2<T0 &, T1 &> env(t0, t1);
184 return eval(*this, context(env, default_actions()));
187 [heading result_of::actor]
189 For reasons of symmetry to the family of `actor::operator()` there is a special
190 metafunction usable for actor result type calculation named `result_of::actor`. This
191 metafunction allows us to directly specify the types of the parameters to be
192 passed to the `actor::operator()` function. Here's a typical `actor_result` that
193 accepts two arguments:
197 template <typename Expr, typename T0, typename T1>
200 typedef fusion::vector2<T0, T1> env_tpe;
201 typedef typename result_of::context<env_type, default_actions>::type ctx_type
202 typedef typename boost::result_of<evaluator(Expr const&, ctx_type)>::type type;