devdocs/elisp/extending-pcase.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

 <h4 class="subsection">Extending pcase</h4>  <p>The <code>pcase</code> macro supports several kinds of patterns (see <a href="pattern_002dmatching-conditional">Pattern-Matching Conditional</a>). You can add support for other kinds of patterns using the <code>pcase-defmacro</code> macro. </p> <dl> <dt id="pcase-defmacro">Macro: <strong>pcase-defmacro</strong> <em>name args [doc] &amp;rest body</em>
</dt> <dd>
<p>Define a new kind of pattern for <code>pcase</code>, to be invoked as <code>(<var>name</var> <var><span class="nolinebreak">actual-args</span></var>)</code>. The <code>pcase</code> macro expands this into a function call that evaluates <var>body</var>, whose job it is to rewrite the invoked pattern into some other pattern, in an environment where <var>args</var> are bound to <var>actual-args</var>. </p> <p>Additionally, arrange to display <var>doc</var> along with the docstring of <code>pcase</code>. By convention, <var>doc</var> should use <code>EXPVAL</code> to stand for the result of evaluating <var>expression</var> (first arg to <code>pcase</code>). </p>
</dd>
</dl> <p>Typically, <var>body</var> rewrites the invoked pattern to use more basic patterns. Although all patterns eventually reduce to core patterns, <code>body</code> need not use core patterns straight away. The following example defines two patterns, named <code>less-than</code> and <code>integer-less-than</code>. </p> <div class="example"> <pre class="example">(pcase-defmacro less-than (n)
  "Matches if EXPVAL is a number less than N."
  `(pred (&gt; ,n)))
</pre>

<pre class="example">(pcase-defmacro integer-less-than (n)
  "Matches if EXPVAL is an integer less than N."
  `(and (pred integerp)
        (less-than ,n)))
</pre>
</div> <p>Note that the docstrings mention <var>args</var> (in this case, only one: <code>n</code>) in the usual way, and also mention <code>EXPVAL</code> by convention. The first rewrite (i.e., <var>body</var> for <code>less-than</code>) uses one core pattern: <code>pred</code>. The second uses two core patterns: <code>and</code> and <code>pred</code>, as well as the newly-defined pattern <code>less-than</code>. Both use a single backquote construct (see <a href="backquote">Backquote</a>). </p><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Extending-pcase.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Extending-pcase.html</a>
  </p>
</div>