diff options
Diffstat (limited to 'devdocs/elisp/specification-list.html')
| -rw-r--r-- | devdocs/elisp/specification-list.html | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/devdocs/elisp/specification-list.html b/devdocs/elisp/specification-list.html new file mode 100644 index 00000000..6c43d881 --- /dev/null +++ b/devdocs/elisp/specification-list.html @@ -0,0 +1,38 @@ + <h4 class="subsubsection">Specification List</h4> <p>A <em>specification list</em> is required for an Edebug specification if some arguments of a macro call are evaluated while others are not. Some elements in a specification list match one or more arguments, but others modify the processing of all following elements. The latter, called <em>specification keywords</em>, are symbols beginning with ‘<samp>&</samp>’ (such as <code>&optional</code>). </p> <p>A specification list may contain sublists, which match arguments that are themselves lists, or it may contain vectors used for grouping. Sublists and groups thus subdivide the specification list into a hierarchy of levels. Specification keywords apply only to the remainder of the sublist or group they are contained in. </p> <p>When a specification list involves alternatives or repetition, matching it against an actual macro call may require backtracking. For more details, see <a href="backtracking">Backtracking</a>. </p> <p>Edebug specifications provide the power of regular expression matching, plus some context-free grammar constructs: the matching of sublists with balanced parentheses, recursive processing of forms, and recursion via indirect specifications. </p> <p>Here’s a table of the possible elements of a specification list, with their meanings (see <a href="specification-examples">Specification Examples</a>, for the referenced examples): </p> <dl compact> <dt><code>sexp</code></dt> <dd> +<p>A single unevaluated Lisp object, which is not instrumented. </p> </dd> <dt><code>form</code></dt> <dd> +<p>A single evaluated expression, which is instrumented. If your macro wraps the expression with <code>lambda</code> before it is evaluated, use <code>def-form</code> instead. See <code>def-form</code> below. </p> </dd> <dt><code>place</code></dt> <dd> +<p>A generalized variable. See <a href="generalized-variables">Generalized Variables</a>. </p> </dd> <dt><code>body</code></dt> <dd> +<p>Short for <code>&rest form</code>. See <code>&rest</code> below. If your macro wraps its body of code with <code>lambda</code> before it is evaluated, use <code>def-body</code> instead. See <code>def-body</code> below. </p> </dd> <dt><code>lambda-expr</code></dt> <dd> +<p>A lambda expression with no quoting. </p> </dd> <dt><code>&optional</code></dt> <dd> +<p>All following elements in the specification list are optional; as soon as one does not match, Edebug stops matching at this level. </p> <p>To make just a few elements optional, followed by non-optional elements, use <code>[&optional <var>specs</var>…]</code>. To specify that several elements must all match or none, use <code>&optional +[<var>specs</var>…]</code>. See the <code>defun</code> example. </p> </dd> <dt><code>&rest</code></dt> <dd> +<p>All following elements in the specification list are repeated zero or more times. In the last repetition, however, it is not a problem if the expression runs out before matching all of the elements of the specification list. </p> <p>To repeat only a few elements, use <code>[&rest <var>specs</var>…]</code>. To specify several elements that must all match on every repetition, use <code>&rest [<var>specs</var>…]</code>. </p> </dd> <dt><code>&or</code></dt> <dd> +<p>Each of the following elements in the specification list is an alternative. One of the alternatives must match, or the <code>&or</code> specification fails. </p> <p>Each list element following <code>&or</code> is a single alternative. To group two or more list elements as a single alternative, enclose them in <code>[…]</code>. </p> </dd> <dt><code>&not</code></dt> <dd> +<p>Each of the following elements is matched as alternatives as if by using <code>&or</code>, but if any of them match, the specification fails. If none of them match, nothing is matched, but the <code>&not</code> specification succeeds. </p> </dd> <dt><code>&define</code></dt> <dd> +<p>Indicates that the specification is for a defining form. Edebug’s definition of a defining form is a form containing one or more code forms which are saved and executed later, after the execution of the defining form. </p> <p>The defining form itself is not instrumented (that is, Edebug does not stop before and after the defining form), but forms inside it typically will be instrumented. The <code>&define</code> keyword should be the first element in a list specification. </p> </dd> <dt><code>nil</code></dt> <dd> +<p>This is successful when there are no more arguments to match at the current argument list level; otherwise it fails. See sublist specifications and the backquote example. </p> </dd> <dt><code>gate</code></dt> <dd> + <p>No argument is matched but backtracking through the gate is disabled while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See <a href="backtracking">Backtracking</a>, for more details. Also see the <code>let</code> example. </p> </dd> <dt><code>&error</code></dt> <dd> +<p><code>&error</code> should be followed by a string, an error message, in the edebug-spec; it aborts the instrumentation, displaying the message in the minibuffer. </p> </dd> <dt><code>&interpose</code></dt> <dd> +<p>Lets a function control the parsing of the remaining code. It takes the form <code>&interpose <var>spec</var> <var>fun</var> <var>args...</var></code> and means that Edebug will first match <var>spec</var> against the code and then call <var>fun</var> with the code that matched <code>spec</code>, a parsing function <var>pf</var>, and finally <var>args...</var>. The parsing function expects a single argument indicating the specification list to use to parse the remaining code. It should be called exactly once and returns the instrumented code that <var>fun</var> is expected to return. For example <code>(&interpose symbolp pcase--match-pat-args)</code> matches sexps whose first element is a symbol and then lets <code>pcase--match-pat-args</code> lookup the specs associated with that head symbol according to <code>pcase--match-pat-args</code> and pass them to the <var>pf</var> it received as argument. </p> </dd> <dt><code><var>other-symbol</var></code></dt> <dd> + <p>Any other symbol in a specification list may be a predicate or an indirect specification. </p> <p>If the symbol has an Edebug specification, this <em>indirect specification</em> should be either a list specification that is used in place of the symbol, or a function that is called to process the arguments. The specification may be defined with <code>def-edebug-elem-spec</code>: </p> <dl> <dt id="def-edebug-elem-spec">Function: <strong>def-edebug-elem-spec</strong> <em>element specification</em> +</dt> <dd><p>Define the <var>specification</var> to use in place of the symbol <var>element</var>. <var>specification</var> has to be a list. </p></dd> +</dl> <p>Otherwise, the symbol should be a predicate. The predicate is called with the argument, and if the predicate returns <code>nil</code>, the specification fails and the argument is not instrumented. </p> <p>Some suitable predicates include <code>symbolp</code>, <code>integerp</code>, <code>stringp</code>, <code>vectorp</code>, and <code>atom</code>. </p> </dd> <dt><code>[<var>elements</var>…]</code></dt> <dd> + <p>A vector of elements groups the elements into a single <em>group specification</em>. Its meaning has nothing to do with vectors. </p> </dd> <dt><code>"<var>string</var>"</code></dt> <dd> +<p>The argument should be a symbol named <var>string</var>. This specification is equivalent to the quoted symbol, <code>'<var>symbol</var></code>, where the name of <var>symbol</var> is the <var>string</var>, but the string form is preferred. </p> </dd> <dt><code>(vector <var>elements</var>…)</code></dt> <dd> +<p>The argument should be a vector whose elements must match the <var>elements</var> in the specification. See the backquote example. </p> </dd> <dt><code>(<var>elements</var>…)</code></dt> <dd> +<p>Any other list is a <em>sublist specification</em> and the argument must be a list whose elements match the specification <var>elements</var>. </p> <p>A sublist specification may be a dotted list and the corresponding list argument may then be a dotted list. Alternatively, the last <small>CDR</small> of a dotted list specification may be another sublist specification (via a grouping or an indirect specification, e.g., <code>(spec . [(more +specs…)])</code>) whose elements match the non-dotted list arguments. This is useful in recursive specifications such as in the backquote example. Also see the description of a <code>nil</code> specification above for terminating such recursion. </p> <p>Note that a sublist specification written as <code>(specs . nil)</code> is equivalent to <code>(specs)</code>, and <code>(specs . +(sublist-elements…))</code> is equivalent to <code>(specs +sublist-elements…)</code>. </p> +</dd> </dl> <p>Here is a list of additional specifications that may appear only after <code>&define</code>. See the <code>defun</code> example. </p> <dl compact> <dt><code>&name</code></dt> <dd> +<p>Extracts the name of the current defining form from the code. It takes the form <code>&name [<var>prestring</var>] <var>spec</var> +[<var>poststring</var>] <var>fun</var> <var>args...</var></code> and means that Edebug will match <var>spec</var> against the code and then call <var>fun</var> with the concatenation of the current name, <var>args...</var>, <var>prestring</var>, the code that matched <code>spec</code>, and <var>poststring</var>. If <var>fun</var> is absent, it defaults to a function that concatenates the arguments (with an <code>@</code> between the previous name and the new). </p> </dd> <dt><code>name</code></dt> <dd> +<p>The argument, a symbol, is the name of the defining form. Shorthand for <code>[&name symbolp]</code>. </p> <p>A defining form is not required to have a name field; and it may have multiple name fields. </p> </dd> <dt><code>arg</code></dt> <dd> +<p>The argument, a symbol, is the name of an argument of the defining form. However, lambda-list keywords (symbols starting with ‘<samp>&</samp>’) are not allowed. </p> </dd> <dt><code>lambda-list</code></dt> <dd> + <p>This matches a lambda list—the argument list of a lambda expression. </p> </dd> <dt><code>def-body</code></dt> <dd> +<p>The argument is the body of code in a definition. This is like <code>body</code>, described above, but a definition body must be instrumented with a different Edebug call that looks up information associated with the definition. Use <code>def-body</code> for the highest level list of forms within the definition. </p> </dd> <dt><code>def-form</code></dt> <dd><p>The argument is a single, highest-level form in a definition. This is like <code>def-body</code>, except it is used to match a single form rather than a list of forms. As a special case, <code>def-form</code> also means that tracing information is not output when the form is executed. See the <code>interactive</code> example. </p></dd> </dl><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-List.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Specification-List.html</a> + </p> +</div> |