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

   1
   2 [library Boost.Proto
   3     [quickbook 1.3]
   4     [authors [Niebler, Eric]]
   5     [copyright 2008 Eric Niebler]
   6     [category template]
   7     [id proto]
   8     [dirname proto]
   9     [purpose
  10         Generic expression template, grammar and
  11         tree-transformation framework.
  12     ]
  13     [license
  14         Distributed under the Boost Software License, Version 1.0.
  15         (See accompanying file LICENSE_1_0.txt or copy at
  16         [@http://www.boost.org/LICENSE_1_0.txt])
  17     ]
  18 ]
  19
  20 [/
  21  / Copyright (c) 2008 Eric Niebler
  22  /
  23  / Distributed under the Boost Software License, Version 1.0. (See accompanying
  24  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  25  /]
  26
  27 [/ QuickBook Document version 1.3 ]
  28
  29 [/  Images   ]
  30
  31 [def __note__               [$images/note.png]]
  32 [def __alert__              [$images/caution.png]]
  33 [def __detail__             [$images/note.png]]
  34 [def __tip__                [$images/tip.png]]
  35
  36 [/  Links   ]
  37
  38 [def _PETE_
  39   [@http://acts.nersc.gov/formertools/pete/index.html PETE]]
  40 [def _spirit_fx_
  41   [@http://spirit.sourceforge.net Spirit Parser Framework]]
  42 [def _spirit_
  43   [@http://spirit.sourceforge.net Spirit]]
  44 [def _xpressive_
  45   [@../../libs/xpressive/index.html Boost.Xpressive]]
  46 [def _typeof_
  47   [@../../libs/typeof/index.html Boost.Typeof]]
  48 [def _expr_
  49   [classref  boost::proto::expr `proto::expr<>`]]
  50 [def _basic_expr_
  51   [classref  boost::proto::basic_expr `proto::basic_expr<>`]]
  52 [def _deep_copy_
  53   [funcref   boost::proto::deep_copy `proto::deep_copy()`]]
  54 [def _domain_
  55   [classref  boost::proto::domain `proto::domain<>`]]
  56 [def _default_domain_
  57   [classref  boost::proto::default_domain `proto::default_domain`]]
  58 [def _extends_
  59   [classref  boost::proto::extends `proto::extends<>`]]
  60 [def _external_transform_
  61   [classref  boost::proto::external_transform `proto::external_transform`]]
  62 [def _external_transforms_
  63   [classref  boost::proto::external_transforms `proto::external_transforms<>`]]
  64 [def _as_expr_
  65   [funcref   boost::proto::as_expr `proto::as_expr()`]]
  66 [def _as_child_
  67   [funcref   boost::proto::as_child `proto::as_child()`]]
  68 [def _make_expr_
  69   [funcref   boost::proto::make_expr `proto::make_expr()`]]
  70 [def _unpack_expr_
  71   [funcref   boost::proto::unpack_expr `proto::unpack_expr()`]]
  72 [def _display_expr_
  73   [funcref   boost::proto::display_expr `proto::display_expr()`]]
  74 [def _matches_
  75   [classref  boost::proto::matches `proto::matches<>`]]
  76 [def _or_
  77   [classref  boost::proto::or_ `proto::or_<>`]]
  78 [def _and_
  79   [classref  boost::proto::and_ `proto::and_<>`]]
  80 [def _if_
  81   [classref  boost::proto::if_ `proto::if_<>`]]
  82 [def _not_
  83   [classref  boost::proto::not_ `proto::not_<>`]]
  84 [def _switch_
  85   [classref  boost::proto::switch_ `proto::switch_<>`]]
  86 [def _exact_
  87   [classref  boost::proto::exact `proto::exact<>`]]
  88 [def _convertible_to_
  89   [classref  boost::proto::convertible_to `proto::convertible_to<>`]]
  90 [def _is_expr_
  91   [classref  boost::proto::is_expr `proto::is_expr<>`]]
  92 [def _tag_of_
  93   [classref  boost::proto::tag_of `proto::tag_of<>`]]
  94 [def _arity_of_
  95   [classref  boost::proto::arity_of `proto::arity_of<>`]]
  96 [def _child_
  97   [funcref   boost::proto::child `proto::child()`]]
  98 [def _child_c_
  99   [funcref   boost::proto::child_c `proto::child_c()`]]
 100 [def _eval_
 101   [funcref   boost::proto::eval `proto::eval()`]]
 102 [def _left_
 103   [funcref   boost::proto::left `proto::left()`]]
 104 [def _right_
 105   [funcref   boost::proto::right `proto::right()`]]
 106 [def _value_
 107   [funcref   boost::proto::value `proto::value()`]]
 108 [def _terminal_
 109   [classref  boost::proto::terminal `proto::terminal<>`]]
 110 [def _unary_plus_
 111   [classref  boost::proto::unary_plus `proto::unary_plus<>`]]
 112 [def _plus_
 113   [classref  boost::proto::plus `proto::plus<>`]]
 114 [def _function_
 115   [classref  boost::proto::function `proto::function<>`]]
 116 [def _unary_expr_
 117   [classref  boost::proto::unary_expr `proto::unary_expr<>`]]
 118 [def _binary_expr_
 119   [classref  boost::proto::binary_expr `proto::binary_expr<>`]]
 120 [def _nary_expr_
 121   [classref  boost::proto::nary_expr `proto::nary_expr<>`]]
 122 [def _literal_
 123   [classref  boost::proto::literal `proto::literal<>`]]
 124 [def _lit_
 125   [funcref   boost::proto::lit `proto::lit()`]]
 126 [def _vararg_
 127   [classref  boost::proto::vararg `proto::vararg<>`]]
 128 [def _default_context_
 129   [classref  boost::proto::context::default_context `proto::default_context`]]
 130 [def _callable_context_
 131   [classref  boost::proto::context::callable_context `proto::callable_context<>`]]
 132 [def _null_context_
 133   [classref  boost::proto::context::null_context `proto::null_context<>`]]
 134 [def _when_
 135   [classref  boost::proto::when `proto::when<>`]]
 136 [def _call_
 137   [classref  boost::proto::call `proto::call<>`]]
 138 [def _make_
 139   [classref  boost::proto::make `proto::make<>`]]
 140 [def _flatten_
 141   [funcref   boost::proto::flatten `proto::flatten()`]]
 142 [def _value_pt_
 143   [classref boost::proto::_value `proto::_value`]]
 144 [def _child_c_pt_
 145   [classref boost::proto::_child_c `proto::_child_c<>`]]
 146 [def _child_pt_
 147   [classref boost::proto::_child `proto::_child`]]
 148 [def _left_pt_
 149   [classref boost::proto::_left `proto::_left`]]
 150 [def _right_pt_
 151   [classref boost::proto::_right `proto::_right`]]
 152 [def _wild_
 153   [classref boost::proto::_ `proto::_`]]
 154 [def _expr_pt_
 155   [classref boost::proto::_expr `proto::_expr`]]
 156 [def _state_pt_
 157   [classref boost::proto::_state `proto::_state`]]
 158 [def _data_pt_
 159   [classref boost::proto::_data `proto::_data`]]
 160 [def _call_pt_
 161   [classref boost::proto::call `proto::call<>`]]
 162 [def _make_pt_
 163   [classref boost::proto::make `proto::make<>`]]
 164 [def _default_pt_
 165   [classref boost::proto::_default `proto::_default<>`]]
 166 [def _fold_pt_
 167   [classref boost::proto::fold `proto::fold<>`]]
 168 [def _fold_tree_pt_
 169   [classref boost::proto::fold_tree `proto::fold_tree<>`]]
 170 [def _reverse_fold_pt_
 171   [classref boost::proto::reverse_fold `proto::reverse_fold<>`]]
 172 [def _reverse_fold_tree_pt_
 173   [classref boost::proto::reverse_fold_tree `proto::reverse_fold_tree<>`]]
 174 [def _generator_
 175   [classref boost::proto::generator `proto::generator<>`]]
 176 [def _pod_generator_
 177   [classref boost::proto::pod_generator `proto::pod_generator<>`]]
 178 [def _deduce_domain_
 179   [classref boost::proto::deduce_domain `proto::deduce_domain`]]
 180 [def _lazy_pt_
 181   [classref boost::proto::lazy `proto::lazy<>`]]
 182 [def _pack_
 183   [classref boost::proto::pack `proto::pack`]]
 184 [def _SYB_
 185   [link boost_proto.users_guide.resources.SYB ["Scrap Your Boilerplate]]]
 186 [def _result_of_value_
 187   [classref boost::proto::result_of::value `proto::result_of::value<>`]]
 188 [def _result_of_child_c_
 189   [classref boost::proto::result_of::child_c `proto::result_of::child_c<>`]]
 190 [def _result_of_child_
 191   [classref boost::proto::result_of::child `proto::result_of::child<>`]]
 192 [def _result_of_left_
 193   [classref boost::proto::result_of::left `proto::result_of::left<>`]]
 194 [def _result_of_right_
 195   [classref boost::proto::result_of::right `proto::result_of::right<>`]]
 196 [def _MAX_ARITY_
 197   [^[macroref BOOST_PROTO_MAX_ARITY]]]
 198 [def _MAX_LOGICAL_ARITY_
 199   [^[macroref BOOST_PROTO_MAX_LOGICAL_ARITY]]]
 200 [def _MAX_FUNCTION_CALL_ARITY_
 201   [^[macroref BOOST_PROTO_MAX_FUNCTION_CALL_ARITY]]]
 202 [def _BASIC_EXTENDS_
 203   [^[macroref BOOST_PROTO_BASIC_EXTENDS]()]]
 204 [def _EXTENDS_
 205   [^[macroref BOOST_PROTO_EXTENDS]()]]
 206 [def _EXTENDS_ASSIGN_
 207   [^[macroref BOOST_PROTO_EXTENDS_ASSIGN]()]]
 208 [def _EXTENDS_SUBSCRIPT_
 209   [^[macroref BOOST_PROTO_EXTENDS_SUBSCRIPT]()]]
 210 [def _EXTENDS_FUNCTION_
 211   [^[macroref BOOST_PROTO_EXTENDS_FUNCTION]()]]
 212 [def _DEFINE_OPERATORS_
 213   [^[macroref BOOST_PROTO_DEFINE_OPERATORS]()]]
 214 [def _AUTO_
 215   [^[macroref BOOST_PROTO_AUTO]()]]
 216 [def _REPEAT_
 217   [^[macroref BOOST_PROTO_REPEAT]()]]
 218 [def _REPEAT_FROM_TO_
 219   [^[macroref BOOST_PROTO_REPEAT_FROM_TO]()]]
 220 [def _REPEAT_EX_
 221   [^[macroref BOOST_PROTO_REPEAT_EX]()]]
 222 [def _REPEAT_FROM_TO_EX_
 223   [^[macroref BOOST_PROTO_REPEAT_FROM_TO_EX]()]]
 224 [def _LOCAL_ITERATE_
 225   [^[macroref BOOST_PROTO_LOCAL_ITERATE]()]]
 226 [def _BOOST_PROTO_typename_A_
 227   [^[macroref BOOST_PROTO_typename_A]()]]
 228 [def _BOOST_PROTO_A_
 229   [^[macroref BOOST_PROTO_A]()]]
 230 [def _BOOST_PROTO_A_const_
 231   [^[macroref BOOST_PROTO_A_const]()]]
 232 [def _BOOST_PROTO_A_ref_
 233   [^[macroref BOOST_PROTO_A_ref]()]]
 234 [def _BOOST_PROTO_A_const_ref_
 235   [^[macroref BOOST_PROTO_A_const_ref]()]]
 236 [def _BOOST_PROTO_A_ref_a_
 237   [^[macroref BOOST_PROTO_A_ref_a]()]]
 238 [def _BOOST_PROTO_A_const_ref_a_
 239   [^[macroref BOOST_PROTO_A_const_ref_a]()]]
 240 [def _BOOST_PROTO_a_
 241   [^[macroref BOOST_PROTO_a]()]]
 242 [def _BOOST_PROTO_ref_a_
 243   [^[macroref BOOST_PROTO_ref_a]()]]
 244
 245 [include preface.qbk]
 246
 247 [/===============================]
 248 [section:users_guide Users' Guide]
 249 [/===============================]
 250
 251 [/===========================================================]
 252 [heading Compilers, Compiler Construction Toolkits, and Proto]
 253 [/===========================================================]
 254
 255 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.
 256
 257 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.
 258
 259 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.
 260
 261 This users' guide is organized as follows. After a [link boost_proto.users_guide.getting_started Getting Started guide], we'll cover the tools Proto provides for defining and manipulating the three major parts of a compiler:
 262
 263 [variablelist
 264   [[[link boost_proto.users_guide.front_end Front Ends]]
 265    [How to define the aspects of your EDSL with which your users will interact directly.]]
 266   [[[link boost_proto.users_guide.intermediate_form Intermediate Form]]
 267    [What Proto expression templates look like, how to discover their structure and access their constituents.]]
 268   [[[link boost_proto.users_guide.back_end Back Ends]]
 269    [How to define evaluation contexts and transforms that make expression templates do interesting things.]]
 270 ]
 271
 272 After that, you may be interested in seeing some [link boost_proto.users_guide.examples Examples] to get a better idea of how the pieces all fit together.
 273
 274 [include getting_started.qbk]
 275
 276 [include front_end.qbk]
 277
 278 [include intermediate_form.qbk]
 279
 280 [include back_end.qbk]
 281
 282 [include examples.qbk]
 283
 284 [include resources.qbk]
 285
 286 [include glossary.qbk]
 287
 288 [endsect]
 289
 290 [xinclude reference.xml]
 291
 292 [/=================]
 293 [section Appendices]
 294 [/=================]
 295
 296 [include release_notes.qbk]
 297
 298 [include history.qbk]
 299
 300 [include rationale.qbk]
 301
 302 [include implementation.qbk]
 303
 304 [include acknowledgements.qbk]
 305
 306 [endsect]