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.
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
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
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
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
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
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.
", and loaded on: "
--temp--))
@end example
-@end defspec
+@end defmac
@node Predicates
@chapter Predicates
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
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},
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}
@pxref{Modify Macros}.)
@code{cl-psetq} always returns @code{nil}.
-@end defspec
+@end defmac
@node Generalized Variables
@section Generalized Variables
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
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
@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
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
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
@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
@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
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
(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
(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
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
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
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
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
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
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}
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
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
@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,
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})};
@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
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
((?\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},
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
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.
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
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
(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
((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
(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
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
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
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.
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},
(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.
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.
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
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
@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
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
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
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
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
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
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.)
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.
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.
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
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
@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.
projects / emacs.git / commitdiff