[/==============================================================================
    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 Composite]

Actors may be combined in a multitude of ways to form composites. Composites are
actors that are composed of zero or more actors. Composition is hierarchical. An
element of the composite can be a primitive or again another composite. The
flexibility to arbitrarily compose hierarchical structures allows us to form
intricate constructions that model complex functions, statements and
expressions.

A composite is-a tuple of 0..N actors. N is the predefined maximum actors a
composite can take.

[note You can set `PHOENIX_COMPOSITE_LIMIT`, the predefined maximum
actors a composite can take. By default, `PHOENIX_COMPOSITE_LIMIT` is set to
`PHOENIX_LIMIT` (See [link phoenix.reference.actor Actor]).]

In Phoenix, every actor is a composite. Phoenix is designed in a way that
expressions form something like a S-Expr structure. This means that the main
building block of phoenix is `proto::function`.

The concept of a composite is therefore best formulated in terms of `proto::function`

	actor<proto::function<F, env, A0, ... AN> >

[variablelist Notation
    [[`F`]                        [The evaluator]]
    [[`env`]                      [The environment (placeholder which gets filled during the actual evaluation)]]
    [[`A0, ... AN`]               [The data carried with an actor]]
]

As mentioned each of the `A0...AN` can be another actor or composite, this makes
an actor a recursive structure. The actual evaluation is handle by the evaluator `F`.
To ease the creation of actors, there exist helper class responsible for
creating the correct types.

[h2 `make_expr`]

The first one is the bare-metal of the one provided. It is the natural expression
template generator facility of __proto__.

Usage Example:

    template <typename F, typename A0>
	 typename proto::result_of::make_expr<proto::tag::function, phoenix_domain, F, A0>::type const
    make_function(F f, A0 const& a0)
	 {
        return proto::make_expr<proto::tag::function, phoenix_domain>(f, a0);
    }

This example creates a lazy function actor, usable within every phoenix expression

[h2 `compose_ex`]

The second one is building upon the proto::make_expr facility, and represents
the heart of phoenix expression creation.

[*Synopsis]

	template <typename F, template <typename> Actor, typename A0 ... AN>
	struct compose_ex
	{
		typedef proto::result_of::make_expr<
			proto::tag::function
		 , default_domain_with_basic_expr
		 , funcwrap<F>
		 , A0 ... AN
		>::type base_type

		typedef Actor<base_type> result_type;

		result_type const
		operator()(A0 const& a0, ... AN const& an) const;
	};

[h2 `compose`]

Convenience class which has `actor<Expr>` as its Actor:

	template <typename F, template <typename> Actor, typename A0 ... AN>
	struct compose: compose_ex<F, actor, A0, ... AN> {};

[endsect]