emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110799: Document setf-local, defv


From: Chong Yidong
Subject: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r110799: Document setf-local, defvar-local, and some doc updates for setf.
Date: Wed, 07 Nov 2012 13:22:10 +0800
User-agent: Bazaar (2.5.0)

------------------------------------------------------------
revno: 110799
committer: Chong Yidong <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-11-07 13:22:10 +0800
message:
  Document setf-local, defvar-local, and some doc updates for setf.
  
  * doc/lispref/edebug.texi (Specification List): setf is no longer CL-only.
  
  * doc/lispref/lists.texi (List Elements, List Variables): Clarify descriptions
  of push and pop for generalized variables.
  
  * doc/lispref/variables.texi (Creating Buffer-Local): Document setq-local and
  defvar-local.
  (Setting Generalized Variables): Arrange table alphabetically.
modified:
  doc/lispref/ChangeLog
  doc/lispref/edebug.texi
  doc/lispref/lists.texi
  doc/lispref/variables.texi
  etc/NEWS
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-11-07 04:37:07 +0000
+++ b/doc/lispref/ChangeLog     2012-11-07 05:22:10 +0000
@@ -1,3 +1,14 @@
+2012-11-07  Chong Yidong  <address@hidden>
+
+       * variables.texi (Creating Buffer-Local): Document setq-local and
+       defvar-local.
+       (Setting Generalized Variables): Arrange table alphabetically.
+
+       * lists.texi (List Elements, List Variables): Clarify descriptions
+       of push and pop for generalized variables.
+
+       * edebug.texi (Specification List): setf is no longer CL-only.
+
 2012-11-07  Glenn Morris  <address@hidden>
 
        * variables.texi (Adding Generalized Variables):

=== modified file 'doc/lispref/edebug.texi'
--- a/doc/lispref/edebug.texi   2012-09-22 13:24:58 +0000
+++ b/doc/lispref/edebug.texi   2012-11-07 05:22:10 +0000
@@ -1211,9 +1211,7 @@
 A single evaluated expression, which is instrumented.
 
 @item place
address@hidden I can't see that this index entry is useful without any 
explanation.
address@hidden @findex edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
+A generalized variable.  @xref{Generalized Variables}.
 
 @item body
 Short for @code{&rest form}.  See @code{&rest} below.

=== modified file 'doc/lispref/lists.texi'
--- a/doc/lispref/lists.texi    2012-10-31 21:00:13 +0000
+++ b/doc/lispref/lists.texi    2012-11-07 05:22:10 +0000
@@ -234,17 +234,15 @@
 @end defun
 
 @defmac pop listname
-This macro is a way of examining the @sc{car} of a list,
-and taking it off the list, all at once.
address@hidden FIXME I don't think is a particularly good way to do it,
address@hidden but generalized variables have not been introduced yet.
-(In fact, this macro can act on generalized variables, not just lists.
address@hidden Variables}.)
+This macro provides a convenient way to examine the @sc{car} of a
+list, and take it off the list, all at once.  It operates on the list
+stored in @var{listname}.  It removes the first element from the list,
+saves the @sc{cdr} into @var{listname}, then returns the removed
+element.
 
-It operates on the list which is stored in the symbol @var{listname}.
-It removes this element from the list by setting @var{listname}
-to the @sc{cdr} of its old value---but it also returns the @sc{car}
-of that list, which is the element being removed.
+In the simplest case, @var{listname} is an unquoted symbol naming a
+list; in that case, this macro is equivalent to @address@hidden(prog1
+(car listname) (setq listname (cdr listname)))}}.
 
 @example
 x
@@ -255,7 +253,10 @@
      @result{} (b c)
 @end example
 
address@hidden
+More generally, @var{listname} can be a generalized variable.  In that
+case, this macro saves into @var{listname} using @code{setf}.
address@hidden Variables}.
+
 For the @code{push} macro, which adds an element to a list,
 @xref{List Variables}.
 @end defmac
@@ -683,13 +684,12 @@
   These functions, and one macro, provide convenient ways
 to modify a list which is stored in a variable.
 
