[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110803: More cl-lib and gv doc up
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110803: More cl-lib and gv doc updates |
Date: |
Wed, 07 Nov 2012 00:56:16 -0800 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110803
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-11-07 00:56:16 -0800
message:
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.
modified:
doc/misc/ChangeLog
doc/misc/cl.texi
etc/NEWS
lisp/ChangeLog
lisp/emacs-lisp/cl.el
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2012-11-07 08:28:34 +0000
+++ b/doc/misc/ChangeLog 2012-11-07 08:56:16 +0000
@@ -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 <address@hidden>
=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi 2012-11-07 08:28:34 +0000
+++ b/doc/misc/cl.texi 2012-11-07 08:56:16 +0000
@@ -5019,14 +5019,16 @@
@end defmac
@defmac defsetf access-fn arglist (store-var) address@hidden
-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 @@
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))
address@hidden example
+
+You could write this using @code{gv-define-setter} as:
+
address@hidden
+(gv-define-setter nth (store n x)
+ `(setcar (nthcdr ,n ,x) ,store))
@end example
@end defmac
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2012-11-07 08:32:34 +0000
+++ b/etc/NEWS 2012-11-07 08:56:16 +0000
@@ -339,8 +339,8 @@
*** 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
+++
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-11-07 04:37:07 +0000
+++ b/lisp/ChangeLog 2012-11-07 08:56:16 +0000
@@ -1,5 +1,8 @@
2012-11-07 Glenn Morris <address@hidden>
+ * 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'.
=== modified file 'lisp/emacs-lisp/cl.el'
--- a/lisp/emacs-lisp/cl.el 2012-11-07 03:14:27 +0000
+++ b/lisp/emacs-lisp/cl.el 2012-11-07 08:56:16 +0000
@@ -547,13 +547,15 @@
(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 @@
(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 @@
(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)))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-24 r110803: More cl-lib and gv doc updates,
Glenn Morris <=