ceph/src/boost/libs/proto/doc/hello_world.qbk

   1 [/
   2  / Copyright (c) 2008 Eric Niebler
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [/==================]
   9 [section Hello World]
  10 [/==================]
  11
  12 Below is a very simple program that uses Proto to build an expression template
  13 and then execute it.
  14
  15     #include <iostream>
  16     #include <boost/proto/proto.hpp>
  17     #include <boost/typeof/std/ostream.hpp>
  18     using namespace boost;
  19
  20     proto::terminal< std::ostream & >::type cout_ = { std::cout };
  21
  22     template< typename Expr >
  23     void evaluate( Expr const & expr )
  24     {
  25         proto::default_context ctx;
  26         proto::eval(expr, ctx);
  27     }
  28
  29     int main()
  30     {
  31         evaluate( cout_ << "hello" << ',' << " world" );
  32         return 0;
  33     }
  34
  35 This program outputs the following:
  36
  37 [pre
  38 hello, world
  39 ]
  40
  41 This program builds an object representing the output operation and passes
  42 it to an `evaluate()` function, which then executes it.
  43
  44 The basic idea of expression templates is to overload all the operators so
  45 that, rather than evaluating the expression immediately, they build a tree-like
  46 representation of the expression so that it can be evaluated later. For each
  47 operator in an expression, at least one operand must be Protofied in order
  48 for Proto's operator overloads to be found. In the expression ...
  49
  50     cout_ << "hello" << ',' << " world"
  51
  52 ... the Protofied sub-expression is `cout_`, which is the Proto-ification of
  53 `std::cout`. The presence of `cout_` "infects" the expression, and brings
  54 Proto's tree-building operator overloads into consideration. Any literals in
  55 the expression are then Protofied by wrapping them in a Proto terminal before
  56 they are combined into larger Proto expressions.
  57
  58 Once Proto's operator overloads have built the expression tree, the expression
  59 can be lazily evaluated later by walking the tree. That is what `proto::eval()`
  60 does. It is a general tree-walking expression evaluator, whose behavior is
  61 customizable via a /context/ parameter. The use of _default_context_ assigns
  62 the standard meanings to the operators in the expression. (By using a different
  63 context, you could give the operators in your expressions different semantics.
  64 By default, Proto makes no assumptions about what operators actually /mean/.)
  65
  66 [/==============================]
  67 [heading Proto Design Philosophy]
  68 [/==============================]
  69
  70 Before we continue, let's use the above example to illustrate an important
  71 design principle of Proto's. The expression template created in the ['hello
  72 world] example is totally general and abstract. It is not tied in any way to
  73 any particular domain or application, nor does it have any particular meaning
  74 or behavior on its own, until it is evaluated in a /context/. Expression
  75 templates are really just heterogeneous trees, which might mean something in
  76 one domain, and something else entirely in a different one.
  77
  78 As we'll see later, there is a way to create Proto expression trees that are
  79 ['not] purely abstract, and that have meaning and behaviors independent of any
  80 context. There is also a way to control which operators are overloaded for your
  81 particular domain. But that is not the default behavior. We'll see later why
  82 the default is often a good thing.
  83
  84 [endsect]