early-access version 3088

externals/vcpkg/buildtrees/boost-phoenix/src/ost-1.79.0-b42fb470fd.clean/doc/examples/adding.qbk

@@ -0,0 +1,111 @@
+[/==============================================================================
+    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 Adding an expression]
+
+This is not a toy example. This is actually part of the library. Remember the
+[link phoenix.modules.statement.while__statement `while`] lazy statement? Putting together
+everything we've learned so far, we eill present it here in its entirety
+(verbatim):
+
+    BOOST_PHOENIX_DEFINE_EXPRESSION(
+        (boost)(phoenix)(while_)
+      , (meta_grammar)           // Cond
+        (meta_grammar)           // Do
+    )
+
+    namespace boost { namespace phoenix
+    {
+        struct while_eval
+        {
+            typedef void result_type;
+
+            template <typename Cond, typename Do, typename Context>
+            result_type
+            operator()(Cond const& cond, Do const& do_, Context & ctx) const
+            {
+                while(eval(cond, ctx))
+                {
+                    eval(do_, ctx);
+                }
+            }
+        };
+        
+        template <typename Dummy>
+        struct default_actions::when<rule::while_, Dummy>
+            : call<while_eval, Dummy>
+        {};
+
+        template <typename Cond>
+        struct while_gen
+        {
+            while_gen(Cond const& cond) : cond(cond) {}
+
+            template <typename Do>
+            typename expression::while_<Cond, Do>::type const
+            operator[](Do const& do_) const
+            {
+                return expression::while_<Cond, Do>::make(cond, do_);
+            }
+
+            Cond const& cond;
+        };
+
+        template <typename Cond>
+        while_gen<Cond> const
+        while_(Cond const& cond)
+        {
+            return while_gen<Cond>(cond);
+        }
+    }}
+
+`while_eval` is an example of how to evaluate an expression. It gets called in
+the `rule::while` action. `while_gen` and `while_` are the expression template
+front ends. Let's break this apart to undestand what's happening. Let's start at
+the bottom. It's easier that way.
+
+When you write:
+
+    while_(cond)
+
+we generate an instance of `while_gen<Cond>`, where `Cond` is the type of `cond`.
+`cond` can be an arbitrarily complex actor expression. The `while_gen` template
+class has an `operator[]` accepting another expression. If we write:
+
+    while_(cond)
+    [
+        do_
+    ]
+
+it will generate a proper composite with the type:
+
+    expression::while_<Cond, Do>::type
+
+where `Cond` is the type of `cond` and `Do` is the type of `do_`. Notice how we are using Phoenix's
+[link phoenix.inside.expression Expression] mechanism here
+        
+    template <typename Do>
+    typename expression::while_<Cond, Do>::type const
+    operator[](Do const& do_) const
+    {
+        return expression::while_<Cond, Do>::make(cond, do_);
+    }
+
+Finally, the `while_eval` does its thing:
+
+    while(eval(cond, ctx))
+    {
+        eval(do_, ctx);
+    }
+
+`cond` and `do_`, at this point, are instances of [link phoenix.inside.actor Actor]. `cond` and `do_` are the [link phoenix.inside.actor Actors] 
+passed as parameters by `call`, ctx is the [link phoenix.inside.actor Context]
+
+[endsect]
+

externals/vcpkg/buildtrees/boost-phoenix/src/ost-1.79.0-b42fb470fd.clean/doc/examples/extending_actors.qbk

