X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/151d90884b7d06bf842273661f3c41b086bd5c3d..HEAD:/doc/lispref/variables.texi diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 79f5eaa7c2..dd3f18be4e 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Variables @chapter Variables @@ -10,10 +10,10 @@ 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 +be precise, under the default @dfn{dynamic scoping} rule, 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 +case under the @dfn{lexical scoping} rule. @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 @@ -25,7 +25,7 @@ representing the variable. @menu * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. +* Constant Variables:: Variables that never change. * Local Variables:: Variable values that exist only temporarily. * Void Variables:: Symbols that lack values. * Defining Variables:: A definition says a symbol is used as a variable. @@ -131,7 +131,7 @@ starts with @samp{:}, interned in the standard obarray, and returns @code{nil} otherwise. @end defun -These constants are fundamentally different from the ``constants'' +These constants are fundamentally different from the constants defined using the @code{defconst} special form (@pxref{Defining Variables}). A @code{defconst} form serves to inform human readers that you do not intend to change the value of a variable, but Emacs @@ -178,7 +178,7 @@ 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 +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}, @@ -263,7 +263,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. +where you are in Emacs. @defopt max-specpdl-size @anchor{Definition of max-specpdl-size} @@ -287,25 +287,27 @@ has room to execute. @end defopt @node Void Variables -@section When a Variable is ``Void'' +@section When a Variable is Void @cindex @code{void-variable} error @cindex void variable 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. +cell (@pxref{Symbol Components}). + + Under Emacs Lisp's default dynamic scoping rule (@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, instead +of returning a value. + + Under the optional lexical scoping rule, the value cell only holds +the variable's global value---the value outside of any lexical binding +construct. When a variable is lexically bound, the local value is +determined by the lexical environment; hence, variables can have local +values even if their symbols' value cells are unassigned. @defun makunbound symbol This function empties out the value cell of @var{symbol}, making the @@ -414,18 +416,23 @@ 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 @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{value} is specified, and @var{symbol} is void (i.e., it has no +dynamically bound value; @pxref{Void Variables}), then @var{value} is +evaluated and @var{symbol} is set to the result. But if @var{symbol} +is not void, @var{value} is not evaluated, and @var{symbol}'s value is +left 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, -not the current (buffer-local) binding. It sets the default value if +@code{defvar} acts on the default value, which is buffer-independent, +rather than the buffer-local binding. It sets the default value if the default value is void. @xref{Buffer-Local Variables}. +If @var{symbol} is already lexically bound (e.g., if the @code{defvar} +form occurs in a @code{let} form with lexical binding enabled), then +@code{defvar} sets the dynamic value. The lexical binding remains in +effect until its binding construct exits. @xref{Variable Scoping}. + When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} arranges to set the variable unconditionally, without @@ -538,8 +545,7 @@ The value is a list of forms (expressions). @item @dots{}-predicate The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. +non-@code{nil} for success and @code{nil} for failure. @item @dots{}-flag The value is significant only as to whether it is @code{nil} or not. @@ -557,7 +563,7 @@ The value specifies options for a command. @end table When you define a variable, always consider whether you should mark -it as ``safe'' or ``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 @@ -761,6 +767,7 @@ error is signaled. @node Variable Scoping @section Scoping Rules for Variable Bindings +@cindex scoping rule When you create a local binding for a variable, that binding takes effect only within a limited portion of the program (@pxref{Local @@ -774,12 +781,12 @@ 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 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 +bindings}. Such a binding has @dfn{dynamic 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. @@ -788,11 +795,12 @@ being executed. @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}. +variable must be located textually within the binding +construct@footnote{With some exceptions; for instance, a lexical +binding can also be accessed from the Lisp debugger.}. 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 @@ -814,22 +822,22 @@ 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. - Dynamic bindings have indefinite scope and dynamic extent, as shown -by the following example: + Dynamic bindings have dynamic scope and extent, as shown by the +following example: @example @group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} +(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + 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.} +;; @r{previous value, which is @minus{}99.} (getx) @result{} -99 @@ -837,20 +845,20 @@ by the following example: @end example @noindent -The function @code{getx} refers to @code{x}. This is a ``free'' +The function @code{getx} refers to @code{x}. This is a @dfn{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). +retrieves the local value (i.e., 1). But when we call @code{getx} +outside the @code{let} form, it retrieves the global value (i.e., +@minus{}99). Here is another example, which illustrates setting a dynamically bound variable using @code{setq}: @example @group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} +(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun addx () (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} @@ -861,7 +869,7 @@ bound variable using @code{setq}: @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.} +;; @r{previous value, which is @minus{}99.} (addx) @result{} -98 @@ -888,12 +896,11 @@ technique: @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. +only within a binding construct, such as the body of the @code{let} +form where the variable was bound. 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 @@ -925,12 +932,16 @@ variables like @code{case-fold-search}: @node Lexical Binding @subsection Lexical 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. + Lexical binding was introduced to Emacs, as an optional feature, in +version 24.1. We expect its importance to increase in the future. +Lexical binding opens up many more opportunities for optimization, so +programs using it are likely to run faster in future Emacs versions. +Lexical binding is also more compatible with concurrency, which we +want to add to Emacs in the future. - Here is an example + A lexically-bound variable has @dfn{lexical scope}, meaning that any +reference to the variable must be located textually within the binding +construct. Here is an example @iftex (see the next subsection, for how to actually enable lexical binding): @end iftex @@ -945,7 +956,7 @@ construct. @result{} 4 (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is lexically bound.} (getx)) @@ -969,6 +980,14 @@ 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. + (Internally, the lexical environment is an alist of symbol-value +pairs, with the final element in the alist being the symbol @code{t} +rather than a cons cell. Such an alist can be passed as the second +argument to the @code{eval} function, in order to specify a lexical +environment in which to evaluate a form. @xref{Eval}. Most Emacs +Lisp programs, however, should not interact directly with lexical +environments in this way; only specialized programs like debuggers.) + @cindex closures, example of using Lexical bindings have indefinite extent. Even after a binding construct has finished executing, its lexical environment can be @@ -988,7 +1007,7 @@ Here is an example: (setq my-ticker (lambda () (setq x (1+ x))))) @result{} (closure ((x . 0) t) () - (1+ x)) + (setq x (1+ x))) (funcall my-ticker) @result{} 1 @@ -1019,13 +1038,6 @@ binding of @code{x} in that lexical environment. 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 @@ -1069,19 +1081,22 @@ 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. + Converting an Emacs Lisp program to lexical binding is easy. First, +add a file-local variable setting of @code{lexical-binding} to +@code{t} in the header line of the Emacs Lisp source file (@pxref{File +Local Variables}). 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. +@cindex free variable +@cindex unused lexical variable 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 +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 @@ -1387,9 +1402,10 @@ buffer-local variable interactively, just as it is useful to create buffer-local variables interactively. @end deffn +@cindex local variables, killed by major mode @defun kill-all-local-variables This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local +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. @@ -1556,7 +1572,7 @@ 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 +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 how file-local variables are processed. @@ -1597,7 +1613,7 @@ 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 +@defun hack-local-variables &optional handle-mode This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable @code{enable-local-variables} has its effect here. However, this @@ -1614,11 +1630,15 @@ is non-@code{nil}; it always calls the other hook. This function ignores a @samp{mode} element if it specifies the same major mode as the buffer already has. -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return a symbol specifying the major mode, -if the @w{@samp{-*-}} line or the local variables list specifies one, -and @code{nil} otherwise. It does not set the mode nor any other -file-local variable. +If the optional argument @var{handle-mode} is @code{t}, then all this +function does is return a symbol specifying the major mode, if the +@w{@samp{-*-}} line or the local variables list specifies one, and +@code{nil} otherwise. It does not set the mode or any other +file-local variable. If @var{handle-mode} has any value other than +@code{nil} or @code{t}, any settings of @samp{mode} in the +@w{@samp{-*-}} line or the local variables list are ignored, and the +other settings are applied. If @var{handle-mode} is @code{nil}, all +the file local variables are set. @end defun @defvar file-local-variables-alist @@ -1649,8 +1669,7 @@ 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. +property value. When defining a user option using @code{defcustom}, you can set its @code{safe-local-variable} property by adding the arguments @@ -1835,9 +1854,16 @@ modification times of the associated directory local variables file updates this list. @end defvar +@defvar enable-dir-local-variables +If @code{nil}, directory-local variables are ignored. This variable +may be useful for modes that want to ignore directory-locals while +still respecting file-local variables (@pxref{File Local Variables}). +@end defvar + @node Variable Aliases @section Variable Aliases @cindex variable aliases +@cindex alias, for variables It is sometimes useful to make two variables synonyms, so that both variables always have the same value, and changing either one also @@ -1880,8 +1906,8 @@ 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}. +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 @@ -1929,6 +1955,7 @@ foo @node Variables with Restricted Values @section Variables with Restricted Values +@cindex lisp variables defined in C, restrictions Ordinary Lisp variables can be assigned any value that is a valid Lisp object. However, certain Lisp variables are not defined in Lisp, @@ -1954,7 +1981,7 @@ will set them to @code{t}: This variable holds a list of all variables of type @code{DEFVAR_BOOL}. @end defvar - Variables of type @code{DEFVAR_INT} can only take on integer values. + Variables of type @code{DEFVAR_INT} can take on only integer values. Attempting to assign them any other value will result in an error: @example @@ -1965,13 +1992,15 @@ Attempting to assign them any other value will result in an error: @node Generalized Variables @section Generalized Variables +@cindex generalized variable +@cindex place form A @dfn{generalized variable} or @dfn{place form} is one of the many places in Lisp memory where values can be stored. The simplest place form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values are stored. -Generalized variables are analogous to ``lvalues'' in the C +Generalized variables are analogous to lvalues in the C language, where @samp{x = a[i]} gets an element from an array and @samp{a[i] = x} stores an element using the same notation. Just as certain forms like @code{a[i]} can be lvalues in C, there @@ -2030,7 +2059,7 @@ cdar nthcdr A call to any of the following Emacs-specific functions: @smallexample -default-value process-get +alist-get process-get frame-parameter process-sentinel terminal-parameter window-buffer keymap-parent window-display-table @@ -2039,7 +2068,7 @@ overlay-get window-hscroll overlay-start window-parameter overlay-end window-point process-buffer window-start -process-filter +process-filter default-value @end smallexample @end itemize @@ -2144,7 +2173,7 @@ of Common Lisp. Consult the source file @file{gv.el} for more details. @cindex CL note---no @code{setf} functions @quotation @b{Common Lisp note:} Common Lisp defines another way to specify the -@code{setf} behavior of a function, namely ``@code{setf} functions'', +@code{setf} behavior of a function, namely @code{setf} functions, whose names are lists @code{(setf @var{name})} rather than symbols. For example, @code{(defun (setf foo) @dots{})} defines the function that is used when @code{setf} is applied to @code{foo}. Emacs does