[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs-25 1d4887a: Improve documentation of 'pcase'
From: |
Michael Heerdegen |
Subject: |
Re: emacs-25 1d4887a: Improve documentation of 'pcase' |
Date: |
Sat, 23 Jan 2016 12:38:34 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) |
Hi Eli,
thanks for finalizing this stuff.
Some comments:
> -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?
> 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.
> +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.
> 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.
And actually, this is not true for floats, only for integers (I'm not
sure why).
> +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.
> 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.
The thing we name "qpattern" is without backquote, so with the current
wording, I would leave the backquote out.
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.
Many, many thanks so far.
Regards,
Michael.
- Re: emacs-25 1d4887a: Improve documentation of 'pcase',
Michael Heerdegen <=
- Re: emacs-25 1d4887a: Improve documentation of 'pcase', Eli Zaretskii, 2016/01/23
- 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