GNU bug report logs - #20642
24.5; Please improve documentation for `pcase'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 20642 in the body.
You can then email your comments to 20642 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; Please improve documentation for `pcase'
Date: Sun, 24 May 2015 12:34:06 +0200

Quoting the documentation of `pcase', some comments inline.

   Perform ML-style pattern matching on EXP.

Users are probably not aware what 'ML-style pattern matching' is.
Please add an introduction without referring to ML.

   CASES is a list of elements of the form (UPATTERN CODE...).

Please document the motivation for the existence and nomenclature or
UPatterns and QPatterns.

    UPatterns can take the following forms:
      _		matches anything.
      SELFQUOTING	matches itself.  This includes keywords,
                        numbers, and strings.

Please add exhaustive information about all the cases covered by the
SELFQUOTING form.  What kinds of forms does it comprise?  There is
overlap with the SYMBOL case below, which has very different semantics,
so the distinction should be made as clear as possible.  Please include
information about the very common symbols nil and t.

      SYMBOL	matches anything and binds it to SYMBOL.

Please state explicitly in which cases this form applies.  Given that _
and :foo are also symbols, it is clear that it doesn't apply to all
symbols.  Something like "all symbols except _, keywords, nil or t"?

      (or UPAT...)	matches if any of the patterns matches.
      (and UPAT...)	matches if all the patterns match.

In the `and' form, please give and example for the following very common
but non-obvious form:

(and UPAT SYMBOL)

e.g. (and (pred integerp) myvar), meaning to bind to a symbol only if
some guard expression matches.




In GNU Emacs 24.5.1 (x86_64-apple-darwin14.1.0, NS apple-appkit-1344.72)
 of 2015-04-12 on p
Configured using:
 `configure --prefix=/usr/local/Cellar/emacs/24.5
 --enable-locallisppath=/usr/local/share/emacs/site-lisp
 --infodir=/usr/local/Cellar/emacs/24.5/share/info/emacs
 --with-file-notification=gfile --with-dbus --with-gnutls --with-rsvg
 --with-imagemagick --without-popmail --with-ns
 --disable-ns-self-contained'

Important settings:
  value of $LANG: de_DE.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Emacs-Lisp

Minor modes in effect:
  tooltip-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent messages:

Mark set
Sending...
Mark set [2 times]
Sending via mail...
Sending email 
Sending email done
gnutls.c: [0] (Emacs) fatal error: The TLS connection was non-properly terminated.
Sending...done


Load-path shadows:
None found.

Features:
(eieio-opt speedbar sb-image ezimage dframe find-func gnutls
network-stream starttls tls mailalias smtpmail auth-source eieio
byte-opt bytecomp byte-compile cl-extra cconv eieio-core password-cache
cus-edit cus-start cus-load wid-edit cl-loaddefs cl-lib help-mode pp
shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
easymenu mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils warnings help-fns files-x xterm time-date
tooltip electric uniquify ediff-hook vc-hooks lisp-float-type mwheel
ns-win tool-bar dnd fontset image regexp-opt fringe tabulated-list
newcomment lisp-mode prog-mode register page menu-bar rfn-eshadow timer
select scroll-bar mouse jit-lock font-lock syntax facemenu font-core
frame cham georgian utf-8-lang misc-lang vietnamese tibetan thai
tai-viet lao korean japanese hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese case-table epa-hook jka-cmpr-hook help
simple abbrev minibuffer nadvice loaddefs button faces cus-face macroexp
files text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote make-network-process
dbusbind gfilenotify cocoa ns multi-tty emacs)

Memory information:
((conses 16 118129 9719)
 (symbols 48 21487 0)
 (miscs 40 54 289)
 (strings 32 20379 5134)
 (string-bytes 1 568058)
 (vectors 16 11343)
 (vector-slots 8 377405 5190)
 (floats 8 77 427)
 (intervals 56 665 100)
 (buffers 960 19))

Message #10 received at 20642 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 20642 <at> debbugs.gnu.org
Subject: Re: bug#20642: 24.5; Please improve documentation for `pcase'
Date: Sun, 24 May 2015 22:08:20 -0400

>       SELFQUOTING	matches itself.  This includes keywords,
>                         numbers, and strings.
> Please add exhaustive information about all the cases covered by the
> SELFQUOTING form.

Actually, it says it right there: keywords, numbers, and strings.
Admittedly, it doesn't say it's exhaustive (partly because this set
could be expanded in the future, tho at this point it seems unlikely).

