![]() |
Home | Libraries | People | FAQ | More |
"Hello, world" is nice, but it doesn't get you very far. Let's
use Proto to build a EDSL (embedded domain-specific language) for a lazily-evaluated
calculator. We'll see how to define the terminals in your mini-language,
how to compose them into larger expressions, and how to define an evaluation
context so that your expressions can do useful work. When we're done, we'll
have a mini-language that will allow us to declare a lazily-evaluated arithmetic
expression, such as (_2
- _1) / _2
* 100
,
where _1
and _2
are placeholders for values to be
passed in when the expression is evaluated.
The first order of business is to define the placeholders _1
and _2
.
For that, we'll use the proto::terminal<>
metafunction.
// Define a placeholder type template<int I> struct placeholder {}; // Define the Protofied placeholder terminals proto::terminal<placeholder<0> >::type const _1 = {{}}; proto::terminal<placeholder<1> >::type const _2 = {{}};
The initialization may look a little odd at first, but there is a good
reason for doing things this way. The objects _1
and _2
above do not require
run-time construction -- they are statically initialized,
which means they are essentially initialized at compile time. See the
Static
Initialization section in the Rationale
appendix for more information.
Now that we have terminals, we can use Proto's operator overloads to combine these terminals into larger expressions. So, for instance, we can immediately say things like:
// This builds an expression template (_2 - _1) / _2 * 100;
This creates an expression tree with a node for each operator. The type of the resulting object is large and complex, but we are not terribly interested in it right now.
So far, the object is just a tree representing the expression. It has no behavior. In particular, it is not yet a calculator. Below we'll see how to make it a calculator by defining an evaluation context.
No doubt you want your expression templates to actually do something. One approach is to define an evaluation context. The context is like a function object that associates behaviors with the node types in your expression tree. The following example should make it clear. It is explained below.
struct calculator_context : proto::callable_context< calculator_context const > { // Values to replace the placeholders std::vector<double> args; // Define the result type of the calculator. // (This makes the calculator_context "callable".) typedef double result_type; // Handle the placeholders: template<int I> double operator()(proto::tag::terminal, placeholder<I>) const { return this->args[I]; } };
In calculator_context
,
we specify how Proto should evaluate the placeholder terminals by defining
the appropriate overloads of the function call operator. For any other
nodes in the expression tree (e.g., arithmetic operations or non-placeholder
terminals), Proto will evaluate the expression in the "default"
way. For example, a binary plus node is evaluated by first evaluating the
left and right operands and adding the results. Proto's default evaluator
uses the Boost.Typeof
library to compute return types.
Now that we have an evaluation context for our calculator, we can use it to evaluate our arithmetic expressions, as below:
calculator_context ctx; ctx.args.push_back(45); // the value of _1 is 45 ctx.args.push_back(50); // the value of _2 is 50 // Create an arithmetic expression and immediately evaluate it double d = proto::eval( (_2 - _1) / _2 * 100, ctx ); // This prints "10" std::cout << d << std::endl;
Later, we'll see how to define more interesting evaluation contexts and expression transforms that give you total control over how your expressions are evaluated.
Our calculator EDSL is already pretty useful, and for many EDSL scenarios,
no more would be needed. But let's keep going. Imagine how much nicer it
would be if all calculator expressions overloaded operator()
so that they could be used as function
objects. We can do that by creating a calculator domain
and telling Proto that all expressions in the calculator domain have extra
members. Here is how to define a calculator domain:
// Forward-declare an expression wrapper template<typename Expr> struct calculator; // Define a calculator domain. Expression within // the calculator domain will be wrapped in the // calculator<> expression wrapper. struct calculator_domain : proto::domain< proto::generator<calculator> > {};
The calculator<>
type will be an expression wrapper. It will behave just like the expression
that it wraps, but it will have extra member functions that we will define.
The calculator_domain
is
what informs Proto about our wrapper. It is used below in the definition
of calculator<>
.
Read on for a description.
// Define a calculator expression wrapper. It behaves just like // the expression it wraps, but with an extra operator() member // function that evaluates the expression. template<typename Expr> struct calculator : proto::extends<Expr, calculator<Expr>, calculator_domain> { typedef proto::extends<Expr, calculator<Expr>, calculator_domain> base_type; calculator(Expr const &expr = Expr()) : base_type(expr) {} typedef double result_type; // Overload operator() to invoke proto::eval() with // our calculator_context. double operator()(double a1 = 0, double a2 = 0) const { calculator_context ctx; ctx.args.push_back(a1); ctx.args.push_back(a2); return proto::eval(*this, ctx); } };
The calculator<>
struct is an expression extension. It uses proto::extends<>
to effectively add additional members to an expression type. When composing
larger expressions from smaller ones, Proto notes what domain the smaller
expressions are in. The larger expression is in the same domain and is
automatically wrapped in the domain's extension wrapper.
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 Protofied placeholder terminals, in the // calculator domain. calculator<proto::terminal<placeholder<0> >::type> const _1; calculator<proto::terminal<placeholder<1> >::type> const _2;
Any larger expression that contain these placeholders will automatically
be wrapped in the calculator<>
wrapper and have our operator()
overload. That means we can use them as function objects as follows.
double result = ((_2 - _1) / _2 * 100)(45.0, 50.0); assert(result == (50.0 - 45.0) / 50.0 * 100));
Since calculator expressions are now valid function objects, we can use them with standard algorithms, as shown below:
double a1[4] = { 56, 84, 37, 69 }; double a2[4] = { 65, 120, 60, 70 }; double a3[4] = { 0 }; // Use std::transform() and a calculator expression // to calculate percentages given two input sequences: std::transform(a1, a1+4, a2, a3, (_2 - _1) / _2 * 100);
Now, let's use the calculator example to explore some other useful features of Proto.
You may have noticed that you didn't have to define an overloaded operator-()
or operator/()
-- Proto defined them for you. In fact, Proto overloads all
the operators for you, even though they may not mean anything in your domain-specific
language. That means it may be possible to create expressions that are
invalid in your domain. You can detect invalid expressions with Proto by
defining the grammar of your domain-specific language.
For simplicity, assume that our calculator EDSL should only allow addition, subtraction, multiplication and division. Any expression involving any other operator is invalid. Using Proto, we can state this requirement by defining the grammar of the calculator EDSL. It looks as follows:
// Define the grammar of calculator expressions struct calculator_grammar : proto::or_< proto::plus< calculator_grammar, calculator_grammar > , proto::minus< calculator_grammar, calculator_grammar > , proto::multiplies< calculator_grammar, calculator_grammar > , proto::divides< calculator_grammar, calculator_grammar > , proto::terminal< proto::_ > > {};
You can read the above grammar as follows: an expression tree conforms
to the calculator grammar if it is a binary plus, minus, multiplies or
divides node, where both child nodes also conform to the calculator grammar;
or if it is a terminal. In a Proto grammar, proto::_
is a wildcard that matches
any type, so proto::terminal<
proto::_ >
matches any terminal, whether it is a placeholder or a literal.
![]() |
Note |
---|---|
This grammar is actually a little looser than we would like. Only placeholders and literals that are convertible to doubles are valid terminals. Later on we'll see how to express things like that in Proto grammars. |
Once you have defined the grammar of your EDSL, you can use the proto::matches<>
metafunction to check
whether a given expression type conforms to the grammar. For instance,
we might add the following to our calculator::operator()
overload:
template<typename Expr> struct calculator : proto::extends< /* ... as before ... */ > { /* ... */ double operator()(double a1 = 0, double a2 = 0) const { // Check here that the expression we are about to // evaluate actually conforms to the calculator grammar. BOOST_MPL_ASSERT((proto::matches<Expr, calculator_grammar>)); /* ... */ } };
The addition of the BOOST_MPL_ASSERT()
line enforces at compile time that we
only evaluate expressions that conform to the calculator EDSL's grammar.
With Proto grammars, proto::matches<>
and BOOST_MPL_ASSERT()
it is very easy to give the users of
your EDSL short and readable compile-time errors when they accidentally
misuse your EDSL.
![]() |
Note |
---|---|
|
Grammars and proto::matches<>
make it possible to detect when a user has created an invalid expression
and issue a compile-time error. But what if you want to prevent users from
creating invalid expressions in the first place? By using grammars and
domains together, you can disable any of Proto's operator overloads that
would create an invalid expression. It is as simple as specifying the EDSL's
grammar when you define the domain, as shown below:
// Define a calculator domain. Expression within // the calculator domain will be wrapped in the // calculator<> expression wrapper. // NEW: Any operator overloads that would create an // expression that does not conform to the // calculator grammar is automatically disabled. struct calculator_domain : proto::domain< proto::generator<calculator>, calculator_grammar > {};
The only thing we changed is we added calculator_grammar
as the second template parameter to the proto::domain<>
template when defining calculator_domain
. With this simple addition,
we disable any of Proto's operator overloads that would create an invalid
calculator expression.
Hopefully, this gives you an idea of what sorts of things Proto can do for you. But this only scratches the surface. The rest of this users' guide will describe all these features and others in more detail.
Happy metaprogramming!