new repository

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 (&amp;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
+  ((&amp;rest
+    &amp;or symbolp (gate symbolp &amp;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
+  (&amp;define name lambda-list
+           [&amp;optional stringp]   ; <span class="roman">Match the doc string, if present.</span>
+           [&amp;optional ("interactive" interactive)]
+           def-body))
+
+(def-edebug-elem-spec 'lambda-list
+  '(([&amp;rest arg]
+     [&amp;optional ["&amp;optional" arg &amp;rest arg]]
+     &amp;optional ["&amp;rest" arg]
+     )))
+
+(def-edebug-elem-spec 'interactive
+  '(&amp;optional &amp;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
+  '(&amp;or ([&amp;or "," ",@"] &amp;or ("quote" backquote-form) form)
+        (backquote-form . [&amp;or nil backquote-form])
+        (vector &amp;rest backquote-form)
+        sexp))
+</pre>
+</div><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/Specification-Examples.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Specification-Examples.html</a>
+  </p>
+</div>