>       SYMBOL	matches anything and binds it to SYMBOL.
> Please state explicitly in which cases this form applies.  Given that _
> and :foo are also symbols, it is clear that it doesn't apply to all
> symbols.  Something like "all symbols except _, keywords, nil or t"?

Keywords can't be bound since their value is constant.  Same for nil
and t.  So that should be "obvious enough".  As for _ I think it should
also be obvious enough that between a rule "for _" and rule for "SYMBOL"
the most specific rule should take precedence.


        Stefan

Message #13 received at 20642 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 20642 <at> debbugs.gnu.org
Subject: Re: bug#20642: 24.5; Please improve documentation for `pcase'
Date: Sun, 24 May 2015 22:27:49 -0400

>    Perform ML-style pattern matching on EXP.
> Users are probably not aware what 'ML-style pattern matching' is.

Indeed.  But this "ML-style" is the only useful thing I can think
to add to this first line.  I don't think removing it will help anyone.

> Please add an introduction without referring to ML.

Feel free to suggest a replacement, but remember it has to fit on
a single line.

>    CASES is a list of elements of the form (UPATTERN CODE...).
> Please document the motivation for the existence and nomenclature or
> UPatterns and QPatterns.

In Emacs-25, the docstring has been indirectly modified, so the QPAT now
is only documented in a separate section about the backquote pattern.
You might like to take a look in that version, to see if it makes more
sense that way.


        Stefan

Message #16 received at 20642 <at> debbugs.gnu.org (full text, mbox):

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 20642 <at> debbugs.gnu.org
Subject: Re: bug#20642: 24.5; Please improve documentation for `pcase'
Date: Sun, 21 Jun 2015 13:07:54 +0000

[Message part 1 (text/plain, inline)]

Stefan Monnier <monnier <at> iro.umontreal.ca> schrieb am Mo., 25. Mai 2015 um
04:27 Uhr:

> >    Perform ML-style pattern matching on EXP.
> > Users are probably not aware what 'ML-style pattern matching' is.
>
> Indeed.  But this "ML-style" is the only useful thing I can think
> to add to this first line.  I don't think removing it will help anyone.
>
> > Please add an introduction without referring to ML.
>
> Feel free to suggest a replacement, but remember it has to fit on
> a single line.
>
> >    CASES is a list of elements of the form (UPATTERN CODE...).
> > Please document the motivation for the existence and nomenclature or
> > UPatterns and QPatterns.
>
> In Emacs-25, the docstring has been indirectly modified, so the QPAT now
> is only documented in a separate section about the backquote pattern.
> You might like to take a look in that version, to see if it makes more
> sense that way.
>
>
>
I think the current wording is better, thanks.

[Message part 2 (text/html, inline)]

Message #19 received at 20642 <at> debbugs.gnu.org (full text, mbox):

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 20642 <at> debbugs.gnu.org
Subject: Re: bug#20642: 24.5; Please improve documentation for `pcase'
Date: Sun, 21 Jun 2015 13:08:34 +0000

[Message part 1 (text/plain, inline)]

Philipp Stephani <p.stephani2 <at> gmail.com> schrieb am So., 21. Juni 2015 um
15:07 Uhr:

> Stefan Monnier <monnier <at> iro.umontreal.ca> schrieb am Mo., 25. Mai 2015 um
> 04:27 Uhr:
>
>> >    Perform ML-style pattern matching on EXP.
>> > Users are probably not aware what 'ML-style pattern matching' is.
>>
>> Indeed.  But this "ML-style" is the only useful thing I can think
>> to add to this first line.  I don't think removing it will help anyone.
>>
>> > Please add an introduction without referring to ML.
>>
>> Feel free to suggest a replacement, but remember it has to fit on
>> a single line.
>>
>> >    CASES is a list of elements of the form (UPATTERN CODE...).
>> > Please document the motivation for the existence and nomenclature or
>> > UPatterns and QPatterns.
>>
>> In Emacs-25, the docstring has been indirectly modified, so the QPAT now
>> is only documented in a separate section about the backquote pattern.
>> You might like to take a look in that version, to see if it makes more
>> sense that way.
>>
>>
>>
> I think the current wording is better, thanks.
>

Sorry, wanted to say "the *new* wording (in Emacs 25) is better".

[Message part 2 (text/html, inline)]

Message #24 received at 20642-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 20642-done <at> debbugs.gnu.org
Subject: Re: bug#20642: 24.5; Please improve documentation for `pcase'
Date: Sun, 21 Jun 2015 21:19:30 -0400

> Sorry, wanted to say "the *new* wording (in Emacs 25) is better".

Thanks,


        Stefan

Previous Next

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