procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Firm up documentation of generalized variables

Browse source 
* doc/lispref/variables.texi (Generalized Variables)
(Setting Generalized Variables): Define a generalized variable as something
setf can write to.  Remove the insinuation that hackers have poor memories.
State explicitly that the list of GVs given is complete.  Remove the
suggestion that `setf' has superseded, or is in the process of superseding,
`setq'.  Make minor corrections to the English.
This commit is contained in:
Alan Mackenzie 2018-03-21 17:36:34 +00:00
parent a5bf099008
commit 4ab4551470
1 changed files with 18 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

34
doc/lispref/variables.texi
View file

@ -2317,11 +2317,12 @@ Attempting to assign them any other value will result in an error:
@cindex generalized variable @cindex generalized variable
@cindex place form @cindex place form
A @dfn{generalized variable} or @dfn{place form} is one of the many places A @dfn{generalized variable} or @dfn{place form} is one of the many
in Lisp memory where values can be stored. The simplest place form is places in Lisp memory where values can be stored using the @code{setf}
a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements macro (@pxref{Setting Generalized Variables}). The simplest place
of arrays, properties of symbols, and many other locations are also form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of
places where Lisp values are stored. lists, elements of arrays, properties of symbols, and many other
locations are also places where Lisp values get stored.
Generalized variables are analogous to lvalues in the C Generalized variables are analogous to lvalues in the C
language, where @samp{x = a[i]} gets an element from an array language, where @samp{x = a[i]} gets an element from an array
@ -2342,8 +2343,8 @@ variables. The @code{setf} form is like @code{setq}, except that it
accepts arbitrary place forms on the left side rather than just accepts arbitrary place forms on the left side rather than just
symbols. For example, @code{(setf (car a) b)} sets the car of symbols. For example, @code{(setf (car a) b)} sets the car of
@code{a} to @code{b}, doing the same operation as @code{(setcar a b)}, @code{a} to @code{b}, doing the same operation as @code{(setcar a b)},
but without having to remember two separate functions for setting and but without you having to use two separate functions for setting and
accessing every type of place. accessing this type of place.
@defmac setf [place form]@dots{} @defmac setf [place form]@dots{}
This macro evaluates @var{form} and stores it in @var{place}, which This macro evaluates @var{form} and stores it in @var{place}, which
@ -2353,18 +2354,19 @@ just as with @code{setq}. @code{setf} returns the value of the last
@var{form}. @var{form}.
@end defmac @end defmac
The following Lisp forms will work as generalized variables, and The following Lisp forms are the forms in Emacs that will work as
so may appear in the @var{place} argument of @code{setf}: generalized variables, and so may appear in the @var{place} argument
of @code{setf}:
@itemize @itemize
@item @item
A symbol naming a variable. In other words, @code{(setf x y)} is A symbol. In other words, @code{(setf x y)} is exactly equivalent to
exactly equivalent to @code{(setq x y)}, and @code{setq} itself is @code{(setq x y)}, and @code{setq} itself is strictly speaking
strictly speaking redundant given that @code{setf} exists. Many redundant given that @code{setf} exists. Most programmers will
programmers continue to prefer @code{setq} for setting simple continue to prefer @code{setq} for setting simple variables, though,
variables, though, purely for stylistic or historical reasons. for stylistic and historical reasons. The macro @code{(setf x y)}
The macro @code{(setf x y)} actually expands to @code{(setq x y)}, actually expands to @code{(setq x y)}, so there is no performance
so there is no performance penalty for using it in compiled code. penalty for using it in compiled code.
@item @item
A call to any of the following standard Lisp functions: A call to any of the following standard Lisp functions: