[Emacs-diffs] /srv/bzr/emacs/trunk r110715: Move some cl.texi setf extensions to the Obsolete appendix

[Glenn Morris]

------------------------------------------------------------
revno: 110715
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2012-10-28 18:29:22 -0700
message:
  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.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-10-29 01:19:26 +0000
+++ b/doc/misc/ChangeLog        2012-10-29 01:29:22 +0000
@@ -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  <address@hidden>
 

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-10-29 01:19:26 +0000
+++ b/doc/misc/cl.texi  2012-10-29 01:29:22 +0000
@@ -883,7 +883,6 @@
 @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 @@
 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
 @end example
 
address@hidden 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} @address@hidden
@@ -1216,214 +1213,6 @@
 macros are used in the processing of symbol macros;
 @pxref{Macro Bindings}.
 
address@hidden Customizing Setf
address@hidden Customizing Setf
-
address@hidden
-Common Lisp defines three macros, @code{define-modify-macro},
address@hidden, and @code{define-setf-method}, that allow the
-user to extend generalized variables in various ways.
-
address@hidden define-modify-macro name arglist function [doc-string]
-This macro defines a ``read-modify-write'' macro similar to
address@hidden 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
-
address@hidden
-(@var{name} @var{place} @var{args}...)
address@hidden example
-
address@hidden
-will be expanded to
-
address@hidden
-(cl-callf @var{func} @var{place} @var{args}...)
address@hidden example
-
address@hidden
-which in turn is roughly equivalent to
-
address@hidden
-(setf @var{place} (@var{func} @var{place} @var{args}...))
address@hidden example
-
-For example:
-
address@hidden
-(define-modify-macro cl-incf (&optional (n 1)) +)
-(define-modify-macro cl-concatf (&rest args) concat)
address@hidden example
-
-Note that @code{&key} is not allowed in @var{arglist}, but
address@hidden&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,
address@hidden 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.
address@hidden defmac
-
address@hidden defsetf access-fn update-fn
-This is the simpler of two @code{defsetf} forms.  Where
address@hidden is the name of a function which accesses a place,
-this declares @var{update-fn} to be the corresponding store
-function.  From now on,
-
address@hidden
-(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
address@hidden example
-
address@hidden
-will be expanded to
-
address@hidden
-(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
address@hidden example
-
address@hidden
-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
address@hidden 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
-
address@hidden
-(let ((temp @var{value}))
-  (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
-  temp)
address@hidden example
-
-Some examples of the use of @code{defsetf}, drawn from the standard
-suite of setf methods, are:
-
address@hidden
-(defsetf car setcar)
-(defsetf symbol-value set)
-(defsetf buffer-name rename-buffer t)
address@hidden example
address@hidden defmac
-
address@hidden 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 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
-
address@hidden
-(defsetf @var{access-fn} (&rest args) (store)
-  (append '(@var{update-fn}) args (list store)))
address@hidden example
-
-The Lisp form that is returned can access the arguments from
address@hidden 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:
-
address@hidden
-(defsetf nth (n x) (store)
-  (list 'setcar (list 'nthcdr n x) store))
address@hidden example
address@hidden defmac
-
address@hidden define-setf-method access-fn arglist address@hidden
-This is the most general way to create new place forms.  When
-a @code{setf} to @var{access-fn} with arguments described by
address@hidden is expanded, the @var{forms} are evaluated and
-must return a list of five items:
-
address@hidden
address@hidden
-A list of @dfn{temporary variables}.
-
address@hidden
-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.
-
address@hidden
-A list of exactly one @dfn{store variable} (generally obtained
-from a call to @code{gensym}).
-
address@hidden
-A Lisp form which stores the contents of the store variable into
-the generalized variable, assuming the temporaries have been
-bound as described above.
-
address@hidden
-A Lisp form which accesses the contents of the generalized variable,
-assuming the temporaries have been bound.
address@hidden 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
address@hidden, 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.
address@hidden defmac
-
address@hidden 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
address@hidden 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
address@hidden on a simpler case, then massaging
-the result in various ways.
address@hidden defun
-
-Modern Common Lisp defines a second, independent way to specify
-the @code{setf} behavior of a function, namely address@hidden
-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
address@hidden  This package does not currently support @code{setf}
-functions.  In particular, it is a compile-time error to use
address@hidden 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 @@
 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
address@hidden) or return a list of values (as in
address@hidden).  This package @emph{does} define placeholders
address@hidden) 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,21 +4877,213 @@
 @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.
-
address@hidden FIXME.
address@hidden define-setf-method name arglist &rest body
-Use @file{gv.el}.
+Common Lisp defines three macros, @code{define-modify-macro},
address@hidden, 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
address@hidden in Emacs 24.3.
address@hidden FIXME details.
+
address@hidden define-modify-macro name arglist function [doc-string]
+This macro defines a ``read-modify-write'' macro similar to
address@hidden 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
+
address@hidden
+(@var{name} @var{place} @var{args}...)
address@hidden example
+
address@hidden
+will be expanded to
+
address@hidden
+(cl-callf @var{func} @var{place} @var{args}...)
address@hidden example
+
address@hidden
+which in turn is roughly equivalent to
+
address@hidden
+(setf @var{place} (@var{func} @var{place} @var{args}...))
address@hidden example
+
+For example:
+
address@hidden
+(define-modify-macro cl-incf (&optional (n 1)) +)
+(define-modify-macro cl-concatf (&rest args) concat)
address@hidden example
+
+Note that @code{&key} is not allowed in @var{arglist}, but
address@hidden&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,
address@hidden 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}.
address@hidden defmac
-
address@hidden define-modify-macro name arglist function [doc-string]
-Use @file{gv.el}.
address@hidden defmac
+This is the simpler of two @code{defsetf} forms.  Where
address@hidden is the name of a function which accesses a place,
+this declares @var{update-fn} to be the corresponding store
+function.  From now on,
+
address@hidden
+(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
address@hidden example
+
address@hidden
+will be expanded to
+
address@hidden
+(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
address@hidden example
+
address@hidden
+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
address@hidden 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
+
address@hidden
+(let ((temp @var{value}))
+  (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
+  temp)
address@hidden example
+
+Some examples of the use of @code{defsetf}, drawn from the standard
+suite of setf methods, are:
+
address@hidden
+(defsetf car setcar)
+(defsetf symbol-value set)
+(defsetf buffer-name rename-buffer t)
address@hidden example
address@hidden defmac
+
address@hidden 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 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
+
address@hidden
+(defsetf @var{access-fn} (&rest args) (store)
+  (append '(@var{update-fn}) args (list store)))
address@hidden example
+
+The Lisp form that is returned can access the arguments from
address@hidden 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:
+
address@hidden
+(defsetf nth (n x) (store)
+  (list 'setcar (list 'nthcdr n x) store))
address@hidden example
address@hidden defmac
+
address@hidden define-setf-method access-fn arglist address@hidden
+This is the most general way to create new place forms.  When
+a @code{setf} to @var{access-fn} with arguments described by
address@hidden is expanded, the @var{forms} are evaluated and
+must return a list of five items:
+
address@hidden
address@hidden
+A list of @dfn{temporary variables}.
+
address@hidden
+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.
+
address@hidden
+A list of exactly one @dfn{store variable} (generally obtained
+from a call to @code{gensym}).
+
address@hidden
+A Lisp form which stores the contents of the store variable into
+the generalized variable, assuming the temporaries have been
+bound as described above.
+
address@hidden
+A Lisp form which accesses the contents of the generalized variable,
+assuming the temporaries have been bound.
address@hidden 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
address@hidden, 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.
address@hidden defmac
+
address@hidden 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
address@hidden 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
address@hidden on a simpler case, then massaging
+the result in various ways.
address@hidden defun
+
+Modern Common Lisp defines a second, independent way to specify
+the @code{setf} behavior of a function, namely address@hidden
+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
address@hidden  This package does not currently support @code{setf}
+functions.  In particular, it is a compile-time error to use
address@hidden 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