Re: Replace trivial pcase occurrences in the Emacs sources

[Alan Mackenzie <acm@muc.de>]

Hello, Stefan.

On Mon, Oct 29, 2018 at 17:08:38 -0400, Stefan Monnier wrote:
> >> > Doc strings which specify fully the arguments to these macros, including
> >> > their semantics, and say what the macros do.  The current doc strings
> >> > (at least some of them) for these macros don't do this.
> >> I understand this in theory, but I don't know what it means in this
> >> concrete case.
> > Take a look at, for example, the doc string for pcase-dolist.  In its
> > entirety, it's this:

> Thanks.  What do you think of the patch below?

I don't think it's enough.

> I'd rather keep it defined in terms of its differences w.r.t `dolist`,
> but if really needed, we could change the doc so it doesn't rely on
> `dolist`s own doc at all.

That's a bad idea if it means not saying what the macro does.  Not
everybody is familiar with dolist by any means.  Is dolist's doc string
of sufficiently high quality to act as this basis?

> We do have to keep the reference to `pcase` because we don't want to
> repeat the definition of what a pcase pattern can look like.

Yes, I think that's right.

Things I believe MUST appear explicitly in the doc string for
pcase-dolist: 
1. It is a loop over the elements of LIST, which must be a list.
2. It attempts to match the current list element with the supplied
PATTERN, which must be a valid pcase style pattern.
3. The BODY forms are evaluated for each element of the list.
4. The purpose of the matching is to create bindings for symbols, and
these bindings are in force when the BODY forms are evaluated.
5. When a pattern match fails, ..... (This needs to be stated).

>         Stefan


> diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
> index 57c2d6c3cb..861c900b21 100644
> --- a/lisp/emacs-lisp/pcase.el
> +++ b/lisp/emacs-lisp/pcase.el
> @@ -281,7 +281,7 @@ pcase-let*
>  (defmacro pcase-let (bindings &rest body)
>    "Like `let' but where you can use `pcase' patterns for bindings.
>  BODY should be a list of expressions, and BINDINGS should be a list of bindings
> -of the form (PAT EXP).
> +of the form (PATTERN EXP).
>  The macro is expanded and optimized under the assumption that those
>  patterns *will* match, so a mismatch may go undetected or may cause
>  any kind of error."
> @@ -302,7 +302,12 @@ pcase-let
 
>  ;;;###autoload
>  (defmacro pcase-dolist (spec &rest body)
> -  "Like `dolist' but where the binding can be a `pcase' pattern.
> +  "Superset of `dolist' where the VAR binding can be a `pcase' PATTERN.
> +More specifically `dolist's VAR binding is replaced by a PATTERN
> +against which each element of the list is matched.
> +As in the case of `pcase-let', PATTERN is matched under the assumption
> +that it *will* match.
> +
>  \n(fn (PATTERN LIST) BODY...)"
>    (declare (indent 1) (debug ((pcase-PAT form) body)))
>    (if (pcase--trivial-upat-p (car spec))

-- 
Alan Mackenzie (Nuremberg, Germany).