X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/7ad8fe5e2876518a8f33b80050f98dab4ff78398..b1f23349eb103eba22f9e2181f97a5fc939f86e0:/doc/lispref/variables.texi diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 1dd2a57945..592279d011 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/variables @node Variables, Functions, Control Structures, Top @@ -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. @@ -39,8 +38,9 @@ variable. * Setting Variables:: Storing new values in variables. * Variable Scoping:: How Lisp chooses among local and global values. * Buffer-Local Variables:: Variable values in effect only in one buffer. -* Future Local Variables:: New kinds of local values we might add some day. * 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. * 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. @@ -64,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 @@ -151,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 @@ -163,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. @@ -265,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 @@ -456,13 +457,13 @@ the main benefits of defining the variable.) The documentation is stored in the symbol's @code{variable-documentation} property. The Emacs help functions (@pxref{Documentation}) look for this property. -If the variable is a user option that users would want to set -interactively, you should use @samp{*} as the first character of -@var{doc-string}. This lets users set the variable conveniently using -the @code{set-variable} command. Note that you should nearly always -use @code{defcustom} instead of @code{defvar} to define these -variables, so that users can use @kbd{M-x customize} and related -commands to set them. @xref{Customization}. +If the documentation string begins with the character @samp{*}, Emacs +allows users to set it interactively using the @code{set-variable} +command. However, you should nearly always use @code{defcustom} +instead of @code{defvar} to define such variables, so that users can +use @kbd{M-x customize} and related commands to set them. In that +case, it is not necessary to begin the documentation string with +@samp{*}. @xref{Customization}. Here are some examples. This form defines @code{foo} but does not initialize it: @@ -619,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. @@ -631,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 @@ -1087,8 +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}.) +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. @@ -1187,6 +1191,10 @@ buffer-local binding of buffer @samp{b}. values when you visit the file. @xref{File Variables,,, emacs, The GNU Emacs Manual}. + A buffer-local variable cannot be made frame-local +(@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple +Displays}). + @node Creating Buffer-Local @subsection Creating and Deleting Buffer-Local Bindings @@ -1195,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. @@ -1238,9 +1245,9 @@ is not current either on entry to or exit from the @code{let}. This is because @code{let} does not distinguish between different kinds of bindings; it knows only which variable the binding was made for. -If the variable is terminal-local, this function signals an error. Such -variables cannot have buffer-local bindings as well. @xref{Multiple -Displays}. +If the variable is terminal-local (@pxref{Multiple Displays}), or +frame-local (@pxref{Frame-Local Variables}), this function signals an +error. Such variables cannot have buffer-local bindings as well. @strong{Warning:} do not use @code{make-local-variable} for a hook variable. The hook variables are automatically made buffer-local as @@ -1355,8 +1362,10 @@ buffer-local variables interactively. @defun kill-all-local-variables This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent.'' As a -result, the buffer will see the default values of most variables. +current buffer except for variables marked as ``permanent'' and local +hook functions that have a non-@code{nil} @code{permanent-local-hook} +property (@pxref{Setting Hooks}). As a result, the buffer will see +the default values of most variables. This function also resets certain other information pertaining to the buffer: it sets the local keymap to @code{nil}, the syntax table to the @@ -1513,25 +1522,6 @@ an ordinary evaluated argument. @end example @end defun -@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. - @node File Local Variables @section File Local Variables @cindex file local variables @@ -1539,12 +1529,18 @@ local bindings, we will provide it in a subsequent Emacs version. 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 @@ -1569,27 +1565,48 @@ function does not look for the @samp{mode:} local variable in the @w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking @code{enable-local-variables} into account (@pxref{Auto Major Mode}). +This function works by walking the alist stored in +@code{file-local-variables-alist} and applying each local variable in +turn. It calls @code{before-hack-local-variables-hook} and +@code{hack-local-variables-hook} before and after applying the +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 - 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. +@defvar file-local-variables-alist +This buffer-local variable holds the alist of file-local variable +settings. Each element of the alist is of the form +@w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of +the local variable and @var{value} is its value. When Emacs visits a +file, it first collects all the file-local variables into this alist, +and then the @code{hack-local-variables} function applies them one by +one. +@end defvar + +@defvar before-hack-local-variables-hook +Emacs calls this hook immediately before applying file-local variables +stored in @code{file-local-variables-alist}. +@end defvar + +@defvar hack-local-variables-hook +Emacs calls this hook immediately after it finishes applying +file-local variables stored in @code{file-local-variables-alist}. +@end defvar @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 @@ -1597,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 @@ -1664,7 +1681,115 @@ 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 +@cindex directory local variables + + A directory can specify local variable values common to all files in +that directory; Emacs uses these to create buffer-local bindings for +those variables in buffers visiting any file in that directory. This +is useful when the files in the directory belong to some @dfn{project} +and therefore share the same local variables. + + There are two different methods for specifying directory local +variables: by putting them in a special file, or by defining a +@dfn{project class} for that directory. + +@defvr Constant dir-locals-file +This constant is the name of the file where Emacs expects to find the +directory-local variables. The name of the file is +@file{.dir-locals.el}@footnote{ +The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to +limitations of the DOS filesystems. +}. A file by that name in a directory causes Emacs to apply its +settings to any file in that directory or any of its subdirectories. +If some of the subdirectories have their own @file{.dir-locals.el} +files, Emacs uses the settings from the deepest file it finds starting +from the file's directory and moving up the directory tree. The file +specifies local variables as a specially formatted list; see +@ref{Directory Variables, , Per-directory Local Variables, emacs, The +GNU Emacs Manual}, for more details. +@end defvr + +@defun hack-dir-local-variables +This function reads the @code{.dir-locals.el} file and stores the +directory-local variables in @code{file-local-variables-alist} that is +local to the buffer visiting any file in the directory, without +applying them. It also stores the directory-local settings in +@code{dir-locals-class-alist}, where it defines a special class for +the directory in which @file{.dir-locals.el} file was found. This +function works by calling @code{dir-locals-set-class-variables} and +@code{dir-locals-set-directory-class}, described below. +@end defun + +@defun dir-locals-set-class-variables class variables +This function defines a set of variable settings for the named +@var{class}, which is a symbol. You can later assign the class to one +or more directories, and Emacs will apply those variable settings to +all files in those directories. The list in @var{variables} can be of +one of the two forms: @code{(@var{major-mode} . @var{alist})} or +@code{(@var{directory} . @var{list})}. With the first form, if the +file's buffer turns on a mode that is derived from @var{major-mode}, +then the all the variables in the associated @var{alist} are applied; +@var{alist} should be of the form @code{(@var{name} . @var{value})}. +A special value @code{nil} for @var{major-mode} means the settings are +applicable to any mode. + +With the second form of @var{variables}, if @var{directory} is the +initial substring of the file's directory, then @var{list} is applied +recursively by following the above rules; @var{list} should be of one +of the two forms accepted by this function in @var{variables}. +@end defun + +@defun dir-locals-set-directory-class directory class +This function assigns @var{class} to all the files in @code{directory} +and its subdirectories. Thereafter, all the variable settings +specified for @var{class} will be applied to any visited file in +@var{directory} and its children. @var{class} must have been already +defined by @code{dir-locals-set-class-variables} +@end defun + +@defvar dir-locals-class-alist +This alist holds the class symbols and the associated variable +settings. It is updated by @code{dir-locals-set-class-variables}. +@end defvar + +@defvar dir-locals-directory-alist +This alist holds directory names and their assigned class names. It +is updated by @code{dir-locals-set-directory-class}. +@end defvar + +@node Frame-Local Variables +@section Frame-Local Values for Variables +@cindex frame-local variables + + 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. + + 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}))) +@end lisp + +@noindent +This causes the variable @var{var} to be bound to the specified +@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