[Emacs-diffs] fix/bug-31311-pcase-doc d5dfe0e 02/18: expand on SYMBOL

[Thien-Thi Nguyen]

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

    expand on SYMBOL
    
    - rework availability into two paras
      - to BODY-FORMS
        - straightforward
        - add xref here
      - to BIGPAT
        - introduce @var{bigpat}
        - forw-ref ‘and’
        - forw-ref and xref caveats
    - add anchor ‘pcase-symbol-caveats’
    - add heading and enumeration
      - three items, last one just a sketch
      - add full example for "2nd mention => ‘eq’" (first item)
    
    Issue: Better word for "caveat"?
---
 doc/lispref/control.texi | 72 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 63 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index f690a3a..e5d2440 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -399,15 +399,13 @@ possible because literal objects of these types are 
self-quoting.
 
 @item @var{symbol}
 Matches any @var{expval}, and additionally let-binds @var{symbol} to
address@hidden, so that you can later refer to it, either in the
address@hidden or also later in the pattern.
address@hidden Hmm, ``later in the pattern'' alludes to SYMBOL being not
address@hidden the entirety of the pattern, i.e., merely a (leading) part.
address@hidden Issue: Which is better?
address@hidden        - Move that blurb to ‘guard’.
address@hidden        - Suffix w/ ``when SYMBOL is part of a larger pattern''.
address@hidden        - Move all idioms and examples out of table.
address@hidden        Probably latter is best.
address@hidden, such that this binding is available to
address@hidden (@pxref{Dynamic Binding}).
+
+If @var{symbol} is part of a compound pattern @var{bigpat}
+(e.g., by using @code{and}, below), the binding is also available to
+the portion of @var{bigpat} following the appearance of @var{symbol}.
+This usage has some caveats (@pxref{pcase-symbol-caveats,,caveats}).
 
 Two symbols to avoid are @code{t}, which behaves like @code{_}
 (above) and is deprecated, and @code{nil}, which signals error.
@@ -500,6 +498,62 @@ should all bind the same symbols.
 Matches if all the argument U-patterns match.
 @end table
 
address@hidden
address@hidden Caveats for @var{symbol} in @var{bigpat}
+
address@hidden
address@hidden When @var{symbol} occurs more than once in @var{bigpat},
+the second and subsequent occurances do not expand to re-binding,
+but instead expand to an equality test using @code{eq}.
+
+The following example features a @code{pcase} form
+with two clauses and two @var{bigpat}, A and B.
+Both A and B first check that @var{expval} is a
+pair (using @code{pred}),
+and then bind symbols to the @code{car} and @code{cdr}
+of @var{expval} (using one @code{app} each).
+
+For A, because symbol @code{st} is mentioned twice, the second
+mention becomes an equality test using @code{eq}.
+On the other hand, B uses two separate symbols, @code{s1} and
address@hidden, both of which become independent bindings.
+
address@hidden
+(defun grok (object)
+  (pcase object
+    ((and (pred consp)        ; bigpat A
+          (app car st)        ; first mention: st
+          (app cdr st))       ; second mention: st
+     (list 'eq st))
+    ((and (pred consp)        ; bigpat B
+          (app car s1)        ; first mention: s1
+          (app cdr s2))       ; first mention: s2
+     (list 'not-eq s1 s2))))
+
address@hidden
+(grok (let ((s "yow!"))
+        (cons s s)))
address@hidden (eq "yow!")
address@hidden group
+
address@hidden
+(grok (cons "yow!" "yow!"))
address@hidden (not-eq "yow!" "yow!")
address@hidden group
+
address@hidden
+(grok '(4 2))
address@hidden (not-eq 4 (2))
address@hidden group
address@hidden example
+
address@hidden Side-effecting code referencing @var{symbol} is undefined.
+Avoid.
+
address@hidden address@hidden should all bind the same symbols'' (from 
@code{or}).
address@hidden (what does it mean?)
address@hidden enumerate
+
 @noindent
 Here's an example of using U-patterns: