From: eric_at_[hidden]
Date: 2008-08-12 16:18:31
Author: eric_niebler
Date: 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
New Revision: 48108
URL: http://svn.boost.org/trac/boost/changeset/48108
Log:
more work on proto's docs
Added:
trunk/libs/proto/doc/references.qbk (contents, props changed)
Text files modified:
trunk/libs/proto/doc/calculator.qbk | 4
trunk/libs/proto/doc/construction.qbk | 57 +++++++++-------
trunk/libs/proto/doc/evaluation.qbk | 2
trunk/libs/proto/doc/extensibility.qbk | 6
trunk/libs/proto/doc/glossary.qbk | 98 +++++++++++++++--------------
trunk/libs/proto/doc/grammars.qbk | 2
trunk/libs/proto/doc/history.qbk | 4 +
trunk/libs/proto/doc/preface.qbk | 79 ++++++++++-------------
trunk/libs/proto/doc/proto.qbk | 2
trunk/libs/proto/doc/quick_start.qbk | 134 ++++++++++++++++++++--------------------
trunk/libs/proto/doc/transforms.qbk | 30 ++++----
11 files changed, 211 insertions(+), 207 deletions(-)
Modified: trunk/libs/proto/doc/calculator.qbk
==============================================================================
--- trunk/libs/proto/doc/calculator.qbk (original)
+++ trunk/libs/proto/doc/calculator.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -30,7 +30,7 @@
struct placeholder
{};
- // Define the Proto-ified placeholder terminals
+ // Define the Protofied placeholder terminals
proto::terminal<placeholder<0> >::type const _1 = {{}};
proto::terminal<placeholder<1> >::type const _2 = {{}};
@@ -178,7 +178,7 @@
All that remains to be done is to put our placeholders in the calculator domain. We
do that by wrapping them in our `calculator<>` wrapper, as below:
- // Define the Proto-ified placeholder terminals, in the
+ // Define the Protofied placeholder terminals, in the
// calculator domain.
calculator<proto::terminal<placeholder<0> >::type> const _1;
calculator<proto::terminal<placeholder<1> >::type> const _2;
Modified: trunk/libs/proto/doc/construction.qbk
==============================================================================
--- trunk/libs/proto/doc/construction.qbk (original)
+++ trunk/libs/proto/doc/construction.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -5,7 +5,7 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
-[def __implelemtation_defined__ [~implementation-defined]]
+[def __unspecified__ [~unspecified]]
[/=======================================================================================]
[section:expression_construction Expression Construction: Building Proto Expression Trees]
@@ -18,14 +18,16 @@
In the calculator example, we defined a placeholder terminal like this:
// Define a placeholder type
- struct placeholder1 {};
+ template<int I>
+ struct placeholder
+ {};
- // Define the Proto-ified placeholder terminal
- proto::terminal< placeholder1 >::type const _1 = {{}};
+ // Define the Protofied placeholder terminal
+ proto::terminal< placeholder<0> >::type const _1 = {{}};
The actual type of `_1` looks like this:
- proto::expr< proto::tag::terminal, proto::term< placeholder1 >, 0 >
+ proto::expr< proto::tag::terminal, proto::term< placeholder<0> >, 0 >
The _expr_ template is the most important type in Proto. Although you will
rarely need to deal with it directly, it's always there behind the scenes
@@ -35,8 +37,8 @@
The _expr_ template makes up the nodes in expression trees. The first template
parameter is the node type; in this case, `proto::tag::terminal`. That means
that `_1` is a leaf-node in the expression tree. The second template parameter
-is a list of child types, or in the case of terminals, the type of the terminal's
-value. Terminals will always have only one type in the type list. The last
+is a list of child types, or in the case of terminals, the terminal's value
+type. Terminals will always have only one type in the type list. The last
parameter is the arity of the expression. Terminals have arity 0, unary
expressions have arity 1, etc.
@@ -58,8 +60,8 @@
['aggregate initialization], with curly braces. In our example, `_1` is
initialized with the initializer `{{}}`. The outer braces is the initializer
for the _expr_ struct, and the inner braces are for the member `_1.child0` which
-is of type `placeholder1`. Note that we use braces to initialize `_1.child0`
-because `placeholder1` is also an aggregate.
+is of type `placeholder<0>`. Note that we use braces to initialize `_1.child0`
+because `placeholder<0>` is also an aggregate.
[/=================================]
[heading Proto's Operator Overloads]
@@ -132,11 +134,11 @@
code works and does what you might expect, but not in the obvious way:
typedef
- proto::terminal< placeholder1 >::type
- placeholder1_type;
+ proto::terminal< placeholder<0> >::type
+ _1_type;
- placeholder1_type const _1 = {{}};
- placeholder1_type const * p = &_1; // OK, &_1 implicitly converted
+ _1_type const _1 = {{}};
+ _1_type const * p = &_1; // OK, &_1 implicitly converted
[/================================]
[heading Building Expression Trees]
@@ -156,7 +158,7 @@
, proto::list1<
proto::expr<
proto::tag::terminal
- , proto::term< placeholder1 >
+ , proto::term< placeholder<0> >
, 0
> const &
>
@@ -173,7 +175,7 @@
, proto::list2<
proto::expr<
proto::tag::terminal
- , proto::term< placeholder1 >
+ , proto::term< placeholder<0> >
, 0
> const &
, proto::expr<
@@ -198,7 +200,7 @@
# Non-Proto expressions, such as the integer literal, are turned into Proto
expressions by making them Proto terminals. These terminal expressions
are thenselves held by reference, but the object itself /is/. Notice that
- the type of the Proto-ified `42` literal is `int const &` -- held by
+ the type of the Protofied `42` literal is `int const &` -- held by
reference.
The types make it clear: everything in a Proto expression tree is held by
@@ -238,7 +240,7 @@
return typename proto::result_of::tag_of<Expr>::type();
}
- proto::terminal<int>::type const i = {0};
+ proto::terminal<int>::type const i = {42};
// Addition nodes have the "plus" tag type:
proto::tag::plus plus_tag = get_tag_of( i + 2 );
@@ -252,7 +254,7 @@
To access them, you can use the _child_c_ function template, as demonstrated
below:
- proto::terminal<int>::type i = {0};
+ proto::terminal<int>::type i = {42};
// Get the 0-th operand of an addition operation:
proto::terminal<int>::type &ri = proto::child_c<0>( i + 2 );
@@ -276,7 +278,7 @@
}
// ...
- terminal<int>::type i = {0};
+ terminal<int>::type i = {42};
test_result_of_child_c( i + 2 );
However, if you ask for the type of the Nth child of `Expr &` or `Expr const &`
@@ -355,7 +357,11 @@
, display()
);
-The above invocation of `fusion::for_each()` displays the following:
+Recall from the Introduction that types in the `proto::functional` namespace
+define function objects that correspond to Proto's free functions. So
+`proto::functional::value()` creates a function object that is equavalent to
+the `proto::value()` function. The above invocation of `fusion::for_each()`
+displays the following:
[pre
1
@@ -397,7 +403,7 @@
fusion::for_each(
fusion::transform(
proto::flatten(_1 + 2 + 3 + 4)
- , functional::child<>()
+ , proto::functional::value()
)
, display()
);
@@ -417,11 +423,10 @@
[section:tags_and_metafunctions Operator Tags and Metafunctions]
[/=============================================================]
-The following table lists the overloadable C++ operators, the Proto tag types
-for each, and the name of the Proto metafunction for generating the
-corresponding Proto expression types. The metafunctions are also usable as
-grammars for matching such nodes, as well as pass-through transforms, as
-explained in later sections.
+The following table lists the overloadable C++ operators, the Proto tag types for
+each, and the name of the metafunctions for generating the corresponding Proto
+expression types. And as we'll see later, the metafunctions are also usable as
+grammars for matching such nodes, as well as pass-through transforms.
[table Operators, Tags and Metafunctions
[[Operator]
Modified: trunk/libs/proto/doc/evaluation.qbk
==============================================================================
--- trunk/libs/proto/doc/evaluation.qbk (original)
+++ trunk/libs/proto/doc/evaluation.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -173,7 +173,7 @@
>
struct eval;
- // Handle placeholder1 terminals here...
+ // Handle placeholder terminals here...
template<typename Expr, int I>
struct eval<Expr, proto::tag::terminal, placeholder<I> >
{
Modified: trunk/libs/proto/doc/extensibility.qbk
==============================================================================
--- trunk/libs/proto/doc/extensibility.qbk (original)
+++ trunk/libs/proto/doc/extensibility.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -107,8 +107,8 @@
Now that we have defined the `calculator<>` expression wrapper, we need to
wrap the placeholders to imbue them with calculator-ness:
- calculator< proto::terminal< placeholder1 >::type > const _1;
- calculator< proto::terminal< placeholder2 >::type > const _2;
+ calculator< proto::terminal< placeholder<0> >::type > const _1;
+ calculator< proto::terminal< placeholder<1> >::type > const _2;
[endsect]
@@ -151,7 +151,7 @@
[section:inhibiting_overloads Controlling Operator Overloads]
[/==========================================================]
-By default, Proto defines every possible operator overload for Proto-ified
+By default, Proto defines every possible operator overload for Protofied
expressions. This makes it simple to bang together a DSEL, and Proto's grammar
building and checking facilities make it simple to detect and report invalid
expressions. In some cases, however, the presence of Proto's promiscuous
Modified: trunk/libs/proto/doc/glossary.qbk
==============================================================================
--- trunk/libs/proto/doc/glossary.qbk (original)
+++ trunk/libs/proto/doc/glossary.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -11,55 +11,59 @@
[def _T_ [~T]]
+[template anchor[x] '''<anchor id="boost_proto.users_guide.glossary.'''[x]'''" />''']
+
[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
+ [ [ [anchor callable_transform] 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.] ]
- [ [domain-specific language]
- [A programming language that targets a particular problem
- space by providing programming idioms, abstractions and
- constructs that match the constructs within that problem
- space.]]
- [ [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
- 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.]]
+ [ [ [anchor dsel] domain-specific embedded language]
+ [A domain-specific language implemented as a library. The langauge in which
+ the library is written is called the "host" langauge, and the language
+ implemented by the library is called the "embedded" language.]]
+ [ [ [anchor dsl] domain-specific language]
+ [A programming language that targets a particular problem space by providing
+ programming idioms, abstractions and constructs that match the constructs
+ within that problem space.]]
+ [ [ [anchor expression] 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.]]
+ [ [ [anchor expression_template] expression template]
+ [A C++ technique using templates and operator overloading to cause
+ expressions to build trees that represent the expression for lazy evaluation
+ later, rather than evaluating the expression eagerly. Some C++ libraries use
+ expression templates to build domain-specific embedded languages.]]
+ [ [ [anchor grammar] grammar]
+ [A grammar is a type that describes a subset of expression types. Expressions
+ in a domain must conform to that domain's grammar. The `proto::matches<>`
+ metafunction evaluates whether an expression type matchesa 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.]]
+ [ [ [anchor object_transform] 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.]]
+ [ [ [anchor polymorphic_function_object] 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.]]
+ [ [ [anchor primitive_transform] 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.]]
+ [ [ [anchor transform] 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: trunk/libs/proto/doc/grammars.qbk
==============================================================================
--- trunk/libs/proto/doc/grammars.qbk (original)
+++ trunk/libs/proto/doc/grammars.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -387,7 +387,7 @@
[pre
group ::= '(' expression ')'
-factor ::= double | placeholder1 | placeholder2 | group
+factor ::= double | '_1' | '_2' | group
term ::= factor (('*' factor) | ('/' factor))*
expression ::= term (('+' term) | ('-' term))*
]
Modified: trunk/libs/proto/doc/history.qbk
==============================================================================
--- trunk/libs/proto/doc/history.qbk (original)
+++ trunk/libs/proto/doc/history.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -9,6 +9,10 @@
[variablelist
[
+ [August 11, 2008]
+ [Proto v4 is merged to Boost trunk with more powerful transform protocol.]
+]
+[
[April 7, 2008]
[Proto is accepted into Boost.]
]
Modified: trunk/libs/proto/doc/preface.qbk
==============================================================================
--- trunk/libs/proto/doc/preface.qbk (original)
+++ trunk/libs/proto/doc/preface.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -7,7 +7,8 @@
[section Preface]
-[:["There are more things in heaven and earth, Horatio, than are dreamt of in your philosophy.]]
+[:["There are more things in heaven and earth, Horatio, than are dreamt of in your
+ philosophy.]]
[:[*['-- William Shakespeare]]]
[heading Description]
@@ -19,11 +20,11 @@
More specifically, Proto provides:
* An expression tree data structure.
+* A mechanism for giving expressions additional behaviors and members.
* Operator overloads for building the tree from an expression.
* Utilities for defining the grammar to which an expression must conform.
* An extensible mechanism for immediately executing an expression template.
* An extensible set of tree transformations to apply to expression trees.
-* A mechanism for giving expressions additional behaviors and members.
[heading Motivation]
@@ -33,63 +34,51 @@
for linear algebra as well as to define C++ parser generators with a readable
syntax. But developing such a library involves writing an inordinate amount of
unreadable and unmaintainable template mumbo-jumbo. Boost.Proto eases the
-development of domain-specific embedded languages (DSELs). Use Proto to define
-the primitives of your mini-language and let Proto handle the operator
-overloading and the construction of the expression parse tree. Immediately
-evaluate the expression tree by passing it a function object. Or transform the
-expression tree by defining the grammar of your mini-language, decorated
-with an assortment of tree transforms provided by Proto or defined by you.
-Then use the grammar to give your users short and readable syntax errors
-for invalid expressions! No more mumbo-jumbo -- an expression template library
-developed with Proto is declarative and readable.
+development of [link boost_proto.users_guide.glossary.dsel domain-specific embedded
+languages (DSELs)]. Use Proto to define the primitives of your mini-language and
+let Proto handle the operator overloading and the construction of the expression
+parse tree. Immediately evaluate the expression tree by passing it a function
+object. Or transform the expression tree by defining the grammar of your mini-
+language, decoratedwith an assortment of tree transforms provided by Proto or
+defined by you. Then use the grammar to give your users short and readable syntax
+errors for invalid expressions! No more mumbo-jumbo -- an expression template
+library developed with Proto is declarative and readable.
In short, Proto is a DSEL for defining DSELs.
-[heading Influences and Related Work]
-
-Proto was initially developed as part of _xpressive_ to simplify the job of
-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. 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
-is similar to Fusion data structures in many respects, and is interoperable
-with Fusion's iterators and algorithms.
-
-The syntax for the grammar-matching features of `proto::matches<>` is inspired
-by MPL's lambda expressions, and by Aleksey Gurtovoy's
-[@http://listarchives.boost.org/Archives/boost/2002/11/39718.php "round" lambda] notation.
-
-[heading Further Reading]
-
-A technical paper about an earlier version of Proto was accepted into the
-[@http://lcsd.cs.tamu.edu/2007/ ACM SIGPLAN Symposium on Library-Centric Software Design LCSD'07],
-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 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 `()`.
+ 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.]
+Finally, you can mentally add the following to any code fragments in this document:
+
+ // Include all of Proto
+ #include <boost/proto/proto.hpp>
+
+ // Create a namespace alias for boost::proto
+ namespace proto = boost::proto;
+
+ // Allow unqualified use of Proto's wildcard pattern
+ using proto::_;
+
[endsect]
Modified: trunk/libs/proto/doc/proto.qbk
==============================================================================
--- trunk/libs/proto/doc/proto.qbk (original)
+++ trunk/libs/proto/doc/proto.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -122,6 +122,8 @@
[include examples.qbk]
+[include references.qbk]
+
[include glossary.qbk]
[endsect]
Modified: trunk/libs/proto/doc/quick_start.qbk
==============================================================================
--- trunk/libs/proto/doc/quick_start.qbk (original)
+++ trunk/libs/proto/doc/quick_start.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -5,6 +5,68 @@
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
+[/================================]
+[section:naming 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]
+
[section Hello World]
Below is a very simple program that uses Proto to build an expression template
@@ -43,15 +105,15 @@
The basic idea of expression templates is to overload all the operators so
that, rather than evaluating the expression immediately, they build a tree-like
representation of the expression so that it can be evaluated later. For each
-operator in an expression, at least one operand must be Proto-ified in order
+operator in an expression, at least one operand must be Protofied in order
for Proto's operator overloads to be found. In the expression ...
cout_ << "hello" << ',' << " world"
-... the Proto-ified sub-expression is `cout_`, which is the Proto-ification of
+... the Protofied sub-expression is `cout_`, which is the Proto-ification of
`std::cout`. The presence of `cout_` "infects" the expression, and brings
Proto's tree-building operator overloads into consideration. Any literals in
-the expression are then Proto-ified by wrapping them in a Proto terminal before
+the expression are then Protofied by wrapping them in a Proto terminal before
they are combined into larger Proto expressions.
Once Proto's operator overloads have built the expression tree, the expression
@@ -62,9 +124,9 @@
context, you could give the operators in your expressions different semantics.
By default, Proto makes no assumptions about what operators actually /mean/.)
-[/=============================]
+[/==============================]
[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
@@ -80,66 +142,4 @@
particular domain. But that is not the default behavior. We'll see later why
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]
Added: trunk/libs/proto/doc/references.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/proto/doc/references.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -0,0 +1,37 @@
+[/
+ / 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:references References and Related Work]
+[/=============================================]
+
+Proto was initially developed as part of _xpressive_ to simplify the job of
+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. 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 is similar to Fusion
+data structures in many respects, and is interoperable with Fusion's iterators and
+algorithms.
+
+The syntax for the grammar-matching features of `proto::matches<>` is inspired by
+MPL's lambda expressions, and by Aleksey Gurtovoy's
+[@http://listarchives.boost.org/Archives/boost/2002/11/39718.php "round" lambda] notation.
+
+[/======================]
+[heading Further Reading]
+[/======================]
+
+A technical paper about an earlier version of Proto was accepted into the
+[@http://lcsd.cs.tamu.edu/2007/ ACM SIGPLAN Symposium on Library-Centric Software
+Design LCSD'07], 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.
+
+[endsect]
Modified: trunk/libs/proto/doc/transforms.qbk
==============================================================================
--- trunk/libs/proto/doc/transforms.qbk (original)
+++ trunk/libs/proto/doc/transforms.qbk 2008-08-12 16:18:30 EDT (Tue, 12 Aug 2008)
@@ -7,16 +7,16 @@
[import ../test/examples.cpp]
-[/==========================================================]
-[section:expression_transformation Expression Transformation]
-[/==========================================================]
-
-Sometimes, rather than immediately executing an expression template, you'd
-like to transform it into some other object. Maybe the transformation is simple,
-like converting all references into values. Maybe it's complicated, like
-transforming an expression template into a finite-state automata for matching a
-regular expression. Proto provides a framework for applying tree
-transformations and several canned transformations that are generally useful.
+[/============================================================================]
+[section:expression_transformation Expression Transformation: Semantic Actions]
+[/============================================================================]
+
+Sometimes, rather than immediately executing an expression template, you'd like to
+transform it into some other object. Maybe the transformation is simple, like
+converting all references into values. Maybe it's complicated, like transforming an
+expression template into a finite-state automata for matching a regular expression.
+Proto provides a framework for applying tree transformations and several canned
+transformations that are generally useful.
[/===============]
[heading Overview]
@@ -209,18 +209,18 @@
the arity of all of the sub-expressions and taking the maximum.
Let's look at the sub-expression for the placeholder `_1`. It is matched by this
-part of our grammar: `proto::terminal< placeholder1 >`. We want to associate this
+part of our grammar: `proto::terminal< placeholder<0> >`. We want to associate this
part of our grammar with an arity of `1`. We do that by attaching a transform.
Since the arity of an expression can be evaluated at compile time, let's use
`mpl::int_<1>` to represent the arity of the first placeholder. The following
attaches a transform that always evaluates to `mpl::int_<1>`:
- proto::when< proto::terminal< placeholder1 >, mpl::int_<1>() >
+ proto::when< proto::terminal< placeholder<0> >, mpl::int_<1>() >
-This grammar rule will match any `placeholder1` terminal, and will transform it
+This grammar rule will match any `placeholder<0>` terminal, and will transform it
to a (default-constructed) `mpl::int_<1>` object. As described previously,
`mpl::int_<1>()` is a function type, but Proto interprets it as an object to
-construct. We will have a similar transform to convert `placeholder2` terminals
+construct. We will have a similar transform to convert `placeholder<1>` terminals
into `mpl::int_<2>`, and other terminals into `mpl::int_<0>`.
Next, let's write a transform for unary operators that returns the arity of the
@@ -273,7 +273,7 @@
which would have the following type:
expr< tag::unary_plus, list1<
- expr< tag::terminal, term< placeholder1 > >
+ expr< tag::terminal, term< placeholder<0> > >
> >
If we executed the `unary_expr< _, CalcArity >` transform on this