From ae97f00ffa51c638c269e8b3e8ee3749be20fa12 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Wed, 20 Jan 2021 07:54:26 -0800
Subject: matcher: bugfix and interface change in @(require).

* share/txr/stdlib/match.tl (compile-require-match): The bug
here is that the condition is placed before the
match.test-expr, which is incorrect. The conditions can only
be evaluated if match.test-expr has succeeded, because
otherwise the variables are not validated to have the
correctly matching value. Also, in the documentation,
the synax insinuates there can be more than one expression. So
let's just make it work: require takes multiple expressions
and combines them with an implicit and.

* txr.1: Documentation updated.
---
 txr.1 | 37 +++++++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 10 deletions(-)

(limited to 'txr.1')

diff --git a/txr.1 b/txr.1
index cde66385..679b91a4 100644
--- a/txr.1
+++ b/txr.1
@@ -39934,7 +39934,7 @@ as its value.
 
 .coNP Pattern operator @ require
 .synb
-.mets @(require < pattern << expression *)
+.mets @(require < pattern << condition *)
 .syne
 .desc
 The pattern operator
@@ -39944,19 +39944,36 @@ applies the specified
 to the corresponding object.
 If the
 .meta pattern
-matches, the operator then imposes the additional conditions specified by
-the extra
-.metn expression .
-The
-.meta expression
+matches, the operator then imposes the additional constraints
+specified by zero or more
+.meta condition
+forms.
+Each
+.meta condition
 is evaluated in a scope in which the variables from
 .meta pattern
 have already been established.
-However, the mach is considered to have succeeded only if
-.meta expression
-yields true. If it yields
+
+For the
+.code require
+operator to be a successful match, every
+.meta condition
+must evaluate true, otherwise the match fails.
+
+The
+.meta condition
+forms behave as if they were the arguments of an implicit
+.code and
+operator, which implies left-to-right evaluation behavior, stopping
+evaluation on the first
+.meta condition
+which produces
 .codn nil ,
-then the match is deemed to have failed.
+and defaulting to a result of
+.code t
+when no
+.meta condition
+forms are specified.
 
 .TP* Examples:
 
-- 
cgit v1.2.3