bug#31311: 27.0; doc of `pcase'

[Thien-Thi Nguyen]

() Noam Postavsky <npostavs@gmail.com>
() Sat, 12 May 2018 09:56:21 -0400

   I would say the behaviour of pcase when guard expressions
   have side-effects is not defined, so the documentation should
   advise against having side-effects in guard expressions.

I've done this (commit 977bd10f5e70) and extended the advice to
other places where evaluation occurs.

   [‘t’ and ‘nil’ as SYMBOL patterns]

Thanks for confirming.  I've addressed this in another post.

   > For anyone just joining, these commits are on the branch
   > ‘fix/bug-31311-pcase-doc’ (off of ‘emacs-26’).  Feedback on
   > anything there is most welcome!

   In the docstring, you have

       [...] two catagories [...] logical and structural.

   You grouped SYMBOL into the "logical patterns", but I don't
   think it really fits into either of those.  Better to make it
   separate, perhaps?

In the end, reverted this distinction, moved `QPAT material to
the ‘(pcase-defmacro \` (qpat) ...)’ form, and added a comment
in ‘pcase--make-docstring’ proposing somehow to arrange for
`QPAT docstring to be presented immediately after ‘pcase’.  More
on this in a post to emacs-devel (which is still queued for
delivery on my side at this moment...).

   I'm also not so sure it's a useful division.  At least, they
   shouldn't be presented as equal categories.  The "structural"
   is more a short form for particular kinds of "logical"
   patterns.  For example, `(1 . 2) is equivalent to

       (and (pred consp)
            (app car 1)
            (app cdr 2))

True.  However, i'm trying to avoid using `QPAT in either
docstrings or examples prior to its introduction (including
table of possible QPAT forms).  Kind of an informational
layering.  This snippet was very useful, anyway; i adapted and
expanded on it for the example illustrating "2nd SYMBOL becomes
‘eq’ test".  Thanks for posting it.

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)
   (pcase (context query)
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502

signature.asc
Description: PGP signature