guile18/doc/ref/api-binding.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Binding Constructs
   9 @section Definitions and Variable Bindings
  10
  11 @c FIXME::martin: Review me!
  12
  13 Scheme supports the definition of variables in different contexts.
  14 Variables can be defined at the top level, so that they are visible in
  15 the entire program, and variables can be defined locally to procedures
  16 and expressions.  This is important for modularity and data abstraction.
  17
  18 @menu
  19 * Top Level::                   Top level variable definitions.
  20 * Local Bindings::              Local variable bindings.
  21 * Internal Definitions::        Internal definitions.
  22 * Binding Reflection::          Querying variable bindings.
  23 @end menu
  24
  25
  26 @node Top Level
  27 @subsection Top Level Variable Definitions
  28
  29 @cindex variable definition
  30
  31 On the top level of a program (i.e. when not inside the body of a
  32 procedure definition or a @code{let}, @code{let*} or @code{letrec}
  33 expression), a definition of the form
  34
  35 @lisp
  36 (define a @var{value})
  37 @end lisp
  38
  39 @noindent
  40 defines a variable called @code{a} and sets it to the value @var{value}.
  41
  42 If the variable already exists, because it has already been created by a
  43 previous @code{define} expression with the same name, its value is
  44 simply changed to the new @var{value}.  In this case, then, the above
  45 form is completely equivalent to
  46
  47 @lisp
  48 (set! a @var{value})
  49 @end lisp
  50
  51 @noindent
  52 This equivalence means that @code{define} can be used interchangeably
  53 with @code{set!} to change the value of variables at the top level of
  54 the REPL or a Scheme source file.  It is useful during interactive
  55 development when reloading a Scheme file that you have modified, because
  56 it allows the @code{define} expressions in that file to work as expected
  57 both the first time that the file is loaded and on subsequent occasions.
  58
  59 Note, though, that @code{define} and @code{set!} are not always
  60 equivalent.  For example, a @code{set!} is not allowed if the named
  61 variable does not already exist, and the two expressions can behave
  62 differently in the case where there are imported variables visible from
  63 another module.
  64
  65 @deffn {Scheme Syntax} define name value
  66 Create a top level variable named @var{name} with value @var{value}.
  67 If the named variable already exists, just change its value.  The return
  68 value of a @code{define} expression is unspecified.
  69 @end deffn
  70
  71 The C API equivalents of @code{define} are @code{scm_define} and
  72 @code{scm_c_define}, which differ from each other in whether the
  73 variable name is specified as a @code{SCM} symbol or as a
  74 null-terminated C string.
  75
  76 @deffn {C Function} scm_define (sym, value)
  77 @deffnx {C Function} scm_c_define (const char *name, value)
  78 C equivalents of @code{define}, with variable name specified either by
  79 @var{sym}, a symbol, or by @var{name}, a null-terminated C string.  Both
  80 variants return the new or preexisting variable object.
  81 @end deffn
  82
  83 @code{define} (when it occurs at top level), @code{scm_define} and
  84 @code{scm_c_define} all create or set the value of a variable in the top
  85 level environment of the current module.  If there was not already a
  86 variable with the specified name belonging to the current module, but a
  87 similarly named variable from another module was visible through having
  88 been imported, the newly created variable in the current module will
  89 shadow the imported variable, such that the imported variable is no
  90 longer visible.
  91
  92 Attention: Scheme definitions inside local binding constructs
  93 (@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
  94
  95
  96 @node Local Bindings
  97 @subsection Local Variable Bindings
  98
  99 @c FIXME::martin: Review me!
 100
 101 @cindex local bindings
 102 @cindex local variables
 103
 104 As opposed to definitions at the top level, which are visible in the
 105 whole program (or current module, when Guile modules are used), it is
 106 also possible to define variables which are only visible in a
 107 well-defined part of the program.  Normally, this part of a program
 108 will be a procedure or a subexpression of a procedure.
 109
 110 With the constructs for local binding (@code{let}, @code{let*} and
 111 @code{letrec}), the Scheme language has a block structure like most
 112 other programming languages since the days of @sc{Algol 60}.  Readers
 113 familiar to languages like C or Java should already be used to this
 114 concept, but the family of @code{let} expressions has a few properties
 115 which are well worth knowing.
 116
 117 The first local binding construct is @code{let}.  The other constructs
 118 @code{let*} and @code{letrec} are specialized versions for usage where
 119 using plain @code{let} is a bit inconvenient.
 120
 121 @deffn syntax let bindings body
 122 @var{bindings} has the form
 123
 124 @lisp
 125 ((@var{variable1} @var{init1}) @dots{})
 126 @end lisp
 127
 128 that is zero or more two-element lists of a variable and an arbitrary
 129 expression each.  All @var{variable} names must be distinct.
 130
 131 A @code{let} expression is evaluated as follows.
 132
 133 @itemize @bullet
 134 @item
 135 All @var{init} expressions are evaluated.
 136
 137 @item
 138 New storage is allocated for the @var{variables}.
 139
 140 @item
 141 The values of the @var{init} expressions are stored into the variables.
 142
 143 @item
 144 The expressions in @var{body} are evaluated in order, and the value of
 145 the last expression is returned as the value of the @code{let}
 146 expression.
 147
 148 @item
 149 The storage for the @var{variables} is freed.
 150 @end itemize
 151
 152 The @var{init} expressions are not allowed to refer to any of the
 153 @var{variables}.
 154 @end deffn
 155
 156 @deffn syntax let* bindings body
 157 Similar to @code{let}, but the variable bindings are performed
 158 sequentially, that means that all @var{init} expression are allowed to
 159 use the variables defined on their left in the binding list.
 160
 161 A @code{let*} expression can always be expressed with nested @code{let}
 162 expressions.
 163
 164 @lisp
 165 (let* ((a 1) (b a))
 166    b)
 167 @equiv{}
 168 (let ((a 1))
 169   (let ((b a))
 170     b))
 171 @end lisp
 172 @end deffn
 173
 174 @deffn syntax letrec bindings body
 175 Similar to @code{let}, but it is possible to refer to the @var{variable}
 176 from lambda expression created in any of the @var{inits}.  That is,
 177 procedures created in the @var{init} expression can recursively refer to
 178 the defined variables.
 179
 180 @lisp
 181 (letrec ((even?
 182           (lambda (n)
 183               (if (zero? n)
 184                   #t
 185                   (odd? (- n 1)))))
 186          (odd?
 187           (lambda (n)
 188               (if (zero? n)
 189                   #f
 190                   (even? (- n 1))))))
 191   (even? 88))
 192 @result{}
 193 #t
 194 @end lisp
 195 @end deffn
 196
 197 There is also an alternative form of the @code{let} form, which is used
 198 for expressing iteration.  Because of the use as a looping construct,
 199 this form (the @dfn{named let}) is documented in the section about
 200 iteration (@pxref{while do, Iteration})
 201
 202 @node Internal Definitions
 203 @subsection Internal definitions
 204
 205 @c FIXME::martin: Review me!
 206
 207 A @code{define} form which appears inside the body of a @code{lambda},
 208 @code{let}, @code{let*}, @code{letrec} or equivalent expression is
 209 called an @dfn{internal definition}.  An internal definition differs
 210 from a top level definition (@pxref{Top Level}), because the definition
 211 is only visible inside the complete body of the enclosing form.  Let us
 212 examine the following example.
 213
 214 @lisp
 215 (let ((frumble "froz"))
 216    (define banana (lambda () (apple 'peach)))
 217    (define apple (lambda (x) x))
 218    (banana))
 219 @result{}
 220 peach
 221 @end lisp
 222
 223 Here the enclosing form is a @code{let}, so the @code{define}s in the
 224 @code{let}-body are internal definitions.  Because the scope of the
 225 internal definitions is the @strong{complete} body of the
 226 @code{let}-expression, the @code{lambda}-expression which gets bound
 227 to the variable @code{banana} may refer to the variable @code{apple},
 228 even though it's definition appears lexically @emph{after} the definition
 229 of @code{banana}.  This is because a sequence of internal definition
 230 acts as if it were a @code{letrec} expression.
 231
 232 @lisp
 233 (let ()
 234   (define a 1)
 235   (define b 2)
 236   (+ a b))
 237 @end lisp
 238
 239 @noindent
 240 is equivalent to
 241
 242 @lisp
 243 (let ()
 244   (letrec ((a 1) (b 2))
 245     (+ a b)))
 246 @end lisp
 247
 248 Another noteworthy difference to top level definitions is that within
 249 one group of internal definitions all variable names must be distinct.
 250 That means where on the top level a second define for a given variable
 251 acts like a @code{set!}, an exception is thrown for internal definitions
 252 with duplicate bindings.
 253
 254 @c FIXME::martin: The following is required by R5RS, but Guile does not
 255 @c   signal an error.  Document it anyway, saying that Guile is sloppy?
 256
 257 @c  Internal definitions are only allowed at the beginning of the body of an
 258 @c  enclosing expression.  They may not be mixed with other expressions.
 259
 260 @c  @lisp
 261 @c  (let ()
 262 @c    (define a 1)
 263 @c    a
 264 @c    (define b 2)
 265 @c    b)
 266 @c  @end lisp
 267
 268 @node Binding Reflection
 269 @subsection Querying variable bindings
 270
 271 Guile provides a procedure for checking whether a symbol is bound in the
 272 top level environment.
 273
 274 @c NJFIXME explain [env]
 275 @deffn {Scheme Procedure} defined? sym [env]
 276 @deffnx {C Function} scm_defined_p (sym, env)
 277 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.
 278 @end deffn
 279
 280
 281 @c Local Variables:
 282 @c TeX-master: "guile.texi"
 283 @c End: