Merge commit '1e3fd6a0c81bb3e9900a93a9d1923cc788de0f99'

[bpt/guile.git] / doc / ref / api-binding.texi

@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011,
@c   2014 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Binding Constructs
@section Definitions and Variable Bindings

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.
* Binding Multiple Values::     Binding multiple return values.
@end menu


@node Top Level
@subsection Top Level Variable Definitions

@cindex variable definition

At the top level of a program (i.e., not nested within any other
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 in the current module, 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}).

Many people end up in a development style of adding and changing
definitions at runtime, building out their program without restarting
it.  (You can do this using @code{reload-module}, the @code{reload} REPL
command, the @code{load} procedure, or even just pasting code into a
REPL.)  If you are one of these people, you will find that sometimes you
there are some variables that you @emph{don't} want to redefine all the
time.  For these, use @code{define-once}.

@fnindex defvar
@deffn {Scheme Syntax} define-once name value
Create a top level variable named @var{name} with value @var{value}, but
only if @var{name} is not already bound in the current module.
@end deffn

Old Lispers probably know @code{define-once} under its Lisp name,
@code{defvar}.


@node Local Bindings
@subsection Local Variable Bindings

@cindex local bindings
@cindex local variables

As opposed to definitions at the top level, which creates bindings that
are visible to all code in a module, 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*},
@code{letrec}, 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 most basic local binding construct is @code{let}.

@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.
@end itemize

The @var{init} expressions are not allowed to refer to any of the
@var{variables}.
@end deffn

The other binding constructs are variations on the same theme: making new
values, binding them to variables, and executing a body in that new,
extended lexical context.

@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

Note that while the @var{init} expressions may refer to the new
variables, they may not access their values.  For example, making the
@code{even?} function above creates a closure (@pxref{About Closure})
referencing the @code{odd?} variable.  But @code{odd?} can't be called
until after execution has entered the body.
@end deffn

@deffn syntax letrec* bindings body
Similar to @code{letrec}, except the @var{init} expressions are bound to
their variables in order.

@code{letrec*} thus relaxes the letrec restriction, in that later
@var{init} expressions may refer to the values of previously bound
variables.

@lisp
(letrec ((a 42)
         (b (+ a 10)))  ;; Illegal access
  (* a b))
;; The behavior of the expression above is unspecified

(letrec* ((a 42)
          (b (+ a 10)))
  (* a b))
@result{} 2184
@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
@subsection 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}, @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 its 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

Internal definitions are only allowed at the beginning of the body of an
enclosing expression.  They may not be mixed with other expressions.

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.

As a historical note, it used to be that internal bindings were expanded
in terms of @code{letrec}, not @code{letrec*}. This was the situation
for the R5RS report and before. However with the R6RS, it was recognized
that sequential definition was a more intuitive expansion, as in the
following case:

@lisp
(let ()
  (define a 1)
  (define b (+ a a))
  (+ a b))
@end lisp  

@noindent
Guile decided to follow the R6RS in this regard, and now expands
internal definitions using @code{letrec*}.


@node Binding Reflection
@subsection Querying variable bindings

Guile provides a procedure for checking whether a symbol is bound in the
top level environment.

@deffn {Scheme Procedure} defined? sym [module]
@deffnx {C Function} scm_defined_p (sym, module)
Return @code{#t} if @var{sym} is defined in the module @var{module} or
the current module when @var{module} is not specified; otherwise return
@code{#f}.
@end deffn


@node Binding Multiple Values
@subsection Binding multiple return values

@deffn {Syntax} define-values formals expression
The @var{expression} is evaluated, and the @var{formals} are bound to
the return values in the same way that the formals in a @code{lambda}
expression are matched to the arguments in a procedure call.
@end deffn

@example
(define-values (q r) (floor/ 10 3))
(list q r) @result{} (3 1)

(define-values (x . y) (values 1 2 3))
x @result{} 1
y @result{} (2 3)

(define-values x (values 1 2 3))
x @result{} (1 2 3)
@end example


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: