* bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description @ 2023-12-25 16:01 Drew Adams 2023-12-27 21:47 ` Stefan Kangas 0 siblings, 1 reply; 5+ messages in thread From: Drew Adams @ 2023-12-25 16:01 UTC (permalink / raw) To: 68028 (Minor.) Please consider moving the description of `rx' forms from after the description of SEQPAT forms (`and' and `or'). The scope of the latter description is less clear if `rx' follows the descriptions of `and' and `or' (with no particular separation). IOW, separate the SEQPAT description from the other pattern descriptions better. In GNU Emacs 29.1 (build 2, x86_64-w64-mingw32) of 2023-08-02 built on AVALON Windowing system distributor 'Microsoft Corp.', version 10.0.19045 System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3803) Configured using: 'configure --with-modules --without-dbus --with-native-compilation=aot --without-compress-install --with-tree-sitter CFLAGS=-O2' Configured features: ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB (NATIVE_COMP present but libgccjit not available) ^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description 2023-12-25 16:01 bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description Drew Adams @ 2023-12-27 21:47 ` Stefan Kangas 2023-12-28 10:29 ` Mattias Engdegård 0 siblings, 1 reply; 5+ messages in thread From: Stefan Kangas @ 2023-12-27 21:47 UTC (permalink / raw) To: Drew Adams; +Cc: Mattias Engdegård, 68028 severity 68028 wishlist thanks Drew Adams <drew.adams@oracle.com> writes: > (Minor.) > > Please consider moving the description of `rx' forms from after the > description of SEQPAT forms (`and' and `or'). The scope of the latter > description is less clear if `rx' follows the descriptions of `and' and > `or' (with no particular separation). IOW, separate the SEQPAT > description from the other pattern descriptions better. Mattias, since you added that part, do you have any thoughts? ^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description 2023-12-27 21:47 ` Stefan Kangas @ 2023-12-28 10:29 ` Mattias Engdegård 2023-12-28 15:43 ` Stefan Kangas 0 siblings, 1 reply; 5+ messages in thread From: Mattias Engdegård @ 2023-12-28 10:29 UTC (permalink / raw) To: Stefan Kangas; +Cc: Stefan Monnier, Drew Adams, 68028 [-- Attachment #1: Type: text/plain, Size: 1454 bytes --] 27 dec. 2023 kl. 22.47 skrev Stefan Kangas <stefankangas@gmail.com>: >> Please consider moving the description of `rx' forms from after the >> description of SEQPAT forms (`and' and `or'). The scope of the latter >> description is less clear if `rx' follows the descriptions of `and' and >> `or' (with no particular separation). IOW, separate the SEQPAT >> description from the other pattern descriptions better. > > Mattias, since you added that part, do you have any thoughts? The location of the `rx` pattern description is fine; it's the SEQPAT paragraph that causes trouble as it splits the table into two parts. I suggest we remove that paragraph because it doesn't actually say anything useful at that point; the user can learn how `or` and `and` patterns work without knowing that they are SEQPATs. Actually, I'd hoist those two patterns and reorder them to keep patterns in a rough order of usage: something like pred, guard, or, and, let, app, rx makes more sense -- `pred` and `guard` clearly belong together, `app` is less common than `let`. We could explain SEQPAT in a short sentence somewhere else, either near the beginning of the node or further down in the 'Caveats' subsection. A simple (and probably flawed) patch attached. Stefan M probably has a better sense of how to improve the text. (By the way, the caveat section says that sequencing patterns use `eq` for comparison. Don't they use `eql`?) [-- Attachment #2: seqpat.diff --] [-- Type: application/octet-stream, Size: 3400 bytes --] diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index d4bd8c14ae3..2c0caacbc17 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -640,37 +640,9 @@ pcase Macro the actual function call becomes: @w{@code{(= 42 @var{expval})}}. @end table -@item (app @var{function} @var{pattern}) -Matches if @var{function} called on @var{expval} returns a -value that matches @var{pattern}. -@var{function} can take one of the forms described for @code{pred}, -above. Unlike @code{pred}, however, @code{app} tests the result -against @var{pattern}, rather than against a boolean truth value. - @item (guard @var{boolean-expression}) Matches if @var{boolean-expression} evaluates to non-@code{nil}. -@item (let @var{pattern} @var{expr}) -Evaluates @var{expr} to get @var{exprval} and matches if @var{exprval} -matches @var{pattern}. (It is called @code{let} because @var{pattern} -can bind symbols to values using @var{symbol}.) -@end table - -@cindex sequencing pattern -A @dfn{sequencing pattern} (also known as @var{seqpat}) is a -pattern that processes its sub-pattern arguments in sequence. -There are two for @code{pcase}: @code{and} and @code{or}. -They behave in a similar manner to the special forms -that share their name (@pxref{Combining Conditions}), -but instead of processing values, they process sub-patterns. - -@table @code -@item (and @var{pattern1}@dots{}) -Attempts to match @var{pattern1}@dots{}, in order, until one of them -fails to match. In that case, @code{and} likewise fails to match, and -the rest of the sub-patterns are not tested. If all sub-patterns -match, @code{and} matches. - @item (or @var{pattern1} @var{pattern2}@dots{}) Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order, until one of them succeeds. In that case, @code{or} likewise matches, @@ -685,6 +657,24 @@ pcase Macro variables bound by each sub-pattern. If a variable is not bound by the sub-pattern that matched, then it is bound to @code{nil}. +@item (and @var{pattern1}@dots{}) +Attempts to match @var{pattern1}@dots{}, in order, until one of them +fails to match. In that case, @code{and} likewise fails to match, and +the rest of the sub-patterns are not tested. If all sub-patterns +match, @code{and} matches. + +@item (app @var{function} @var{pattern}) +Matches if @var{function} called on @var{expval} returns a +value that matches @var{pattern}. +@var{function} can take one of the forms described for @code{pred}, +above. Unlike @code{pred}, however, @code{app} tests the result +against @var{pattern}, rather than against a boolean truth value. + +@item (let @var{pattern} @var{expr}) +Evaluates @var{expr} to get @var{exprval} and matches if @var{exprval} +matches @var{pattern}. (It is called @code{let} because @var{pattern} +can bind symbols to values using @var{symbol}.) + @ifnottex @anchor{rx in pcase} @item (rx @var{rx-expr}@dots{}) @@ -881,9 +871,10 @@ pcase Macro @anchor{pcase-symbol-caveats} @subheading Caveats for @var{symbol} in Sequencing Patterns -The preceding examples all use sequencing patterns -which include the @var{symbol} -sub-pattern in some way. +@cindex sequencing pattern +The preceding examples all use @dfn{sequencing patterns} +(@code{and} and @code{or} patterns) +which include the @var{symbol} sub-pattern in some way. Here are some important details about that usage. @enumerate ^ permalink raw reply related [flat|nested] 5+ messages in thread
* bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description 2023-12-28 10:29 ` Mattias Engdegård @ 2023-12-28 15:43 ` Stefan Kangas 2023-12-28 17:29 ` Drew Adams 0 siblings, 1 reply; 5+ messages in thread From: Stefan Kangas @ 2023-12-28 15:43 UTC (permalink / raw) To: Mattias Engdegård; +Cc: Stefan Monnier, Drew Adams, 68028 Mattias Engdegård <mattiase@acm.org> writes: > I suggest we remove that paragraph because it doesn't actually say > anything useful at that point; the user can learn how `or` and `and` > patterns work without knowing that they are SEQPATs. Actually, I'd > hoist those two patterns and reorder them to keep patterns in a rough > order of usage: something like > > pred, guard, or, and, let, app, rx > > makes more sense -- `pred` and `guard` clearly belong together, `app` > is less common than `let`. > > We could explain SEQPAT in a short sentence somewhere else, either > near the beginning of the node or further down in the 'Caveats' > subsection. A simple (and probably flawed) patch attached. > > Stefan M probably has a better sense of how to improve the text. (By > the way, the caveat section says that sequencing patterns use `eq` for > comparison. Don't they use `eql`?) Makes sense to me. Perhaps your patch could be installed first, and then we can take it from there. ^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description 2023-12-28 15:43 ` Stefan Kangas @ 2023-12-28 17:29 ` Drew Adams 0 siblings, 0 replies; 5+ messages in thread From: Drew Adams @ 2023-12-28 17:29 UTC (permalink / raw) To: Stefan Kangas, Mattias Engdegård Cc: Stefan Monnier, 68028@debbugs.gnu.org You might as well make this bug "wont-fix", like the others you closed for this node. The whole section, particularly this node, needs a rewrite and reorg. Ignoring that doesn't help users. Tried to guide you a bit - sorry for wasting all of our time. Other `Pattern-Matching Conditional' nodes are less problematic. The most useful, particularly for users unfamiliar with pattern-matching constructs, is the _last_ in the section, `Destructuring with pcase Patterns'. ___ (But whaddo I know? I've only been writing and managing developer docs professionally for 50 years. I've only been familiar with FP/LP/constraint pattern-matching languages for 40 years. Still I try to help out here a bit - silly me.) ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-12-28 17:29 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2023-12-25 16:01 bug#68028: 29.1; (elisp) `pcase Macro': move `rx' before SEQPAT description Drew Adams 2023-12-27 21:47 ` Stefan Kangas 2023-12-28 10:29 ` Mattias Engdegård 2023-12-28 15:43 ` Stefan Kangas 2023-12-28 17:29 ` Drew Adams
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.