[Emacs-diffs] fix/bug-31311-pcase-doc f2c9983 2/8: explain ‘or’ same-symbols caveat

[Thien-Thi Nguyen]

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

    explain ‘or’ same-symbols caveat
    
    - rewrite 2nd para
      - use "consistent environment"; add xref
      - mention "on match"
      - add Issue
    - write caveat text
      - 1st para: start w/ general truth and ‘and’ handling
      - 2nd para: ‘or’
        - contrast w/ ‘and’
        - use "distinguish"
        - add example (invalid) plus explanation
        - add example (reworked) plus explanation
---
 doc/lispref/control.texi | 81 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 76 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 75b5103..101109f 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -459,10 +459,15 @@ Simply @address@hidden(or @var{pattern1})}} signals 
error.)
 @c        Are there exceptions, qualifications?
 @c        (Btw, ``Please avoid it'' is a poor error message.)
 
address@hidden TODO: Pick one: (a) drop; (b) forw-ref caveat.
-For this reason,
-if any of the sub-patterns let-binds symbols to the matched value, they
+To present a consistent environment (@pxref{Intro Eval})
+to @var{body-forms} on match,
+if any of the sub-patterns let-binds symbols, they
 should all bind the same symbols.
address@hidden Issue: Using ``should'' is kind of weak.  However, the stronger
address@hidden        ``it is an error to...'' is not exactly correct, either,
address@hidden        since the error is raised during BODY-FORMS evaluation.
address@hidden        Maybe ‘s/on match/and avoid a symbol resolution error &/’
address@hidden        along w/ ‘s/should/must/’?
 
 @item (and @address@hidden)
 Attempts to match @address@hidden, in order,
@@ -754,8 +759,74 @@ in @var{boolean-expression} (in @code{guard}),
 but also in @var{expr} (in @code{let})
 and @var{function} (in @code{pred} and @code{app}).
 
address@hidden address@hidden should all bind the same symbols'' (from 
@code{or}).
address@hidden (what does it mean?)
address@hidden On match, the clause's body forms can reference the set
+of symbols the pattern let-binds.
+When @var{bigpat} is @code{and}, this set is
+the union of all the symbols each of its sub-patterns let-binds.
+This makes sense because, for @code{and} to match,
+all the sub-patterns must match.
+
+When @var{bigpat} is @code{or}, things are different:
address@hidden matches at the first sub-pattern that matches;
+the rest of the sub-patterns are ignored.
+It makes no sense for each sub-pattern to let-bind a different
+set of symbols because the body forms have no way to distinguish
+which sub-pattern matched and choose among the different sets.
+For example, the following is invalid:
+
address@hidden
address@hidden
+(pcase (read-number "Enter an integer: ")
+  ((or (and (pred evenp)
+            e-num)      ; @r{bind @code{e-num} to @var{expval}}
+       o-num)           ; @r{bind @code{o-num} to @var{expval}}
+   (list e-num o-num)))
address@hidden group
+
address@hidden
+Enter an integer: 42
address@hidden Symbol’s value as variable is void: o-num
address@hidden group
address@hidden
+Enter an integer: 149
address@hidden Symbol’s value as variable is void: e-num
address@hidden group
address@hidden example
+
address@hidden
+Evaluating body form @address@hidden(list e-num o-num)}} signals error.
+To distinguish between sub-patterns, you can use another symbol,
+identical in name in all sub-patterns but differing in value.
+Reworking the above example:
+
address@hidden
address@hidden
+(pcase (read-number "Enter an integer: ")
+  ((and num                                ; @r{line 1}
+        (or (and (pred evenp)              ; @r{line 2}
+                 (let spin 'even))         ; @r{line 3}
+            (let spin 'odd)))              ; @r{line 4}
+   (list spin num)))                       ; @r{line 5}
address@hidden group
+
address@hidden
+Enter an integer: 42
+(even 42)
address@hidden group
address@hidden
+Enter an integer: 149
+(odd 149)
address@hidden group
address@hidden example
+
address@hidden
+Line 1 ``factors out'' the @var{expval} binding with
address@hidden and @var{symbol} (in this case, @code{num}).
+The @code{or} begins in the same manner as before (line 2),
+but instead of binding different symbols, uses @code{let}
+to bind the same symbol @code{spin} in both sub-patterns.
+The value of the @code{spin} distinguishes the sub-patterns.
+The body form references both symbols (line 5).
 @end enumerate
 
 @node Extending pcase