[Emacs-diffs] fix/bug-31311-pcase-doc 455f990 6/9: start on Backquote-Style Patterns

[Thien-Thi Nguyen]

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

    start on Backquote-Style Patterns
    
    - add subheading and related Issue
    - add cindex entry
    - split intro into two paras
      - 1st para
        - drop "In addition"
        - do ‘s/backquoted/backquote-style/g’
        - mention ‘pcase’
        - mention "extensions" and ‘pcase-defmacro’
      - 2nd para
        - mention "to match"
        - use "you can write"
        - show impl w/ core pattern
        - move impl w/ backquote-style pattern into @example block
        - use "concise", "resembling"
        - mention binding-mu
    - zonk FIXME comment that requests side-by-side comparison
      (now achieved)
---
 doc/lispref/control.texi | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 14446f5..fe01531 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -903,12 +903,35 @@ The second uses two core patterns: @code{and} and 
@code{pred},
 as well as the newly-defined pattern @code{less-than}.
 Both use a single backquote construct (@pxref{Backquote}).
 
-In addition, you can use backquoted patterns that are more powerful.
-They allow matching @var{expval} against specifications of its
address@hidden  For example, you can specify that the value must be
-a list of 2 elements whose first element is a specific string and the
-second element is any value with a backquoted pattern like
address@hidden("first" ,second-elem)}.
address@hidden Issue: Should this be split off into its own node/subsection?
address@hidden Backquote-Style Patterns
address@hidden backquote-style patterns
+
address@hidden patterns} are a powerful set of
address@hidden pattern extensions (created using @code{pcase-defmacro})
+that make it easy to match @var{expval} against
+specifications of its @emph{structure}.
+
+For example, to match @var{expval} that must be a list of two
+elements whose first element is a specific string and the second
+element is any value, you can write a core pattern:
+
address@hidden
+(and (pred listp)
+     ls
+     (guard (= 2 (length ls)))
+     (guard (string= "first" (car ls)))
+     (let second-elem (cadr ls)))
address@hidden example
+
address@hidden
+or you can write the equivalent backquote-style pattern,
+which is more concise, resembling the structure of @var{expval},
+and avoids binding @code{ls}:
+
address@hidden
+`("first" ,second-elem)
address@hidden example
 
 Backquoted patterns have the form @address@hidden where
 @var{qpattern} can have the following forms:
@@ -944,8 +967,6 @@ Note that uses of Q-patterns can be expressed using only 
core
 patterns, as Q-patterns are implemented on top of core patterns using
 @code{pcase-defmacro}, described below.  However, using Q-patterns will
 in many cases lead to a more readable code.
address@hidden FIXME: There should be an example here showing how a 'pcase' that
address@hidden uses Q-patterns can be rewritten using core patterns.
 
 Here is an example of using @code{pcase} to implement a simple
 interpreter for a little expression language (note that this example