ceph/src/boost/libs/spirit/doc/karma/action.qbk

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   4
   5     Distributed under the Boost Software License, Version 1.0. (See accompanying
   6     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7 ===============================================================================/]
   8
   9 [section:action Semantic Actions with Generators]
  10
  11 [heading Description]
  12
  13 Semantic actions may be attached to any point in the grammar specification.
  14 They allow to call a function or function object in order to provide the value
  15 output by the generator attached to the semantic action.  Semantic
  16 actions are associated with a generator using the syntax `g[]`, where `g` is an
  17 arbitrary generator expression.
  18
  19 [heading Header]
  20
  21     // forwards to <boost/spirit/home/karma/action.hpp>
  22     #include <boost/spirit/include/karma_action.hpp>
  23
  24 Also, see __include_structure__.
  25
  26 [heading Model of]
  27
  28 [:__unary_generator_concept__]
  29
  30 [variablelist Notation
  31     [[`a`, `g`][Instances of a generator, `G`]]
  32     [[`A`]     [Attribute type exposed by a generator, `a`]]
  33     [[`fa`]    [A (semantic action) function with signature `void(Attrib&, Context&, bool&)`.
  34                The third parameter is a boolean flag that can be set to false to
  35                force the generator to fail. Both `Context` and the boolean flag are
  36                optional. For more information see below.]]
  37     [[`Attrib`][The attribute to be used to generate output from.]]
  38     [[`Context`]  [The type of the generator execution context. For more
  39                 information see below.]]
  40 ]
  41
  42 [heading Expression Semantics]
  43
  44 Semantics of an expression is defined only where it differs from, or is not
  45 defined in __unary_generator_concept__.
  46
  47 [table
  48     [[Expression]       [Semantics]]
  49     [[`g[fa]`]          [Call semantic action, `fa` /before/ invoking `g`. The function
  50                          or function object `fa` is expected to provide the value
  51                          to generate output from to the generator `g`.]]
  52 ]
  53
  54 The possible signatures for functions to be used as semantic actions are:
  55
  56     template <typename Attrib>
  57     void fa(Attrib& attr);
  58
  59     template <typename Attrib, typename Context>
  60     void fa(Attrib& attr, Context& context);
  61
  62     template <typename Attrib, typename Context>
  63     void fa(Attrib& attr, Context& context, bool& pass);
  64
  65 The function or function object is expected to return the value to generate
  66 output from by assigning it to the first parameter, `attr`. Here `Attrib` is
  67 the attribute type of the generator attached to the semantic action.
  68
  69 The type `Context` is the type of the generator execution context. This type is
  70 unspecified and depends on the context the generator is invoked in. The value
  71 `context` is used by semantic actions written using __phoenix__ to access various
  72 context dependent attributes and values. For more information about __phoenix__
  73 placeholder expressions usable in semantic actions see __karma_nonterminal_concept__.
  74
  75 The third parameter, `pass`, can be used by the semantic action to force the
  76 associated generator to fail. If pass is set to `false` the action generator
  77 will immediately return `false` as well, while not invoking `g` and not
  78 generating any output.
  79
  80 [heading Attributes]
  81
  82 [table
  83     [[Expression]       [Attribute]]
  84     [[`a[fa]`]          [`a: A --> a[fa]: A`]]
  85 ]
  86
  87 [heading Complexity]
  88
  89 The complexity of the action generator is defined by the complexity of the
  90 generator the semantic action is attached to and the complexity of the function
  91 or function object used as the semantic action.
  92
  93 [important Please note that the use of semantic actions in __karma__ generally
  94            forces the library to create a /copy/ of the attribute, which might
  95            be a costly operation. Always consider using other means of
  96            associating a value with a particular generator first.]
  97
  98 [heading Example]
  99
 100 [note The test harness for the example(s) below is presented in the
 101       __karma_basics_examples__ section.]
 102
 103 Some includes:
 104
 105 [reference_karma_includes]
 106
 107 Some using declarations:
 108
 109 [reference_karma_using_declarations_action]
 110
 111 Some examples:
 112
 113 [reference_karma_action]
 114
 115 More examples for semantic actions can be found here:
 116 [link spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions Examples of Semantic Actions].
 117
 118 [endsect] [/ Action]
 119