[Boost-commit] svn:boost r67286 - trunk/libs/spirit/doc/karma

Subject: [Boost-commit] svn:boost r67286 - trunk/libs/spirit/doc/karma
From: hartmut.kaiser_at_[hidden]
Date: 2010-12-17 13:33:14

Author: hkaiser
Date: 2010-12-17 13:33:11 EST (Fri, 17 Dec 2010)
New Revision: 67286
URL: http://svn.boost.org/trac/boost/changeset/67286

Log:
Spirit: fixing docs
Text files modified: 
   trunk/libs/spirit/doc/karma/string.qbk |    46 +++++++++++++++++++++++++++++++++++++++ 
   1 files changed, 45 insertions(+), 1 deletions(-)

Modified: trunk/libs/spirit/doc/karma/string.qbk
==============================================================================
--- trunk/libs/spirit/doc/karma/string.qbk	(original)
+++ trunk/libs/spirit/doc/karma/string.qbk	2010-12-17 13:33:11 EST (Fri, 17 Dec 2010)
@@ -266,7 +266,51 @@
 
 [heading Attributes]
 
-The attribute of `symbol<Attrib, T>` is `Attrib`.
+The attribute of `symbol<Attrib, T>` is `Attrib`. 
+
+If the supplied attribute is a __fusion__ sequence, then the symbol table 
+generator will use the first element of that __fusion__ sequence as the key 
+to be used for lookup. The type of that first element needs to be convertible 
+to `Attrib`. In this case the second element of the __fusion__ sequence is used
+as the attribute while calling a generator derived from the value stored in the 
+symbol table for the found entry.
+
+If the supplied attribute is a container type (__customize_is_container__ 
+resolves to `mpl::true_`), then the symbol table generator will use the first 
+element stored in that container as the key to be used for lookup. The 
+`value_type` (returned by __customize_container_value__) has to be convertible 
+to `Attrib`. In this case the second element stored in that container is used
+as the attribute while calling a generator derived from the value stored in the 
+symbol table for the found entry.
+
+If the supplied attribute is not a __fusion__ sequence and not a container
+type, the supplied attribute is directly used as the key for item lookup. The
+attribute is used as the attribute while calling a generator derived from the 
+value stored in the symbol table for the found entry.
+
+In any case, because the supplied key (i.e. either the first element of the 
+__fusion__ sequence, the first container element, or the attribute otherwise)
+is passed as the attribute to a generator derived from the value
+stored in the symbol table for the found entry, the symbol table may store 
+generators, which will produce output based on that value. For instance:
+
+    // The symbol table maps a single character key to a rule<>
+    // The rule<> exposes an attribute of char as well
+    rule<output_iterator_type, char()> r1 = char_;
+        
+    symbols<char, rule<output_iterator_type, char()> > sym;
+    sym.add
+        ('j', r1.alias())
+        ('h', r1.alias())
+        ('t', r1.alias())
+        ('k', r1.alias())
+    ;
+
+    // Supplying a fusion vector as the attribute will use the first element
+    // (the 'j') as the key to be looked up, while the second element (the 'J') 
+    // is passed on as the attribute to the rule<> stored in the symbol table. 
+    // Consequently, the example generates a single 'J'.
+    BOOST_ASSERT(test("J", sym, make_vector('j', 'J')));
 
 [heading Complexity]