From abbc19cd0ad874e48ade95c1be81fb357ee9a729 Mon Sep 17 00:00:00 2001 From: Thomas Heller Date: Tue, 18 Jan 2011 09:13:32 +0000 Subject: [PATCH] documentation work [SVN r68222] --- doc/html/index.html | 14 +-- doc/html/phoenix/reference.html | 6 +- doc/html/phoenix/reference/the_language.html | 113 ++++++++++++++---- doc/html/phoenix/starter_kit.html | 2 +- doc/html/phoenix/starter_kit/composites.html | 6 +- doc/html/phoenix/starter_kit/primitives.html | 4 +- doc/reference.qbk | 91 ++++++++++++-- include/boost/phoenix/core/argument.hpp | 63 ++++++---- include/boost/phoenix/core/reference.hpp | 49 +++++--- include/boost/phoenix/core/terminal.hpp | 11 -- include/boost/phoenix/core/value.hpp | 4 +- .../boost/phoenix/scope/local_variable.hpp | 4 +- 12 files changed, 267 insertions(+), 100 deletions(-) diff --git a/doc/html/index.html b/doc/html/index.html index 4a86563..fdf9d27 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -27,7 +27,7 @@

Copyright © 2002-2005, 2010 Joel de Guzman, Dan Marsden, 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)

@@ -48,7 +48,7 @@

- + Preface

@@ -67,7 +67,7 @@ lambda_cpp

- + Description

@@ -85,7 +85,7 @@ library is organized in highly independent modules and layers.

- + How to use this manual

@@ -107,7 +107,7 @@ icons precede some text to indicate:

-

Table 1.1. Icons

+

Table 1.1. Icons

@@ -196,12 +196,12 @@

- + ...To my dear daughter, Phoenix

- +

Last revised: January 17, 2011 at 20:39:59 GMT

Last revised: January 18, 2011 at 08:32:20 GMT
diff --git a/doc/html/phoenix/reference.html b/doc/html/phoenix/reference.html index e5d61c2..0124d7a 100644 --- a/doc/html/phoenix/reference.html +++ b/doc/html/phoenix/reference.html @@ -79,7 +79,7 @@

- + Concepts

@@ -87,14 +87,14 @@ their meanings consider the following definitions.

- + Phoenix Actor

A Phoenix Actor is the C++ Expression that is generated by the Phoenix Generators.

- + Phoenix Generator

diff --git a/doc/html/phoenix/reference/the_language.html b/doc/html/phoenix/reference/the_language.html index 67d57f1..1f7d950 100644 --- a/doc/html/phoenix/reference/the_language.html +++ b/doc/html/phoenix/reference/the_language.html @@ -48,16 +48,57 @@ placeholder := _1 | _2 | _3 | ... | _PHOENIX_ARG_LIMIT +

+ Terminals are the core building blocks. Phoenix, by default distinguishes + between 3 types of terminals: +

+
    +
  1. + Value Terminals +
    2. +
  2. + Reference Terminals +
    3. +
  3. + Placeholders +
    4. +
+

+ The last two terminal types are handled by the terminal customization points. +

- Values are one of the core building blocks of Phoenix. + Whenever we see a constant in a partially applied function, an

-
- - Synopsis +
expression::value<T>::type
+
+

+ (where T is the type of the constant) is automatically created for us. + For instance: +

+
add(arg1, 6)
+
+

+ Passing a second argument, 6, + an expression::value<int>::type is implicitly created behind the + scenes. This is also equivalent to: +

+
add(arg1, val(6))
+
+

+ val(x) + generates an expression::value<T>::type + where T is the type of + x. In most cases, there's + no need to explicitly use val, + but, as we'll see later on, there are situations where this is unavoidable. +

