Mercurial > emacs
comparison lispref/variables.texi @ 22138:d4ac295a98b3
*** empty log message ***
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 19 May 1998 03:45:57 +0000 |
parents | 90da2489c498 |
children | 40089afa2b1d |
comparison
equal
deleted
inserted
replaced
22137:2b0e6a1e7fb9 | 22138:d4ac295a98b3 |
---|---|
102 In Emacs Lisp, certain symbols normally evaluate to themselves. These | 102 In Emacs Lisp, certain symbols normally evaluate to themselves. These |
103 include @code{nil} and @code{t}, as well as any symbol whose name starts | 103 include @code{nil} and @code{t}, as well as any symbol whose name starts |
104 with @samp{:}. These symbols cannot be rebound, nor can their values be | 104 with @samp{:}. These symbols cannot be rebound, nor can their values be |
105 changed. Any attempt to set or bind @code{nil} or @code{t} signals a | 105 changed. Any attempt to set or bind @code{nil} or @code{t} signals a |
106 @code{setting-constant} error. The same is true for a symbol whose name | 106 @code{setting-constant} error. The same is true for a symbol whose name |
107 starts with @samp{:}, except that you are allowed to set such symbol to | 107 starts with @samp{:}, except that you are allowed to set such a symbol to |
108 itself. | 108 itself. |
109 | 109 |
110 @example | 110 @example |
111 @group | 111 @group |
112 nil @equiv{} 'nil | 112 nil @equiv{} 'nil |
116 (setq nil 500) | 116 (setq nil 500) |
117 @error{} Attempt to set constant symbol: nil | 117 @error{} Attempt to set constant symbol: nil |
118 @end group | 118 @end group |
119 @end example | 119 @end example |
120 | 120 |
121 @defvar keyword-symbols-constant-flag | |
121 @tindex keyword-symbols-constant-flag | 122 @tindex keyword-symbols-constant-flag |
122 @defvar keyword-symbols-constant-flag | |
123 If this variable is @code{nil}, you are allowed to set and bind symbols | 123 If this variable is @code{nil}, you are allowed to set and bind symbols |
124 whose names start with @samp{:} as you wish. This is to make it | 124 whose names start with @samp{:} as you wish. This is to make it |
125 possible to run old Lisp programs which do that. | 125 possible to run old Lisp programs which do that. |
126 @end defvar | 126 @end defvar |
127 | 127 |
245 @item | 245 @item |
246 @code{condition-case} (@pxref{Errors}). | 246 @code{condition-case} (@pxref{Errors}). |
247 @end itemize | 247 @end itemize |
248 | 248 |
249 Variables can also have buffer-local bindings (@pxref{Buffer-Local | 249 Variables can also have buffer-local bindings (@pxref{Buffer-Local |
250 Variables}); a few variables have terminal-local bindings | 250 Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a |
251 (@pxref{Multiple Displays}). These kinds of bindings work somewhat like | 251 few variables have terminal-local bindings (@pxref{Multiple Displays}). |
252 ordinary local bindings, but they are localized depending on ``where'' | 252 These kinds of bindings work somewhat like ordinary local bindings, but |
253 you are in Emacs, rather than localized in time. | 253 they are localized depending on ``where'' you are in Emacs, rather than |
254 localized in time. | |
254 | 255 |
255 @defvar max-specpdl-size | 256 @defvar max-specpdl-size |
256 @cindex variable limit error | 257 @cindex variable limit error |
257 @cindex evaluation error | 258 @cindex evaluation error |
258 @cindex infinite recursion | 259 @cindex infinite recursion |
259 This variable defines the limit on the total number of local variable | 260 This variable defines the limit on the total number of local variable |
260 bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits}) | 261 bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits}) |
261 that are allowed before signaling an error (with data @code{"Variable | 262 that are allowed before signaling an error (with data @code{"Variable |
262 binding depth exceeds max-specpdl-size"}). | 263 binding depth exceeds max-specpdl-size"}). |
263 | 264 |
264 This limit, with the associated error when it is exceeded, is one way | 265 This limit, with the associated error when it is exceeded, is one way |
265 that Lisp avoids infinite recursion on an ill-defined function. | 266 that Lisp avoids infinite recursion on an ill-defined function. |
266 | 267 @code{max-lisp-eval-depth} provides another limit on depth of nesting. |
267 The default value is 600. | |
268 | |
269 @code{max-lisp-eval-depth} provides another limit on depth of nesting. | |
270 @xref{Eval}. | 268 @xref{Eval}. |
269 | |
270 The default value is 600. Entry to the Lisp debugger increases the | |
271 value, if there is little room left, to make sure the debugger itself | |
272 has room to execute. | |
271 @end defvar | 273 @end defvar |
272 | 274 |
273 @node Void Variables | 275 @node Void Variables |
274 @section When a Variable is ``Void'' | 276 @section When a Variable is ``Void'' |
275 @kindex void-variable | 277 @kindex void-variable |
428 evaluates it and sets @var{symbol} to the result. But if @var{symbol} | 430 evaluates it and sets @var{symbol} to the result. But if @var{symbol} |
429 already has a value (i.e., it is not void), @var{value} is not even | 431 already has a value (i.e., it is not void), @var{value} is not even |
430 evaluated, and @var{symbol}'s value remains unchanged. If @var{value} | 432 evaluated, and @var{symbol}'s value remains unchanged. If @var{value} |
431 is omitted, the value of @var{symbol} is not changed in any case. | 433 is omitted, the value of @var{symbol} is not changed in any case. |
432 | 434 |
435 If @var{symbol} has a buffer-local binding in the current buffer, | |
436 @code{defvar} operates on the default value, which is buffer-independent, | |
437 not the current (buffer-local) binding. It sets the default value if | |
438 the default value is void. @xref{Buffer-Local Variables}. | |
439 | |
433 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in | 440 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in |
434 Emacs Lisp mode (@code{eval-defun}), a special feature of | 441 Emacs Lisp mode (@code{eval-defun}), a special feature of |
435 @code{eval-defun} arranges to set the variable unconditionally even if | 442 @code{eval-defun} arranges to set the variable unconditionally, without |
436 the variable already has a value. | 443 testing whether its value is void. |
437 | |
438 If @var{symbol} has a buffer-local binding in the current buffer, | |
439 @code{defvar} sets the default (buffer-independent) value, not the | |
440 buffer-local value. @xref{Buffer-Local Variables}. | |
441 | 444 |
442 If the @var{doc-string} argument appears, it specifies the documentation | 445 If the @var{doc-string} argument appears, it specifies the documentation |
443 for the variable. (This opportunity to specify documentation is one of | 446 for the variable. (This opportunity to specify documentation is one of |
444 the main benefits of defining the variable.) The documentation is | 447 the main benefits of defining the variable.) The documentation is |
445 stored in the symbol's @code{variable-documentation} property. The | 448 stored in the symbol's @code{variable-documentation} property. The |
516 or by other programs. Note that @var{symbol} is not evaluated; the | 519 or by other programs. Note that @var{symbol} is not evaluated; the |
517 symbol to be defined must appear explicitly in the @code{defconst}. | 520 symbol to be defined must appear explicitly in the @code{defconst}. |
518 | 521 |
519 @code{defconst} always evaluates @var{value}, and sets the value of | 522 @code{defconst} always evaluates @var{value}, and sets the value of |
520 @var{symbol} to the result if @var{value} is given. If @var{symbol} | 523 @var{symbol} to the result if @var{value} is given. If @var{symbol} |
521 does has a buffer-local binding in the current buffer, @code{defconst} | 524 does have a buffer-local binding in the current buffer, @code{defconst} |
522 sets the default value, not the buffer-local value. But you should not | 525 sets the default value, not the buffer-local value. (But you should not |
523 be making the symbol buffer-local if it is defined with @code{defconst}. | 526 be making buffer-local bindings for a symbol that is defined with |
527 @code{defconst}.) | |
524 | 528 |
525 Here, @code{pi} is a constant that presumably ought not to be changed | 529 Here, @code{pi} is a constant that presumably ought not to be changed |
526 by anyone (attempts by the Indiana State Legislature notwithstanding). | 530 by anyone (attempts by the Indiana State Legislature notwithstanding). |
527 As the second form illustrates, however, this is only advisory. | 531 As the second form illustrates, however, this is only advisory. |
528 | 532 |
558 @kindex variable-interactive | 562 @kindex variable-interactive |
559 If a user option variable has a @code{variable-interactive} property, | 563 If a user option variable has a @code{variable-interactive} property, |
560 the @code{set-variable} command uses that value to control reading the | 564 the @code{set-variable} command uses that value to control reading the |
561 new value for the variable. The property's value is used as if it were | 565 new value for the variable. The property's value is used as if it were |
562 to @code{interactive} (@pxref{Using Interactive}). However, this feature | 566 to @code{interactive} (@pxref{Using Interactive}). However, this feature |
563 is largely obsoleted by the @code{defcustom} (@pxref{Customization}). | 567 is largely obsoleted by @code{defcustom} (@pxref{Customization}). |
564 | 568 |
565 @strong{Warning:} If the @code{defconst} and @code{defvar} special | 569 @strong{Warning:} If the @code{defconst} and @code{defvar} special |
566 forms are used while the variable has a local binding, they set the | 570 forms are used while the variable has a local binding, they set the |
567 local binding's value; the global binding is not changed. This is not | 571 local binding's value; the global binding is not changed. This is not |
568 what we really want. To prevent it, use these special forms at top | 572 what we really want. To prevent it, use these special forms at top |
1067 one frame. Having different values for a variable in different buffers | 1071 one frame. Having different values for a variable in different buffers |
1068 and/or frames is an important customization method. | 1072 and/or frames is an important customization method. |
1069 | 1073 |
1070 This section describes buffer-local bindings; for frame-local | 1074 This section describes buffer-local bindings; for frame-local |
1071 bindings, see the following section, @ref{Frame-Local Variables}. (A few | 1075 bindings, see the following section, @ref{Frame-Local Variables}. (A few |
1072 variables have bindings that are local to a X terminal; see | 1076 variables have bindings that are local to each X terminal; see |
1073 @ref{Multiple Displays}.) | 1077 @ref{Multiple Displays}.) |
1074 | 1078 |
1075 @menu | 1079 @menu |
1076 * Intro to Buffer-Local:: Introduction and concepts. | 1080 * Intro to Buffer-Local:: Introduction and concepts. |
1077 * Creating Buffer-Local:: Creating and destroying buffer-local bindings. | 1081 * Creating Buffer-Local:: Creating and destroying buffer-local bindings. |
1135 different binding is in effect, and then exiting the @code{let}. This | 1139 different binding is in effect, and then exiting the @code{let}. This |
1136 can scramble the values of the buffer-local and default bindings. | 1140 can scramble the values of the buffer-local and default bindings. |
1137 | 1141 |
1138 To preserve your sanity, avoid using a variable in that way. If you | 1142 To preserve your sanity, avoid using a variable in that way. If you |
1139 use @code{save-excursion} around each piece of code that changes to a | 1143 use @code{save-excursion} around each piece of code that changes to a |
1140 different current buffer, you will not have this problem. Here is an | 1144 different current buffer, you will not have this problem |
1141 example of what to avoid: | 1145 (@pxref{Excursions}). Here is an example of what to avoid: |
1142 | 1146 |
1143 @example | 1147 @example |
1144 @group | 1148 @group |
1145 (setq foo 'b) | 1149 (setq foo 'b) |
1146 (set-buffer "a") | 1150 (set-buffer "a") |
1286 (setq bind-me 69) | 1290 (setq bind-me 69) |
1287 @end group | 1291 @end group |
1288 (setq lcl (buffer-local-variables)) | 1292 (setq lcl (buffer-local-variables)) |
1289 ;; @r{First, built-in variables local in all buffers:} | 1293 ;; @r{First, built-in variables local in all buffers:} |
1290 @result{} ((mark-active . nil) | 1294 @result{} ((mark-active . nil) |
1291 (buffer-undo-list nil) | 1295 (buffer-undo-list . nil) |
1292 (mode-name . "Fundamental") | 1296 (mode-name . "Fundamental") |
1293 @dots{} | 1297 @dots{} |
1294 @group | 1298 @group |
1295 ;; @r{Next, non-built-in buffer-local variables.} | 1299 ;; @r{Next, non-built-in buffer-local variables.} |
1296 ;; @r{This one is buffer-local and void:} | 1300 ;; @r{This one is buffer-local and void:} |
1329 current buffer except for variables marked as ``permanent''. As a | 1333 current buffer except for variables marked as ``permanent''. As a |
1330 result, the buffer will see the default values of most variables. | 1334 result, the buffer will see the default values of most variables. |
1331 | 1335 |
1332 This function also resets certain other information pertaining to the | 1336 This function also resets certain other information pertaining to the |
1333 buffer: it sets the local keymap to @code{nil}, the syntax table to the | 1337 buffer: it sets the local keymap to @code{nil}, the syntax table to the |
1334 value of @code{standard-syntax-table}, and the abbrev table to the value | 1338 value of @code{(standard-syntax-table)}, the case table to |
1335 of @code{fundamental-mode-abbrev-table}. | 1339 @code{(standard-case-table)}, and the abbrev table to the value of |
1340 @code{fundamental-mode-abbrev-table}. | |
1336 | 1341 |
1337 The very first thing this function does is run the normal hook | 1342 The very first thing this function does is run the normal hook |
1338 @code{change-major-mode-hook} (see below). | 1343 @code{change-major-mode-hook} (see below). |
1339 | 1344 |
1340 Every major mode command begins by calling this function, which has the | 1345 Every major mode command begins by calling this function, which has the |
1398 | 1403 |
1399 @code{default-boundp} is to @code{default-value} as @code{boundp} is to | 1404 @code{default-boundp} is to @code{default-value} as @code{boundp} is to |
1400 @code{symbol-value}. | 1405 @code{symbol-value}. |
1401 @end defun | 1406 @end defun |
1402 | 1407 |
1403 @defspec setq-default symbol value | 1408 @defspec setq-default [symbol form]@dots{} |
1404 This sets the default value of @var{symbol} to @var{value}. It does not | 1409 This special form gives each @var{symbol} a new default value, which is |
1405 evaluate @var{symbol}, but does evaluate @var{value}. The value of the | 1410 the result of evaluating the corresponding @var{form}. It does not |
1406 @code{setq-default} form is @var{value}. | 1411 evaluate @var{symbol}, but does evaluate @var{form}. The value of the |
1412 @code{setq-default} form is the value of the last @var{form}. | |
1407 | 1413 |
1408 If a @var{symbol} is not buffer-local for the current buffer, and is not | 1414 If a @var{symbol} is not buffer-local for the current buffer, and is not |
1409 marked automatically buffer-local, @code{setq-default} has the same | 1415 marked automatically buffer-local, @code{setq-default} has the same |
1410 effect as @code{setq}. If @var{symbol} is buffer-local for the current | 1416 effect as @code{setq}. If @var{symbol} is buffer-local for the current |
1411 buffer, then this changes the value that other buffers will see (as long | 1417 buffer, then this changes the value that other buffers will see (as long |
1490 name as the parameter name. | 1496 name as the parameter name. |
1491 | 1497 |
1492 To enable frame-local bindings for a certain variable, call the function | 1498 To enable frame-local bindings for a certain variable, call the function |
1493 @code{make-variable-frame-local}. | 1499 @code{make-variable-frame-local}. |
1494 | 1500 |
1495 @defun make-variable-frame-local variable | 1501 @deffn Command make-variable-frame-local variable |
1496 Enable the use of frame-local bindings for @var{variable}. This does | 1502 Enable the use of frame-local bindings for @var{variable}. This does |
1497 not in itself create any frame-local bindings for the variable; however, | 1503 not in itself create any frame-local bindings for the variable; however, |
1498 if some frame already has a value for @var{variable} as a frame | 1504 if some frame already has a value for @var{variable} as a frame |
1499 parameter, that value automatically becomes a frame-local binding. | 1505 parameter, that value automatically becomes a frame-local binding. |
1500 | 1506 |
1501 If the variable is terminal-local, this function signals an error. Such | 1507 If the variable is terminal-local, this function signals an error, |
1502 variables cannot have buffer-local bindings as well. @xref{Multiple | 1508 because such variables cannot have frame-local bindings as well. |
1503 Displays}. A few variables that are implemented specially in Emacs | 1509 @xref{Multiple Displays}. A few variables that are implemented |
1504 can be (and usually are) buffer-local, but can never be frame-local. | 1510 specially in Emacs can be (and usually are) buffer-local, but can never |
1505 @end defun | 1511 be frame-local. |
1512 @end deffn | |
1506 | 1513 |
1507 Buffer-local bindings take precedence over frame-local bindings. Thus, | 1514 Buffer-local bindings take precedence over frame-local bindings. Thus, |
1508 consider a variable @code{foo}: if the current buffer has a buffer-local | 1515 consider a variable @code{foo}: if the current buffer has a buffer-local |
1509 binding for @code{foo}, that binding is active; otherwise, if the | 1516 binding for @code{foo}, that binding is active; otherwise, if the |
1510 selected frame has a frame-local binding for @code{foo}, that binding is | 1517 selected frame has a frame-local binding for @code{foo}, that binding is |