Semantics tweak: short circuiting behavior for @(all) and @(none).

* match.c (match_files): Added a couple of break statements.

* txr.1: Updated.

3 files changed, 64 insertions, 35 deletions

diff --git a/ChangeLog b/ChangeLog
index 8686ce13..9d2b76b3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2011-09-21  Kaz Kylheku  <kaz@kylheku.com>
+
+	Semantics tweak: short circuiting behavior for @(all) and @(none).
+
+	* match.c (match_files): Added a couple of break statements.
+
+	* txr.1: Updated.
+
 2011-09-22  Kaz Kylheku  <kaz@kylheku.com>
 
 	Version 036
diff --git a/match.c b/match.c
index b75c0766..299246d1 100644
--- a/match.c
+++ b/match.c
@@ -1173,9 +1173,11 @@ repeat_spec_same_data:
                 max_data = new_data;
               }
             }
-            if (sym == cases_s)
+            if (sym == cases_s || sym == none_s)
               break;
           } else {
+            if (sym == all_s)
+              break;
             all_match = nil;
           }
         }
diff --git a/txr.1 b/txr.1
index 57f5f947..78b109cd 100644
--- a/txr.1
+++ b/txr.1
@@ -877,21 +877,28 @@ query line to that string. The newline characters (or custom separators) appear
 explicitly in that string.
 
 .IP @(some)
-Match some clauses in parallel. At least one has to match.
+Multiple clauses are each applied to the same input. Succeeds if at least one
+of the clauses matches the input. The bindings established by earlier
+successful clauses are visible to the later clauses.
 
 .IP @(all)
-Match some clauses in parallel. Each one must match.
+Multiple clauses are applied to the same input. Succeeds if and only if each
+one of the clauses matches. The clauses are applied in sequence, and evaluation stops on the first failure.  The bindings established by earlier
+successful clauses are visible to the later clauses.
 
 .IP @(none)
-Match some clauses in parallel. None must match.
+Multiple clauses are applied to the same input. Succeeds if and only if none of
+them match. The clauses are applied in sequence, and evaluation stops on the
+first success. No bindings are ever produced by this construct.
 
 .IP @(maybe)
-Match some clauses in parallel, which may or may not match.
-No failure occurs if none match.
+Multiple clauses are applied to the same input. No failure occurs if none of
+them match.  The bindings established by earlier successful clauses are visible
+to the later clauses.
 
 .IP @(cases)
-Match some clauses sequentially, stopping if one of them
-matches successfully.
+Multiple clauses are applied to the same input. Evaluation stops on the
+first successful clause.
 
 .IP @(define\ NAME\ (\ ARGUMENTS\ ...))
 Introduces a function. Functions are discussed in the FUNCTIONS section below.
@@ -906,11 +913,11 @@ works within one line.
 A collect is an anonymous block.
 
 .IP @(and)
-Separator of clauses for @(some), @(all), and @(none).
+Separator of clauses for @(some), @(all), @(none), @(maybe) and @(cases).
 Equivalent to @(or). Choice is stylistic.
 
 .IP @(or)
-Separator of clauses for @(some), @(all), and @(none).
+Separator of clauses for @(some), @(all), @(none), @(maybe) and @(cases).
 Equivalent to @(and). Choice is stylistic.
 
 .IP @(end)
@@ -1257,9 +1264,11 @@ Example:
   @(coll)@{token /[^:]*/}:@(end)
   @(end)
 
-.SS The Some, All, None and Maybe directives
+.SS The Some, All, None, Maybe and Cases directives
 
-These directives combine multiple subqueries, which are applied at the same position in parallel. The syntax of all three follows this example:
+These directives, called the parallel directives, combine multiple subqueries,
+which are applied at the same input position, rather than to consecutive input.
+The syntax of the parallel directives follows this example:
 
   @(some)
   subquery1
@@ -1278,11 +1287,12 @@ These directives combine multiple subqueries, which are applied at the same posi
   .
   @(end)
 
-The @(some), @(all) or @(none) directive must appear as the only element in a
-query line. It must be followed by at least one subquery clause, and terminated
-by @(end). If there are two or more subqueries, these additional clauses are
-indicated by @(and) or @(or), which are interchangeable.  The @(and), @(or) and
-@(end) directives also must appear as the only element in a query line.
+The @(some), @(all), @(none), @(maybe) or @(cases) directive must appear as the
+only element in a query line. It must be followed by at least one subquery
+clause, and terminated by @(end). If there are two or more subqueries, these
+additional clauses are indicated by @(and) or @(or), which are interchangeable.
+The separator and terminator directives also must appear as the only element in
+a query line.
 
 The syntax supports arbitrary nesting. For example:
 
@@ -1307,44 +1317,53 @@ line "a dark". The @(some) clause combines the text line "it",
 and a @(none) clause which contains just one clause consisting of
 the line "was".
 
-The semantics of the some, all, none, maybe and cases directives is:
+The semantics of the parallel directives is:
 
 .IP @(all)
 Each of the clauses is matched at the current position. If any of the
 clauses fails to match, the directive fails (and thus does not produce
-any variable bindings).
+any variable bindings). Clauses following the failed directive are not
+evaluated. Bindings extracted by a successful clause are visible the clauses
+which follow, and if the directive succeeds, all of the combined bindings
+emerge.
 
 .IP @(some)
-Each of the clauses is matched at the current position. If any
-of the clauses succeed, the directive succeeds. The bindings from
-all successful clauses are retained.
+Each of the clauses is matched at the current position. If any of the clauses
+succeed, the directive succeeds, retaining the bindings accumulated by the
+successully matching clauses.  Evaluation does not stop on the first successful
+clause. Bindings extracted by a successful clause are visible to the clauses
+which follow.
 
 .IP @(none)
 Each of the clauses is matched at the current position. The
 directive succeeds only if all of the clauses fail. If
-any clause succeeds, the directive fails. Thus, this
-directive never produces variable bindings.
+any clause succeeds, the directive fails, and subsequent clauses are not
+evaluated. Thus, this directive never produces variable bindings, only matching
+success or failure.
 
 .IP @(maybe)
-Each of the clauses is matched at the current position.
-The directive succeeds even if all of the clauses fail.
-Whatever bindings are found in any of the clauses are
-retained.
+Each of the clauses is matched at the current position.  The directive always
+succeeds, even if all of the clauses fail.  Whatever bindings are found in any
+of the clauses are retained. Bindings extracted by any successful clause are
+visible the clauses which follow.
 
 .IP @(cases)
+Each of the clauses is matched at the current position. The
 The clauses are matched, in order, at the current position.
 If any clause matches, the matching stops and the bindings
 collected from that clause are retained. Any remaining clauses
 after that one are not processed. If no clause matches, the
 directive fails, and produces no bindings.
 
-When a @(some), @(all), or @(cases) directive matches successfully, or a
-@(maybe) directive matches in at least one of its clauses, the query advances
-by the greatest number of lines matched in any of the subclauses. For instance
-if there are two subclauses, and one of them matches three lines, but the other
-one matches five lines, then the overall clause is considered to have made a
-five line match at its position. If more directives follow, they begin matching
-five lines down from that position.
+For all of the parallel directives other than @(none), the query advances
+the input position by the greatest number of lines that match
+in any of the successfully matching subclauses that are evaluated.
+The @(none) directive does not advance the input position.
+
+For instance if there are two subclauses, and one of them matches three lines,
+but the other one matches five lines, then the overall clause is considered to
+have made a five line match at its position. If more directives follow, they
+begin matching five lines down from that position.
 
 .SS The Collect Directive