1@c -*-texinfo-*- 2@c This is part of the GNU Emacs Lisp Reference Manual. 3@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 4@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 5@c See the file elisp.texi for copying conditions. 6@setfilename ../info/variables 7@node Variables, Functions, Control Structures, Top 8@chapter Variables 9@cindex variable 10 11 A @dfn{variable} is a name used in a program to stand for a value. 12Nearly all programming languages have variables of some sort. In the 13text of a Lisp program, variables are written using the syntax for 14symbols. 15 16 In Lisp, unlike most programming languages, programs are represented 17primarily as Lisp objects and only secondarily as text. The Lisp 18objects used for variables are symbols: the symbol name is the variable 19name, and the variable's value is stored in the value cell of the 20symbol. The use of a symbol as a variable is independent of its use as 21a function name. @xref{Symbol Components}. 22 23 The Lisp objects that constitute a Lisp program determine the textual 24form of the program---it is simply the read syntax for those Lisp 25objects. This is why, for example, a variable in a textual Lisp program 26is written using the read syntax for the symbol that represents the 27variable. 28 29@menu 30* Global Variables:: Variable values that exist permanently, everywhere. 31* Constant Variables:: Certain "variables" have values that never change. 32* Local Variables:: Variable values that exist only temporarily. 33* Void Variables:: Symbols that lack values. 34* Defining Variables:: A definition says a symbol is used as a variable. 35* Tips for Defining:: Things you should think about when you 36 define a variable. 37* Accessing Variables:: Examining values of variables whose names 38 are known only at run time. 39* Setting Variables:: Storing new values in variables. 40* Variable Scoping:: How Lisp chooses among local and global values. 41* Buffer-Local Variables:: Variable values in effect only in one buffer. 42* Frame-Local Variables:: Variable values in effect only in one frame. 43* Future Local Variables:: New kinds of local values we might add some day. 44* File Local Variables:: Handling local variable lists in files. 45* Variable Aliases:: Variables that are aliases for other variables. 46* Variables with Restricted Values:: Non-constant variables whose value can 47 @emph{not} be an arbitrary Lisp object. 48@end menu 49 50@node Global Variables 51@section Global Variables 52@cindex global variable 53 54 The simplest way to use a variable is @dfn{globally}. This means that 55the variable has just one value at a time, and this value is in effect 56(at least for the moment) throughout the Lisp system. The value remains 57in effect until you specify a new one. When a new value replaces the 58old one, no trace of the old value remains in the variable. 59 60 You specify a value for a symbol with @code{setq}. For example, 61 62@example 63(setq x '(a b)) 64@end example 65 66@noindent 67gives the variable @code{x} the value @code{(a b)}. Note that 68@code{setq} does not evaluate its first argument, the name of the 69variable, but it does evaluate the second argument, the new value. 70 71 Once the variable has a value, you can refer to it by using the symbol 72by itself as an expression. Thus, 73 74@example 75@group 76x @result{} (a b) 77@end group 78@end example 79 80@noindent 81assuming the @code{setq} form shown above has already been executed. 82 83 If you do set the same variable again, the new value replaces the old 84one: 85 86@example 87@group 88x 89 @result{} (a b) 90@end group 91@group 92(setq x 4) 93 @result{} 4 94@end group 95@group 96x 97 @result{} 4 98@end group 99@end example 100 101@node Constant Variables 102@section Variables that Never Change 103@kindex setting-constant 104@cindex keyword symbol 105@cindex variable with constant value 106@cindex constant variables 107@cindex symbol that evaluates to itself 108@cindex symbol with constant value 109 110 In Emacs Lisp, certain symbols normally evaluate to themselves. These 111include @code{nil} and @code{t}, as well as any symbol whose name starts 112with @samp{:} (these are called @dfn{keywords}). These symbols cannot 113be rebound, nor can their values be changed. Any attempt to set or bind 114@code{nil} or @code{t} signals a @code{setting-constant} error. The 115same is true for a keyword (a symbol whose name starts with @samp{:}), 116if it is interned in the standard obarray, except that setting such a 117symbol to itself is not an error. 118 119@example 120@group 121nil @equiv{} 'nil 122 @result{} nil 123@end group 124@group 125(setq nil 500) 126@error{} Attempt to set constant symbol: nil 127@end group 128@end example 129 130@defun keywordp object 131function returns @code{t} if @var{object} is a symbol whose name 132starts with @samp{:}, interned in the standard obarray, and returns 133@code{nil} otherwise. 134@end defun 135 136@node Local Variables 137@section Local Variables 138@cindex binding local variables 139@cindex local variables 140@cindex local binding 141@cindex global binding 142 143 Global variables have values that last until explicitly superseded 144with new values. Sometimes it is useful to create variable values that 145exist temporarily---only until a certain part of the program finishes. 146These values are called @dfn{local}, and the variables so used are 147called @dfn{local variables}. 148 149 For example, when a function is called, its argument variables receive 150new local values that last until the function exits. The @code{let} 151special form explicitly establishes new local values for specified 152variables; these last until exit from the @code{let} form. 153 154@cindex shadowing of variables 155 Establishing a local value saves away the previous value (or lack of 156one) of the variable. When the life span of the local value is over, 157the previous value is restored. In the mean time, we say that the 158previous value is @dfn{shadowed} and @dfn{not visible}. Both global and 159local values may be shadowed (@pxref{Scope}). 160 161 If you set a variable (such as with @code{setq}) while it is local, 162this replaces the local value; it does not alter the global value, or 163previous local values, that are shadowed. To model this behavior, we 164speak of a @dfn{local binding} of the variable as well as a local value. 165 166 The local binding is a conceptual place that holds a local value. 167Entry to a function, or a special form such as @code{let}, creates the 168local binding; exit from the function or from the @code{let} removes the 169local binding. As long as the local binding lasts, the variable's value 170is stored within it. Use of @code{setq} or @code{set} while there is a 171local binding stores a different value into the local binding; it does 172not create a new binding. 173 174 We also speak of the @dfn{global binding}, which is where 175(conceptually) the global value is kept. 176 177@cindex current binding 178 A variable can have more than one local binding at a time (for 179example, if there are nested @code{let} forms that bind it). In such a 180case, the most recently created local binding that still exists is the 181@dfn{current binding} of the variable. (This rule is called 182@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no 183local bindings, the variable's global binding is its current binding. 184We sometimes call the current binding the @dfn{most-local existing 185binding}, for emphasis. Ordinary evaluation of a symbol always returns 186the value of its current binding. 187 188 The special forms @code{let} and @code{let*} exist to create 189local bindings. 190 191@defspec let (bindings@dots{}) forms@dots{} 192This special form binds variables according to @var{bindings} and then 193evaluates all of the @var{forms} in textual order. The @code{let}-form 194returns the value of the last form in @var{forms}. 195 196Each of the @var{bindings} is either @w{(i) a} symbol, in which case 197that symbol is bound to @code{nil}; or @w{(ii) a} list of the form 198@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is 199bound to the result of evaluating @var{value-form}. If @var{value-form} 200is omitted, @code{nil} is used. 201 202All of the @var{value-form}s in @var{bindings} are evaluated in the 203order they appear and @emph{before} binding any of the symbols to them. 204Here is an example of this: @code{z} is bound to the old value of 205@code{y}, which is 2, not the new value of @code{y}, which is 1. 206 207@example 208@group 209(setq y 2) 210 @result{} 2 211@end group 212@group 213(let ((y 1) 214 (z y)) 215 (list y z)) 216 @result{} (1 2) 217@end group 218@end example 219@end defspec 220 221@defspec let* (bindings@dots{}) forms@dots{} 222This special form is like @code{let}, but it binds each variable right 223after computing its local value, before computing the local value for 224the next variable. Therefore, an expression in @var{bindings} can 225reasonably refer to the preceding symbols bound in this @code{let*} 226form. Compare the following example with the example above for 227@code{let}. 228 229@example 230@group 231(setq y 2) 232 @result{} 2 233@end group 234@group 235(let* ((y 1) 236 (z y)) ; @r{Use the just-established value of @code{y}.} 237 (list y z)) 238 @result{} (1 1) 239@end group 240@end example 241@end defspec 242 243 Here is a complete list of the other facilities that create local 244bindings: 245 246@itemize @bullet 247@item 248Function calls (@pxref{Functions}). 249 250@item 251Macro calls (@pxref{Macros}). 252 253@item 254@code{condition-case} (@pxref{Errors}). 255@end itemize 256 257 Variables can also have buffer-local bindings (@pxref{Buffer-Local 258Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a 259few variables have terminal-local bindings (@pxref{Multiple Displays}). 260These kinds of bindings work somewhat like ordinary local bindings, but 261they are localized depending on ``where'' you are in Emacs, rather than 262localized in time. 263 264@defvar max-specpdl-size 265@anchor{Definition of max-specpdl-size} 266@cindex variable limit error 267@cindex evaluation error 268@cindex infinite recursion 269This variable defines the limit on the total number of local variable 270bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,, 271Cleaning Up from Nonlocal Exits}) that are allowed before signaling an 272error (with data @code{"Variable binding depth exceeds 273max-specpdl-size"}). 274 275This limit, with the associated error when it is exceeded, is one way 276that Lisp avoids infinite recursion on an ill-defined function. 277@code{max-lisp-eval-depth} provides another limit on depth of nesting. 278@xref{Definition of max-lisp-eval-depth,, Eval}. 279 280The default value is 1000. Entry to the Lisp debugger increases the 281value, if there is little room left, to make sure the debugger itself 282has room to execute. 283@end defvar 284 285@node Void Variables 286@section When a Variable is ``Void'' 287@kindex void-variable 288@cindex void variable 289 290 If you have never given a symbol any value as a global variable, we 291say that that symbol's global value is @dfn{void}. In other words, the 292symbol's value cell does not have any Lisp object in it. If you try to 293evaluate the symbol, you get a @code{void-variable} error rather than 294a value. 295 296 Note that a value of @code{nil} is not the same as void. The symbol 297@code{nil} is a Lisp object and can be the value of a variable just as any 298other object can be; but it is @emph{a value}. A void variable does not 299have any value. 300 301 After you have given a variable a value, you can make it void once more 302using @code{makunbound}. 303 304@defun makunbound symbol 305This function makes the current variable binding of @var{symbol} void. 306Subsequent attempts to use this symbol's value as a variable will signal 307the error @code{void-variable}, unless and until you set it again. 308 309@code{makunbound} returns @var{symbol}. 310 311@example 312@group 313(makunbound 'x) ; @r{Make the global value of @code{x} void.} 314 @result{} x 315@end group 316@group 317x 318@error{} Symbol's value as variable is void: x 319@end group 320@end example 321 322If @var{symbol} is locally bound, @code{makunbound} affects the most 323local existing binding. This is the only way a symbol can have a void 324local binding, since all the constructs that create local bindings 325create them with values. In this case, the voidness lasts at most as 326long as the binding does; when the binding is removed due to exit from 327the construct that made it, the previous local or global binding is 328reexposed as usual, and the variable is no longer void unless the newly 329reexposed binding was void all along. 330 331@smallexample 332@group 333(setq x 1) ; @r{Put a value in the global binding.} 334 @result{} 1 335(let ((x 2)) ; @r{Locally bind it.} 336 (makunbound 'x) ; @r{Void the local binding.} 337 x) 338@error{} Symbol's value as variable is void: x 339@end group 340@group 341x ; @r{The global binding is unchanged.} 342 @result{} 1 343 344(let ((x 2)) ; @r{Locally bind it.} 345 (let ((x 3)) ; @r{And again.} 346 (makunbound 'x) ; @r{Void the innermost-local binding.} 347 x)) ; @r{And refer: it's void.} 348@error{} Symbol's value as variable is void: x 349@end group 350 351@group 352(let ((x 2)) 353 (let ((x 3)) 354 (makunbound 'x)) ; @r{Void inner binding, then remove it.} 355 x) ; @r{Now outer @code{let} binding is visible.} 356 @result{} 2 357@end group 358@end smallexample 359@end defun 360 361 A variable that has been made void with @code{makunbound} is 362indistinguishable from one that has never received a value and has 363always been void. 364 365 You can use the function @code{boundp} to test whether a variable is 366currently void. 367 368@defun boundp variable 369@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; 370more precisely, if its current binding is not void. It returns 371@code{nil} otherwise. 372 373@smallexample 374@group 375(boundp 'abracadabra) ; @r{Starts out void.} 376 @result{} nil 377@end group 378@group 379(let ((abracadabra 5)) ; @r{Locally bind it.} 380 (boundp 'abracadabra)) 381 @result{} t 382@end group 383@group 384(boundp 'abracadabra) ; @r{Still globally void.} 385 @result{} nil 386@end group 387@group 388(setq abracadabra 5) ; @r{Make it globally nonvoid.} 389 @result{} 5 390@end group 391@group 392(boundp 'abracadabra) 393 @result{} t 394@end group 395@end smallexample 396@end defun 397 398@node Defining Variables 399@section Defining Global Variables 400@cindex variable definition 401 402 You may announce your intention to use a symbol as a global variable 403with a @dfn{variable definition}: a special form, either @code{defconst} 404or @code{defvar}. 405 406 In Emacs Lisp, definitions serve three purposes. First, they inform 407people who read the code that certain symbols are @emph{intended} to be 408used a certain way (as variables). Second, they inform the Lisp system 409of these things, supplying a value and documentation. Third, they 410provide information to utilities such as @code{etags} and 411@code{make-docfile}, which create data bases of the functions and 412variables in a program. 413 414 The difference between @code{defconst} and @code{defvar} is primarily 415a matter of intent, serving to inform human readers of whether the value 416should ever change. Emacs Lisp does not restrict the ways in which a 417variable can be used based on @code{defconst} or @code{defvar} 418declarations. However, it does make a difference for initialization: 419@code{defconst} unconditionally initializes the variable, while 420@code{defvar} initializes it only if it is void. 421 422@ignore 423 One would expect user option variables to be defined with 424@code{defconst}, since programs do not change them. Unfortunately, this 425has bad results if the definition is in a library that is not preloaded: 426@code{defconst} would override any prior value when the library is 427loaded. Users would like to be able to set user options in their init 428files, and override the default values given in the definitions. For 429this reason, user options must be defined with @code{defvar}. 430@end ignore 431 432@defspec defvar symbol [value [doc-string]] 433This special form defines @var{symbol} as a variable and can also 434initialize and document it. The definition informs a person reading 435your code that @var{symbol} is used as a variable that might be set or 436changed. Note that @var{symbol} is not evaluated; the symbol to be 437defined must appear explicitly in the @code{defvar}. 438 439If @var{symbol} is void and @var{value} is specified, @code{defvar} 440evaluates it and sets @var{symbol} to the result. But if @var{symbol} 441already has a value (i.e., it is not void), @var{value} is not even 442evaluated, and @var{symbol}'s value remains unchanged. If @var{value} 443is omitted, the value of @var{symbol} is not changed in any case. 444 445If @var{symbol} has a buffer-local binding in the current buffer, 446@code{defvar} operates on the default value, which is buffer-independent, 447not the current (buffer-local) binding. It sets the default value if 448the default value is void. @xref{Buffer-Local Variables}. 449 450When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in 451Emacs Lisp mode (@code{eval-defun}), a special feature of 452@code{eval-defun} arranges to set the variable unconditionally, without 453testing whether its value is void. 454 455If the @var{doc-string} argument appears, it specifies the documentation 456for the variable. (This opportunity to specify documentation is one of 457the main benefits of defining the variable.) The documentation is 458stored in the symbol's @code{variable-documentation} property. The 459Emacs help functions (@pxref{Documentation}) look for this property. 460 461If the variable is a user option that users would want to set 462interactively, you should use @samp{*} as the first character of 463@var{doc-string}. This lets users set the variable conveniently using 464the @code{set-variable} command. Note that you should nearly always 465use @code{defcustom} instead of @code{defvar} to define these 466variables, so that users can use @kbd{M-x customize} and related 467commands to set them. @xref{Customization}. 468 469Here are some examples. This form defines @code{foo} but does not 470initialize it: 471 472@example 473@group 474(defvar foo) 475 @result{} foo 476@end group 477@end example 478 479This example initializes the value of @code{bar} to @code{23}, and gives 480it a documentation string: 481 482@example 483@group 484(defvar bar 23 485 "The normal weight of a bar.") 486 @result{} bar 487@end group 488@end example 489 490The following form changes the documentation string for @code{bar}, 491making it a user option, but does not change the value, since @code{bar} 492already has a value. (The addition @code{(1+ nil)} would get an error 493if it were evaluated, but since it is not evaluated, there is no error.) 494 495@example 496@group 497(defvar bar (1+ nil) 498 "*The normal weight of a bar.") 499 @result{} bar 500@end group 501@group 502bar 503 @result{} 23 504@end group 505@end example 506 507Here is an equivalent expression for the @code{defvar} special form: 508 509@example 510@group 511(defvar @var{symbol} @var{value} @var{doc-string}) 512@equiv{} 513(progn 514 (if (not (boundp '@var{symbol})) 515 (setq @var{symbol} @var{value})) 516 (if '@var{doc-string} 517 (put '@var{symbol} 'variable-documentation '@var{doc-string})) 518 '@var{symbol}) 519@end group 520@end example 521 522The @code{defvar} form returns @var{symbol}, but it is normally used 523at top level in a file where its value does not matter. 524@end defspec 525 526@defspec defconst symbol value [doc-string] 527This special form defines @var{symbol} as a value and initializes it. 528It informs a person reading your code that @var{symbol} has a standard 529global value, established here, that should not be changed by the user 530or by other programs. Note that @var{symbol} is not evaluated; the 531symbol to be defined must appear explicitly in the @code{defconst}. 532 533@code{defconst} always evaluates @var{value}, and sets the value of 534@var{symbol} to the result. If @var{symbol} does have a buffer-local 535binding in the current buffer, @code{defconst} sets the default value, 536not the buffer-local value. (But you should not be making 537buffer-local bindings for a symbol that is defined with 538@code{defconst}.) 539 540Here, @code{pi} is a constant that presumably ought not to be changed 541by anyone (attempts by the Indiana State Legislature notwithstanding). 542As the second form illustrates, however, this is only advisory. 543 544@example 545@group 546(defconst pi 3.1415 "Pi to five places.") 547 @result{} pi 548@end group 549@group 550(setq pi 3) 551 @result{} pi 552@end group 553@group 554pi 555 @result{} 3 556@end group 557@end example 558@end defspec 559 560@defun user-variable-p variable 561@cindex user option 562This function returns @code{t} if @var{variable} is a user option---a 563variable intended to be set by the user for customization---and 564@code{nil} otherwise. (Variables other than user options exist for the 565internal purposes of Lisp programs, and users need not know about them.) 566 567User option variables are distinguished from other variables either 568though being declared using @code{defcustom}@footnote{They may also be 569declared equivalently in @file{cus-start.el}.} or by the first character 570of their @code{variable-documentation} property. If the property exists 571and is a string, and its first character is @samp{*}, then the variable 572is a user option. Aliases of user options are also user options. 573@end defun 574 575@kindex variable-interactive 576 If a user option variable has a @code{variable-interactive} property, 577the @code{set-variable} command uses that value to control reading the 578new value for the variable. The property's value is used as if it were 579specified in @code{interactive} (@pxref{Using Interactive}). However, 580this feature is largely obsoleted by @code{defcustom} 581(@pxref{Customization}). 582 583 @strong{Warning:} If the @code{defconst} and @code{defvar} special 584forms are used while the variable has a local binding (made with 585@code{let}, or a function argument), they set the local-binding's 586value; the top-level binding is not changed. This is not what you 587usually want. To prevent it, use these special forms at top level in 588a file, where normally no local binding is in effect, and make sure to 589load the file before making a local binding for the variable. 590 591@node Tips for Defining 592@section Tips for Defining Variables Robustly 593 594 When you define a variable whose value is a function, or a list of 595functions, use a name that ends in @samp{-function} or 596@samp{-functions}, respectively. 597 598 There are several other variable name conventions; 599here is a complete list: 600 601@table @samp 602@item @dots{}-hook 603The variable is a normal hook (@pxref{Hooks}). 604 605@item @dots{}-function 606The value is a function. 607 608@item @dots{}-functions 609The value is a list of functions. 610 611@item @dots{}-form 612The value is a form (an expression). 613 614@item @dots{}-forms 615The value is a list of forms (expressions). 616 617@item @dots{}-predicate 618The value is a predicate---a function of one argument that returns 619non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' 620arguments. 621 622@item @dots{}-flag 623The value is significant only as to whether it is @code{nil} or not. 624 625@item @dots{}-program 626The value is a program name. 627 628@item @dots{}-command 629The value is a whole shell command. 630 631@item @dots{}-switches 632The value specifies options for a command. 633@end table 634 635 When you define a variable, always consider whether you should mark 636it as ``risky''; see @ref{File Local Variables}. 637 638 When defining and initializing a variable that holds a complicated 639value (such as a keymap with bindings in it), it's best to put the 640entire computation of the value into the @code{defvar}, like this: 641 642@example 643(defvar my-mode-map 644 (let ((map (make-sparse-keymap))) 645 (define-key map "\C-c\C-a" 'my-command) 646 @dots{} 647 map) 648 @var{docstring}) 649@end example 650 651@noindent 652This method has several benefits. First, if the user quits while 653loading the file, the variable is either still uninitialized or 654initialized properly, never in-between. If it is still uninitialized, 655reloading the file will initialize it properly. Second, reloading the 656file once the variable is initialized will not alter it; that is 657important if the user has run hooks to alter part of the contents (such 658as, to rebind keys). Third, evaluating the @code{defvar} form with 659@kbd{C-M-x} @emph{will} reinitialize the map completely. 660 661 Putting so much code in the @code{defvar} form has one disadvantage: 662it puts the documentation string far away from the line which names the 663variable. Here's a safe way to avoid that: 664 665@example 666(defvar my-mode-map nil 667 @var{docstring}) 668(unless my-mode-map 669 (let ((map (make-sparse-keymap))) 670 (define-key map "\C-c\C-a" 'my-command) 671 @dots{} 672 (setq my-mode-map map))) 673@end example 674 675@noindent 676This has all the same advantages as putting the initialization inside 677the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on 678each form, if you do want to reinitialize the variable. 679 680 But be careful not to write the code like this: 681 682@example 683(defvar my-mode-map nil 684 @var{docstring}) 685(unless my-mode-map 686 (setq my-mode-map (make-sparse-keymap)) 687 (define-key my-mode-map "\C-c\C-a" 'my-command) 688 @dots{}) 689@end example 690 691@noindent 692This code sets the variable, then alters it, but it does so in more than 693one step. If the user quits just after the @code{setq}, that leaves the 694variable neither correctly initialized nor void nor @code{nil}. Once 695that happens, reloading the file will not initialize the variable; it 696will remain incomplete. 697 698@node Accessing Variables 699@section Accessing Variable Values 700 701 The usual way to reference a variable is to write the symbol which 702names it (@pxref{Symbol Forms}). This requires you to specify the 703variable name when you write the program. Usually that is exactly what 704you want to do. Occasionally you need to choose at run time which 705variable to reference; then you can use @code{symbol-value}. 706 707@defun symbol-value symbol 708This function returns the value of @var{symbol}. This is the value in 709the innermost local binding of the symbol, or its global value if it 710has no local bindings. 711 712@example 713@group 714(setq abracadabra 5) 715 @result{} 5 716@end group 717@group 718(setq foo 9) 719 @result{} 9 720@end group 721 722@group 723;; @r{Here the symbol @code{abracadabra}} 724;; @r{is the symbol whose value is examined.} 725(let ((abracadabra 'foo)) 726 (symbol-value 'abracadabra)) 727 @result{} foo 728@end group 729 730@group 731;; @r{Here, the value of @code{abracadabra},} 732;; @r{which is @code{foo},} 733;; @r{is the symbol whose value is examined.} 734(let ((abracadabra 'foo)) 735 (symbol-value abracadabra)) 736 @result{} 9 737@end group 738 739@group 740(symbol-value 'abracadabra) 741 @result{} 5 742@end group 743@end example 744 745A @code{void-variable} error is signaled if the current binding of 746@var{symbol} is void. 747@end defun 748 749@node Setting Variables 750@section How to Alter a Variable Value 751 752 The usual way to change the value of a variable is with the special 753form @code{setq}. When you need to compute the choice of variable at 754run time, use the function @code{set}. 755 756@defspec setq [symbol form]@dots{} 757This special form is the most common method of changing a variable's 758value. Each @var{symbol} is given a new value, which is the result of 759evaluating the corresponding @var{form}. The most-local existing 760binding of the symbol is changed. 761 762@code{setq} does not evaluate @var{symbol}; it sets the symbol that you 763write. We say that this argument is @dfn{automatically quoted}. The 764@samp{q} in @code{setq} stands for ``quoted.'' 765 766The value of the @code{setq} form is the value of the last @var{form}. 767 768@example 769@group 770(setq x (1+ 2)) 771 @result{} 3 772@end group 773x ; @r{@code{x} now has a global value.} 774 @result{} 3 775@group 776(let ((x 5)) 777 (setq x 6) ; @r{The local binding of @code{x} is set.} 778 x) 779 @result{} 6 780@end group 781x ; @r{The global value is unchanged.} 782 @result{} 3 783@end example 784 785Note that the first @var{form} is evaluated, then the first 786@var{symbol} is set, then the second @var{form} is evaluated, then the 787second @var{symbol} is set, and so on: 788 789@example 790@group 791(setq x 10 ; @r{Notice that @code{x} is set before} 792 y (1+ x)) ; @r{the value of @code{y} is computed.} 793 @result{} 11 794@end group 795@end example 796@end defspec 797 798@defun set symbol value 799This function sets @var{symbol}'s value to @var{value}, then returns 800@var{value}. Since @code{set} is a function, the expression written for 801@var{symbol} is evaluated to obtain the symbol to set. 802 803The most-local existing binding of the variable is the binding that is 804set; shadowed bindings are not affected. 805 806@example 807@group 808(set one 1) 809@error{} Symbol's value as variable is void: one 810@end group 811@group 812(set 'one 1) 813 @result{} 1 814@end group 815@group 816(set 'two 'one) 817 @result{} one 818@end group 819@group 820(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} 821 @result{} 2 822@end group 823@group 824one ; @r{So it is @code{one} that was set.} 825 @result{} 2 826(let ((one 1)) ; @r{This binding of @code{one} is set,} 827 (set 'one 3) ; @r{not the global value.} 828 one) 829 @result{} 3 830@end group 831@group 832one 833 @result{} 2 834@end group 835@end example 836 837If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} 838error is signaled. 839 840@example 841(set '(x y) 'z) 842@error{} Wrong type argument: symbolp, (x y) 843@end example 844 845Logically speaking, @code{set} is a more fundamental primitive than 846@code{setq}. Any use of @code{setq} can be trivially rewritten to use 847@code{set}; @code{setq} could even be defined as a macro, given the 848availability of @code{set}. However, @code{set} itself is rarely used; 849beginners hardly need to know about it. It is useful only for choosing 850at run time which variable to set. For example, the command 851@code{set-variable}, which reads a variable name from the user and then 852sets the variable, needs to use @code{set}. 853 854@cindex CL note---@code{set} local 855@quotation 856@b{Common Lisp note:} In Common Lisp, @code{set} always changes the 857symbol's ``special'' or dynamic value, ignoring any lexical bindings. 858In Emacs Lisp, all variables and all bindings are dynamic, so @code{set} 859always affects the most local existing binding. 860@end quotation 861@end defun 862 863@node Variable Scoping 864@section Scoping Rules for Variable Bindings 865 866 A given symbol @code{foo} can have several local variable bindings, 867established at different places in the Lisp program, as well as a global 868binding. The most recently established binding takes precedence over 869the others. 870 871@cindex scope 872@cindex extent 873@cindex dynamic scoping 874@cindex lexical scoping 875 Local bindings in Emacs Lisp have @dfn{indefinite scope} and 876@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in 877the source code the binding can be accessed. ``Indefinite scope'' means 878that any part of the program can potentially access the variable 879binding. @dfn{Extent} refers to @emph{when}, as the program is 880executing, the binding exists. ``Dynamic extent'' means that the binding 881lasts as long as the activation of the construct that established it. 882 883 The combination of dynamic extent and indefinite scope is called 884@dfn{dynamic scoping}. By contrast, most programming languages use 885@dfn{lexical scoping}, in which references to a local variable must be 886located textually within the function or block that binds the variable. 887 888@cindex CL note---special variables 889@quotation 890@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are 891dynamically scoped, like all variables in Emacs Lisp. 892@end quotation 893 894@menu 895* Scope:: Scope means where in the program a value is visible. 896 Comparison with other languages. 897* Extent:: Extent means how long in time a value exists. 898* Impl of Scope:: Two ways to implement dynamic scoping. 899* Using Scoping:: How to use dynamic scoping carefully and avoid problems. 900@end menu 901 902@node Scope 903@subsection Scope 904 905 Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. 906This means that any function anywhere in the program text might access a 907given binding of a variable. Consider the following function 908definitions: 909 910@example 911@group 912(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} 913 (foo 5)) ; @r{@code{foo} is some other function.} 914@end group 915 916@group 917(defun user () ; @r{@code{x} is used ``free'' in @code{user}.} 918 (list x)) 919@end group 920@end example 921 922 In a lexically scoped language, the binding of @code{x} in 923@code{binder} would never be accessible in @code{user}, because 924@code{user} is not textually contained within the function 925@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} 926may or may not refer to the binding of @code{x} established in 927@code{binder}, depending on the circumstances: 928 929@itemize @bullet 930@item 931If we call @code{user} directly without calling @code{binder} at all, 932then whatever binding of @code{x} is found, it cannot come from 933@code{binder}. 934 935@item 936If we define @code{foo} as follows and then call @code{binder}, then the 937binding made in @code{binder} will be seen in @code{user}: 938 939@example 940@group 941(defun foo (lose) 942 (user)) 943@end group 944@end example 945 946@item 947However, if we define @code{foo} as follows and then call @code{binder}, 948then the binding made in @code{binder} @emph{will not} be seen in 949@code{user}: 950 951@example 952(defun foo (x) 953 (user)) 954@end example 955 956@noindent 957Here, when @code{foo} is called by @code{binder}, it binds @code{x}. 958(The binding in @code{foo} is said to @dfn{shadow} the one made in 959@code{binder}.) Therefore, @code{user} will access the @code{x} bound 960by @code{foo} instead of the one bound by @code{binder}. 961@end itemize 962 963Emacs Lisp uses dynamic scoping because simple implementations of 964lexical scoping are slow. In addition, every Lisp system needs to offer 965dynamic scoping at least as an option; if lexical scoping is the norm, 966there must be a way to specify dynamic scoping instead for a particular 967variable. It might not be a bad thing for Emacs to offer both, but 968implementing it with dynamic scoping only was much easier. 969 970@node Extent 971@subsection Extent 972 973 @dfn{Extent} refers to the time during program execution that a 974variable name is valid. In Emacs Lisp, a variable is valid only while 975the form that bound it is executing. This is called @dfn{dynamic 976extent}. ``Local'' or ``automatic'' variables in most languages, 977including C and Pascal, have dynamic extent. 978 979 One alternative to dynamic extent is @dfn{indefinite extent}. This 980means that a variable binding can live on past the exit from the form 981that made the binding. Common Lisp and Scheme, for example, support 982this, but Emacs Lisp does not. 983 984 To illustrate this, the function below, @code{make-add}, returns a 985function that purports to add @var{n} to its own argument @var{m}. This 986would work in Common Lisp, but it does not do the job in Emacs Lisp, 987because after the call to @code{make-add} exits, the variable @code{n} 988is no longer bound to the actual argument 2. 989 990@example 991(defun make-add (n) 992 (function (lambda (m) (+ n m)))) ; @r{Return a function.} 993 @result{} make-add 994(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} 995 ; @r{with @code{(make-add 2)}.} 996 @result{} (lambda (m) (+ n m)) 997(add2 4) ; @r{Try to add 2 to 4.} 998@error{} Symbol's value as variable is void: n 999@end example 1000 1001@cindex closures not available 1002 Some Lisp dialects have ``closures,'' objects that are like functions 1003but record additional variable bindings. Emacs Lisp does not have 1004closures. 1005 1006@node Impl of Scope 1007@subsection Implementation of Dynamic Scoping 1008@cindex deep binding 1009 1010 A simple sample implementation (which is not how Emacs Lisp actually 1011works) may help you understand dynamic binding. This technique is 1012called @dfn{deep binding} and was used in early Lisp systems. 1013 1014 Suppose there is a stack of bindings, which are variable-value pairs. 1015At entry to a function or to a @code{let} form, we can push bindings 1016onto the stack for the arguments or local variables created there. We 1017can pop those bindings from the stack at exit from the binding 1018construct. 1019 1020 We can find the value of a variable by searching the stack from top to 1021bottom for a binding for that variable; the value from that binding is 1022the value of the variable. To set the variable, we search for the 1023current binding, then store the new value into that binding. 1024 1025 As you can see, a function's bindings remain in effect as long as it 1026continues execution, even during its calls to other functions. That is 1027why we say the extent of the binding is dynamic. And any other function 1028can refer to the bindings, if it uses the same variables while the 1029bindings are in effect. That is why we say the scope is indefinite. 1030 1031@cindex shallow binding 1032 The actual implementation of variable scoping in GNU Emacs Lisp uses a 1033technique called @dfn{shallow binding}. Each variable has a standard 1034place in which its current value is always found---the value cell of the 1035symbol. 1036 1037 In shallow binding, setting the variable works by storing a value in 1038the value cell. Creating a new binding works by pushing the old value 1039(belonging to a previous binding) onto a stack, and storing the new 1040local value in the value cell. Eliminating a binding works by popping 1041the old value off the stack, into the value cell. 1042 1043 We use shallow binding because it has the same results as deep 1044binding, but runs faster, since there is never a need to search for a 1045binding. 1046 1047@node Using Scoping 1048@subsection Proper Use of Dynamic Scoping 1049 1050 Binding a variable in one function and using it in another is a 1051powerful technique, but if used without restraint, it can make programs 1052hard to understand. There are two clean ways to use this technique: 1053 1054@itemize @bullet 1055@item 1056Use or bind the variable only in a few related functions, written close 1057together in one file. Such a variable is used for communication within 1058one program. 1059 1060You should write comments to inform other programmers that they can see 1061all uses of the variable before them, and to advise them not to add uses 1062elsewhere. 1063 1064@item 1065Give the variable a well-defined, documented meaning, and make all 1066appropriate functions refer to it (but not bind it or set it) wherever 1067that meaning is relevant. For example, the variable 1068@code{case-fold-search} is defined as ``non-@code{nil} means ignore case 1069when searching''; various search and replace functions refer to it 1070directly or through their subroutines, but do not bind or set it. 1071 1072Then you can bind the variable in other programs, knowing reliably what 1073the effect will be. 1074@end itemize 1075 1076 In either case, you should define the variable with @code{defvar}. 1077This helps other people understand your program by telling them to look 1078for inter-function usage. It also avoids a warning from the byte 1079compiler. Choose the variable's name to avoid name conflicts---don't 1080use short names like @code{x}. 1081 1082@node Buffer-Local Variables 1083@section Buffer-Local Variables 1084@cindex variable, buffer-local 1085@cindex buffer-local variables 1086 1087 Global and local variable bindings are found in most programming 1088languages in one form or another. Emacs, however, also supports additional, 1089unusual kinds of variable binding: @dfn{buffer-local} bindings, which 1090apply only in one buffer, and @dfn{frame-local} bindings, which apply only in 1091one frame. Having different values for a variable in different buffers 1092and/or frames is an important customization method. 1093 1094 This section describes buffer-local bindings; for frame-local 1095bindings, see the following section, @ref{Frame-Local Variables}. (A few 1096variables have bindings that are local to each terminal; see 1097@ref{Multiple Displays}.) 1098 1099@menu 1100* Intro to Buffer-Local:: Introduction and concepts. 1101* Creating Buffer-Local:: Creating and destroying buffer-local bindings. 1102* Default Value:: The default value is seen in buffers 1103 that don't have their own buffer-local values. 1104@end menu 1105 1106@node Intro to Buffer-Local 1107@subsection Introduction to Buffer-Local Variables 1108 1109 A buffer-local variable has a buffer-local binding associated with a 1110particular buffer. The binding is in effect when that buffer is 1111current; otherwise, it is not in effect. If you set the variable while 1112a buffer-local binding is in effect, the new value goes in that binding, 1113so its other bindings are unchanged. This means that the change is 1114visible only in the buffer where you made it. 1115 1116 The variable's ordinary binding, which is not associated with any 1117specific buffer, is called the @dfn{default binding}. In most cases, 1118this is the global binding. 1119 1120 A variable can have buffer-local bindings in some buffers but not in 1121other buffers. The default binding is shared by all the buffers that 1122don't have their own bindings for the variable. (This includes all 1123newly-created buffers.) If you set the variable in a buffer that does 1124not have a buffer-local binding for it, this sets the default binding 1125(assuming there are no frame-local bindings to complicate the matter), 1126so the new value is visible in all the buffers that see the default 1127binding. 1128 1129 The most common use of buffer-local bindings is for major modes to change 1130variables that control the behavior of commands. For example, C mode and 1131Lisp mode both set the variable @code{paragraph-start} to specify that only 1132blank lines separate paragraphs. They do this by making the variable 1133buffer-local in the buffer that is being put into C mode or Lisp mode, and 1134then setting it to the new value for that mode. @xref{Major Modes}. 1135 1136 The usual way to make a buffer-local binding is with 1137@code{make-local-variable}, which is what major mode commands typically 1138use. This affects just the current buffer; all other buffers (including 1139those yet to be created) will continue to share the default value unless 1140they are explicitly given their own buffer-local bindings. 1141 1142@cindex automatically buffer-local 1143 A more powerful operation is to mark the variable as 1144@dfn{automatically buffer-local} by calling 1145@code{make-variable-buffer-local}. You can think of this as making the 1146variable local in all buffers, even those yet to be created. More 1147precisely, the effect is that setting the variable automatically makes 1148the variable local to the current buffer if it is not already so. All 1149buffers start out by sharing the default value of the variable as usual, 1150but setting the variable creates a buffer-local binding for the current 1151buffer. The new value is stored in the buffer-local binding, leaving 1152the default binding untouched. This means that the default value cannot 1153be changed with @code{setq} in any buffer; the only way to change it is 1154with @code{setq-default}. 1155 1156 @strong{Warning:} When a variable has buffer-local or frame-local 1157bindings in one or more buffers, @code{let} rebinds the binding that's 1158currently in effect. For instance, if the current buffer has a 1159buffer-local value, @code{let} temporarily rebinds that. If no 1160buffer-local or frame-local bindings are in effect, @code{let} rebinds 1161the default value. If inside the @code{let} you then change to a 1162different current buffer in which a different binding is in effect, 1163you won't see the @code{let} binding any more. And if you exit the 1164@code{let} while still in the other buffer, you won't see the 1165unbinding occur (though it will occur properly). Here is an example 1166to illustrate: 1167 1168@example 1169@group 1170(setq foo 'g) 1171(set-buffer "a") 1172(make-local-variable 'foo) 1173@end group 1174(setq foo 'a) 1175(let ((foo 'temp)) 1176 ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}} 1177 (set-buffer "b") 1178 ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} 1179 @var{body}@dots{}) 1180@group 1181foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} 1182 ; @r{but we don't see that in buffer @samp{b}} 1183@end group 1184@group 1185(set-buffer "a") ; @r{verify the local value was restored} 1186foo @result{} 'a 1187@end group 1188@end example 1189 1190 Note that references to @code{foo} in @var{body} access the 1191buffer-local binding of buffer @samp{b}. 1192 1193 When a file specifies local variable values, these become buffer-local 1194values when you visit the file. @xref{File Variables,,, emacs, The 1195GNU Emacs Manual}. 1196 1197@node Creating Buffer-Local 1198@subsection Creating and Deleting Buffer-Local Bindings 1199 1200@deffn Command make-local-variable variable 1201This function creates a buffer-local binding in the current buffer for 1202@var{variable} (a symbol). Other buffers are not affected. The value 1203returned is @var{variable}. 1204 1205@c Emacs 19 feature 1206The buffer-local value of @var{variable} starts out as the same value 1207@var{variable} previously had. If @var{variable} was void, it remains 1208void. 1209 1210@example 1211@group 1212;; @r{In buffer @samp{b1}:} 1213(setq foo 5) ; @r{Affects all buffers.} 1214 @result{} 5 1215@end group 1216@group 1217(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} 1218 @result{} foo 1219@end group 1220@group 1221foo ; @r{That did not change} 1222 @result{} 5 ; @r{the value.} 1223@end group 1224@group 1225(setq foo 6) ; @r{Change the value} 1226 @result{} 6 ; @r{in @samp{b1}.} 1227@end group 1228@group 1229foo 1230 @result{} 6 1231@end group 1232 1233@group 1234;; @r{In buffer @samp{b2}, the value hasn't changed.} 1235(save-excursion 1236 (set-buffer "b2") 1237 foo) 1238 @result{} 5 1239@end group 1240@end example 1241 1242Making a variable buffer-local within a @code{let}-binding for that 1243variable does not work reliably, unless the buffer in which you do this 1244is not current either on entry to or exit from the @code{let}. This is 1245because @code{let} does not distinguish between different kinds of 1246bindings; it knows only which variable the binding was made for. 1247 1248If the variable is terminal-local, this function signals an error. Such 1249variables cannot have buffer-local bindings as well. @xref{Multiple 1250Displays}. 1251 1252@strong{Warning:} do not use @code{make-local-variable} for a hook 1253variable. The hook variables are automatically made buffer-local as 1254needed if you use the @var{local} argument to @code{add-hook} or 1255@code{remove-hook}. 1256@end deffn 1257 1258@deffn Command make-variable-buffer-local variable 1259This function marks @var{variable} (a symbol) automatically 1260buffer-local, so that any subsequent attempt to set it will make it 1261local to the current buffer at the time. 1262 1263A peculiar wrinkle of this feature is that binding the variable (with 1264@code{let} or other binding constructs) does not create a buffer-local 1265binding for it. Only setting the variable (with @code{set} or 1266@code{setq}), while the variable does not have a @code{let}-style 1267binding that was made in the current buffer, does so. 1268 1269If @var{variable} does not have a default value, then calling this 1270command will give it a default value of @code{nil}. If @var{variable} 1271already has a default value, that value remains unchanged. 1272Subsequently calling @code{makunbound} on @var{variable} will result 1273in a void buffer-local value and leave the default value unaffected. 1274 1275The value returned is @var{variable}. 1276 1277@strong{Warning:} Don't assume that you should use 1278@code{make-variable-buffer-local} for user-option variables, simply 1279because users @emph{might} want to customize them differently in 1280different buffers. Users can make any variable local, when they wish 1281to. It is better to leave the choice to them. 1282 1283The time to use @code{make-variable-buffer-local} is when it is crucial 1284that no two buffers ever share the same binding. For example, when a 1285variable is used for internal purposes in a Lisp program which depends 1286on having separate values in separate buffers, then using 1287@code{make-variable-buffer-local} can be the best solution. 1288@end deffn 1289 1290@defun local-variable-p variable &optional buffer 1291This returns @code{t} if @var{variable} is buffer-local in buffer 1292@var{buffer} (which defaults to the current buffer); otherwise, 1293@code{nil}. 1294@end defun 1295 1296@defun local-variable-if-set-p variable &optional buffer 1297This returns @code{t} if @var{variable} will become buffer-local in 1298buffer @var{buffer} (which defaults to the current buffer) if it is 1299set there. 1300@end defun 1301 1302@defun buffer-local-value variable buffer 1303This function returns the buffer-local binding of @var{variable} (a 1304symbol) in buffer @var{buffer}. If @var{variable} does not have a 1305buffer-local binding in buffer @var{buffer}, it returns the default 1306value (@pxref{Default Value}) of @var{variable} instead. 1307@end defun 1308 1309@defun buffer-local-variables &optional buffer 1310This function returns a list describing the buffer-local variables in 1311buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is 1312used.) It returns an association list (@pxref{Association Lists}) in 1313which each element contains one buffer-local variable and its value. 1314However, when a variable's buffer-local binding in @var{buffer} is void, 1315then the variable appears directly in the resulting list. 1316 1317@example 1318@group 1319(make-local-variable 'foobar) 1320(makunbound 'foobar) 1321(make-local-variable 'bind-me) 1322(setq bind-me 69) 1323@end group 1324(setq lcl (buffer-local-variables)) 1325 ;; @r{First, built-in variables local in all buffers:} 1326@result{} ((mark-active . nil) 1327 (buffer-undo-list . nil) 1328 (mode-name . "Fundamental") 1329 @dots{} 1330@group 1331 ;; @r{Next, non-built-in buffer-local variables.} 1332 ;; @r{This one is buffer-local and void:} 1333 foobar 1334 ;; @r{This one is buffer-local and nonvoid:} 1335 (bind-me . 69)) 1336@end group 1337@end example 1338 1339Note that storing new values into the @sc{cdr}s of cons cells in this 1340list does @emph{not} change the buffer-local values of the variables. 1341@end defun 1342 1343@deffn Command kill-local-variable variable 1344This function deletes the buffer-local binding (if any) for 1345@var{variable} (a symbol) in the current buffer. As a result, the 1346default binding of @var{variable} becomes visible in this buffer. This 1347typically results in a change in the value of @var{variable}, since the 1348default value is usually different from the buffer-local value just 1349eliminated. 1350 1351If you kill the buffer-local binding of a variable that automatically 1352becomes buffer-local when set, this makes the default value visible in 1353the current buffer. However, if you set the variable again, that will 1354once again create a buffer-local binding for it. 1355 1356@code{kill-local-variable} returns @var{variable}. 1357 1358This function is a command because it is sometimes useful to kill one 1359buffer-local variable interactively, just as it is useful to create 1360buffer-local variables interactively. 1361@end deffn 1362 1363@defun kill-all-local-variables 1364This function eliminates all the buffer-local variable bindings of the 1365current buffer except for variables marked as ``permanent.'' As a 1366result, the buffer will see the default values of most variables. 1367 1368This function also resets certain other information pertaining to the 1369buffer: it sets the local keymap to @code{nil}, the syntax table to the 1370value of @code{(standard-syntax-table)}, the case table to 1371@code{(standard-case-table)}, and the abbrev table to the value of 1372@code{fundamental-mode-abbrev-table}. 1373 1374The very first thing this function does is run the normal hook 1375@code{change-major-mode-hook} (see below). 1376 1377Every major mode command begins by calling this function, which has the 1378effect of switching to Fundamental mode and erasing most of the effects 1379of the previous major mode. To ensure that this does its job, the 1380variables that major modes set should not be marked permanent. 1381 1382@code{kill-all-local-variables} returns @code{nil}. 1383@end defun 1384 1385@defvar change-major-mode-hook 1386The function @code{kill-all-local-variables} runs this normal hook 1387before it does anything else. This gives major modes a way to arrange 1388for something special to be done if the user switches to a different 1389major mode. It is also useful for buffer-specific minor modes 1390that should be forgotten if the user changes the major mode. 1391 1392For best results, make this variable buffer-local, so that it will 1393disappear after doing its job and will not interfere with the 1394subsequent major mode. @xref{Hooks}. 1395@end defvar 1396 1397@c Emacs 19 feature 1398@cindex permanent local variable 1399A buffer-local variable is @dfn{permanent} if the variable name (a 1400symbol) has a @code{permanent-local} property that is non-@code{nil}. 1401Permanent locals are appropriate for data pertaining to where the file 1402came from or how to save it, rather than with how to edit the contents. 1403 1404@node Default Value 1405@subsection The Default Value of a Buffer-Local Variable 1406@cindex default value 1407 1408 The global value of a variable with buffer-local bindings is also 1409called the @dfn{default} value, because it is the value that is in 1410effect whenever neither the current buffer nor the selected frame has 1411its own binding for the variable. 1412 1413 The functions @code{default-value} and @code{setq-default} access and 1414change a variable's default value regardless of whether the current 1415buffer has a buffer-local binding. For example, you could use 1416@code{setq-default} to change the default setting of 1417@code{paragraph-start} for most buffers; and this would work even when 1418you are in a C or Lisp mode buffer that has a buffer-local value for 1419this variable. 1420 1421@c Emacs 19 feature 1422 The special forms @code{defvar} and @code{defconst} also set the 1423default value (if they set the variable at all), rather than any 1424buffer-local or frame-local value. 1425 1426@defun default-value symbol 1427This function returns @var{symbol}'s default value. This is the value 1428that is seen in buffers and frames that do not have their own values for 1429this variable. If @var{symbol} is not buffer-local, this is equivalent 1430to @code{symbol-value} (@pxref{Accessing Variables}). 1431@end defun 1432 1433@c Emacs 19 feature 1434@defun default-boundp symbol 1435The function @code{default-boundp} tells you whether @var{symbol}'s 1436default value is nonvoid. If @code{(default-boundp 'foo)} returns 1437@code{nil}, then @code{(default-value 'foo)} would get an error. 1438 1439@code{default-boundp} is to @code{default-value} as @code{boundp} is to 1440@code{symbol-value}. 1441@end defun 1442 1443@defspec setq-default [symbol form]@dots{} 1444This special form gives each @var{symbol} a new default value, which is 1445the result of evaluating the corresponding @var{form}. It does not 1446evaluate @var{symbol}, but does evaluate @var{form}. The value of the 1447@code{setq-default} form is the value of the last @var{form}. 1448 1449If a @var{symbol} is not buffer-local for the current buffer, and is not 1450marked automatically buffer-local, @code{setq-default} has the same 1451effect as @code{setq}. If @var{symbol} is buffer-local for the current 1452buffer, then this changes the value that other buffers will see (as long 1453as they don't have a buffer-local value), but not the value that the 1454current buffer sees. 1455 1456@example 1457@group 1458;; @r{In buffer @samp{foo}:} 1459(make-local-variable 'buffer-local) 1460 @result{} buffer-local 1461@end group 1462@group 1463(setq buffer-local 'value-in-foo) 1464 @result{} value-in-foo 1465@end group 1466@group 1467(setq-default buffer-local 'new-default) 1468 @result{} new-default 1469@end group 1470@group 1471buffer-local 1472 @result{} value-in-foo 1473@end group 1474@group 1475(default-value 'buffer-local) 1476 @result{} new-default 1477@end group 1478 1479@group 1480;; @r{In (the new) buffer @samp{bar}:} 1481buffer-local 1482 @result{} new-default 1483@end group 1484@group 1485(default-value 'buffer-local) 1486 @result{} new-default 1487@end group 1488@group 1489(setq buffer-local 'another-default) 1490 @result{} another-default 1491@end group 1492@group 1493(default-value 'buffer-local) 1494 @result{} another-default 1495@end group 1496 1497@group 1498;; @r{Back in buffer @samp{foo}:} 1499buffer-local 1500 @result{} value-in-foo 1501(default-value 'buffer-local) 1502 @result{} another-default 1503@end group 1504@end example 1505@end defspec 1506 1507@defun set-default symbol value 1508This function is like @code{setq-default}, except that @var{symbol} is 1509an ordinary evaluated argument. 1510 1511@example 1512@group 1513(set-default (car '(a b c)) 23) 1514 @result{} 23 1515@end group 1516@group 1517(default-value 'a) 1518 @result{} 23 1519@end group 1520@end example 1521@end defun 1522 1523@node Frame-Local Variables 1524@section Frame-Local Variables 1525@cindex frame-local variables 1526 1527 Just as variables can have buffer-local bindings, they can also have 1528frame-local bindings. These bindings belong to one frame, and are in 1529effect when that frame is selected. Frame-local bindings are actually 1530frame parameters: you create a frame-local binding in a specific frame 1531by calling @code{modify-frame-parameters} and specifying the variable 1532name as the parameter name. 1533 1534 To enable frame-local bindings for a certain variable, call the function 1535@code{make-variable-frame-local}. 1536 1537@deffn Command make-variable-frame-local variable 1538Enable the use of frame-local bindings for @var{variable}. This does 1539not in itself create any frame-local bindings for the variable; however, 1540if some frame already has a value for @var{variable} as a frame 1541parameter, that value automatically becomes a frame-local binding. 1542 1543If @var{variable} does not have a default value, then calling this 1544command will give it a default value of @code{nil}. If @var{variable} 1545already has a default value, that value remains unchanged. 1546 1547If the variable is terminal-local, this function signals an error, 1548because such variables cannot have frame-local bindings as well. 1549@xref{Multiple Displays}. A few variables that are implemented 1550specially in Emacs can be buffer-local, but can never be frame-local. 1551 1552This command returns @var{variable}. 1553@end deffn 1554 1555 Buffer-local bindings take precedence over frame-local bindings. Thus, 1556consider a variable @code{foo}: if the current buffer has a buffer-local 1557binding for @code{foo}, that binding is active; otherwise, if the 1558selected frame has a frame-local binding for @code{foo}, that binding is 1559active; otherwise, the default binding of @code{foo} is active. 1560 1561 Here is an example. First we prepare a few bindings for @code{foo}: 1562 1563@example 1564(setq f1 (selected-frame)) 1565(make-variable-frame-local 'foo) 1566 1567;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.} 1568(set-buffer (get-buffer-create "b1")) 1569(make-local-variable 'foo) 1570(setq foo '(b 1)) 1571 1572;; @r{Make a frame-local binding for @code{foo} in a new frame.} 1573;; @r{Store that frame in @code{f2}.} 1574(setq f2 (make-frame)) 1575(modify-frame-parameters f2 '((foo . (f 2)))) 1576@end example 1577 1578 Now we examine @code{foo} in various contexts. Whenever the 1579buffer @samp{b1} is current, its buffer-local binding is in effect, 1580regardless of the selected frame: 1581 1582@example 1583(select-frame f1) 1584(set-buffer (get-buffer-create "b1")) 1585foo 1586 @result{} (b 1) 1587 1588(select-frame f2) 1589(set-buffer (get-buffer-create "b1")) 1590foo 1591 @result{} (b 1) 1592@end example 1593 1594@noindent 1595Otherwise, the frame gets a chance to provide the binding; when frame 1596@code{f2} is selected, its frame-local binding is in effect: 1597 1598@example 1599(select-frame f2) 1600(set-buffer (get-buffer "*scratch*")) 1601foo 1602 @result{} (f 2) 1603@end example 1604 1605@noindent 1606When neither the current buffer nor the selected frame provides 1607a binding, the default binding is used: 1608 1609@example 1610(select-frame f1) 1611(set-buffer (get-buffer "*scratch*")) 1612foo 1613 @result{} nil 1614@end example 1615 1616@noindent 1617When the active binding of a variable is a frame-local binding, setting 1618the variable changes that binding. You can observe the result with 1619@code{frame-parameters}: 1620 1621@example 1622(select-frame f2) 1623(set-buffer (get-buffer "*scratch*")) 1624(setq foo 'nobody) 1625(assq 'foo (frame-parameters f2)) 1626 @result{} (foo . nobody) 1627@end example 1628 1629@node Future Local Variables 1630@section Possible Future Local Variables 1631 1632 We have considered the idea of bindings that are local to a category 1633of frames---for example, all color frames, or all frames with dark 1634backgrounds. We have not implemented them because it is not clear that 1635this feature is really useful. You can get more or less the same 1636results by adding a function to @code{after-make-frame-functions}, set up to 1637define a particular frame parameter according to the appropriate 1638conditions for each frame. 1639 1640 It would also be possible to implement window-local bindings. We 1641don't know of many situations where they would be useful, and it seems 1642that indirect buffers (@pxref{Indirect Buffers}) with buffer-local 1643bindings offer a way to handle these situations more robustly. 1644 1645 If sufficient application is found for either of these two kinds of 1646local bindings, we will provide it in a subsequent Emacs version. 1647 1648@node File Local Variables 1649@section File Local Variables 1650@cindex file local variables 1651 1652 A file can specify local variable values; Emacs uses these to create 1653buffer-local bindings for those variables in the buffer visiting that 1654file. @xref{File variables, , Local Variables in Files, emacs, The 1655GNU Emacs Manual}, for basic information about file local variables. 1656This section describes the functions and variables that affect 1657processing of file local variables. 1658 1659@defopt enable-local-variables 1660This variable controls whether to process file local variables. 1661The possible values are: 1662 1663@table @asis 1664@item @code{t} (the default) 1665Set the safe variables, and query (once) about any unsafe variables. 1666@item @code{:safe} 1667Set only the safe variables and do not query. 1668@item @code{:all} 1669Set all the variables and do not query. 1670@item @code{nil} 1671Don't set any variables. 1672@item anything else 1673Query (once) about all the variables. 1674@end table 1675@end defopt 1676 1677@defun hack-local-variables &optional mode-only 1678This function parses, and binds or evaluates as appropriate, any local 1679variables specified by the contents of the current buffer. The variable 1680@code{enable-local-variables} has its effect here. However, this 1681function does not look for the @samp{mode:} local variable in the 1682@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking 1683@code{enable-local-variables} into account (@pxref{Auto Major Mode}). 1684 1685If the optional argument @var{mode-only} is non-@code{nil}, then all 1686this function does is return @code{t} if the @w{@samp{-*-}} line or 1687the local variables list specifies a mode and @code{nil} otherwise. 1688It does not set the mode nor any other file local variable. 1689@end defun 1690 1691 If a file local variable could specify a function that would 1692be called later, or an expression that would be executed later, simply 1693visiting a file could take over your Emacs. Emacs takes several 1694measures to prevent this. 1695 1696@cindex safe local variable 1697 You can specify safe values for a variable with a 1698@code{safe-local-variable} property. The property has to be 1699a function of one argument; any value is safe if the function 1700returns non-@code{nil} given that value. Many commonly encountered 1701file variables standardly have @code{safe-local-variable} properties, 1702including @code{fill-column}, @code{fill-prefix}, and 1703@code{indent-tabs-mode}. For boolean-valued variables that are safe, 1704use @code{booleanp} as the property value. Lambda expressions should 1705be quoted so that @code{describe-variable} can display the predicate. 1706 1707@defopt safe-local-variable-values 1708This variable provides another way to mark some variable values as 1709safe. It is a list of cons cells @code{(@var{var} . @var{val})}, 1710where @var{var} is a variable name and @var{val} is a value which is 1711safe for that variable. 1712 1713When Emacs asks the user whether or not to obey a set of file local 1714variable specifications, the user can choose to mark them as safe. 1715Doing so adds those variable/value pairs to 1716@code{safe-local-variable-values}, and saves it to the user's custom 1717file. 1718@end defopt 1719 1720@defun safe-local-variable-p sym val 1721This function returns non-@code{nil} if it is safe to give @var{sym} 1722the value @var{val}, based on the above criteria. 1723@end defun 1724 1725@c @cindex risky local variable Duplicates risky-local-variable 1726 Some variables are considered @dfn{risky}. A variable whose name 1727ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function}, 1728@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, 1729@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, 1730@samp{-program}, or @samp{-predicate} is considered risky. The 1731variables @samp{font-lock-keywords}, @samp{font-lock-keywords} 1732followed by a digit, and @samp{font-lock-syntactic-keywords} are also 1733considered risky. Finally, any variable whose name has a 1734non-@code{nil} @code{risky-local-variable} property is considered 1735risky. 1736 1737@defun risky-local-variable-p sym 1738This function returns non-@code{nil} if @var{sym} is a risky variable, 1739based on the above criteria. 1740@end defun 1741 1742 If a variable is risky, it will not be entered automatically into 1743@code{safe-local-variable-values} as described above. Therefore, 1744Emacs will always query before setting a risky variable, unless the 1745user explicitly allows the setting by customizing 1746@code{safe-local-variable-values} directly. 1747 1748@defvar ignored-local-variables 1749This variable holds a list of variables that should not be given local 1750values by files. Any value specified for one of these variables is 1751completely ignored. 1752@end defvar 1753 1754 The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs 1755normally asks for confirmation before handling it. 1756 1757@defopt enable-local-eval 1758This variable controls processing of @samp{Eval:} in @samp{-*-} lines 1759or local variables 1760lists in files being visited. A value of @code{t} means process them 1761unconditionally; @code{nil} means ignore them; anything else means ask 1762the user what to do for each file. The default value is @code{maybe}. 1763@end defopt 1764 1765@defopt safe-local-eval-forms 1766This variable holds a list of expressions that are safe to 1767evaluate when found in the @samp{Eval:} ``variable'' in a file 1768local variables list. 1769@end defopt 1770 1771 If the expression is a function call and the function has a 1772@code{safe-local-eval-function} property, the property value 1773determines whether the expression is safe to evaluate. The property 1774value can be a predicate to call to test the expression, a list of 1775such predicates (it's safe if any predicate succeeds), or @code{t} 1776(always safe provided the arguments are constant). 1777 1778 Text properties are also potential loopholes, since their values 1779could include functions to call. So Emacs discards all text 1780properties from string values specified for file local variables. 1781 1782@node Variable Aliases 1783@section Variable Aliases 1784@cindex variable aliases 1785 1786 It is sometimes useful to make two variables synonyms, so that both 1787variables always have the same value, and changing either one also 1788changes the other. Whenever you change the name of a 1789variable---either because you realize its old name was not well 1790chosen, or because its meaning has partly changed---it can be useful 1791to keep the old name as an @emph{alias} of the new one for 1792compatibility. You can do this with @code{defvaralias}. 1793 1794@defun defvaralias new-alias base-variable &optional docstring 1795This function defines the symbol @var{new-alias} as a variable alias 1796for symbol @var{base-variable}. This means that retrieving the value 1797of @var{new-alias} returns the value of @var{base-variable}, and 1798changing the value of @var{new-alias} changes the value of 1799@var{base-variable}. The two aliased variable names always share the 1800same value and the same bindings. 1801 1802If the @var{docstring} argument is non-@code{nil}, it specifies the 1803documentation for @var{new-alias}; otherwise, the alias gets the same 1804documentation as @var{base-variable} has, if any, unless 1805@var{base-variable} is itself an alias, in which case @var{new-alias} gets 1806the documentation of the variable at the end of the chain of aliases. 1807 1808This function returns @var{base-variable}. 1809@end defun 1810 1811 Variable aliases are convenient for replacing an old name for a 1812variable with a new name. @code{make-obsolete-variable} declares that 1813the old name is obsolete and therefore that it may be removed at some 1814stage in the future. 1815 1816@defun make-obsolete-variable obsolete-name current-name &optional when 1817This function makes the byte-compiler warn that the variable 1818@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is 1819the variable's new name; then the warning message says to use 1820@var{current-name} instead of @var{obsolete-name}. If @var{current-name} 1821is a string, this is the message and there is no replacement variable. 1822 1823If provided, @var{when} should be a string indicating when the 1824variable was first made obsolete---for example, a date or a release 1825number. 1826@end defun 1827 1828 You can make two variables synonyms and declare one obsolete at the 1829same time using the macro @code{define-obsolete-variable-alias}. 1830 1831@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring 1832This macro marks the variable @var{obsolete-name} as obsolete and also 1833makes it an alias for the variable @var{current-name}. It is 1834equivalent to the following: 1835 1836@example 1837(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) 1838(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) 1839@end example 1840@end defmac 1841 1842@defun indirect-variable variable 1843This function returns the variable at the end of the chain of aliases 1844of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is 1845not defined as an alias, the function returns @var{variable}. 1846 1847This function signals a @code{cyclic-variable-indirection} error if 1848there is a loop in the chain of symbols. 1849@end defun 1850 1851@example 1852(defvaralias 'foo 'bar) 1853(indirect-variable 'foo) 1854 @result{} bar 1855(indirect-variable 'bar) 1856 @result{} bar 1857(setq bar 2) 1858bar 1859 @result{} 2 1860@group 1861foo 1862 @result{} 2 1863@end group 1864(setq foo 0) 1865bar 1866 @result{} 0 1867foo 1868 @result{} 0 1869@end example 1870 1871@node Variables with Restricted Values 1872@section Variables with Restricted Values 1873 1874 Ordinary Lisp variables can be assigned any value that is a valid 1875Lisp object. However, certain Lisp variables are not defined in Lisp, 1876but in C. Most of these variables are defined in the C code using 1877@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on 1878any value. However, some variables are defined using 1879@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp 1880variables in C,, Writing Emacs Primitives}, in particular the 1881description of functions of the type @code{syms_of_@var{filename}}, 1882for a brief discussion of the C implementation. 1883 1884 Variables of type @code{DEFVAR_BOOL} can only take on the values 1885@code{nil} or @code{t}. Attempting to assign them any other value 1886will set them to @code{t}: 1887 1888@example 1889(let ((display-hourglass 5)) 1890 display-hourglass) 1891 @result{} t 1892@end example 1893 1894@defvar byte-boolean-vars 1895This variable holds a list of all variables of type @code{DEFVAR_BOOL}. 1896@end defvar 1897 1898 Variables of type @code{DEFVAR_INT} can only take on integer values. 1899Attempting to assign them any other value will result in an error: 1900 1901@example 1902(setq window-min-height 5.0) 1903@error{} Wrong type argument: integerp, 5.0 1904@end example 1905 1906@ignore 1907 arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e 1908@end ignore 1909