@appendix Common Lisp Compatibility
@noindent
-Following is a list of all known incompatibilities between this
+The following is a list of all known incompatibilities between this
package and Common Lisp as documented in Steele (2nd edition).
The word @code{cl-defun} is required instead of @code{defun} in order
to use extended Common Lisp argument lists in a function. Likewise,
@code{cl-defmacro} and @code{cl-function} are versions of those forms
which understand full-featured argument lists. The @code{&whole}
-keyword does not work in @code{defmacro} argument lists (except
+keyword does not work in @code{cl-defmacro} argument lists (except
inside recursive argument lists).
The @code{equal} predicate does not distinguish
between IEEE floating-point plus and minus zero. The @code{cl-equalp}
predicate has several differences with Common Lisp; @pxref{Predicates}.
-@c FIXME no longer provided by cl.
+@c FIXME consider moving to lispref
+@ignore
The @code{setf} mechanism is entirely compatible, except that
setf-methods return a list of five values rather than five
values directly. Also, the new ``@code{setf} function'' concept
(typified by @code{(defun (setf foo) @dots{})}) is not implemented.
+@end ignore
The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
with no @var{obarray} argument. In Common Lisp, this form would
treats them as part of the symbol name. Thus, while @code{mapcar}
and @code{lisp:mapcar} may refer to the same symbol in Common
Lisp, they are totally distinct in Emacs Lisp. Common Lisp
-programs which refer to a symbol by the full name sometimes
+programs that refer to a symbol by the full name sometimes
and the short name other times will not port cleanly to Emacs.
Emacs Lisp does have a concept of ``obarrays'', which are
@code{defsetf}, and @code{define-setf-method}, that allow the
user to extend generalized variables in various ways.
In Emacs, these are obsolete, replaced by various features of
-@file{gv.el} in Emacs 24.3.
-@c FIXME details.
+@file{gv.el} in Emacs 24.3. Many of the implementation
+details in the following are out-of-date.
+@c FIXME this whole section needs updating.
@defmac define-modify-macro name arglist function [doc-string]
This macro defines a ``read-modify-write'' macro similar to
@code{setf} is supposed to behave.
As a special (non-Common-Lisp) extension, a third argument of @code{t}
-to @code{defsetf} says that the @code{update-fn}'s return value is
+to @code{defsetf} says that the return value of @code{update-fn} is
not suitable, so that the above @code{setf} should be expanded to
something more like
@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
+argument. The @var{forms} should return a Lisp form that stores
the value of @var{store-var} into the generalized variable formed
by a call to @var{access-fn} with arguments described by @var{arglist}.
The @var{forms} may begin with a string which documents the @code{setf}
The Lisp form that is returned can access the arguments from
@var{arglist} and @var{store-var} in an unrestricted fashion;
-macros like @code{setf} and @code{cl-incf} which invoke this
+macros like @code{cl-incf} that invoke this
setf-method will insert temporary variables as needed to make
sure the apparent order of evaluation is preserved.
a @code{setf} to @var{access-fn} with arguments described by
@var{arglist} is expanded, the @var{forms} are evaluated and
must return a list of five items:
+@c FIXME Is this still true?
@enumerate
@item
from a call to @code{gensym}).
@item
-A Lisp form which stores the contents of the store variable into
+A Lisp form that stores the contents of the store variable into
the generalized variable, assuming the temporaries have been
bound as described above.
@item
-A Lisp form which accesses the contents of the generalized variable,
+A Lisp form that accesses the contents of the generalized variable,
assuming the temporaries have been bound.
@end enumerate
@code{defsetf}, the second return value is simply the list of
arguments in the place form, and the first return value is a
list of a corresponding number of temporary variables generated
-by @code{cl-gensym}. Macros like @code{setf} and @code{cl-incf} which
+@c FIXME I don't think this is true anymore.
+by @code{cl-gensym}. Macros like @code{cl-incf} that
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.
invoking the definition previously recorded by @code{defsetf}
or @code{define-setf-method}. The result is a list of five
values as described above. You can use this function to build
-your own @code{cl-incf}-like modify macros. (Actually, it is
-@c FIXME?
-better to use the internal functions @code{cl-setf-do-modify}
-and @code{cl-setf-do-store}, which are a bit easier to use and
-which also do a number of optimizations; consult the source
-code for the @code{cl-incf} function for a simple example.)
+your own @code{cl-incf}-like modify macros.
+@c These no longer exist.
+@ignore
+(Actually, it is better to use the internal functions
+@code{cl-setf-do-modify} and @code{cl-setf-do-store}, which are a bit
+easier to use and which also do a number of optimizations; consult the
+source code for the @code{cl-incf} function for a simple example.)
+@end ignore
The argument @var{env} specifies the ``environment'' to be
passed on to @code{macroexpand} if @code{get-setf-method} should
an @code{&environment} argument to the macro or setf-method
that called @code{get-setf-method}.
+@c FIXME No longer true.
See also the source code for the setf-method for
@c Also @code{apply}, but that is commented out.
@code{substring}, which works by calling @code{get-setf-method} on a
simpler case, then massaging the result.
@end defun
+@c FIXME does not belong here any more, maybe in lispref?
Modern Common Lisp defines a second, independent way to specify
the @code{setf} behavior of a function, namely ``@code{setf}
functions'' whose names are lists @code{(setf @var{name})}
HCoop / bpt / emacs.git / commitdiff