ceph/src/boost/libs/proto/doc/conventions.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:naming Naming Conventions]
  10 [/================================]
  11
  12 Proto is a large library and probably quite unlike any library you've used
  13 before. Proto uses some consistent naming conventions to make it easier to
  14 navigate, and they're described below.
  15
  16 [/================]
  17 [heading Functions]
  18 [/================]
  19
  20 All of Proto's functions are defined in the `boost::proto` namespace. For
  21 example, there is a function called `value()` defined in `boost::proto` that
  22 accepts a terminal expression and returns the terminal's value.
  23
  24 [/====================]
  25 [heading Metafunctions]
  26 [/====================]
  27
  28 Proto defines /metafunctions/ that correspond to each of Proto's free functions.
  29 The metafunctions are used to compute the functions' return types. All of
  30 Proto's metafunctions live in the `boost::proto::result_of` namespace and
  31 have the same name as the functions to which they correspond. For instance,
  32 there is a class template `boost::proto::result_of::value<>` that you can
  33 use to compute the return type of the `boost::proto::value()` function.
  34
  35 [/=======================]
  36 [heading Function Objects]
  37 [/=======================]
  38
  39 Proto defines /function object/ equivalents of all of its free functions. (A
  40 function object is an instance of a class type that defines an `operator()`
  41 member function.) All of Proto's function object types are defined in the
  42 `boost::proto::functional` namespace and have the same name as their
  43 corresponding free functions. For example, `boost::proto::functional::value`
  44 is a class that defines a function object that does the same thing as the
  45 `boost::proto::value()` free function.
  46
  47 [/===========================]
  48 [heading Primitive Transforms]
  49 [/===========================]
  50
  51 Proto also defines /primitive transforms/ -- class types that can be used
  52 to compose larger transforms for manipulating expression trees. Many of
  53 Proto's free functions have corresponding primitive transforms. These live
  54 in the `boost::proto` namespace and their names have a leading underscore.
  55 For instance, the transform corresponding to the `value()` function is
  56 called `boost::proto::_value`.
  57
  58 The following table summarizes the discussion above:
  59
  60 [table Proto Naming Conventions
  61   [[Entity]           [Example]                            ]
  62   [[Free Function]    [`boost::proto::value()`]            ]
  63   [[Metafunction]     [`boost::proto::result_of::value<>`] ]
  64   [[Function Object]  [`boost::proto::functional::value`]  ]
  65   [[Transform]        [`boost::proto::_value`]             ]
  66 ]
  67
  68 [endsect]
  69