Commit 031b2ea7 authored by Glenn Morris's avatar Glenn Morris
Browse files

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.
parent 9512f820
......@@ -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 <rgm@gnu.org>
......
......@@ -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
......
......@@ -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
+++
......
2012-11-07 Glenn Morris <rgm@gnu.org>
* 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'.
......
......@@ -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)))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment