Re: pcase docstring tweaks

[Michael Heerdegen]

Hello,

Stefan, ok to install this?

And as I said before: anyone is invited to bike shedding ;-)

> Let's continue with the `pcase' docstring.  I think it's already quite
> good.  Here is a patch emphasizing that EXP is actually evaluated (I
> think that is not evident) and some more or less cosmetic changes.  Is
> it clear then?
>
>
> *** /tmp/ediff17164yyt        2015-10-25 01:54:53.175155728 +0200
> --- /home/micha/software/emacs/lisp/emacs-lisp/pcase.el       2015-10-25 
> 00:35:23.999856799 +0200
> ***************
> *** 107,113 ****
>   
>   ;;;###autoload
>   (defmacro pcase (exp &rest cases)
> !   "Perform ML-style pattern matching on EXP.
>   CASES is a list of elements of the form (PATTERN CODE...).
>   
>   Patterns can take the following forms:
> --- 107,113 ----
>   
>   ;;;###autoload
>   (defmacro pcase (exp &rest cases)
> !   "Eval EXP and perform ML-style pattern matching on that value.
>   CASES is a list of elements of the form (PATTERN CODE...).
>   
>   Patterns can take the following forms:
> ***************
> *** 115,123 ****
>     SYMBOL    matches anything and binds it to SYMBOL.
>     (or PAT...)       matches if any of the patterns matches.
>     (and PAT...)      matches if all the patterns match.
> !   \\='VAL           matches if the object is `equal' to VAL
>     ATOM              is a shorthand for \\='ATOM.
> !                ATOM can be a keyword, an integer, or a string.
>     (pred FUN)        matches if FUN applied to the object returns non-nil.
>     (guard BOOLEXP)   matches if BOOLEXP evaluates to non-nil.
>     (let PAT EXP)     matches if EXP matches PAT.
> --- 115,123 ----
>     SYMBOL    matches anything and binds it to SYMBOL.
>     (or PAT...)       matches if any of the patterns matches.
>     (and PAT...)      matches if all the patterns match.
> !   \\='VAL           matches if the object is `equal' to VAL.
>     ATOM              is a shorthand for \\='ATOM.
> !                when ATOM is a keyword, an integer, or a string.
>     (pred FUN)        matches if FUN applied to the object returns non-nil.
>     (guard BOOLEXP)   matches if BOOLEXP evaluates to non-nil.
>     (let PAT EXP)     matches if EXP matches PAT.
> ***************
> *** 131,141 ****
>                           which is the value being matched.
>   So a FUN of the form SYMBOL is equivalent to one of the form (FUN).
>   FUN can refer to variables bound earlier in the pattern.
> - FUN is assumed to be pure, i.e. it can be dropped if its result is not used,
> - and two identical calls can be merged into one.
>   E.g. you can match pairs where the cdr is larger than the car with a pattern
>   like \\=`(,a . ,(pred (< a))) or, with more checks:
>   \\=`(,(and a (pred numberp)) . ,(and (pred numberp) (pred (< a))))
>   
>   Additional patterns can be defined via `pcase-defmacro'.
>   Currently, the following patterns are provided this way:"
> --- 131,141 ----
>                           which is the value being matched.
>   So a FUN of the form SYMBOL is equivalent to one of the form (FUN).
>   FUN can refer to variables bound earlier in the pattern.
>   E.g. you can match pairs where the cdr is larger than the car with a pattern
>   like \\=`(,a . ,(pred (< a))) or, with more checks:
>   \\=`(,(and a (pred numberp)) . ,(and (pred numberp) (pred (< a))))
> + FUN is assumed to be pure, i.e. it can be dropped if its result is not used,
> + and two identical calls can be merged into one.
>   
>   Additional patterns can be defined via `pcase-defmacro'.
>   Currently, the following patterns are provided this way:"


Thanks,

Michael.