2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Binding Constructs
8 @section Definitions and Variable Bindings
10 Scheme supports the definition of variables in different contexts.
11 Variables can be defined at the top level, so that they are visible in
12 the entire program, and variables can be defined locally to procedures
13 and expressions. This is important for modularity and data abstraction.
16 * Top Level:: Top level variable definitions.
17 * Local Bindings:: Local variable bindings.
18 * Internal Definitions:: Internal definitions.
19 * Binding Reflection:: Querying variable bindings.
24 @subsection Top Level Variable Definitions
26 @cindex variable definition
28 At the top level of a program (i.e., not nested within any other
29 expression), a definition of the form
32 (define a @var{value})
36 defines a variable called @code{a} and sets it to the value @var{value}.
38 If the variable already exists in the current module, because it has
39 already been created by a previous @code{define} expression with the
40 same name, its value is simply changed to the new @var{value}. In this
41 case, then, the above form is completely equivalent to
48 This equivalence means that @code{define} can be used interchangeably
49 with @code{set!} to change the value of variables at the top level of
50 the REPL or a Scheme source file. It is useful during interactive
51 development when reloading a Scheme file that you have modified, because
52 it allows the @code{define} expressions in that file to work as expected
53 both the first time that the file is loaded and on subsequent occasions.
55 Note, though, that @code{define} and @code{set!} are not always
56 equivalent. For example, a @code{set!} is not allowed if the named
57 variable does not already exist, and the two expressions can behave
58 differently in the case where there are imported variables visible from
61 @deffn {Scheme Syntax} define name value
62 Create a top level variable named @var{name} with value @var{value}.
63 If the named variable already exists, just change its value. The return
64 value of a @code{define} expression is unspecified.
67 The C API equivalents of @code{define} are @code{scm_define} and
68 @code{scm_c_define}, which differ from each other in whether the
69 variable name is specified as a @code{SCM} symbol or as a
70 null-terminated C string.
72 @deffn {C Function} scm_define (sym, value)
73 @deffnx {C Function} scm_c_define (const char *name, value)
74 C equivalents of @code{define}, with variable name specified either by
75 @var{sym}, a symbol, or by @var{name}, a null-terminated C string. Both
76 variants return the new or preexisting variable object.
79 @code{define} (when it occurs at top level), @code{scm_define} and
80 @code{scm_c_define} all create or set the value of a variable in the top
81 level environment of the current module. If there was not already a
82 variable with the specified name belonging to the current module, but a
83 similarly named variable from another module was visible through having
84 been imported, the newly created variable in the current module will
85 shadow the imported variable, such that the imported variable is no
88 Attention: Scheme definitions inside local binding constructs
89 (@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
91 Many people end up in a development style of adding and changing
92 definitions at runtime, building out their program without restarting
93 it. (You can do this using @code{reload-module}, the @code{reload} REPL
94 command, the @code{load} procedure, or even just pasting code into a
95 REPL.) If you are one of these people, you will find that sometimes you
96 there are some variables that you @emph{don't} want to redefine all the
97 time. For these, use @code{define-once}.
100 @deffn {Scheme Syntax} define-once name value
101 Create a top level variable named @var{name} with value @var{value}, but
102 only if @var{name} is not already bound in the current module.
105 Old Lispers probably know @code{define-once} under its Lisp name,
110 @subsection Local Variable Bindings
112 @cindex local bindings
113 @cindex local variables
115 As opposed to definitions at the top level, which creates bindings that
116 are visible to all code in a module, it is also possible to define
117 variables which are only visible in a well-defined part of the program.
118 Normally, this part of a program will be a procedure or a subexpression
121 With the constructs for local binding (@code{let}, @code{let*},
122 @code{letrec}, and @code{letrec*}), the Scheme language has a block
123 structure like most other programming languages since the days of
124 @sc{Algol 60}. Readers familiar to languages like C or Java should
125 already be used to this concept, but the family of @code{let}
126 expressions has a few properties which are well worth knowing.
128 The most basic local binding construct is @code{let}.
130 @deffn syntax let bindings body
131 @var{bindings} has the form
134 ((@var{variable1} @var{init1}) @dots{})
137 that is zero or more two-element lists of a variable and an arbitrary
138 expression each. All @var{variable} names must be distinct.
140 A @code{let} expression is evaluated as follows.
144 All @var{init} expressions are evaluated.
147 New storage is allocated for the @var{variables}.
150 The values of the @var{init} expressions are stored into the variables.
153 The expressions in @var{body} are evaluated in order, and the value of
154 the last expression is returned as the value of the @code{let}
158 The @var{init} expressions are not allowed to refer to any of the
162 The other binding constructs are variations on the same theme: making new
163 values, binding them to variables, and executing a body in that new,
164 extended lexical context.
166 @deffn syntax let* bindings body
167 Similar to @code{let}, but the variable bindings are performed
168 sequentially, that means that all @var{init} expression are allowed to
169 use the variables defined on their left in the binding list.
171 A @code{let*} expression can always be expressed with nested @code{let}
184 @deffn syntax letrec bindings body
185 Similar to @code{let}, but it is possible to refer to the @var{variable}
186 from lambda expression created in any of the @var{inits}. That is,
187 procedures created in the @var{init} expression can recursively refer to
188 the defined variables.
191 (letrec ((even? (lambda (n)
204 Note that while the @var{init} expressions may refer to the new
205 variables, they may not access their values. For example, making the
206 @code{even?} function above creates a closure (@pxref{About Closure})
207 referencing the @code{odd?} variable. But @code{odd?} can't be called
208 until after execution has entered the body.
211 @deffn syntax letrec* bindings body
212 Similar to @code{letrec}, except the @var{init} expressions are bound to
213 their variables in order.
215 @code{letrec*} thus relaxes the letrec restriction, in that later
216 @var{init} expressions may refer to the values of previously bound
221 (b (+ a 10))) ;; Illegal access
223 ;; The behavior of the expression above is unspecified
232 There is also an alternative form of the @code{let} form, which is used
233 for expressing iteration. Because of the use as a looping construct,
234 this form (the @dfn{named let}) is documented in the section about
235 iteration (@pxref{while do, Iteration})
237 @node Internal Definitions
238 @subsection Internal definitions
240 @c FIXME::martin: Review me!
242 A @code{define} form which appears inside the body of a @code{lambda},
243 @code{let}, @code{let*}, @code{letrec}, @code{letrec*} or equivalent
244 expression is called an @dfn{internal definition}. An internal
245 definition differs from a top level definition (@pxref{Top Level}),
246 because the definition is only visible inside the complete body of the
247 enclosing form. Let us examine the following example.
250 (let ((frumble "froz"))
251 (define banana (lambda () (apple 'peach)))
252 (define apple (lambda (x) x))
258 Here the enclosing form is a @code{let}, so the @code{define}s in the
259 @code{let}-body are internal definitions. Because the scope of the
260 internal definitions is the @strong{complete} body of the
261 @code{let}-expression, the @code{lambda}-expression which gets bound to
262 the variable @code{banana} may refer to the variable @code{apple}, even
263 though its definition appears lexically @emph{after} the definition of
264 @code{banana}. This is because a sequence of internal definition acts
265 as if it were a @code{letrec*} expression.
279 (letrec* ((a 1) (b 2))
283 Internal definitions are only allowed at the beginning of the body of an
284 enclosing expression. They may not be mixed with other expressions.
286 Another noteworthy difference to top level definitions is that within
287 one group of internal definitions all variable names must be distinct.
288 That means where on the top level a second define for a given variable
289 acts like a @code{set!}, an exception is thrown for internal definitions
290 with duplicate bindings.
292 As a historical note, it used to be that internal bindings were expanded
293 in terms of @code{letrec}, not @code{letrec*}. This was the situation
294 for the R5RS report and before. However with the R6RS, it was recognized
295 that sequential definition was a more intuitive expansion, as in the
306 Guile decided to follow the R6RS in this regard, and now expands
307 internal definitions using @code{letrec*}.
310 @node Binding Reflection
311 @subsection Querying variable bindings
313 Guile provides a procedure for checking whether a symbol is bound in the
314 top level environment.
316 @deffn {Scheme Procedure} defined? sym [module]
317 @deffnx {C Function} scm_defined_p (sym, module)
318 Return @code{#t} if @var{sym} is defined in the module @var{module} or
319 the current module when @var{module} is not specified; otherwise return
325 @c TeX-master: "guile.texi"