+
+ + Synopsis 
namespace expression
 {
@@ -79,9 +120,11 @@
 typename expression::value<T>::type
 val(T t);
-
-

Table 1.2. Parameters

-
+
+ + Parameters +
+
@@ -108,7 +151,7 @@

- T + T

@@ -125,7 +168,7 @@

- t + t

@@ -141,10 +184,9 @@
-
-
- - Expression +
+ + Expression Semantics 
expression::value<T>::type
@@ -174,6 +216,15 @@
 

             Semantics: Calls expression::value<T>::make(t), Automatically deduces type T
           

+

+            [header Header] #include <boost/phoenix/core/value.hpp>
+          

+

+            [header Example]
+          

+

+            TODO
+
@@ -183,7 +234,7 @@ References are one of the core building blocks of Phoenix.

- + Synopsis 
namespace expression
@@ -193,7 +244,7 @@
     {
         typedef unspecified type;
 
-        static type make(T t);
+        static type make(T &t);
     };
 }
 
@@ -205,9 +256,11 @@
 typename expression::reference<T const>::type
 cref(T const & t);
-
-

Table 1.3. Parameters

-
+
+ + Parameters +
+
@@ -264,9 +317,8 @@
-
-
- +
+ Expression Semantics
@@ -287,7 +339,7 @@

Semantics: Creates a Phoenix reference - expression initialized with a copy of of the supplied argument + expression initialized with the supplied argument 

ref(t);
@@ -306,13 +358,26 @@ Semantics: Calls expression::reference<T const>::make(t), Automatically deduces type T

+
+ + Header +
+
#include <boost/phoenix/core/reference.hpp>
+
+
+ + Example +
+

+ TODO +

- + Synopsis 
template <int I>
diff --git a/doc/html/phoenix/starter_kit.html b/doc/html/phoenix/starter_kit.html
index 9d7752d..9c03d70 100644
--- a/doc/html/phoenix/starter_kit.html
+++ b/doc/html/phoenix/starter_kit.html
@@ -62,7 +62,7 @@
       into high gear quickly.
     

 

-
+
       Functors everywhere
     

 

diff --git a/doc/html/phoenix/starter_kit/composites.html b/doc/html/phoenix/starter_kit/composites.html
index c113f52..f414884 100644
--- a/doc/html/phoenix/starter_kit/composites.html
+++ b/doc/html/phoenix/starter_kit/composites.html
@@ -91,7 +91,7 @@
- + First Practical Example
@@ -238,7 +238,7 @@ function<is_odd_impl> is_odd;
- + Things to note:
@@ -269,7 +269,7 @@ (See function.cpp)

- + Predefined Lazy Functions
diff --git a/doc/html/phoenix/starter_kit/primitives.html b/doc/html/phoenix/starter_kit/primitives.html index c9c4284..345526e 100644 --- a/doc/html/phoenix/starter_kit/primitives.html +++ b/doc/html/phoenix/starter_kit/primitives.html @@ -47,7 +47,7 @@ World".

- + Lazy Evaluation
@@ -80,7 +80,7 @@ anything and defers the evaluation for later.

- + Callbacks

