bug#31311: 27.0; doc of `pcase'

[Michael Heerdegen]

Hi Drew,

I've read the docstring again.  There are indeed many things left
unclear.  I think a prior version already had been clearer, though, much
also more brief.

> 2. Don't use ATOM unless you mean any atom, even if you explain
>    subsequently that you really mean a self-evaluating atom.

The best part of the doc string is the "complete list of patterns".
What is says is right: "ATOM can be a keyword, an integer, or a string".
In particular, floats are excluded.  nil and t are also excluded.
"KEYWORD-OR-INTEGER-OR-STRING" is not a good name, however.

> 3. The doc string (but not the Elisp manual, node `Pattern matching case
>    statement') refers to "the object" without ever specifying what it
>    is.  This makes all of the specifications that use "the object"
>    meaningless: 'VAL, (pred FUN), and (app FUN PAT).
>
>    The manual uses "the value being matched" instead, which is OK
>    (understandable).

Yes, that's what I would prefer.

>  Still, it would be clearer to give a name to "the value being
>  matched" at the beginning: EXPVAL, for example, at the place where
>  you say, "based on the value of EXPRESSION".

That's not necessarily true, however.  For example, in

(pcase .9
  ((let (pred integerp) 1) t))

(which evals to t) "(pred integerp)" is matched against 1, not the
original expression (which is ignored by the pattern in this case).

> 5. Don't use "QPattern" and "UPattern".  Use "Q pattern" and "U
>    pattern", or (probably better) "Q-pattern" and "U-pattern".

I would rather like to get rid from these old names completely.

> 6. This part of the description of `guard' is unclear, to me:
>
>    For example ... and let-binds the variable 'x' to that number.
>
>    I see nothing in the descriptions of `guard' and `and' that indicates
>    why `x' would be let-bound in this example.

It's just the SYMBOL case: "SYMBOL matches anything and binds it to
SYMBOL."  And "(and PAT...) matches if all the patterns match."


Michael.