-This is ../info/lispref.info, produced by makeinfo version 4.0 from
-lispref/lispref.texi.
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Handling Errors, Next: Error Symbols, Prev: Processing of Errors, Up: Errors
-
-Writing Code to Handle Errors
-.............................
-
- The usual effect of signaling an error is to terminate the command
-that is running and return immediately to the XEmacs editor command
-loop. You can arrange to trap errors occurring in a part of your
-program by establishing an error handler, with the special form
-`condition-case'. A simple example looks like this:
-
- (condition-case nil
- (delete-file filename)
- (error nil))
-
-This deletes the file named FILENAME, catching any error and returning
-`nil' if an error occurs.
-
- The second argument of `condition-case' is called the "protected
-form". (In the example above, the protected form is a call to
-`delete-file'.) The error handlers go into effect when this form
-begins execution and are deactivated when this form returns. They
-remain in effect for all the intervening time. In particular, they are
-in effect during the execution of functions called by this form, in
-their subroutines, and so on. This is a good thing, since, strictly
-speaking, errors can be signaled only by Lisp primitives (including
-`signal' and `error') called by the protected form, not by the
-protected form itself.
-
- The arguments after the protected form are handlers. Each handler
-lists one or more "condition names" (which are symbols) to specify
-which errors it will handle. The error symbol specified when an error
-is signaled also defines a list of condition names. A handler applies
-to an error if they have any condition names in common. In the example
-above, there is one handler, and it specifies one condition name,
-`error', which covers all errors.
-
- The search for an applicable handler checks all the established
-handlers starting with the most recently established one. Thus, if two
-nested `condition-case' forms offer to handle the same error, the inner
-of the two will actually handle it.
-
- When an error is handled, control returns to the handler. Before
-this happens, XEmacs unbinds all variable bindings made by binding
-constructs that are being exited and executes the cleanups of all
-`unwind-protect' forms that are exited. Once control arrives at the
-handler, the body of the handler is executed.
-
- After execution of the handler body, execution continues by returning
-from the `condition-case' form. Because the protected form is exited
-completely before execution of the handler, the handler cannot resume
-execution at the point of the error, nor can it examine variable
-bindings that were made within the protected form. All it can do is
-clean up and proceed.
-
- `condition-case' is often used to trap errors that are predictable,
-such as failure to open a file in a call to `insert-file-contents'. It
-is also used to trap errors that are totally unpredictable, such as
-when the program evaluates an expression read from the user.
-
- Even when an error is handled, the debugger may still be called if
-the variable `debug-on-signal' (*note Error Debugging::) is non-`nil'.
-Note that this may yield unpredictable results with code that traps
-expected errors as normal part of its operation. Do not set
-`debug-on-signal' unless you know what you are doing.
-
- Error signaling and handling have some resemblance to `throw' and
-`catch', but they are entirely separate facilities. An error cannot be
-caught by a `catch', and a `throw' cannot be handled by an error
-handler (though using `throw' when there is no suitable `catch' signals
-an error that can be handled).
-
- - Special Form: condition-case var protected-form handlers...
- This special form establishes the error handlers HANDLERS around
- the execution of PROTECTED-FORM. If PROTECTED-FORM executes
- without error, the value it returns becomes the value of the
- `condition-case' form; in this case, the `condition-case' has no
- effect. The `condition-case' form makes a difference when an
- error occurs during PROTECTED-FORM.
-
- Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
- Here CONDITIONS is an error condition name to be handled, or a
- list of condition names; BODY is one or more Lisp expressions to
- be executed when this handler handles an error. Here are examples
- of handlers:
-
- (error nil)
-
- (arith-error (message "Division by zero"))
-
- ((arith-error file-error)
- (message
- "Either division by zero or failure to open a file"))
-
- Each error that occurs has an "error symbol" that describes what
- kind of error it is. The `error-conditions' property of this
- symbol is a list of condition names (*note Error Symbols::). Emacs
- searches all the active `condition-case' forms for a handler that
- specifies one or more of these condition names; the innermost
- matching `condition-case' handles the error. Within this
- `condition-case', the first applicable handler handles the error.
-
- After executing the body of the handler, the `condition-case'
- returns normally, using the value of the last form in the handler
- body as the overall value.
-
- The argument VAR is a variable. `condition-case' does not bind
- this variable when executing the PROTECTED-FORM, only when it
- handles an error. At that time, it binds VAR locally to a list of
- the form `(ERROR-SYMBOL . DATA)', giving the particulars of the
- error. The handler can refer to this list to decide what to do.
- For example, if the error is for failure opening a file, the file
- name is the second element of DATA--the third element of VAR.
-
- If VAR is `nil', that means no variable is bound. Then the error
- symbol and associated data are not available to the handler.
-
- Here is an example of using `condition-case' to handle the error
-that results from dividing by zero. The handler prints out a warning
-message and returns a very large number.
-
- (defun safe-divide (dividend divisor)
- (condition-case err
- ;; Protected form.
- (/ dividend divisor)
- ;; The handler.
- (arith-error ; Condition.
- (princ (format "Arithmetic error: %s" err))
- 1000000)))
- => safe-divide
-
- (safe-divide 5 0)
- -| Arithmetic error: (arith-error)
- => 1000000
-
-The handler specifies condition name `arith-error' so that it will
-handle only division-by-zero errors. Other kinds of errors will not be
-handled, at least not by this `condition-case'. Thus,
-
- (safe-divide nil 3)
- error--> Wrong type argument: integer-or-marker-p, nil
-
- Here is a `condition-case' that catches all kinds of errors,
-including those signaled with `error':
-
- (setq baz 34)
- => 34
-
- (condition-case err
- (if (eq baz 35)
- t
- ;; This is a call to the function `error'.
- (error "Rats! The variable %s was %s, not 35" 'baz baz))
- ;; This is the handler; it is not a form.
- (error (princ (format "The error was: %s" err))
- 2))
- -| The error was: (error "Rats! The variable baz was 34, not 35")
- => 2
-
-\1f
-File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors
-
-Error Symbols and Condition Names
-.................................
-
- When you signal an error, you specify an "error symbol" to specify
-the kind of error you have in mind. Each error has one and only one
-error symbol to categorize it. This is the finest classification of
-errors defined by the XEmacs Lisp language.
-
- These narrow classifications are grouped into a hierarchy of wider
-classes called "error conditions", identified by "condition names".
-The narrowest such classes belong to the error symbols themselves: each
-error symbol is also a condition name. There are also condition names
-for more extensive classes, up to the condition name `error' which
-takes in all kinds of errors. Thus, each error has one or more
-condition names: `error', the error symbol if that is distinct from
-`error', and perhaps some intermediate classifications.
-
- In other words, each error condition "inherits" from another error
-condition, with `error' sitting at the top of the inheritance hierarchy.
-
- - Function: define-error error-symbol error-message &optional
- inherits-from
- This function defines a new error, denoted by ERROR-SYMBOL.
- ERROR-MESSAGE is an informative message explaining the error, and
- will be printed out when an unhandled error occurs. ERROR-SYMBOL
- is a sub-error of INHERITS-FROM (which defaults to `error').
-
- `define-error' internally works by putting on ERROR-SYMBOL an
- `error-message' property whose value is ERROR-MESSAGE, and an
- `error-conditions' property that is a list of ERROR-SYMBOL
- followed by each of its super-errors, up to and including `error'.
- You will sometimes see code that sets this up directly rather than
- calling `define-error', but you should _not_ do this yourself,
- unless you wish to maintain compatibility with FSF Emacs, which
- does not provide `define-error'.
-
- Here is how we define a new error symbol, `new-error', that belongs
-to a range of errors called `my-own-errors':
-
- (define-error 'my-own-errors "A whole range of errors" 'error)
- (define-error 'new-error "A new error" 'my-own-errors)
-
-`new-error' has three condition names: `new-error', the narrowest
-classification; `my-own-errors', which we imagine is a wider
-classification; and `error', which is the widest of all.
-
- Note that it is not legal to try to define an error unless its
-super-error is also defined. For instance, attempting to define
-`new-error' before `my-own-errors' are defined will signal an error.
-
- The error string should start with a capital letter but it should
-not end with a period. This is for consistency with the rest of Emacs.
-
- Naturally, XEmacs will never signal `new-error' on its own; only an
-explicit call to `signal' (*note Signaling Errors::) in your code can
-do this:
-
- (signal 'new-error '(x y))
- error--> A new error: x, y
-
- This error can be handled through any of the three condition names.
-This example handles `new-error' and any other errors in the class
-`my-own-errors':
-
- (condition-case foo
- (bar nil t)
- (my-own-errors nil))
-
- The significant way that errors are classified is by their condition
-names--the names used to match errors with handlers. An error symbol
-serves only as a convenient way to specify the intended error message
-and list of condition names. It would be cumbersome to give `signal' a
-list of condition names rather than one error symbol.
-
- By contrast, using only error symbols without condition names would
-seriously decrease the power of `condition-case'. Condition names make
-it possible to categorize errors at various levels of generality when
-you write an error handler. Using error symbols alone would eliminate
-all but the narrowest level of classification.
-
- *Note Standard Errors::, for a list of all the standard error symbols
-and their conditions.
-
-\1f
File: lispref.info, Node: Cleanups, Prev: Errors, Up: Nonlocal Exits
Cleaning Up from Nonlocal Exits
put a data structure in an inconsistent state; it permits you to ensure
the data are consistent in the event of an error or throw.
- - Special Form: unwind-protect body cleanup-forms...
+ - Special Form: unwind-protect BODY CLEANUP-FORMS...
`unwind-protect' executes the BODY with a guarantee that the
CLEANUP-FORMS will be evaluated if control leaves BODY, no matter
how that happens. The BODY may complete normally, or execute a
Only the BODY is actually protected by the `unwind-protect'. If
any of the CLEANUP-FORMS themselves exits nonlocally (e.g., via a
- `throw' or an error), `unwind-protect' is _not_ guaranteed to
+ `throw' or an error), `unwind-protect' is *not* guaranteed to
evaluate the rest of them. If the failure of one of the
CLEANUP-FORMS has the potential to cause trouble, then protect it
with another `unwind-protect' around that form.
The number of currently active `unwind-protect' forms counts,
together with the number of local variable bindings, against the
- limit `max-specpdl-size' (*note Local Variables::).
+ limit `max-specpdl-size' (*note Local Variables::.).
For example, here we make an invisible buffer for temporary use, and
make sure to kill it before finishing:
buffer becomes current in time to kill it.)
Here is an actual example taken from the file `ftp.el'. It creates
-a process (*note Processes::) to try to establish a connection to a
+a process (*note Processes::.) to try to establish a connection to a
remote machine. As the function `ftp-login' is highly susceptible to
numerous problems that the writer of the function cannot anticipate, it
is protected with a form that guarantees deletion of the process in the
one) of the variable. When the life span of the local value is over,
the previous value is restored. In the mean time, we say that the
previous value is "shadowed" and "not visible". Both global and local
-values may be shadowed (*note Scope::).
+values may be shadowed (*note Scope::.).
If you set a variable (such as with `setq') while it is local, this
replaces the local value; it does not alter the global value, or
The special forms `let' and `let*' exist to create local bindings.
- - Special Form: let (bindings...) forms...
+ - Special Form: let (BINDINGS...) FORMS...
This special form binds variables according to BINDINGS and then
evaluates all of the FORMS in textual order. The `let'-form
returns the value of the last form in FORMS.
evaluating VALUE-FORM. If VALUE-FORM is omitted, `nil' is used.
All of the VALUE-FORMs in BINDINGS are evaluated in the order they
- appear and _before_ any of the symbols are bound. Here is an
+ appear and *before* any of the symbols are bound. Here is an
example of this: `Z' is bound to the old value of `Y', which is 2,
not the new value, 1.
(list Y Z))
=> (1 2)
- - Special Form: let* (bindings...) forms...
+ - Special Form: let* (BINDINGS...) FORMS...
This special form is like `let', but it binds each variable right
after computing its local value, before computing the local value
for the next variable. Therefore, an expression in BINDINGS can
Here is a complete list of the other facilities that create local
bindings:
- * Function calls (*note Functions::).
+ * Function calls (*note Functions::.).
- * Macro calls (*note Macros::).
+ * Macro calls (*note Macros::.).
- * `condition-case' (*note Errors::).
+ * `condition-case' (*note Errors::.).
Variables can also have buffer-local bindings (*note Buffer-Local
-Variables::). These kinds of bindings work somewhat like ordinary local
-bindings, but they are localized depending on "where" you are in Emacs,
-rather than localized in time.
+Variables::.). These kinds of bindings work somewhat like ordinary
+local bindings, but they are localized depending on "where" you are in
+Emacs, rather than localized in time.
- Variable: max-specpdl-size
This variable defines the limit on the total number of local
variable bindings and `unwind-protect' cleanups (*note Nonlocal
- Exits::) that are allowed before signaling an error (with data
+ Exits::.) that are allowed before signaling an error (with data
`"Variable binding depth exceeds max-specpdl-size"').
This limit, with the associated error when it is exceeded, is one
Note that a value of `nil' is not the same as void. The symbol
`nil' is a Lisp object and can be the value of a variable just as any
-other object can be; but it is _a value_. A void variable does not
+other object can be; but it is *a value*. A void variable does not
have any value.
After you have given a variable a value, you can make it void once
more using `makunbound'.
- - Function: makunbound symbol
+ - Function: makunbound SYMBOL
This function makes the current binding of SYMBOL void.
Subsequent attempts to use this symbol's value as a variable will
signal the error `void-variable', unless or until you set it again.
(makunbound 'x) ; Void the local binding.
x)
error--> Symbol's value as variable is void: x
+
x ; The global binding is unchanged.
=> 1
(makunbound 'x) ; Void the innermost-local binding.
x)) ; And refer: it's void.
error--> Symbol's value as variable is void: x
-
+
(let ((x 2))
(let ((x 3))
(makunbound 'x)) ; Void inner binding, then remove it.
You can use the function `boundp' to test whether a variable is
currently void.
- - Function: boundp variable
+ - Function: boundp VARIABLE
`boundp' returns `t' if VARIABLE (a symbol) is not void; more
precisely, if its current binding is not void. It returns `nil'
otherwise.
(boundp 'abracadabra) ; Starts out void.
=> nil
+
(let ((abracadabra 5)) ; Locally bind it.
(boundp 'abracadabra))
=> t
+
(boundp 'abracadabra) ; Still globally void.
=> nil
+
(setq abracadabra 5) ; Make it globally nonvoid.
=> 5
+
(boundp 'abracadabra)
=> t
`defvar'.
In XEmacs Lisp, definitions serve three purposes. First, they inform
-people who read the code that certain symbols are _intended_ to be used
+people who read the code that certain symbols are *intended* to be used
a certain way (as variables). Second, they inform the Lisp system of
these things, supplying a value and documentation. Third, they provide
information to utilities such as `etags' and `make-docfile', which
and override the default values given in the definitions. For this
reason, user options must be defined with `defvar'.
- - Special Form: defvar symbol [value [doc-string]]
+ - Special Form: defvar SYMBOL [VALUE [DOC-STRING]]
This special form defines SYMBOL as a value and initializes it.
The definition informs a person reading your code that SYMBOL is
used as a variable that programs are likely to set or change. It
for the variable. (This opportunity to specify documentation is
one of the main benefits of defining the variable.) The
documentation is stored in the symbol's `variable-documentation'
- property. The XEmacs help functions (*note Documentation::) look
+ property. The XEmacs help functions (*note Documentation::.) look
for this property.
If the first character of DOC-STRING is `*', it means that this
The `defvar' form returns SYMBOL, but it is normally used at top
level in a file where its value does not matter.
- - Special Form: defconst symbol [value [doc-string]]
+ - Special Form: defconst SYMBOL [VALUE [DOC-STRING]]
This special form defines SYMBOL as a value and initializes it.
It informs a person reading your code that SYMBOL has a global
value, established here, that will not normally be changed or
pi
=> 3
- - Function: user-variable-p variable
+ - Function: user-variable-p VARIABLE
This function returns `t' if VARIABLE is a user option--a variable
intended to be set by the user for customization--and `nil'
otherwise. (Variables other than user options exist for the
=========================
The usual way to reference a variable is to write the symbol which
-names it (*note Symbol Forms::). This requires you to specify the
+names it (*note Symbol Forms::.). This requires you to specify the
variable name when you write the program. Usually that is exactly what
you want to do. Occasionally you need to choose at run time which
variable to reference; then you can use `symbol-value'.
- - Function: symbol-value symbol
+ - Function: symbol-value SYMBOL
This function returns the value of SYMBOL. This is the value in
the innermost local binding of the symbol, or its global value if
it has no local bindings.
form `setq'. When you need to compute the choice of variable at run
time, use the function `set'.
- - Special Form: setq [symbol form]...
+ - Special Form: setq [SYMBOL FORM]...
This special form is the most common method of changing a
variable's value. Each SYMBOL is given a new value, which is the
result of evaluating the corresponding FORM. The most-local
y (1+ x)) ; the value of `y' is computed.
=> 11
- - Function: set symbol value
+ - Function: set SYMBOL VALUE
This function sets SYMBOL's value to VALUE, then returns VALUE.
Since `set' is a function, the expression written for SYMBOL is
evaluated to obtain the symbol to set.
One other function for setting a variable is designed to add an
element to a list if it is not already present in the list.
- - Function: add-to-list symbol element
+ - Function: add-to-list SYMBOL ELEMENT
This function sets the variable SYMBOL by consing ELEMENT onto the
old value, if ELEMENT is not already a member of that value. It
returns the resulting list, whether updated or not. The value of
the others.
Local bindings in XEmacs Lisp have "indefinite scope" and "dynamic
-extent". "Scope" refers to _where_ textually in the source code the
+extent". "Scope" refers to *where* textually in the source code the
binding can be accessed. Indefinite scope means that any part of the
program can potentially access the variable binding. "Extent" refers
-to _when_, as the program is executing, the binding exists. Dynamic
+to *when*, as the program is executing, the binding exists. Dynamic
extent means that the binding lasts as long as the activation of the
construct that established it.
(user))
* If we define `foo' as follows and call `binder', then the binding
- made in `binder' _will not_ be seen in `user':
+ made in `binder' *will not* be seen in `user':
(defun foo (x)
(user))
* Default Value:: The default value is seen in buffers
that don't have their own local values.
+\1f
+File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables
+
+Introduction to Buffer-Local Variables
+--------------------------------------
+
+ A buffer-local variable has a buffer-local binding associated with a
+particular buffer. The binding is in effect when that buffer is
+current; otherwise, it is not in effect. If you set the variable while
+a buffer-local binding is in effect, the new value goes in that binding,
+so the global binding is unchanged; this means that the change is
+visible in that buffer alone.
+
+ A variable may have buffer-local bindings in some buffers but not in
+others. The global binding is shared by all the buffers that don't have
+their own bindings. Thus, if you set the variable in a buffer that does
+not have a buffer-local binding for it, the new value is visible in all
+buffers except those with buffer-local bindings. (Here we are assuming
+that there are no `let'-style local bindings to complicate the issue.)
+
+ The most common use of buffer-local bindings is for major modes to
+change variables that control the behavior of commands. For example, C
+mode and Lisp mode both set the variable `paragraph-start' to specify
+that only blank lines separate paragraphs. They do this by making the
+variable buffer-local in the buffer that is being put into C mode or
+Lisp mode, and then setting it to the new value for that mode.
+
+ The usual way to make a buffer-local binding is with
+`make-local-variable', which is what major mode commands use. This
+affects just the current buffer; all other buffers (including those yet
+to be created) continue to share the global value.
+
+ A more powerful operation is to mark the variable as "automatically
+buffer-local" by calling `make-variable-buffer-local'. You can think
+of this as making the variable local in all buffers, even those yet to
+be created. More precisely, the effect is that setting the variable
+automatically makes the variable local to the current buffer if it is
+not already so. All buffers start out by sharing the global value of
+the variable as usual, but any `setq' creates a buffer-local binding
+for the current buffer. The new value is stored in the buffer-local
+binding, leaving the (default) global binding untouched. The global
+value can no longer be changed with `setq'; you need to use
+`setq-default' to do that.
+
+ Local variables in a file you edit are also represented by
+buffer-local bindings for the buffer that holds the file within XEmacs.
+*Note Auto Major Mode::.
+
+\1f
+File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables
+
+Creating and Deleting Buffer-Local Bindings
+-------------------------------------------
+
+ - Command: make-local-variable VARIABLE
+ This function creates a buffer-local binding in the current buffer
+ for VARIABLE (a symbol). Other buffers are not affected. The
+ value returned is VARIABLE.
+
+ The buffer-local value of VARIABLE starts out as the same value
+ VARIABLE previously had. If VARIABLE was void, it remains void.
+
+ ;; In buffer `b1':
+ (setq foo 5) ; Affects all buffers.
+ => 5
+ (make-local-variable 'foo) ; Now it is local in `b1'.
+ => foo
+ foo ; That did not change
+ => 5 ; the value.
+ (setq foo 6) ; Change the value
+ => 6 ; in `b1'.
+ foo
+ => 6
+
+ ;; In buffer `b2', the value hasn't changed.
+ (save-excursion
+ (set-buffer "b2")
+ foo)
+ => 5
+
+ Making a variable buffer-local within a `let'-binding for that
+ variable does not work. This is because `let' does not distinguish
+ between different kinds of bindings; it knows only which variable
+ the binding was made for.
+
+ *Please note:* do not use `make-local-variable' for a hook
+ variable. Instead, use `make-local-hook'. *Note Hooks::.
+
+ - Command: make-variable-buffer-local VARIABLE
+ This function marks VARIABLE (a symbol) automatically
+ buffer-local, so that any subsequent attempt to set it will make it
+ local to the current buffer at the time.
+
+ The value returned is VARIABLE.
+
+ - Function: local-variable-p VARIABLE &optional BUFFER
+ This returns `t' if VARIABLE is buffer-local in buffer BUFFER
+ (which defaults to the current buffer); otherwise, `nil'.
+
+ - Function: buffer-local-variables &optional BUFFER
+ This function returns a list describing the buffer-local variables
+ in buffer BUFFER. It returns an association list (*note
+ Association Lists::.) in which each association contains one
+ buffer-local variable and its value. When a buffer-local variable
+ is void in BUFFER, then it appears directly in the resulting list.
+ If BUFFER is omitted, the current buffer is used.
+
+ (make-local-variable 'foobar)
+ (makunbound 'foobar)
+ (make-local-variable 'bind-me)
+ (setq bind-me 69)
+ (setq lcl (buffer-local-variables))
+ ;; First, built-in variables local in all buffers:
+ => ((mark-active . nil)
+ (buffer-undo-list nil)
+ (mode-name . "Fundamental")
+ ...
+ ;; Next, non-built-in local variables.
+ ;; This one is local and void:
+ foobar
+ ;; This one is local and nonvoid:
+ (bind-me . 69))
+
+ Note that storing new values into the CDRs of cons cells in this
+ list does *not* change the local values of the variables.
+
+ - Command: kill-local-variable VARIABLE
+ This function deletes the buffer-local binding (if any) for
+ VARIABLE (a symbol) in the current buffer. As a result, the
+ global (default) binding of VARIABLE becomes visible in this
+ buffer. Usually this results in a change in the value of
+ VARIABLE, since the global value is usually different from the
+ buffer-local value just eliminated.
+
+ If you kill the local binding of a variable that automatically
+ becomes local when set, this makes the global value visible in the
+ current buffer. However, if you set the variable again, that will
+ once again create a local binding for it.
+
+ `kill-local-variable' returns VARIABLE.
+
+ This function is a command because it is sometimes useful to kill
+ one buffer-local variable interactively, just as it is useful to
+ create buffer-local variables interactively.
+
+ - Function: kill-all-local-variables
+ This function eliminates all the buffer-local variable bindings of
+ the current buffer except for variables marked as "permanent". As
+ a result, the buffer will see the default values of most variables.
+
+ This function also resets certain other information pertaining to
+ the buffer: it sets the local keymap to `nil', the syntax table to
+ the value of `standard-syntax-table', and the abbrev table to the
+ value of `fundamental-mode-abbrev-table'.
+
+ Every major mode command begins by calling this function, which
+ has the effect of switching to Fundamental mode and erasing most
+ of the effects of the previous major mode. To ensure that this
+ does its job, the variables that major modes set should not be
+ marked permanent.
+
+ `kill-all-local-variables' returns `nil'.
+
+ A local variable is "permanent" if the variable name (a symbol) has a
+`permanent-local' property that is non-`nil'. Permanent locals are
+appropriate for data pertaining to where the file came from or how to
+save it, rather than with how to edit the contents.
+
+\1f
+File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables
+
+The Default Value of a Buffer-Local Variable
+--------------------------------------------
+
+ The global value of a variable with buffer-local bindings is also
+called the "default" value, because it is the value that is in effect
+except when specifically overridden.
+
+ The functions `default-value' and `setq-default' access and change a
+variable's default value regardless of whether the current buffer has a
+buffer-local binding. For example, you could use `setq-default' to
+change the default setting of `paragraph-start' for most buffers; and
+this would work even when you are in a C or Lisp mode buffer that has a
+buffer-local value for this variable.
+
+ The special forms `defvar' and `defconst' also set the default value
+(if they set the variable at all), rather than any local value.
+
+ - Function: default-value SYMBOL
+ This function returns SYMBOL's default value. This is the value
+ that is seen in buffers that do not have their own values for this
+ variable. If SYMBOL is not buffer-local, this is equivalent to
+ `symbol-value' (*note Accessing Variables::.).
+
+ - Function: default-boundp SYMBOL
+ The function `default-boundp' tells you whether SYMBOL's default
+ value is nonvoid. If `(default-boundp 'foo)' returns `nil', then
+ `(default-value 'foo)' would get an error.
+
+ `default-boundp' is to `default-value' as `boundp' is to
+ `symbol-value'.
+
+ - Special Form: setq-default SYMBOL VALUE
+ This sets the default value of SYMBOL to VALUE. It does not
+ evaluate SYMBOL, but does evaluate VALUE. The value of the
+ `setq-default' form is VALUE.
+
+ If a SYMBOL is not buffer-local for the current buffer, and is not
+ marked automatically buffer-local, `setq-default' has the same
+ effect as `setq'. If SYMBOL is buffer-local for the current
+ buffer, then this changes the value that other buffers will see
+ (as long as they don't have a buffer-local value), but not the
+ value that the current buffer sees.
+
+ ;; In buffer `foo':
+ (make-local-variable 'local)
+ => local
+ (setq local 'value-in-foo)
+ => value-in-foo
+ (setq-default local 'new-default)
+ => new-default
+ local
+ => value-in-foo
+ (default-value 'local)
+ => new-default
+
+ ;; In (the new) buffer `bar':
+ local
+ => new-default
+ (default-value 'local)
+ => new-default
+ (setq local 'another-default)
+ => another-default
+ (default-value 'local)
+ => another-default
+
+ ;; Back in buffer `foo':
+ local
+ => value-in-foo
+ (default-value 'local)
+ => another-default
+
+ - Function: set-default SYMBOL VALUE
+ This function is like `setq-default', except that SYMBOL is
+ evaluated.
+
+ (set-default (car '(a b c)) 23)
+ => 23
+ (default-value 'a)
+ => 23
+
projects / chise / xemacs-chise.git.1 / blobdiff