X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6ed161e1d6f2210883ad9ac5a008a9ad7633d4b8..b1f23349eb103eba22f9e2181f97a5fc939f86e0:/doc/lispref/variables.texi diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 75cfd783c6..592279d011 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -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 @@ -621,6 +620,8 @@ arguments. @item @dots{}-flag The value is significant only as to whether it is @code{nil} or not. +Since such variables often end up acquiring more values over time, +this convention is not strongly recommended. @item @dots{}-program The value is a program name. @@ -633,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 @@ -1089,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. @@ -1190,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}). @@ -1202,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. @@ -1529,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 @@ -1568,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 @@ -1591,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 @@ -1613,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 @@ -1680,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 @@ -1767,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}))) @@ -1779,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}. - -@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. +@var{value} in the named @var{frame}. To check the frame-specific +values of such variables, use @code{frame-parameter}. @xref{Parameter +Access}. + + Note that you cannot have a frame-local binding for a variable that +has a buffer-local binding. @node Variable Aliases @section Variable Aliases