pcase docstring tweaks (was: Question on pcase)

[Michael Heerdegen]

Alan Mackenzie <address@hidden> writes:

> But I honestly think it's time for our discussion to cease.  We've
> unwittingly descended into bikeshedding, and we're not going to be
> helping Michael Heerdegen much with it.  But thanks for the discussion
> anyway!

I can only thank everyone who joined the discussion as well!  I'll think
carefully about all comments, and make the corrections.

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:"


Regards,

Michael.