From: Stefan Monnier <monnier@IRO.UMontreal.CA>
To: Thien-Thi Nguyen <ttn@gnu.org>
Cc: emacs-devel@gnu.org
Subject: EXPVAL in pcase-defmacro docstrings
Date: Wed, 30 May 2018 08:28:29 -0400 [thread overview]
Message-ID: <jwvfu29xs2s.fsf-monnier+emacs@gnu.org> (raw)
I think this change is misguided:
- When reading source code, you get things like:
(pcase-defmacro radix-tree-leaf (vpat)
"Build a `pcase' pattern that matches radix-tree leaf EXPVAL.
VPAT is a `pcase' pattern to extract the value."
where the EXPVAL comes out of nowhere
- The wording "matches radix-tree leaf EXPVAL" makes it sound like the
reader is already familiar with EXPVAL and that we know already that
it's a radix-tree leaf, whereas the pattern will have to check if
EXPVAL is such a leaf.
- In the pcase docstring, EXPVAL refers to the "toplevel" value, so when
we say things like
'VAL matches if EXPVAL is `equal' to VAL.
it makes it sound like
(cons '1 '2)
will not match against the value (1 . 2) because EXPVAL is (1 . 2) and
'1 is not `equal` to (1 . 2).
- The "standard" way to describe a pattern is to say things like
(fumble-tree E1 E2) matches fumble-trees
E.g.
_ matches anything
SYMBOL matches anything and binds it to SYMBOL.
(guard BOOLEXP) matches if BOOLEXP evaluates to non-nil.
(let PAT EXPR) matches if EXPR matches PAT.
(and PAT...) matches if all the patterns match.
(or PAT...) matches if any of the patterns matches.
While it may occasionally be handy to be able to refer to EXPVAL,
for example in
(app FUN PAT) matches if FUN called on EXPVAL matches PAT.
I believe the standard terminology is to say "the target" instead of
EXPVAL.
For example, I think the patch below would improve the doc.
Stefan
diff --git a/lisp/emacs-lisp/radix-tree.el b/lisp/emacs-lisp/radix-tree.el
index 2491ccea95..6a11977782 100644
--- a/lisp/emacs-lisp/radix-tree.el
+++ b/lisp/emacs-lisp/radix-tree.el
@@ -196,8 +196,8 @@ radix-tree-prefixes
(eval-and-compile
(pcase-defmacro radix-tree-leaf (vpat)
- "Build a `pcase' pattern that matches radix-tree leaf EXPVAL.
-VPAT is a `pcase' pattern to extract the value."
+ "Pattern which matches a radix-tree leaf.
+The pattern VPAT is matched against the leaf's carried value."
;; FIXME: We'd like to use a negative pattern (not consp), but pcase
;; doesn't support it. Using `atom' works but generates sub-optimal code.
`(or `(t . ,,vpat) (and (pred atom) ,vpat))))
diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index fa7b1de8b4..0ba0d75776 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -119,7 +119,7 @@ pcase
PATTERN matches. PATTERN can take one of the forms:
_ matches anything.
- \\='VAL matches if EXPVAL is `equal' to VAL.
+ \\='VAL matches objects `equal' to VAL.
KEYWORD shorthand for \\='KEYWORD
INTEGER shorthand for \\='INTEGER
STRING shorthand for \\='STRING
next reply other threads:[~2018-05-30 12:28 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-05-30 12:28 Stefan Monnier [this message]
2018-05-31 14:56 ` EXPVAL in pcase-defmacro docstrings Thien-Thi Nguyen
2018-06-04 14:43 ` Stefan Monnier
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=jwvfu29xs2s.fsf-monnier+emacs@gnu.org \
--to=monnier@iro.umontreal.ca \
--cc=emacs-devel@gnu.org \
--cc=ttn@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.