address@hidden push newelt listname
-This macro provides an alternative way to write
address@hidden(setq @var{listname} (cons @var{newelt} @var{listname}))}.
address@hidden FIXME I don't think is a particularly good way to do it,
address@hidden but generalized variables have not been introduced yet.
-(In fact, this macro can act on generalized variables, not just lists.
address@hidden Variables}.)
address@hidden push element listname
+This macro creates a new list whose @sc{car} is @var{element} and
+whose @sc{cdr} is the list specified by @var{listname}, and saves that
+list in @var{listname}.  In the simplest case, @var{listname} is an
+unquoted symbol naming a list, and this macro is equivalent
+to @address@hidden(setq @var{listname} (cons @var{element} @var{listname}))}}.
 
 @example
 (setq l '(a b))
@@ -700,7 +700,11 @@
      @result{} (c a b)
 @end example
 
address@hidden
+More generally, @code{listname} can be a generalized variable.  In
+that case, this macro does the equivalent of @address@hidden(setf
address@hidden (cons @var{element} @var{listname}))}}.
address@hidden Variables}.
+
 For the @code{pop} macro, which removes the first element from a list,
 @xref{List Elements}.
 @end defmac

=== modified file 'doc/lispref/variables.texi'
--- a/doc/lispref/variables.texi        2012-11-07 04:37:07 +0000
+++ b/doc/lispref/variables.texi        2012-11-07 05:22:10 +0000
@@ -1262,6 +1262,13 @@
 @code{remove-hook}.
 @end deffn
 
address@hidden setq-local variable value
+This macro creates a buffer-local binding in the current buffer for
address@hidden, and gives it the buffer-local value @var{value}.  It
+is equivalent to calling @code{make-local-variable} followed by
address@hidden  @var{variable} should be an unquoted symbol.
address@hidden defmac
+
 @deffn Command make-variable-buffer-local variable
 This function marks @var{variable} (a symbol) automatically
 buffer-local, so that any subsequent attempt to set it will make it
@@ -1297,6 +1304,14 @@
 @code{make-variable-buffer-local} can be the best solution.
 @end deffn
 
address@hidden defvar-local variable value &optional docstring
+This macro defines @var{variable} as a variable with initial value
address@hidden and @var{docstring}, and marks it as automatically
+buffer-local.  It is equivalent to calling @code{defvar} followed by
address@hidden  @var{variable} should be an
+unquoted symbol.
address@hidden defmac
+
 @defun local-variable-p variable &optional buffer
 This returns @code{t} if @var{variable} is buffer-local in buffer
 @var{buffer} (which defaults to the current buffer); otherwise,
@@ -1948,7 +1963,6 @@
 @error{} Wrong type argument: integerp, 1000.0
 @end example
 
address@hidden FIXME?  Not sure this is the right place for this section.
 @node Generalized Variables
 @section Generalized Variables
 
@@ -1958,7 +1972,6 @@
 of arrays, properties of symbols, and many other locations are also
 places where Lisp values are stored.
 
address@hidden FIXME?  Not sure this is a useful analogy...
 Generalized variables are analogous to ``lvalues'' in the C
 language, where @samp{x = a[i]} gets an element from an array
 and @samp{a[i] = x} stores an element using the same notation.
@@ -2006,14 +2019,16 @@
 A call to any of the following standard Lisp functions:
 
 @smallexample
-car            cdr            nth            nthcdr
-caar           cadr           cdar           cddr
-aref           elt            get            gethash
-symbol-function        symbol-value          symbol-plist
+aref      cddr      symbol-function
+car       elt       symbol-plist
+caar      get       symbol-value
+cadr      gethash
+cdr       nth
+cdar      nthcdr  
 @end smallexample
 
 @item
-The following Emacs-specific functions are also @code{setf}-able:
+A call to any of the following Emacs-specific functions:
 
 @smallexample
 default-value                 process-get
@@ -2030,8 +2045,8 @@
 @end itemize
 
 @noindent
-Using any forms other than these in the @var{place} argument to
address@hidden will signal an error.
address@hidden signals an error if you pass a @var{place} form that it
+does not know how to handle.
 
 @c And for cl-lib's cl-getf.
 Note that for @code{nthcdr}, the list argument of the function must

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-06 02:22:07 +0000
+++ b/etc/NEWS  2012-11-07 05:22:10 +0000
@@ -788,6 +788,7 @@
 The sampling rate can be based on CPU time (only supported on some
 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',
@@ -823,7 +824,7 @@
 *** Set `debug-on-message' to enter the debugger when a certain
 message is displayed in the echo area.  This can be useful when trying
 to work out which code is doing something.
-
+---
 *** New var `inhibit-debugger', automatically set to prevent accidental
 recursive invocations.
 
@@ -936,6 +937,7 @@
 +++
 *** `tty-top-frame' returns the topmost frame of a text terminal.
 
++++
 ** New macros `setq-local' and `defvar-local'.
 
 +++


reply via email to

[Prev in Thread] Current Thread [Next in Thread]