[Emacs-diffs] fix/bug-31311-pcase-doc 4d4df12 5/9: expand text post ‘defmac pcase-defmacro’

[Thien-Thi Nguyen]

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

    expand text post ‘defmac pcase-defmacro’
    
    - explain typical BODY duty
    - use "more basic pattern"
    - explain non-necessity of goto-core
    - add example w/ explanation
---
 doc/lispref/control.texi | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 6444338..14446f5 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -870,6 +870,39 @@ to stand for the result of
 evaluating @var{expression} (first arg to @code{pcase}).
 @end defmac
 
address@hidden
+Typically, @var{body} rewrites the invoked pattern
+to use more basic patterns.
+Although all patterns eventually reduce to core patterns,
address@hidden need not use core patterns straight away.
+The following example defines two patterns, named
address@hidden and @code{integer-less-than}.
+
address@hidden
address@hidden
+(pcase-defmacro less-than (n)
+  "Matches if EXPVAL is a number less than N."
+  `(pred (> ,n)))
address@hidden group
+
address@hidden
+(pcase-defmacro integer-less-than (n)
+  "Matches if EXPVAL is an integer less than N."
+  `(and (pred integerp)
+        (less-than ,n)))
address@hidden group
address@hidden example
+
address@hidden
+Note that the docstrings mention @var{args}
+(in this case, only one: @code{n}) in the usual way,
+and also mention @code{EXPVAL} by convention.
+The first rewrite (i.e., @var{body} for @code{less-than})
+uses one core pattern: @code{pred}.
+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
 @emph{structure}.  For example, you can specify that the value must be