[Boost-commit] svn:boost r73087 - trunk/libs/spirit/doc/qi

Subject: [Boost-commit] svn:boost r73087 - trunk/libs/spirit/doc/qi
From: joel_at_[hidden]
Date: 2011-07-13 19:29:38

Author: djowel
Date: 2011-07-13 19:29:37 EDT (Wed, 13 Jul 2011)
New Revision: 73087
URL: http://svn.boost.org/trac/boost/changeset/73087

Log:
Added notes from Rob Stewart
Text files modified: 
   trunk/libs/spirit/doc/qi/operator.qbk |    28 ++++++++++++++++++++++------            
   1 files changed, 22 insertions(+), 6 deletions(-)

Modified: trunk/libs/spirit/doc/qi/operator.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/operator.qbk	(original)
+++ trunk/libs/spirit/doc/qi/operator.qbk	2011-07-13 19:29:37 EDT (Wed, 13 Jul 2011)
@@ -20,7 +20,7 @@
 This module includes different parsers which get instantiated if one of
 the overloaded operators is used with more primitive parser constructs.
 It includes Alternative (`|`), And-predicate (unary `&`), Difference
-(`-`), Expect (`>`), Kleene star (unary `*`), Lists (`%`), Not-predicate (`!`), 
+(`-`), Expect (`>`), Kleene star (unary `*`), Lists (`%`), Not-predicate (`!`),
 Optional (unary `-`), Permutation (`^`), Plus (unary
 `+`), Sequence (`>>`), and Sequential-Or (`||`).
 
@@ -96,9 +96,9 @@
 a: A, b: A --> (a | b): A``]]
 ]
 
-[note Alternative parsers do not roll back changes made to the outer attribute 
-      because of a failed alternative. If you need to enforce that only the 
-      succeeded alternative changes the outer attribute please utilize the 
+[note Alternative parsers do not roll back changes made to the outer attribute
+      because of a failed alternative. If you need to enforce that only the
+      succeeded alternative changes the outer attribute please utilize the
       directive __qi_hold__`[]`.]
 
 [heading Complexity]
@@ -127,7 +127,7 @@
 
 Syntactic predicates assert a certain conditional syntax to be satisfied
 before evaluating another production. Similar to semantic predicates,
-__qi_eps__, syntactic predicates do not consume any input. The /and-predicate/, 
+__qi_eps__, syntactic predicates do not consume any input. The /and-predicate/,
 `&a`, is a positive syntactic predicate that returns a zero
 length match only if its predicate matches.
 
@@ -248,6 +248,22 @@
 
 [heading Description]
 
+There are occasions in which it is expected that the input must match a
+particular parser or the input is invalid. Such cases generally arise
+after matching a portion of a grammar, such that the context is fully
+known. In such a situation, failure to match should result in an
+exception. For example, when parsing an e-mail address, after matching a
+name and "@" there must be a domain name or the address is invalid.
+
+The expectation operator (>) requires that the following parser match
+the input or an exception is emitted. Using on_error(), that exception
+can be handled by calling a handler with the context at which the
+parsing failed can be reported.
+
+By contrast, the follows operator (>>) does not require that the
+following parser match the input, which allows for backtracking or
+simply returning false from the parse() function with no exceptions.
+
 Like the __qi_sequence__, the expectation operator, `a > b`, parses two or
 more operands (`a`, `b`, ... etc.), in sequence:
 
@@ -465,7 +481,7 @@
 
 Syntactic predicates assert a certain conditional syntax to be satisfied
 before evaluating another production. Similar to semantic predicates,
-__qi_eps__, syntactic predicates do not consume any input. The /not-predicate/, 
+__qi_eps__, syntactic predicates do not consume any input. The /not-predicate/,
 `!a`, is a negative syntactic predicate that returns a zero
 length match only if its predicate fails to match.