diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2001-11-19 22:28:58 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2001-11-19 22:28:58 +0000 |
commit | d4e5a409a52a703f1e1719b14aa103bf7d6f6bc2 (patch) | |
tree | fa4ab48f67b941df4ecd7e9044b6ab7791ad4f36 | |
parent | d0eeda85631222d80216fb59852ce37ca277989c (diff) | |
download | guile-d4e5a409a52a703f1e1719b14aa103bf7d6f6bc2.tar.gz |
* Improve doc on variables and definitions.
-rw-r--r-- | doc/ref/ChangeLog | 11 | ||||
-rw-r--r-- | doc/ref/new-docstrings.texi | 5 | ||||
-rw-r--r-- | doc/ref/scheme-binding.texi | 66 | ||||
-rwxr-xr-x | doc/ref/scheme-data.texi | 53 |
4 files changed, 93 insertions, 42 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index ed8f871c2..2e2790f10 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -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> * scheme-data.texi (Vectors): Autoupdate docs for diff --git a/doc/ref/new-docstrings.texi b/doc/ref/new-docstrings.texi index 65ea5a620..f9195b694 100644 --- a/doc/ref/new-docstrings.texi +++ b/doc/ref/new-docstrings.texi @@ -573,11 +573,6 @@ Return the value from @var{obj}'s slot with the name @var{slot_name}. @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 @deffnx {C Function} scm_sys_tag_body (body) Internal GOOPS magic---don't use this function! diff --git a/doc/ref/scheme-binding.texi b/doc/ref/scheme-binding.texi index 38f9bae08..5c68bf772 100644 --- a/doc/ref/scheme-binding.texi +++ b/doc/ref/scheme-binding.texi @@ -20,35 +20,71 @@ and expressions. This is important for modularity and data abstraction. @node Top Level @section Top Level Variable Definitions -@c FIXME::martin: Review me! - @cindex variable definition -On the top level of a program (e.g. when not inside of a procedure -definition or a @code{let}, @code{let*} or @code{letrec} expression), a -definition of the form +On the top level of a program (i.e. when not inside the body of a +procedure definition or a @code{let}, @code{let*} or @code{letrec} +expression), a definition of the form @lisp -(define a 1) +(define a @var{value}) @end lisp @noindent -defines a variable called @var{a} and sets it to the value 1. When the -variable already was bound with a @code{define} expression, the above +defines a variable called @code{a} and sets it to the value @var{value}. + +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 @lisp -(set! a 1) +(set! a @var{value}) @end lisp @noindent -that means that @code{define} can be used interchangeably with -@code{set!} when at the top level of the REPL or a Scheme source file. -But note that a @code{set!} is not allowed if the variable was not bound -before. +This equivalence means that @code{define} can be used interchangeably +with @code{set!} to change the value of variables at the top level of +the REPL or a Scheme source file. It is useful during interactive +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. + +Note, though, that @code{define} and @code{set!} are not always +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 -Attention: definitions inside local binding constructs (@pxref{Local -Bindings}) act differently (@pxref{Internal Definitions}). +@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 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. |