GNU bug report logs - #70510
Small documentation error for case-lambda*

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 22 Apr 2024 06:51:34 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Apr 22 02:51:34 2024
Received: from localhost ([127.0.0.1]:45558 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rynWW-0005NE-Jt
	for submit <at> debbugs.gnu.org; Mon, 22 Apr 2024 02:51:34 -0400
Received: from lists.gnu.org ([2001:470:142::17]:37832)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <jeremy@HIDDEN>) id 1ryZkf-00071D-4Y
 for submit <at> debbugs.gnu.org; Sun, 21 Apr 2024 12:09:15 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <jeremy@HIDDEN>)
 id 1ryZkK-0007hu-Ac
 for bug-guile@HIDDEN; Sun, 21 Apr 2024 12:08:52 -0400
Received: from sender4-op-o11.zoho.com ([136.143.188.11])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <jeremy@HIDDEN>)
 id 1ryZkI-00043G-9C
 for bug-guile@HIDDEN; Sun, 21 Apr 2024 12:08:52 -0400
ARC-Seal: i=1; a=rsa-sha256; t=1713715725; cv=none; 
 d=zohomail.com; s=zohoarc; 
 b=Ej8NWD3QznyQ/IZRR1dCkRK2qAJqEDIqr66LFh1k92KHDf12FXuePnU+ml5mmp6racncxhqFpjr7yzl/Gs2w7DEYl4qAnqhY7Wq9CAtFwHbE5sv+VVVTb4yE5HOg0Vv79rlT1Aq8dOk6zXF1niukOQfcBCoZBHaAF4MThEja7OA=
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com;
 s=zohoarc; t=1713715725;
 h=Content-Type:Content-Transfer-Encoding:Date:Date:From:From:MIME-Version:Message-ID:Subject:Subject:To:To:Message-Id:Reply-To:Cc;
 bh=rW+l4G9NUFUlIZQGNCYW6G9GWMRtvsp8hOKG6ig01Lw=; 
 b=ELkUhHb7M37U96q9KoaDiQDrTlJy7DUdP+fdoLYqhSyoGkdRUkCnxBvAFgW+1I7qkNSjvHLUfpaVHWV6Z1jrBhpspUkYWZmk4TObbhlkNj/8Buoke8No3udML7wB++85kR7VhJqJ0SpgxaM6On+XDvJSoGtstYfPQUFomJ01jPI=
ARC-Authentication-Results: i=1; mx.zohomail.com;
 dkim=pass  header.i=sporktania.com;
 spf=pass  smtp.mailfrom=jeremy@HIDDEN;
 dmarc=pass header.from=<jeremy@HIDDEN>
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1713715725; 
 s=zoho; d=sporktania.com; i=jeremy@HIDDEN;
 h=Date:Date:From:From:To:To:Message-ID:In-Reply-To:Subject:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding:Message-Id:Reply-To:Cc;
 bh=rW+l4G9NUFUlIZQGNCYW6G9GWMRtvsp8hOKG6ig01Lw=;
 b=fJ83e3GQVYMOeBhEhoDlAmNqQ41eg3QboHl7lObqhkSpLPkBdveORXigVcZjALOS
 RFt/dMkp32ivsxWR0Qa52naV9iCAbiGQJD24fkVNwYbPsnmTOz6g/hbSM5ELqBTMduO
 Ln56YUtaGgNIVjU+s4ttZXa0O7fFqoJ+8L83N5Ig=
Received: from mail.zoho.com by mx.zohomail.com
 with SMTP id 1713715718741811.1397100889144;
 Sun, 21 Apr 2024 09:08:38 -0700 (PDT)
Date: Sun, 21 Apr 2024 12:08:38 -0400
From: jeremy <jeremy@HIDDEN>
To: "bug-guile" <bug-guile@HIDDEN>
Message-ID: <18f016aaa0d.dbf246a52699947.6437033605540521566@HIDDEN>
In-Reply-To: 
Subject: Small documentation error for case-lambda*
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Importance: Medium
User-Agent: Zoho Mail
X-Mailer: Zoho Mail
Received-SPF: pass client-ip=136.143.188.11;
 envelope-from=jeremy@HIDDEN; helo=sender4-op-o11.zoho.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
 RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01,
 SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: submit
X-Mailman-Approved-At: Mon, 22 Apr 2024 02:51:31 -0400
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.0 (/)

Hi,
I've been familiarizing myself with scheme and guile by haphazardly reading=
 documentation and experimenting, and I believe I have found an error in th=
e docs here: https://www.gnu.org/software/guile/manual/html_node/Case_002dl=
ambda.html

The example at the bottom of the page reads as follows:
(define f
  (case-lambda*
    ((a #:optional b) 'clause-1
    ((a #:optional b #:key c) 'clause-2)
    ((a #:key d) 'clause-3)
    ((#:key e #:rest f) 'clause-4)))

(f) =E2=87=92 clause-4
(f 1) =E2=87=92 clause-1
(f) =E2=87=92 clause-4
(f #:e 10) clause-1
(f 1 #:foo) clause-1
(f 1 #:c 2) clause-2
(f #:a #:b #:c #:d #:e) clause-4

;; clause-2 will match anything that clause-3 would match.
(f 1 #:d 2) =E2=87=92 error: bad keyword args in clause 2

However, the penultimate example=C2=A0`(f #:a #:b #:c #:d #:e)` does not ap=
pear to match clause 4 at all when I try it at the guile REPL, and I'm not =
sure how it ever could have. I believe it is matching `clause-2`, binding `=
a` to `#:a`, `b` to `#f`, and treating the last 4 parameters as keyword arg=
uments matching #:b and #:d - I get an "Unrecognized keyword: #:b" error.

Perhaps a more useful example definition would be:

(define f
  (case-lambda*
    ((a #:optional b) (list 'clause-1 a b))
    ((a #:optional b #:key c) (list 'clause-2 a b c))
    ((a #:key d) (list 'clause-3 a d))
    ((#:key e #:rest f) (list 'clause-4 e f))))

as it reveals not only which clause is matched but what the bindings end up=
 as, making it more clear _how_ it matched. For example, the last example a=
lludes to the fact that interaction between #:optional and #:key arguments =
can be surprising, but it's much clearer with a working example:

(f) =E2=87=92 (clause-4 #f ())
(f 1) =E2=87=92 (clause-1 1 #f)
(f #:e 10) =E2=87=92 (clause-1 #:e 10)
(f 1 #:foo) =E2=87=92 (clause-1 1 #:foo)
(f 1 #:c 2) =E2=87=92 (clause-2 1 #f 2)
(f #:a 2 #:c #;d)  =E2=87=92 (clause-2 #:a 2 #:d)
(f 1 2 3 #:e 4) =E2=87=92 (clause-4 5 (1 2 3 #:e 4))

;; clause-2 will match anything that clause-3 would match.
(f 1 #:d 2) =E2=87=92 error: unrecognized keyword #:d in clause 2

;; clause-2 will also match many things that you might expect clause-4 to m=
atch
(f #:e 1 2 3 4) =E2=87=92 (clause-4 1 (#:e 1 2 3 4))
(f 1 #:e 2 3 4) =E2=87=92 Unrecognized keyword: #:e
(f 1 2 #:e 3 4) =E2=87=92 Unrecognized keyword: #:e
(f 1 2 3 #:e 4) =E2=87=92 (clause-4 4 (1 2 3 #:e 4))

Anyway, hope this is helpful! I'm finding the docs very good in general.

Thanks,
Jeremy