[Boost-commit] svn:boost r39915 - trunk/libs/xpressive/doc

From: eric_at_[hidden]
Date: 2007-10-10 22:12:07

Author: eric_niebler
Date: 2007-10-10 22:12:07 EDT (Wed, 10 Oct 2007)
New Revision: 39915
URL: http://svn.boost.org/trac/boost/changeset/39915

Log:
document placeholder<> and match_results<>::let()
Text files modified: 
   trunk/libs/xpressive/doc/actions.qbk |   208 +++++++++++++++++++++++++-------------- 
   1 files changed, 134 insertions(+), 74 deletions(-)

Modified: trunk/libs/xpressive/doc/actions.qbk
==============================================================================
--- trunk/libs/xpressive/doc/actions.qbk	(original)
+++ trunk/libs/xpressive/doc/actions.qbk	2007-10-10 22:12:07 EDT (Wed, 10 Oct 2007)
@@ -128,6 +128,82 @@
 character. When the `'?'` character is encountered, the match algorithm
 backtracks, removing the final action from the queue.
 
+[h3 Lazy Functions]
+
+So far, we've seen how to write semantic actions consisting of variables and
+operators. But what if you want to be able to call a function from a semantic
+action? Xpressive provides a mechanism to do this.
+
+The first step is to define a function object type. Here, for instance, is a 
+function object type that calls `push()` on its argument:
+
+    struct push_impl
+    {
+        // Result type, needed for tr1::result_of
+        typedef void result_type;
+
+        template<typename Sequence, typename Value>
+        void operator()(Sequence &seq, Value const &val) const
+        {
+            seq.push(val);
+        }
+    };
+
+The next step is to use xpressive's `function<>` template to define a function
+object named `push`:
+
+    // Global "push" function object.
+    function<push_impl>::type const push = {{}};
+
+The initialization looks a bit odd, but this is because `push` is being 
+statically initialized. That means it doesn't need to be constructed
+at runtime. We can use `push` in semantic actions as follows:
+
+    std::stack<int> ints;
+    // Match digits, cast them to an int
+    // and push it on the stack.
+    sregex rex = (+_d)[push(ref(ints), as<int>(_))];
+
+You'll notice that doing it this way causes member function invocations
+to look like ordinary function invocations. You can choose to write your
+semantic action in a different way that makes it look a bit more like
+a member function call:
+
+    sregex rex = (+_d)[ref(ints)->*push(as<int>(_))];
+
+Xpressive recognizes the use of the `->*` and treats this expression
+exactly the same as the one above.
+
+When your function object must return a type that depends on its
+arguments, you can use a `result<>` member template instead of the
+`result_type` typedef. Here, for example, is a `first` function object
+that returns the `first` member of a `std::pair<>` or _sub_match_:
+
+    // Function object that returns the 
+    // first element of a pair.
+    struct first_impl
+    {
+        template<typename Sig> struct result {};
+
+        template<typename This, typename Pair>
+        struct result<This(Pair)>
+        {
+            typedef typename remove_reference<Pair>
+                ::type::first_type type;
+        };
+
+        template<typename Pair>
+        typename Pair::first_type
+        operator()(Pair const &p) const
+        {
+            return p.first;
+        }
+    };
+
+    // OK, use as first(s1) to get the begin iterator
+    // of the sub-match referred to by s1.    
+    function<first_impl> const first = {{}};
+
 [h3 Referring to Local Variables]
 
 As we've seen in the examples above, we can refer to local variables within
@@ -206,88 +282,72 @@
     assert( i.get() == 2 );
 
 Notice that we use `local<>::get()` to access the value of the local
-variable. Also, beware that `local<>` can be uses to create a dangling
+variable. Also, beware that `local<>` can be used to create a dangling
 reference, just as `reference<>` can.
 
-[h3 Lazy Functions]
-
-So far, we've seen how to write semantic actions consisting of variables and
-operators. But what if you want to be able to call a function from a semantic
-action? Xpressive provides a mechanism to do this.
-
-The first step is to define a function object type. Here, for instance, is a 
-function object type that calls `push()` on its argument:
-
-    struct push_impl
-    {
-        // Result type, needed for tr1::result_of
-        typedef void result_type;
-
-        template<typename Sequence, typename Value>
-        void operator()(Sequence &seq, Value const &val) const
-        {
-            seq.push(val);
-        }
-    };
-
-The next step is to use xpressive's `function<>` template to define a function
-object named `push`:
-
-    // Global "push" function object.
-    function<push_impl>::type const push = {{}};
+[h3 Referring to Non-Local Variables]
 
