summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-data.texi
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2001-11-19 22:28:58 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2001-11-19 22:28:58 +0000
commitd4e5a409a52a703f1e1719b14aa103bf7d6f6bc2 (patch)
treefa4ab48f67b941df4ecd7e9044b6ab7791ad4f36 /doc/ref/scheme-data.texi
parentd0eeda85631222d80216fb59852ce37ca277989c (diff)
downloadguile-d4e5a409a52a703f1e1719b14aa103bf7d6f6bc2.tar.gz
* Improve doc on variables and definitions.
Diffstat (limited to 'doc/ref/scheme-data.texi')
-rwxr-xr-xdoc/ref/scheme-data.texi53
1 files changed, 31 insertions, 22 deletions
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
index 77e9a654c..463233546 100755
--- a/doc/ref/scheme-data.texi
+++ b/doc/ref/scheme-data.texi
@@ -2475,14 +2475,6 @@ Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
table (with an undefined value) if none is yet present.
-@c FIXME::martin: According to NEWS, removed. Remove here too, or
-@c leave for compatibility?
-@c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
-@c @deffn {Scheme Procedure} builtin-bindings
-@c Create and return a copy of the global symbol table, removing all
-@c unbound symbols.
-@c @end deffn
-
@deffn {Scheme Procedure} gensym [prefix]
@deffnx {C Function} scm_gensym (prefix)
Create a new symbol with a name constructed from a prefix and
@@ -2571,30 +2563,47 @@ function returns @code{#t} if the symbol was present and @code{#f}
otherwise.
@end deffn
+
@node Variables
@subsection Variables
@tpindex Variables
-@c FIXME::martin: Review me!
+A variable is a box-like object that can hold any Scheme value. It is
+said to be @dfn{undefined} if its box holds a special Scheme value that
+denotes undefined-ness (which is different from all other Scheme values,
+including for example @code{#f}); otherwise the variable is
+@dfn{defined}.
+
+On its own, a variable object is anonymous. A variable is said to be
+@dfn{bound} when it is associated with a name in some way, usually a
+symbol in a module obarray. When this happens, the relationship is
+mutual: the variable is bound to the name (in that module), and the name
+(in that module) is bound to the variable.
+
+(That's the theory, anyway. In practice, defined-ness and bound-ness
+sometimes get confused, because Lisp and Scheme implementations have
+often conflated --- or deliberately drawn no distinction between --- a
+name that is unbound and a name that is bound to a variable whose value
+is undefined. We will try to be clear about the difference and explain
+any confusion where it is unavoidable.)
+
+Variables do not have a read syntax. Most commonly they are created and
+bound implicitly by @code{define} expressions: a top-level @code{define}
+expression of the form
-Variables are objects with two fields. They contain a value and they
-can contain a symbol, which is the name of the variable. A variable is
-said to be bound if it does not contain the object denoting unbound
-variables in the value slot.
+@lisp
+(define @var{name} @var{value})
+@end lisp
-Variables do not have a read syntax, they have to be created by calling
-one of the constructor procedures @code{make-variable} or
-@code{make-undefined-variable} or retrieved by @code{builtin-variable}.
+@noindent
+creates a variable with initial value @var{value} and binds it to the
+name @var{name} in the current module. But they can also be created
+dynamically by calling one of the constructor procedures
+@code{make-variable} and @code{make-undefined-variable}.
First-class variables are especially useful for interacting with the
current module system (@pxref{The Guile module system}).
-@deffn {Scheme Procedure} builtin-variable name
-Return the built-in variable with the name @var{name}.
-@var{name} must be a symbol (not a string).
-Then use @code{variable-ref} to access its value.
-@end deffn
-
@deffn {Scheme Procedure} make-undefined-variable
@deffnx {C Function} scm_make_undefined_variable ()
Return a variable that is initially unbound.