doc/ref/scheme-binding.texi

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