summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-binding.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/scheme-binding.texi')
-rw-r--r--doc/ref/scheme-binding.texi279
1 files changed, 0 insertions, 279 deletions
diff --git a/doc/ref/scheme-binding.texi b/doc/ref/scheme-binding.texi
deleted file mode 100644
index 23786b3bf..000000000
--- a/doc/ref/scheme-binding.texi
+++ /dev/null
@@ -1,279 +0,0 @@
-@page
-@node Binding Constructs
-@chapter Definitions and Variable Bindings
-
-@c FIXME::martin: Review me!
-
-Scheme supports the definition of variables in different contexts.
-Variables can be defined at the top level, so that they are visible in
-the entire program, and variables can be defined locally to procedures
-and expressions. This is important for modularity and data abstraction.
-
-@menu
-* Top Level:: Top level variable definitions.
-* Local Bindings:: Local variable bindings.
-* Internal Definitions:: Internal definitions.
-* Binding Reflection:: Querying variable bindings.
-@end menu
-
-
-@node Top Level
-@section Top Level Variable Definitions
-
-@cindex variable definition
-
-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 @var{value})
-@end lisp
-
-@noindent
-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 @var{value})
-@end lisp
-
-@noindent
-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
-
-@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
-@section Local Variable Bindings
-
-@c FIXME::martin: Review me!
-
-@cindex local bindings
-@cindex local variables
-
-As opposed to definitions at the top level, which are visible in the
-whole program (or current module, when Guile modules are used), it is
-also possible to define variables which are only visible in a
-well-defined part of the program. Normally, this part of a program
-will be a procedure or a subexpression of a procedure.
-
-With the constructs for local binding (@code{let}, @code{let*} and
-@code{letrec}), the Scheme language has a block structure like most
-other programming languages since the days of @sc{Algol 60}. Readers
-familiar to languages like C or Java should already be used to this
-concept, but the family of @code{let} expressions has a few properties
-which are well worth knowing.
-
-The first local binding construct is @code{let}. The other constructs
-@code{let*} and @code{letrec} are specialized versions for usage where
-using plain @code{let} is a bit inconvenient.
-
-@deffn syntax let bindings body
-@var{bindings} has the form
-
-@lisp
-((@var{variable1} @var{init1}) @dots{})
-@end lisp
-
-that is zero or more two-element lists of a variable and an arbitrary
-expression each. All @var{variable} names must be distinct.
-
-A @code{let} expression is evaluated as follows.
-
-@itemize @bullet
-@item
-All @var{init} expressions are evaluated.
-
-@item
-New storage is allocated for the @var{variables}.
-
-@item
-The values of the @var{init} expressions are stored into the variables.
-
-@item
-The expressions in @var{body} are evaluated in order, and the value of
-the last expression is returned as the value of the @code{let}
-expression.
-
-@item
-The storage for the @var{variables} is freed.
-@end itemize
-
-The @var{init} expressions are not allowed to refer to any of the
-@var{variables}.
-@end deffn
-
-@deffn syntax let* bindings body
-Similar to @code{let}, but the variable bindings are performed
-sequentially, that means that all @var{init} expression are allowed to
-use the variables defined on their left in the binding list.
-
-A @code{let*} expression can always be expressed with nested @code{let}
-expressions.
-
-@lisp
-(let* ((a 1) (b a))
- b)
-@equiv{}
-(let ((a 1))
- (let ((b a))
- b))
-@end lisp
-@end deffn
-
-@deffn syntax letrec bindings body
-Similar to @code{let}, but it is possible to refer to the @var{variable}
-from lambda expression created in any of the @var{inits}. That is,
-procedures created in the @var{init} expression can recursively refer to
-the defined variables.
-
-@lisp
-(letrec ((even?
- (lambda (n)
- (if (zero? n)
- #t
- (odd? (- n 1)))))
- (odd?
- (lambda (n)
- (if (zero? n)
- #f
- (even? (- n 1))))))
- (even? 88))
-@result{}
-#t
-@end lisp
-@end deffn
-
-There is also an alternative form of the @code{let} form, which is used
-for expressing iteration. Because of the use as a looping construct,
-this form (the @dfn{named let}) is documented in the section about
-iteration (@pxref{while do, Iteration})
-
-@node Internal Definitions
-@section Internal definitions
-
-@c FIXME::martin: Review me!
-
-A @code{define} form which appears inside the body of a @code{lambda},
-@code{let}, @code{let*}, @code{letrec} or equivalent expression is
-called an @dfn{internal definition}. An internal definition differs
-from a top level definition (@pxref{Top Level}), because the definition
-is only visible inside the complete body of the enclosing form. Let us
-examine the following example.
-
-@lisp
-(let ((frumble "froz"))
- (define banana (lambda () (apple 'peach)))
- (define apple (lambda (x) x))
- (banana))
-@result{}
-peach
-@end lisp
-
-Here the enclosing form is a @code{let}, so the @code{define}s in the
-@code{let}-body are internal definitions. Because the scope of the
-internal definitions is the @strong{complete} body of the
-@code{let}-expression, the @code{lambda}-expression which gets bound
-to the variable @code{banana} may refer to the variable @code{apple},
-even though it's definition appears lexically @emph{after} the definition
-of @code{banana}. This is because a sequence of internal definition
-acts as if it were a @code{letrec} expression.
-
-@lisp
-(let ()
- (define a 1)
- (define b 2)
- (+ a b))
-@end lisp
-
-@noindent
-is equivalent to
-
-@lisp
-(let ()
- (letrec ((a 1) (b 2))
- (+ a b)))
-@end lisp
-
-Another noteworthy difference to top level definitions is that within
-one group of internal definitions all variable names must be distinct.
-That means where on the top level a second define for a given variable
-acts like a @code{set!}, an exception is thrown for internal definitions
-with duplicate bindings.
-
-@c FIXME::martin: The following is required by R5RS, but Guile does not
-@c signal an error. Document it anyway, saying that Guile is sloppy?
-
-@c Internal definitions are only allowed at the beginning of the body of an
-@c enclosing expression. They may not be mixed with other expressions.
-
-@c @lisp
-@c (let ()
-@c (define a 1)
-@c a
-@c (define b 2)
-@c b)
-@c @end lisp
-
-@node Binding Reflection
-@section Querying variable bindings
-
-Guile provides a procedure for checking whether a symbol is bound in the
-top level environment. If you want to test whether a symbol is locally
-bound in expression, you can use the @code{bound?} macro from the module
-@code{(ice-9 optargs)}, documented in @ref{Optional Arguments}.
-
-@c NJFIXME explain [env]
-@deffn {Scheme Procedure} defined? sym [env]
-@deffnx {C Function} scm_definedp (sym, env)
-Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End: