X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6142d1d06cbc870f82591f85eaa908541d9bb4f9..b3ab615bc11f85df1a242dbdebd713a3ac5534e9:/lispref/variables.texi diff --git a/lispref/variables.texi b/lispref/variables.texi index ab5e99e506..38fb929c16 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -1,6 +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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, +@c 2000, 2003, 2004 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/variables @@ -41,8 +42,10 @@ variable. * Buffer-Local Variables:: Variable values in effect only in one buffer. * Frame-Local Variables:: Variable values in effect only in one frame. * Future Local Variables:: New kinds of local values we might add some day. -* Variable Aliases:: Variables that are aliases for other variables. * File Local Variables:: Handling local variable lists in files. +* 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. @end menu @node Global Variables @@ -259,18 +262,20 @@ they are localized depending on ``where'' you are in Emacs, rather than localized in time. @defvar max-specpdl-size +@anchor{Definition of max-specpdl-size} @cindex variable limit error @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{Nonlocal Exits}) -that are allowed before signaling an error (with data @code{"Variable -binding depth exceeds max-specpdl-size"}). +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 +max-specpdl-size"}). This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function. @code{max-lisp-eval-depth} provides another limit on depth of nesting. -@xref{Eval}. +@xref{Definition of max-lisp-eval-depth,, Eval}. The default value is 600. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself @@ -518,7 +523,7 @@ 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 -@defspec defconst symbol [value [doc-string]] +@defspec defconst symbol value [doc-string] This special form defines @var{symbol} as a value and initializes it. It informs a person reading your code that @var{symbol} has a standard global value, established here, that should not be changed by the user @@ -526,10 +531,10 @@ or by other programs. Note that @var{symbol} is not evaluated; the symbol to be defined must appear explicitly in the @code{defconst}. @code{defconst} always evaluates @var{value}, and sets the value of -@var{symbol} to the result if @var{value} is given. If @var{symbol} -does have a buffer-local binding in the current buffer, @code{defconst} -sets the default value, not the buffer-local value. (But you should not -be making buffer-local bindings for a symbol that is defined with +@var{symbol} to the result. If @var{symbol} does have a buffer-local +binding in the current buffer, @code{defconst} sets the default value, +not the buffer-local value. (But you should not be making +buffer-local bindings for a symbol that is defined with @code{defconst}.) Here, @code{pi} is a constant that presumably ought not to be changed @@ -564,7 +569,7 @@ 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. +is a user option. Aliases of user options are also user options. @end defun @kindex variable-interactive @@ -858,11 +863,16 @@ always affects the most local existing binding. One other function for setting a variable is designed to add an element to a list if it is not already present in the list. -@defun add-to-list symbol element +@defun add-to-list symbol element &optional append This function sets the variable @var{symbol} by consing @var{element} onto the old value, if @var{element} is not already a member of that value. It returns the resulting list, whether updated or not. The value of @var{symbol} had better be a list already before the call. +Membership is tested using @code{equal}. + +Normally, if @var{element} is added, it is added to the front of +@var{symbol}, but if the optional argument @var{append} is +non-@code{nil}, it is added at the end. The argument @var{symbol} is not implicitly quoted; @code{add-to-list} is an ordinary function, like @code{set} and unlike @code{setq}. Quote @@ -893,6 +903,62 @@ foo ;; @r{@code{foo} was changed.} (setq @var{var} (cons @var{value} @var{var}))) @end example +@defun add-to-ordered-list symbol element &optional order +This function sets the variable @var{symbol} by inserting +@var{element} into the old value, which must be a list, at the +position specified by @var{order}. If @var{element} is already a +member of the list, its position in the list is adjusted according +to @var{order}. Membership is tested using @code{eq}. +This function returns the resulting list, whether updated or not. + +The @var{order} is typically a number (integer or float), and the +elements of the list are sorted in non-decreasing numerical order. + +@var{order} may also be omitted or @code{nil}. Then the numeric order +of @var{element} stays unchanged if it already has one; otherwise, +@var{element} has no numeric order. Elements without a numeric list +order are placed at the end of the list, in no particular order. + +Any other value for @var{order} removes the numeric order of @var{element} +if it already has one; otherwise, it is equivalent to @code{nil}. + +The argument @var{symbol} is not implicitly quoted; +@code{add-to-ordered-list} is an ordinary function, like @code{set} +and unlike @code{setq}. Quote the argument yourself if that is what +you want. + +The ordering information is stored in a hash table on @var{symbol}'s +@code{list-order} property. +@end defun + +Here's a scenario showing how to use @code{add-to-ordered-list}: + +@example +(setq foo '()) + @result{} nil + +(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} + @result{} (a) + +(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} + @result{} (a c) + +(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} + @result{} (a b c) + +(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} + @result{} (a c b) + +(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} + @result{} (a c b d) + +(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. + @result{} (a c b e d) + +foo ;; @r{@code{foo} was changed.} + @result{} (a c b e d) +@end example + @node Variable Scoping @section Scoping Rules for Variable Bindings @@ -904,6 +970,7 @@ the others. @cindex scope @cindex extent @cindex dynamic scoping +@cindex lexical scoping 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 @@ -1295,7 +1362,14 @@ local to the current buffer at the time. A peculiar wrinkle of this feature is that binding the variable (with @code{let} or other binding constructs) does not create a buffer-local binding for it. Only setting the variable (with @code{set} or -@code{setq}) does so. +@code{setq}), while the variable does not have a @code{let}-style +binding that was made in the current buffer, does so. + +If @var{variable} does not have a default value, then calling this +command will give it a default value of @code{nil}. If @var{variable} +already has a default value, that value remains unchanged. +Subsequently calling @code{makunbound} on @var{variable} will result +in a void buffer-local value and leave the default value unaffected. The value returned is @var{variable}. @@ -1318,6 +1392,12 @@ This returns @code{t} if @var{variable} is buffer-local in buffer @code{nil}. @end defun +@defun local-variable-if-set-p variable &optional buffer +This returns @code{t} if @var{variable} will become buffer-local in +buffer @var{buffer} (which defaults to the current buffer) if it is +set there. +@end defun + @defun buffer-local-value variable buffer This function returns the buffer-local binding of @var{variable} (a symbol) in buffer @var{buffer}. If @var{variable} does not have a @@ -1405,8 +1485,11 @@ variables that major modes set should not be marked permanent. The function @code{kill-all-local-variables} runs this normal hook before it does anything else. This gives major modes a way to arrange for something special to be done if the user switches to a different -major mode. For best results, make this variable buffer-local, so that -it will disappear after doing its job and will not interfere with the +major mode. It is also useful for buffer-specific minor modes +that should be forgotten if the user changes the major mode. + +For best results, make this variable buffer-local, so that it will +disappear after doing its job and will not interfere with the subsequent major mode. @xref{Hooks}. @end defvar @@ -1555,11 +1638,17 @@ not in itself create any frame-local bindings for the variable; however, if some frame already has a value for @var{variable} as a frame parameter, that value automatically becomes a frame-local binding. +If @var{variable} does not have a default value, then calling this +command will give it a default value of @code{nil}. If @var{variable} +already has a default value, that value remains unchanged. + If the variable is terminal-local, this function signals an error, because such variables cannot have frame-local bindings as well. @xref{Multiple Displays}. A few variables that are implemented specially in Emacs can be (and usually are) buffer-local, but can never be frame-local. + +This command returns @var{variable}. @end deffn Buffer-local bindings take precedence over frame-local bindings. Thus, @@ -1655,6 +1744,92 @@ 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 + + This section describes the functions and variables that affect +processing of file local variables. @xref{File variables, , +Local Variables in Files, emacs, The GNU Emacs Manual}, for basic +information about file local variables. + +@defopt enable-local-variables +This variable controls whether to process file local variables. A +value of @code{t} means process them unconditionally; @code{nil} means +ignore them; anything else means ask the user what to do for each +file. The default value is @code{t}. +@end defopt + +@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 +@code{enable-local-variables} has its effect here. However, this +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}). + +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. +@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. To prevent this, Emacs +takes care not to allow to set such file local variables. + + For one thing, 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} cannot be given a file local +value. In general, you should use such a name whenever it is +appropriate for the variable's meaning. The variables +@samp{font-lock-keywords}, @samp{font-lock-keywords} followed by a +digit, and @samp{font-lock-syntactic-keywords} cannot be given file +local values either. These rules can be overridden by giving the +variable's name a non-@code{nil} @code{safe-local-variable} property. +If one gives it a @code{safe-local-variable} property of @code{t}, +then one can give the variable any file local value. One can also +give any symbol, including the above, a @code{safe-local-variable} +property that is a function taking exactly one argument. In that +case, giving a variable with that name a file local value is only +allowed if the function returns non-@code{nil} when called with that +value as argument. + + In addition, any variable whose name has a non-@code{nil} +@code{risky-local-variable} property is also ignored. So are all +variables listed in @code{ignored-local-variables}: + +@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 +ignored. +@end defvar + +@defun risky-local-variable-p sym &optional val +If @var{val} is non-@code{nil}, returns non-@code{nil} if giving +@var{sym} a file local value of @var{val} would be risky, for any of +the reasons stated above. If @var{val} is @code{nil} or omitted, only +returns @code{nil} if @var{sym} can be safely assigned any file local +value whatsoever. +@end defun + + The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs +normally asks for confirmation before handling it. + +@defopt enable-local-eval +This variable controls processing of @samp{Eval:} in @samp{-*-} lines +or local variables +lists in files being visited. A value of @code{t} means process them +unconditionally; @code{nil} means ignore them; anything else means ask +the user what to do for each file. The default value is @code{maybe}. +@end defopt + + 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. + @node Variable Aliases @section Variable Aliases @@ -1666,21 +1841,59 @@ chosen, or because its meaning has partly changed---it can be useful to keep the old name as an @emph{alias} of the new one for compatibility. You can do this with @code{defvaralias}. -@defun defvaralias alias-var base-var &optional docstring -This function defines the symbol @var{alias-var} as a variable alias -for symbol @var{base-var}. This means that retrieving the value of -@var{alias-var} returns the value of @var{base-var}, and changing the -value of @var{alias-var} changes the value of @var{base-var}. +@defun defvaralias new-alias base-variable &optional docstring +This function defines the symbol @var{new-alias} as a variable alias +for symbol @var{base-variable}. This means that retrieving the value of +@var{new-alias} returns the value of @var{base-variable}, and changing the +value of @var{new-alias} changes the value of @var{base-variable}. If the @var{docstring} argument is non-@code{nil}, it specifies the -documentation for @var{alias-var}; otherwise, the alias gets the same -documentation as @var{base-var} has, if any. +documentation for @var{new-alias}; otherwise, the alias gets the same +documentation as @var{base-variable} has, if any, unless +@var{base-variable} is itself an alias, in which case @var{new-alias} gets +the documentation of the variable at the end of the chain of aliases. + +This function returns @var{base-variable}. @end defun + Variable aliases are convenient for replacing an old name for a +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 +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. +@end defun + + You can make two variables synonyms and declare one obsolete at the +same time using the macro @code{define-obsolete-variable-alias}. + +@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring +This macro marks the variable @var{obsolete-name} as obsolete and also +makes it an alias for the variable @var{current-name}. It is +equivalent to the following: + +@example +(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) +(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) +@end example +@end defmac + @defun indirect-variable variable This function returns the variable at the end of the chain of aliases of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is not defined as an alias, the function returns @var{variable}. + +This function signals a @code{cyclic-variable-indirection} error if +there is a loop in the chain of symbols. @end defun @example @@ -1692,8 +1905,10 @@ not defined as an alias, the function returns @var{variable}. (setq bar 2) bar @result{} 2 +@group foo @result{} 2 +@end group (setq foo 0) bar @result{} 0 @@ -1701,73 +1916,40 @@ foo @result{} 0 @end example -@node File Local Variables -@section File Local Variables - - This section describes the functions and variables that affect -processing of local variables lists in files. - -@defopt enable-local-variables -This variable controls whether to process file local variables lists. A -value of @code{t} means process the local variables lists -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{t}. -@end defopt - -@defun hack-local-variables &optional force -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. +@node Variables with Restricted Values +@section Variables with Restricted Values -The argument @var{force} usually comes from the argument @var{find-file} -given to @code{normal-mode}. -@end defun + Ordinary Lisp variables can be assigned any value that is a valid +Lisp object. However, certain Lisp variables are not defined in Lisp, +but in C. Most of these variables are defined in the C code using +@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on +any value. However, some variables are defined using +@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp +variables in C,, Writing Emacs Primitives}, in particular the +description of functions of the type @code{syms_of_@var{filename}}, +for a brief discussion of the C implementation. - If a file local variable list could specify a function that will -be called later, or an expression that will be executed later, simply -visiting a file could take over your Emacs. To prevent this, Emacs -takes care not to allow local variable lists to set such variables. - - For one thing, any variable whose name ends in @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} cannot be set in a local variable list. In general, -you should use such a name whenever it is appropriate for the -variable's meaning. The variables @samp{font-lock-keywords}, -@samp{font-lock-keywords-[0-9]}, and -@samp{font-lock-syntactic-keywords} cannot be set in a local variable -list, either. + Variables of type @code{DEFVAR_BOOL} can only take on the values +@code{nil} or @code{t}. Attempting to assign them any other value +will set them to @code{t}: - In addition, any variable whose name has a non-@code{nil} -@code{risky-local-variable} property is also ignored. So are all -variables listed in @code{ignored-local-variables}: +@example +(let ((display-hourglass 5)) + display-hourglass) + @result{} t +@end example -@defvar ignored-local-variables -This variable holds a list of variables that should not be -set by a file's local variables list. Any value specified -for one of these variables is ignored. +@defvar byte-boolean-vars +This variable holds a list of all variables of type @code{DEFVAR_BOOL}. @end defvar -@defun risky-local-variable-p sym -Returns non-@code{nil} if @var{sym} is risky for any of the reasons -stated above. -@end defun + Variables of type @code{DEFVAR_INT} can only take on integer values. +Attempting to assign them any other value will result in an error: - The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs -normally asks for confirmation before handling it. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in local variables -lists in files being visited. A value of @code{t} means process them -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{maybe}. -@end defopt - - Text properties are also potential loopholes, since their values -could include functions to call. So Emacs discards all text -properties from string values specified in a file's local variables -list. +@example +(setq window-min-height 5.0) +@error{} Wrong type argument: integerp, 5.0 +@end example @ignore arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e