X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/4f8a4547454e24304b4182fbf4ae4b34a7bdc92b..33017fafd17d722e82a268e9b272f27df261e09d:/doc/lispref/variables.texi diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 091765043e..0be496a3c4 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,27 +1,26 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. -@setfilename ../../info/variables @node Variables, Functions, Control Structures, Top @chapter Variables @cindex variable A @dfn{variable} is a name used in a program to stand for a value. -Nearly all programming languages have variables of some sort. In the -text of a Lisp program, variables are written using the syntax for -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}. - - 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 +In Lisp, each variable is represented by a Lisp symbol +(@pxref{Symbols}). The variable name is simply the symbol's name, and +the variable's value is stored in the symbol's value cell@footnote{To +be precise, under the default @dfn{dynamic binding} rules the value +cell always holds the variable's current value, but this is not the +case under @dfn{lexical binding} rules. @xref{Variable Scoping}, for +details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a +symbol as a variable is independent of its use as a function name. + + As previously noted in this manual, a Lisp program is represented +primarily by Lisp objects, and only secondarily as text. The textual +form of a Lisp program is given by the read syntax of the Lisp objects +that constitute the program. Hence, the textual form of a variable in +a Lisp program is written using the read syntax for the symbol representing the variable. @menu @@ -145,63 +144,63 @@ does not raise an error if you actually change it. @cindex global binding Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to create variable values that -exist temporarily---only until a certain part of the program finishes. -These values are called @dfn{local}, and the variables so used are -called @dfn{local variables}. - - For example, when a function is called, its argument variables receive -new local values that last until the function exits. The @code{let} -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 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 -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. -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. +with new values. Sometimes it is useful to give a variable a +@dfn{local value}---a value that takes effect only within a certain +part of a Lisp program. When a variable has a local value, we say +that it is @dfn{locally bound} to that value, and that it is a +@dfn{local variable}. + + For example, when a function is called, its argument variables +receive local values, which are the actual arguments supplied to the +function call; these local bindings take effect within the body of the +function. To take another example, the @code{let} special form +explicitly establishes local bindings for specific variables, which +take effect within the body of the @code{let} form. We also speak of the @dfn{global binding}, which is where (conceptually) the global value is kept. +@cindex shadowing of variables + Establishing a local binding saves away the variable's previous +value (or lack of one). We say that the previous value is +@dfn{shadowed}. Both global and local values may be shadowed. If a +local binding is in effect, using @code{setq} on the local variable +stores the specified value in the local binding. When that local +binding is no longer in effect, the previously shadowed value (or lack +of one) comes back. + @cindex current binding - A variable can have more than one local binding at a time (for -example, if there are nested @code{let} forms that bind it). In such a -case, the most recently created local binding that still exists is the -@dfn{current binding} of the variable. (This rule is called -@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no -local bindings, the variable's global binding is its current binding. -We sometimes call the current binding the @dfn{most-local existing -binding}, for emphasis. Ordinary evaluation of a symbol always returns -the value of its current binding. - - The special forms @code{let} and @code{let*} exist to create -local bindings. + A variable can have more than one local binding at a time (e.g.@: if +there are nested @code{let} forms that bind the variable). The +@dfn{current binding} is the local binding that is actually in effect. +It determines the value returned by evaluating the variable symbol, +and it is the binding acted on by @code{setq}. + + For most purposes, you can think of the current binding as the +``innermost'' local binding, or the global binding if there is no +local binding. To be more precise, a rule called the @dfn{scoping +rule} determines where in a program a local binding takes effect. The +default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, +which simply states that the current binding at any given point in the +execution of a program is the most recently-created binding for that +variable that still exists. For details about dynamic scoping, and an +alternative scoping rule called @dfn{lexical scoping}, @xref{Variable +Scoping}. + + The special forms @code{let} and @code{let*} exist to create local +bindings: @defspec let (bindings@dots{}) forms@dots{} -This special form binds variables according to @var{bindings} and then -evaluates all of the @var{forms} in textual order. The @code{let}-form -returns the value of the last form in @var{forms}. +This special form sets up local bindings for a certain set of +variables, as specified by @var{bindings}, and then evaluates all of +the @var{forms} in textual order. Its return value is the value of +the last form in @var{forms}. Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is bound to @code{nil}; or @w{(ii) a} list of the form -@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is -bound to the result of evaluating @var{value-form}. If @var{value-form} -is omitted, @code{nil} is used. +that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the +form @code{(@var{symbol} @var{value-form})}, in which case +@var{symbol} is locally bound to the result of evaluating +@var{value-form}. If @var{value-form} is omitted, @code{nil} is used. All of the @var{value-form}s in @var{bindings} are evaluated in the order they appear and @emph{before} binding any of the symbols to them. @@ -213,6 +212,7 @@ Here is an example of this: @code{z} is bound to the old value of (setq y 2) @result{} 2 @end group + @group (let ((y 1) (z y)) @@ -226,15 +226,15 @@ Here is an example of this: @code{z} is bound to the old value of This special form is like @code{let}, but it binds each variable right after computing its local value, before computing the local value for the next variable. Therefore, an expression in @var{bindings} can -reasonably refer to the preceding symbols bound in this @code{let*} -form. Compare the following example with the example above for -@code{let}. +refer to the preceding symbols bound in this @code{let*} form. +Compare the following example with the example above for @code{let}. @example @group (setq y 2) @result{} 2 @end group + @group (let* ((y 1) (z y)) ; @r{Use the just-established value of @code{y}.} @@ -262,7 +262,7 @@ Macro calls (@pxref{Macros}). Variables}); a few variables have terminal-local bindings (@pxref{Multiple Terminals}). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs, rather than localized in time. +``where'' you are in Emacs. @defopt max-specpdl-size @anchor{Definition of max-specpdl-size} @@ -280,7 +280,7 @@ that Lisp avoids infinite recursion on an ill-defined function. @code{max-lisp-eval-depth} provides another limit on depth of nesting. @xref{Definition of max-lisp-eval-depth,, Eval}. -The default value is 1000. Entry to the Lisp debugger increases the +The default value is 1300. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute. @end defopt @@ -290,46 +290,33 @@ has room to execute. @cindex @code{void-variable} error @cindex void variable - If you have never given a symbol any value as a global variable, we -say that that symbol's global value is @dfn{void}. In other words, the -symbol's value cell does not have any Lisp object in it. If you try to -evaluate the symbol, you get a @code{void-variable} error rather than -a value. - - Note that a value of @code{nil} is not the same as void. The symbol -@code{nil} is a Lisp object and can be the value of a variable just as any -other object can be; but it is @emph{a value}. A void variable does not -have any value. - - After you have given a variable a value, you can make it void once more -using @code{makunbound}. + We say that a variable is void if its symbol has an unassigned value +cell (@pxref{Symbol Components}). Under Emacs Lisp's default dynamic +binding rules (@pxref{Variable Scoping}), the value cell stores the +variable's current (local or global) value. Note that an unassigned +value cell is @emph{not} the same as having @code{nil} in the value +cell. The symbol @code{nil} is a Lisp object and can be the value of +a variable, just as any other object can be; but it is still a value. +If a variable is void, trying to evaluate the variable signals a +@code{void-variable} error rather than a value. + + Under lexical binding rules, the value cell only holds the +variable's global value, i.e.@: the value outside of any lexical +binding construct. When a variable is lexically bound, the local value +is determined by the lexical environment; the variable may have a +local value if its symbol's value cell is unassigned. @defun makunbound symbol -This function makes the current variable binding of @var{symbol} void. -Subsequent attempts to use this symbol's value as a variable will signal -the error @code{void-variable}, unless and until you set it again. +This function empties out the value cell of @var{symbol}, making the +variable void. It returns @var{symbol}. -@code{makunbound} returns @var{symbol}. +If @var{symbol} has a dynamic local binding, @code{makunbound} voids +the current binding, and this voidness lasts only as long as the local +binding is in effect. Afterwards, the previously shadowed local or +global binding is reexposed; then the variable will no longer be void, +unless the reexposed binding is void too. -@example -@group -(makunbound 'x) ; @r{Make the global value of @code{x} void.} - @result{} x -@end group -@group -x -@error{} Symbol's value as variable is void: x -@end group -@end example - -If @var{symbol} is locally bound, @code{makunbound} affects the most -local existing binding. This is the only way a symbol can have a void -local binding, since all the constructs that create local bindings -create them with values. In this case, the voidness lasts at most as -long as the binding does; when the binding is removed due to exit from -the construct that made it, the previous local or global binding is -reexposed as usual, and the variable is no longer void unless the newly -reexposed binding was void all along. +Here are some examples (assuming dynamic binding is in effect): @smallexample @group @@ -361,17 +348,11 @@ x ; @r{The global binding is unchanged.} @end smallexample @end defun - A variable that has been made void with @code{makunbound} is -indistinguishable from one that has never received a value and has -always been void. - - You can use the function @code{boundp} to test whether a variable is -currently void. - @defun boundp variable -@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; -more precisely, if its current binding is not void. It returns -@code{nil} otherwise. +This function returns @code{t} if @var{variable} (a symbol) is not +void, and @code{nil} if it is void. + +Here are some examples (assuming dynamic binding is in effect): @smallexample @group @@ -402,52 +383,41 @@ more precisely, if its current binding is not void. It returns @section Defining Global Variables @cindex variable definition - You may announce your intention to use a symbol as a global variable -with a @dfn{variable definition}: a special form, either @code{defconst} -or @code{defvar}. - - In Emacs Lisp, definitions serve three purposes. First, they inform -people who read the code that certain symbols are @emph{intended} to be -used a certain way (as variables). Second, they inform the Lisp system -of these things, supplying a value and documentation. Third, they -provide information to utilities such as @code{etags} and -@code{make-docfile}, which create data bases of the functions and -variables in a program. - - The difference between @code{defconst} and @code{defvar} is primarily -a matter of intent, serving to inform human readers of whether the value -should ever change. Emacs Lisp does not restrict the ways in which a -variable can be used based on @code{defconst} or @code{defvar} -declarations. However, it does make a difference for initialization: -@code{defconst} unconditionally initializes the variable, while -@code{defvar} initializes it only if it is void. - -@ignore - One would expect user option variables to be defined with -@code{defconst}, since programs do not change them. Unfortunately, this -has bad results if the definition is in a library that is not preloaded: -@code{defconst} would override any prior value when the library is -loaded. Users would like to be able to set user options in their init -files, and override the default values given in the definitions. For -this reason, user options must be defined with @code{defvar}. -@end ignore + A @dfn{variable definition} is a construct that announces your +intention to use a symbol as a global variable. It uses the special +forms @code{defvar} or @code{defconst}, which are documented below. + + A variable definition serves three purposes. First, it informs +people who read the code that the symbol is @emph{intended} to be used +a certain way (as a variable). Second, it informs the Lisp system of +this, optionally supplying an initial value and a documentation +string. Third, it provides information to programming tools such as +@command{etags}, allowing them to find where the variable was defined. + + The difference between @code{defconst} and @code{defvar} is mainly a +matter of intent, serving to inform human readers of whether the value +should ever change. Emacs Lisp does not actually prevent you from +changing the value of a variable defined with @code{defconst}. One +notable difference between the two forms is that @code{defconst} +unconditionally initializes the variable, whereas @code{defvar} +initializes it only if it is originally void. + + To define a customizable variable, you should use @code{defcustom} +(which calls @code{defvar} as a subroutine). @xref{Customization}. @defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a variable and can also -initialize and document it. The definition informs a person reading -your code that @var{symbol} is used as a variable that might be set or -changed. It also declares this variable as @dfn{special}, meaning that it -should always use dynamic scoping rules. Note that @var{symbol} is not -evaluated; the symbol to be defined must appear explicitly in the -@code{defvar}. +This special form defines @var{symbol} as a variable. Note that +@var{symbol} is not evaluated; the symbol to be defined should appear +explicitly in the @code{defvar} form. The variable is marked as +@dfn{special}, meaning that it should always be dynamically bound +(@pxref{Variable Scoping}). If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates it and sets @var{symbol} to the result. But if @var{symbol} -already has a value (i.e., it is not void), @var{value} is not even -evaluated, and @var{symbol}'s value remains unchanged. -If @var{value} is omitted, the value of @var{symbol} is not changed in any -case; instead, the only effect of @code{defvar} is to declare locally that this -variable exists elsewhere and should hence always use dynamic scoping rules. +evaluates @var{value} and sets @var{symbol} to the result. But if +@var{symbol} already has a value (i.e.@: it is not void), @var{value} +is not even evaluated, and @var{symbol}'s value remains unchanged. If +@var{value} is omitted, the value of @var{symbol} is not changed in +any case. If @var{symbol} has a buffer-local binding in the current buffer, @code{defvar} operates on the default value, which is buffer-independent, @@ -459,19 +429,9 @@ Emacs Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} arranges to set the variable unconditionally, without testing whether its value is void. -If the @var{doc-string} argument appears, it specifies the documentation -for the variable. (This opportunity to specify documentation is one of -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 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}. +If the @var{doc-string} argument is supplied, it specifies the +documentation string for the variable (stored in the symbol's +@code{variable-documentation} property). @xref{Documentation}. Here are some examples. This form defines @code{foo} but does not initialize it: @@ -494,38 +454,6 @@ it a documentation string: @end group @end example -The following form changes the documentation string for @code{bar}, -making it a user option, but does not change the value, since @code{bar} -already has a value. (The addition @code{(1+ nil)} would get an error -if it were evaluated, but since it is not evaluated, there is no error.) - -@example -@group -(defvar bar (1+ nil) - "*The normal weight of a bar.") - @result{} bar -@end group -@group -bar - @result{} 23 -@end group -@end example - -Here is an equivalent expression for the @code{defvar} special form: - -@example -@group -(defvar @var{symbol} @var{value} @var{doc-string}) -@equiv{} -(progn - (if (not (boundp '@var{symbol})) - (setq @var{symbol} @var{value})) - (if '@var{doc-string} - (put '@var{symbol} 'variable-documentation '@var{doc-string})) - '@var{symbol}) -@end group -@end example - The @code{defvar} form returns @var{symbol}, but it is normally used at top level in a file where its value does not matter. @end defspec @@ -538,6 +466,11 @@ global value, established here, that should not be changed by the user or by other programs. Note that @var{symbol} is not evaluated; the symbol to be defined must appear explicitly in the @code{defconst}. +The @code{defconst} form, like @code{defvar}, marks the variable as +@dfn{special}, meaning that it should always be dynamically bound +(@pxref{Variable Scoping}). In addition, it marks the variable as +risky (@pxref{File Local Variables}). + @code{defconst} always evaluates @var{value}, and sets the value of @var{symbol} to the result. If @var{symbol} does have a buffer-local binding in the current buffer, @code{defconst} sets the default value, @@ -545,7 +478,7 @@ not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined with @code{defconst}.) -An example of the use of @code{defconst} is Emacs' definition of +An example of the use of @code{defconst} is Emacs's definition of @code{float-pi}---the mathematical constant @math{pi}, which ought not to be changed by anyone (attempts by the Indiana State Legislature notwithstanding). As the second form illustrates, however, @@ -567,37 +500,13 @@ float-pi @end example @end defspec -@defun user-variable-p variable -@cindex user option -This function returns @code{t} if @var{variable} is a user option---a -variable intended to be set by the user for customization---and -@code{nil} otherwise. (Variables other than user options exist for the -internal purposes of Lisp programs, and users need not know about them.) - -User option variables are distinguished from other variables either -though being declared using @code{defcustom}@footnote{They may also be -declared equivalently in @file{cus-start.el}.} or by the first character -of their @code{variable-documentation} property. If the property exists -and is a string, and its first character is @samp{*}, then the variable -is a user option. Aliases of user options are also user options. -@end defun - -@cindex @code{variable-interactive} property -@findex set-variable - If a user option variable has a @code{variable-interactive} property, -the @code{set-variable} command uses that value to control reading the -new value for the variable. The property's value is used as if it were -specified in @code{interactive} (@pxref{Using Interactive}). However, -this feature is largely obsoleted by @code{defcustom} -(@pxref{Customization}). - - @strong{Warning:} If the @code{defconst} and @code{defvar} special -forms are used while the variable has a local binding (made with -@code{let}, or a function argument), they set the local-binding's -value; the top-level binding is not changed. This is not what you -usually want. To prevent it, use these special forms at top level in -a file, where normally no local binding is in effect, and make sure to -load the file before making a local binding for the variable. + @strong{Warning:} If you use a @code{defconst} or @code{defvar} +special form while the variable has a local binding (made with +@code{let}, or a function argument), it sets the local binding rather +than the global binding. This is not what you usually want. To +prevent this, use these special forms at top level in a file, where +normally no local binding is in effect, and make sure to load the file +before making a local binding for the variable. @node Tips for Defining @section Tips for Defining Variables Robustly @@ -667,9 +576,9 @@ loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents (such -as, to rebind keys). Third, evaluating the @code{defvar} form with -@kbd{C-M-x} @emph{will} reinitialize the map completely. +important if the user has run hooks to alter part of the contents +(such as, to rebind keys). Third, evaluating the @code{defvar} form +with @kbd{C-M-x} will reinitialize the map completely. Putting so much code in the @code{defvar} form has one disadvantage: it puts the documentation string far away from the line which names the @@ -690,37 +599,27 @@ This has all the same advantages as putting the initialization inside the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on each form, if you do want to reinitialize the variable. - But be careful not to write the code like this: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (setq my-mode-map (make-sparse-keymap)) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{}) -@end example - -@noindent -This code sets the variable, then alters it, but it does so in more than -one step. If the user quits just after the @code{setq}, that leaves the -variable neither correctly initialized nor void nor @code{nil}. Once -that happens, reloading the file will not initialize the variable; it -will remain incomplete. - @node Accessing Variables @section Accessing Variable Values The usual way to reference a variable is to write the symbol which -names it (@pxref{Symbol Forms}). This requires you to specify the -variable name when you write the program. Usually that is exactly what -you want to do. Occasionally you need to choose at run time which -variable to reference; then you can use @code{symbol-value}. +names it. @xref{Symbol Forms}. + + Occasionally, you may want to reference a variable which is only +determined at run time. In that case, you cannot specify the variable +name in the text of the program. You can use the @code{symbol-value} +function to extract the value. @defun symbol-value symbol -This function returns the value of @var{symbol}. This is the value in -the innermost local binding of the symbol, or its global value if it -has no local bindings. +This function returns the value stored in @var{symbol}'s value cell. +This is where the variable's current (dynamic) value is stored. If +the variable has no local binding, this is simply its global value. +If the variable is void, a @code{void-variable} error is signaled. + +If the variable is lexically bound, the value reported by +@code{symbol-value} is not necessarily the same as the variable's +lexical value, which is determined by the lexical environment rather +than the symbol's value cell. @xref{Variable Scoping}. @example @group @@ -754,13 +653,10 @@ has no local bindings. @result{} 5 @end group @end example - -A @code{void-variable} error is signaled if the current binding of -@var{symbol} is void. @end defun @node Setting Variables -@section How to Alter a Variable Value +@section Setting Variable Values The usual way to change the value of a variable is with the special form @code{setq}. When you need to compute the choice of variable at @@ -769,12 +665,12 @@ run time, use the function @code{set}. @defspec setq [symbol form]@dots{} This special form is the most common method of changing a variable's value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The most-local existing -binding of the symbol is changed. +evaluating the corresponding @var{form}. The current binding of the +symbol is changed. @code{setq} does not evaluate @var{symbol}; it sets the symbol that you write. We say that this argument is @dfn{automatically quoted}. The -@samp{q} in @code{setq} stands for ``quoted.'' +@samp{q} in @code{setq} stands for ``quoted''. The value of the @code{setq} form is the value of the last @var{form}. @@ -809,12 +705,17 @@ second @var{symbol} is set, and so on: @end defspec @defun set symbol value -This function sets @var{symbol}'s value to @var{value}, then returns -@var{value}. Since @code{set} is a function, the expression written for -@var{symbol} is evaluated to obtain the symbol to set. - -The most-local existing binding of the variable is the binding that is -set; shadowed bindings are not affected. +This function puts @var{value} in the value cell of @var{symbol}. +Since it is a function rather than a special form, the expression +written for @var{symbol} is evaluated to obtain the symbol to set. +The return value is @var{value}. + +When dynamic variable binding is in effect (the default), @code{set} +has the same effect as @code{setq}, apart from the fact that +@code{set} evaluates its @var{symbol} argument whereas @code{setq} +does not. But when a variable is lexically bound, @code{set} affects +its @emph{dynamic} value, whereas @code{setq} affects its current +(lexical) value. @xref{Variable Scoping}. @example @group @@ -854,327 +755,337 @@ error is signaled. (set '(x y) 'z) @error{} Wrong type argument: symbolp, (x y) @end example - -Logically speaking, @code{set} is a more fundamental primitive than -@code{setq}. Any use of @code{setq} can be trivially rewritten to use -@code{set}; @code{setq} could even be defined as a macro, given the -availability of @code{set}. However, @code{set} itself is rarely used; -beginners hardly need to know about it. It is useful only for choosing -at run time which variable to set. For example, the command -@code{set-variable}, which reads a variable name from the user and then -sets the variable, needs to use @code{set}. - -@cindex CL note---@code{set} local -@quotation -@b{Common Lisp note:} In Common Lisp, @code{set} always changes the -symbol's ``special'' or dynamic value, ignoring any lexical bindings. -In Emacs Lisp, all variables and all bindings are dynamic, so @code{set} -always affects the most local existing binding. -@end quotation @end defun @node Variable Scoping @section Scoping Rules for Variable Bindings - A given symbol @code{foo} can have several local variable bindings, -established at different places in the Lisp program, as well as a global -binding. The most recently established binding takes precedence over -the others. + When you create a local binding for a variable, that binding takes +effect only within a limited portion of the program (@pxref{Local +Variables}). This section describes exactly what this means. @cindex scope @cindex extent -@cindex dynamic scoping -@cindex lexical scoping - By default, local bindings in Emacs Lisp have @dfn{indefinite scope} and -@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in -the source code the binding can be accessed. ``Indefinite scope'' means -that any part of the program can potentially access the variable -binding. @dfn{Extent} refers to @emph{when}, as the program is -executing, the binding exists. ``Dynamic extent'' means that the binding -lasts as long as the activation of the construct that established it. - - The combination of dynamic extent and indefinite scope is called -@dfn{dynamic scoping}. By contrast, most programming languages use -@dfn{lexical scoping}, in which references to a local variable must be -located textually within the function or block that binds the variable. -Emacs can also support lexical scoping, upon request (@pxref{Lexical -Binding}). - -@cindex CL note---special variables -@quotation -@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are -dynamically scoped, like all variables in Emacs Lisp. -@end quotation + Each local binding has a certain @dfn{scope} and @dfn{extent}. +@dfn{Scope} refers to @emph{where} in the textual source code the +binding can be accessed. @dfn{Extent} refers to @emph{when}, as the +program is executing, the binding exists. + +@cindex dynamic binding +@cindex indefinite scope +@cindex dynamic extent + By default, the local bindings that Emacs creates are @dfn{dynamic +bindings}. Such a binding has @dfn{indefinite scope}, meaning that +any part of the program can potentially access the variable binding. +It also has @dfn{dynamic extent}, meaning that the binding lasts only +while the binding construct (such as the body of a @code{let} form) is +being executed. + +@cindex lexical binding +@cindex lexical scope +@cindex indefinite extent + Emacs can optionally create @dfn{lexical bindings}. A lexical +binding has @dfn{lexical scope}, meaning that any reference to the +variable must be located textually within the binding construct. It +also has @dfn{indefinite extent}, meaning that under some +circumstances the binding can live on even after the binding construct +has finished executing, by means of special objects called +@dfn{closures}. + + The following subsections describe dynamic binding and lexical +binding in greater detail, and how to enable lexical binding in Emacs +Lisp programs. @menu -* Scope:: Scope means where in the program a value is visible. - Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and avoid problems. -* Lexical Binding:: Use of lexical scoping. +* Dynamic Binding:: The default for binding local variables in Emacs. +* Dynamic Binding Tips:: Avoiding problems with dynamic binding. +* Lexical Binding:: A different type of local variable binding. +* Using Lexical Binding:: How to enable lexical binding. @end menu -@node Scope -@subsection Scope +@node Dynamic Binding +@subsection Dynamic Binding + + By default, the local variable bindings made by Emacs are dynamic +bindings. When a variable is dynamically bound, its current binding +at any point in the execution of the Lisp program is simply the most +recently-created dynamic local binding for that symbol, or the global +binding if there is no such local binding. - Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. -This means that any function anywhere in the program text might access a -given binding of a variable. Consider the following function -definitions: + Dynamic bindings have indefinite scope and dynamic extent, as shown +by the following example: @example @group -(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} - (foo 5)) ; @r{@code{foo} is some other function.} -@end group +(defvar x -99) ; @r{@code{x} receives an initial value of -99.} -@group -(defun user () ; @r{@code{x} is used ``free'' in @code{user}.} - (list x)) +(defun getx () + x) ; @r{@code{x} is used ``free'' in this function.} + +(let ((x 1)) ; @r{@code{x} is dynamically bound.} + (getx)) + @result{} 1 + +;; @r{After the @code{let} form finishes, @code{x} reverts to its} +;; @r{previous value, which is -99.} + +(getx) + @result{} -99 @end group @end example - In a lexically scoped language, the binding of @code{x} in -@code{binder} would never be accessible in @code{user}, because -@code{user} is not textually contained within the function -@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} -may or may not refer to the binding of @code{x} established in -@code{binder}, depending on the circumstances: - -@itemize @bullet -@item -If we call @code{user} directly without calling @code{binder} at all, -then whatever binding of @code{x} is found, it cannot come from -@code{binder}. +@noindent +The function @code{getx} refers to @code{x}. This is a ``free'' +reference, in the sense that there is no binding for @code{x} within +that @code{defun} construct itself. When we call @code{getx} from +within a @code{let} form in which @code{x} is (dynamically) bound, it +retrieves the local value of @code{x} (i.e.@: 1). But when we call +@code{getx} outside the @code{let} form, it retrieves the global value +of @code{x} (i.e.@: -99). -@item -If we define @code{foo} as follows and then call @code{binder}, then the -binding made in @code{binder} will be seen in @code{user}: + Here is another example, which illustrates setting a dynamically +bound variable using @code{setq}: @example @group -(defun foo (lose) - (user)) +(defvar x -99) ; @r{@code{x} receives an initial value of -99.} + +(defun addx () + (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} + +(let ((x 1)) + (addx) + (addx)) + @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.} + +;; @r{After the @code{let} form finishes, @code{x} reverts to its} +;; @r{previous value, which is -99.} + +(addx) + @result{} -98 @end group @end example -@item -However, if we define @code{foo} as follows and then call @code{binder}, -then the binding made in @code{binder} @emph{will not} be seen in -@code{user}: + Dynamic binding is implemented in Emacs Lisp in a simple way. Each +symbol has a value cell, which specifies its current dynamic value (or +absence of value). @xref{Symbol Components}. When a symbol is given +a dynamic local binding, Emacs records the contents of the value cell +(or absence thereof) in a stack, and stores the new local value in the +value cell. When the binding construct finishes executing, Emacs pops +the old value off the stack, and puts it in the value cell. -@example -(defun foo (x) - (user)) -@end example +@node Dynamic Binding Tips +@subsection Proper Use of Dynamic Binding -@noindent -Here, when @code{foo} is called by @code{binder}, it binds @code{x}. -(The binding in @code{foo} is said to @dfn{shadow} the one made in -@code{binder}.) Therefore, @code{user} will access the @code{x} bound -by @code{foo} instead of the one bound by @code{binder}. -@end itemize + Dynamic binding is a powerful feature, as it allows programs to +refer to variables that are not defined within their local textual +scope. However, if used without restraint, this can also make +programs hard to understand. There are two clean ways to use this +technique: -Emacs Lisp used dynamic scoping by default because simple implementations of -lexical scoping are slow. In addition, every Lisp system needs to offer -dynamic scoping at least as an option; if lexical scoping is the norm, there -must be a way to specify dynamic scoping instead for a particular variable. -Nowadays, Emacs offers both, but the default is still to use exclusively -dynamic scoping. - -@node Extent -@subsection Extent - - @dfn{Extent} refers to the time during program execution that a -variable name is valid. In Emacs Lisp, a variable is valid only while -the form that bound it is executing. This is called @dfn{dynamic -extent}. ``Local'' or ``automatic'' variables in most languages, -including C and Pascal, have dynamic extent. - - One alternative to dynamic extent is @dfn{indefinite extent}. This -means that a variable binding can live on past the exit from the form -that made the binding. Common Lisp and Scheme, for example, support -this, but Emacs Lisp does not. - - To illustrate this, the function below, @code{make-add}, returns a -function that purports to add @var{n} to its own argument @var{m}. This -would work in Common Lisp, but it does not do the job in Emacs Lisp, -because after the call to @code{make-add} exits, the variable @code{n} -is no longer bound to the actual argument 2. +@itemize @bullet +@item +If a variable has no global definition, use it as a local variable +only within a binding construct, e.g.@: the body of the @code{let} +form where the variable was bound, or the body of the function for an +argument variable. If this convention is followed consistently +throughout a program, the value of the variable will not affect, nor +be affected by, any uses of the same variable symbol elsewhere in the +program. + +@item +Otherwise, define the variable with @code{defvar}, @code{defconst}, or +@code{defcustom}. @xref{Defining Variables}. Usually, the definition +should be at top-level in an Emacs Lisp file. As far as possible, it +should include a documentation string which explains the meaning and +purpose of the variable. You should also choose the variable's name +to avoid name conflicts (@pxref{Coding Conventions}). + +Then you can bind the variable anywhere in a program, knowing reliably +what the effect will be. Wherever you encounter the variable, it will +be easy to refer back to the definition, e.g.@: via the @kbd{C-h v} +command (provided the variable definition has been loaded into Emacs). +@xref{Name Help,,, emacs, The GNU Emacs Manual}. + +For example, it is common to use local bindings for customizable +variables like @code{case-fold-search}: @example -(defun make-add (n) - (function (lambda (m) (+ n m)))) ; @r{Return a function.} - @result{} make-add -(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} - ; @r{with @code{(make-add 2)}.} - @result{} (lambda (m) (+ n m)) -(add2 4) ; @r{Try to add 2 to 4.} -@error{} Symbol's value as variable is void: n +@group +(defun search-for-abc () + "Search for the string \"abc\", ignoring case differences." + (let ((case-fold-search nil)) + (re-search-forward "abc"))) +@end group @end example +@end itemize -@cindex closures not available - Some Lisp dialects have ``closures,'' objects that are like functions -but record additional variable bindings. Emacs Lisp does not have -closures. +@node Lexical Binding +@subsection Lexical Binding -@node Impl of Scope -@subsection Implementation of Dynamic Scoping -@cindex deep binding +Optionally, you can create lexical bindings in Emacs Lisp. A +lexically bound variable has @dfn{lexical scope}, meaning that any +reference to the variable must be located textually within the binding +construct. - A simple sample implementation (which is not how Emacs Lisp actually -works) may help you understand dynamic binding. This technique is -called @dfn{deep binding} and was used in early Lisp systems. + Here is an example +@iftex +(see the next subsection, for how to actually enable lexical binding): +@end iftex +@ifnottex +(@pxref{Using Lexical Binding}, for how to actually enable lexical binding): +@end ifnottex - Suppose there is a stack of bindings, which are variable-value pairs. -At entry to a function or to a @code{let} form, we can push bindings -onto the stack for the arguments or local variables created there. We -can pop those bindings from the stack at exit from the binding -construct. +@example +@group +(let ((x 1)) ; @r{@code{x} is lexically bound.} + (+ x 3)) + @result{} 4 - We can find the value of a variable by searching the stack from top to -bottom for a binding for that variable; the value from that binding is -the value of the variable. To set the variable, we search for the -current binding, then store the new value into that binding. - - As you can see, a function's bindings remain in effect as long as it -continues execution, even during its calls to other functions. That is -why we say the extent of the binding is dynamic. And any other function -can refer to the bindings, if it uses the same variables while the -bindings are in effect. That is why we say the scope is indefinite. - -@cindex shallow binding - The actual implementation of variable scoping in GNU Emacs Lisp uses a -technique called @dfn{shallow binding}. Each variable has a standard -place in which its current value is always found---the value cell of the -symbol. - - In shallow binding, setting the variable works by storing a value in -the value cell. Creating a new binding works by pushing the old value -(belonging to a previous binding) onto a stack, and storing the new -local value in the value cell. Eliminating a binding works by popping -the old value off the stack, into the value cell. - - We use shallow binding because it has the same results as deep -binding, but runs faster, since there is never a need to search for a -binding. +(defun getx () + x) ; @r{@code{x} is used ``free'' in this function.} -@node Using Scoping -@subsection Proper Use of Dynamic Scoping +(let ((x 1)) ; @r{@code{x} is lexically bound.} + (getx)) +@error{} Symbol's value as variable is void: x +@end group +@end example - Binding a variable in one function and using it in another is a -powerful technique, but if used without restraint, it can make programs -hard to understand. There are two clean ways to use this technique: +@noindent +Here, the variable @code{x} has no global value. When it is lexically +bound within a @code{let} form, it can be used in the textual confines +of that @code{let} form. But it can @emph{not} be used from within a +@code{getx} function called from the @code{let} form, since the +function definition of @code{getx} occurs outside the @code{let} form +itself. + +@cindex lexical environment + Here is how lexical binding works. Each binding construct defines a +@dfn{lexical environment}, specifying the symbols that are bound +within the construct and their local values. When the Lisp evaluator +wants the current value of a variable, it looks first in the lexical +environment; if the variable is not specified in there, it looks in +the symbol's value cell, where the dynamic value is stored. + +@cindex closures + Lexical bindings have indefinite extent. Even after a binding +construct has finished executing, its lexical environment can be +``kept around'' in Lisp objects called @dfn{closures}. A closure is +created when you create a named or anonymous function with lexical +binding enabled. @xref{Closures}, for details. + + When a closure is called as a function, any lexical variable +references within its definition use the retained lexical environment. +Here is an example: -@itemize @bullet -@item -Use or bind the variable only in a few related functions, written close -together in one file. Such a variable is used for communication within -one program. +@example +(defvar my-ticker nil) ; @r{We will use this dynamically bound} + ; @r{variable to store a closure.} -You should write comments to inform other programmers that they can see -all uses of the variable before them, and to advise them not to add uses -elsewhere. +(let ((x 0)) ; @r{@code{x} is lexically bound.} + (setq my-ticker (lambda () + (setq x (1+ x))))) + @result{} (closure ((x . 0) t) () + (1+ x)) -@item -Give the variable a well-defined, documented meaning, and make all -appropriate functions refer to it (but not bind it or set it) wherever -that meaning is relevant. For example, the variable -@code{case-fold-search} is defined as ``non-@code{nil} means ignore case -when searching''; various search and replace functions refer to it -directly or through their subroutines, but do not bind or set it. - -Then you can bind the variable in other programs, knowing reliably what -the effect will be. -@end itemize +(funcall my-ticker) + @result{} 1 - In either case, you should define the variable with @code{defvar}. -This helps other people understand your program by telling them to look -for inter-function usage. It also avoids a warning from the byte -compiler. Choose the variable's name to avoid name conflicts---don't -use short names like @code{x}. +(funcall my-ticker) + @result{} 2 +(funcall my-ticker) + @result{} 3 -@node Lexical Binding -@subsection Use of Lexical Scoping +x ; @r{Note that @code{x} has no global value.} +@error{} Symbol's value as variable is void: x +@end example -Emacs Lisp can be evaluated in two different modes: in dynamic binding -mode or lexical binding mode. In dynamic binding mode, all local -variables use dynamic scoping, whereas in lexical binding mode -variables that have been declared @dfn{special} (i.e., declared with -@code{defvar}, @code{defcustom} or @code{defconst}) use dynamic -scoping and all others use lexical scoping. +@noindent +The @code{let} binding defines a lexical environment in which the +variable @code{x} is locally bound to 0. Within this binding +construct, we define a lambda expression which increments @code{x} by +one and returns the incremented value. This lambda expression is +automatically turned into a closure, in which the lexical environment +lives on even after the @code{let} binding construct has exited. Each +time we evaluate the closure, it increments @code{x}, using the +binding of @code{x} in that lexical environment. + + Note that functions like @code{symbol-value}, @code{boundp}, and +@code{set} only retrieve or modify a variable's dynamic binding +(i.e.@: the contents of its symbol's value cell). Also, the code in +the body of a @code{defun} or @code{defmacro} cannot refer to +surrounding lexical variables. + + Currently, lexical binding is not much used within the Emacs +sources. However, we expect its importance to increase in the future. +Lexical binding opens up a lot more opportunities for optimization, so +Emacs Lisp code that makes use of lexical binding is likely to run +faster in future Emacs versions. Such code is also much more friendly +to concurrency, which we want to add to Emacs in the near future. + +@node Using Lexical Binding +@subsection Using Lexical Binding + + When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical +binding is enabled if the buffer-local variable @code{lexical-binding} +is non-@code{nil}: @defvar lexical-binding -When non-nil, evaluation of Lisp code uses lexical scoping for non-special -local variables instead of dynamic scoping. If nil, dynamic scoping is used -for all local variables. This variable is typically set for a whole Elisp file -via file local variables (@pxref{File Local Variables}). +If this buffer-local variable is non-@code{nil}, Emacs Lisp files and +buffers are evaluated using lexical binding instead of dynamic +binding. (However, special variables are still dynamically bound; see +below.) If @code{nil}, dynamic binding is used for all local +variables. This variable is typically set for a whole Emacs Lisp +file, as a file local variable (@pxref{File Local Variables}). +Note that unlike other such variables, this one must be set in the +first line of a file. @end defvar +@noindent +When evaluating Emacs Lisp code directly using an @code{eval} call, +lexical binding is enabled if the @var{lexical} argument to +@code{eval} is non-@code{nil}. @xref{Eval}. + +@cindex special variables + Even when lexical binding is enabled, certain variables will +continue to be dynamically bound. These are called @dfn{special +variables}. Every variable that has been defined with @code{defvar}, +@code{defcustom} or @code{defconst} is a special variable +(@pxref{Defining Variables}). All other variables are subject to +lexical binding. + @defun special-variable-p SYMBOL -Return whether SYMBOL has been declared as a special variable, via -@code{defvar} or @code{defconst}. +This function returns non-@code{nil} if @var{symbol} is a special +variable (i.e.@: it has a @code{defvar}, @code{defcustom}, or +@code{defconst} variable definition). Otherwise, the return value is +@code{nil}. @end defun -The use of a special variable as a formal argument in a function is generally -discouraged and its behavior in lexical binding mode is unspecified (it may use -lexical scoping sometimes and dynamic scoping other times). - -Functions like @code{symbol-value}, @code{boundp}, or @code{set} only know -about dynamically scoped variables, so you cannot get the value of a lexical -variable via @code{symbol-value} and neither can you change it via @code{set}. -Another particularity is that code in the body of a @code{defun} or -@code{defmacro} cannot refer to surrounding lexical variables. - -Evaluation of a @code{lambda} expression in lexical binding mode will not just -return that lambda expression unchanged, as in the dynamic binding case, but -will instead construct a new object that remembers the current lexical -environment in which that lambda expression was defined, so that the function -body can later be evaluated in the proper context. Those objects are called -@dfn{closures}. They are also functions, in the sense that they are accepted -by @code{funcall}, and they are represented by a cons cell whose @code{car} is -the symbol @code{closure}. - -@menu -* Converting to Lexical Binding:: How to start using lexical scoping -@end menu - -@node Converting to Lexical Binding -@subsubsection Converting a package to use lexical scoping - -Lexical scoping, as currently implemented, does not bring many significant -benefits, unless you are a seasoned functional programmer addicted to -higher-order functions. But its importance will increase in the future: -lexical scoping opens up a lot more opportunities for optimization, so -lexically scoped code is likely to run faster in future Emacs versions, and it -is much more friendly to concurrency, which we want to add in the near future. - -Converting a package to lexical binding is usually pretty easy and should not -break backward compatibility: just add a file-local variable setting -@code{lexical-binding} to @code{t} and add declarations of the form -@code{(defvar @var{VAR})} for every variable which still needs to use -dynamic scoping. - -To find which variables need this declaration, the simplest solution is to -check the byte-compiler's warnings. The byte-compiler will usually find those -variables either because they are used outside of a let-binding (leading to -warnings about reference or assignment to ``free variable @var{VAR}'') or -because they are let-bound but not used within the let-binding (leading to -warnings about ``unused lexical variable @var{VAR}''). - -In cases where a dynamically scoped variable was bound as a function argument, -you will also need to move this binding to a @code{let}. These cases are also -flagged by the byte-compiler. - -To silence byte-compiler warnings about unused variables, just use a variable -name that start with an underscore, which the byte-compiler interpret as an -indication that this is a variable known not to be used. - -In most cases, the resulting code will then work with either setting of -@code{lexical-binding}, so it can still be used with older Emacsen (which will -simply ignore the @code{lexical-binding} variable setting). + The use of a special variable as a formal argument in a function is +discouraged. Doing so gives rise to unspecified behavior when lexical +binding mode is enabled (it may use lexical binding sometimes, and +dynamic binding other times). + + Converting an Emacs Lisp program to lexical binding is pretty easy. +First, add a file-local variable setting of @code{lexical-binding} to +@code{t} in the Emacs Lisp source file. Second, check that every +variable in the program which needs to be dynamically bound has a +variable definition, so that it is not inadvertently bound lexically. + + A simple way to find out which variables need a variable definition +is to byte-compile the source file. @xref{Byte Compilation}. If a +non-special variable is used outside of a @code{let} form, the +byte-compiler will warn about reference or assignment to a ``free +variable''. If a non-special variable is bound but not used within a +@code{let} form, the byte-compiler will warn about an ``unused lexical +variable''. The byte-compiler will also issue a warning if you use a +special variable as a function argument. + + (To silence byte-compiler warnings about unused variables, just use +a variable name that start with an underscore. The byte-compiler +interprets this as an indication that this is a variable known not to +be used.) @node Buffer-Local Variables @section Buffer-Local Variables @@ -1279,7 +1190,8 @@ foo @result{} 'a @end group @end example - Note that references to @code{foo} in @var{body} access the +@noindent +Note that references to @code{foo} in @var{body} access the buffer-local binding of buffer @samp{b}. When a file specifies local variable values, these become buffer-local @@ -1351,7 +1263,10 @@ needed if you use the @var{local} argument to @code{add-hook} or @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 -local to the current buffer at the time. +local to the current buffer at the time. Unlike +@code{make-local-variable}, with which it is often confused, this +cannot be undone, and affects the behavior of the variable in all +buffers. A peculiar wrinkle of this feature is that binding the variable (with @code{let} or other binding constructs) does not create a buffer-local @@ -1401,11 +1316,12 @@ value (@pxref{Default Value}) of @var{variable} instead. @defun buffer-local-variables &optional buffer This function returns a list describing the buffer-local variables in -buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is -used.) It returns an association list (@pxref{Association Lists}) in -which each element contains one buffer-local variable and its value. -However, when a variable's buffer-local binding in @var{buffer} is void, -then the variable appears directly in the resulting list. +buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer +is used.) Normally, each list element has the form +@w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local +variable (a symbol) and @var{val} is its buffer-local value. But when +a variable's buffer-local binding in @var{buffer} is void, its list +element is just @var{sym}. @example @group @@ -1657,6 +1573,13 @@ Query (once) about all the variables. @end table @end defopt +@defvar inhibit-local-variables-regexps +This is a list of regular expressions. If a file has a name +matching an element of this list, then it is not scanned for +any form of file-local variable. For examples of why you might want +to use this, @pxref{Auto Major Mode}. +@end defvar + @defun hack-local-variables &optional mode-only This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable @@ -1712,6 +1635,11 @@ 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. + When defining a user option using @code{defcustom}, you can set its +@code{safe-local-variable} property by adding the arguments +@code{:safe @var{function}} to @code{defcustom} (@pxref{Variable +Definitions}). + @defopt safe-local-variable-values This variable provides another way to mark some variable values as safe. It is a list of cons cells @code{(@var{var} . @var{val})}, @@ -1731,28 +1659,31 @@ the value @var{val}, based on the above criteria. @end defun @c @cindex risky local variable Duplicates risky-local-variable - Some variables are considered @dfn{risky}. A variable whose name -ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function}, + Some variables are considered @dfn{risky}. If a variable is risky, +it is never entered automatically into +@code{safe-local-variable-values}; Emacs always queries before setting +a risky variable, unless the user explicitly allows a value by +customizing @code{safe-local-variable-values} directly. + + Any variable whose name has a non-@code{nil} +@code{risky-local-variable} property is considered risky. When you +define a user option using @code{defcustom}, you can set its +@code{risky-local-variable} property by adding the arguments +@code{:risky @var{value}} to @code{defcustom} (@pxref{Variable +Definitions}). In addition, any variable whose name ends in any of +@samp{-command}, @samp{-frame-alist}, @samp{-function}, @samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, -@samp{-program}, or @samp{-predicate} is considered risky. The -variables @samp{font-lock-keywords}, @samp{font-lock-keywords} -followed by a digit, and @samp{font-lock-syntactic-keywords} are also -considered risky. Finally, any variable whose name has a -non-@code{nil} @code{risky-local-variable} property is considered -risky. +@samp{-program}, or @samp{-predicate} is automatically considered +risky. The variables @samp{font-lock-keywords}, +@samp{font-lock-keywords} followed by a digit, and +@samp{font-lock-syntactic-keywords} are also considered risky. @defun risky-local-variable-p sym This function returns non-@code{nil} if @var{sym} is a risky variable, based on the above criteria. @end defun - If a variable is risky, it will not be entered automatically into -@code{safe-local-variable-values} as described above. Therefore, -Emacs will always query before setting a risky variable, unless the -user explicitly allows the setting by customizing -@code{safe-local-variable-values} directly. - @defvar ignored-local-variables This variable holds a list of variables that should not be given local values by files. Any value specified for one of these variables is @@ -1829,6 +1760,15 @@ function works by calling @code{dir-locals-set-class-variables} and @code{dir-locals-set-directory-class}, described below. @end defun +@defun hack-dir-local-variables-non-file-buffer +This function looks for directory-local variables, and immediately +applies them in the current buffer. It is intended to be called in +the mode commands for non-file buffers, such as Dired buffers, to let +them obey directory-local variable settings. For non-file buffers, +Emacs looks for directory-local variables in @code{default-directory} +and its parent directories. +@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 @@ -1912,16 +1852,19 @@ variable with a new name. @code{make-obsolete-variable} declares that the old name is obsolete and therefore that it may be removed at some stage in the future. -@defun make-obsolete-variable obsolete-name current-name &optional when +@defun make-obsolete-variable obsolete-name current-name when &optional access-type This function makes the byte compiler warn that the variable -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is -the variable's new name; then the warning message says to use -@var{current-name} instead of @var{obsolete-name}. If @var{current-name} -is a string, this is the message and there is no replacement variable. - -If provided, @var{when} should be a string indicating when the -variable was first made obsolete---for example, a date or a release -number. +@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, +it is the variable's new name; then the warning message says to use +@var{current-name} instead of @var{obsolete-name}. If +@var{current-name} is a string, this is the message and there is no +replacement variable. @var{when} should be a string indicating when +the variable was first made obsolete (usually a version number +string). + +The optional argument @var{access-type}, if non-@code{nil}, should +should specify the kind of access that will trigger obsolescence +warnings; it can be either @code{get} or @code{set}. @end defun You can make two variables synonyms and declare one obsolete at the @@ -1998,6 +1941,6 @@ This variable holds a list of all variables of type @code{DEFVAR_BOOL}. Attempting to assign them any other value will result in an error: @example -(setq window-min-height 5.0) -@error{} Wrong type argument: integerp, 5.0 +(setq undo-limit 1000.0) +@error{} Wrong type argument: integerp, 1000.0 @end example