[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110787: Add some documentation on defining new generalized variables

[Glenn Morris]

------------------------------------------------------------
revno: 110787
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Mon 2012-11-05 20:42:17 -0500
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/variables.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-11-05 14:30:58 +0000
+++ b/doc/lispref/ChangeLog     2012-11-06 01:42:17 +0000
@@ -1,3 +1,10 @@
+2012-11-06  Glenn Morris  <address@hidden>
+
+       * 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  <address@hidden>
 
        * frames.texi (Initial Parameters): Doc fix (Bug#12144).

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-10-27 22:42:07 +0000
+++ b/doc/lispref/elisp.texi    2012-11-06 01:42:17 +0000
@@ -502,6 +502,11 @@
 * 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.

=== modified file 'doc/lispref/variables.texi'
--- a/doc/lispref/variables.texi        2012-10-31 19:23:06 +0000
+++ b/doc/lispref/variables.texi        2012-11-06 01:42:17 +0000
@@ -1965,6 +1965,14 @@
 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.
 
address@hidden
+* Setting Generalized Variables::   The @code{setf} macro.
+* Adding Generalized Variables::    Defining new @code{setf} forms.
address@hidden menu
+
address@hidden Setting Generalized Variables
address@hidden 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 @@
 The @file{cl-lib} library defines various extensions for generalized
 variables, including additional @code{setf} places.
 @xref{Generalized Variables,,, cl, Common Lisp Extensions}.
+
+
address@hidden Adding Generalized Variables
address@hidden Defining new @code{setf} forms
+
+This section describes how to define new forms that @code{setf} can
+operate on.
+
address@hidden 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.,
address@hidden(gv-define-simple-setter car setcar)}.
+
+This macro translates a call of the form
+
address@hidden
+(setf (@var{name} @address@hidden) @var{value})
address@hidden example
+
+into
address@hidden
+(@var{setter} @address@hidden @var{value})
address@hidden example
+
address@hidden
+Such a @code{setf} call is documented to return @var{value}.  This is
+no problem with, e.g., @code{car} and @code{setcar}, because
address@hidden returns the value that it set.  If your @var{setter}
+function does not return @var{value}, use a address@hidden 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.
address@hidden defmac
+
+
address@hidden 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
address@hidden(setf (@var{name} @address@hidden) @var{value})} by
+first binding the @code{setf} argument forms
address@hidden(@var{value} @address@hidden)} 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:
+
address@hidden
+(gv-define-setter caar (val x) `(setcar (car ,x) ,val))
address@hidden example
address@hidden defmac
+
address@hidden FIXME?  Not sure what, if anything, to say about this.
address@hidden
address@hidden gv-define-expander name handler
+This is the most general way to define a new @code{setf} expansion.
address@hidden defmac
address@hidden ignore

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-03 18:55:29 +0000
+++ b/etc/NEWS  2012-11-06 01:42:17 +0000
@@ -783,6 +783,8 @@
 
 ** 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'.