From 7c08f8ba7246ddd20f70e8306f646ac981a64f5a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 7 Nov 2012 13:22:10 +0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 11 ++++++++++ doc/lispref/edebug.texi | 4 +--- doc/lispref/lists.texi | 44 +++++++++++++++++++++----------------- doc/lispref/variables.texi | 33 ++++++++++++++++++++-------- etc/NEWS | 4 +++- 5 files changed, 63 insertions(+), 33 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 6e7a0b7a648..9af670dc6cc 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2012-11-07 Chong Yidong + + * 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 * variables.texi (Adding Generalized Variables): diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 0211f9e1b9c..b5edda06bad 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1211,9 +1211,7 @@ A single unevaluated Lisp object, which is not instrumented. A single evaluated expression, which is instrumented. @item place -@c I can't see that this index entry is useful without any explanation. -@c @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. diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 458db838177..40e8d08f72c 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -234,17 +234,15 @@ This is in contrast to @code{cdr}, which signals an error if @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. -@c FIXME I don't think is a particularly good way to do it, -@c but generalized variables have not been introduced yet. -(In fact, this macro can act on generalized variables, not just lists. -@xref{Generalized Variables}.) - -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. +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. + +In the simplest case, @var{listname} is an unquoted symbol naming a +list; in that case, this macro is equivalent to @w{@code{(prog1 +(car listname) (setq listname (cdr listname)))}}. @example x @@ -255,7 +253,10 @@ x @result{} (b c) @end example -@noindent +More generally, @var{listname} can be a generalized variable. In that +case, this macro saves into @var{listname} using @code{setf}. +@xref{Generalized Variables}. + For the @code{push} macro, which adds an element to a list, @xref{List Variables}. @end defmac @@ -683,13 +684,12 @@ Some examples: These functions, and one macro, provide convenient ways to modify a list which is stored in a variable. -@defmac push newelt listname -This macro provides an alternative way to write -@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. -@c FIXME I don't think is a particularly good way to do it, -@c but generalized variables have not been introduced yet. -(In fact, this macro can act on generalized variables, not just lists. -@xref{Generalized Variables}.) +@defmac 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 @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}. @example (setq l '(a b)) @@ -700,7 +700,11 @@ l @result{} (c a b) @end example -@noindent +More generally, @code{listname} can be a generalized variable. In +that case, this macro does the equivalent of @w{@code{(setf +@var{listname} (cons @var{element} @var{listname}))}}. +@xref{Generalized Variables}. + For the @code{pop} macro, which removes the first element from a list, @xref{List Elements}. @end defmac diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index fb98b3cd035..c8451527d4f 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1262,6 +1262,13 @@ needed if you use the @var{local} argument to @code{add-hook} or @code{remove-hook}. @end deffn +@defmac setq-local variable value +This macro creates a buffer-local binding in the current buffer for +@var{variable}, and gives it the buffer-local value @var{value}. It +is equivalent to calling @code{make-local-variable} followed by +@code{setq}. @var{variable} should be an unquoted symbol. +@end 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 @@ on having separate values in separate buffers, then using @code{make-variable-buffer-local} can be the best solution. @end deffn +@defmac defvar-local variable value &optional docstring +This macro defines @var{variable} as a variable with initial value +@var{value} and @var{docstring}, and marks it as automatically +buffer-local. It is equivalent to calling @code{defvar} followed by +@code{make-variable-buffer-local}. @var{variable} should be an +unquoted symbol. +@end 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 @@ Attempting to assign them any other value will result in an error: @error{} Wrong type argument: integerp, 1000.0 @end example -@c FIXME? Not sure this is the right place for this section. @node Generalized Variables @section Generalized Variables @@ -1958,7 +1972,6 @@ a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values are stored. -@c 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 @@ so there is no performance penalty for using it in compiled code. 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 @@ process-filter @end itemize @noindent -Using any forms other than these in the @var{place} argument to -@code{setf} will signal an error. +@code{setf} 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 diff --git a/etc/NEWS b/etc/NEWS index be5de734636..7023ce5cb98 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -788,6 +788,7 @@ Try M-x profiler-start ... M-x profiler-stop; and then M-x profiler-report. 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 @@ These do not trigger the debugger. *** 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 @@ describing the cycle. +++ *** `tty-top-frame' returns the topmost frame of a text terminal. ++++ ** New macros `setq-local' and `defvar-local'. +++ -- 2.39.5