Re: The poor state of documentation of pcase like things.

[Michael Heerdegen]

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.