From: Michael Heerdegen <michael_heerdegen@web.de>
To: Eli Zaretskii <eliz@gnu.org>
Cc: jwiegley@gmail.com, emacs-devel@gnu.org
Subject: Re: emacs-25 1d4887a: Improve documentation of 'pcase'
Date: Mon, 25 Jan 2016 14:49:20 +0100 [thread overview]
Message-ID: <87h9i1rcpr.fsf@web.de> (raw)
In-Reply-To: <837fj05sum.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 23 Jan 2016 15:27:13 +0200")
Eli Zaretskii <eliz@gnu.org> writes:
> > > -To compare a particular value against various possible cases, the
> > > macro
> > > -@code{pcase} 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'?
"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.
> > > +@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.
> > > +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.
> > > +@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.
> > > +Matches if @var{boolean-expression} evaluates to non-@code{nil}.
> > > 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, @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.
That's why I think it's a bad example without the additional test.
> > > +@table @code
> > > +@item `(@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}.
> > > +@item `[@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}]
> > > +Matches if the value being matched is a vector of length @var{m}
> > > whose
> > > +@code{0}..@code{(@var{m}-1)}th elements match @var{qpattern1},
> > > +@var{qpattern2} @dots{} @var{qpatternm}, respectively.
> > > +@item `(,@var{upattern1} ,@var{upattern2} @dots{})
> > > +Matches if the value being matched is a list whose elements match the
> > > +corresponding @var{upattern1}, @var{upattern2}, etc.
> > > +@item @var{atom}
> > > +Matches if corresponding element of the value being matched is
> > > +@code{equal} to the specified @var{atom}.
> > > +@item ,@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.
Ok, I hope I don't miss it.
> > 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. Sorry if
he answered other things already that I tell here.
> > 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.
Ok.
Thanks,
Michael.
next prev parent reply other threads:[~2016-01-25 13:49 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20160123102327.23087.15367@vcs.savannah.gnu.org>
[not found] ` <E1aMvLr-00060z-TI@vcs.savannah.gnu.org>
2016-01-23 11:38 ` emacs-25 1d4887a: Improve documentation of 'pcase' Michael Heerdegen
2016-01-23 13:27 ` Eli Zaretskii
2016-01-25 13:49 ` Michael Heerdegen [this message]
2016-01-25 14:36 ` Stefan Monnier
2016-01-25 15:29 ` Michael Heerdegen
2016-01-25 15:56 ` Drew Adams
2016-01-25 16:10 ` Michael Heerdegen
2016-01-25 16:48 ` Drew Adams
2016-01-25 16:15 ` Stefan Monnier
2016-01-25 16:23 ` Eli Zaretskii
2016-01-25 16:43 ` Michael Heerdegen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87h9i1rcpr.fsf@web.de \
--to=michael_heerdegen@web.de \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=jwiegley@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.