Re: emacs-25 1d4887a: Improve documentation of 'pcase'

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: jwiegley@gmail.com,  emacs-devel@gnu.org
> Date: Mon, 25 Jan 2016 14:49:20 +0100
> 
> "A pattern can be a literal value (comparison to literal values is what
> @code{cond} does)".
> 
> Comparison to literal values is what case does.  cond evaluates
> expressions and looks whether the value is non-nil.

What I meant was that 'cond' can be used to compare against literal
values.  I will tweak the wording to make that more clear, thanks.

> > > > +@defmac pcase expression &rest clauses
> > > > +Evaluate @var{expression} and choose among an arbitrary number of
> > > > +alternatives based on the value of @var{expression}.  The possible
> > > > +alternatives are specified by @var{clauses}, each of which must be a
> > > > +list of the form @code{(@var{pattern} @var{body-forms})}.
> > > 
> > > I think we should write @code{(@var{pattern} . @var{body-forms})}
> > >                                              ^
> > > if we mean that BODY-FORMS is a list, or use an ellipsis: "...", as you
> > > do later.
> >
> > Sorry, I don't understand why.  "Forms", in plural, means there are
> > more than one of them.  I'm okay with adding @dots{}, if you somehow
> > think it's required.  But using a cons cell would be too confusing, as
> > none of the examples uses that form.
> 
> But if body-forms is a list, you would get a template like
> 
>   (pattern (expr1 expr2))
> 
> and that's wrong.

I didn't say body-forms is a list.  I just said that there can be more
than one form there.

> > > > +The @var{pattern} part of a clause can be of one of two types:
> > > > +@dfn{QPattern}, a pattern quoted with a backquote; or a
> > > > +@dfn{UPattern}, which is not quoted.  UPatterns are simpler, so we
> > > > +describe them first.
> > > 
> > > I had hoped we can get rid of the QPattern/Upattern distinction.  Is it
> > > too late to change that?  In particular, we wanted to speak of just
> > > patterns instead of Upatterns.
> >
> > Find a better name for them, and we can switch.  Using "pattern" for
> > UPattern is not a good idea, IMO, as that word is too generic, and we
> > are describing a feature where we must use that word all the time.
> 
> I just call them pcase patterns.

Too wordy, IMO.  Try using that in the descriptions of each pattern,
and you quickly get a mouthful.

> > > > +@item '@var{val}
> > > > +Matches if the value being matched is @code{equal} to @var{val}.
> > > > +@item @var{atom}
> > > > +Matches any @var{atom}, which can be a keyword, a number, or a
> > > > string.
> > > > +(These are self-quoting, so this kind of UPattern is actually a
> > > > +shorthand for @code{'@var{atom}}.)
> > > 
> > > Can we say "matches any (equal) atom"?  This makes a difference for
> > > strings.
> >
> > Why does it make a difference?
> 
> Strings and floats don't only match themselves, but also any equal
> string/float.  That's important, since not everything is always tested
> with `euqal' - multiple occurrences of a symbol are turned into `eq'
> tests, for example.

But there's no reference to 'eq' or 'equal' in that text.  It just
says "matches".

> > > > +below.  For example, @w{@code{(and x (guard (< x 10)))}} is a pattern
> > > > +which matches any number smaller than 10 and let-binds the variable
> > > > +@code{x} to that number.
> > > 
> > > Maybe we should use
> > > 
> > >   @w{@code{(and x (pred numberp) (guard (< x 10)))}}
> > > 
> > > instead in the example, because without the numberp test, the pattern
> > > will raise an error if x is not bound to a number.
> >
> > I don't think we need to be so pedantic in "for example" fragments,
> > they are just there to illustrate a point.
> 
> But the reader may get the impression that such things are tested
> implicitly, or the error is silenced and the pattern just doesn't match.

There's no reason to believe readers will get such an expression from
something that is clearly an incomplete fragment.

> > > The thing we name "qpattern" is without backquote, so with the current
> > > wording, I would leave the backquote out.
> >
> > There's no backquote in the QPatterns in the text I wrote, see above.
> > the backquote is explicitly prepended.  So I'm not sure how to
> > understand this comment.
> 
> I think Stefan has answered this question in a different post.

He just said that he (and evidently you as well) use a different
"language" when you talk about QPatterns.  I think my "language" is
more easily understood and matches the actual usage better, even if
it's pedantically less rigorous.

Thanks.