From: Glenn Morris Date: Wed, 7 Nov 2012 08:56:16 +0000 (-0800) Subject: More cl-lib and gv doc updates X-Git-Tag: emacs-24.2.90~148 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=031b2ea7f5cefc53885d469c3c37ef68103d49aa;p=emacs.git More cl-lib and gv doc updates * lisp/emacs-lisp/cl.el (define-setf-expander, defsetf) (define-modify-macro): Doc fixes. * doc/misc/cl.texi (Obsolete Setf Customization): Give defsetf gv.el replacements. * etc/NEWS: Related edit. --- diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 93a2971f8c6..6951f2df79d 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -2,7 +2,7 @@ * cl.texi (Obsolete Setf Customization): Revert defsetf example to the more correct let rather than prog1. - Give define-modify-macro gv.el replacement. + Give define-modify-macro and defsetf gv.el replacements. 2012-11-06 Glenn Morris diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 21750b79c93..d3c9ad6aedf 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -5019,14 +5019,16 @@ These translate directly to @code{gv-define-simple-setter}: @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 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} -method (analogous to the doc string that appears at the front of a -function). +This is the second, more complex, form of @code{defsetf}. +It can be replaced by @code{gv-define-setter}. + +This form of @code{defsetf} is rather like @code{defmacro} except for +the additional @var{store-var} 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} 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 @@ -5041,11 +5043,18 @@ 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. -Another example drawn from the standard package: +Another standard example: @example (defsetf nth (n x) (store) - (list 'setcar (list 'nthcdr n x) store)) + `(setcar (nthcdr ,n ,x) ,store)) +@end example + +You could write this using @code{gv-define-setter} as: + +@example +(gv-define-setter nth (store n x) + `(setcar (nthcdr ,n ,x) ,store)) @end example @end defmac diff --git a/etc/NEWS b/etc/NEWS index 33ec17c1960..76126cf6dda 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -339,8 +339,8 @@ rather than making them unbound. *** The following methods of extending `setf' are obsolete (use features from gv.el instead): `define-modify-macro' (use `gv-letplace') -`defsetf' (use `gv-define-simple-setter', or FIXME) -`define-setf-expander' (use FIXME) +`defsetf' (use `gv-define-simple-setter' or `gv-define-setter') +`define-setf-expander' (use `gv-define-setter' or `gv-define-expander') ** Compilation mode +++ diff --git a/lisp/ChangeLog b/lisp/ChangeLog index cfd79fc57ef..ff9684ad175 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,8 @@ 2012-11-07 Glenn Morris + * emacs-lisp/cl.el (define-setf-expander, defsetf) + (define-modify-macro): Doc fixes. + * emacs-lisp/gv.el (gv-letplace): Fix doc typo. (gv-define-simple-setter): Update doc of `fix-return'. diff --git a/lisp/emacs-lisp/cl.el b/lisp/emacs-lisp/cl.el index 52567f34278..016967bc713 100644 --- a/lisp/emacs-lisp/cl.el +++ b/lisp/emacs-lisp/cl.el @@ -547,13 +547,15 @@ deprecated usage of `symbol-function' in place forms)." ; bug#12760 (defmacro define-setf-expander (name arglist &rest body) "Define a `setf' method. -This method shows how to handle `setf's to places of the form (NAME ARGS...). -The argument forms ARGS are bound according to ARGLIST, as if NAME were -going to be expanded as a macro, then the BODY forms are executed and must -return a list of five elements: a temporary-variables list, a value-forms -list, a store-variables list (of length one), a store-form, and an access- -form. See `gv-define-expander', `gv-define-setter', and `gv-define-expander' -for a better and simpler ways to define setf-methods." +This method shows how to handle `setf's to places of the form +\(NAME ARGS...). The argument forms ARGS are bound according to +ARGLIST, as if NAME were going to be expanded as a macro, then +the BODY forms are executed and must return a list of five elements: +a temporary-variables list, a value-forms list, a store-variables list +\(of length one), a store-form, and an access- form. + +See `gv-define-expander', and `gv-define-setter' for better and +simpler ways to define setf-methods." (declare (debug (&define name cl-lambda-list cl-declarations-or-string def-body))) `(progn @@ -566,23 +568,31 @@ for a better and simpler ways to define setf-methods." (defmacro defsetf (name arg1 &rest args) "Define a `setf' method. -This macro is an easy-to-use substitute for `define-setf-expander' that works -well for simple place forms. In the simple `defsetf' form, `setf's of -the form (setf (NAME ARGS...) VAL) are transformed to function or macro -calls of the form (FUNC ARGS... VAL). Example: +This macro is an easy-to-use substitute for `define-setf-expander' +that works well for simple place forms. + +In the simple `defsetf' form, `setf's of the form (setf (NAME +ARGS...) VAL) are transformed to function or macro calls of the +form (FUNC ARGS... VAL). For example: (defsetf aref aset) +You can replace this form with `gv-define-simple-setter'. + Alternate form: (defsetf NAME ARGLIST (STORE) BODY...). -Here, the above `setf' call is expanded by binding the argument forms ARGS -according to ARGLIST, binding the value form VAL to STORE, then executing -BODY, which must return a Lisp form that does the necessary `setf' operation. -Actually, ARGLIST and STORE may be bound to temporary variables which are -introduced automatically to preserve proper execution order of the arguments. -Example: + +Here, the above `setf' call is expanded by binding the argument +forms ARGS according to ARGLIST, binding the value form VAL to +STORE, then executing BODY, which must return a Lisp form that +does the necessary `setf' operation. Actually, ARGLIST and STORE +may be bound to temporary variables which are introduced +automatically to preserve proper execution order of the arguments. +For example: (defsetf nth (n x) (v) `(setcar (nthcdr ,n ,x) ,v)) +You can replace this form with `gv-define-setter'. + \(fn NAME [FUNC | ARGLIST (STORE) BODY...])" (declare (debug (&define name @@ -639,8 +649,12 @@ Example: (defmacro define-modify-macro (name arglist func &optional doc) "Define a `setf'-like modify macro. -If NAME is called, it combines its PLACE argument with the other arguments -from ARGLIST using FUNC: (define-modify-macro incf (&optional (n 1)) +)" +If NAME is called, it combines its PLACE argument with the other +arguments from ARGLIST using FUNC. For example: + + (define-modify-macro incf (&optional (n 1)) +) + +You can replace this macro with `gv-letplace'." (declare (debug (&define name cl-lambda-list ;; should exclude &key symbolp &optional stringp)))