[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Update of pcase docs for the elisp manual
From: |
Eli Zaretskii |
Subject: |
Re: Update of pcase docs for the elisp manual |
Date: |
Sun, 24 Jan 2016 16:33:04 +0200 |
> From: Stefan Monnier <address@hidden>
> Date: Sat, 23 Jan 2016 23:40:19 -0500
>
> > (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'.
Yes, I know. That's not the confusing part (although re-using 'x' in
this way muddies the waters and doesn't help).
> So (let (pred (lambda (x) (< 5 x))) (abs x)) ends up being equivalent to
> (guard (< 5 (abs x))).
Yes, because it doesn't use the feature for which 'let' was invented:
it doesn't bind any symbols to values. And that's the confusing part:
'let' is being used where it isn't really needed, so this is not the
ideal example for the 'let' pattern.
> > . 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 above describes QPatterns, not UPatterns. I also arrived at the
conclusion that we should talk about UPatterns (see how I changed the
above for the manual), but then those 2 shouldn't appear in the list
as QPatterns, they should be explained as UPatterns a QPattern can use
by unquoting them. Which is exactly what I did in the manual.
> > 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.
Which IMO means we must add the likes of `(A B C D) to the manual,
because expecting the readers of software documentation to solve
riddles as they read is not a good idea.
> > . 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.
Then this, too, should be added, probably with an example. Michael,
would you mind providing an educational example for that, please?
> > . 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).
This probably means that 'quote' shouldn't be documented as a separate
pattern, as that is a technicality which is much more likely to
confuse than to help understanding. Unless, that is, there are
important scenarios where using (quote FOO) in a pattern is required
where it isn't a trivial replacement for 'FOO. Do you know about such
scenarios?
Thanks.
- Re: Update of pcase docs for the elisp manual, Eli Zaretskii, 2016/01/23
- Re: Update of pcase docs for the elisp manual, Stefan Monnier, 2016/01/23
- Re: Update of pcase docs for the elisp manual,
Eli Zaretskii <=
- Re: Update of pcase docs for the elisp manual, Stefan Monnier, 2016/01/24
- Re: Update of pcase docs for the elisp manual, Eli Zaretskii, 2016/01/25
- Re: Update of pcase docs for the elisp manual, Stefan Monnier, 2016/01/25
- Re: Update of pcase docs for the elisp manual, Eli Zaretskii, 2016/01/26
- Re: Update of pcase docs for the elisp manual, Stefan Monnier, 2016/01/26
- Re: Update of pcase docs for the elisp manual, Michael Heerdegen, 2016/01/25
Re: Update of pcase docs for the elisp manual, Michael Heerdegen, 2016/01/25