Mercurial > emacs
comparison doc/lispref/variables.texi @ 91073:4bc33ffdda1a
Merge from emacs--devo--0
Patches applied:
* emacs--devo--0 (patch 902-908)
- Update from CVS
- Merge from emacs--rel--22
* emacs--rel--22 (patch 131-137)
- Update from CVS
- Merge from gnus--rel--5.10
* gnus--rel--5.10 (patch 261-262)
- Update from CVS
Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-278
author | Miles Bader <miles@gnu.org> |
---|---|
date | Sat, 27 Oct 2007 09:12:07 +0000 |
parents | b210bba3f477 |
children | 1aadc9bdea81 |
comparison
equal
deleted
inserted
replaced
91072:74ab3ea909f9 | 91073:4bc33ffdda1a |
---|---|
37 * Accessing Variables:: Examining values of variables whose names | 37 * Accessing Variables:: Examining values of variables whose names |
38 are known only at run time. | 38 are known only at run time. |
39 * Setting Variables:: Storing new values in variables. | 39 * Setting Variables:: Storing new values in variables. |
40 * Variable Scoping:: How Lisp chooses among local and global values. | 40 * Variable Scoping:: How Lisp chooses among local and global values. |
41 * Buffer-Local Variables:: Variable values in effect only in one buffer. | 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. | 42 * Future Local Variables:: New kinds of local values we might add some day. |
44 * File Local Variables:: Handling local variable lists in files. | 43 * File Local Variables:: Handling local variable lists in files. |
45 * Variable Aliases:: Variables that are aliases for other variables. | 44 * Variable Aliases:: Variables that are aliases for other variables. |
46 * Variables with Restricted Values:: Non-constant variables whose value can | 45 * Variables with Restricted Values:: Non-constant variables whose value can |
47 @emph{not} be an arbitrary Lisp object. | 46 @emph{not} be an arbitrary Lisp object. |
253 @item | 252 @item |
254 @code{condition-case} (@pxref{Errors}). | 253 @code{condition-case} (@pxref{Errors}). |
255 @end itemize | 254 @end itemize |
256 | 255 |
257 Variables can also have buffer-local bindings (@pxref{Buffer-Local | 256 Variables can also have buffer-local bindings (@pxref{Buffer-Local |
258 Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a | 257 Variables}); a few variables have terminal-local bindings |
259 few variables have terminal-local bindings (@pxref{Multiple Displays}). | 258 (@pxref{Multiple Displays}). These kinds of bindings work somewhat |
260 These kinds of bindings work somewhat like ordinary local bindings, but | 259 like ordinary local bindings, but they are localized depending on |
261 they are localized depending on ``where'' you are in Emacs, rather than | 260 ``where'' you are in Emacs, rather than localized in time. |
262 localized in time. | |
263 | 261 |
264 @defvar max-specpdl-size | 262 @defvar max-specpdl-size |
265 @anchor{Definition of max-specpdl-size} | 263 @anchor{Definition of max-specpdl-size} |
266 @cindex variable limit error | 264 @cindex variable limit error |
267 @cindex evaluation error | 265 @cindex evaluation error |
1083 @section Buffer-Local Variables | 1081 @section Buffer-Local Variables |
1084 @cindex variable, buffer-local | 1082 @cindex variable, buffer-local |
1085 @cindex buffer-local variables | 1083 @cindex buffer-local variables |
1086 | 1084 |
1087 Global and local variable bindings are found in most programming | 1085 Global and local variable bindings are found in most programming |
1088 languages in one form or another. Emacs, however, also supports additional, | 1086 languages in one form or another. Emacs, however, also supports |
1089 unusual kinds of variable binding: @dfn{buffer-local} bindings, which | 1087 additional, unusual kinds of variable binding, such as |
1090 apply only in one buffer, and @dfn{frame-local} bindings, which apply only in | 1088 @dfn{buffer-local} bindings, which apply only in one buffer. Having |
1091 one frame. Having different values for a variable in different buffers | 1089 different values for a variable in different buffers is an important |
1092 and/or frames is an important customization method. | 1090 customization method. (A few variables have bindings that are local |
1093 | 1091 to each terminal; see @ref{Multiple Displays}.) |
1094 This section describes buffer-local bindings; for frame-local | |
1095 bindings, see the following section, @ref{Frame-Local Variables}. (A few | |
1096 variables have bindings that are local to each terminal; see | |
1097 @ref{Multiple Displays}.) | |
1098 | 1092 |
1099 @menu | 1093 @menu |
1100 * Intro to Buffer-Local:: Introduction and concepts. | 1094 * Intro to Buffer-Local:: Introduction and concepts. |
1101 * Creating Buffer-Local:: Creating and destroying buffer-local bindings. | 1095 * Creating Buffer-Local:: Creating and destroying buffer-local bindings. |
1102 * Default Value:: The default value is seen in buffers | 1096 * Default Value:: The default value is seen in buffers |
1119 | 1113 |
1120 A variable can have buffer-local bindings in some buffers but not in | 1114 A variable can have buffer-local bindings in some buffers but not in |
1121 other buffers. The default binding is shared by all the buffers that | 1115 other buffers. The default binding is shared by all the buffers that |
1122 don't have their own bindings for the variable. (This includes all | 1116 don't have their own bindings for the variable. (This includes all |
1123 newly-created buffers.) If you set the variable in a buffer that does | 1117 newly-created buffers.) If you set the variable in a buffer that does |
1124 not have a buffer-local binding for it, this sets the default binding | 1118 not have a buffer-local binding for it, this sets the default binding, |
1125 (assuming there are no frame-local bindings to complicate the matter), | |
1126 so the new value is visible in all the buffers that see the default | 1119 so the new value is visible in all the buffers that see the default |
1127 binding. | 1120 binding. |
1128 | 1121 |
1129 The most common use of buffer-local bindings is for major modes to change | 1122 The most common use of buffer-local bindings is for major modes to change |
1130 variables that control the behavior of commands. For example, C mode and | 1123 variables that control the behavior of commands. For example, C mode and |
1151 buffer. The new value is stored in the buffer-local binding, leaving | 1144 buffer. The new value is stored in the buffer-local binding, leaving |
1152 the default binding untouched. This means that the default value cannot | 1145 the default binding untouched. This means that the default value cannot |
1153 be changed with @code{setq} in any buffer; the only way to change it is | 1146 be changed with @code{setq} in any buffer; the only way to change it is |
1154 with @code{setq-default}. | 1147 with @code{setq-default}. |
1155 | 1148 |
1156 @strong{Warning:} When a variable has buffer-local or frame-local | 1149 @strong{Warning:} When a variable has buffer-local |
1157 bindings in one or more buffers, @code{let} rebinds the binding that's | 1150 bindings in one or more buffers, @code{let} rebinds the binding that's |
1158 currently in effect. For instance, if the current buffer has a | 1151 currently in effect. For instance, if the current buffer has a |
1159 buffer-local value, @code{let} temporarily rebinds that. If no | 1152 buffer-local value, @code{let} temporarily rebinds that. If no |
1160 buffer-local or frame-local bindings are in effect, @code{let} rebinds | 1153 buffer-local bindings are in effect, @code{let} rebinds |
1161 the default value. If inside the @code{let} you then change to a | 1154 the default value. If inside the @code{let} you then change to a |
1162 different current buffer in which a different binding is in effect, | 1155 different current buffer in which a different binding is in effect, |
1163 you won't see the @code{let} binding any more. And if you exit the | 1156 you 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 | 1157 @code{let} while still in the other buffer, you won't see the |
1165 unbinding occur (though it will occur properly). Here is an example | 1158 unbinding occur (though it will occur properly). Here is an example |
1419 this variable. | 1412 this variable. |
1420 | 1413 |
1421 @c Emacs 19 feature | 1414 @c Emacs 19 feature |
1422 The special forms @code{defvar} and @code{defconst} also set the | 1415 The special forms @code{defvar} and @code{defconst} also set the |
1423 default value (if they set the variable at all), rather than any | 1416 default value (if they set the variable at all), rather than any |
1424 buffer-local or frame-local value. | 1417 buffer-local value. |
1425 | 1418 |
1426 @defun default-value symbol | 1419 @defun default-value symbol |
1427 This function returns @var{symbol}'s default value. This is the value | 1420 This function returns @var{symbol}'s default value. This is the value |
1428 that is seen in buffers and frames that do not have their own values for | 1421 that is seen in buffers and frames that do not have their own values for |
1429 this variable. If @var{symbol} is not buffer-local, this is equivalent | 1422 this variable. If @var{symbol} is not buffer-local, this is equivalent |
1517 (default-value 'a) | 1510 (default-value 'a) |
1518 @result{} 23 | 1511 @result{} 23 |
1519 @end group | 1512 @end group |
1520 @end example | 1513 @end example |
1521 @end defun | 1514 @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 | |
1528 frame-local bindings. These bindings belong to one frame, and are in | |
1529 effect when that frame is selected. Frame-local bindings are actually | |
1530 frame parameters: you create a frame-local binding in a specific frame | |
1531 by calling @code{modify-frame-parameters} and specifying the variable | |
1532 name 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 | |
1538 Enable the use of frame-local bindings for @var{variable}. This does | |
1539 not in itself create any frame-local bindings for the variable; however, | |
1540 if some frame already has a value for @var{variable} as a frame | |
1541 parameter, that value automatically becomes a frame-local binding. | |
1542 | |
1543 If @var{variable} does not have a default value, then calling this | |
1544 command will give it a default value of @code{nil}. If @var{variable} | |
1545 already has a default value, that value remains unchanged. | |
1546 | |
1547 If the variable is terminal-local, this function signals an error, | |
1548 because such variables cannot have frame-local bindings as well. | |
1549 @xref{Multiple Displays}. A few variables that are implemented | |
1550 specially in Emacs can be buffer-local, but can never be frame-local. | |
1551 | |
1552 This command returns @var{variable}. | |
1553 @end deffn | |
1554 | |
1555 Buffer-local bindings take precedence over frame-local bindings. Thus, | |
1556 consider a variable @code{foo}: if the current buffer has a buffer-local | |
1557 binding for @code{foo}, that binding is active; otherwise, if the | |
1558 selected frame has a frame-local binding for @code{foo}, that binding is | |
1559 active; 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 | |
1579 buffer @samp{b1} is current, its buffer-local binding is in effect, | |
1580 regardless of the selected frame: | |
1581 | |
1582 @example | |
1583 (select-frame f1) | |
1584 (set-buffer (get-buffer-create "b1")) | |
1585 foo | |
1586 @result{} (b 1) | |
1587 | |
1588 (select-frame f2) | |
1589 (set-buffer (get-buffer-create "b1")) | |
1590 foo | |
1591 @result{} (b 1) | |
1592 @end example | |
1593 | |
1594 @noindent | |
1595 Otherwise, 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*")) | |
1601 foo | |
1602 @result{} (f 2) | |
1603 @end example | |
1604 | |
1605 @noindent | |
1606 When neither the current buffer nor the selected frame provides | |
1607 a binding, the default binding is used: | |
1608 | |
1609 @example | |
1610 (select-frame f1) | |
1611 (set-buffer (get-buffer "*scratch*")) | |
1612 foo | |
1613 @result{} nil | |
1614 @end example | |
1615 | |
1616 @noindent | |
1617 When the active binding of a variable is a frame-local binding, setting | |
1618 the 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 | 1515 |
1629 @node Future Local Variables | 1516 @node Future Local Variables |
1630 @section Possible Future Local Variables | 1517 @section Possible Future Local Variables |
1631 | 1518 |
1632 We have considered the idea of bindings that are local to a category | 1519 We have considered the idea of bindings that are local to a category |