[/==============================================================================
    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:expression Phoenix Expressions]

A Phoenix Expression is a model of the __proto_expr__ Concept. These expressions
are wrapped inside an [link phoenix.inside.actor Actor] template. The `actor` provides
the function call operator which evaluates the expressions.
The `actor` is the domain specific wrapper around Phoenix expressions.

By design, Phoenix Expressions do not carry any information on how they will be
evaluated later on. They are the data structure on which the `Actions` will work.

The library provides a convenience template to define expressions:
    
    template <template <typename> Actor, typename Tag, typename A0, ..., typename A1>
    struct expr_ext
        : proto::transform<expr_ext<Actor, Tag, A0, ..., A1> >
    {
        typedef __unspecified__ base_expr;
        typedef Actor<base_expr> type;

        typedef __unspecified__ proto_grammar;

        static type make(A0 a0, ..., A1 a1);
    };

    template <typename Tag, typename A0, ..., typename A1>
    struct expr : expr_ext<actor, Tag, A0, ..., A1> {};

[*Notation]
[variablelist
    [[`A0...AN`] [Child node types]]
    [[`a0...aN`] [Child node objects]]
    [[`G0...GN`] [__proto__ grammar types]]
]

[*Expression Semantics]
[table
    [[Expression] [Semantics]]
    [[`expr<Tag, A0...AN>::type`] [The type of Expression having tag `Tag` and `A0...AN` children]]
    [[`expr<Tag, G0...GN>`] [A __proto__ grammar and __proto_pass_through_transform__]]
    [[`expr<Tag, A0...AN>::make(a0...aN)`] [Returns a Phoenix Expression]]
]

[note
	You might have noticed the template template argument `Actor` used in
	`expr_ext`. This can be a user supplied custom Actor adding other member
	functions or objects than the default `actor` template. See
	[link phoenix.examples.extending_actors Extending Actors] for more details.
]

[heading meta_grammar]

Defining expressions is only part of the game to make it a valid Phoenix Expression.
In order to use the expressions in the Phoenix domain, we need to "register" them
to our grammar.

The `meta_grammar` is a struct for exactly that purpose. It is an openly extendable __proto__ Grammar:
    
    struct meta_grammar
        : proto::switch_<meta_grammar>
    {
        template <typename Tag, typename Dummy>
        struct case_
            : proto::not_<proto::_>
        {};
    };

As you can see, by default the `meta_grammar` matches nothing. With every [link phoenix.modules Module]
you include this grammar gets extended by various expressions.

[heading Example]

Define an expression:

    template <typename Lhs, typename Rhs>
    struct plus
        : expr<proto::tag::plus, Lhs, Rhs>
    {};

And add it to the grammar:

    template <>
    struct meta_grammar::case_<proto::tag::plus>
        : enable_rule<
            plus<
                meta_grammar
              , meta_grammar
            >
        >
    {};

Define a generator function to make the life of our potential users easier:

    template <typename Lhs, typename Rhs>
    typename plus<Lhs, Rhs>::type
    plus(Lhs const & lhs, Rhs const & rhs)
    {
        return expression::plus<Lhs, Rhs>::make(lhs, rhs);
    }

Look if it really works:

    plus(6, 5)();

returns 11!

    proto::display_expr(plus(5, 6));

prints:

    plus(
        terminal(6)
      , terminal(5)
    )

See [@../../example/define_expression.cpp define_expression.cpp] for the full example.

[note
	The example shown here only works because `default_actions` knows how to handle
	an expression having the `proto::tag::plus` and two children. This is because
	`default_actions` uses the `proto::_default<meta_grammar>` transform to
    evaluate operators and functions. Learn more about actions
    [link phoenix.inside.actions here].
]

[section Boilerplate Macros]

When having more and more expressions, you start to realize that this is a very
repetetive task. Phoenix provides boilerplate macros that make defining Phoenix
Expressions as you have seen in the
[link phoenix.inside.expression previous section] look like a piece of cake.


[/
These expressions generate the following:
* A tag (in the underlying namespace tag)
* An expression 
* an expression type in namespace expression
]

[section BOOST_PHOENIX_DEFINE_EXPRESSION]

[heading Description]

`BOOST_PHOENIX_DEFINE_EXPRESSION` is a macro that can be used to generate all the
necessary boilerplate to create Phoenix Expressions

[heading Synopsis]
    
    BOOST_PHOENIX_DEFINE_EXPRESSION(
        (namespace_seq)(name)
      , (child_grammar0)
        (child_grammar1)
        ...
    )

