GNU logs - #70510, boring messages

Message sent to bug-guile@HIDDEN:

Subject: bug#70510: Small documentation error for case-lambda*
Resent-From: jeremy <jeremy@HIDDEN>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
Resent-CC: bug-guile@HIDDEN
Resent-Date: Mon, 22 Apr 2024 06:52:03 +0000
Resent-Message-ID: <handler.70510.B.171376869420674 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: 70510 <at> debbugs.gnu.org
Date: Sun, 21 Apr 2024 12:08:38 -0400
From: jeremy <jeremy@HIDDEN>
Message-ID: <18f016aaa0d.dbf246a52699947.6437033605540521566@HIDDEN>
In-Reply-To: 
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Importance: Medium
User-Agent: 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-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

Message sent:

Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-Mailer: MIME-tools 5.505 (Entity 5.505)
Content-Type: text/plain; charset=utf-8
X-Loop: help-debbugs@HIDDEN
From: help-debbugs@HIDDEN (GNU bug Tracking System)
To: jeremy <jeremy@HIDDEN>
Subject: bug#70510: Acknowledgement (Small documentation error for
 case-lambda*)
Message-ID: <handler.70510.B.171376869420674.ack <at> debbugs.gnu.org>
References: <18f016aaa0d.dbf246a52699947.6437033605540521566@HIDDEN>
X-Gnu-PR-Message: ack 70510
X-Gnu-PR-Package: guile
Reply-To: 70510 <at> debbugs.gnu.org
Date: Mon, 22 Apr 2024 06:52:04 +0000

Thank you for filing a new bug report with debbugs.gnu.org.

This is an automatically generated reply to let you know your message
has been received.

Your message is being forwarded to the package maintainers and other
interested parties for their attention; they will reply in due course.

Your message has been sent to the package maintainer(s):
 bug-guile@HIDDEN

If you wish to submit further information on this problem, please
send it to 70510 <at> debbugs.gnu.org.

Please do not send mail to help-debbugs@HIDDEN unless you wish
to report a problem with the Bug-tracking system.

--=20
70510: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D70510
GNU Bug Tracking System
Contact help-debbugs@HIDDEN with problems

Last modified: Mon, 22 Apr 2024 07:00:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.