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