From: Glenn Morris Date: Mon, 29 Oct 2012 01:29:22 +0000 (-0700) Subject: Move some cl.texi setf extensions to the Obsolete appendix X-Git-Tag: emacs-24.2.90~209^2~25 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d571e9c385d648a90581e2c5cd1a883b8c0ea0e4;p=emacs.git Move some cl.texi setf extensions to the Obsolete appendix * doc/misc/cl.texi (Customizing Setf): Move contents to "Obsolete Setf Customization". (Modify Macros, Multiple Values): Remove mentions of obsolete feature. --- diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 9aeaf87426e..e85e18ff5c7 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -2,6 +2,8 @@ * cl.texi (Organization): More details on cl-lib.el versus cl.el. (Setf Extensions): Remove `apply' setf since it seems to be disabled. + (Customizing Setf): Move contents to "Obsolete Setf Customization". + (Modify Macros, Multiple Values): Remove mentions of obsolete feature. 2012-10-28 Glenn Morris diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index b77dfcd94be..086cc25fbcc 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -883,7 +883,6 @@ generalized variables. @menu * Setf Extensions:: Additional @code{setf} places. * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc. -* Customizing Setf:: @code{define-modify-macro}, @code{defsetf}, @code{define-setf-method}. @end menu @node Setf Extensions @@ -1198,9 +1197,7 @@ Some more examples: (cl-callf cl-union happy-people (list joe bob) :test 'same-person) @end example -@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. +Note again that @code{cl-callf} is an extension to standard Common Lisp. @end defmac @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} @@ -1216,214 +1213,6 @@ blocks for other macros like @code{cl-incf}, @code{cl-pushnew}, and macros are used in the processing of symbol macros; @pxref{Macro Bindings}. -@node Customizing Setf -@subsection Customizing Setf - -@noindent -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. - -@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 -described by @var{arglist}. The call - -@example -(@var{name} @var{place} @var{args}...) -@end example - -@noindent -will be expanded to - -@example -(cl-callf @var{func} @var{place} @var{args}...) -@end example - -@noindent -which in turn is roughly equivalent to - -@example -(setf @var{place} (@var{func} @var{place} @var{args}...)) -@end example - -For example: - -@example -(define-modify-macro cl-incf (&optional (n 1)) +) -(define-modify-macro cl-concatf (&rest args) concat) -@end example - -Note that @code{&key} is not allowed in @var{arglist}, but -@code{&rest} is sufficient to pass keywords on to the function. - -Most of the modify macros defined by Common Lisp do not exactly -follow the pattern of @code{define-modify-macro}. For example, -@code{push} takes its arguments in the wrong order, and @code{pop} -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 defmac - -@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 -function. From now on, - -@example -(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) -@end example - -@noindent -will be expanded to - -@example -(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) -@end example - -@noindent -The @var{update-fn} is required to be either a true function, or -a macro which evaluates its arguments in a function-like way. Also, -the @var{update-fn} is expected to return @var{value} as its result. -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 -not suitable, so that the above @code{setf} should be expanded to -something more like - -@example -(let ((temp @var{value})) - (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) - temp) -@end example - -Some examples of the use of @code{defsetf}, drawn from the standard -suite of setf methods, are: - -@example -(defsetf car setcar) -(defsetf symbol-value set) -(defsetf buffer-name rename-buffer t) -@end example -@end defmac - -@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 -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} -method (analogous to the doc string that appears at the front of a -function). - -For example, the simple form of @code{defsetf} is shorthand for - -@example -(defsetf @var{access-fn} (&rest args) (store) - (append '(@var{update-fn}) args (list store))) -@end example - -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 -setf-method will insert temporary variables as needed to make -sure the apparent order of evaluation is preserved. - -Another example drawn from the standard package: - -@example -(defsetf nth (n x) (store) - (list 'setcar (list 'nthcdr n x) store)) -@end example -@end defmac - -@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 -must return a list of five items: - -@enumerate -@item -A list of @dfn{temporary variables}. - -@item -A list of @dfn{value forms} corresponding to the temporary variables -above. The temporary variables will be bound to these value forms -as the first step of any operation on the generalized variable. - -@item -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 -the generalized variable, assuming the temporaries have been -bound as described above. - -@item -A Lisp form which accesses the contents of the generalized variable, -assuming the temporaries have been bound. -@end enumerate - -This is exactly like the Common Lisp macro of the same name, -except that the method returns a list of five values rather -than the five values themselves, since Emacs Lisp does not -support Common Lisp's notion of multiple return values. - -Once again, the @var{forms} may begin with a documentation string. - -A setf-method should be maximally conservative with regard to -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 -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 defmac - -@defun get-setf-method place &optional env -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.) - -The argument @var{env} specifies the ``environment'' to be -passed on to @code{macroexpand} if @code{get-setf-method} should -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}. - -See also the source code for the setf-methods for @code{apply} -and @code{substring}, each of which works by calling -@code{get-setf-method} on a simpler case, then massaging -the result in various ways. -@end defun - -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})} -rather than symbols. For example, @code{(defun (setf foo) @dots{})} -defines the function that is used when @code{setf} is applied to -@code{foo}. This package does not currently support @code{setf} -functions. In particular, it is a compile-time error to use -@code{setf} on a form which has not already been @code{defsetf}'d -or otherwise declared; in newer Common Lisps, this would not be -an error since the function @code{(setf @var{func})} might be -defined later. @node Variable Bindings @section Variable Bindings @@ -2672,8 +2461,8 @@ functions, by contrast, always return exactly one result. This package makes no attempt to emulate Common Lisp multiple return values; Emacs versions of Common Lisp functions that return more than one value either return just the first value (as in -@code{cl-compiler-macroexpand}) or return a list of values (as in -@code{get-setf-method}). This package @emph{does} define placeholders +@code{cl-compiler-macroexpand}) or return a list of values. +This package @emph{does} define placeholders for the Common Lisp functions that work with multiple values, but in Emacs Lisp these functions simply operate on lists instead. The @code{cl-values} form, for example, is a synonym for @code{list} @@ -5088,22 +4877,214 @@ Replaced by @code{cl-letf} (@pxref{Modify Macros}). @node Obsolete Setf Customization @appendixsec Obsolete Ways to Customize Setf -This section describes some obsolete ways to extend @code{setf}. -They are replaced by @file{gv.el} in Emacs 24.3. +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. + +@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 +described by @var{arglist}. The call + +@example +(@var{name} @var{place} @var{args}...) +@end example + +@noindent +will be expanded to -@c FIXME. -@defmac define-setf-method name arglist &rest body -Use @file{gv.el}. +@example +(cl-callf @var{func} @var{place} @var{args}...) +@end example + +@noindent +which in turn is roughly equivalent to + +@example +(setf @var{place} (@var{func} @var{place} @var{args}...)) +@end example + +For example: + +@example +(define-modify-macro cl-incf (&optional (n 1)) +) +(define-modify-macro cl-concatf (&rest args) concat) +@end example + +Note that @code{&key} is not allowed in @var{arglist}, but +@code{&rest} is sufficient to pass keywords on to the function. + +Most of the modify macros defined by Common Lisp do not exactly +follow the pattern of @code{define-modify-macro}. For example, +@code{push} takes its arguments in the wrong order, and @code{pop} +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 defmac @defmac defsetf access-fn update-fn -Use @file{gv.el}. +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 +function. From now on, + +@example +(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) +@end example + +@noindent +will be expanded to + +@example +(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) +@end example + +@noindent +The @var{update-fn} is required to be either a true function, or +a macro which evaluates its arguments in a function-like way. Also, +the @var{update-fn} is expected to return @var{value} as its result. +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 +not suitable, so that the above @code{setf} should be expanded to +something more like + +@example +(let ((temp @var{value})) + (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) + temp) +@end example + +Some examples of the use of @code{defsetf}, drawn from the standard +suite of setf methods, are: + +@example +(defsetf car setcar) +(defsetf symbol-value set) +(defsetf buffer-name rename-buffer t) +@end example @end defmac -@defmac define-modify-macro name arglist function [doc-string] -Use @file{gv.el}. +@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 +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} +method (analogous to the doc string that appears at the front of a +function). + +For example, the simple form of @code{defsetf} is shorthand for + +@example +(defsetf @var{access-fn} (&rest args) (store) + (append '(@var{update-fn}) args (list store))) +@end example + +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 +setf-method will insert temporary variables as needed to make +sure the apparent order of evaluation is preserved. + +Another example drawn from the standard package: + +@example +(defsetf nth (n x) (store) + (list 'setcar (list 'nthcdr n x) store)) +@end example @end defmac +@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 +must return a list of five items: + +@enumerate +@item +A list of @dfn{temporary variables}. + +@item +A list of @dfn{value forms} corresponding to the temporary variables +above. The temporary variables will be bound to these value forms +as the first step of any operation on the generalized variable. + +@item +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 +the generalized variable, assuming the temporaries have been +bound as described above. + +@item +A Lisp form which accesses the contents of the generalized variable, +assuming the temporaries have been bound. +@end enumerate + +This is exactly like the Common Lisp macro of the same name, +except that the method returns a list of five values rather +than the five values themselves, since Emacs Lisp does not +support Common Lisp's notion of multiple return values. + +Once again, the @var{forms} may begin with a documentation string. + +A setf-method should be maximally conservative with regard to +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 +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 defmac + +@defun get-setf-method place &optional env +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.) + +The argument @var{env} specifies the ``environment'' to be +passed on to @code{macroexpand} if @code{get-setf-method} should +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}. + +See also the source code for the setf-methods for @code{apply} +and @code{substring}, each of which works by calling +@code{get-setf-method} on a simpler case, then massaging +the result in various ways. +@end defun + +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})} +rather than symbols. For example, @code{(defun (setf foo) @dots{})} +defines the function that is used when @code{setf} is applied to +@code{foo}. This package does not currently support @code{setf} +functions. In particular, it is a compile-time error to use +@code{setf} on a form which has not already been @code{defsetf}'d +or otherwise declared; in newer Common Lisps, this would not be +an error since the function @code{(setf @var{func})} might be +defined later. + @node GNU Free Documentation License @appendix GNU Free Documentation License