Subject: Documentation and behavior differ for match (not ...) pattern

From: "Jakub Wojciech" <[email-masked]>
Date: Fri, 23 Jul 2021 11:45:34 +0200

The documentation states:
> (not pat_1 ... pat_n)           if all pat_1 thru pat_n don't match

The code only implements (not pat), for a singular pattern, e.g:
  (match 2
    ((not 1) 'not-one)
    (1 'one)
    (2 'two))
  => not-one

According to the documentation this should work, but the result is erroneous:
  (match 3
    ((not 1 2) 'not-one-nor-two)
    (1 'one)
    (2 'two)
    (3 'three))
  => three

So it fails silently.

RhodiumToad on #guile proposed the simple fix that I took a liberty of
attaching to this message.
It adds a clause for (not ...), delegating it to 'or': (not (or ...)).

However RhodiumToad also raised another issue: is the code wrong or is
the documentation wrong?

The documentation in the file itself states:
> The 'not' operator succeeds if the given pattern doesn't match.
The test from upstream also only checks for the singular pattern inside
the 'not' clause.
This means that the idea behind this code is to allow one and only one
pattern.

Although I lean towards fixing the code to match the Guile's
documentation (i.e. applying the attached patch), I also wonder about
the relation with the upstream - Chibi Scheme.
There are three possibilities:
1. Diverge from their implementation.
2. Try to convince them to apply that patch too.
3. Make passing more than one pattern to 'not' clause a syntax error and
   changing the info manual documentation.

The question is: which one do we want to choose?

The rationale for not selecting option 3 is the fact that the change is
non-breaking, adds a functionality, and conforms to both SRFI-200 and
SRFI-204 drafts and the original Wright-Duba paper.

diff --git a/module/ice-9/match.upstream.scm b/module/ice-9/match.upstream.scm
index b1fc371b8..f12981cb3 100644
--- a/module/ice-9/match.upstream.scm
+++ b/module/ice-9/match.upstream.scm
@@ -115,7 +115,7 @@
 ;;> @example{(match 1 ((or x) x))}
 ;;> @example{(match 1 ((or x 2) x))}
 
-;;> The @scheme{not} operator succeeds if the given pattern doesn't
+;;> The @scheme{not} operator succeeds if none of the given patterns
 ;;> match.  None of the identifiers used are available in the body.
 
 ;;> @example{(match 1 ((not 2) #t))}
@@ -355,6 +355,8 @@
      (match-extract-vars (or p ...) (match-gen-or v (p ...) g+s sk fk i) i ()))
     ((match-two v (not p) g+s (sk ...) fk i)
      (match-one v p g+s (match-drop-ids fk) (sk ... i) i))
+    ((match-two v (not p ...) g+s (sk ...) fk i)
+     (match-two v (not (or p ...)) g+s (sk ...) fk i))
     ((match-two v (get! getter) (g s) (sk ...) fk i)
      (let ((getter (lambda () g))) (sk ... i)))
     ((match-two v (set! setter) (g (s ...)) (sk ...) fk i)