|
|
Boost-Commit : |
From: eric_at_[hidden]
Date: 2008-08-09 20:22:51
Author: eric_niebler
Date: 2008-08-09 20:22:50 EDT (Sat, 09 Aug 2008)
New Revision: 48051
URL: http://svn.boost.org/trac/boost/changeset/48051
Log:
more work on docs
Added:
branches/proto/v4/libs/proto/doc/glossary.qbk (contents, props changed)
Text files modified:
branches/proto/v4/libs/proto/doc/preface.qbk | 27 +++++++++-
branches/proto/v4/libs/proto/doc/proto.qbk | 2
branches/proto/v4/libs/proto/doc/quick_start.qbk | 68 ++++++++++++++++++++++++++
branches/proto/v4/libs/proto/doc/transforms.qbk | 100 ++++++++++++++++++++-------------------
4 files changed, 144 insertions(+), 53 deletions(-)
Added: branches/proto/v4/libs/proto/doc/glossary.qbk
==============================================================================
--- (empty file)
+++ branches/proto/v4/libs/proto/doc/glossary.qbk 2008-08-09 20:22:50 EDT (Sat, 09 Aug 2008)
@@ -0,0 +1,60 @@
+[/
+ / Copyright (c) 2008 Eric Niebler
+ /
+ / 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 Glossary]
+[/===============]
+
+[def _T_ [~T]]
+
+[variablelist
+ [ [callable transform]
+ [A transform of the form `R(A0,A1,...)` (i.e., a function
+ type) where `proto::is_callable<R>::value` is `true`.
+ `R` is treated as a polymorphic function object and the
+ arguments are treated as transforms that yield the
+ arguments to the function object.] ]
+ [ [expression]
+ [A heterogeneous tree where each node is either an
+ instantiation of `boost::proto::expr<>` or some type
+ that is an extension (via `boost::proto::extends<>`
+ or `BOOST_PROTO_EXTENDS()`) of such an instantiation.]]
+ [ [grammar]
+ [A grammar is a type that describes a subset of all
+ expression types. Expressions in a domain must conform
+ to that domain's grammar. The `proto::matches<>`
+ metafunction evaluates whether an expression type matches
+ a grammar. Grammars are either primitives such as `proto::_`,
+ composites such as `proto::plus<>`, control structures
+ such as `proto::or_<>`, or some type derived from a grammar.]]
+ [ [object transform]
+ [A transform of the form `R(A0,A1,...)` (i.e., a function
+ type) where `proto::is_callable<R>::value` is `false`.
+ `R` is treated as the type of an object to construct and
+ the arguments are treated as transforms that yield the
+ parameters to the constructor.]]
+ [ [polymorphic function object]
+ [An instance of a class type with an overloaded function
+ call operator and an nested `result_type` typedef or
+ `result<>` template for calculating the return type of
+ the function call operator.]]
+ [ [primitive transform]
+ [A type that defines a kind of polymorphic function object
+ that takes three arguments: expression, state, and data.
+ Primitive transforms can be used to compose callable
+ transforms and object transforms.]]
+ [ [transform]
+ [Transforms are used to manipulate expression trees. They
+ come in three flavors: primitive transforms, callable
+ transforms, or object transforms. A transform `_T_` can
+ be made into a ternary polymorphic function object with
+ `proto::when<>`, as in `proto::when<proto::_, _T_>`. Such
+ a function object accepts /expression/, /state/, and /data/
+ parameters, and computes a result from them.]]
+]
+
+[endsect]
Modified: branches/proto/v4/libs/proto/doc/preface.qbk
==============================================================================
--- branches/proto/v4/libs/proto/doc/preface.qbk (original)
+++ branches/proto/v4/libs/proto/doc/preface.qbk 2008-08-09 20:22:50 EDT (Sat, 09 Aug 2008)
@@ -51,9 +51,9 @@
transforming an expression template into an executable finite state machine
capable of matching a regular expression. Since then, Proto has found
application in the redesigned and improved Spirit-2 and the related Karma
-library, currently under development. As a result of these efforts, Proto
-evolved into a generic and abstract grammar and tree transformation
-framework applicable in a wide variety of DSEL scenarios.
+library. As a result of these efforts, Proto evolved into a generic and
+abstract grammar and tree transformation framework applicable in a wide
+variety of DSEL scenarios.
The grammar and tree transformation framework is modelled on Spirit's
grammar and semantic action framework. The expression tree data structure
@@ -71,4 +71,25 @@
and can be found at [@http://lcsd.cs.tamu.edu/2007/final/1/1_Paper.pdf]. The
tree transforms described in that paper differ from what exists today.
+[heading How To Use This Documentation]
+
+This documentation makes use of the following naming and formatting conventions.
+
+* Code is in `fixed with font` and is syntax-highlighted.
+* Replaceable text that you will need to supply is in [~italics].
+* If a name refers to a free function, it is specified like this: `free_function()`;
+ that is, it is in code font and its name is followed by `()` to indicate that
+ it is a free function.
+* If a name refers to a class template, it is specified like this: `class_template<>`;
+ that is, it is in code font and its name is followed by `<>` to indicate that
+ it is a class template.
+* If a name refers to a function-like macro, it is specified like this: `MACRO()`;
+ that is, it is uppercase in code font and its name is followed by `()` to indicate that
+ it is a function-like macro. Object-like macros appear without the trailing `()`.
+* Names that refer to /concepts/ in the generic programming sense are
+ specified in CamelCase.
+
+[note In addition, notes such as this one specify non-essential information that
+provides additional background or rationale.]
+
[endsect]
Modified: branches/proto/v4/libs/proto/doc/proto.qbk
==============================================================================
--- branches/proto/v4/libs/proto/doc/proto.qbk (original)
+++ branches/proto/v4/libs/proto/doc/proto.qbk 2008-08-09 20:22:50 EDT (Sat, 09 Aug 2008)
@@ -122,6 +122,8 @@
[include examples.qbk]
+[include glossary.qbk]
+
[endsect]
[xinclude proto.xml]
Modified: branches/proto/v4/libs/proto/doc/quick_start.qbk
==============================================================================
--- branches/proto/v4/libs/proto/doc/quick_start.qbk (original)
+++ branches/proto/v4/libs/proto/doc/quick_start.qbk 2008-08-09 20:22:50 EDT (Sat, 09 Aug 2008)
@@ -62,7 +62,9 @@
context, you could give the operators in your expressions different semantics.
By default, Proto makes no assumptions about what operators actually /mean/.)
-[note [*Proto Design Philosophy]
+[/=============================]
+[heading Proto Design Philosophy]
+[/=============================]
Before we continue, let's use the above example to illustrate an important
design principle of Proto's. The expression template created in the ['hello
@@ -76,6 +78,68 @@
['not] purely abstract, and that have meaning and behaviors independent of any
context. There is also a way to control which operators are overloaded for your
particular domain. But that is not the default behavior. We'll see later why
-the default is often a good thing.]
+the default is often a good thing.
+
+[/=========================]
+[section Naming Conventions]
+[/=========================]
+
+Proto is a large library and probably quite unlike any library you've used
+before. Proto uses some consistent naming conventions to make it easier to
+navigate, and they're described below.
+
+[/===============]
+[heading Functions]
+[/===============]
+
+All of Proto's functions are defined in the `boost::proto` namespace. For
+example, there is a function called `value()` defined in `boost::proto` that
+accepts a terminal expression and returns the terminal's value.
+
+[/===================]
+[heading Metafunctions]
+[/===================]
+
+Proto defines /metafunctions/ that correspond to each of Proto's free functions.
+The metafunctions are used to compute the functions' return types. All of
+Proto's metafunctions live in the `boost::proto::result_of` namespace and
+have the same name as the functions to which they correspond. For instance,
+there is a class template `boost::proto::result_of::value<>` that you can
+use to compute the return type of the `boost::proto::value()` function.
+
+[/======================]
+[heading Function Objects]
+[/======================]
+
+Proto defines /function object/ equivalents of all of its free functions. (A
+function object is an instance of a class type that defines an `operator()`
+member function.) All of Proto's function object types are defined in the
+`boost::proto::functional` namespace and have the same name as their
+corresponding free functions. For example, `boost::proto::functional::value`
+is a class that defines a function object that does the same thing as the
+`boost::proto::value()` free function.
+
+[/==========================]
+[heading Primitive Transforms]
+[/==========================]
+
+Proto also defines /primitive transforms/ -- class types that can be used
+to compose larger transforms for manipulating expression trees. Many of
+Proto's free functions have corresponding primitive transforms. These live
+in the `boost::proto` namespace and their names have a leading underscore.
+For instance, the transform corresponding to the `value()` function is
+called `boost::proto::_value`.
+
+The following table summarizes the discussion above:
+
+[table Proto Naming Conventions
+ [[Entity] [Example] ]
+ [[Free Function] [`boost::proto::value()`] ]
+ [[Metafunction] [`boost::proto::result_of::value<>`] ]
+ [[Function Object] [`boost::proto::functional::value`] ]
+ [[Transform] [`boost::proto::_value`] ]
+]
+
+[endsect]
[endsect]
Modified: branches/proto/v4/libs/proto/doc/transforms.qbk
==============================================================================
--- branches/proto/v4/libs/proto/doc/transforms.qbk (original)
+++ branches/proto/v4/libs/proto/doc/transforms.qbk 2008-08-09 20:22:50 EDT (Sat, 09 Aug 2008)
@@ -29,8 +29,11 @@
is the tree transformation.
You associate transforms with your grammar rules using _when_. For instance,
-you might want to promote all `int` terminals to `long`. You would say
-`proto::when< proto::terminal<int>, proto::terminal<long>::type(proto::_value) >`. Here,
+you might want to promote all `int` terminals to `long`. You would say the
+following:
+
+ proto::when< proto::terminal<int>, proto::terminal<long>::type(proto::_value) >
+
`proto::terminal<long>::type(proto::_value)` is an example of a Proto transform. It says to
create an object of type `proto::terminal<long>::type` and initialize it with the
result of the `proto::_value` transform. `proto::_value` is a transform defined by Proto which
@@ -38,25 +41,25 @@
[note The transform above might look a little strange at first. It appears
to be constructing a temporary object in place. In fact, it is a
-/function type/. Since `proto::terminal<long>::type` and `proto::_value` are /types/,
-`proto::terminal<long>::type(proto::_value)` is actually the type of a function that takes
-`proto::_value` as a parameter and returns `proto::terminal<long>::type`. But no such
-function actually exists! Rather, Proto interprets this function
-type as a transform, the effect of which is described above. The resemblance
-to an in-place construction of a temporary object is intentional. It is a
-concise and natural notation for specifying transforms. Proto transforms use
-function types extensively, as we'll see.]
+/function type/. Since `proto::terminal<long>::type` and `proto::_value`
+are types, `proto::terminal<long>::type(proto::_value)` is actually the type
+of a function that takes `proto::_value` as a parameter and returns
+`proto::terminal<long>::type`. But no such function actually exists! Rather,
+Proto interprets this function type as a transform, the effect of which is
+described above. The resemblance to an in-place construction of a temporary
+object is intentional. It is a concise and natural notation for specifying
+transforms. Proto transforms use function types extensively, as we'll see.]
A grammar decorated with transforms is a function object that takes three
parameters:
* `expr` -- the Proto expression to transform
-* `state` -- an optional initial state of the transformation
+* `state` -- an optional initial state for the transformation
* `data` -- any optional mutable state information
Many transforms do no use the state and data parameters, and you can pass
-dummy values for them or leave them off entirely. Later on we'll see where
-they are useful.
+dummy values for them or leave them off entirely. Later on we'll describe
+the difference between them and see where they are useful.
In addition to being a function object, a grammar decorated with transforms
is also a grammar. That is, it can be used as the second parameter to
@@ -91,7 +94,7 @@
transform typically looks like this:
// Assuming we have an expression to transform,
- // an initial state, and a data ...
+ // an initial state, and some auxiliary data ...
Expr expr;
State state;
Data data;
@@ -1258,41 +1261,42 @@
[/======================================================]
In previous sections, we've seen how to compose larger transforms
-out of smaller transforms using function types.
-We've also seen the primitive transforms that Proto provides.
-So-called primitive transforms can be used without specifying
-arguments, like `_child0` which returns the first child of the
-current node. In this section we'll see how to author your own
-primitive transforms.
-
-There are a few reasons why you might want to write your own
-primitive transforms. For instance, your transform may be complicated and
-composing it out of primitives becomes unwieldy. You might also need
+out of smaller transforms using function types. The smaller transforms
+from which larger transforms are composed are /primitive transforms/,
+and Proto provides a bunch of common ones such as `_child0` and `_value`.
+In this section we'll see how to author your own primitive transforms.
+
+[note There are a few reasons why you might want to write your own
+primitive transforms. For instance, your transform may be complicated,
+and composing it out of primitives becomes unwieldy. You might also need
to work around compiler bugs on legacy compilers that makes
composing transforms using function types problematic. Finally,
you might also decide to define your own primitive transforms
to improve compile times. Since Proto can simply invoke a
primitive transform directly without having to process arguments
or differentiate callable transforms from object transforms,
-primitive transforms are more efficient.
+primitive transforms are more efficient.]
+
+[def _N_ [~N]]
-Your primitive transforms will inherit from `proto::transform<>`
+Primitive transforms inherit from `proto::transform<>`
and have a nested `impl<>` template that inherits from
-`proto::transform_impl<>`. For example, is how Proto defines
-the `_child_c<>` transform:
+`proto::transform_impl<>`. For example, this is how Proto
+defines the `_child_c<_N_>` transform, which returns the
+_N_-th child of the current expression:
namespace boost { namespace proto
{
- // A PrimitiveTransform that returns I-th child of the current
- // expression.
- template<int I>
- struct _child_c : transform<_child_c<I> >
+ // A primitive transform that returns N-th child
+ // of the current expression.
+ template<int N>
+ struct _child_c : transform<_child_c<N> >
{
template<typename Expr, typename State, typename Data>
struct impl : transform_impl<Expr, State, Data>
{
typedef
- typename result_of::child_c<Expr, I>::type
+ typename result_of::child_c<Expr, N>::type
result_type;
result_type operator ()(
@@ -1301,31 +1305,31 @@
, typename impl::data_param data
) const
{
- return proto::child_c<I>(expr);
+ return proto::child_c<N>(expr);
}
};
};
- // Note that _child_c<I> is callable, so that
+ // Note that _child_c<N> is callable, so that
// it can be used with arguments, as:
// _child_c<0>(_child_c<1>)
- template<int I>
- struct is_callable<_child_c<I> >
+ template<int N>
+ struct is_callable<_child_c<N> >
: mpl::true_
{};
}}
The `proto::transform<>` base class provides the `operator()` overloads
and the nested `result<>` template that make your transform a valid
-TR1-style function object that works with `boost::result_of<>`. These
-are all implemented in terms of the nested `impl<>` template you define.
+function object. These are implemented in terms of the nested `impl<>`
+template you define.
-The `proto::transform_impl<>` base class is merely a convenience. It
+The `proto::transform_impl<>` base class is a convenience. It
provides some nested typedefs that are generally useful. The are
specified in the table below:
[table proto::transform_impl<Expr, State, Data> typedefs
-[[typedef][Equivalen To]]
+[[typedef][Equivalent To]]
[[`expr`][`typename remove_reference<Expr>::type`]]
[[`state`][`typename remove_reference<State>::type`]]
[[`data`][`typename remove_reference<Data>::type`]]
@@ -1336,12 +1340,12 @@
You'll notice that `_child_c::impl::operator()` takes arguments of types
`expr_param`, `state_param`, and `data_param`. The typedefs make it easy to
-accepts arguments by reference or const reference accordingly.
+accept arguments by reference or const reference accordingly.
The only other interesting bit is the `is_callable<>` specialization, which
-will be described in the section called
+will be described in the
[link boost_proto.users_guide.expression_transformation.is_callable
-"Making Your Transform Callable"].
+next section].
[endsect]
@@ -1359,7 +1363,7 @@
The first thing to know is that templates are not considered callable
by default. This is true ['even if the template inherits from
-`proto::callable`]. Consider the following erroneous transform:
+`proto::callable`]. Consider the following erroneous callable transform:
// Proto can't tell this defines a
// callable transform!
@@ -1387,10 +1391,10 @@
[note Why can't Proto tell that `times2<int>` is callable? After all,
it inherits from `proto::callable`, and that is detectable, right?
-In fact, determining whether some type `X<Y>` inherits from
+The problem is that merely asking whether some type `X<Y>` inherits from
`callable` will cause the template `X<Y>` to be instantiated. That's a
problem for a type like `std::vector<_value(_child1)>()`, which is a valid
-transform that default-constructs a particular instantiation of
+(object) transform that default-constructs a particular instantiation of
`std::vector<>`. But `std::vector<>` will not suffer to be instantiated
with `_value(_child1)` as a template parameter! As a result, Proto has
to assume that a type `X<Y>` represents an object transform and not
@@ -1449,7 +1453,7 @@
to `proto::callable`:
// Proto will recognize this as callable
- template<typename T, typename Dummy = callable>
+ template<typename T, typename Dummy = proto::callable>
struct times2 : callable
{
typedef T result_type;
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk