From: Philip Kaludercic <philipk@posteo.net>
Date: Sun, 4 Aug 2024 14:52:38 +0000 (+0200)
Subject: Clarify that 'pcase-lambda' only destructs
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=adb67612c95d9903b069bc8bd22724beeacc1139;p=emacs.git

Clarify that 'pcase-lambda' only destructs

* lisp/emacs-lisp/pcase.el (pcase-lambda): Copy notice from
'pcase-let', indicating that pcase-lambda won't pattern match
like 'pcase', but just try to destruct with uncertain side
effects if this fails. (Bug#71503)

(cherry picked from commit 0756f3085ea948c945e309e2ce347fc5ab836574)
---

diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 5a7f3995311..fd6b0c8db5c 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -241,9 +241,14 @@ not signal an error."
 ;;;###autoload
 (defmacro pcase-lambda (lambda-list &rest body)
   "Like `lambda' but allow each argument to be a pattern.
-I.e. accepts the usual &optional and &rest keywords, but every
-formal argument can be any pattern accepted by `pcase' (a mere
-variable name being but a special case of it)."
+I.e. accepts the usual &optional and &rest keywords, but every formal
+argument can be any pattern destructed by `pcase-let' (a mere variable
+name being but a special case of it).
+
+Each argument should match its respective pattern in the parameter
+list (i.e. be of a compatible structure); a mismatch may signal an error
+or may go undetected, binding arguments to arbitrary values, such as
+nil."
   (declare (doc-string 2) (indent defun)
            (debug (&define (&rest pcase-PAT) lambda-doc def-body)))
   (let* ((bindings ())