matcher: rearrange match order of @(with).

The @(with side-pat expr main-pat) syntax becomes
@(with main-pat side-pat expr), which is more useful.
Also, the main-pat can be omitted.

* share/txr/stdlib/match.tl (compile-with-match): Recognize
two forms of the syntax: two argument form with main-pat
omitted and the full form. In the full form, main-pat is
on the left now and processed first, so we have to rearrange
the compilation and integration order.

* tests/011/patmatch.tl: Existing tests updated. Two-argument
test added.

* txr.1: Updated.

1 files changed, 22 insertions, 10 deletions

diff --git a/txr.1 b/txr.1
index 9aa0dbb1..74359b7c 100644
--- a/txr.1
+++ b/txr.1
@@ -40288,12 +40288,12 @@ as its value.
 
 .coNP Pattern operator @ with
 .synb
-.mets @(with >> [ side-pattern | << name ] < expr << main-pattern )
+.mets @(with <> [ main-pattern ] >> { side-pattern | << name } << expr )
 .syne
 .desc
 The
 .code with
-pattern operator matches the
+pattern operator matches the optional
 .meta main-pattern
 against a corresponding object, while matching a
 .meta side-pattern
@@ -40303,15 +40303,27 @@ against the value of the expression
 .meta expr
 which is embedded in the syntax.
 
+First, if
+.meta main-pattern
+is present in the syntax,
+it is matched its corresponding object. This match must
+succeed, or else the
+.code with
+operator fails to match.
 
-First,
+Next,
 .meta expr
-is evaluated in the scope of earlier pattern variables. It is unspecified
-whether later pattern variables are visible. The matching of
+is evaluated in the scope of earlier pattern variables, including any
+which that emanate from
+.metn main-pattern .
+It is unspecified
+whether later pattern variables are visible.
+
+Finally,
 .meta side-pattern
-follows, and if that succeeds, then the matching of
-.meta main-pattern
-against the corresponding object takes place.
+is matched against the value of
+.metn expr .
+If that succeeds, then the operator has successfully matched.
 
 If a
 .meta name
@@ -40323,11 +40335,11 @@ it must be a bindable symbol or else
 .TP* Examples:
 
 .verb
-  (when-match (@(with x 42 @a) @b @c) '(1 2 3) (list a b c x))
+  (when-match (@(with @a x 42) @b @c) '(1 2 3) (list a b c x))
   --> (1 2 3 42)
 
   (let ((o 3))
-    (when-match (@(evenp x) @(with @(oddp y) o @z)) '(4 6)
+    (when-match (@(evenp x) @(with @z @(oddp y) o)) '(4 6)
       (list x y z)))
   --> (4 3 6)
 .brev