1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-07-03 16:20:39 +02:00

* Improve doc on variables and definitions.

This commit is contained in:
Neil Jerram 2001-11-19 22:28:58 +00:00
parent d0eeda8563
commit d4e5a409a5
4 changed files with 93 additions and 42 deletions

View file

@ -1,3 +1,14 @@
2001-11-19 Neil Jerram <neil@ossau.uklinux.net>
* scheme-data.texi (Symbol Tables), new-docstrings.texi: Removed
doc for builtin-bindings (no longer exists).
(Variables): Expanded existing description of variables. Removed
doc for builtin-variable (no longer exists).
* scheme-binding.texi (Top Level): New docs for define, scm_define
and scm_c_define. Also clarified point about interchangeability
of define and set!.
2001-11-18 Neil Jerram <neil@ossau.uklinux.net> 2001-11-18 Neil Jerram <neil@ossau.uklinux.net>
* scheme-data.texi (Vectors): Autoupdate docs for * scheme-data.texi (Vectors): Autoupdate docs for

View file

@ -573,11 +573,6 @@ Return the value from @var{obj}'s slot with the name
@var{slot_name}. @var{slot_name}.
@end deffn @end deffn
@deffn {Scheme Procedure} builtin-bindings
Create and return a copy of the global symbol table, removing all
unbound symbols.
@end deffn
@deffn {Scheme Procedure} %tag-body body @deffn {Scheme Procedure} %tag-body body
@deffnx {C Function} scm_sys_tag_body (body) @deffnx {C Function} scm_sys_tag_body (body)
Internal GOOPS magic---don't use this function! Internal GOOPS magic---don't use this function!

View file

@ -20,35 +20,71 @@ and expressions. This is important for modularity and data abstraction.
@node Top Level @node Top Level
@section Top Level Variable Definitions @section Top Level Variable Definitions
@c FIXME::martin: Review me!
@cindex variable definition @cindex variable definition
On the top level of a program (e.g. when not inside of a procedure On the top level of a program (i.e. when not inside the body of a
definition or a @code{let}, @code{let*} or @code{letrec} expression), a procedure definition or a @code{let}, @code{let*} or @code{letrec}
definition of the form expression), a definition of the form
@lisp @lisp
(define a 1) (define a @var{value})
@end lisp @end lisp
@noindent @noindent
defines a variable called @var{a} and sets it to the value 1. When the defines a variable called @code{a} and sets it to the value @var{value}.
variable already was bound with a @code{define} expression, the above
If the variable already exists, because it has already been created by a
previous @code{define} expression with the same name, its value is
simply changed to the new @var{value}. In this case, then, the above
form is completely equivalent to form is completely equivalent to
@lisp @lisp
(set! a 1) (set! a @var{value})
@end lisp @end lisp
@noindent @noindent
that means that @code{define} can be used interchangeably with This equivalence means that @code{define} can be used interchangeably
@code{set!} when at the top level of the REPL or a Scheme source file. with @code{set!} to change the value of variables at the top level of
But note that a @code{set!} is not allowed if the variable was not bound the REPL or a Scheme source file. It is useful during interactive
before. development when reloading a Scheme file that you have modified, because
it allows the @code{define} expressions in that file to work as expected
both the first time that the file is loaded and on subsequent occasions.
Attention: definitions inside local binding constructs (@pxref{Local Note, though, that @code{define} and @code{set!} are not always
Bindings}) act differently (@pxref{Internal Definitions}). equivalent. For example, a @code{set!} is not allowed if the named
variable does not already exist, and the two expressions can behave
differently in the case where there are imported variables visible from
another module.
@deffn {Scheme Syntax} define name value
Create a top level variable named @var{name} with value @var{value}.
If the named variable already exists, just change its value. The return
value of a @code{define} expression is unspecified.
@end deffn
The C API equivalents of @code{define} are @code{scm_define} and
@code{scm_c_define}, which differ from each other in whether the
variable name is specified as a @code{SCM} symbol or as a
null-terminated C string.
@deffn {C Function} scm_define (sym, value)
@deffnx {C Function} scm_c_define (const char *name, value)
C equivalents of @code{define}, with variable name specified either by
@var{sym}, a symbol, or by @var{name}, a null-terminated C string. Both
variants return the new or preexisting variable object.
@end deffn
@code{define} (when it occurs at top level), @code{scm_define} and
@code{scm_c_define} all create or set the value of a variable in the top
level environment of the current module. If there was not already a
variable with the specified name belonging to the current module, but a
similarly named variable from another module was visible through having
been imported, the newly created variable in the current module will
shadow the imported variable, such that the imported variable is no
longer visible.
Attention: Scheme definitions inside local binding constructs
(@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
@node Local Bindings @node Local Bindings

View file

@ -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 (@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
table (with an undefined value) if none is yet present. 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] @deffn {Scheme Procedure} gensym [prefix]
@deffnx {C Function} scm_gensym (prefix) @deffnx {C Function} scm_gensym (prefix)
Create a new symbol with a name constructed from a prefix and 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. otherwise.
@end deffn @end deffn
@node Variables @node Variables
@subsection Variables @subsection Variables
@tpindex 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}.
Variables are objects with two fields. They contain a value and they On its own, a variable object is anonymous. A variable is said to be
can contain a symbol, which is the name of the variable. A variable is @dfn{bound} when it is associated with a name in some way, usually a
said to be bound if it does not contain the object denoting unbound symbol in a module obarray. When this happens, the relationship is
variables in the value slot. mutual: the variable is bound to the name (in that module), and the name
(in that module) is bound to the variable.
Variables do not have a read syntax, they have to be created by calling (That's the theory, anyway. In practice, defined-ness and bound-ness
one of the constructor procedures @code{make-variable} or sometimes get confused, because Lisp and Scheme implementations have
@code{make-undefined-variable} or retrieved by @code{builtin-variable}. 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
@lisp
(define @var{name} @var{value})
@end lisp
@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 First-class variables are especially useful for interacting with the
current module system (@pxref{The Guile module system}). 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 @deffn {Scheme Procedure} make-undefined-variable
@deffnx {C Function} scm_make_undefined_variable () @deffnx {C Function} scm_make_undefined_variable ()
Return a variable that is initially unbound. Return a variable that is initially unbound.