bug#31311: 27.0; doc of `pcase'

[Noam Postavsky <npostavs@gmail.com>]

Thien-Thi Nguyen <ttn@gnu.org> writes:

> * c6e9b975f  add some Issue comments; nfc
>
>   This first set of ponderables revolves around the precise
>   semantics of the SYMBOL let-binding feature.

> +@c        - This is a design decision.  Document the limitation
> +@c          (i.e., BOOLEAN-EXPRESSION SHOULD NOT be side-effecting).
> +@c        - This is an unforseen case; behavior is based on the
> +@c          implementation (‘cond’ + redundant ‘let*’ expansion)
> +@c          and is considered {undefined, wontfix, futurefix}.
> +@c          Leave undocumented for now.

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.  By the way, the current
implementation causes a compiler warning if the variable is not used in
the body (Bug#16771), so it may well be changed if someone can figure
out how.

> Additionally, related to SYMBOL binding, i see (in *scratch*):
>
>   a.  (pcase t   ('t   'true))  => true
>   b.  (pcase nil ('nil 'false)) => false
>   c.  (pcase t   (t    'true))  => true

Yes, it looks like t is intentionally equivalent to _, cf pcase.el:

    (defconst pcase--dontcare-upats '(t _ pcase--dontcare))

Hence also:

    (pcase 42   (t    'true)) => true

>   d.  (pcase nil (nil  'false)) |= ERROR: Unknown pattern ‘nil’

In Emacs 24.5, it gives "Lisp error: (setting-constant nil)", so we can
see that this case now gives a more specific error.

> 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

    The two catagories of patterns are logical and structural.

    A logical pattern expands, in essence, to a predicate function
    to call on EXPVAL. [...]

    On the other hand, a structural pattern specifies a template,
    and allows for elements of that template to be either constants
    or sub-patterns (of either category).

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?

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))