| 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: |