[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: The poor state of documentation of pcase like things.
From: |
Michael Heerdegen |
Subject: |
Re: The poor state of documentation of pcase like things. |
Date: |
Sun, 20 Dec 2015 14:11:26 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) |
Alan Mackenzie <address@hidden> writes:
> I don't really know what pcase-let does. I haven't a clue what
> pcase-lambda, pcase-defmacro, ... do.
The doc of `pcase-defmacro' is very terse, but I find the docs of
`pcase-lambda' and `pcase-let' understandable. What's wrong with these?
> > Mmh, but it also doesn't say that the normal meanings of and, or, ' and
> > let are suspended.
> > I think it doesn't have to, because a pcase pattern is not an
> > expression that is evaluated, so symbols with known names can't have
> > the same semantics as a pattern than as a defined function.
>
> That would be a good argument if only experts read the doc string.
> Thoroughly confused people also read doc strings. I don't think we
> should presuppose such sophisticated discernment in the typical
> reader.
Ok, speaking it out is a good idea. But I would prefer the (improved)
manual section.
> > > There is still no explicit statement of what pcase's ` and , mean.
>
> > But do we agree that the current docstring completely explains the
> > semantics, even if the definition is recursive?
>
> I don't agree. Completely missing is something like "pcase compares the
> value with each pattern in turn until one matches, and it then evaluates
> the corresponding BODY, returning the result of the last body form
> evaluated. If no pattern matches, nil is returned.". The somewhat
> offensive "perform ML-style pattern matching on that value" is no
> substitute for this.
I agree, but that is unrelated to backquote.
> There is no mention of ``' and `,' in the section on patterns. Or is
> \\='VAL really meant to be \\=`VAL?
No.
Since it's defined with `pcase-defmacro' now, it's listed later in the
section describing all additional pattern types:
,----------------------------------------------------------------------
| -- `QPAT
|
| Backquote-style pcase patterns.
| QPAT can take the following forms:
| (QPAT1 . QPAT2) matches if QPAT1 matches the car and QPAT2 the cdr.
| [QPAT1 QPAT2..QPATn] matches a vector of length n and QPAT1..QPATn match
| its 0..(n-1)th elements, respectively.
| ,PAT matches if the pcase pattern PAT matches.
| ATOM matches if the object is ‘equal’ to ATOM.
| ATOM can be a symbol, an integer, or a
| string.
`----------------------------------------------------------------------
Did you miss it all the time?
> But what does ``' _do_? What it normally does is well explained in its
> own doc string (which will need modification for pcase).
No, pcase just uses the symbol ``'. What ``' "means" in pcase doesn't
belong in the docstring of `backquote', those are two completely
unrelated things, there is just some analogy (which led Stefan to use a
backquote for the syntax).
> Are you saying that "QPattern" has no more conceptual meaning than
> "patterns which are backquoted"?
That's were the name comes from. But the forms a QPAT can have are
different from the "normal" pcase pattern types. See the -- `QPAT
section I quoted.
Regards,
Michael.
P.S. I'll be on a trip for the next two days in ~ two hours and will not be
able to read this list in that time.