bug#20643: 24.5; Please improve documentation of `pcase-let'

bug#20643: 24.5; Please improve documentation of `pcase-let'

[Philipp Stephani]

The documentation of `pcase-let' is very terse.  Please expand it to
state what happens to each binding in the case that the pattern of a
binding matches, in the case where it doesn't match, and in the case
where there are no binding constructs in a pattern.



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:
Auto-saving...done
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 121758 16283)
 (symbols 48 21489 1)
 (miscs 40 70 436)
 (strings 32 20572 5003)
 (string-bytes 1 573284)
 (vectors 16 11348)
 (vector-slots 8 377433 8228)
 (floats 8 77 372)
 (intervals 56 1062 144)
 (buffers 960 20))

bug#20643: 24.5; Please improve documentation of `pcase-let'

[Stefan Monnier]

> The documentation of `pcase-let' is very terse.  Please expand it to
> state what happens to each binding in the case that the pattern of a
> binding matches, in the case where it doesn't match, and in the case
> where there are no binding constructs in a pattern.

I added:

   The macro is expanded and optimized under the assumption that those
   patterns *will* match, so a mismatch may go undetected or may cause
   any kind of error."


-- Stefan

bug#20643: 24.5; Please improve documentation of `pcase-let'

[Philipp Stephani]

[-- Attachment #1: Type: text/plain, Size: 675 bytes --]

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

> > The documentation of `pcase-let' is very terse.  Please expand it to
> > state what happens to each binding in the case that the pattern of a
> > binding matches, in the case where it doesn't match, and in the case
> > where there are no binding constructs in a pattern.
>
> I added:
>
>    The macro is expanded and optimized under the assumption that those
>    patterns *will* match, so a mismatch may go undetected or may cause
>    any kind of error."
>
>
>
Thanks. Though I think it would be better to be more defensive and
guarantee to raise a signal in the case of a mismatch.

[-- Attachment #2: Type: text/html, Size: 1023 bytes --]

bug#20643: 24.5; Please improve documentation of `pcase-let'

[Stefan Monnier]

> Thanks. Though I think it would be better to be more defensive and
> guarantee to raise a signal in the case of a mismatch.

If you want that, you need to use pcase, or pcase-exclusive.

This is a judgment call, but it lets pcase-let generate significantly
shorter and more efficient code and hence better serve the expected
common case.


        Stefan