[Top][All Lists]

[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?


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.



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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]