1[/==============================================================================
2    Copyright (C) 2001-2010 Joel de Guzman
3    Copyright (C) 2001-2005 Dan Marsden
4    Copyright (C) 2001-2010 Thomas Heller
5
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===============================================================================/]
9
10[section Transforming the Expression Tree]
11
12This example will show how to write __phoenix_actions__ that transform the
13Phoenix AST.
14
15[:
16"/Lisp macros transform the program structure itself, with the full language
17available to express such transformations./"
18
19[@http://en.wikipedia.org/wiki/Lisp_macro#Lisp_macros Wikipedia]
20]
21
22What we want to do is to invert some arithmetic operators, i.e. plus will be
23transformed to minus, minus to plus, multiplication to division and division to
24multiplication.
25
26Let's start with defining our default action:
27
28[def __proto_nary_expr__    [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/nary_expr.html `proto::nary_expr`]]
29[def __proto_vararg__       [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/vararg.html `proto::vararg`]]
30[def __proto_when__         [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/when.html `proto::when`]]
31[def __proto_underscore__   [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/_.html `proto::_`]]
32[def __proto_make_expr__    [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/functional/make_expr.html `proto::functional::make_expr`]]
33
34    struct invert_actions
35    {
36        template <typename Rule>
37        struct when
38            : __proto_nary_expr__
39                  __proto_underscore__
40                , __proto_vararg__
41                      __proto_when__<__proto_underscore__, phoenix::evaluator(__proto_underscore__, phoenix::_context)
42                  >
43              >
44        {};
45    };
46
47Wow, this looks complicated! Granted you need to know a little bit about __proto__
48(For a good introduction read through the
49 [@http://cpp-next.com/archive/2010/08/expressive-c-introduction/ Expressive C++] series).
50
51By default, we don't want to do anything, well, not exactly nothing, but just
52continue transformation into its arguments.
53
54So, it is done by the following:
55
56* For each arguments are passed to evaluator (with the current context, that contains our invert_actions)
57* Create new expression using current expression tag, what is done by __proto_underscore__, with the result of evaluated arguments
58
59So, after the basics are set up, we can start by writing the transformations we
60want to have on our tree:
61
62    // Transform plus to minus
63    template <>
64    struct invert_actions::when<phoenix::rule::plus>
65        : __proto_call__<
66            __proto_make_expr__<proto::tag::minus>(
67                phoenix::evaluator(proto::_left, phoenix::_context)
68              , phoenix::evaluator(proto::_right, phoenix::_context)
69            )
70        >
71    {};
72
73What is done is the following:
74
75* The left expression is passed to evaluator (with the current context, that contains our invert_actions)
76* The right expression is passed to evaluator (with the current context, that contains our invert_actions)
77* The result of these two __proto_transforms__ are passed to __proto_make_expr__ which returns the freshly created expression
78
79After you know what is going on, maybe the rest doesn't look so scary anymore:
80
81    // Transform minus to plus
82    template <>
83    struct invert_actions::when<phoenix::rule::minus>
84        : __proto_call__<
85            __proto_make_expr__<proto::tag::plus>(
86                phoenix::evaluator(proto::_left, phoenix::_context)
87              , phoenix::evaluator(proto::_right, phoenix::_context)
88            )
89        >
90    {};
91
92    // Transform multiplies to divides
93    template <>
94    struct invert_actions::when<phoenix::rule::multiplies>
95        : __proto_call__<
96            __proto_make_expr__<proto::tag::divides>(
97                phoenix::evaluator(proto::_left, phoenix::_context)
98              , phoenix::evaluator(proto::_right, phoenix::_context)
99            )
100        >
101    {};
102
103    // Transform divides to multiplies
104    template <>
105    struct invert_actions::when<phoenix::rule::divides>
106        : __proto_call__<
107            __proto_make_expr__<proto::tag::multiplies>(
108                phoenix::evaluator(proto::_left, phoenix::_context)
109              , phoenix::evaluator(proto::_right, phoenix::_context)
110            )
111        >
112    {};
113
114That's it! Now that we have our actions defined, we want to evaluate some of our expressions with them:
115
116    template <typename Expr>
117    // Calculate the result type: our transformed AST
118    typename boost::result_of<
119        phoenix::evaluator(
120            Expr const&
121          , phoenix::result_of::context<int, invert_actions>::type
122        )
123    >::type
124    invert(Expr const & expr)
125    {
126        return
127            // Evaluate it with our actions
128            phoenix::eval(
129                expr
130              , phoenix::context(
131                    int()
132                  , invert_actions()
133                )
134            );
135    }
136
137Run some tests to see if it is working:
138
139    invert(_1);                    // --> _1
140    invert(_1 + _2);               // --> _1 - _2
141    invert(_1 + _2 - _3);          // --> _1 - _2 + _3
142    invert(_1 * _2);               // --> _1 / _2
143    invert(_1 * _2 / _3);          // --> _1 / _2 * _3
144    invert(_1 * _2 + _3);          // --> _1 / _2 - _3
145    invert(_1 * _2 - _3);          // --> _1 / _2 + _2
146    invert(if_(_1 * _4)[_2 - _3]); // --> if_(_1 / _4)[_2 + _3]
147    _1 * invert(_2 - _3));         // --> _1 * _2 + _3
148
149__note__ The complete example can be found here: [@../../example/invert.cpp example/invert.cpp]
150
151/Pretty simple .../
152
153[endsect]
154