(Variables): Clarify introduction.
(Global Variables): Mention that setq is a special form. (Local Variables): Use active voice. (Tips for Defining): Mention marking variables as safe. (Buffer-Local Variables): Mention terminal-local and frame-local variables together. (File Local Variables): Copyedits. (Frame-Local Variables): Note that they are not really useful. (Future Local Variables): Node deleted.
This commit is contained in:
Chong Yidong
parent
d0884adf3e
commit
3277011456
1 changed files with 64 additions and 83 deletions
|
|
@ -15,16 +15,15 @@ symbols.
|
|||
|
||||
In Lisp, unlike most programming languages, programs are represented
|
||||
primarily as Lisp objects and only secondarily as text. The Lisp
|
||||
objects used for variables are symbols: the symbol name is the variable
|
||||
name, and the variable's value is stored in the value cell of the
|
||||
symbol. The use of a symbol as a variable is independent of its use as
|
||||
a function name. @xref{Symbol Components}.
|
||||
objects used for variables are symbols: the symbol name is the
|
||||
variable name, and the variable's value is stored in the value cell of
|
||||
the symbol. The use of a symbol as a variable is independent of its
|
||||
use as a function name. @xref{Symbol Components}.
|
||||
|
||||
The Lisp objects that constitute a Lisp program determine the textual
|
||||
form of the program---it is simply the read syntax for those Lisp
|
||||
objects. This is why, for example, a variable in a textual Lisp program
|
||||
is written using the read syntax for the symbol that represents the
|
||||
variable.
|
||||
The textual form of a Lisp program is given by the read syntax of
|
||||
the Lisp objects that constitute the program. Hence, a variable in a
|
||||
textual Lisp program is written using the read syntax for the symbol
|
||||
representing the variable.
|
||||
|
||||
@menu
|
||||
* Global Variables:: Variable values that exist permanently, everywhere.
|
||||
|
|
@ -42,7 +41,6 @@ variable.
|
|||
* File Local Variables:: Handling local variable lists in files.
|
||||
* Directory Local Variables:: Local variables common to all files in a directory.
|
||||
* Frame-Local Variables:: Frame-local bindings for variables.
|
||||
* Future Local Variables:: New kinds of local values we might add some day.
|
||||
* Variable Aliases:: Variables that are aliases for other variables.
|
||||
* Variables with Restricted Values:: Non-constant variables whose value can
|
||||
@emph{not} be an arbitrary Lisp object.
|
||||
|
|
@ -66,11 +64,12 @@ old one, no trace of the old value remains in the variable.
|
|||
|
||||
@noindent
|
||||
gives the variable @code{x} the value @code{(a b)}. Note that
|
||||
@code{setq} does not evaluate its first argument, the name of the
|
||||
variable, but it does evaluate the second argument, the new value.
|
||||
@code{setq} is a special form (@pxref{Special Forms}); it does not
|
||||
evaluate its first argument, the name of the variable, but it does
|
||||
evaluate the second argument, the new value.
|
||||
|
||||
Once the variable has a value, you can refer to it by using the symbol
|
||||
by itself as an expression. Thus,
|
||||
Once the variable has a value, you can refer to it by using the
|
||||
symbol itself as an expression. Thus,
|
||||
|
||||
@example
|
||||
@group
|
||||
|
|
@ -153,11 +152,11 @@ special form explicitly establishes new local values for specified
|
|||
variables; these last until exit from the @code{let} form.
|
||||
|
||||
@cindex shadowing of variables
|
||||
Establishing a local value saves away the previous value (or lack of
|
||||
one) of the variable. When the life span of the local value is over,
|
||||
the previous value is restored. In the mean time, we say that the
|
||||
previous value is @dfn{shadowed} and @dfn{not visible}. Both global and
|
||||
local values may be shadowed (@pxref{Scope}).
|
||||
Establishing a local value saves away the variable's previous value
|
||||
(or lack of one). We say that the previous value is @dfn{shadowed}
|
||||
and @dfn{not visible}. Both global and local values may be shadowed
|
||||
(@pxref{Scope}). After the life span of the local value is over, the
|
||||
previous value (or lack of one) is restored.
|
||||
|
||||
If you set a variable (such as with @code{setq}) while it is local,
|
||||
this replaces the local value; it does not alter the global value, or
|
||||
|
|
@ -165,10 +164,10 @@ previous local values, that are shadowed. To model this behavior, we
|
|||
speak of a @dfn{local binding} of the variable as well as a local value.
|
||||
|
||||
The local binding is a conceptual place that holds a local value.
|
||||
Entry to a function, or a special form such as @code{let}, creates the
|
||||
local binding; exit from the function or from the @code{let} removes the
|
||||
local binding. As long as the local binding lasts, the variable's value
|
||||
is stored within it. Use of @code{setq} or @code{set} while there is a
|
||||
Entering a function, or a special form such as @code{let}, creates the
|
||||
local binding; exiting the function or the @code{let} removes the
|
||||
local binding. While the local binding lasts, the variable's value is
|
||||
stored within it. Using @code{setq} or @code{set} while there is a
|
||||
local binding stores a different value into the local binding; it does
|
||||
not create a new binding.
|
||||
|
||||
|
|
@ -267,9 +266,9 @@ like ordinary local bindings, but they are localized depending on
|
|||
@cindex evaluation error
|
||||
@cindex infinite recursion
|
||||
This variable defines the limit on the total number of local variable
|
||||
bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
|
||||
Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
|
||||
error (with data @code{"Variable binding depth exceeds
|
||||
bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,,
|
||||
Cleaning Up from Nonlocal Exits}) that are allowed before Emacs
|
||||
signals an error (with data @code{"Variable binding depth exceeds
|
||||
max-specpdl-size"}).
|
||||
|
||||
This limit, with the associated error when it is exceeded, is one way
|
||||
|
|
@ -635,7 +634,7 @@ The value specifies options for a command.
|
|||
@end table
|
||||
|
||||
When you define a variable, always consider whether you should mark
|
||||
it as ``risky''; see @ref{File Local Variables}.
|
||||
it as ``safe'' or ``risky''; see @ref{File Local Variables}.
|
||||
|
||||
When defining and initializing a variable that holds a complicated
|
||||
value (such as a keymap with bindings in it), it's best to put the
|
||||
|
|
@ -1091,9 +1090,9 @@ languages in one form or another. Emacs, however, also supports
|
|||
additional, unusual kinds of variable binding, such as
|
||||
@dfn{buffer-local} bindings, which apply only in one buffer. Having
|
||||
different values for a variable in different buffers is an important
|
||||
customization method. (A few variables have bindings that are local
|
||||
to each terminal; see @ref{Multiple Displays}. You can also have
|
||||
frame-local bindings for variables; see @ref{Frame-Local Variables}.)
|
||||
customization method. (Variables can also have bindings that are
|
||||
local to each terminal, or to each frame. @xref{Multiple Displays},
|
||||
and @xref{Frame-Local Variables}.)
|
||||
|
||||
@menu
|
||||
* Intro to Buffer-Local:: Introduction and concepts.
|
||||
|
|
@ -1192,7 +1191,7 @@ buffer-local binding of buffer @samp{b}.
|
|||
values when you visit the file. @xref{File Variables,,, emacs, The
|
||||
GNU Emacs Manual}.
|
||||
|
||||
A variable cannot be both buffer-local and frame-local
|
||||
A buffer-local variable cannot be made frame-local
|
||||
(@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple
|
||||
Displays}).
|
||||
|
||||
|
|
@ -1204,7 +1203,6 @@ This function creates a buffer-local binding in the current buffer for
|
|||
@var{variable} (a symbol). Other buffers are not affected. The value
|
||||
returned is @var{variable}.
|
||||
|
||||
@c Emacs 19 feature
|
||||
The buffer-local value of @var{variable} starts out as the same value
|
||||
@var{variable} previously had. If @var{variable} was void, it remains
|
||||
void.
|
||||
|
|
@ -1531,12 +1529,18 @@ an ordinary evaluated argument.
|
|||
A file can specify local variable values; Emacs uses these to create
|
||||
buffer-local bindings for those variables in the buffer visiting that
|
||||
file. @xref{File variables, , Local Variables in Files, emacs, The
|
||||
GNU Emacs Manual}, for basic information about file local variables.
|
||||
This section describes the functions and variables that affect
|
||||
processing of file local variables.
|
||||
GNU Emacs Manual}, for basic information about file-local variables.
|
||||
This section describes the functions and variables that affect how
|
||||
file-local variables are processed.
|
||||
|
||||
If a file-local variable could specify an arbitrary function or Lisp
|
||||
expression that would be called later, visiting a file could take over
|
||||
your Emacs. Emacs protects against this by automatically setting only
|
||||
those file-local variables whose specified values are known to be
|
||||
safe. Other file-local variables are set only if the user agrees.
|
||||
|
||||
@defopt enable-local-variables
|
||||
This variable controls whether to process file local variables.
|
||||
This variable controls whether to process file-local variables.
|
||||
The possible values are:
|
||||
|
||||
@table @asis
|
||||
|
|
@ -1570,7 +1574,7 @@ variables, respectively.
|
|||
If the optional argument @var{mode-only} is non-@code{nil}, then all
|
||||
this function does is return @code{t} if the @w{@samp{-*-}} line or
|
||||
the local variables list specifies a mode and @code{nil} otherwise.
|
||||
It does not set the mode nor any other file local variable.
|
||||
It does not set the mode nor any other file-local variable.
|
||||
@end defun
|
||||
|
||||
@defvar file-local-variables-alist
|
||||
|
|
@ -1593,21 +1597,16 @@ Emacs calls this hook immediately after it finishes applying
|
|||
file-local variables stored in @code{file-local-variables-alist}.
|
||||
@end defvar
|
||||
|
||||
If a file local variable could specify a function that would
|
||||
be called later, or an expression that would be executed later, simply
|
||||
visiting a file could take over your Emacs. Emacs takes several
|
||||
measures to prevent this.
|
||||
|
||||
@cindex safe local variable
|
||||
You can specify safe values for a variable with a
|
||||
@code{safe-local-variable} property. The property has to be
|
||||
a function of one argument; any value is safe if the function
|
||||
returns non-@code{nil} given that value. Many commonly encountered
|
||||
file variables standardly have @code{safe-local-variable} properties,
|
||||
including @code{fill-column}, @code{fill-prefix}, and
|
||||
@code{indent-tabs-mode}. For boolean-valued variables that are safe,
|
||||
use @code{booleanp} as the property value. Lambda expressions should
|
||||
be quoted so that @code{describe-variable} can display the predicate.
|
||||
@code{safe-local-variable} property. The property has to be a
|
||||
function of one argument; any value is safe if the function returns
|
||||
non-@code{nil} given that value. Many commonly-encountered file
|
||||
variables have @code{safe-local-variable} properties; these include
|
||||
@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}.
|
||||
For boolean-valued variables that are safe, use @code{booleanp} as the
|
||||
property value. Lambda expressions should be quoted so that
|
||||
@code{describe-variable} can display the predicate.
|
||||
|
||||
@defopt safe-local-variable-values
|
||||
This variable provides another way to mark some variable values as
|
||||
|
|
@ -1615,7 +1614,7 @@ safe. It is a list of cons cells @code{(@var{var} . @var{val})},
|
|||
where @var{var} is a variable name and @var{val} is a value which is
|
||||
safe for that variable.
|
||||
|
||||
When Emacs asks the user whether or not to obey a set of file local
|
||||
When Emacs asks the user whether or not to obey a set of file-local
|
||||
variable specifications, the user can choose to mark them as safe.
|
||||
Doing so adds those variable/value pairs to
|
||||
@code{safe-local-variable-values}, and saves it to the user's custom
|
||||
|
|
@ -1682,7 +1681,7 @@ such predicates (it's safe if any predicate succeeds), or @code{t}
|
|||
|
||||
Text properties are also potential loopholes, since their values
|
||||
could include functions to call. So Emacs discards all text
|
||||
properties from string values specified for file local variables.
|
||||
properties from string values specified for file-local variables.
|
||||
|
||||
@node Directory Local Variables
|
||||
@section Directory Local Variables
|
||||
|
|
@ -1769,11 +1768,15 @@ is updated by @code{dir-locals-set-directory-class}.
|
|||
In addition to buffer-local variable bindings (@pxref{Buffer-Local
|
||||
Variables}), Emacs supports @dfn{frame-local} bindings. A frame-local
|
||||
binding for a variable is in effect in a frame for which it was
|
||||
defined. Note that you cannot have frame-local bindings for a
|
||||
variable that has a buffer-local binding.
|
||||
defined.
|
||||
|
||||
To define a frame-specific binding for a variable @var{var} in frame
|
||||
@var{frame}, set the @var{var} frame parameter for that frame:
|
||||
In practice, frame-local variables have not proven very useful.
|
||||
Ordinary frame parameters are generally used instead (@pxref{Frame
|
||||
Parameters}). The function @code{make-variable-frame-local}, which
|
||||
was used to define frame-local variables, has been deprecated since
|
||||
Emacs 22.2. However, you can still define a frame-specific binding
|
||||
for a variable @var{var} in frame @var{frame}, by setting the
|
||||
@var{var} frame parameter for that frame:
|
||||
|
||||
@lisp
|
||||
(modify-frame-parameters @var{frame} '((@var{var} . @var{value})))
|
||||
|
|
@ -1781,34 +1784,12 @@ variable that has a buffer-local binding.
|
|||
|
||||
@noindent
|
||||
This causes the variable @var{var} to be bound to the specified
|
||||
@var{value} in the named @var{frame}. @xref{Parameter Access,
|
||||
modify-frame-parameters}.
|
||||
@var{value} in the named @var{frame}. To check the frame-specific
|
||||
values of such variables, use @code{frame-parameter}. @xref{Parameter
|
||||
Access}.
|
||||
|
||||
@findex make-variable-frame-local@r{, deprecated}
|
||||
Use of @code{make-variable-frame-local} for defining frame-local
|
||||
bindings is deprecated since Emacs 22.2.
|
||||
|
||||
To check the frame-specific values of such variables, use
|
||||
@code{frame-parameter} (@pxref{Parameter Access, frame-parameter}).
|
||||
|
||||
@node Future Local Variables
|
||||
@section Possible Future Local Variables
|
||||
|
||||
We have considered the idea of bindings that are local to a category
|
||||
of frames---for example, all color frames, or all frames with dark
|
||||
backgrounds. We have not implemented them because it is not clear that
|
||||
this feature is really useful. You can get more or less the same
|
||||
results by adding a function to @code{after-make-frame-functions}, set up to
|
||||
define a particular frame parameter according to the appropriate
|
||||
conditions for each frame.
|
||||
|
||||
It would also be possible to implement window-local bindings. We
|
||||
don't know of many situations where they would be useful, and it seems
|
||||
that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
|
||||
bindings offer a way to handle these situations more robustly.
|
||||
|
||||
If sufficient application is found for either of these two kinds of
|
||||
local bindings, we will provide it in a subsequent Emacs version.
|
||||
Note that you cannot have a frame-local binding for a variable that
|
||||
has a buffer-local binding.
|
||||
|
||||
@node Variable Aliases
|
||||
@section Variable Aliases
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue