users_manual.qbk

来自「Boost provides free peer-reviewed portab」· QBK 代码 · 共 1,963 行 · 第 1/5 页

Lazy functions are your friends. The library provides a facility to make lazy
functions. The code below is a rewrite of the `is_odd` function using the
facility:

    struct is_odd_impl
    {
        template <typename Arg>
        struct result
        {
            typedef bool type;
        };

        template <typename Arg>
        bool operator()(Arg arg1) const
        {
            return arg1 % 2 == 1;
        }
    };

    function<is_odd_impl> is_odd;

[h2 Things to note:]

* `result` is a nested metafunction that reflects the return type of the
  function (in this case, bool). This makes the function fully polymorphic:
  It can work with arbitrary `Arg` types.
* There are as many Args in the `result` metafunction as in the actual
  `operator()`.
* `is_odd_impl` implements the function.
* `is_odd`, an instance of `function<is_odd_impl>`, is the lazy function.

Now, `is_odd` is a truly lazy function that we can use in conjunction with the
rest of phoenix. Example:

    find_if(c.begin(), c.end(), is_odd(arg1));

(See [@../../example/users_manual/function.cpp function.cpp])

[h2 Predefined Lazy Functions]

The library is chock full of STL savvy, predefined lazy functions covering the
whole of the STL containers, iterators and algorithms. For example, there are lazy
versions of container related operations such as assign, at, back, begin,
pop_back, pop_front, push_back, push_front, etc. (See [link phoenix.container
Container]).

[endsect]
[section More]

As mentioned earlier, this chapter is not a thorough discourse of the library.
It is meant only to cover enough ground to get you into high gear as quickly as
possible. Some advanced stuff is not discussed here (e.g. [link phoenix.composite.scope
Scopes]); nor are features that provide alternative (short-hand) ways to do the
same things (e.g. [link phoenix.composite.bind Bind] vs. Lazy Functions).

[blurb __tip__ ...*If you still wish to learn more, the read on...*]

[endsect]
[endsect]

[section Basics]

[def __constant_n__ /n/]
[def __argument_n__ a/n/]

Almost everything is a function in the Phoenix library that can be evaluated as
`f(a1, a2, ..., __argument_n__)`, where __constant_n__ is the function's arity, or number of arguments that the
function expects. Operators are also functions. For example, `a + b` is just a
function with arity == 2 (or binary). `a + b` is the same as `add(a, b)`, `a + b
+ c` is the same as `add(add(a, b), c)`.

[note Amusingly, functions may even return functions. We shall see
what this means in a short while.]

[h2 Partial Function Application]

Think of a function as a black box. You pass arguments and it returns something
back. The figure below depicts the typical scenario.

[$images/fbox.png]

A fully evaluated function is one in which all the arguments are given. All
functions in plain C++ are fully evaluated. When you call the `sin(x)` function,
you have to pass a number x. The function will return a result in return: the
sin of x. When you call the `add(x, y)` function, you have to pass two numbers x
and y. The function will return the sum of the two numbers. The figure below is
a fully evaluated `add` function.

[$images/adder.png]

A partially applied function, on the other hand, is one in which not all the
arguments are supplied. If we are able to partially apply the function `add`
above, we may pass only the first argument. In doing so, the function does not
have all the required information it needs to perform its task to compute and
return a result. What it returns instead is another function, a lambda function
--another black box. Unlike the original `add` function which has an arity of 2,
the resulting lambda function has an arity of 1. Why? because we already
supplied part of the input: `2`

[$images/add2.png]

Now, when we shove in a number into our lambda function, it will return 2 plus
whatever we pass in. The lambda function essentially remembers 1) the original
function, `add`, and 2) the partial input, 2. The figure below illustrates a
case where we pass 3 to our lambda function, which then returns 5:

[$images/add2_call.png]

Obviously, partially applying the `add` function, as we see above, cannot be
done directly in C++ where we are expected to supply all the arguments that a
function expects. That's where the Phoenix library comes in. The library
provides the facilities to do partial function application.

[h2 STL and higher order functions]

So, what's all the fuss? What makes partial function application so useful?
Recall our original example in the [link phoenix.starter_kit previous section]:

    find_if(c.begin(), c.end(), arg1 % 2 == 1)

The expression `arg1 % 2 == 1` evaluates to a lambda function. `arg1` is a placeholder
for an argument to be supplied later. Hence, since there's only one unsupplied argument, the
lambda function has an arity 1. It just so happens that `find_if` supplies the
unsupplied argument as it loops from `c.begin()` to `c.end()`.

