[Boost-commit] svn:boost r57189 - in trunk/libs/spirit/doc: karma qi

Subject: [Boost-commit] svn:boost r57189 - in trunk/libs/spirit/doc: karma qi
From: joel_at_[hidden]
Date: 2009-10-28 06:25:36

Author: djowel
Date: 2009-10-28 06:25:36 EDT (Wed, 28 Oct 2009)
New Revision: 57189
URL: http://svn.boost.org/trac/boost/changeset/57189

Log:
actions. first pass.
Text files modified: 
   trunk/libs/spirit/doc/karma/action.qbk |     2                                         
   trunk/libs/spirit/doc/qi/action.qbk    |    96 +++++++++++++++++++++++++++++++++++++++ 
   2 files changed, 95 insertions(+), 3 deletions(-)

Modified: trunk/libs/spirit/doc/karma/action.qbk
==============================================================================
--- trunk/libs/spirit/doc/karma/action.qbk	(original)
+++ trunk/libs/spirit/doc/karma/action.qbk	2009-10-28 06:25:36 EDT (Wed, 28 Oct 2009)
@@ -87,7 +87,7 @@
 [heading Complexity]
 
 The complexity of the action generator is defined by the complexity of the 
-generator teh semantic action is attached to and the complexity of the function
+generator the semantic action is attached to and the complexity of the function
 or function object used as the semantic action.
 
 [important Please note that the use of semantic actions in __karma__ generally

Modified: trunk/libs/spirit/doc/qi/action.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/action.qbk	(original)
+++ trunk/libs/spirit/doc/qi/action.qbk	2009-10-28 06:25:36 EDT (Wed, 28 Oct 2009)
@@ -6,8 +6,100 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ===============================================================================/]
 
-[/ section Action]
+[section Action]
 
+[heading Description]
 
+Semantic actions may be attached to any point in the grammar specification. 
+They allow to call a function or function object in order to provide the value 
+to be output by the parser the semantic action is attached to. Semantic 
+actions are associated with a parser using the syntax `p[]`, where `p` is an
+arbitrary parser expression.
+
+[heading Header]
+
+    // forwards to <boost/spirit/qi/action.hpp>
+    #include <boost/spirit/include/qi_action.hpp>
+
+Also, see __include_structure__.
+
+[heading Model of]
+
+[:__unary_parser_concept__]
+
+[variablelist Notation
+    [[`a`, `p`][Instances of a parser, `P`]]
+    [[`A`]     [Attribute type exposed by a parser, `a`]]
+    [[`fa`]    [A (semantic action) function with signature `void(Attrib&, Context, bool&)`.
+               The third parameter is a boolean flag that can be set to false to
+               force the parser to fail. Both `Context` and the boolean flag are
+               optional. For more information see below.]]
+    [[`Attrib`][The attribute obtained from the parse.]]
+    [[`Context`]  [The type of the parser execution context. For more 
+                information see below.]]
+]
+
+[heading Expression Semantics]
+
+Semantics of an expression is defined only where it differs from, or is not
+defined in __unary_parser_concept__.
+
+[table
+    [[Expression]       [Semantics]]
+    [[`p[fa]`]          [If `p` is successful, call semantic action, `fa`. The function
+                         or function object `fa` is provided the attribute value
+                         parsed by the parser `p`, plus some more context information
+                         and a mutable bool flag which can be used to fail parsing.]]
+]
+
+The possible signatures for functions to be used as semantic actions are:
+
+    template <typename Attrib>
+    void fa(Attrib& attr);
+
+    template <typename Attrib, typename Context>
+    void fa(Attrib& attr, Context& context);
+
+    template <typename Attrib, typename Context>
+    void fa(Attrib& attr, Context& context, bool& pass);
+
+The function or function object is expected to return the value to generate 
+output from by assigning it to the first parameter, `attr`. Here `Attrib` is 
+the attribute type of the parser the semantic action is attached to. 
+
+The type `Context` is the type of the parser execution context. This type is 
+unspecified and depends on the context the parser is invoked in. The value, 
+`context` used by semantic actions written using __phoenix__ to access various 
+context dependent attributes and values. For more information about __phoenix__ 
+placeholder expressions usable in semantic actions see __qi_nonterminal_concept__.
+
+The third parameter, `pass`, can be used by the semantic action to force the 
+associated parser to fail. If pass is set to `false` the action parser 
+will immediatly return `false` as well, while not invoking `p` and not 
+generating any output.
+
+[heading Attributes]
+
+[table
+    [[Expression]       [Attribute]]
+    [[`a[fa]`]          [`a: A --> a[fa]: A`]]
+]
+
+[heading Complexity]
+
+The complexity of the action parser is defined by the complexity of the 
+parser the semantic action is attached to and the complexity of the function
+or function object used as the semantic action.
+
+[heading Example]
+
+[note The test harness for the example(s) below is presented in the
+      __qi_basics_examples__ section.]
+
+[reference_qi_action]
+
+More examples for semantic actions can be found here: 
+[link spirit.qi.tutorials.semantic_actions.examples_of_semantic_actions Examples of Semantic Actions].
+
+[endsect] [/ Action]
 
-[/ endsect]