diff --git a/doc/reference.qbk b/doc/reference.qbk index 3cfc01f..21b5bac 100644 --- a/doc/reference.qbk +++ b/doc/reference.qbk @@ -105,9 +105,34 @@ The definition of the language is split into the following parts: placeholder := _1 | _2 | _3 | ... | _PHOENIX_ARG_LIMIT -[section:blubb Value] +Terminals are the core building blocks. Phoenix, by default distinguishes +between 3 types of terminals: -Values are one of the core building blocks of Phoenix. +# Value Terminals +# Reference Terminals +# Placeholders + +The last two terminal types are handled by the terminal customization points. + +[section Value] + +Whenever we see a constant in a partially applied function, an + + expression::value::type + +(where T is the type of the constant) is automatically created for +us. For instance: + + add(arg1, 6) + +Passing a second argument, `6`, an `expression::value::type` is implicitly created +behind the scenes. This is also equivalent to: + + add(arg1, val(6)) + +`val(x)` generates an `expression::value::type` where `T` is the type of `x`. In most +cases, there's no need to explicitly use `val`, but, as we'll see later on, +there are situations where this is unavoidable. [heading Synopsis] namespace expression @@ -130,10 +155,12 @@ Values are one of the core building blocks of Phoenix. typename expression::value::type val(T t); -[table Parameters +[heading Parameters] + +[table [[Parameter] [Requirement] [Description]] - [[T] [Model of Copy Constructible] [Operation's Argument]] - [[t] [Object of type T] [Operation's Argument]] + [[`T`] [Model of Copy Constructible] [Operation's Argument]] + [[`t`] [Object of type T] [Operation's Argument]] ] [heading Expression Semantics] @@ -156,11 +183,47 @@ the supplied argument [*Semantics]: Calls `expression::value::make(t)`, Automatically deduces type T +[header Header] + #include + +[header Example] + +TODO + [endsect] [section Reference] -References are one of the core building blocks of Phoenix. +Values are immutable constants. Attempting to modify a value will result in a +compile time error. When we want the function to modify the parameter, we use a +reference instead. For instance, imagine a lazy function `add_assign`: + + void add_assign(T& x, T y) { x += y; } // pseudo code + +Here, we want the first function argument, x, to be mutable. Obviously, we +cannot write: + + add_assign(1, 2) // error first argument is immutable + +In C++, we can pass in a reference to a variable as the first argument in our +example above. Yet, by default, the library forces arguments passed to partially +applied functions functions to be immutable values (see [link __phoenix_reference_value__] +). To achieve our intent, we use: + + expression::reference::type + +This is similar to `expression::value::type` before but instead holds a reference to a +variable. + +We normally don't instantiate `expression::reference::type` objects directly. Instead we +use `ref`. For example (where `i` is an `int` variable): + + add_assign(ref(i), 2) + +Another free function `cref(cv)` may also be used. `cref(cv)` creates an +`expression::reference::type` object. This is similar to `expression::value::type` but +when the data to be passed as argument to a function is heavy and expensive to +copy by value, the `cref(cv)` offers a lighter alternative. [heading Synopsis] namespace expression @@ -170,7 +233,7 @@ References are one of the core building blocks of Phoenix. { typedef __unspecified__ type; - static type make(T t); + static type make(T &t); }; } @@ -182,7 +245,9 @@ References are one of the core building blocks of Phoenix. typename expression::reference::type cref(T const & t); -[table Parameters +[heading Parameters] + +[table [[Parameter] [Requirement] [Description]] [[T] [] [Operation's Argument]] [[t] [Object of type T] [Operation's Argument]] @@ -199,8 +264,7 @@ References are one of the core building blocks of Phoenix. [*Return type]: `expression::reference::type` -[*Semantics]: Creates a Phoenix reference expression initialized with a copy of of -the supplied argument +[*Semantics]: Creates a Phoenix reference expression initialized with the supplied argument ref(t); @@ -214,6 +278,13 @@ the supplied argument [*Semantics]: Calls `expression::reference::make(t)`, Automatically deduces type T +[heading Header] + #include + +[heading Example] + +TODO + [endsect] [section Placeholder] diff --git a/include/boost/phoenix/core/argument.hpp b/include/boost/phoenix/core/argument.hpp index 8679af4..29d6cbd 100644 --- a/include/boost/phoenix/core/argument.hpp +++ b/include/boost/phoenix/core/argument.hpp @@ -29,40 +29,59 @@ namespace boost { namespace phoenix // //////////////////////////////////////////////////////////////////////////// - template - struct argument + namespace detail { - typedef I type; - typedef typename I::value_type value_type; - static value_type const value = I::value; - - bool operator==(argument) const + template + struct argument + : mpl::int_ { - return true; - } + bool operator==(argument) const + { + return true; + } - template - bool operator==(argument) const - { - return false; - } - }; + template + bool operator==(argument) const + { + return false; + } + }; + } }} namespace boost { - template - struct is_placeholder > - : I + template + struct is_placeholder > + : mpl::int_ {}; } namespace boost { namespace phoenix { + namespace expression + { + template + struct argument + { + typedef + actor< + typename proto::terminal >::type + > + type; + + static const type make() + { + type const e = {}; + return e; + } + }; + } + #define BOOST_PHOENIX_ARGUMENT_N(_, N, name) \ - actor< \ - proto::terminal > >::type \ - > const BOOST_PP_CAT(name, BOOST_PP_INC(N)) = {}; + expression::argument::type const \ + BOOST_PP_CAT(name, BOOST_PP_INC(N)) = {}; \ + /**/ namespace placeholders { @@ -75,6 +94,8 @@ namespace boost { namespace phoenix BOOST_PP_REPEAT(PHOENIX_ARG_LIMIT, BOOST_PHOENIX_ARGUMENT_N, arg) BOOST_PP_REPEAT(PHOENIX_ARG_LIMIT, BOOST_PHOENIX_ARGUMENT_N, _) } + + #undef BOOST_PHOENIX_ARGUMENT_N }} #endif diff --git a/include/boost/phoenix/core/reference.hpp b/include/boost/phoenix/core/reference.hpp index f292472..a4ad0f3 100644 --- a/include/boost/phoenix/core/reference.hpp +++ b/include/boost/phoenix/core/reference.hpp @@ -22,27 +22,48 @@ namespace boost { namespace phoenix // function for evaluating references, e.g. ref(123) // ///////////////////////////////////////////////////////////////////////////// - template - struct reference - : proto::terminal > + + namespace expression { - typedef actor >::type> type; - }; + template + struct reference + : proto::terminal > + { + typedef actor >::type> type; - template - typename reference::type const - ref(T & t) - { - typename reference::type const e = {{boost::ref(t)}}; - return e; + static const type make(T & t) + { + typename reference::type const e = {{boost::ref(t)}}; + return e; + } + }; + + template + struct reference + : proto::terminal > + { + typedef actor >::type> type; + + static const type make(T const & t) + { + typename reference::type const e = {{boost::cref(t)}}; + return e; + } + }; } template - typename reference::type const + typename expression::reference::type const + ref(T & t) + { + return expression::reference::make(t); + } + + template + typename expression::reference::type const cref(T const & t) { - typename reference::type const e = {{boost::cref(t)}}; - return e; + return expression::reference::make(t); } // Call out boost::reference_wrapper for special handling diff --git a/include/boost/phoenix/core/terminal.hpp b/include/boost/phoenix/core/terminal.hpp index 80c2c00..cc206aa 100644 --- a/include/boost/phoenix/core/terminal.hpp +++ b/include/boost/phoenix/core/terminal.hpp @@ -32,18 +32,8 @@ namespace boost { namespace phoenix struct terminal : proto::terminal {}; - - template - struct expr::case_ - : proto::or_< - proto::when - , proto::when - , proto::when - > - {}; } - /* template struct meta_grammar::case_ : proto::or_< @@ -52,7 +42,6 @@ namespace boost { namespace phoenix , proto::when > {}; - */ template struct default_actions::when diff --git a/include/boost/phoenix/core/value.hpp b/include/boost/phoenix/core/value.hpp index 566a44a..41bf26b 100644 --- a/include/boost/phoenix/core/value.hpp +++ b/include/boost/phoenix/core/value.hpp @@ -30,7 +30,7 @@ namespace boost { namespace phoenix { typedef actor::type> type; - static type make(T t) + static const type make(T t) { typename value::type const e = {{t}}; return e; @@ -43,7 +43,7 @@ namespace boost { namespace phoenix { typedef actor::type> type; - static type make(T t[N]) + static const type make(T t[N]) { typename value::type const e = {{t}}; return e; diff --git a/include/boost/phoenix/scope/local_variable.hpp b/include/boost/phoenix/scope/local_variable.hpp index b7f9f63..3877592 100644 --- a/include/boost/phoenix/scope/local_variable.hpp +++ b/include/boost/phoenix/scope/local_variable.hpp @@ -73,10 +73,10 @@ namespace boost { namespace phoenix typedef typename mpl::eval_if< is_reference - , reference< + , expression::reference< typename boost::remove_reference::type > - , value + , expression::value >::type type; };