boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Users' Guide</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../proto.html" title="Chapter 23. Boost.Proto"> <link rel="prev" href="../proto.html" title="Chapter 23. Boost.Proto"> <link rel="next" href="reference.html" title="Reference"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="../proto.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../proto.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="proto.users_guide"></a><a class="link" href="users_guide.html" title="Users' Guide">Users' Guide</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="users_guide.html#boost_proto.users_guide.getting_started">Getting Started</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.front_end">Fronts Ends: Defining Terminals and Non-Terminals of Your EDSL</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.intermediate_form">Intermediate Form: Understanding and Introspecting Expressions</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.back_end">Back Ends: Making Expression Templates Do Useful Work</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.examples">Examples</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.resources">Background and Resources</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.glossary">Glossary</a></dt> </dl></div> <h4> <a name="proto.users_guide.h0"></a> <a name="proto.users_guide.compilers__compiler_construction_toolkits__and_proto"></a><a class="link" href="users_guide.html#proto.users_guide.compilers__compiler_construction_toolkits__and_proto">Compilers, Compiler Construction Toolkits, and Proto</a> </h4> Most compilers have front ends and back ends. The front end parses the text of an input program into some intermediate form like an abstract syntax tree, and the back end takes the intermediate form and generates an executable from it. A library built with Proto is essentially a compiler for an embedded domain-specific language (EDSL). It also has a front end, an intermediate form, and a back end. The front end is comprised of the symbols (a.k.a., terminals), members, operators and functions that make up the user-visible aspects of the EDSL. The back end is made of evaluation contexts and transforms that give meaning and behavior to the expression templates generated by the front end. In between is the intermediate form: the expression template itself, which is an abstract syntax tree in a very real sense. To build a library with Proto, you will first decide what your interface will be; that is, you'll design a programming language for your domain and build the front end with tools provided by Proto. Then you'll design the back end by writing evaluation contexts and/or transforms that accept expression templates and do interesting things with them. This users' guide is organized as follows. After a <a class="link" href="users_guide.html#boost_proto.users_guide.getting_started" title="Getting Started">Getting Started guide</a>, we'll cover the tools Proto provides for defining and manipulating the three major parts of a compiler: <div class="variablelist"> <dl class="variablelist"> <dt><a class="link" href="users_guide.html#boost_proto.users_guide.front_end" title="Fronts Ends: Defining Terminals and Non-Terminals of Your EDSL">Front Ends</a></dt> <dd> How to define the aspects of your EDSL with which your users will interact directly. </dd> <dt><a class="link" href="users_guide.html#boost_proto.users_guide.intermediate_form" title="Intermediate Form: Understanding and Introspecting Expressions">Intermediate Form</a></dt> <dd> What Proto expression templates look like, how to discover their structure and access their constituents. </dd> <dt><a class="link" href="users_guide.html#boost_proto.users_guide.back_end" title="Back Ends: Making Expression Templates Do Useful Work">Back Ends</a></dt> <dd> How to define evaluation contexts and transforms that make expression templates do interesting things. </dd> </dl> </div> After that, you may be interested in seeing some <a class="link" href="users_guide.html#boost_proto.users_guide.examples" title="Examples">Examples</a> to get a better idea of how the pieces all fit together. <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="boost_proto.users_guide.getting_started"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started" title="Getting Started">Getting Started</a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="users_guide.html#boost_proto.users_guide.getting_started.installing_proto">Installing Proto</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.getting_started.naming">Naming Conventions</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.getting_started.hello_world">Hello World</a></dt> <dt><a href="users_guide.html#boost_proto.users_guide.getting_started.hello_calculator">Hello Calculator</a></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="boost_proto.users_guide.getting_started.installing_proto"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.installing_proto" title="Installing Proto">Installing Proto</a> </h4></div></div></div> <h6> <a name="boost_proto.users_guide.getting_started.installing_proto.h0"></a> <a name="boost_proto.users_guide.getting_started.installing_proto.getting_proto"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.installing_proto.getting_proto">Getting Proto</a> </h6> You can get Proto by downloading Boost (Proto is in version 1.37 and later), or by accessing Boost's SVN repository on SourceForge.net. Just go to <a href="http://svn.boost.org/trac/boost/wiki/BoostSubversion" target="_top">http://svn.boost.org/trac/boost/wiki/BoostSubversion</a> and follow the instructions there for anonymous SVN access. <h6> <a name="boost_proto.users_guide.getting_started.installing_proto.h1"></a> <a name="boost_proto.users_guide.getting_started.installing_proto.building_with_proto"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.installing_proto.building_with_proto">Building with Proto</a> </h6> Proto is a header-only template library, which means you don't need to alter your build scripts or link to any separate lib file to use it. All you need to do is <code class="computeroutput">#include <boost/proto/proto.hpp></code>. Or, you might decide to just include the core of Proto (<code class="computeroutput">#include <boost/proto/core.hpp></code>) and whichever contexts and transforms you happen to use. <h6> <a name="boost_proto.users_guide.getting_started.installing_proto.h2"></a> <a name="boost_proto.users_guide.getting_started.installing_proto.requirements"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.installing_proto.requirements">Requirements</a> </h6> Proto depends on Boost. You must use either Boost version 1.34.1 or higher, or the version in SVN trunk. <h6> <a name="boost_proto.users_guide.getting_started.installing_proto.h3"></a> <a name="boost_proto.users_guide.getting_started.installing_proto.supported_compilers"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.installing_proto.supported_compilers">Supported Compilers</a> </h6> Currently, Boost.Proto is known to work on the following compilers: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Visual C++ 8 and higher </li> <li class="listitem"> GNU C++ 3.4 and higher </li> <li class="listitem"> Intel on Linux 8.1 and higher </li> <li class="listitem"> Intel on Windows 9.1 and higher </li> </ul></div> <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> Please send any questions, comments and bug reports to eric <at> boostpro <dot> com. </td></tr> </table></div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="boost_proto.users_guide.getting_started.naming"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.naming" title="Naming Conventions">Naming Conventions</a> </h4></div></div></div> 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. <h6> <a name="boost_proto.users_guide.getting_started.naming.h0"></a> <a name="boost_proto.users_guide.getting_started.naming.functions"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.naming.functions">Functions</a> </h6> All of Proto's functions are defined in the <code class="computeroutput">boost::proto</code> namespace. For example, there is a function called <code class="computeroutput">value()</code> defined in <code class="computeroutput">boost::proto</code> that accepts a terminal expression and returns the terminal's value. <h6> <a name="boost_proto.users_guide.getting_started.naming.h1"></a> <a name="boost_proto.users_guide.getting_started.naming.metafunctions"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.naming.metafunctions">Metafunctions</a> </h6> 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 <code class="computeroutput">boost::proto::result_of</code> namespace and have the same name as the functions to which they correspond. For instance, there is a class template <code class="computeroutput">boost::proto::result_of::value<></code> that you can use to compute the return type of the <code class="computeroutput">boost::proto::value()</code> function. <h6> <a name="boost_proto.users_guide.getting_started.naming.h2"></a> <a name="boost_proto.users_guide.getting_started.naming.function_objects"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.naming.function_objects">Function Objects</a> </h6> Proto defines function object equivalents of all of its free functions. (A function object is an instance of a class type that defines an <code class="computeroutput">operator()</code> member function.) All of Proto's function object types are defined in the <code class="computeroutput">boost::proto::functional</code> namespace and have the same name as their corresponding free functions. For example, <code class="computeroutput">boost::proto::functional::value</code> is a class that defines a function object that does the same thing as the <code class="computeroutput">boost::proto::value()</code> free function. <h6> <a name="boost_proto.users_guide.getting_started.naming.h3"></a> <a name="boost_proto.users_guide.getting_started.naming.primitive_transforms"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.naming.primitive_transforms">Primitive Transforms</a> </h6> 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 <code class="computeroutput">boost::proto</code> namespace and their names have a leading underscore. For instance, the transform corresponding to the <code class="computeroutput">value()</code> function is called <code class="computeroutput">boost::proto::_value</code>. The following table summarizes the discussion above: <div class="table"> <a name="boost_proto.users_guide.getting_started.naming.t0"></a>Table 23.1. Proto Naming Conventions <div class="table-contents"><table class="table" summary="Proto Naming Conventions"> <colgroup> <col> <col> </colgroup> <thead><tr> <th> Entity </th> <th> Example </th> </tr></thead> <tbody> <tr> <td> Free Function </td> <td> <code class="computeroutput">boost::proto::value()</code> </td> </tr> <tr> <td> Metafunction </td> <td> <code class="computeroutput">boost::proto::result_of::value<></code> </td> </tr> <tr> <td> Function Object </td> <td> <code class="computeroutput">boost::proto::functional::value</code> </td> </tr> <tr> <td> Transform </td> <td> <code class="computeroutput">boost::proto::_value</code> </td> </tr> </tbody> </table></div> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="boost_proto.users_guide.getting_started.hello_world"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_world" title="Hello World">Hello World</a> </h4></div></div></div> Below is a very simple program that uses Proto to build an expression template and then execute it. <pre class="programlisting">#include <iostream> #include <boost/proto/proto.hpp> #include <boost/typeof/std/ostream.hpp> using namespace boost; proto::terminal< std::ostream & >::type cout_ = { std::cout }; template< typename Expr > void evaluate( Expr const & expr ) { proto::default_context ctx; proto::eval(expr, ctx); } int main() { evaluate( cout_ << "hello" << ',' << " world" ); return 0; } </pre> This program outputs the following: <pre class="programlisting">hello, world </pre> This program builds an object representing the output operation and passes it to an <code class="computeroutput">evaluate()</code> function, which then executes it. 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 Protofied in order for Proto's operator overloads to be found. In the expression ... <pre class="programlisting">cout_ << "hello" << ',' << " world" </pre> ... the Protofied sub-expression is <code class="computeroutput">cout_</code>, which is the Proto-ification of <code class="computeroutput">std::cout</code>. The presence of <code class="computeroutput">cout_</code> "infects" the expression, and brings Proto's tree-building operator overloads into consideration. Any literals in 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 can be lazily evaluated later by walking the tree. That is what <code class="computeroutput">proto::eval()</code> does. It is a general tree-walking expression evaluator, whose behavior is customizable via a context parameter. The use of <code class="computeroutput"><a class="link" href="../boost/proto/context/default_context.html" title="Struct default_context">proto::default_context</a></code> assigns the standard meanings to the operators in the expression. (By using a different context, you could give the operators in your expressions different semantics. By default, Proto makes no assumptions about what operators actually mean.) <h6> <a name="boost_proto.users_guide.getting_started.hello_world.h0"></a> <a name="boost_proto.users_guide.getting_started.hello_world.proto_design_philosophy"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_world.proto_design_philosophy">Proto Design Philosophy</a> </h6> 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 world example is totally general and abstract. It is not tied in any way to any particular domain or application, nor does it have any particular meaning or behavior on its own, until it is evaluated in a context. Expression templates are really just heterogeneous trees, which might mean something in one domain, and something else entirely in a different one. As we'll see later, there is a way to create Proto expression trees that are 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. </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="boost_proto.users_guide.getting_started.hello_calculator"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_calculator" title="Hello Calculator">Hello Calculator</a> </h4></div></div></div> "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 <code class="computeroutput">(_2 - _1) / _2 * 100</code>, where <code class="computeroutput">_1</code> and <code class="computeroutput">_2</code> are placeholders for values to be passed in when the expression is evaluated. <h6> <a name="boost_proto.users_guide.getting_started.hello_calculator.h0"></a> <a name="boost_proto.users_guide.getting_started.hello_calculator.defining_terminals"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_calculator.defining_terminals">Defining Terminals</a> </h6> The first order of business is to define the placeholders <code class="computeroutput">_1</code> and <code class="computeroutput">_2</code>. For that, we'll use the <code class="computeroutput"><a class="link" href="../boost/proto/terminal.html" title="Struct template terminal">proto::terminal<></a></code> metafunction. <pre class="programlisting">// 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 = {{}}; </pre> The initialization may look a little odd at first, but there is a good reason for doing things this way. The objects <code class="computeroutput">_1</code> and <code class="computeroutput">_2</code> above do not require run-time construction -- they are statically initialized, which means they are essentially initialized at compile time. See the <a class="link" href="appendices.html#boost_proto.appendices.rationale.static_initialization" title="Static Initialization">Static Initialization</a> section in the <a class="link" href="appendices.html#boost_proto.appendices.rationale" title="Appendix C: Rationale">Rationale</a> appendix for more information. <h6> <a name="boost_proto.users_guide.getting_started.hello_calculator.h1"></a> <a name="boost_proto.users_guide.getting_started.hello_calculator.constructing_expression_trees"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_calculator.constructing_expression_trees">Constructing Expression Trees</a> </h6> 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: <pre class="programlisting">// This builds an expression template (_2 - _1) / _2 * 100; </pre> 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. <h6> <a name="boost_proto.users_guide.getting_started.hello_calculator.h2"></a> <a name="boost_proto.users_guide.getting_started.hello_calculator.evaluating_expression_trees"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_calculator.evaluating_expression_trees">Evaluating Expression Trees</a> </h6> 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. <pre class="programlisting">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]; } }; </pre> In <code class="computeroutput">calculator_context</code>, 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 <a href="../../../libs/typeof/index.html" target="_top">Boost.Typeof</a> 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: <pre class="programlisting">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; </pre> 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. <h6> <a name="boost_proto.users_guide.getting_started.hello_calculator.h3"></a> <a name="boost_proto.users_guide.getting_started.hello_calculator.customizing_expression_trees"></a><a class="link" href="users_guide.html#boost_proto.users_guide.getting_started.hello_calculator.customizing_expression_trees">Customizing Expression Trees</a> </h6> 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 <code class="computeroutput">operator()</code> 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: <pre class="programlisting">// 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> > {}; </pre> The <code class="computeroutput">calculator<></code> 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 <code class="computeroutput">calculator_domain</code> is what informs Proto about our wrapper. It is used below in the definition of <code class="computeroutput">calculator<></code>. Read on for a description. <pre class="programlisting">// 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); } }; </pre> The <code class="computeroutput">calculator<></code> struct is an expression extension. It uses <code class="computeroutput">proto::extends<></code> 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 <code class="computeroutput">calculator<></code> wrapper, as below: <pre class="programlisting">// 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; </pre> Any larger expression that contain these placeholders will automatically be wrapped in the <code class="computeroutput">calculator<></code> wrapper and have our <code class="computeroutput">operator()</code> overload. That means we can use them as function objects as follows. <pre class="programlisting">double result <span class