phoenix/doc/inside/actor.qbk

[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2005 Dan Marsden
    Copyright (C) 2001-2010 Thomas Heller

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section:actor Actors in Detail]

[heading Actor]

The main concept is the `Actor`. An `Actor` is a model of the __PFO__ concept
(that can accept 0 to N arguments (where N is a predefined maximum).

An `Actor` contains a valid Phoenix Expression, a call to one of the function
call operator overloads, starts the evaluation process.

[note You can set `BOOST_PHOENIX_LIMIT`, the predefined maximum arity an
actor can take. By default, `BOOST_PHOENIX_LIMIT` is set to 10.]

The `actor` template class models the `Actor` concept:

    template <typename Expr>
    struct actor
    {
        template <typename Sig>
        struct result;

        typename result_of::actor<Expr>::type
        operator()() const;

        template <typename T0>
        typename result_of::actor<Expr, T0 &>::type
        operator()(T0& _0) const;

        template <typename T0>
        typename result_of::actor<Expr, T0 const &>::type
        operator()(T0 const & _0) const;

        //...
    };

[table Actor Concept Requirements
    [
     [Expression]
     [Semantics]
    ]
    [
     [`actor(arg0, arg1, ..., argN)`]
     [Function call operators to start the evaluation]
    ]
    [
     [`boost::result_of<Actor<Expr>(Arg0, Arg1, ..., ArgN)>::type`]
     [Result of the evaluation]
    ]
    [
     [`result_of::actor<Expr, Arg0, Arg1, ..., ArgN>::type`]
     [Result of the evaluation]
    ]
]

[heading Function Call Operators]

There are 2*N function call operators for 0 to N arguments (N == `BOOST_PHOENIX_LIMIT`).
The actor class accepts the arguments and forwards the arguments to the default
evaluation action.

Additionally, there exist function call operators accepting permutations of const
and non-const references. These operators are created for all N <=
`BOOST_PHOENIX_PERFECT_FORWARD_LIMIT` (which defaults to 3).

[def $http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2002/n1385.htm]

[note *Forwarding Function Problem*

    There is a known issue with current C++ called the "__forwarding__".
    The problem is that given an arbitrary function `F`, using current C++
    language rules, one cannot create a forwarding function `FF` that
    transparently assumes the arguments of `F`.
]

[heading Context]

On an actor function call, before calling the evaluation function, the actor created a *context*.
This context consists of an `Environment` and an `Action` part. These contain all information
necessary to evaluate the given expression.

[table Context Concept Requirements
    [
     [Expression]
     [Semantics]
    ]
    [
     [`result_of::context<Env, Actions>::type`]
     [Type of a Context]
    ]
    [
     [`context(e, a)`]
     [A Context containing environment `e` and actions `a`]
    ]
    [
     [`result_of::env<Context>::type`]
     [Type of the contained Environment]
    ]
    [
     [`env(ctx)`]
     [The environment]
    ]
    [
     [`result_of::actions<Context>::type`]
     [Type of the contained Actions]
    ]
    [
     [`actions(ctx)`]
     [The actions]
    ]
]

[heading Environment]

The Environment is a model of __random_access__.

The arguments passed to the actor's function call operator are collected inside the Environment:

[$images/funnel_in.png]

Other parts of the library (e.g. the scope module) extends the `Environment`
concept to hold other information such as local variables, etc.

[heading Actions]

Actions is the part of Phoenix which are responsible for giving the actual expressions
a specific behaviour. During the traversal of the Phoenix Expression Tree these actions
are called whenever a specified rule in the grammar matches.

    struct actions
    {
        template <typename Rule>
        struct when;
    };

The nested `when` template is required to be __proto_primitive_transform__. No
worries, you don't have to learn __proto__ just yet! Phoenix provides some wrappers
to let you define simple actions without the need to dive deep into proto.

Phoenix ships with a predefined `default_actions` class that evaluates the expressions with
C++ semantics:

    struct default_actions
    {
        template <typename Rule, typename Dummy = void>
        struct when
            : proto::_default<meta_grammar>
        {};
    };

For more information on how to use the default_actions class and how to attach custom actions
to the evaluation process, see [link phoenix.inside.actions more on actions].

[heading Evaluation]

    struct evaluator
    {
        template <typename Expr, typename Context>
        __unspecified__ operator()(Expr &, Context &);
    };

    evaluator const eval = {};

The evaluation of a Phoenix expression is started by a call to the function call operator of
`evaluator`.

The evaluator is called by the `actor` function operator overloads after the context is built up.
For reference, here is a typical `actor::operator()` that accepts two arguments:

    template <typename T0, typename T1>
    typename result_of::actor<Expr, T0 &, T1 &>::type
    operator()(T0 &t0, T1 &t1) const
    {
        fusion::vector2<T0 &, T1 &> env(t0, t1);

        return eval(*this, context(env, default_actions()));
    }

[heading result_of::actor]

For reasons of symmetry to the family of `actor::operator()` there is a special
metafunction usable for actor result type calculation named `result_of::actor`. This
metafunction allows us to directly specify the types of the parameters to be
passed to the `actor::operator()` function. Here's a typical `actor_result` that
accepts two arguments:

    namespace result_of
    {
        template <typename Expr, typename T0, typename T1>
        struct actor
        {
            typedef fusion::vector2<T0, T1>                                           env_tpe;
            typedef typename result_of::context<env_type, default_actions>::type      ctx_type
            typedef typename boost::result_of<evaluator(Expr const&, ctx_type)>::type type;
        };
    }

[endsect]