Re: Update of pcase docs for the elisp manual

[Stefan Monnier]

>      (pcase x
>        ((and (pred numberp)
>            (let (pred (lambda (x) (< 5 x)))
>              (abs x)))

The second arg to `let' (i.e. (abs x) here) is a plain old normal
expression, so it does not necessarily use the currently matched object
and if it wants to, it can do it as above by simply re-using the same
expression as was passed to `pcase'.

Then the result of this expression is matched against the first arg of
`let' (i.e. (pred (lambda (x) (< 5 x))) here).

So (let (pred (lambda (x) (< 5 x))) (abs x)) ends up being equivalent to
(guard (< 5 (abs x))).

>   . The exact syntax and possible forms of QPatterns are described
>     ambiguously and seemingly incompletely, and profoundly contradict
>     almost every given example of them.  Both Michael and the previous
>     manual text describe them as follows:

>      The form is `QPAT where QPAT is one of the following:

>        (QPAT1 . QPAT2)
>        [QPAT1 QPAT2 ... QPATn]
>        ,PAT
>        ATOM

>     The last two look wrong: AFAIU, there is no QPattern of the form
>     `,PATH

I think `,PAT is a valid UPattern, which is simply equivalent to PAT.

>     or `ATOM.

And `ATOM is also a valid UPattern.

>     The examples are terribly confusing.  They all use this form:
>      `(A B C D ...)
>     where each of A, B, etc. can be one of:
>      - ,UPAT
>      - ATOM
>     And yet this pattern doesn't appear at all in the possible forms
>     of QPAT above!

Of course it does: `(A B C D ...) is 100% equivalent to
`(A . (B . (C . (D . ...)))) and (QPAT1 . QPAT2) is a QPAT.

>   . Many of the examples using QPatterns seem to allow to be easily
>     rewritten to use only UPatterns, by adding additional 'pred' and
>     'guard' conditions.  Is that true?

Very much so.  QPatterns aren't "core patterns".  So much so that in
Emacs-25 the `QPAT form is actually defined on top of the core patterns
using pcase-defmacro.

>   . Last, but not least: NEWS says we now have a new UPattern 'quote',
>     but neither John, nor Michael or the doc strings mention this
>     pattern.  What did I miss?

The docstring says:

  'VAL          matches if the object is ‘equal’ to VAL.

and 'VAL is also spelled (quote VAL).


        Stefan