matcher: left-to-right scoping for @(and).

And binds left to right now; only or is parallel.

* share/txr/stdlib/match.tl (compile-and-mach): Do not compile
the patterns with copies of the var list, but with he one and
only incoming var-list. Consequently, there are not var lists
to merge. par-pat parameter renamed to and-pat.

* txr.1: Improve and/or documentation, clarifying scope
rules. Also, clarify that variables in non-matching patterns
of an or are no set to nil, if they are existing bindings from
before the or.

2 files changed, 33 insertions, 26 deletions

diff --git a/share/txr/stdlib/match.tl b/share/txr/stdlib/match.tl
index ea0134fc..f99a8fe6 100644
--- a/share/txr/stdlib/match.tl
+++ b/share/txr/stdlib/match.tl
@@ -446,15 +446,11 @@
            obj-var obj-var
            guard-chain (list dj-guard)))))
 
-(defun compile-and-match (par-pat obj-var var-list)
-  (mac-param-bind *match-form* (op . pats) par-pat
-    (let* ((var-lists (mapcar (ret (copy var-list)) pats))
-           (par-matches (mapcar (op compile-match @1 obj-var @2)
-                                pats var-lists)))
-      (each ((vl var-lists))
-        var-list.(merge vl))
+(defun compile-and-match (and-pat obj-var var-list)
+  (mac-param-bind *match-form* (op . pats) and-pat
+    (let* ((par-matches (mapcar (lop compile-match obj-var var-list) pats)))
       (new compiled-match
-           pattern par-pat
+           pattern and-pat
            obj-var obj-var
            guard-chain (mappend .guard-chain par-matches)))))
 
diff --git a/txr.1 b/txr.1
index e54097bf..762e886c 100644
--- a/txr.1
+++ b/txr.1
@@ -40307,15 +40307,11 @@ operator succeeds if
 .meta pattern
 matches.
 
-Note: the
-.code and
-operator can be used to bind a variable to an object, with back-referencing, in
-parallel with other patterns which also match the object. However, all of the
-elements of
-.code and
-are in separate scopes; back-referencing among branches of an
+Note: in a situation when it is necessary to bind a variable to an object
+in parallel with one or more patterns, such that the variable can back-reference
+to an existing occurrence, the
 .code and
-isn't possible.
+pattern operator can be used.
 
 .TP* Example:
 
@@ -40598,24 +40594,39 @@ operator requires one
 to match. It tries the patterns in left to right order, and
 stops at the first matching one, declaring failure if none match.
 
+The
+.code and
+and
+.code or
+operators have different scoping rules.
+Under
+.codn and ,
+later patterns are processed in the scopes of earlier patterns,
+just like with other pattern operators. Duplicate variables
+back-reference.
+Under
+.codn or ,
+the patterns are processed in separate, parallel scopes.
+No back-referencing takes place among same-named variables
+introduced in separate patterns of the same
+.codn or .
+
 When the
 .code and
 matches, the variables from all of the
-patterns are bound.  Duplicate variables from multiple patterns are merged into
-a single instance. The rightmost occurrence of a variable takes precedence; its
-value is the one that appears.
-
+patterns are bound.
 When the
 .code or
 operator matches, the variables from all of the patterns
-are bound.
-The variables from the matching
+are also bound. However, only the variables from the matching
 .meta pattern
 take on the values implied by that pattern.
-The variables from the non-matching patterns that are not
-duplicates of variables in the matching
-.meta pattern
-take on
+The variables from the non-matching patterns that do not have
+the same names as variables in the matching
+.metn pattern ,
+and that have been newly introduced in the
+.code or
+operator, take on
 .code nil
 values.