From: Glenn Morris Date: Tue, 6 Nov 2012 01:42:17 +0000 (-0500) Subject: Add some documentation on defining new generalized variables X-Git-Tag: emacs-24.2.90~164 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ebdbfb953591230bf217151535211af5a300ee3c;p=emacs.git Add some documentation on defining new generalized variables * doc/lispref/variables.texi (Setting Generalized Variables): Split most of previous contents into this subsection. (Adding Generalized Variables): New subsection. * doc/lispref/elisp.texi: Add Generalized Variables subsections to detailed menu. * etc/NEWS: Mention some gv.el macros by name. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 8057089cf68..d97a258da34 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2012-11-06 Glenn Morris + + * variables.texi (Setting Generalized Variables): + Split most of previous contents into this subsection. + (Adding Generalized Variables): New subsection. + * elisp.texi: Add Generalized Variables subsections to detailed menu. + 2012-11-05 Chong Yidong * frames.texi (Initial Parameters): Doc fix (Bug#12144). diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 06a2ebfcaf8..5f10b450e84 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -502,6 +502,11 @@ Buffer-Local Variables * Default Value:: The default value is seen in buffers that don't have their own buffer-local values. +Generalized Variables + +* Setting Generalized Variables:: The @code{setf} macro. +* Adding Generalized Variables:: Defining new @code{setf} forms. + Functions * What Is a Function:: Lisp functions vs. primitives; terminology. diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 88b7909126e..f9f69850ef8 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1965,6 +1965,14 @@ and @samp{a[i] = x} stores an element using the same notation. Just as certain forms like @code{a[i]} can be lvalues in C, there is a set of forms that can be generalized variables in Lisp. +@menu +* Setting Generalized Variables:: The @code{setf} macro. +* Adding Generalized Variables:: Defining new @code{setf} forms. +@end menu + +@node Setting Generalized Variables +@subsection The @code{setf} Macro + The @code{setf} macro is the most basic way to operate on generalized variables. The @code{setf} form is like @code{setq}, except that it accepts arbitrary place forms on the left side rather than just @@ -2049,3 +2057,65 @@ place can be used to insert or delete at any position in a list. The @file{cl-lib} library defines various extensions for generalized variables, including additional @code{setf} places. @xref{Generalized Variables,,, cl, Common Lisp Extensions}. + + +@node Adding Generalized Variables +@subsection Defining new @code{setf} forms + +This section describes how to define new forms that @code{setf} can +operate on. + +@defmac gv-define-simple-setter name setter &optional fix-return +This macro enables you to easily define @code{setf} methods for simple +cases. @var{name} is the name of a function, macro, or special form. +You can use this macro whenever @var{name} has a directly +corresponding @var{setter} function that updates it, e.g., +@code{(gv-define-simple-setter car setcar)}. + +This macro translates a call of the form + +@example +(setf (@var{name} @var{args}@dots{}) @var{value}) +@end example + +into +@example +(@var{setter} @var{args}@dots{} @var{value}) +@end example + +@noindent +Such a @code{setf} call is documented to return @var{value}. This is +no problem with, e.g., @code{car} and @code{setcar}, because +@code{setcar} returns the value that it set. If your @var{setter} +function does not return @var{value}, use a non-@code{nil} value for +the @var{fix-return} argument of @code{gv-define-simple-setter}. This +wraps the @code{setf} expansion in @code{(prog1 @var{value} @dots{})} +so that it returns the correct result. +@end defmac + + +@defmac gv-define-setter name arglist &rest body +This macro allows for more complex @code{setf} expansions than the +previous form. You may need to use this form, for example, if there +is no simple setter function to call, or if there is one but it +requires different arguments to the place form. + +This macro expands the form +@code{(setf (@var{name} @var{args}@dots{}) @var{value})} by +first binding the @code{setf} argument forms +@code{(@var{value} @var{args}@dots{})} according to @var{arglist}, +and then executing @var{body}. @var{body} should return a Lisp +form that does the assignment. Remember that it should return the +value that was set. An example of using this macro is: + +@example +(gv-define-setter caar (val x) `(setcar (car ,x) ,val)) +@end example +@end defmac + +@c FIXME? Not sure what, if anything, to say about this. +@ignore +@defmac gv-define-expander name handler +This is the most general way to define a new @code{setf} expansion. +@end defmac +@end ignore diff --git a/etc/NEWS b/etc/NEWS index 4f8b56cb363..c9c68513a8b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -783,6 +783,8 @@ systems), or based on memory allocations. ** CL-style generalized variables are now in core Elisp. `setf' is autoloaded; `push' and `pop' accept generalized variables. +You can define your own generalized variables using `gv-define-simple-setter', +`gv-define-setter', etc. +++ ** `defun' also accepts a (declare DECLS) form, like `defmacro'.