[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs-25 1d4887a: Improve documentation of 'pcase'
From: |
Eli Zaretskii |
Subject: |
Re: emacs-25 1d4887a: Improve documentation of 'pcase' |
Date: |
Sat, 23 Jan 2016 15:27:13 +0200 |
> From: Michael Heerdegen <address@hidden>
> Cc: John Wiegley <address@hidden>,
> Emacs Development <address@hidden>
> Date: Sat, 23 Jan 2016 12:38:34 +0100
>
> Hi Eli,
>
> thanks for finalizing this stuff.
You are welcome.
> > -To compare a particular value against various possible cases, the macro
> > address@hidden can come handy. It takes the following form:
> > +The @code{cond} form lets you choose between alternatives using
> > +predicate conditions that compare values of expressions against
> > +specific values known and written in advance. However, sometimes it
> > +is useful to select alternatives based on more general conditions that
> > +distinguish between broad classes of values. The @code{pcase} macro
> > +allows to choose between alternatives based on matching the value of
> > +an expression against a series of patterns. A pattern can be a
> > +literal value (comparison to literal values is what @code{cond}
> > does),
>
> That does sound more as a description of `cl-case' -- typo?
No, of course not. What's incorrect about that text regarding
'pcase'?
> > address@hidden 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.
> > +The @var{pattern} part of a clause can be of one of two types:
> > address@hidden, a pattern quoted with a backquote; or a
> > address@hidden, 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.
> > address@hidden '@var{val}
> > +Matches if the value being matched is @code{equal} to @var{val}.
> > address@hidden @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?
> > +Matches if @var{boolean-expression} evaluates to address@hidden This
> > +allows to include in a UPattern boolean conditions that refer to
> > +symbols bound to values (including the value being matched) by
> > +previous UPatterns. Typically used inside an @code{and} UPattern, see
> > +below. For example, @address@hidden(and x (guard (< x 10)))}} is a pattern
> > +which matches any number smaller than 10 and let-binds the variable
> > address@hidden to that number.
>
> Maybe we should use
>
> @address@hidden(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.
>
> > address@hidden @code
> > address@hidden `(@var{qpattern1} . @var{qpattern2})
> > +Matches if the value being matched is a cons cell whose @code{car}
> > +matches @var{qpattern1} and whose @code{cdr} matches @var{qpattern2}.
> > address@hidden address@hidden @var{qpattern2} @dots{} @var{qpatternm}]
> > +Matches if the value being matched is a vector of length @var{m} whose
> > address@hidden@code{(@var{m}-1)}th elements match @var{qpattern1},
> > address@hidden @dots{} @var{qpatternm}, respectively.
> > address@hidden `(,@var{upattern1} ,@var{upattern2} @dots{})
> > +Matches if the value being matched is a list whose elements match the
> > +corresponding @var{upattern1}, @var{upattern2}, etc.
> > address@hidden @var{atom}
> > +Matches if corresponding element of the value being matched is
> > address@hidden to the specified @var{atom}.
> > address@hidden ,@var{upattern}
> > +Matches if the corresponding element of the value being matched
> > +matches the specified @var{upattern}.
>
> Please decide if you include the backquote in all examples, or in none.
I did. The two last ones belong to the "issues" I raise in a separate
mail: I Think they don't have a place in this list, at least not in
that syntax. When that discussion ends to my satisfaction, I will fix
whatever needs to be fixed.
> 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.
> And these templates are not covering everything possible, e.g. you can
> also have
>
> `(,up1 . ,up2)
>
> or
>
> `(,up qp1)
>
> I think I would reorganize that paragraph.
When the fog and the dust settle down, perhaps I will. For now, this
is the best I could come up with, and it closely follows what you
wrote in your guide, btw.
Thanks for reviewing it.
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Michael Heerdegen, 2016/01/23
- Re: emacs-25 1d4887a: Improve documentation of 'pcase',
Eli Zaretskii <=
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Michael Heerdegen, 2016/01/25
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Stefan Monnier, 2016/01/25
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Michael Heerdegen, 2016/01/25
- RE: emacs-25 1d4887a: Improve documentation of 'pcase', Drew Adams, 2016/01/25
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Michael Heerdegen, 2016/01/25
- RE: emacs-25 1d4887a: Improve documentation of 'pcase', Drew Adams, 2016/01/25
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Stefan Monnier, 2016/01/25
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Eli Zaretskii, 2016/01/25
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Michael Heerdegen, 2016/01/25