users_manual.qbk

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

        if_(arg1 % 2 == 1)
        [
            cout << arg1 << ' '
        ]
    );

Huh? Is that valid C++? Read on...

Yes, it is valid C++. The sample code above is as close as you can get to the
syntax of C++. This stylized C++ syntax differs from actual C++ code. First, the
`if` has a trailing underscore. Second, the block uses square brackets instead
of the familiar curly braces {}.

[note *C++ in C++?*

    In as much as __spirit__ attempts to mimic EBNF in C++,
    Phoenix attempts to mimic C++ in C++!!!
]

Here are more examples with annotations. The code almost speaks for itself.

[section Block Statement]

    #include <boost/spirit/home/phoenix/statement/sequence.hpp>

Syntax:

    statement,
    statement,
    ....
    statement

Basically, these are comma separated statements. Take note that unlike the C/C++
semicolon, the comma is a separator put *in-between* statements. This is like
Pascal's semicolon separator, rather than C/C++'s semicolon terminator. For
example:

    statement,
    statement,
    statement, // ERROR!

Is an error. The last statement should not have a comma. Block statements can be
grouped using the parentheses. Again, the last statement in a group should not
have a trailing comma.

    statement,
    statement,
    (
        statement,
        statement
    ),
    statement

Outside the square brackets, block statements should be grouped. For example:

    for_each(c.begin(), c.end(),
        (
            do_this(arg1),
            do_that(arg1)
        )
    );

Wrapping a comma operator chain around a parentheses pair blocks the
interpretation as an argument separator.  The reason for the exception for
the square bracket operator is that the operator always takes exactly one
argument, so it "transforms" any attempt at multiple arguments with a comma
operator chain (and spits out an error for zero arguments).

[endsect]
[section if_ Statement]

    #include <boost/spirit/home/phoenix/statement/if.hpp>

We have seen the `if_` statement. The syntax is:

    if_(conditional_expression)
    [
        sequenced_statements
    ]

[endsect]
[section if_else_ statement]

    #include <boost/spirit/home/phoenix/statement/if.hpp>

The syntax is

    if_(conditional_expression)
    [
        sequenced_statements
    ]
    .else_
    [
        sequenced_statements
    ]

Take note that `else` has a leading dot and a trailing underscore: `.else_`

Example: This code prints out all the elements and appends `" > 5"`, `" == 5"`
or `" < 5"` depending on the element's actual value:

    for_each(c.begin(), c.end(),
        if_(arg1 > 5)
        [
            cout << arg1 << " > 5\n"
        ]
        .else_
        [
            if_(arg1 == 5)
            [
                cout << arg1 << " == 5\n"
            ]
            .else_
            [
                cout << arg1 << " < 5\n"
            ]
        ]
    );

Notice how the `if_else_` statement is nested.

[endsect]
[section switch_ statement]

    #include <boost/spirit/home/phoenix/statement/switch.hpp>

The syntax is:

    switch_(integral_expression)
    [
        case_<integral_value>(sequenced_statements),
        ...
        default_<integral_value>(sequenced_statements)
    ]

A comma separated list of cases, and an optional default can be provided. Note unlike
a normal switch statement, cases do not fall through.

Example: This code prints out `"one"`, `"two"` or `"other value"` depending on the
element's actual value:

    for_each(c.begin(), c.end(),
        switch_(arg1)
        [
            case_<1>(cout << val("one") << '\n'),
            case_<2>(cout << val("two") << '\n'),
            default_(cout << val("other value") << '\n')
        ]
    );

[endsect]
[section while_ Statement]

    #include <boost/spirit/home/phoenix/statement/while.hpp>

The syntax is:

    while_(conditional_expression)
    [
        sequenced_statements
    ]

Example: This code decrements each element until it reaches zero and prints out
the number at each step. A newline terminates the printout of each value.

    for_each(c.begin(), c.end(),
        (
            while_(arg1--)
            [
                cout << arg1 << ", "
            ],
            cout << val("\n")
        )
    );

[endsect]
[section do_while_ Statement]

    #include <boost/spirit/home/phoenix/statement/do_while.hpp>

The syntax is:

    do_
    [
        sequenced_statements
    ]
    .while_(conditional_expression)

Again, take note that `while` has a leading dot and a trailing underscore:
`.while_`

Example: This code is almost the same as the previous example above with a
slight twist in logic.

    for_each(c.begin(), c.end(),
        (
            do_
            [
                cout << arg1 << ", "
            ]
            .while_(arg1--),
            cout << val("\n")
        )
    );

[endsect]
[section for_ Statement]

    #include <boost/spirit/home/phoenix/statement/for.hpp>

