From e11174254bab35ec88a8dfb483bd49104773d051 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 27 Oct 2012 15:54:53 -0700 Subject: [PATCH] * doc/misc/cl.texi: Use defmac for macros rather than defspec. (Efficiency Concerns): Related copyedit. --- doc/misc/ChangeLog | 3 + doc/misc/cl.texi | 238 ++++++++++++++++++++++----------------------- 2 files changed, 121 insertions(+), 120 deletions(-) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index d447b0ca1ff..24d8f1cee25 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,5 +1,8 @@ 2012-10-27 Glenn Morris + * cl.texi: Use defmac for macros rather than defspec. + (Efficiency Concerns): Related copyedit. + * cl.texi (Control Structure): Update for setf now being in core. (Setf Extensions): Rename from Basic Setf. Move much of the former content to lispref/variables.texi. diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index aba3f244012..09386e2c0c7 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -268,14 +268,14 @@ this package to implement Common Lisp argument lists seamlessly. Instead, this package defines alternates for several Lisp forms which you must use if you need Common Lisp argument lists. -@defspec cl-defun name arglist body... +@defmac cl-defun name arglist body... This form is identical to the regular @code{defun} form, except that @var{arglist} is allowed to be a full Common Lisp argument list. Also, the function body is enclosed in an implicit block called @var{name}; @pxref{Blocks and Exits}. -@end defspec +@end defmac -@defspec cl-defsubst name arglist body... +@defmac cl-defsubst name arglist body... This is just like @code{cl-defun}, except that the function that is defined is automatically proclaimed @code{inline}, i.e., calls to it may be expanded into in-line code by the byte compiler. @@ -285,9 +285,9 @@ works in all versions of Emacs, and also generates somewhat more efficient inline expansions. In particular, @code{cl-defsubst} arranges for the processing of keyword arguments, default values, etc., to be done at compile-time whenever possible. -@end defspec +@end defmac -@defspec cl-defmacro name arglist body... +@defmac cl-defmacro name arglist body... This is identical to the regular @code{defmacro} form, except that @var{arglist} is allowed to be a full Common Lisp argument list. The @code{&environment} keyword is supported as @@ -296,13 +296,13 @@ within destructured lists (see below); top-level @code{&whole} cannot be implemented with the current Emacs Lisp interpreter. The macro expander body is enclosed in an implicit block called @var{name}. -@end defspec +@end defmac -@defspec cl-function symbol-or-lambda +@defmac cl-function symbol-or-lambda This is identical to the regular @code{function} form, except that if the argument is a @code{lambda} form then that form may use a full Common Lisp argument list. -@end defspec +@end defmac Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined in this package that include @var{arglist}s in their syntax allow @@ -491,7 +491,7 @@ For example, the compiler effectively evaluates @code{defmacro} forms at compile-time so that later parts of the file can refer to the macros that are defined. -@defspec cl-eval-when (situations...) forms... +@defmac cl-eval-when (situations...) forms... This form controls when the body @var{forms} are evaluated. The @var{situations} list may contain any set of the symbols @code{compile}, @code{load}, and @code{eval} (or their long-winded @@ -563,7 +563,7 @@ to @code{(progn @dots{})} in all contexts. The compiler treats certain top-level forms, like @code{defmacro} (sort-of) and @code{require}, as if they were wrapped in @code{(cl-eval-when (compile load eval) @dots{})}. -@end defspec +@end defmac Emacs includes two special forms related to @code{cl-eval-when}. One of these, @code{eval-when-compile}, is not quite equivalent to @@ -573,7 +573,7 @@ The other form, @code{(eval-and-compile @dots{})}, is exactly equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and so is not itself defined by this package. -@defspec eval-when-compile forms... +@defmac eval-when-compile forms... The @var{forms} are evaluated at compile-time; at execution time, this form acts like a quoted constant of the resulting value. Used at top-level, @code{eval-when-compile} is just like @samp{eval-when @@ -582,9 +582,9 @@ allows code to be evaluated once at compile-time for efficiency or other reasons. This form is similar to the @samp{#.} syntax of true Common Lisp. -@end defspec +@end defmac -@defspec cl-load-time-value form +@defmac cl-load-time-value form The @var{form} is evaluated at load-time; at execution time, this form acts like a quoted constant of the resulting value. @@ -625,7 +625,7 @@ Byte-compiled, the above defun will result in the following code ", and loaded on: " --temp--)) @end example -@end defspec +@end defmac @node Predicates @chapter Predicates @@ -733,7 +733,7 @@ floats. In all other circumstances, @code{cl-coerce} signals an error. @end defun -@defspec cl-deftype name arglist forms... +@defmac cl-deftype name arglist forms... This macro defines a new type called @var{name}. It is similar to @code{defmacro} in many ways; when @var{name} is encountered as a type name, the body @var{forms} are evaluated and should @@ -761,7 +761,7 @@ unsigned-byte @equiv{} (integer 0 *) The last example shows how the Common Lisp @code{unsigned-byte} type specifier could be implemented if desired; this package does not implement @code{unsigned-byte} by default. -@end defspec +@end defmac The @code{cl-typecase} and @code{cl-check-type} macros also use type names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map}, @@ -826,7 +826,7 @@ constructs. The @code{cl-psetq} form is just like @code{setq}, except that multiple assignments are done in parallel rather than sequentially. -@defspec cl-psetq [symbol form]@dots{} +@defmac cl-psetq [symbol form]@dots{} This special form (actually a macro) is used to assign to several variables simultaneously. Given only one @var{symbol} and @var{form}, it has the same effect as @code{setq}. Given several @var{symbol} @@ -854,7 +854,7 @@ provides an even more convenient way to swap two variables; @pxref{Modify Macros}.) @code{cl-psetq} always returns @code{nil}. -@end defspec +@end defmac @node Generalized Variables @section Generalized Variables @@ -1010,15 +1010,15 @@ This package defines a number of macros that operate on generalized variables. Many are interesting and useful even when the @var{place} is just a variable name. -@defspec cl-psetf [place form]@dots{} +@defmac cl-psetf [place form]@dots{} This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}: When several @var{place}s and @var{form}s are involved, the assignments take place in parallel rather than sequentially. Specifically, all subforms are evaluated from left to right, then all the assignments are done (in an undefined order). -@end defspec +@end defmac -@defspec cl-incf place &optional x +@defmac cl-incf place &optional x This macro increments the number stored in @var{place} by one, or by @var{x} if specified. The incremented value is returned. For example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and @@ -1057,22 +1057,22 @@ the other generalized-variable macros. As a more Emacs-specific example of @code{cl-incf}, the expression @code{(cl-incf (point) @var{n})} is essentially equivalent to @code{(forward-char @var{n})}. -@end defspec +@end defmac -@defspec cl-decf place &optional x +@defmac cl-decf place &optional x This macro decrements the number stored in @var{place} by one, or by @var{x} if specified. -@end defspec +@end defmac -@defspec cl-pushnew x place @t{&key :test :test-not :key} +@defmac cl-pushnew x place @t{&key :test :test-not :key} This macro inserts @var{x} at the front of the list stored in @var{place}, but only if @var{x} was not @code{eql} to any existing element of the list. The optional keyword arguments are interpreted in the same way as for @code{cl-adjoin}. @xref{Lists as Sets}. -@end defspec +@end defmac -@defspec cl-shiftf place@dots{} newvalue +@defmac cl-shiftf place@dots{} newvalue This macro shifts the @var{place}s left by one, shifting in the value of @var{newvalue} (which may be any Lisp expression, not just a generalized variable), and returning the value shifted out of @@ -1090,9 +1090,9 @@ the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c} @noindent except that the subforms of @var{a}, @var{b}, and @var{c} are actually evaluated only once each and in the apparent order. -@end defspec +@end defmac -@defspec cl-rotatef place@dots{} +@defmac cl-rotatef place@dots{} This macro rotates the @var{place}s left by one in circular fashion. Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to @@ -1107,12 +1107,12 @@ Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to except for the evaluation of subforms. @code{cl-rotatef} always returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})} conveniently exchanges @var{a} and @var{b}. -@end defspec +@end defmac The following macros were invented for this package; they have no analogues in Common Lisp. -@defspec letf (bindings@dots{}) forms@dots{} +@defmac letf (bindings@dots{}) forms@dots{} This macro is analogous to @code{let}, but for generalized variables rather than just symbols. Each @var{binding} should be of the form @code{(@var{place} @var{value})}; the original contents of the @@ -1162,14 +1162,14 @@ entry to the @code{letf} form. The only exceptions are plain variables and calls to @code{symbol-value} and @code{symbol-function}. If the symbol is not bound on entry, it is simply made unbound by @code{makunbound} or @code{fmakunbound} on exit. -@end defspec +@end defmac -@defspec cl-letf* (bindings@dots{}) forms@dots{} +@defmac cl-letf* (bindings@dots{}) forms@dots{} This macro is to @code{letf} what @code{let*} is to @code{let}: It does the bindings in sequential rather than parallel order. -@end defspec +@end defmac -@defspec cl-callf @var{function} @var{place} @var{args}@dots{} +@defmac cl-callf @var{function} @var{place} @var{args}@dots{} This is the ``generic'' modify macro. It calls @var{function}, which should be an unquoted function name, macro name, or lambda. It passes @var{place} and @var{args} as arguments, and assigns the @@ -1186,14 +1186,14 @@ Some more examples: @xref{Customizing Setf}, for @code{define-modify-macro}, a way to create even more concise notations for modify macros. Note again that @code{cl-callf} is an extension to standard Common Lisp. -@end defspec +@end defmac -@defspec cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} +@defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} This macro is like @code{cl-callf}, except that @var{place} is the @emph{second} argument of @var{function} rather than the first. For example, @code{(push @var{x} @var{place})} is equivalent to @code{(cl-callf2 cons @var{x} @var{place})}. -@end defspec +@end defmac The @code{cl-callf} and @code{cl-callf2} macros serve as building blocks for other macros like @code{cl-incf}, @code{cl-pushnew}, and @@ -1209,7 +1209,7 @@ Common Lisp defines three macros, @code{define-modify-macro}, @code{defsetf}, and @code{define-setf-method}, that allow the user to extend generalized variables in various ways. -@defspec define-modify-macro name arglist function [doc-string] +@defmac define-modify-macro name arglist function [doc-string] This macro defines a ``read-modify-write'' macro similar to @code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined to take a @var{place} argument followed by additional arguments @@ -1249,9 +1249,9 @@ follow the pattern of @code{define-modify-macro}. For example, is completely irregular. You can define these macros ``by hand'' using @code{get-setf-method}, or consult the source to see how to use the internal @code{setf} building blocks. -@end defspec +@end defmac -@defspec defsetf access-fn update-fn +@defmac defsetf access-fn update-fn This is the simpler of two @code{defsetf} forms. Where @var{access-fn} is the name of a function which accesses a place, this declares @var{update-fn} to be the corresponding store @@ -1294,9 +1294,9 @@ suite of setf methods, are: (defsetf symbol-value set) (defsetf buffer-name rename-buffer t) @end example -@end defspec +@end defmac -@defspec defsetf access-fn arglist (store-var) forms@dots{} +@defmac defsetf access-fn arglist (store-var) forms@dots{} This is the second, more complex, form of @code{defsetf}. It is rather like @code{defmacro} except for the additional @var{store-var} argument. The @var{forms} should return a Lisp form which stores @@ -1325,9 +1325,9 @@ Another example drawn from the standard package: (defsetf nth (n x) (store) (list 'setcar (list 'nthcdr n x) store)) @end example -@end defspec +@end defmac -@defspec define-setf-method access-fn arglist forms@dots{} +@defmac define-setf-method access-fn arglist forms@dots{} This is the most general way to create new place forms. When a @code{setf} to @var{access-fn} with arguments described by @var{arglist} is expanded, the @var{forms} are evaluated and @@ -1372,7 +1372,7 @@ by @code{cl-gensym}. Macros like @code{setf} and @code{cl-incf} which use this setf-method will optimize away most temporaries that turn out to be unnecessary, so there is little reason for the setf-method itself to optimize. -@end defspec +@end defmac @defun get-setf-method place &optional env This function returns the setf-method for @var{place}, by @@ -1435,7 +1435,7 @@ The standard @code{let} form binds variables whose names are known at compile-time. The @code{cl-progv} form provides an easy way to bind variables whose names are computed at run-time. -@defspec cl-progv symbols values forms@dots{} +@defmac cl-progv symbols values forms@dots{} This form establishes @code{let}-style variable bindings on a set of variables computed at run-time. The expressions @var{symbols} and @var{values} are evaluated, and must return lists @@ -1445,7 +1445,7 @@ If @var{values} is shorter than @var{symbols}, the last few symbols are bound to @code{nil}. If @var{symbols} is shorter than @var{values}, the excess values are ignored. -@end defspec +@end defmac @node Lexical Bindings @subsection Lexical Bindings @@ -1454,7 +1454,7 @@ are ignored. The @code{CL} package defines the following macro which more closely follows the Common Lisp @code{let} form: -@defspec lexical-let (bindings@dots{}) forms@dots{} +@defmac lexical-let (bindings@dots{}) forms@dots{} This form is exactly like @code{let} except that the bindings it establishes are purely lexical. Lexical bindings are similar to local variables in a language like C: Only the code physically @@ -1554,12 +1554,12 @@ instance of the lexical variable. The @code{lexical-let} form is an extension to Common Lisp. In true Common Lisp, all bindings are lexical unless declared otherwise. -@end defspec +@end defmac -@defspec lexical-let* (bindings@dots{}) forms@dots{} +@defmac lexical-let* (bindings@dots{}) forms@dots{} This form is just like @code{lexical-let}, except that the bindings are made sequentially in the manner of @code{let*}. -@end defspec +@end defmac @node Function Bindings @subsection Function Bindings @@ -1568,7 +1568,7 @@ are made sequentially in the manner of @code{let*}. These forms make @code{let}-like bindings to functions instead of variables. -@defspec flet (bindings@dots{}) forms@dots{} +@defmac flet (bindings@dots{}) forms@dots{} This form establishes @code{let}-style bindings on the function cells of symbols rather than on the value cells. Each @var{binding} must be a list of the form @samp{(@var{name} @var{arglist} @@ -1612,9 +1612,9 @@ Functions defined by @code{flet} may use the full Common Lisp argument notation supported by @code{cl-defun}; also, the function body is enclosed in an implicit block as if by @code{cl-defun}. @xref{Program Structure}. -@end defspec +@end defmac -@defspec labels (bindings@dots{}) forms@dots{} +@defmac labels (bindings@dots{}) forms@dots{} The @code{labels} form is like @code{flet}, except that it makes lexical bindings of the function names rather than dynamic bindings. (In true Common Lisp, both @code{flet} and @@ -1635,7 +1635,7 @@ functions. A ``reference'' to a function name is either a call to that function, or a use of its name quoted by @code{quote} or @code{function} to be passed on to, say, @code{mapcar}. -@end defspec +@end defmac @node Macro Bindings @subsection Macro Bindings @@ -1643,7 +1643,7 @@ function, or a use of its name quoted by @code{quote} or @noindent These forms create local macros and ``symbol macros''. -@defspec cl-macrolet (bindings@dots{}) forms@dots{} +@defmac cl-macrolet (bindings@dots{}) forms@dots{} This form is analogous to @code{flet}, but for macros instead of functions. Each @var{binding} is a list of the same form as the arguments to @code{cl-defmacro} (i.e., a macro name, argument list, @@ -1655,9 +1655,9 @@ scoped even in Emacs Lisp: The @code{cl-macrolet} binding will affect only calls that appear physically within the body @var{forms}, possibly after expansion of other macros in the body. -@end defspec +@end defmac -@defspec cl-symbol-macrolet (bindings@dots{}) forms@dots{} +@defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{} This form creates @dfn{symbol macros}, which are macros that look like variable references rather than function calls. Each @var{binding} is a list @samp{(@var{var} @var{expansion})}; @@ -1723,7 +1723,7 @@ which in turn expands to @xref{Loop Facility}, for a description of the @code{cl-loop} macro. This package defines a nonstandard @code{in-ref} loop clause that works much like @code{my-dolist}. -@end defspec +@end defmac @node Conditionals @section Conditionals @@ -1732,7 +1732,7 @@ works much like @code{my-dolist}. These conditional forms augment Emacs Lisp's simple @code{if}, @code{and}, @code{or}, and @code{cond} forms. -@defspec cl-case keyform clause@dots{} +@defmac cl-case keyform clause@dots{} This macro evaluates @var{keyform}, then compares it with the key values listed in the various @var{clause}s. Whichever clause matches the key is executed; comparison is done by @code{eql}. If no clause @@ -1766,15 +1766,15 @@ a @key{RET} or @kbd{C-j}, or anything else. ((?\r ?\n) (do-ret-thing)) (t (do-other-thing))) @end example -@end defspec +@end defmac -@defspec cl-ecase keyform clause@dots{} +@defmac cl-ecase keyform clause@dots{} This macro is just like @code{cl-case}, except that if the key does not match any of the clauses, an error is signaled rather than simply returning @code{nil}. -@end defspec +@end defmac -@defspec cl-typecase keyform clause@dots{} +@defmac cl-typecase keyform clause@dots{} This macro is a version of @code{cl-case} that checks for types rather than values. Each @var{clause} is of the form @samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, @@ -1791,13 +1791,13 @@ for a description of type specifiers. For example, The type specifier @code{t} matches any type of object; the word @code{otherwise} is also allowed. To make one clause match any of several types, use an @code{(or ...)} type specifier. -@end defspec +@end defmac -@defspec cl-etypecase keyform clause@dots{} +@defmac cl-etypecase keyform clause@dots{} This macro is just like @code{cl-typecase}, except that if the key does not match any of the clauses, an error is signaled rather than simply returning @code{nil}. -@end defspec +@end defmac @node Blocks and Exits @section Blocks and Exits @@ -1810,7 +1810,7 @@ in terms of @code{catch}; however, the lexical scoping allows the optimizing byte-compiler to omit the costly @code{catch} step if the body of the block does not actually @code{cl-return-from} the block. -@defspec cl-block name forms@dots{} +@defmac cl-block name forms@dots{} The @var{forms} are evaluated as if by a @code{progn}. However, if any of the @var{forms} execute @code{(cl-return-from @var{name})}, they will jump out and return directly from the @code{cl-block} form. @@ -1849,20 +1849,20 @@ not in fact contain any @code{cl-return} or @code{cl-return-from} calls that jump to it. This means that @code{cl-do} loops and @code{cl-defun} functions which don't use @code{cl-return} don't pay the overhead to support it. -@end defspec +@end defmac -@defspec cl-return-from name [result] +@defmac cl-return-from name [result] This macro returns from the block named @var{name}, which must be an (unevaluated) symbol. If a @var{result} form is specified, it is evaluated to produce the result returned from the @code{block}. Otherwise, @code{nil} is returned. -@end defspec +@end defmac -@defspec cl-return [result] +@defmac cl-return [result] This macro is exactly like @code{(cl-return-from nil @var{result})}. Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose themselves in @code{nil} blocks. -@end defspec +@end defmac @node Iteration @section Iteration @@ -1872,7 +1872,7 @@ The macros described here provide more sophisticated, high-level looping constructs to complement Emacs Lisp's basic @code{while} loop. -@defspec cl-loop forms@dots{} +@defmac cl-loop forms@dots{} The @code{CL} package supports both the simple, old-style meaning of @code{loop} and the extremely powerful and flexible feature known as the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced @@ -1900,9 +1900,9 @@ interpreted as a Loop Macro specification as described later. (This is not a restriction in practice, since a plain symbol in the above notation would simply access and throw away the value of a variable.) -@end defspec +@end defmac -@defspec cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +@defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} This macro creates a general iterative loop. Each @var{spec} is of the form @@ -1948,9 +1948,9 @@ the rest of the loop. ((or (null x) (null y)) (nreverse z))) @end example -@end defspec +@end defmac -@defspec cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +@defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} This is to @code{cl-do} what @code{let*} is to @code{let}. In particular, the initial values are bound as if by @code{let*} rather than @code{let}, and the steps are assigned as if by @@ -1968,9 +1968,9 @@ Here is another way to write the above loop: (nreverse z)) (push (f x y) z)) @end example -@end defspec +@end defmac -@defspec cl-dolist (var list [result]) forms@dots{} +@defmac cl-dolist (var list [result]) forms@dots{} This is a more specialized loop which iterates across the elements of a list. @var{list} should evaluate to a list; the body @var{forms} are executed with @var{var} bound to each element of the list in @@ -1978,9 +1978,9 @@ turn. Finally, the @var{result} form (or @code{nil}) is evaluated with @var{var} bound to @code{nil} to produce the result returned by the loop. Unlike with Emacs's built in @code{dolist}, the loop is surrounded by an implicit @code{nil} block. -@end defspec +@end defmac -@defspec cl-dotimes (var count [result]) forms@dots{} +@defmac cl-dotimes (var count [result]) forms@dots{} This is a more specialized loop which iterates a specified number of times. The body is executed with @var{var} bound to the integers from zero (inclusive) to @var{count} (exclusive), in turn. Then @@ -1988,9 +1988,9 @@ the @code{result} form is evaluated with @var{var} bound to the total number of iterations that were done (i.e., @code{(max 0 @var{count})}) to get the return value for the loop form. Unlike with Emacs's built in @code{dolist}, the loop is surrounded by an implicit @code{nil} block. -@end defspec +@end defmac -@defspec cl-do-symbols (var [obarray [result]]) forms@dots{} +@defmac cl-do-symbols (var [obarray [result]]) forms@dots{} This loop iterates over all interned symbols. If @var{obarray} is specified and is not @code{nil}, it loops over all symbols in that obarray. For each symbol, the body @var{forms} are evaluated @@ -1998,12 +1998,12 @@ with @var{var} bound to that symbol. The symbols are visited in an unspecified order. Afterward the @var{result} form, if any, is evaluated (with @var{var} bound to @code{nil}) to get the return value. The loop is surrounded by an implicit @code{nil} block. -@end defspec +@end defmac -@defspec cl-do-all-symbols (var [result]) forms@dots{} +@defmac cl-do-all-symbols (var [result]) forms@dots{} This is identical to @code{cl-do-symbols} except that the @var{obarray} argument is omitted; it always iterates over the default obarray. -@end defspec +@end defmac @xref{Mapping over Sequences}, for some more functions for iterating over vectors or lists. @@ -2043,7 +2043,7 @@ Since @code{cl-loop} is a macro, all parsing of the loop language takes place at byte-compile time; compiled @code{cl-loop}s are just as efficient as the equivalent @code{while} loops written longhand. -@defspec cl-loop clauses@dots{} +@defmac cl-loop clauses@dots{} A loop construct consists of a series of @var{clause}s, each introduced by a symbol like @code{for} or @code{do}. Clauses are simply strung together in the argument list of @code{cl-loop}, @@ -2082,7 +2082,7 @@ explicit @code{return} clause to jump out of the implicit block. (Because the loop body is enclosed in an implicit block, you can also use regular Lisp @code{cl-return} or @code{cl-return-from} to break out of the loop.) -@end defspec +@end defmac The following sections give some examples of the Loop Macro in action, and describe the particular loop clauses in great detail. @@ -2773,21 +2773,21 @@ in Emacs Lisp these functions simply operate on lists instead. The @code{values} form, for example, is a synonym for @code{list} in Emacs. -@defspec cl-multiple-value-bind (var@dots{}) values-form forms@dots{} +@defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{} This form evaluates @var{values-form}, which must return a list of values. It then binds the @var{var}s to these respective values, as if by @code{let}, and then executes the body @var{forms}. If there are more @var{var}s than values, the extra @var{var}s are bound to @code{nil}. If there are fewer @var{var}s than values, the excess values are ignored. -@end defspec +@end defmac -@defspec cl-multiple-value-setq (var@dots{}) form +@defmac cl-multiple-value-setq (var@dots{}) form This form evaluates @var{form}, which must return a list of values. It then sets the @var{var}s to these respective values, as if by @code{setq}. Extra @var{var}s or values are treated the same as in @code{cl-multiple-value-bind}. -@end defspec +@end defmac Since a perfect emulation is not feasible in Emacs Lisp, this package opts to keep it as simple and predictable as possible. @@ -2805,7 +2805,7 @@ for @code{defmacro} due to technical difficulties. Destructuring is made available to the user by way of the following macro: -@defspec cl-destructuring-bind arglist expr forms@dots{} +@defmac cl-destructuring-bind arglist expr forms@dots{} This macro expands to code which executes @var{forms}, with the variables in @var{arglist} bound to the list of values returned by @var{expr}. The @var{arglist} can include all @@ -2814,13 +2814,13 @@ including destructuring. (The @code{&environment} keyword is not allowed.) The macro expansion will signal an error if @var{expr} returns a list of the wrong number of arguments or with incorrect keyword arguments. -@end defspec +@end defmac This package also includes the Common Lisp @code{cl-define-compiler-macro} facility, which allows you to define compile-time expansions and optimizations for your functions. -@defspec cl-define-compiler-macro name arglist forms@dots{} +@defmac cl-define-compiler-macro name arglist forms@dots{} This form is similar to @code{defmacro}, except that it only expands calls to @var{name} at compile-time; calls processed by the Lisp interpreter are not expanded, nor are they expanded by the @@ -2854,7 +2854,7 @@ if there are any keyword arguments in the call, then the original @code{cl-member} call is left intact. (The actual compiler macro for @code{cl-member} optimizes a number of other cases, including common @code{:test} predicates.) -@end defspec +@end defmac @defun cl-compiler-macroexpand form This function is analogous to @code{macroexpand}, except that it @@ -2896,7 +2896,7 @@ This function records a ``global'' declaration specified by is evaluated and thus should normally be quoted. @end defun -@defspec cl-declaim decl-specs@dots{} +@defmac cl-declaim decl-specs@dots{} This macro is like @code{cl-proclaim}, except that it takes any number of @var{decl-spec} arguments, and the arguments are unevaluated and unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when @@ -2905,22 +2905,22 @@ be registered at compile-time as well as at run-time. (This is vital, since normally the declarations are meant to influence the way the compiler treats the rest of the file that contains the @code{cl-declaim} form.) -@end defspec +@end defmac -@defspec cl-declare decl-specs@dots{} +@defmac cl-declare decl-specs@dots{} This macro is used to make declarations within functions and other code. Common Lisp allows declarations in various locations, generally at the beginning of any of the many ``implicit @code{progn}s'' throughout Lisp syntax, such as function bodies, @code{let} bodies, etc. Currently the only declaration understood by @code{cl-declare} is @code{special}. -@end defspec +@end defmac -@defspec cl-locally declarations@dots{} forms@dots{} +@defmac cl-locally declarations@dots{} forms@dots{} In this package, @code{cl-locally} is no different from @code{progn}. -@end defspec +@end defmac -@defspec cl-the type form +@defmac cl-the type form Type information provided by @code{cl-the} is ignored in this package; in other words, @code{(cl-the @var{type} @var{form})} is equivalent to @var{form}. Future versions of the optimizing byte-compiler may @@ -2933,7 +2933,7 @@ of time. With @code{(mapcar 'car (cl-the vector foo))}, a future compiler would have enough information to expand the loop in-line. For now, Emacs Lisp will treat the above code as exactly equivalent to @code{(mapcar 'car foo)}. -@end defspec +@end defmac Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or @code{cl-declare} should be a list beginning with a symbol that says @@ -3137,7 +3137,7 @@ function and its @var{place} argument can actually be any Lisp expression. @end defun -@defspec cl-remf place property +@defmac cl-remf place property This macro removes the property-value pair for @var{property} from the property list stored at @var{place}, which is any @code{setf}-able place expression. It returns true if the property was found. Note @@ -3145,7 +3145,7 @@ that if @var{property} happens to be first on the list, this will effectively do a @code{(setf @var{place} (cddr @var{place}))}, whereas if it occurs later, this simply uses @code{setcdr} to splice out the property and value cells. -@end defspec +@end defmac @node Creating Symbols @section Creating Symbols @@ -4259,7 +4259,7 @@ system provides no way to create new distinct types, this package implements structures as vectors (or lists upon request) with a special ``tag'' symbol to identify them. -@defspec cl-defstruct name slots@dots{} +@defmac cl-defstruct name slots@dots{} The @code{cl-defstruct} form defines a new structure type called @var{name}, with the specified @var{slots}. (The @var{slots} may begin with a string which documents the structure type.) @@ -4563,7 +4563,7 @@ the type @code{:include}s another type, then @code{:initial-offset} specifies a number of slots to be skipped between the last slot of the included type and the first new slot. @end table -@end defspec +@end defmac Except as noted, the @code{cl-defstruct} facility of this package is entirely compatible with that of Common Lisp. @@ -4582,7 +4582,7 @@ If the optimization property @code{speed} has been set to 3, and away the following assertions. Because assertions might be optimized away, it is a bad idea for them to include side-effects. -@defspec cl-assert test-form [show-args string args@dots{}] +@defmac cl-assert test-form [show-args string args@dots{}] This form verifies that @var{test-form} is true (i.e., evaluates to a non-@code{nil} value). If so, it returns @code{nil}. If the test is not satisfied, @code{cl-assert} signals an error. @@ -4606,9 +4606,9 @@ true Common Lisp, the second argument gives a list of @var{places} which can be @code{setf}'d by the user before continuing from the error. Since Emacs Lisp does not support continuable errors, it makes no sense to specify @var{places}. -@end defspec +@end defmac -@defspec cl-check-type form type [string] +@defmac cl-check-type form type [string] This form verifies that @var{form} evaluates to a value of type @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type} signals a @code{wrong-type-argument} error. The default error message @@ -4627,7 +4627,7 @@ Note that in Common Lisp, the first argument to @code{check-type} must be a @var{place} suitable for use by @code{setf}, because @code{check-type} signals a continuable error that allows the user to modify @var{place}. -@end defspec +@end defmac @node Efficiency Concerns @appendix Efficiency Concerns @@ -4660,12 +4660,10 @@ readable @code{cl-incf} form in your compiled code. @emph{Interpreted} code, on the other hand, must expand these macros every time they are executed. For this reason it is strongly recommended that code making heavy use of macros be compiled. -@c FIXME why are they not labelled as macros? -(The features labeled ``Special Form'' instead of ``Function'' in -this manual are macros.) A loop using @code{cl-incf} a hundred times -will execute considerably faster if compiled, and will also -garbage-collect less because the macro expansion will not have -to be generated, used, and thrown away a hundred times. +A loop using @code{cl-incf} a hundred times will execute considerably +faster if compiled, and will also garbage-collect less because the +macro expansion will not have to be generated, used, and thrown away a +hundred times. You can find out how a macro expands by using the @code{cl-prettyexpand} function. -- 2.39.2