@@ -0,0 +1,177 @@
+[/==============================================================================
+    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 Extending Actors]
+
+[link phoenix.inside.actor Actors] are one of the main parts of the
+library, and one of the many customization points. The default actor implementation
+provides several operator() overloads which deal with the evaluation of expressions.
+
+For some use cases this might not be enough. For convenience it is thinkable to
+provide custom member functions which generate new expressions. An example is the
+[link phoenix.modules.statement.___if_else_____statement '''if_else_'''
+Statement] which provides an additional else member for generating a lazy if-else
+expression. With this the actual Phoenix expression becomes more expressive.
+
+Another scenario is to give actors the semantics of a certain well known interface
+or concept. This tutorial like section will provide information on how to implement
+a custom actor which is usable as if it were a
+[@http://www.sgi.com/tech/stl/Container.html STL Container].
+
+[heading Requirements]
+
+Let's repeat what we want to have:
+
+[table
+	[[Expression] [Semantics]]
+	[[`a.begin()`] [Returns an iterator pointing to the first element in the container.]]
+	[[`a.end()`] [Returns an iterator pointing one past the last element in the container.]]
+	[[`a.size()`] [Returns the size of the container, that is, its number of elements.]]
+	[[`a.max_size()`] [Returns the largest size that this container can ever have.]]
+	[[`a.empty()`] [Equivalent to a.size() == 0. (But possibly faster.)]]
+	[[`a.swap(b)`] [Equivalent to swap(a,b)]]
+]
+
+Additionally, we want all the operator() overloads of the regular actor.
+
+[heading Defining the actor]
+
+The first version of our `container_actor` interface will show the general
+principle. This will be continually extended. For the sake of simplicity,
+every member function generator will return [link phoenix.modules.core.nothing `nothing`]
+at first.
+
+	template <typename Expr>
+	struct container_actor
+		: actor<Expr>
+	{
+		typedef actor<Expr> base_type;
+		typedef container_actor<Expr> that_type;
+		
+		container_actor( base_type const& base )
+			: base_type( base ) {}
+
+		expression::null<mpl::void_>::type const begin() const { return nothing; }
+		expression::null<mpl::void_>::type const end() const { return nothing; }
+		expression::null<mpl::void_>::type const size() const { return nothing; }
+		expression::null<mpl::void_>::type const max_size() const { return nothing; }
+		expression::null<mpl::void_>::type const empty() const { return nothing; }
+
+		// Note that swap is the only function needing another container.
+		template <typename Container>
+		expression::null<mpl::void_>::type const swap( actor<Container> const& ) const { return nothing; }
+	};
+
+[heading Using the actor]
+
+Although the member functions do nothing right now, we want to test if we can use
+our new actor.
+
+First, lets create a generator which wraps the `container_actor` around any other
+expression:
+
+    template <typename Expr>
+    container_actor<Expr> const
+    container( actor<Expr> const& expr )
+    {
+        return expr;
+    }
+
+Now let's test this:
+
+	std::vector<int> v;
+	v.push_back(0);
+	v.push_back(1);
+	v.push_back(2);
+	v.push_back(3);
+
+	(container(arg1).size())(v);
+
+Granted, this is not really elegant and not very practical (we could have just
+used phoenix::begin(v) from the [link phoenix.modules.stl.algorithm Phoenix algorithm module], 
+but we can do better.
+
+Let's have an [link phoenix.modules.core.arguments argument placeholder]
+which is usable as if it was a STL container:
+
+	container_actor<expression::argument<1>::type> const con1;
+	// and so on ...
+
+The above example can be rewritten as:
+
+	std::vector<int> v;
+	v.push_back(0);
+	v.push_back(1);
+	v.push_back(2);
+	v.push_back(3);
+
+	(con1.size())(v);
+
+Wow, that was easy!
+
+[heading Adding life to the actor]
+
+This one will be even easier!
+
+First, we define a [link phoenix.modules.function lazy function] which
+evaluates the expression we want to implement.
+Following is the implementation of the size function:
+
+	struct size_impl
+	{
+		// result_of protocol:
+		template <typename Sig>
+		struct result;
+
+		template <typename This, typename Container>
+		struct result<This(Container)>
+		{
+			// Note, remove reference here, because Container can be anything
+			typedef typename boost::remove_reference<Container>::type container_type;
+
+			// The result will be size_type
+			typedef typename container_type::size_type type;
+		};
+
+		template <typename Container>
+		typename result<size_impl(Container const&)>::type
+		operator()(Container const& container) const
+		{
+			return container.size();
+		}
+	};
+
+Good, this was the first part. The second part will be to implement the size member
+function of `container_actor`:
+	
+	template <typename Expr>
+	struct container_actor
+		: actor<Expr>
+	{
+		typedef actor<Expr> base_type;
+		typedef container_actor<Expr> that_type;
+		
+		container_actor( base_type const& base )
+			: base_type( base ) {}
+
+		typename expression::function<size_impl, that_type>::type const
+		size() const
+		{
+			function<size_impl> const f = size_impl();
+			return f(*this);
+		}
+	
+		// the rest ...
+	};
+
+It is left as an exercise to the user to implement the missing parts by reusing
+functions from the [link phoenix.modules.stl.algorithm Phoenix Algorithm Module]
+(the impatient take a look here: [@../../example/container_actor.cpp container_actor.cpp]).
+
+[endsect]

externals/vcpkg/buildtrees/boost-phoenix/src/ost-1.79.0-b42fb470fd.clean/doc/examples/transforming.qbk

@@ -0,0 +1,153 @@
+[/==============================================================================
+    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 Transforming the Expression Tree]
+
+This example will show how to write __phoenix_actions__ that transform the
+Phoenix AST.
+
+[:
+"/Lisp macros transform the program structure itself, with the full language
+available to express such transformations./"
+
+[@http://en.wikipedia.org/wiki/Lisp_macro#Lisp_macros Wikipedia]
+]
+
+What we want to do is to invert some arithmetic operators, i.e. plus will be
+transformed to minus, minus to plus, multiplication to division and division to
+multiplication.
+
+Let's start with defining our default action:
+
+[def __proto_nary_expr__    [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/nary_expr.html `proto::nary_expr`]]
+[def __proto_vararg__       [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/vararg.html `proto::vararg`]]
+[def __proto_when__         [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/when.html `proto::when`]]
+[def __proto_underscore__   [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/_.html `proto::_`]]
+[def __proto_make_expr__    [@http://www.boost.org/doc/libs/release/doc/html/boost/proto/functional/make_expr.html `proto::functional::make_expr`]]
+
+    struct invert_actions
+    {
+        template <typename Rule>
+        struct when
+            : __proto_nary_expr__
+                  __proto_underscore__
+                , __proto_vararg__
+                      __proto_when__<__proto_underscore__, phoenix::evaluator(__proto_underscore__, phoenix::_context)
+                  >
+              >
+        {};
+    };
+
+Wow, this looks complicated! Granted you need to know a little bit about __proto__
+(For a good introduction read through the
+ [@http://cpp-next.com/archive/2010/08/expressive-c-introduction/ Expressive C++] series).
+
+By default, we don't want to do anything, well, not exactly nothing, but just
+continue transformation into its arguments.
+
+So, it is done by the following:
+
+* For each arguments are passed to evaluator (with the current context, that contains our invert_actions)
+* Create new expression using current expression tag, what is done by __proto_underscore__, with the result of evaluated arguments
+
+So, after the basics are set up, we can start by writing the transformations we
+want to have on our tree:
+
+    // Transform plus to minus
+    template <>
+    struct invert_actions::when<phoenix::rule::plus>
+        : __proto_call__<
+            __proto_make_expr__<proto::tag::minus>(
+                phoenix::evaluator(proto::_left, phoenix::_context)
+              , phoenix::evaluator(proto::_right, phoenix::_context)
+            )
+        >
+    {};
+
+What is done is the following:
+
+* The left expression is passed to evaluator (with the current context, that contains our invert_actions)
+* The right expression is passed to evaluator (with the current context, that contains our invert_actions)
+* The result of these two __proto_transforms__ are passed to __proto_make_expr__ which returns the freshly created expression
+
+After you know what is going on, maybe the rest doesn't look so scary anymore:
+
+    // Transform minus to plus
+    template <>
+    struct invert_actions::when<phoenix::rule::minus>
+        : __proto_call__<
+            __proto_make_expr__<proto::tag::plus>(
+                phoenix::evaluator(proto::_left, phoenix::_context)
+              , phoenix::evaluator(proto::_right, phoenix::_context)
+            )
+        >
+    {};
+
+    // Transform multiplies to divides
+    template <>
+    struct invert_actions::when<phoenix::rule::multiplies>
+        : __proto_call__<
+            __proto_make_expr__<proto::tag::divides>(
+                phoenix::evaluator(proto::_left, phoenix::_context)
+              , phoenix::evaluator(proto::_right, phoenix::_context)
+            )
+        >
+    {};
+
+    // Transform divides to multiplies
+    template <>
+    struct invert_actions::when<phoenix::rule::divides>
+        : __proto_call__<
+            __proto_make_expr__<proto::tag::multiplies>(
+                phoenix::evaluator(proto::_left, phoenix::_context)
+              , phoenix::evaluator(proto::_right, phoenix::_context)
+            )
+        >
+    {};
+
+That's it! Now that we have our actions defined, we want to evaluate some of our expressions with them:
+
+    template <typename Expr>
+    // Calculate the result type: our transformed AST
+    typename boost::result_of<
+        phoenix::evaluator(
+            Expr const&
+          , phoenix::result_of::context<int, invert_actions>::type
+        )
+    >::type
+    invert(Expr const & expr)
+    {
+        return 
+            // Evaluate it with our actions
+            phoenix::eval(
+                expr
+              , phoenix::context(
+                    int()
+                  , invert_actions()
+                )
+            );
+    }
+
+Run some tests to see if it is working:
+
+    invert(_1);                    // --> _1
+    invert(_1 + _2);               // --> _1 - _2
+    invert(_1 + _2 - _3);          // --> _1 - _2 + _3
+    invert(_1 * _2);               // --> _1 / _2
+    invert(_1 * _2 / _3);          // --> _1 / _2 * _3
+    invert(_1 * _2 + _3);          // --> _1 / _2 - _3
+    invert(_1 * _2 - _3);          // --> _1 / _2 + _2
+    invert(if_(_1 * _4)[_2 - _3]); // --> if_(_1 / _4)[_2 + _3]
+    _1 * invert(_2 - _3));         // --> _1 * _2 + _3
+
+__note__ The complete example can be found here: [@../../example/invert.cpp example/invert.cpp]
+
+/Pretty simple .../
+
+[endsect]