[Emacs-diffs] fix/bug-31311-pcase-doc c6e9b97 2/3: add some Issue comments; nfc

[Thien-Thi Nguyen]

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

    add some Issue comments; nfc
    
    these stem from playing around in *scratch*:
    
    (macroexpand-all
     '(pcase 42
        ((and x (guard (< (incf x) 10))) (list 'single-digit x))
        (_ 'no-idea)))
    =>
    (if
        (let*
        ((x 42))
          (<
           (setq x
             (1+ x))
           10))
        (let
        ((x 42))
          (list 'single-digit x))
      'no-idea)
---
 doc/lispref/control.texi | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 802f6ca..23a961f 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -401,6 +401,13 @@ possible because these types are self-quoting.
 Matches any @var{expval}, and additionally let-binds @var{symbol} to
 @var{expval}, so that you can later refer to it, either in the
 @var{body-forms} 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.
 
 @item (pred @var{predfun})
 Matches if the predicate function @var{predfun} returns address@hidden
@@ -415,6 +422,28 @@ previous U-patterns.  Typically used inside an @code{and} 
U-pattern, see
 below.  For example, @address@hidden(and x (guard (< x 10)))}} is a pattern
 which matches any number smaller than 10 and let-binds the variable
 @code{x} to that number.
address@hidden What about side-effecting (ugh-lý :-D) BOOLEAN-EXPRESSION
address@hidden that mutates let-bound vars?  Any (dis-)guarantees?  Consider:
address@hidden
address@hidden (defun hmm (n)
address@hidden   (pcase n
address@hidden     ((and x (guard (< (decf x) 10)))
address@hidden      (list 'single-digit x))))
address@hidden
address@hidden (hmm 42) => nil
address@hidden (hmm 11) => nil
address@hidden (hmm 10) => (single-digit 10)
address@hidden (hmm 1)  => (single-digit 1)
address@hidden (hmm 0)  => (single-digit 0)
address@hidden
address@hidden Maybe there is some discussion of this already?
address@hidden Issue: Pick one:
address@hidden        - This is a design decision.  Document the limitation
address@hidden          (i.e., BOOLEAN-EXPRESSION SHOULD NOT be side-effecting).
address@hidden        - This is an unforseen case; behavior is based on the
address@hidden          implementation (‘cond’ + redundant ‘let*’ expansion)
address@hidden          and is considered {undefined, wontfix, futurefix}.
address@hidden          Leave undocumented for now.
 
 @item (let @var{upattern} @var{expression})
 Matches if the specified @var{expression} matches the specified
@@ -424,6 +453,7 @@ first argument to @code{pcase}.  (It is called @code{let} 
because
 @var{upattern} can bind symbols to values using the @var{symbol}
 U-pattern.  For example:
 @address@hidden((or `(key . ,val) (let val 5)) val)}}.)
address@hidden Issue: Same as above (side-effecting EXPRESSION).
 
 @item (app @var{function} @var{upattern})
 Matches if @var{function} applied to @var{expval} returns a
@@ -431,6 +461,7 @@ value that matches @var{upattern}.  This is like the 
@code{pred}
 U-pattern, except that it tests the result against @var{upattern},
 rather than against a boolean truth value.  The @var{function} call can
 use one of the forms described below.
address@hidden Issue: Same as above (side-effecting FUNCTION or UPATTERN).
 
 @item (or @var{upattern1} @address@hidden)
 Matches if one the argument U-patterns matches.  As soon as the first