-The initialization looks a bit odd, but this is because `push` is being 
-statically initialized. That means it doesn't need to be constructed
-at runtime. We can use `push` in semantic actions as follows:
-
-    std::stack<int> ints;
-    // Match digits, cast them to an int
-    // and push it on the stack.
-    sregex rex = (+_d)[push(ref(ints), as<int>(_))];
-
-You'll notice that doing it this way causes member function invocations
-to look like ordinary function invocations. You can choose to write your
-semantic action in a different way that makes it look a bit more like
-a member function call:
-
-    sregex rex = (+_d)[ref(ints)->*push(as<int>(_))];
-
-Xpressive recognizes the use of the `->*` and treats this expression
-exactly the same as the one above.
-
-When your function object must return a type that depends on its
-arguments, you can use a `result<>` member template instead of the
-`result_type` typedef. Here, for example, is a `first` function object
-that returns the `first` member of a `std::pair<>` or _sub_match_:
+In the beginning of this
+section, we used a regex with a semantic action to parse a string of
+word/integer pairs and stuff them into a `std::map<>`. That required that
+the map and the regex be defined together and used before either could
+go out of scope. What if we wanted to define the regex once and use it
+to fill lots of different maps? We would rather pass the map into the
+_regex_match_ algorithm rather than embed a reference to it directly in
+the regex object. What we can do instead is define a placeholder and use
+that in the semantic action instead of the map itself. Later, when we
+call one of the regex algorithms, we can bind the reference to an actual
+map object. The following code shows how.
+    
+    // Define a placeholder for a map object:
+    placeholder<std::map<std::string, int> > _map;
+    
+    // Match a word and an integer, separated by =>,
+    // and then stuff the result into a std::map<>
+    sregex pair = ( (s1= +_w) >> "=>" >> (s2= +_d) )
+        [ _map[s1] = as<int>(s2) ];
+    
+    // Match one or more word/integer pairs, separated
+    // by whitespace.
+    sregex rx = pair >> *(+_s >> pair);
+
+    // The string to parse
+    std::string str("aaa=>1 bbb=>23 ccc=>456");
+
+    // Here is the actual map to fill in:
+    std::map<std::string, int> result;
+    
+    // Bind the _map placeholder to the actual map
+    smatch what;
+    what.let( _map = result );
 
-    // Function object that returns the 
-    // first element of a pair.
-    struct first_impl
+    // Execute the match and fill in result map
+    if(regex_match(str, what, rx))
     {
-        template<typename Sig> struct result {};
-
-        template<typename This, typename Pair>
-        struct result<This(Pair)>
-        {
-            typedef typename remove_reference<Pair>
-                ::type::first_type type;
-        };
-
-        template<typename Pair>
-        typename Pair::first_type
-        operator()(Pair const &p) const
-        {
-            return p.first;
-        }
-    };
+        std::cout << result["aaa"] << '\n';
+        std::cout << result["bbb"] << '\n';
+        std::cout << result["ccc"] << '\n';
+    }
 
-    // OK, use as first(s1) to get the begin iterator
-    // of the sub-match referred to by s1.    
-    function<first_impl> const first = {{}};
+This program displays:
 
-[h3 Late-Bound Variables]
+[pre
+1
+23
+456
+]
 
-TODO describe placeholder<> and match_results<>::let().
+We use `placeholder<>` here to define `_map`, which stands in for a 
+`std::map<>` variable. We can use the placeholder in the semantic action as if
+it were a map. Then, we define a _match_results_ struct and bind an actual map
+to the placeholder with "`what.let( _map = result );`". The _regex_match_ call 
+behaves as if the placeholder in the semantic action had been replaced with a
+reference to `result`.
+
+[note Placeholders in semantic actions are not /actually/ replaced at runtime
+with references to variables. The regex object is never mutated in any way
+during any of the regex algorithms, so they are safe to use in multiple
+threads.]
 
 [h2 User-Defined Assertions]