Commit d571e9c3 authored by Glenn Morris's avatar Glenn Morris

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.
parent a3c5b619
...@@ -2,6 +2,8 @@ ...@@ -2,6 +2,8 @@
* cl.texi (Organization): More details on cl-lib.el versus cl.el. * cl.texi (Organization): More details on cl-lib.el versus cl.el.
(Setf Extensions): Remove `apply' setf since it seems to be disabled. (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 <rgm@gnu.org> 2012-10-28 Glenn Morris <rgm@gnu.org>
......
...@@ -883,7 +883,6 @@ generalized variables. ...@@ -883,7 +883,6 @@ generalized variables.
@menu @menu
* Setf Extensions:: Additional @code{setf} places. * Setf Extensions:: Additional @code{setf} places.
* Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc. * 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 @end menu
@node Setf Extensions @node Setf Extensions
...@@ -1198,9 +1197,7 @@ Some more examples: ...@@ -1198,9 +1197,7 @@ Some more examples:
(cl-callf cl-union happy-people (list joe bob) :test 'same-person) (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
@end example @end example
@xref{Customizing Setf}, for @code{define-modify-macro}, a way Note again that @code{cl-callf} is an extension to standard Common Lisp.
to create even more concise notations for modify macros. Note
again that @code{cl-callf} is an extension to standard Common Lisp.
@end defmac @end defmac
@defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} @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 ...@@ -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; macros are used in the processing of symbol macros;
@pxref{Macro Bindings}. @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 @node Variable Bindings
@section Variable Bindings @section Variable Bindings
...@@ -2672,8 +2461,8 @@ functions, by contrast, always return exactly one result. This ...@@ -2672,8 +2461,8 @@ functions, by contrast, always return exactly one result. This
package makes no attempt to emulate Common Lisp multiple return package makes no attempt to emulate Common Lisp multiple return
values; Emacs versions of Common Lisp functions that return more values; Emacs versions of Common Lisp functions that return more
than one value either return just the first value (as in than one value either return just the first value (as in
@code{cl-compiler-macroexpand}) or return a list of values (as in @code{cl-compiler-macroexpand}) or return a list of values.
@code{get-setf-method}). This package @emph{does} define placeholders This package @emph{does} define placeholders
for the Common Lisp functions that work with multiple values, but for the Common Lisp functions that work with multiple values, but
in Emacs Lisp these functions simply operate on lists instead. in Emacs Lisp these functions simply operate on lists instead.
The @code{cl-values} form, for example, is a synonym for @code{list} 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}). ...@@ -5088,22 +4877,214 @@ Replaced by @code{cl-letf} (@pxref{Modify Macros}).
@node Obsolete Setf Customization @node Obsolete Setf Customization
@appendixsec Obsolete Ways to Customize Setf @appendixsec Obsolete Ways to Customize Setf
This section describes some obsolete ways to extend @code{setf}. Common Lisp defines three macros, @code{define-modify-macro},
They are replaced by @file{gv.el} in Emacs 24.3. @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. @example
@defmac define-setf-method name arglist &rest body (cl-callf @var{func} @var{place} @var{args}...)
Use @file{gv.el}. @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 @end defmac
@defmac defsetf access-fn update-fn @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 @end defmac
@defmac define-modify-macro name arglist function [doc-string] @defmac defsetf access-fn arglist (store-var) forms@dots{}
Use @file{gv.el}. 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 @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 @node GNU Free Documentation License
@appendix GNU Free Documentation License @appendix GNU Free Documentation License
......
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