[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: |
Sat, 23 Jan 2016 13:17:07 +0200 |
> From: John Wiegley <address@hidden>
> Cc: Eli Zaretskii <address@hidden>
> Date: Fri, 22 Jan 2016 10:03:55 -0800
>
> Below is an update to the pcase.texi I sent earlier, with Michael's
> corrections.
Thanks.
> Eli, I'm not sure the Texinfo here is even sane.
Texinfo is the least of our problems in this and similar cases.
I updated the docs, thanks to both of you. I used your text, John,
and also Michael's pcase-guide.el as the starting points, source of
inspiration and examples, and sometimes source of swaths of text as
well. I also used what was already in the manual. The end result,
for which I accept full responsibility (although you are named as
co-authors), is in the repository; please take a look and comment,
modify, and improve as appropriate. In particular, the UPattern
example needs to be improved as the comment there says, please do so
if you have time.
Some subtle points that I still don't regard as resolved in a
satisfactory manner:
. The description of the 'let' pattern is not entirely clear.
Michael's examples actually confused me instead of helping to
understand it, because the examples use the same symbol for the
1st arg of 'pcase' and for symbols that are UPatterns (and also in
other contexts). Example:
(pcase x
((and (pred numberp)
(let (pred (lambda (x) (< 5 x)))
(abs x)))
t)
(_ nil))
The documentation of 'let' says that it matches if the expression
matches the pattern. Here, the expression is "(abs x)" and the
pattern is "(pred (lambda (x) (< 5 x)))", right? So how can they
"match"? The fact that 'x' is used here in no less than 3
different contexts doesn't help, either. I actually don't
understand the "(abs x)" part at all, since 'x' was not bound to
anything by any previous pattern. AFAIU, the 1st argument of
'pcase' cannot be used like that, because it will not be a symbol
in the general case, it's an expression whose value is not bound
to anything.
The sharp-eyed among you might notice that the documentation of
the 'let' pattern is somewhat vague -- the above is the reason.
. 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 or `ATOM. These 2 seem to be _components_ or QPatterns,
see below.
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!
. 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? If so, we should tell this
somewhere, because otherwise the reader might think she
misunderstood something very important. I did, because none of
the texts I've seen in preparation for this work discusses this
aspect. Take this, for example:
(pcase x
(`("foo") t)
(`("foo" ,a) a)
(`("foo" . ,(and (pred listp) rest)) rest))
What do we have here that cannot be done with UPatterns?
. 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?
Thanks.
- Re: Update of pcase docs for the elisp manual,
Eli Zaretskii <=
- 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, 2016/01/24
- 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