The syntax is:

    for_(init_statement, conditional_expression, step_statement)
    [
        sequenced_statements
    ]

It is again very similar to the C++ for statement. Take note that the
init_statement, conditional_expression and step_statement are separated by the
comma instead of the semi-colon and each must be present (i.e. `for_(,,)` is
invalid). This is a case where the [link phoenix.primitives.nothing nothing]
actor can be useful.

Example: This code prints each element N times where N is the element's value. A
newline terminates the printout of each value.

    int iii;
    for_each(c.begin(), c.end(),
        (
            for_(ref(iii) = 0, ref(iii) < arg1, ++ref(iii))
            [
                cout << arg1 << ", "
            ],
            cout << val("\n")
        )
    );

As before, all these are lazily evaluated. The result of such statements are in
fact composites that are passed on to STL's for_each function. In the viewpoint
of `for_each`, what was passed is just a functor, no more, no less.

[note Unlike lazy functions and lazy operators, lazy statements always
return void.]

[endsect]
[section try_ catch_ Statement]

    #include <boost/spirit/home/phoenix/statement/try_catch.hpp>

The syntax is:

    try_
    [
        sequenced_statements
    ]
    .catch_<exception_type>()
    [
        sequenced_statements
    ]
    ...
    .catch_all
    [
        sequenced_statement
    ]

Note the usual underscore after try and catch, and the extra parentheses required
after the catch.

Example: The following code calls the (lazy) function `f` for each element, and
prints messages about different exception types it catches.

    try_
    [
        f(arg1)
    ]
    .catch_<runtime_error>()
    [
        cout << val("caught runtime error or derived\n")
    ]
    .catch_<exception>()
    [
        cout << val("caught exception or derived\n")
    ]
    .catch_all
    [
        cout << val("caught some other type of exception\n")
    ]

[endsect]
[section throw_]

    #include <boost/spirit/home/phoenix/statement/throw.hpp>

As a natural companion to the try/catch support, the statement module provides
lazy throwing and rethrowing of exceptions.

The syntax to throw an exception is:

    throw_(exception_expression)

The syntax to rethrow an exception is:

    throw_()

Example: This code extends the try/catch example, rethrowing exceptions derived from
runtime_error or exception, and translating other exception types to runtime_errors.

    try_
    [
        f(arg1)
    ]
    .catch_<runtime_error>()
    [
        cout << val("caught runtime error or derived\n"),
        throw_()
    ]
    .catch_<exception>()
    [
        cout << val("caught exception or derived\n"),
        throw_()
    ]
    .catch_all
    [
        cout << val("caught some other type of exception\n"),
        throw_(runtime_error("translated exception"))
    ]

[endsect]
[endsect]

[section Object]

The Object module deals with object construction, destruction and conversion.
The module provides /"lazy"/ versions of C++'s object constructor, `new`,
`delete`, `static_cast`, `dynamic_cast`, `const_cast` and `reinterpret_cast`.

[h2 Construction]

[*/Lazy constructors.../]

    #include <boost/spirit/home/phoenix/object/construct.hpp>

Lazily construct an object from an arbitrary set of arguments:

    construct<T>(ctor_arg1, ctor_arg2, ..., ctor_argN);

where the given parameters are the parameters to the contructor of the object of
type T (This implies, that type T is expected to have a constructor with a
corresponding set of parameter types.).

Example:

    construct<std::string>(arg1, arg2)

Constructs a `std::string` from `arg1` and `arg2`.

[note The maximum number of actual parameters is limited by the
preprocessor constant PHOENIX_COMPOSITE_LIMIT. Note though, that this limit
should not be greater than PHOENIX_LIMIT. By default, `PHOENIX_COMPOSITE_LIMIT`
is set to `PHOENIX_LIMIT` (See [link phoenix.actors Actors]).]

[h2 New]

[*/Lazy new.../]

    #include <boost/spirit/home/phoenix/object/new.hpp>

Lazily construct an object, on the heap, from an arbitrary set of arguments:

    new_<T>(ctor_arg1, ctor_arg2, ..., ctor_argN);

where the given parameters are the parameters to the contructor of the object of
type T (This implies, that type T is expected to have a constructor with a
corresponding set of parameter types.).

Example:

    new_<std::string>(arg1, arg2) // note the spelling of new_ (with trailing underscore)

Creates a `std::string` from `arg1` and `arg2` on the heap.

[note Again, the maximum number of actual parameters is limited by the
preprocessor constant PHOENIX_COMPOSITE_LIMIT. See the note above.]

[h2 Delete]

[*/Lazy delete.../]

    #include <boost/spirit/home/phoenix/object/delete.hpp>

Lazily delete an object, from the heap:

    delete_(arg);