[heading Semantics]

The above macro generates the necessary code for an expression `name` in
namespace `namespace_seq`. The sequence of `(child_grammarN)` declares how many
children the expression will have and what `proto::grammar` they match.

The macro should be used at global scope. `namespace_seq` shall be the sequence
of namespaces under which the following symbols will be defined:

    namespace tag
    {
        struct name;
    }

    namespace expression
    {
        template <typename A0, typename A1 ... typename AN>
        struct name
            : boost::phoenix::expr<
                tag::name
              , A0
              , A1
                ...
              , AN
            >
    }

    namespace rule
    {
        struct name
            : boost::phoenix::expr<
                child_grammar0
              , child_grammar1
                ...
              , child_grammarN
            >
        {};
    }

    namespace functional
    {
        struct make_name; // A polymorphic function object that can be called to create the expression node
    }

    namespace result_of
    {
        template <typename A0, typename A1 ... typename AN>
        struct make_name; // The result type of the expression node
    }

    // convenience polymorphic function to create an expression node
    template <typename A0, typename A1 ... typename AN>
    result_of::make_name<A0, A1 ... AN>
    make_name(A0 const & a0, A1 const & a1 ... AN const & an);

This macros also adds a specialization for `meta_grammar::case_<tag::name>` to
enable the rule for further use in actions.

[heading Header]

    #include <boost/phoenix/core/expression.hpp>

[heading Example]

The example from the previous section can be rewritten as:

    BOOST_PHOENIX_DEFINE_EXPRESSION(
        (plus)
      , (meta_grammar)               // Lhs
        (meta_grammar)               // Rhs
    )

    template <typename Lhs, typename Rhs>
    typename plus<Lhs, Rhs>::type
    plus(Lhs const & lhs, Rhs const & rhs)
    {
        return expression::plus<Lhs, Rhs>::make(lhs, rhs);
    }

[endsect]

[section BOOST_PHOENIX_DEFINE_EXPRESSION_VARARG]

[heading Description]

`BOOST_PHOENIX_DEFINE_EXPRESSION_VARARG` is a macro that can be used to generate all the
necessary boilerplate to create Phoenix Expressions

[heading Synopsis]
    
    BOOST_PHOENIX_DEFINE_EXPRESSION_VARARG(
        (namespace_seq)(name)
      , (child_grammar0)
        (child_grammar1)
        ...
        (child_grammarN)
      , N
    )

[heading Semantics]

The above macro generates the necessary code for an expression `name` in
namespace `namespace_seq`. `N` is the maximum number of variable children.
All but the last elements in the grammar sequence are required children of
the expression, and the last denotes a variable number of children. The number
of children an expression of this kind can hold is therefor `N-1` plus the size of
the sequence

The macro should be used at global scope. `namespace_seq` shall be the sequence
of namespaces under which the following symbols will be defined:

    namespace tag
    {
        struct name;
    }

    namespace expression
    {
        template <typename A0, typename A1 ... typename AN>
        struct name
            : boost::phoenix::expr<
                tag::name
              , A0
              , A1
                ...
              , AN
            >
        {};
    }

    namespace rule
    {
        struct name
            : expression::name<
                child_grammar0
              , child_grammar1
                ...
              , proto::vararg<child_grammarN>
            >
        {};
    }

    namespace functional
    {
        struct make_name; // A polymorphic function object that can be called to create the expression node
    }

    namespace result_of
    {
        template <typename A0, typename A1 ... typename AN>
        struct make_name; // The result type of the expression node
    }

    // convenience polymorphic function to create an expression node
    template <typename A0, typename A1 ... typename AN>
    result_of::make_name<A0, A1 ... AN>
    make_name(A0 const & a0, A1 const & a1 ... AN const & an);

This macros also adds a specialization for `meta_grammar::case_<tag::name>` to
enable the rule for further use in actions.

[heading Header]

    #include <boost/phoenix/core/expression.hpp>

[heading Example]

    BOOST_PHOENIX_DEFINE_EXPRESSION_VARARG(
        (boost)(phoenix)(mem_fun_ptr)
      , (meta_grammar)                // Pointer to Object
        (meta_grammar)                // Member pointer
        (meta_grammar)                // Variable number of arguments
      , BOOST_PHOENIX_LIMIT
    )

This defines the member function pointer operator expression as described in
[link phoenix.modules.operator operators].

