From 3a4d19175aaf8ba6d43dac0bb2be703def774bd8 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 3 Nov 2012 11:23:38 -0700 Subject: [PATCH] More general edits for cl.texi Appendices --- doc/misc/cl.texi | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 593985edbfc..1b1a3f9836f 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -4479,25 +4479,27 @@ referenced by @code{cl-return} or @code{cl-return-from} inside the block. @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 @@ -4630,7 +4632,7 @@ However, the Emacs parser does not understand colons and just 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 @@ -4917,8 +4919,9 @@ 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. 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 @@ -4987,7 +4990,7 @@ Otherwise, the above expansion would not obey the rules for the way @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 @@ -5010,7 +5013,7 @@ suite of setf methods, are: @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} @@ -5026,7 +5029,7 @@ For example, the simple form of @code{defsetf} is shorthand for 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. @@ -5043,6 +5046,7 @@ 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 must return a list of five items: +@c FIXME Is this still true? @enumerate @item @@ -5058,12 +5062,12 @@ A list of exactly one @dfn{store variable} (generally obtained 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 @@ -5079,7 +5083,8 @@ temporary variables. In the setf-methods generated by @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. @@ -5090,12 +5095,14 @@ This function returns the setf-method for @var{place}, by 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 @@ -5103,12 +5110,14 @@ need to expand a macro in @var{place}. It should come from 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})} -- 2.39.2