[note Higher order functions are functions which can take other
functions as arguments, and may also return functions as results. Higher order
functions are functions that are treated like any other objects and can be used as
arguments and return values from functions.]

[h2 Lazy Evaluation]

In Phoenix, to put it more accurately, function evaluation has two stages:

# Partial application
# Final evaluation

The first stage is handled by a set of generator functions. These are your front
ends (in the client's perspective). These generators create (through partial
function application), higher order functions that can be passed on just like
any other function pointer or function object. The second stage, the actual
function call, can be invoked or executed anytime in the future, or not at all;
hence /"lazy"/.

If we look more closely, the first step involves partial function application:

    arg1 % 2 == 1

The second step is the actual function invocation (done inside the `find_if`
function. These are the back-ends (often, the final invocation is never actually
seen by the client). In our example, the `find_if`, if we take a look inside,
we'll see something like:

    template <class InputIterator, class Predicate>
    InputIterator
    find_if(InputIterator first, InputIterator last, Predicate pred)
    {
        while (first != last && !pred(*first))  // <--- The lambda function is called here
            ++first;                            //      passing in *first
        return first;
    }

Again, typically, we, as clients, see only the first step. However, in this
document and in the examples and tests provided, don't be surprised to see the
first and second steps juxtaposed in order to illustrate the complete semantics
of Phoenix expressions. Examples:

    int x = 1;
    int y = 2;

    cout << (arg1 % 2 == 1)(x) << endl; // prints 1 or true
    cout << (arg1 % 2 == 1)(y) << endl; // prints 0 or false


[h2 Forwarding Function Problem]

Usually, we, as clients, write the call-back functions while libraries (such as
STL) provide the callee (e.g. `find_if`). In case the role is reversed, e.g.
if you have to write an STL algorithm that takes in a predicate, or develop a
GUI library that accepts event handlers, you have to be aware of a little known
problem in C++ called the "__forwarding__".

Look again at the code above:

    (arg1 % 2 == 1)(x)

Notice that, in the second-stage (the final evaluation), we used a variable `x`.
Be aware that the second stage cannot accept non-const temporaries and literal
constants. Hence, this will fail:

    (arg1 % 2 == 1)(123) // Error!

Disallowing non-const rvalues partially solves the "__forwarding__" but
prohibits code like above.

[h2 Polymorphic Functions]

Unless otherwise noted, Phoenix generated functions are fully polymorphic. For
instance, the `add` example above can apply to integers, floating points, user
defined complex numbers or even strings. Example:

    std::string h("Hello");
    char const* w = " World";
    std::string r = add(arg1, arg2)(h, w);

evaluates to `std::string("Hello World")`. The observant reader might notice
that this function call in fact takes in heterogeneous arguments where `arg1` is
of type `std::string` and `arg2` is of type `char const*`. `add` still works
because the C++ standard library allows the expression `a + b` where `a` is a
`std::string` and `b` is a `char const*`.

[endsect]

[section Organization]

Care and attention to detail was given, painstakingly, to the design and
implementation of Phoenix.

The library is organized in four layers:

[$images/organization.png]

The modules are orthogonal, with no cyclic dependencies.
Lower layers do not depend on higher layers. Modules in a layer do not depend on other modules in the same layer.
This means, for example, that Bind can be completely discarded if it is
not required; or one could perhaps take out Operator and Statement and just use Function,
which may be desireable in a pure FP application.

The library has grown from the original Phoenix but still comprises only
header files. There are no object files to link against.

[h2 Core]

The lowest two layers comprise the core.

The `Actor` is the main concept behind the library. Lazy functions are
abstracted as actors. There are only 2
kinds of actors:

# Primitives
# Composites

Primitives provide the basic building blocks of functionality within Phoenix.
Composites are used to combine these primitives together to provide more
powerful functionality.

Composites are composed of zero or more actors. Each actor in a composite can
again be another composite.

[table Modules
    [[Module]           [Description]]
    [[Function]         [Lazy functions support (e.g. `add`)]]
    [[Operator]         [Lazy operators support (e.g. `+`)]]
    [[Statement]        [Lazy statments (e.g. `if_`, `while_`)]]
    [[Object]           [Lazy casts (e.g. `static_cast_`),
                        object creation destruction (e.g.
                        `new_`, `delete_`)]]
    [[Scope]            [Support for scopes, local variables and lambda-lambda]]
    [[Bind]             [Lazy functions from free functions, member functions or member variables.]]
    [[Container]        [Set of predefined "lazy" functions that work on STL
                        containers and sequences (e.g. `push_back`).]]
    [[Algorithm]        [Set of predefined "lazy" versions of the STL algorithms
                        (e.g. `find_if`).]]
]

Each module is defined in a header file with the same name. For example,
the core module is defined in `<boost/spirit/home/phoenix/core.hpp>`.

[table Includes
    [[Module]           [File]]
    [[Core]             [`#include <boost/spirit/home/phoenix/core.hpp>`]]
    [[Function]         [`#include <boost/spirit/home/phoenix/function.hpp>`]]
    [[Operator]         [`#include <boost/spirit/home/phoenix/operator.hpp>`]]
    [[Statement]        [`#include <boost/spirit/home/phoenix/statement.hpp>`]]
    [[Object]           [`#include <boost/spirit/home/phoenix/object.hpp>`]]
    [[Scope]            [`#include <boost/spirit/home/phoenix/scope.hpp>`]]
    [[Bind]             [`#include <boost/spirit/home/phoenix/bind.hpp>`]]
    [[Container]        [`#include <boost/spirit/home/phoenix/container.hpp>`]]
    [[Algorithm]        [`#include <boost/spirit/home/phoenix/algorithm.hpp>`]]
]

[blurb __tip__ Finer grained include files are available per feature; see the
succeeding sections.]

[endsect]

[section Actors]

The `Actor` is the main concept behind the library. Actors are function objects.
An actor can accept 0 to `PHOENIX_LIMIT` arguments.

[note You can set `PHOENIX_LIMIT`, the predefined maximum arity an
actor can take. By default, `PHOENIX_LIMIT` is set to 10.]

Phoenix supplies an `actor` class template whose specializations
model the `Actor` concept.  `actor` has one template parameter, `Eval`,
that supplies the smarts to evaluate the resulting function.

    template <typename Eval>
    struct actor : Eval
    {
        return_type
        operator()() const;

        template <typename T0>
        return_type
        operator()(T0& _0) const;

        template <typename T0, typename T1>
        return_type
        operator()(T0& _0, T1& _1) const;

        //...
    };

The actor class accepts the arguments through a set of function call operators
for 0 to `PHOENIX_LIMIT` arities (Don't worry about the details, for now. Note, for example,
that we skimp over the details regarding `return_type`). The arguments
are then forwarded to the actor's `Eval` for evaluation.

[endsect]

[section Primitives]

Actors are composed to create more complex actors in a tree-like hierarchy. The
primitives are atomic entities that are like the leaves in the tree. Phoenix is
extensible. New primitives can be added anytime. Right out of the box, there are
only a few primitives. This section shall deal with these preset primitives.

[section Arguments]

    #include <boost/spirit/home/phoenix/core/argument.hpp>

We use an instance of:

    actor<argument<N> >

to represent the Nth function argument. The argument placeholder acts as an
imaginary data-bin where a function argument will be placed.

[h2 Predefined Arguments]

There are a few predefined instances of `actor<argument<N> >` named
`arg1`..`argN`, and its __bll__ counterpart `_1`..`_N`. (where N is a predefined
maximum).

Here are some sample preset definitions of `arg1`..`argN`

    actor<argument<0> > const arg1 = argument<0>();
    actor<argument<1> > const arg2 = argument<1>();
    actor<argument<2> > const arg3 = argument<2>();

and its __bll__ `_1`..`_N` style counterparts:

    actor<argument<0> > const _1 = argument<0>();
    actor<argument<1> > const _2 = argument<1>();
    actor<argument<2> > const _3 = argument<2>();

[note You can set `PHOENIX_ARG_LIMIT`, the predefined maximum
placeholder index. By default, `PHOENIX_ARG_LIMIT` is set to `PHOENIX_LIMIT`
(See [link phoenix.actors Actors]).]

[h2 User Defined Arguments]

When appropriate, you can define your own `argument<N>` names. For example:

    actor<argument<0> > x; // note zero based index

`x` may now be used as a parameter to a lazy function:

    add(x, 6)

which is equivalent to:

    add(arg1, 6)

[h2 Evaluating an Argument]

An argument, when evaluated, selects the Nth argument from the those passed
in by the client.

For example:

    char        c = 'A';
    int         i = 123;
    const char* s = "Hello World";

    cout << arg1(c) << endl;        //  Get the 1st argument: c
    cout << arg1(i, s) << endl;     //  Get the 1st argument: i
    cout << arg2(i, s) << endl;     //  Get the 2nd argument: s

will print out: