diff options
Diffstat (limited to 'devdocs/elisp/specification-examples.html')
| -rw-r--r-- | devdocs/elisp/specification-examples.html | 36 |
1 files changed, 36 insertions, 0 deletions
diff --git a/devdocs/elisp/specification-examples.html b/devdocs/elisp/specification-examples.html new file mode 100644 index 00000000..fbd6ff5c --- /dev/null +++ b/devdocs/elisp/specification-examples.html @@ -0,0 +1,36 @@ + <h4 class="subsubsection">Specification Examples</h4> <p>It may be easier to understand Edebug specifications by studying the examples provided here. </p> <p>Consider a hypothetical macro <code>my-test-generator</code> that runs tests on supplied lists of data. Although it is Edebug’s default behavior to not instrument arguments as code, as controlled by <code>edebug-eval-macro-args</code> (see <a href="instrumenting-macro-calls">Instrumenting Macro Calls</a>), it can be useful to explicitly document that the arguments are data: </p> <div class="example"> <pre class="example">(def-edebug-spec my-test-generator (&rest sexp)) +</pre> +</div> <p>A <code>let</code> special form has a sequence of bindings and a body. Each of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the <code>gate</code> inside of the sublist to prevent backtracking once a sublist is found. </p> <div class="example"> <pre class="example">(def-edebug-spec let + ((&rest + &or symbolp (gate symbolp &optional form)) + body)) +</pre> +</div> <p>Edebug uses the following specifications for <code>defun</code> and the associated argument list and <code>interactive</code> specifications. It is necessary to handle interactive forms specially since an expression argument is actually evaluated outside of the function body. (The specification for <code>defmacro</code> is very similar to that for <code>defun</code>, but allows for the <code>declare</code> statement.) </p> <div class="example"> <pre class="example">(def-edebug-spec defun + (&define name lambda-list + [&optional stringp] ; <span class="roman">Match the doc string, if present.</span> + [&optional ("interactive" interactive)] + def-body)) + +(def-edebug-elem-spec 'lambda-list + '(([&rest arg] + [&optional ["&optional" arg &rest arg]] + &optional ["&rest" arg] + ))) + +(def-edebug-elem-spec 'interactive + '(&optional &or stringp def-form)) ; <span class="roman">Notice: <code>def-form</code></span> +</pre> +</div> <p>The specification for backquote below illustrates how to match dotted lists and use <code>nil</code> to terminate recursion. It also illustrates how components of a vector may be matched. (The actual specification defined by Edebug is a little different, and does not support dotted lists because doing so causes very deep recursion that could fail.) </p> <div class="example"> <pre class="example">(def-edebug-spec \` (backquote-form)) ; <span class="roman">Alias just for clarity.</span> + +(def-edebug-elem-spec 'backquote-form + '(&or ([&or "," ",@"] &or ("quote" backquote-form) form) + (backquote-form . [&or nil backquote-form]) + (vector &rest backquote-form) + sexp)) +</pre> +</div><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/Specification-Examples.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Specification-Examples.html</a> + </p> +</div> |