Commit 7c08f8ba authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 2ee1d59f
2012-11-07 Chong Yidong <cyd@gnu.org>
* 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 <rgm@gnu.org>
* variables.texi (Adding Generalized Variables):
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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'.
+++
......
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