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

[Michael Heerdegen <michael_heerdegen@web.de>]

Hi Eli,

thanks for finalizing this stuff.


Some comments:


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


> +@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.

> +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.

> +@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.

And actually, this is not true for floats, only for integers (I'm not
sure why).

> +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.


> +@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.
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.