"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/lispref/variables.texi" between
xemacs-21.4.22.tar.gz and xemacs-21.4.24.tar.bz2

About: XEmacs (an alternative to GNU Emacs) is a highly customizable open source text editor and application development system (current version).

variables.texi  (xemacs-21.4.22):variables.texi  (xemacs-21.4.24.tar.bz2)
@c -*-texinfo-*- @c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual. @c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions. @c See the file lispref.texi for copying conditions.
@setfilename ../../info/variables.info @setfilename ../../info/variables.info
@node Variables, Functions and Commands, Control Structures, Top @node Variables, Functions and Commands, Control Structures, Top
@chapter Variables @chapter Variables
@cindex variable @cindex variable
A @dfn{variable} is a name used in a program to stand for a value. A @dfn{variable} is a name used in a program to stand for a value.
Nearly all programming languages have variables of some sort. In the Nearly all programming languages have variables of some sort. In the
text of a Lisp program, variables are written using the syntax for text of a Lisp program, variables are written using the syntax for
symbols. symbols.
In Lisp, unlike most programming languages, programs are represented In Lisp, unlike most programming languages, programs are represented
primarily as Lisp objects and only secondarily as text. The Lisp primarily as Lisp objects and only secondarily as text. The Lisp
skipping to change at line 42 skipping to change at line 43
* Void Variables:: Symbols that lack values. * Void Variables:: Symbols that lack values.
* Defining Variables:: A definition says a symbol is used as a variable. * Defining Variables:: A definition says a symbol is used as a variable.
* Accessing Variables:: Examining values of variables whose names * Accessing Variables:: Examining values of variables whose names
are known only at run time. are known only at run time.
* Setting Variables:: Storing new values in variables. * Setting Variables:: Storing new values in variables.
* Variable Scoping:: How Lisp chooses among local and global values. * Variable Scoping:: How Lisp chooses among local and global values.
* Buffer-Local Variables:: Variable values in effect only in one buffer. * Buffer-Local Variables:: Variable values in effect only in one buffer.
* Variable Aliases:: Making one variable point to another. * Variable Aliases:: Making one variable point to another.
@end menu @end menu
@node Global Variables @node Global Variables, Constant Variables, Variables, Variables
@section Global Variables @section Global Variables
@cindex global variable @cindex global variable
The simplest way to use a variable is @dfn{globally}. This means that The simplest way to use a variable is @dfn{globally}. This means that
the variable has just one value at a time, and this value is in effect the variable has just one value at a time, and this value is in effect
(at least for the moment) throughout the Lisp system. The value remains (at least for the moment) throughout the Lisp system. The value remains
in effect until you specify a new one. When a new value replaces the in effect until you specify a new one. When a new value replaces the
old one, no trace of the old value remains in the variable. old one, no trace of the old value remains in the variable.
You specify a value for a symbol with @code{setq}. For example, You specify a value for a symbol with @code{setq}. For example,
skipping to change at line 92 skipping to change at line 93
@group @group
(setq x 4) (setq x 4)
@result{} 4 @result{} 4
@end group @end group
@group @group
x x
@result{} 4 @result{} 4
@end group @end group
@end example @end example
@node Constant Variables @node Constant Variables, Local Variables, Global Variables, Variables
@section Variables That Never Change @section Variables That Never Change
@vindex nil @vindex nil
@vindex t @vindex t
@kindex setting-constant @kindex setting-constant
In XEmacs Lisp, some symbols always evaluate to themselves: the two In XEmacs Lisp, some symbols always evaluate to themselves: the two
special symbols @code{nil} and @code{t}, as well as @dfn{keyword special symbols @code{nil} and @code{t}, as well as @dfn{keyword
symbols}, that is, symbols whose name begins with the character symbols}, that is, symbols whose name begins with the character
@samp{@code{:}}. These symbols cannot be rebound, nor can their value @samp{@code{:}}. These symbols cannot be rebound, nor can their value
cells be changed. An attempt to change the value of @code{nil} or cells be changed. An attempt to change the value of @code{nil} or
skipping to change at line 116 skipping to change at line 117
@group @group
nil @equiv{} 'nil nil @equiv{} 'nil
@result{} nil @result{} nil
@end group @end group
@group @group
(setq nil 500) (setq nil 500)
@error{} Attempt to set constant symbol: nil @error{} Attempt to set constant symbol: nil
@end group @end group
@end example @end example
@node Local Variables @node Local Variables, Void Variables, Constant Variables, Variables
@section Local Variables @section Local Variables
@cindex binding local variables @cindex binding local variables
@cindex local variables @cindex local variables
@cindex local binding @cindex local binding
@cindex global binding @cindex global binding
Global variables have values that last until explicitly superseded Global variables have values that last until explicitly superseded
with new values. Sometimes it is useful to create variable values that with new values. Sometimes it is useful to create variable values that
exist temporarily---only while within a certain part of the program. exist temporarily---only while within a certain part of the program.
These values are called @dfn{local}, and the variables so used are These values are called @dfn{local}, and the variables so used are
skipping to change at line 260 skipping to change at line 261
This limit, with the associated error when it is exceeded, is one way This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function. that Lisp avoids infinite recursion on an ill-defined function.
The default value is 3000. The default value is 3000.
@code{max-lisp-eval-depth} provides another limit on depth of nesting. @code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Eval}. @xref{Eval}.
@end defvar @end defvar
@node Void Variables @node Void Variables, Defining Variables, Local Variables, Variables
@section When a Variable is ``Void'' @section When a Variable is ``Void''
@kindex void-variable @kindex void-variable
@cindex void variable @cindex void variable
If you have never given a symbol any value as a global variable, we If you have never given a symbol any value as a global variable, we
say that that symbol's global value is @dfn{void}. In other words, the say that that symbol's global value is @dfn{void}. In other words, the
symbol's value cell does not have any Lisp object in it. If you try to symbol's value cell does not have any Lisp object in it. If you try to
evaluate the symbol, you get a @code{void-variable} error rather than evaluate the symbol, you get a @code{void-variable} error rather than
a value. a value.
skipping to change at line 374 skipping to change at line 375
(setq abracadabra 5) ; @r{Make it globally nonvoid.} (setq abracadabra 5) ; @r{Make it globally nonvoid.}
@result{} 5 @result{} 5
@end group @end group
@group @group
(boundp 'abracadabra) (boundp 'abracadabra)
@result{} t @result{} t
@end group @end group
@end smallexample @end smallexample
@end defun @end defun
@node Defining Variables @node Defining Variables, Accessing Variables, Void Variables, Variables
@section Defining Global Variables @section Defining Global Variables
@cindex variable definition @cindex variable definition
You may announce your intention to use a symbol as a global variable You may announce your intention to use a symbol as a global variable
with a @dfn{variable definition}: a special form, either @code{defconst} with a @dfn{variable definition}: a special form, either @code{defconst}
or @code{defvar}. or @code{defvar}.
In XEmacs Lisp, definitions serve three purposes. First, they inform In XEmacs Lisp, definitions serve three purposes. First, they inform
people who read the code that certain symbols are @emph{intended} to be people who read the code that certain symbols are @emph{intended} to be
used a certain way (as variables). Second, they inform the Lisp system used a certain way (as variables). Second, they inform the Lisp system
skipping to change at line 560 skipping to change at line 561
new value for the variable. The property's value is used as if it were new value for the variable. The property's value is used as if it were
the argument to @code{interactive}. the argument to @code{interactive}.
@strong{Warning:} If the @code{defconst} and @code{defvar} special @strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the forms are used while the variable has a local binding, they set the
local binding's value; the global binding is not changed. This is not local binding's value; the global binding is not changed. This is not
what we really want. To prevent it, use these special forms at top what we really want. To prevent it, use these special forms at top
level in a file, where normally no local binding is in effect, and make level in a file, where normally no local binding is in effect, and make
sure to load the file before making a local binding for the variable. sure to load the file before making a local binding for the variable.
@node Accessing Variables @node Accessing Variables, Setting Variables, Defining Variables, Variables
@section Accessing Variable Values @section Accessing Variable Values
The usual way to reference a variable is to write the symbol which The usual way to reference a variable is to write the symbol which
names it (@pxref{Symbol Forms}). This requires you to specify the names it (@pxref{Symbol Forms}). This requires you to specify the
variable name when you write the program. Usually that is exactly what 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 you want to do. Occasionally you need to choose at run time which
variable to reference; then you can use @code{symbol-value}. variable to reference; then you can use @code{symbol-value}.
@defun symbol-value symbol @defun symbol-value symbol
This function returns the value of @var{symbol}. This is the value in This function returns the value of @var{symbol}. This is the value in
skipping to change at line 611 skipping to change at line 612
@group @group
(symbol-value 'abracadabra) (symbol-value 'abracadabra)
@result{} 5 @result{} 5
@end group @end group
@end example @end example
A @code{void-variable} error is signaled if @var{symbol} has neither a A @code{void-variable} error is signaled if @var{symbol} has neither a
local binding nor a global value. local binding nor a global value.
@end defun @end defun
@node Setting Variables @node Setting Variables, Variable Scoping, Accessing Variables, Variables
@section How to Alter a Variable Value @section How to Alter a Variable Value
The usual way to change the value of a variable is with the special The usual way to change the value of a variable is with the special
form @code{setq}. When you need to compute the choice of variable at form @code{setq}. When you need to compute the choice of variable at
run time, use the function @code{set}. run time, use the function @code{set}.
@defspec setq [symbol form]@dots{} @defspec setq [symbol form]@dots{}
This special form is the most common method of changing a variable's This special form is the most common method of changing a variable's
value. Each @var{symbol} is given a new value, which is the result of value. Each @var{symbol} is given a new value, which is the result of
evaluating the corresponding @var{form}. The most-local existing evaluating the corresponding @var{form}. The most-local existing
skipping to change at line 763 skipping to change at line 764
@end defun @end defun
An equivalent expression for @code{(add-to-list '@var{var} An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this: @var{value})} is this:
@example @example
(or (member @var{value} @var{var}) (or (member @var{value} @var{var})
(setq @var{var} (cons @var{value} @var{var}))) (setq @var{var} (cons @var{value} @var{var})))
@end example @end example
@node Variable Scoping @node Variable Scoping, Buffer-Local Variables, Setting Variables, Variables
@section Scoping Rules for Variable Bindings @section Scoping Rules for Variable Bindings
A given symbol @code{foo} may have several local variable bindings, A given symbol @code{foo} may have several local variable bindings,
established at different places in the Lisp program, as well as a global established at different places in the Lisp program, as well as a global
binding. The most recently established binding takes precedence over binding. The most recently established binding takes precedence over
the others. the others.
@cindex scope @cindex scope
@cindex extent @cindex extent
@cindex dynamic scoping @cindex dynamic scoping
skipping to change at line 801 skipping to change at line 802
@end quotation @end quotation
@menu @menu
* Scope:: Scope means where in the program a value is visible. * Scope:: Scope means where in the program a value is visible.
Comparison with other languages. Comparison with other languages.
* Extent:: Extent means how long in time a value exists. * Extent:: Extent means how long in time a value exists.
* Impl of Scope:: Two ways to implement dynamic scoping. * Impl of Scope:: Two ways to implement dynamic scoping.
* Using Scoping:: How to use dynamic scoping carefully and avoid problems. * Using Scoping:: How to use dynamic scoping carefully and avoid problems.
@end menu @end menu
@node Scope @node Scope, Extent, Variable Scoping, Variable Scoping
@subsection Scope @subsection Scope
XEmacs Lisp uses @dfn{indefinite scope} for local variable bindings. XEmacs Lisp uses @dfn{indefinite scope} for local variable bindings.
This means that any function anywhere in the program text might access a This means that any function anywhere in the program text might access a
given binding of a variable. Consider the following function given binding of a variable. Consider the following function
definitions: definitions:
@example @example
@group @group
(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} (defun binder (x) ; @r{@code{x} is bound in @code{binder}.}
skipping to change at line 861 skipping to change at line 862
(user)) (user))
@end example @end example
@noindent @noindent
Here, when @code{foo} is called by @code{binder}, it binds @code{x}. Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
(The binding in @code{foo} is said to @dfn{shadow} the one made in (The binding in @code{foo} is said to @dfn{shadow} the one made in
@code{binder}.) Therefore, @code{user} will access the @code{x} bound @code{binder}.) Therefore, @code{user} will access the @code{x} bound
by @code{foo} instead of the one bound by @code{binder}. by @code{foo} instead of the one bound by @code{binder}.
@end itemize @end itemize
@node Extent @node Extent, Impl of Scope, Scope, Variable Scoping
@subsection Extent @subsection Extent
@dfn{Extent} refers to the time during program execution that a @dfn{Extent} refers to the time during program execution that a
variable name is valid. In XEmacs Lisp, a variable is valid only while variable name is valid. In XEmacs Lisp, a variable is valid only while
the form that bound it is executing. This is called @dfn{dynamic the form that bound it is executing. This is called @dfn{dynamic
extent}. ``Local'' or ``automatic'' variables in most languages, extent}. ``Local'' or ``automatic'' variables in most languages,
including C and Pascal, have dynamic extent. including C and Pascal, have dynamic extent.
One alternative to dynamic extent is @dfn{indefinite extent}. This One alternative to dynamic extent is @dfn{indefinite extent}. This
means that a variable binding can live on past the exit from the form means that a variable binding can live on past the exit from the form
skipping to change at line 897 skipping to change at line 898
@result{} (lambda (m) (+ n m)) @result{} (lambda (m) (+ n m))
(add2 4) ; @r{Try to add 2 to 4.} (add2 4) ; @r{Try to add 2 to 4.}
@error{} Symbol's value as variable is void: n @error{} Symbol's value as variable is void: n
@end example @end example
@cindex closures not available @cindex closures not available
Some Lisp dialects have ``closures'', objects that are like functions Some Lisp dialects have ``closures'', objects that are like functions
but record additional variable bindings. XEmacs Lisp does not have but record additional variable bindings. XEmacs Lisp does not have
closures. closures.
@node Impl of Scope @node Impl of Scope, Using Scoping, Extent, Variable Scoping
@subsection Implementation of Dynamic Scoping @subsection Implementation of Dynamic Scoping
@cindex deep binding @cindex deep binding
A simple sample implementation (which is not how XEmacs Lisp actually A simple sample implementation (which is not how XEmacs Lisp actually
works) may help you understand dynamic binding. This technique is works) may help you understand dynamic binding. This technique is
called @dfn{deep binding} and was used in early Lisp systems. called @dfn{deep binding} and was used in early Lisp systems.
Suppose there is a stack of bindings: variable-value pairs. At entry Suppose there is a stack of bindings: variable-value pairs. At entry
to a function or to a @code{let} form, we can push bindings on the stack to a function or to a @code{let} form, we can push bindings on the stack
for the arguments or local variables created there. We can pop those for the arguments or local variables created there. We can pop those
skipping to change at line 937 skipping to change at line 938
In shallow binding, setting the variable works by storing a value in In shallow binding, setting the variable works by storing a value in
the value cell. Creating a new binding works by pushing the old value the value cell. Creating a new binding works by pushing the old value
(belonging to a previous binding) on a stack, and storing the local value (belonging to a previous binding) on a stack, and storing the local value
in the value cell. Eliminating a binding works by popping the old value in the value cell. Eliminating a binding works by popping the old value
off the stack, into the value cell. off the stack, into the value cell.
We use shallow binding because it has the same results as deep We use shallow binding because it has the same results as deep
binding, but runs faster, since there is never a need to search for a binding, but runs faster, since there is never a need to search for a
binding. binding.
@node Using Scoping @node Using Scoping, , Impl of Scope, Variable Scoping
@subsection Proper Use of Dynamic Scoping @subsection Proper Use of Dynamic Scoping
Binding a variable in one function and using it in another is a Binding a variable in one function and using it in another is a
powerful technique, but if used without restraint, it can make programs powerful technique, but if used without restraint, it can make programs
hard to understand. There are two clean ways to use this technique: hard to understand. There are two clean ways to use this technique:
@itemize @bullet @itemize @bullet
@item @item
Use or bind the variable only in a few related functions, written close Use or bind the variable only in a few related functions, written close
together in one file. Such a variable is used for communication within together in one file. Such a variable is used for communication within
skipping to change at line 972 skipping to change at line 973
Then you can bind the variable in other programs, knowing reliably what Then you can bind the variable in other programs, knowing reliably what
the effect will be. the effect will be.
@end itemize @end itemize
In either case, you should define the variable with @code{defvar}. In either case, you should define the variable with @code{defvar}.
This helps other people understand your program by telling them to look This helps other people understand your program by telling them to look
for inter-function usage. It also avoids a warning from the byte for inter-function usage. It also avoids a warning from the byte
compiler. Choose the variable's name to avoid name conflicts---don't compiler. Choose the variable's name to avoid name conflicts---don't
use short names like @code{x}. use short names like @code{x}.
@node Buffer-Local Variables @node Buffer-Local Variables, Variable Aliases, Variable Scoping, Variables
@section Buffer-Local Variables @section Buffer-Local Variables
@cindex variables, buffer-local @cindex variables, buffer-local
@cindex buffer-local variables @cindex buffer-local variables
Global and local variable bindings are found in most programming Global and local variable bindings are found in most programming
languages in one form or another. XEmacs also supports another, unusual languages in one form or another. XEmacs also supports another, unusual
kind of variable binding: @dfn{buffer-local} bindings, which apply only kind of variable binding: @dfn{buffer-local} bindings, which apply only
to one buffer. XEmacs Lisp is meant for programming editing commands, to one buffer. XEmacs Lisp is meant for programming editing commands,
and having different values for a variable in different buffers is an and having different values for a variable in different buffers is an
important customization method. important customization method.
@menu @menu
* Intro to Buffer-Local:: Introduction and concepts. * Intro to Buffer-Local:: Introduction and concepts.
* Creating Buffer-Local:: Creating and destroying buffer-local bindings. * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
* Default Value:: The default value is seen in buffers * Default Value:: The default value is seen in buffers
that don't have their own local values. that don't have their own local values.
@end menu @end menu
@node Intro to Buffer-Local @node Intro to Buffer-Local, Creating Buffer-Local, Buffer-Local Variables, Buff er-Local Variables
@subsection Introduction to Buffer-Local Variables @subsection Introduction to Buffer-Local Variables
A buffer-local variable has a buffer-local binding associated with a A buffer-local variable has a buffer-local binding associated with a
particular buffer. The binding is in effect when that buffer is particular buffer. The binding is in effect when that buffer is
current; otherwise, it is not in effect. If you set the variable while 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, 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 so the global binding is unchanged; this means that the change is
visible in that buffer alone. visible in that buffer alone.
A variable may have buffer-local bindings in some buffers but not in A variable may have buffer-local bindings in some buffers but not in
skipping to change at line 1042 skipping to change at line 1043
that. that.
@ignore @ignore
Section about not changing buffers during let bindings. Mly fixed Section about not changing buffers during let bindings. Mly fixed
this for XEmacs. this for XEmacs.
@end ignore @end ignore
Local variables in a file you edit are also represented by Local variables in a file you edit are also represented by
buffer-local bindings for the buffer that holds the file within XEmacs. buffer-local bindings for the buffer that holds the file within XEmacs.
@xref{Auto Major Mode}. @xref{Auto Major Mode}.
@node Creating Buffer-Local @node Creating Buffer-Local, Default Value, Intro to Buffer-Local, Buffer-Local Variables
@subsection Creating and Deleting Buffer-Local Bindings @subsection Creating and Deleting Buffer-Local Bindings
@deffn Command make-local-variable variable @deffn Command make-local-variable variable
This function creates a buffer-local binding in the current buffer for This function creates a buffer-local binding in the current buffer for
@var{variable} (a symbol). Other buffers are not affected. The value @var{variable} (a symbol). Other buffers are not affected. The value
returned is @var{variable}. returned is @var{variable}.
@c Emacs 19 feature @c Emacs 19 feature
The buffer-local value of @var{variable} starts out as the same value The buffer-local value of @var{variable} starts out as the same value
@var{variable} previously had. If @var{variable} was void, it remains @var{variable} previously had. If @var{variable} was void, it remains
skipping to change at line 1205 skipping to change at line 1206
@code{kill-all-local-variables} returns @code{nil}. @code{kill-all-local-variables} returns @code{nil}.
@end defun @end defun
@c Emacs 19 feature @c Emacs 19 feature
@cindex permanent local variable @cindex permanent local variable
A local variable is @dfn{permanent} if the variable name (a symbol) has a A local variable is @dfn{permanent} if the variable name (a symbol) has a
@code{permanent-local} property that is non-@code{nil}. Permanent @code{permanent-local} property that is non-@code{nil}. Permanent
locals are appropriate for data pertaining to where the file came from 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. or how to save it, rather than with how to edit the contents.
@node Default Value @node Default Value, , Creating Buffer-Local, Buffer-Local Variables
@subsection The Default Value of a Buffer-Local Variable @subsection The Default Value of a Buffer-Local Variable
@cindex default value @cindex default value
The global value of a variable with buffer-local bindings is also The global value of a variable with buffer-local bindings is also
called the @dfn{default} value, because it is the value that is in called the @dfn{default} value, because it is the value that is in
effect except when specifically overridden. effect except when specifically overridden.
The functions @code{default-value} and @code{setq-default} access and The functions @code{default-value} and @code{setq-default} access and
change a variable's default value regardless of whether the current change a variable's default value regardless of whether the current
buffer has a buffer-local binding. For example, you could use buffer has a buffer-local binding. For example, you could use
skipping to change at line 1322 skipping to change at line 1323
(set-default (car '(a b c)) 23) (set-default (car '(a b c)) 23)
@result{} 23 @result{} 23
@end group @end group
@group @group
(default-value 'a) (default-value 'a)
@result{} 23 @result{} 23
@end group @end group
@end example @end example
@end defun @end defun
@node Variable Aliases @node Variable Aliases, , Buffer-Local Variables, Variables
@section Variable Aliases @section Variable Aliases
@cindex variables, indirect @cindex variables, indirect
@cindex indirect variables @cindex indirect variables
@cindex variable aliases @cindex variable aliases
@cindex aliases, for variables @cindex aliases, for variables
You can define a variable as an @dfn{alias} for another. Any time You can define a variable as an @dfn{alias} for another. Any time
you reference the former variable, the current value of the latter you reference the former variable, the current value of the latter
is returned. Any time you change the value of the former variable, is returned. Any time you change the value of the former variable,
the value of the latter is actually changed. This is useful in the value of the latter is actually changed. This is useful in
 End of changes. 18 change blocks. 
17 lines changed or deleted 18 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)