[endsect]

[section BOOST_PHOENIX_DEFINE_EXPRESSION_EXT]

[heading Description]

`BOOST_PHOENIX_DEFINE_EXPRESSION_EXT` is a macro that can be used to generate all the
necessary boilerplate to create Phoenix Expressions

[heading Synopsis]
    
    BOOST_PHOENIX_DEFINE_EXPRESSION_EXT(
        actor
      , (namespace_seq)(name)
      , (child_grammar0)
        (child_grammar1)
        ...
        (child_grammarN)
      , N
    )

[heading Semantics]

The above macro generates the necessary code for an expression `name` in
namespace `namespace_seq`. The sequence of `(child_grammarN)` declares how many
children the expression will have and what `proto::grammar` they match.

The macro should be used at global scope. `namespace_seq` shall be the sequence
of namespaces under which the following symbols will be defined:

    namespace tag
    {
        struct name;
    }

    namespace expression
    {
        template <typename A0, typename A1 ... typename AN>
        struct name
            : boost::phoenix::expr_ext<
                actor
              , tag::name
              , A0
              , A1
                ...
              , AN
            >
    }

    namespace rule
    {
        struct name
            : boost::phoenix::expr<
                child_grammar0
              , child_grammar1
                ...
              , child_grammarN
            >
        {};
    }

    namespace functional
    {
        struct make_name; // A polymorphic function object that can be called to create the expression node
    }

    namespace result_of
    {
        template <typename A0, typename A1 ... typename AN>
        struct make_name; // The result type of the expression node
    }

    // convenience polymorphic function to create an expression node
    template <typename A0, typename A1 ... typename AN>
    result_of::make_name<A0, A1 ... AN>
    make_name(A0 const & a0, A1 const & a1 ... AN const & an);

This macros also adds a specialization for `meta_grammar::case_<tag::name>` to
enable the rule for further use in actions.

[heading Header]

    #include <boost/phoenix/core/expression.hpp>

[heading Example]

    BOOST_PHOENIX_DEFINE_EXPRESSION_EXT(
        if_actor
      , (boost)(phoenix)(if_)
      , (meta_grammar) // Cond
        (meta_grammar) // Then
    )

This defines the if_ expression. The custom actor defines `else_` as a member.

[endsect]

[section BOOST_PHOENIX_DEFINE_EXPRESSION_EXT_VARARG]

[heading Description]

`BOOST_PHOENIX_DEFINE_EXPRESSION_EXT_VARARG` is a macro that can be used to generate all the
necessary boilerplate to create Phoenix Expressions

[heading Synopsis]
    
    BOOST_PHOENIX_DEFINE_EXPRESSION_EXT_VARARG(
        actor
      , (namespace_seq)(name)
      , (child_grammar0)
        (child_grammar1)
        ...
        (child_grammarN)
      , N
    )

[heading Semantics]

The above macro generates the necessary code for an expression `name` in
namespace `namespace_seq`. `N` is the maximum number of variable children.
All but the last elements in the grammar sequence are required children of
the expression, and the last denotes a variable number of children. The number
of children an expression of this kind can hold is therefor `N-1` plus the size of
the sequence

The macro should be used at global scope. `namespace_seq` shall be the sequence
of namespaces under which the following symbols will be defined:

    namespace tag
    {
        struct name;
    }

    namespace expression
    {
        template <typename A0, typename A1 ... typename AN>
        struct name
            : boost::phoenix::expr_ext<
                actor
              , tag::name
              , A0
              , A1
                ...
              , AN
            >
        {};
    }

    namespace rule
    {
        struct name
            : expression::name<
                child_grammar0
              , child_grammar1
                ...
              , proto::vararg<child_grammarN>
            >
        {};
    }

    namespace functional
    {
        struct make_name; // A polymorphic function object that can be called to create the expression node
    }

    namespace result_of
    {
        template <typename A0, typename A1 ... typename AN>
        struct make_name; // The result type of the expression node
    }

    // convenience polymorphic function to create an expression node
    template <typename A0, typename A1 ... typename AN>
    result_of::make_name<A0, A1 ... AN>
    make_name(A0 const & a0, A1 const & a1 ... AN const & an);

This macros also adds a specialization for `meta_grammar::case_<tag::name>` to
enable the rule for further use in actions.

[heading Header]

    #include <boost/phoenix/core/expression.hpp>

[heading Example]

TBD

[endsect]

[endsect]

[endsect]