[Emacs-diffs] fix/bug-3133-pcase-doc c3d1896 12/13: (docstring) rework middle

[Thien-Thi Nguyen]

branch: fix/bug-3133-pcase-doc
commit c3d1896c7c48e15ff5dce350e044446dd246dc69
Author: Thien-Thi Nguyen <address@hidden>
Commit: Thien-Thi Nguyen <address@hidden>

    (docstring) rework middle
    
    - zonk ‘cl-destructuring-bind’ info (interesting, but...)
    - use "two categories: logical and structural"
    - describe logical first
    - mention "expands" and "predicate function"
    - move table after logical description
    - describe structural second
    - quote ‘backquote’ (to build on reader familiarity)
    - add example (from ~/.signature :-D)
    - mention "congruent"
---
 lisp/emacs-lisp/pcase.el | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index ab80aea..b84f8ba 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -114,28 +114,11 @@ For the first CASE whose PATTERN \"matches\" EXPVAL,
 evaluate its CODE..., and return the value of the last form.
 If no CASE has a PATTERN that matches, return nil.
 
-A structural PATTERN describes a template that identifies a class
-of values.  For example, the pattern \\=`(,foo ,bar) matches any
-two element list, binding its elements to symbols named `foo' and
-`bar' -- in much the same way that `cl-destructuring-bind' would.
+The two catagories of patterns are logical and structural.
 
-A significant difference from `cl-destructuring-bind' is that, if
-a pattern match fails, the next case is tried until either a
-successful match is found or there are no more cases.  The CODE
-expression corresponding to the matching pattern determines the
-return value.  If there is no match the returned value is nil.
-
-Another difference is that pattern elements may be quoted,
-meaning they must match exactly: The pattern \\='(foo bar)
-matches only against two element lists containing the symbols
-`foo' and `bar' in that order.
-
-Lastly, a pattern can be logical, such as (pred numberp), that
-matches any number-like element; or the symbol `_', that matches
-anything.  Also, when patterns are backquoted, a comma may be
-used to introduce logical patterns inside backquoted patterns.
-
-The complete list of standard patterns is as follows:
+A logical pattern expands, in essence, to a predicate function
+to call on EXPVAL.  When the return value of that call is non-nil,
+the pattern matches.  A logical pattern can take one of the forms:
 
   _            matches anything.
   \\='VAL              matches if EXPVAL is `equal' to VAL.
@@ -152,6 +135,23 @@ The complete list of standard patterns is as follows:
   (let PAT EXP)        matches if EXP matches PAT.
   (app FUN PAT)        matches if FUN applied to EXPVAL matches PAT.
 
+On the other hand, a structural pattern specifies a template,
+and allows for elements of that template to be either constants
+or sub-patterns (of either category).  A structural pattern
+begins with `backquote' and logical sub-pattern elements are
+introduced by a comma.  For example:
+
+  \\=`(technical ,ml)
+
+The predicate function specified by a structural pattern is a
+combination of those specified by any sub-patterns, wrapped in a
+top-level condition: EXPVAL must be \"congruent\" with the template.
+In the above example, the predicate is the logical-AND of:
+ - Is EXPVAL a list of two elements?
+ - Is the first element the symbol `technical'?
+ - True!  (The second element can be anything, and for the sake
+   of CODE..., its value is bound to the symbol `ml'.)
+
 Additional patterns can be defined using `pcase-defmacro'.
 
 The FUN argument in the `app' pattern may have the following forms: