Merge branch 'master' into wip-manual-2
[bpt/guile.git] / doc / ref / scheme-ideas.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, 2005
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
6
7 @node Basic Ideas
8 @section Basic Ideas in Scheme
9
10 In this chapter, we introduce the basic concepts that underpin the
11 elegance and power of the Scheme language.
12
13 Readers who already possess a background knowledge of Scheme may happily
14 skip this chapter. For the reader who is new to the language, however,
15 the following discussions on data, procedures, expressions and closure
16 are designed to provide a minimum level of Scheme understanding that is
17 more or less assumed by the reference chapters that follow.
18
19 The style of this introductory material aims about halfway between the
20 terse precision of R5RS and the discursive randomness of a Scheme
21 tutorial.
22
23 @menu
24 * About Data:: Latent typing, types, values and variables.
25 * About Procedures:: The representation and use of procedures.
26 * About Expressions:: All kinds of expressions and their meaning.
27 * About Closure:: Closure, scoping and environments.
28 @end menu
29
30
31 @node About Data
32 @subsection Data Types, Values and Variables
33
34 This section discusses the representation of data types and values, what
35 it means for Scheme to be a @dfn{latently typed} language, and the role
36 of variables. We conclude by introducing the Scheme syntaxes for
37 defining a new variable, and for changing the value of an existing
38 variable.
39
40 @menu
41 * Latent Typing:: Scheme as a "latently typed" language.
42 * Values and Variables:: About data types, values and variables.
43 * Definition:: Defining variables and setting their values.
44 @end menu
45
46
47 @node Latent Typing
48 @subsubsection Latent Typing
49
50 The term @dfn{latent typing} is used to describe a computer language,
51 such as Scheme, for which you cannot, @emph{in general}, simply look at
52 a program's source code and determine what type of data will be
53 associated with a particular variable, or with the result of a
54 particular expression.
55
56 Sometimes, of course, you @emph{can} tell from the code what the type of
57 an expression will be. If you have a line in your program that sets the
58 variable @code{x} to the numeric value 1, you can be certain that,
59 immediately after that line has executed (and in the absence of multiple
60 threads), @code{x} has the numeric value 1. Or if you write a procedure
61 that is designed to concatenate two strings, it is likely that the rest
62 of your application will always invoke this procedure with two string
63 parameters, and quite probable that the procedure would go wrong in some
64 way if it was ever invoked with parameters that were not both strings.
65
66 Nevertheless, the point is that there is nothing in Scheme which
67 requires the procedure parameters always to be strings, or @code{x}
68 always to hold a numeric value, and there is no way of declaring in your
69 program that such constraints should always be obeyed. In the same
70 vein, there is no way to declare the expected type of a procedure's
71 return value.
72
73 Instead, the types of variables and expressions are only known -- in
74 general -- at run time. If you @emph{need} to check at some point that
75 a value has the expected type, Scheme provides run time procedures that
76 you can invoke to do so. But equally, it can be perfectly valid for two
77 separate invocations of the same procedure to specify arguments with
78 different types, and to return values with different types.
79
80 The next subsection explains what this means in practice, for the ways
81 that Scheme programs use data types, values and variables.
82
83
84 @node Values and Variables
85 @subsubsection Values and Variables
86
87 Scheme provides many data types that you can use to represent your data.
88 Primitive types include characters, strings, numbers and procedures.
89 Compound types, which allow a group of primitive and compound values to
90 be stored together, include lists, pairs, vectors and multi-dimensional
91 arrays. In addition, Guile allows applications to define their own data
92 types, with the same status as the built-in standard Scheme types.
93
94 As a Scheme program runs, values of all types pop in and out of
95 existence. Sometimes values are stored in variables, but more commonly
96 they pass seamlessly from being the result of one computation to being
97 one of the parameters for the next.
98
99 Consider an example. A string value is created because the interpreter
100 reads in a literal string from your program's source code. Then a
101 numeric value is created as the result of calculating the length of the
102 string. A second numeric value is created by doubling the calculated
103 length. Finally the program creates a list with two elements -- the
104 doubled length and the original string itself -- and stores this list in
105 a program variable.
106
107 All of the values involved here -- in fact, all values in Scheme --
108 carry their type with them. In other words, every value ``knows,'' at
109 runtime, what kind of value it is. A number, a string, a list,
110 whatever.
111
112 A variable, on the other hand, has no fixed type. A variable --
113 @code{x}, say -- is simply the name of a location -- a box -- in which
114 you can store any kind of Scheme value. So the same variable in a
115 program may hold a number at one moment, a list of procedures the next,
116 and later a pair of strings. The ``type'' of a variable -- insofar as
117 the idea is meaningful at all -- is simply the type of whatever value
118 the variable happens to be storing at a particular moment.
119
120
121 @node Definition
122 @subsubsection Defining and Setting Variables
123
124 To define a new variable, you use Scheme's @code{define} syntax like
125 this:
126
127 @lisp
128 (define @var{variable-name} @var{value})
129 @end lisp
130
131 This makes a new variable called @var{variable-name} and stores
132 @var{value} in it as the variable's initial value. For example:
133
134 @lisp
135 ;; Make a variable `x' with initial numeric value 1.
136 (define x 1)
137
138 ;; Make a variable `organization' with an initial string value.
139 (define organization "Free Software Foundation")
140 @end lisp
141
142 (In Scheme, a semicolon marks the beginning of a comment that continues
143 until the end of the line. So the lines beginning @code{;;} are
144 comments.)
145
146 Changing the value of an already existing variable is very similar,
147 except that @code{define} is replaced by the Scheme syntax @code{set!},
148 like this:
149
150 @lisp
151 (set! @var{variable-name} @var{new-value})
152 @end lisp
153
154 Remember that variables do not have fixed types, so @var{new-value} may
155 have a completely different type from whatever was previously stored in
156 the location named by @var{variable-name}. Both of the following
157 examples are therefore correct.
158
159 @lisp
160 ;; Change the value of `x' to 5.
161 (set! x 5)
162
163 ;; Change the value of `organization' to the FSF's street number.
164 (set! organization 545)
165 @end lisp
166
167 In these examples, @var{value} and @var{new-value} are literal numeric
168 or string values. In general, however, @var{value} and @var{new-value}
169 can be any Scheme expression. Even though we have not yet covered the
170 forms that Scheme expressions can take (@pxref{About Expressions}), you
171 can probably guess what the following @code{set!} example does@dots{}
172
173 @lisp
174 (set! x (+ x 1))
175 @end lisp
176
177 (Note: this is not a complete description of @code{define} and
178 @code{set!}, because we need to introduce some other aspects of Scheme
179 before the missing pieces can be filled in. If, however, you are
180 already familiar with the structure of Scheme, you may like to read
181 about those missing pieces immediately by jumping ahead to the following
182 references.
183
184 @itemize @bullet
185 @item
186 @ref{Lambda Alternatives}, to read about an alternative form of the
187 @code{define} syntax that can be used when defining new procedures.
188
189 @item
190 @ref{Procedures with Setters}, to read about an alternative form of the
191 @code{set!} syntax that helps with changing a single value in the depths
192 of a compound data structure.)
193
194 @item
195 @xref{Internal Definitions}, to read about using @code{define} other
196 than at top level in a Scheme program, including a discussion of when it
197 works to use @code{define} rather than @code{set!} to change the value
198 of an existing variable.
199 @end itemize
200
201
202 @node About Procedures
203 @subsection The Representation and Use of Procedures
204
205 This section introduces the basics of using and creating Scheme
206 procedures. It discusses the representation of procedures as just
207 another kind of Scheme value, and shows how procedure invocation
208 expressions are constructed. We then explain how @code{lambda} is used
209 to create new procedures, and conclude by presenting the various
210 shorthand forms of @code{define} that can be used instead of writing an
211 explicit @code{lambda} expression.
212
213 @menu
214 * Procedures as Values:: Procedures are values like everything else.
215 * Simple Invocation:: How to write a simple procedure invocation.
216 * Creating a Procedure:: How to create your own procedures.
217 * Lambda Alternatives:: Other ways of writing procedure definitions.
218 @end menu
219
220
221 @node Procedures as Values
222 @subsubsection Procedures as Values
223
224 One of the great simplifications of Scheme is that a procedure is just
225 another type of value, and that procedure values can be passed around
226 and stored in variables in exactly the same way as, for example, strings
227 and lists. When we talk about a built-in standard Scheme procedure such
228 as @code{open-input-file}, what we actually mean is that there is a
229 pre-defined top level variable called @code{open-input-file}, whose
230 value is a procedure that implements what R5RS says that
231 @code{open-input-file} should do.
232
233 Note that this is quite different from many dialects of Lisp ---
234 including Emacs Lisp --- in which a program can use the same name with
235 two quite separate meanings: one meaning identifies a Lisp function,
236 while the other meaning identifies a Lisp variable, whose value need
237 have nothing to do with the function that is associated with the first
238 meaning. In these dialects, functions and variables are said to live in
239 different @dfn{namespaces}.
240
241 In Scheme, on the other hand, all names belong to a single unified
242 namespace, and the variables that these names identify can hold any kind
243 of Scheme value, including procedure values.
244
245 One consequence of the ``procedures as values'' idea is that, if you
246 don't happen to like the standard name for a Scheme procedure, you can
247 change it.
248
249 For example, @code{call-with-current-continuation} is a very important
250 standard Scheme procedure, but it also has a very long name! So, many
251 programmers use the following definition to assign the same procedure
252 value to the more convenient name @code{call/cc}.
253
254 @lisp
255 (define call/cc call-with-current-continuation)
256 @end lisp
257
258 Let's understand exactly how this works. The definition creates a new
259 variable @code{call/cc}, and then sets its value to the value of the
260 variable @code{call-with-current-continuation}; the latter value is a
261 procedure that implements the behaviour that R5RS specifies under the
262 name ``call-with-current-continuation''. So @code{call/cc} ends up
263 holding this value as well.
264
265 Now that @code{call/cc} holds the required procedure value, you could
266 choose to use @code{call-with-current-continuation} for a completely
267 different purpose, or just change its value so that you will get an
268 error if you accidentally use @code{call-with-current-continuation} as a
269 procedure in your program rather than @code{call/cc}. For example:
270
271 @lisp
272 (set! call-with-current-continuation "Not a procedure any more!")
273 @end lisp
274
275 Or you could just leave @code{call-with-current-continuation} as it was.
276 It's perfectly fine for more than one variable to hold the same
277 procedure value.
278
279
280 @node Simple Invocation
281 @subsubsection Simple Procedure Invocation
282
283 A procedure invocation in Scheme is written like this:
284
285 @lisp
286 (@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
287 @end lisp
288
289 In this expression, @var{procedure} can be any Scheme expression whose
290 value is a procedure. Most commonly, however, @var{procedure} is simply
291 the name of a variable whose value is a procedure.
292
293 For example, @code{string-append} is a standard Scheme procedure whose
294 behaviour is to concatenate together all the arguments, which are
295 expected to be strings, that it is given. So the expression
296
297 @lisp
298 (string-append "/home" "/" "andrew")
299 @end lisp
300
301 @noindent
302 is a procedure invocation whose result is the string value
303 @code{"/home/andrew"}.
304
305 Similarly, @code{string-length} is a standard Scheme procedure that
306 returns the length of a single string argument, so
307
308 @lisp
309 (string-length "abc")
310 @end lisp
311
312 @noindent
313 is a procedure invocation whose result is the numeric value 3.
314
315 Each of the parameters in a procedure invocation can itself be any
316 Scheme expression. Since a procedure invocation is itself a type of
317 expression, we can put these two examples together to get
318
319 @lisp
320 (string-length (string-append "/home" "/" "andrew"))
321 @end lisp
322
323 @noindent
324 --- a procedure invocation whose result is the numeric value 12.
325
326 (You may be wondering what happens if the two examples are combined the
327 other way round. If we do this, we can make a procedure invocation
328 expression that is @emph{syntactically} correct:
329
330 @lisp
331 (string-append "/home" (string-length "abc"))
332 @end lisp
333
334 @noindent
335 but when this expression is executed, it will cause an error, because
336 the result of @code{(string-length "abc")} is a numeric value, and
337 @code{string-append} is not designed to accept a numeric value as one of
338 its arguments.)
339
340
341 @node Creating a Procedure
342 @subsubsection Creating and Using a New Procedure
343
344 Scheme has lots of standard procedures, and Guile provides all of these
345 via predefined top level variables. All of these standard procedures
346 are documented in the later chapters of this reference manual.
347
348 Before very long, though, you will want to create new procedures that
349 encapsulate aspects of your own applications' functionality. To do
350 this, you can use the famous @code{lambda} syntax.
351
352 For example, the value of the following Scheme expression
353
354 @lisp
355 (lambda (name address) @var{expression} @dots{})
356 @end lisp
357
358 @noindent
359 is a newly created procedure that takes two arguments:
360 @code{name} and @code{address}. The behaviour of the
361 new procedure is determined by the sequence of @var{expression}s in the
362 @dfn{body} of the procedure definition. (Typically, these
363 @var{expression}s would use the arguments in some way, or else there
364 wouldn't be any point in giving them to the procedure.) When invoked,
365 the new procedure returns a value that is the value of the last
366 @var{expression} in the procedure body.
367
368 To make things more concrete, let's suppose that the two arguments are
369 both strings, and that the purpose of this procedure is to form a
370 combined string that includes these arguments. Then the full lambda
371 expression might look like this:
372
373 @lisp
374 (lambda (name address)
375 (string-append "Name=" name ":Address=" address))
376 @end lisp
377
378 We noted in the previous subsection that the @var{procedure} part of a
379 procedure invocation expression can be any Scheme expression whose value
380 is a procedure. But that's exactly what a lambda expression is! So we
381 can use a lambda expression directly in a procedure invocation, like
382 this:
383
384 @lisp
385 ((lambda (name address)
386 (string-append "Name=" name ":Address=" address))
387 "FSF"
388 "Cambridge")
389 @end lisp
390
391 @noindent
392 This is a valid procedure invocation expression, and its result is the
393 string:
394
395 @lisp
396 "Name=FSF:Address=Cambridge"
397 @end lisp
398
399 It is more common, though, to store the procedure value in a variable ---
400
401 @lisp
402 (define make-combined-string
403 (lambda (name address)
404 (string-append "Name=" name ":Address=" address)))
405 @end lisp
406
407 @noindent
408 --- and then to use the variable name in the procedure invocation:
409
410 @lisp
411 (make-combined-string "FSF" "Cambridge")
412 @end lisp
413
414 @noindent
415 Which has exactly the same result.
416
417 It's important to note that procedures created using @code{lambda} have
418 exactly the same status as the standard built in Scheme procedures, and
419 can be invoked, passed around, and stored in variables in exactly the
420 same ways.
421
422
423 @node Lambda Alternatives
424 @subsubsection Lambda Alternatives
425
426 Since it is so common in Scheme programs to want to create a procedure
427 and then store it in a variable, there is an alternative form of the
428 @code{define} syntax that allows you to do just that.
429
430 A @code{define} expression of the form
431
432 @lisp
433 (define (@var{name} [@var{arg1} [@var{arg2} @dots{}]])
434 @var{expression} @dots{})
435 @end lisp
436
437 @noindent
438 is exactly equivalent to the longer form
439
440 @lisp
441 (define @var{name}
442 (lambda ([@var{arg1} [@var{arg2} @dots{}]])
443 @var{expression} @dots{}))
444 @end lisp
445
446 So, for example, the definition of @code{make-combined-string} in the
447 previous subsection could equally be written:
448
449 @lisp
450 (define (make-combined-string name address)
451 (string-append "Name=" name ":Address=" address))
452 @end lisp
453
454 This kind of procedure definition creates a procedure that requires
455 exactly the expected number of arguments. There are two further forms
456 of the @code{lambda} expression, which create a procedure that can
457 accept a variable number of arguments:
458
459 @lisp
460 (lambda (@var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
461
462 (lambda @var{args} @var{expression} @dots{})
463 @end lisp
464
465 @noindent
466 The corresponding forms of the alternative @code{define} syntax are:
467
468 @lisp
469 (define (@var{name} @var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
470
471 (define (@var{name} . @var{args}) @var{expression} @dots{})
472 @end lisp
473
474 @noindent
475 For details on how these forms work, see @xref{Lambda}.
476
477 (It could be argued that the alternative @code{define} forms are rather
478 confusing, especially for newcomers to the Scheme language, as they hide
479 both the role of @code{lambda} and the fact that procedures are values
480 that are stored in variables in the some way as any other kind of value.
481 On the other hand, they are very convenient, and they are also a good
482 example of another of Scheme's powerful features: the ability to specify
483 arbitrary syntactic transformations at run time, which can be applied to
484 subsequently read input.)
485
486
487 @node About Expressions
488 @subsection Expressions and Evaluation
489
490 So far, we have met expressions that @emph{do} things, such as the
491 @code{define} expressions that create and initialize new variables, and
492 we have also talked about expressions that have @emph{values}, for
493 example the value of the procedure invocation expression:
494
495 @lisp
496 (string-append "/home" "/" "andrew")
497 @end lisp
498
499 @noindent
500 but we haven't yet been precise about what causes an expression like
501 this procedure invocation to be reduced to its ``value'', or how the
502 processing of such expressions relates to the execution of a Scheme
503 program as a whole.
504
505 This section clarifies what we mean by an expression's value, by
506 introducing the idea of @dfn{evaluation}. It discusses the side effects
507 that evaluation can have, explains how each of the various types of
508 Scheme expression is evaluated, and describes the behaviour and use of
509 the Guile REPL as a mechanism for exploring evaluation. The section
510 concludes with a very brief summary of Scheme's common syntactic
511 expressions.
512
513 @menu
514 * Evaluating:: How a Scheme program is executed.
515 * Tail Calls:: Space-safe recursion.
516 * The REPL:: Interacting with the Guile interpreter.
517 * Syntax Summary:: Common syntactic expressions -- in brief.
518 @end menu
519
520
521 @node Evaluating
522 @subsubsection Evaluating Expressions and Executing Programs
523
524 In Scheme, the process of executing an expression is known as
525 @dfn{evaluation}. Evaluation has two kinds of result:
526
527 @itemize @bullet
528 @item
529 the @dfn{value} of the evaluated expression
530
531 @item
532 the @dfn{side effects} of the evaluation, which consist of any effects of
533 evaluating the expression that are not represented by the value.
534 @end itemize
535
536 Of the expressions that we have met so far, @code{define} and
537 @code{set!} expressions have side effects --- the creation or
538 modification of a variable --- but no value; @code{lambda} expressions
539 have values --- the newly constructed procedures --- but no side
540 effects; and procedure invocation expressions, in general, have either
541 values, or side effects, or both.
542
543 It is tempting to try to define more intuitively what we mean by
544 ``value'' and ``side effects'', and what the difference between them is.
545 In general, though, this is extremely difficult. It is also
546 unnecessary; instead, we can quite happily define the behaviour of a
547 Scheme program by specifying how Scheme executes a program as a whole,
548 and then by describing the value and side effects of evaluation for each
549 type of expression individually.
550
551 @noindent
552 So, some@footnote{These definitions are approximate. For the whole
553 and detailed truth, see @ref{Formal syntax and semantics,R5RS
554 syntax,,r5rs,The Revised(5) Report on the Algorithmic Language
555 Scheme}.} definitions@dots{}
556
557 @itemize @bullet
558
559 @item
560 A Scheme program consists of a sequence of expressions.
561
562 @item
563 A Scheme interpreter executes the program by evaluating these
564 expressions in order, one by one.
565
566 @item
567 An expression can be
568
569 @itemize @bullet
570 @item
571 a piece of literal data, such as a number @code{2.3} or a string
572 @code{"Hello world!"}
573 @item
574 a variable name
575 @item
576 a procedure invocation expression
577 @item
578 one of Scheme's special syntactic expressions.
579 @end itemize
580 @end itemize
581
582 @noindent
583 The following subsections describe how each of these types of expression
584 is evaluated.
585
586 @c @menu
587 @c * Eval Literal:: Evaluating literal data.
588 @c * Eval Variable:: Evaluating variable references.
589 @c * Eval Procedure:: Evaluating procedure invocation expressions.
590 @c * Eval Special:: Evaluating special syntactic expressions.
591 @c @end menu
592
593 @c @node Eval Literal
594
595 @subsubheading Evaluating Literal Data
596
597 When a literal data expression is evaluated, the value of the expression
598 is simply the value that the expression describes. The evaluation of a
599 literal data expression has no side effects.
600
601 @noindent
602 So, for example,
603
604 @itemize @bullet
605 @item
606 the value of the expression @code{"abc"} is the string value
607 @code{"abc"}
608
609 @item
610 the value of the expression @code{3+4i} is the complex number 3 + 4i
611
612 @item
613 the value of the expression @code{#(1 2 3)} is a three-element vector
614 containing the numeric values 1, 2 and 3.
615 @end itemize
616
617 For any data type which can be expressed literally like this, the syntax
618 of the literal data expression for that data type --- in other words,
619 what you need to write in your code to indicate a literal value of that
620 type --- is known as the data type's @dfn{read syntax}. This manual
621 specifies the read syntax for each such data type in the section that
622 describes that data type.
623
624 Some data types do not have a read syntax. Procedures, for example,
625 cannot be expressed as literal data; they must be created using a
626 @code{lambda} expression (@pxref{Creating a Procedure}) or implicitly
627 using the shorthand form of @code{define} (@pxref{Lambda Alternatives}).
628
629
630 @c @node Eval Variable
631 @subsubheading Evaluating a Variable Reference
632
633 When an expression that consists simply of a variable name is evaluated,
634 the value of the expression is the value of the named variable. The
635 evaluation of a variable reference expression has no side effects.
636
637 So, after
638
639 @lisp
640 (define key "Paul Evans")
641 @end lisp
642
643 @noindent
644 the value of the expression @code{key} is the string value @code{"Paul
645 Evans"}. If @var{key} is then modified by
646
647 @lisp
648 (set! key 3.74)
649 @end lisp
650
651 @noindent
652 the value of the expression @code{key} is the numeric value 3.74.
653
654 If there is no variable with the specified name, evaluation of the
655 variable reference expression signals an error.
656
657
658 @c @node Eval Procedure
659 @subsubheading Evaluating a Procedure Invocation Expression
660
661 This is where evaluation starts getting interesting! As already noted,
662 a procedure invocation expression has the form
663
664 @lisp
665 (@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
666 @end lisp
667
668 @noindent
669 where @var{procedure} must be an expression whose value, when evaluated,
670 is a procedure.
671
672 The evaluation of a procedure invocation expression like this proceeds
673 by
674
675 @itemize @bullet
676 @item
677 evaluating individually the expressions @var{procedure}, @var{arg1},
678 @var{arg2}, and so on
679
680 @item
681 calling the procedure that is the value of the @var{procedure}
682 expression with the list of values obtained from the evaluations of
683 @var{arg1}, @var{arg2} etc. as its parameters.
684 @end itemize
685
686 For a procedure defined in Scheme, ``calling the procedure with the list
687 of values as its parameters'' means binding the values to the
688 procedure's formal parameters and then evaluating the sequence of
689 expressions that make up the body of the procedure definition. The
690 value of the procedure invocation expression is the value of the last
691 evaluated expression in the procedure body. The side effects of calling
692 the procedure are the combination of the side effects of the sequence of
693 evaluations of expressions in the procedure body.
694
695 For a built-in procedure, the value and side-effects of calling the
696 procedure are best described by that procedure's documentation.
697
698 Note that the complete side effects of evaluating a procedure invocation
699 expression consist not only of the side effects of the procedure call,
700 but also of any side effects of the preceding evaluation of the
701 expressions @var{procedure}, @var{arg1}, @var{arg2}, and so on.
702
703 To illustrate this, let's look again at the procedure invocation
704 expression:
705
706 @lisp
707 (string-length (string-append "/home" "/" "andrew"))
708 @end lisp
709
710 In the outermost expression, @var{procedure} is @code{string-length} and
711 @var{arg1} is @code{(string-append "/home" "/" "andrew")}.
712
713 @itemize @bullet
714 @item
715 Evaluation of @code{string-length}, which is a variable, gives a
716 procedure value that implements the expected behaviour for
717 ``string-length''.
718
719 @item
720 Evaluation of @code{(string-append "/home" "/" "andrew")}, which is
721 another procedure invocation expression, means evaluating each of
722
723 @itemize @bullet
724 @item
725 @code{string-append}, which gives a procedure value that implements the
726 expected behaviour for ``string-append''
727
728 @item
729 @code{"/home"}, which gives the string value @code{"/home"}
730
731 @item
732 @code{"/"}, which gives the string value @code{"/"}
733
734 @item
735 @code{"andrew"}, which gives the string value @code{"andrew"}
736 @end itemize
737
738 and then invoking the procedure value with this list of string values as
739 its arguments. The resulting value is a single string value that is the
740 concatenation of all the arguments, namely @code{"/home/andrew"}.
741 @end itemize
742
743 In the evaluation of the outermost expression, the interpreter can now
744 invoke the procedure value obtained from @var{procedure} with the value
745 obtained from @var{arg1} as its arguments. The resulting value is a
746 numeric value that is the length of the argument string, which is 12.
747
748
749 @c @node Eval Special
750 @subsubheading Evaluating Special Syntactic Expressions
751
752 When a procedure invocation expression is evaluated, the procedure and
753 @emph{all} the argument expressions must be evaluated before the
754 procedure can be invoked. Special syntactic expressions are special
755 because they are able to manipulate their arguments in an unevaluated
756 form, and can choose whether to evaluate any or all of the argument
757 expressions.
758
759 Why is this needed? Consider a program fragment that asks the user
760 whether or not to delete a file, and then deletes the file if the user
761 answers yes.
762
763 @lisp
764 (if (string=? (read-answer "Should I delete this file?")
765 "yes")
766 (delete-file file))
767 @end lisp
768
769 If the outermost @code{(if @dots{})} expression here was a procedure
770 invocation expression, the expression @code{(delete-file file)}, whose
771 side effect is to actually delete a file, would already have been
772 evaluated before the @code{if} procedure even got invoked! Clearly this
773 is no use --- the whole point of an @code{if} expression is that the
774 @dfn{consequent} expression is only evaluated if the condition of the
775 @code{if} expression is ``true''.
776
777 Therefore @code{if} must be special syntax, not a procedure. Other
778 special syntaxes that we have already met are @code{define}, @code{set!}
779 and @code{lambda}. @code{define} and @code{set!} are syntax because
780 they need to know the variable @emph{name} that is given as the first
781 argument in a @code{define} or @code{set!} expression, not that
782 variable's value. @code{lambda} is syntax because it does not
783 immediately evaluate the expressions that define the procedure body;
784 instead it creates a procedure object that incorporates these
785 expressions so that they can be evaluated in the future, when that
786 procedure is invoked.
787
788 The rules for evaluating each special syntactic expression are specified
789 individually for each special syntax. For a summary of standard special
790 syntax, see @xref{Syntax Summary}.
791
792
793 @node Tail Calls
794 @subsubsection Tail calls
795 @cindex tail calls
796 @cindex recursion
797
798 Scheme is ``properly tail recursive'', meaning that tail calls or
799 recursions from certain contexts do not consume stack space or other
800 resources and can therefore be used on arbitrarily large data or for
801 an arbitrarily long calculation. Consider for example,
802
803 @example
804 (define (foo n)
805 (display n)
806 (newline)
807 (foo (1+ n)))
808
809 (foo 1)
810 @print{}
811 1
812 2
813 3
814 @dots{}
815 @end example
816
817 @code{foo} prints numbers infinitely, starting from the given @var{n}.
818 It's implemented by printing @var{n} then recursing to itself to print
819 @math{@var{n}+1} and so on. This recursion is a tail call, it's the
820 last thing done, and in Scheme such tail calls can be made without
821 limit.
822
823 Or consider a case where a value is returned, a version of the SRFI-1
824 @code{last} function (@pxref{SRFI-1 Selectors}) returning the last
825 element of a list,
826
827 @example
828 (define (my-last lst)
829 (if (null? (cdr lst))
830 (car lst)
831 (my-last (cdr lst))))
832
833 (my-last '(1 2 3)) @result{} 3
834 @end example
835
836 If the list has more than one element, @code{my-last} applies itself
837 to the @code{cdr}. This recursion is a tail call, there's no code
838 after it, and the return value is the return value from that call. In
839 Scheme this can be used on an arbitrarily long list argument.
840
841 @sp 1
842 A proper tail call is only available from certain contexts, namely the
843 following special form positions,
844
845 @itemize @bullet
846 @item
847 @code{and} --- last expression
848
849 @item
850 @code{begin} --- last expression
851
852 @item
853 @code{case} --- last expression in each clause
854
855 @item
856 @code{cond} --- last expression in each clause, and the call to a
857 @code{=>} procedure is a tail call
858
859 @item
860 @code{do} --- last result expression
861
862 @item
863 @code{if} --- ``true'' and ``false'' leg expressions
864
865 @item
866 @code{lambda} --- last expression in body
867
868 @item
869 @code{let}, @code{let*}, @code{letrec}, @code{let-syntax},
870 @code{letrec-syntax} --- last expression in body
871
872 @item
873 @code{or} --- last expression
874 @end itemize
875
876 @noindent
877 The following core functions make tail calls,
878
879 @itemize @bullet
880 @item
881 @code{apply} --- tail call to given procedure
882
883 @item
884 @code{call-with-current-continuation} --- tail call to the procedure
885 receiving the new continuation
886
887 @item
888 @code{call-with-values} --- tail call to the values-receiving
889 procedure
890
891 @item
892 @code{eval} --- tail call to evaluate the form
893
894 @item
895 @code{string-any}, @code{string-every} --- tail call to predicate on
896 the last character (if that point is reached)
897 @end itemize
898
899 @sp 1
900 The above are just core functions and special forms. Tail calls in
901 other modules are described with the relevant documentation, for
902 example SRFI-1 @code{any} and @code{every} (@pxref{SRFI-1 Searching}).
903
904 It will be noted there are a lot of places which could potentially be
905 tail calls, for instance the last call in a @code{for-each}, but only
906 those explicitly described are guaranteed.
907
908
909 @node The REPL
910 @subsubsection Using the Guile REPL
911
912 If you start Guile without specifying a particular program for it to
913 execute, Guile enters its standard Read Evaluate Print Loop --- or
914 @dfn{REPL} for short. In this mode, Guile repeatedly reads in the next
915 Scheme expression that the user types, evaluates it, and prints the
916 resulting value.
917
918 The REPL is a useful mechanism for exploring the evaluation behaviour
919 described in the previous subsection. If you type @code{string-append},
920 for example, the REPL replies @code{#<primitive-procedure
921 string-append>}, illustrating the relationship between the variable
922 @code{string-append} and the procedure value stored in that variable.
923
924 In this manual, the notation @result{} is used to mean ``evaluates
925 to''. Wherever you see an example of the form
926
927 @lisp
928 @var{expression}
929 @result{}
930 @var{result}
931 @end lisp
932
933 @noindent
934 feel free to try it out yourself by typing @var{expression} into the
935 REPL and checking that it gives the expected @var{result}.
936
937
938 @node Syntax Summary
939 @subsubsection Summary of Common Syntax
940
941 This subsection lists the most commonly used Scheme syntactic
942 expressions, simply so that you will recognize common special syntax
943 when you see it. For a full description of each of these syntaxes,
944 follow the appropriate reference.
945
946 @code{lambda} (@pxref{Lambda}) is used to construct procedure objects.
947
948 @code{define} (@pxref{Top Level}) is used to create a new variable and
949 set its initial value.
950
951 @code{set!} (@pxref{Top Level}) is used to modify an existing variable's
952 value.
953
954 @code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
955 create an inner lexical environment for the evaluation of a sequence of
956 expressions, in which a specified set of local variables is bound to the
957 values of a corresponding set of expressions. For an introduction to
958 environments, see @xref{About Closure}.
959
960 @code{begin} (@pxref{begin}) executes a sequence of expressions in order
961 and returns the value of the last expression. Note that this is not the
962 same as a procedure which returns its last argument, because the
963 evaluation of a procedure invocation expression does not guarantee to
964 evaluate the arguments in order.
965
966 @code{if} and @code{cond} (@pxref{if cond case}) provide conditional
967 evaluation of argument expressions depending on whether one or more
968 conditions evaluate to ``true'' or ``false''.
969
970 @code{case} (@pxref{if cond case}) provides conditional evaluation of
971 argument expressions depending on whether a variable has one of a
972 specified group of values.
973
974 @code{and} (@pxref{and or}) executes a sequence of expressions in order
975 until either there are no expressions left, or one of them evaluates to
976 ``false''.
977
978 @code{or} (@pxref{and or}) executes a sequence of expressions in order
979 until either there are no expressions left, or one of them evaluates to
980 ``true''.
981
982
983 @node About Closure
984 @subsection The Concept of Closure
985
986 @cindex closure
987
988 The concept of @dfn{closure} is the idea that a lambda expression
989 ``captures'' the variable bindings that are in lexical scope at the
990 point where the lambda expression occurs. The procedure created by the
991 lambda expression can refer to and mutate the captured bindings, and the
992 values of those bindings persist between procedure calls.
993
994 This section explains and explores the various parts of this idea in
995 more detail.
996
997 @menu
998 * About Environments:: Names, locations, values and environments.
999 * Local Variables:: Local variables and local environments.
1000 * Chaining:: Environment chaining.
1001 * Lexical Scope:: The meaning of lexical scoping.
1002 * Closure:: Explaining the concept of closure.
1003 * Serial Number:: Example 1: a serial number generator.
1004 * Shared Variable:: Example 2: a shared persistent variable.
1005 * Callback Closure:: Example 3: the callback closure problem.
1006 * OO Closure:: Example 4: object orientation.
1007 @end menu
1008
1009 @node About Environments
1010 @subsubsection Names, Locations, Values and Environments
1011
1012 @cindex location
1013 @cindex environment
1014 @cindex vcell
1015 @cindex top level environment
1016 @cindex environment, top level
1017
1018 We said earlier that a variable name in a Scheme program is associated
1019 with a location in which any kind of Scheme value may be stored.
1020 (Incidentally, the term ``vcell'' is often used in Lisp and Scheme
1021 circles as an alternative to ``location''.) Thus part of what we mean
1022 when we talk about ``creating a variable'' is in fact establishing an
1023 association between a name, or identifier, that is used by the Scheme
1024 program code, and the variable location to which that name refers.
1025 Although the value that is stored in that location may change, the
1026 location to which a given name refers is always the same.
1027
1028 We can illustrate this by breaking down the operation of the
1029 @code{define} syntax into three parts: @code{define}
1030
1031 @itemize @bullet
1032 @item
1033 creates a new location
1034
1035 @item
1036 establishes an association between that location and the name specified
1037 as the first argument of the @code{define} expression
1038
1039 @item
1040 stores in that location the value obtained by evaluating the second
1041 argument of the @code{define} expression.
1042 @end itemize
1043
1044 A collection of associations between names and locations is called an
1045 @dfn{environment}. When you create a top level variable in a program
1046 using @code{define}, the name-location association for that variable is
1047 added to the ``top level'' environment. The ``top level'' environment
1048 also includes name-location associations for all the procedures that are
1049 supplied by standard Scheme.
1050
1051 It is also possible to create environments other than the top level one,
1052 and to create variable bindings, or name-location associations, in those
1053 environments. This ability is a key ingredient in the concept of
1054 closure; the next subsection shows how it is done.
1055
1056
1057 @node Local Variables
1058 @subsubsection Local Variables and Environments
1059
1060 @cindex local variable
1061 @cindex variable, local
1062 @cindex local environment
1063 @cindex environment, local
1064
1065 We have seen how to create top level variables using the @code{define}
1066 syntax (@pxref{Definition}). It is often useful to create variables
1067 that are more limited in their scope, typically as part of a procedure
1068 body. In Scheme, this is done using the @code{let} syntax, or one of
1069 its modified forms @code{let*} and @code{letrec}. These syntaxes are
1070 described in full later in the manual (@pxref{Local Bindings}). Here
1071 our purpose is to illustrate their use just enough that we can see how
1072 local variables work.
1073
1074 For example, the following code uses a local variable @code{s} to
1075 simplify the computation of the area of a triangle given the lengths of
1076 its three sides.
1077
1078 @lisp
1079 (define a 5.3)
1080 (define b 4.7)
1081 (define c 2.8)
1082
1083 (define area
1084 (let ((s (/ (+ a b c) 2)))
1085 (sqrt (* s (- s a) (- s b) (- s c)))))
1086 @end lisp
1087
1088 The effect of the @code{let} expression is to create a new environment
1089 and, within this environment, an association between the name @code{s}
1090 and a new location whose initial value is obtained by evaluating
1091 @code{(/ (+ a b c) 2)}. The expressions in the body of the @code{let},
1092 namely @code{(sqrt (* s (- s a) (- s b) (- s c)))}, are then evaluated
1093 in the context of the new environment, and the value of the last
1094 expression evaluated becomes the value of the whole @code{let}
1095 expression, and therefore the value of the variable @code{area}.
1096
1097
1098 @node Chaining
1099 @subsubsection Environment Chaining
1100
1101 @cindex shadowing an imported variable binding
1102 @cindex chaining environments
1103
1104 In the example of the previous subsection, we glossed over an important
1105 point. The body of the @code{let} expression in that example refers not
1106 only to the local variable @code{s}, but also to the top level variables
1107 @code{a}, @code{b}, @code{c} and @code{sqrt}. (@code{sqrt} is the
1108 standard Scheme procedure for calculating a square root.) If the body
1109 of the @code{let} expression is evaluated in the context of the
1110 @emph{local} @code{let} environment, how does the evaluation get at the
1111 values of these top level variables?
1112
1113 The answer is that the local environment created by a @code{let}
1114 expression automatically has a reference to its containing environment
1115 --- in this case the top level environment --- and that the Scheme
1116 interpreter automatically looks for a variable binding in the containing
1117 environment if it doesn't find one in the local environment. More
1118 generally, every environment except for the top level one has a
1119 reference to its containing environment, and the interpreter keeps
1120 searching back up the chain of environments --- from most local to top
1121 level --- until it either finds a variable binding for the required
1122 identifier or exhausts the chain.
1123
1124 This description also determines what happens when there is more than
1125 one variable binding with the same name. Suppose, continuing the
1126 example of the previous subsection, that there was also a pre-existing
1127 top level variable @code{s} created by the expression:
1128
1129 @lisp
1130 (define s "Some beans, my lord!")
1131 @end lisp
1132
1133 Then both the top level environment and the local @code{let} environment
1134 would contain bindings for the name @code{s}. When evaluating code
1135 within the @code{let} body, the interpreter looks first in the local
1136 @code{let} environment, and so finds the binding for @code{s} created by
1137 the @code{let} syntax. Even though this environment has a reference to
1138 the top level environment, which also has a binding for @code{s}, the
1139 interpreter doesn't get as far as looking there. When evaluating code
1140 outside the @code{let} body, the interpreter looks up variable names in
1141 the top level environment, so the name @code{s} refers to the top level
1142 variable.
1143
1144 Within the @code{let} body, the binding for @code{s} in the local
1145 environment is said to @dfn{shadow} the binding for @code{s} in the top
1146 level environment.
1147
1148
1149 @node Lexical Scope
1150 @subsubsection Lexical Scope
1151
1152 The rules that we have just been describing are the details of how
1153 Scheme implements ``lexical scoping''. This subsection takes a brief
1154 diversion to explain what lexical scope means in general and to present
1155 an example of non-lexical scoping.
1156
1157 ``Lexical scope'' in general is the idea that
1158
1159 @itemize @bullet
1160 @item
1161 an identifier at a particular place in a program always refers to the
1162 same variable location --- where ``always'' means ``every time that the
1163 containing expression is executed'', and that
1164
1165 @item
1166 the variable location to which it refers can be determined by static
1167 examination of the source code context in which that identifier appears,
1168 without having to consider the flow of execution through the program as
1169 a whole.
1170 @end itemize
1171
1172 In practice, lexical scoping is the norm for most programming languages,
1173 and probably corresponds to what you would intuitively consider to be
1174 ``normal''. You may even be wondering how the situation could possibly
1175 --- and usefully --- be otherwise. To demonstrate that another kind of
1176 scoping is possible, therefore, and to compare it against lexical
1177 scoping, the following subsection presents an example of non-lexical
1178 scoping and examines in detail how its behavior differs from the
1179 corresponding lexically scoped code.
1180
1181 @c @menu
1182 @c * Scoping Example:: An example of non-lexical scoping.
1183 @c @end menu
1184
1185
1186 @c @node Scoping Example
1187 @subsubheading An Example of Non-Lexical Scoping
1188
1189 To demonstrate that non-lexical scoping does exist and can be useful, we
1190 present the following example from Emacs Lisp, which is a ``dynamically
1191 scoped'' language.
1192
1193 @lisp
1194 (defvar currency-abbreviation "USD")
1195
1196 (defun currency-string (units hundredths)
1197 (concat currency-abbreviation
1198 (number-to-string units)
1199 "."
1200 (number-to-string hundredths)))
1201
1202 (defun french-currency-string (units hundredths)
1203 (let ((currency-abbreviation "FRF"))
1204 (currency-string units hundredths)))
1205 @end lisp
1206
1207 The question to focus on here is: what does the identifier
1208 @code{currency-abbreviation} refer to in the @code{currency-string}
1209 function? The answer, in Emacs Lisp, is that all variable bindings go
1210 onto a single stack, and that @code{currency-abbreviation} refers to the
1211 topmost binding from that stack which has the name
1212 ``currency-abbreviation''. The binding that is created by the
1213 @code{defvar} form, to the value @code{"USD"}, is only relevant if none
1214 of the code that calls @code{currency-string} rebinds the name
1215 ``currency-abbreviation'' in the meanwhile.
1216
1217 The second function @code{french-currency-string} works precisely by
1218 taking advantage of this behaviour. It creates a new binding for the
1219 name ``currency-abbreviation'' which overrides the one established by
1220 the @code{defvar} form.
1221
1222 @lisp
1223 ;; Note! This is Emacs Lisp evaluation, not Scheme!
1224 (french-currency-string 33 44)
1225 @result{}
1226 "FRF33.44"
1227 @end lisp
1228
1229 Now let's look at the corresponding, @emph{lexically scoped} Scheme
1230 code:
1231
1232 @lisp
1233 (define currency-abbreviation "USD")
1234
1235 (define (currency-string units hundredths)
1236 (string-append currency-abbreviation
1237 (number->string units)
1238 "."
1239 (number->string hundredths)))
1240
1241 (define (french-currency-string units hundredths)
1242 (let ((currency-abbreviation "FRF"))
1243 (currency-string units hundredths)))
1244 @end lisp
1245
1246 According to the rules of lexical scoping, the
1247 @code{currency-abbreviation} in @code{currency-string} refers to the
1248 variable location in the innermost environment at that point in the code
1249 which has a binding for @code{currency-abbreviation}, which is the
1250 variable location in the top level environment created by the preceding
1251 @code{(define currency-abbreviation @dots{})} expression.
1252
1253 In Scheme, therefore, the @code{french-currency-string} procedure does
1254 not work as intended. The variable binding that it creates for
1255 ``currency-abbreviation'' is purely local to the code that forms the
1256 body of the @code{let} expression. Since this code doesn't directly use
1257 the name ``currency-abbreviation'' at all, the binding is pointless.
1258
1259 @lisp
1260 (french-currency-string 33 44)
1261 @result{}
1262 "USD33.44"
1263 @end lisp
1264
1265 This begs the question of how the Emacs Lisp behaviour can be
1266 implemented in Scheme. In general, this is a design question whose
1267 answer depends upon the problem that is being addressed. In this case,
1268 the best answer may be that @code{currency-string} should be
1269 redesigned so that it can take an optional third argument. This third
1270 argument, if supplied, is interpreted as a currency abbreviation that
1271 overrides the default.
1272
1273 It is possible to change @code{french-currency-string} so that it mostly
1274 works without changing @code{currency-string}, but the fix is inelegant,
1275 and susceptible to interrupts that could leave the
1276 @code{currency-abbreviation} variable in the wrong state:
1277
1278 @lisp
1279 (define (french-currency-string units hundredths)
1280 (set! currency-abbreviation "FRF")
1281 (let ((result (currency-string units hundredths)))
1282 (set! currency-abbreviation "USD")
1283 result))
1284 @end lisp
1285
1286 The key point here is that the code does not create any local binding
1287 for the identifier @code{currency-abbreviation}, so all occurrences of
1288 this identifier refer to the top level variable.
1289
1290
1291 @node Closure
1292 @subsubsection Closure
1293
1294 Consider a @code{let} expression that doesn't contain any
1295 @code{lambda}s:
1296
1297 @lisp
1298 (let ((s (/ (+ a b c) 2)))
1299 (sqrt (* s (- s a) (- s b) (- s c))))
1300 @end lisp
1301
1302 @noindent
1303 When the Scheme interpreter evaluates this, it
1304
1305 @itemize @bullet
1306 @item
1307 creates a new environment with a reference to the environment that was
1308 current when it encountered the @code{let}
1309
1310 @item
1311 creates a variable binding for @code{s} in the new environment, with
1312 value given by @code{(/ (+ a b c) 2)}
1313
1314 @item
1315 evaluates the expression in the body of the @code{let} in the context of
1316 the new local environment, and remembers the value @code{V}
1317
1318 @item
1319 forgets the local environment
1320
1321 @item
1322 continues evaluating the expression that contained the @code{let}, using
1323 the value @code{V} as the value of the @code{let} expression, in the
1324 context of the containing environment.
1325 @end itemize
1326
1327 After the @code{let} expression has been evaluated, the local
1328 environment that was created is simply forgotten, and there is no longer
1329 any way to access the binding that was created in this environment. If
1330 the same code is evaluated again, it will follow the same steps again,
1331 creating a second new local environment that has no connection with the
1332 first, and then forgetting this one as well.
1333
1334 If the @code{let} body contains a @code{lambda} expression, however, the
1335 local environment is @emph{not} forgotten. Instead, it becomes
1336 associated with the procedure that is created by the @code{lambda}
1337 expression, and is reinstated every time that that procedure is called.
1338 In detail, this works as follows.
1339
1340 @itemize @bullet
1341 @item
1342 When the Scheme interpreter evaluates a @code{lambda} expression, to
1343 create a procedure object, it stores the current environment as part of
1344 the procedure definition.
1345
1346 @item
1347 Then, whenever that procedure is called, the interpreter reinstates the
1348 environment that is stored in the procedure definition and evaluates the
1349 procedure body within the context of that environment.
1350 @end itemize
1351
1352 The result is that the procedure body is always evaluated in the context
1353 of the environment that was current when the procedure was created.
1354
1355 This is what is meant by @dfn{closure}. The next few subsections
1356 present examples that explore the usefulness of this concept.
1357
1358
1359 @node Serial Number
1360 @subsubsection Example 1: A Serial Number Generator
1361
1362 This example uses closure to create a procedure with a variable binding
1363 that is private to the procedure, like a local variable, but whose value
1364 persists between procedure calls.
1365
1366 @lisp
1367 (define (make-serial-number-generator)
1368 (let ((current-serial-number 0))
1369 (lambda ()
1370 (set! current-serial-number (+ current-serial-number 1))
1371 current-serial-number)))
1372
1373 (define entry-sn-generator (make-serial-number-generator))
1374
1375 (entry-sn-generator)
1376 @result{}
1377 1
1378
1379 (entry-sn-generator)
1380 @result{}
1381 2
1382 @end lisp
1383
1384 When @code{make-serial-number-generator} is called, it creates a local
1385 environment with a binding for @code{current-serial-number} whose
1386 initial value is 0, then, within this environment, creates a procedure.
1387 The local environment is stored within the created procedure object and
1388 so persists for the lifetime of the created procedure.
1389
1390 Every time the created procedure is invoked, it increments the value of
1391 the @code{current-serial-number} binding in the captured environment and
1392 then returns the current value.
1393
1394 Note that @code{make-serial-number-generator} can be called again to
1395 create a second serial number generator that is independent of the
1396 first. Every new invocation of @code{make-serial-number-generator}
1397 creates a new local @code{let} environment and returns a new procedure
1398 object with an association to this environment.
1399
1400
1401 @node Shared Variable
1402 @subsubsection Example 2: A Shared Persistent Variable
1403
1404 This example uses closure to create two procedures, @code{get-balance}
1405 and @code{deposit}, that both refer to the same captured local
1406 environment so that they can both access the @code{balance} variable
1407 binding inside that environment. The value of this variable binding
1408 persists between calls to either procedure.
1409
1410 Note that the captured @code{balance} variable binding is private to
1411 these two procedures: it is not directly accessible to any other code.
1412 It can only be accessed indirectly via @code{get-balance} or
1413 @code{deposit}, as illustrated by the @code{withdraw} procedure.
1414
1415 @lisp
1416 (define get-balance #f)
1417 (define deposit #f)
1418
1419 (let ((balance 0))
1420 (set! get-balance
1421 (lambda ()
1422 balance))
1423 (set! deposit
1424 (lambda (amount)
1425 (set! balance (+ balance amount))
1426 balance)))
1427
1428 (define (withdraw amount)
1429 (deposit (- amount)))
1430
1431 (get-balance)
1432 @result{}
1433 0
1434
1435 (deposit 50)
1436 @result{}
1437 50
1438
1439 (withdraw 75)
1440 @result{}
1441 -25
1442 @end lisp
1443
1444 An important detail here is that the @code{get-balance} and
1445 @code{deposit} variables must be set up by @code{define}ing them at top
1446 level and then @code{set!}ing their values inside the @code{let} body.
1447 Using @code{define} within the @code{let} body would not work: this
1448 would create variable bindings within the local @code{let} environment
1449 that would not be accessible at top level.
1450
1451
1452 @node Callback Closure
1453 @subsubsection Example 3: The Callback Closure Problem
1454
1455 A frequently used programming model for library code is to allow an
1456 application to register a callback function for the library to call when
1457 some particular event occurs. It is often useful for the application to
1458 make several such registrations using the same callback function, for
1459 example if several similar library events can be handled using the same
1460 application code, but the need then arises to distinguish the callback
1461 function calls that are associated with one callback registration from
1462 those that are associated with different callback registrations.
1463
1464 In languages without the ability to create functions dynamically, this
1465 problem is usually solved by passing a @code{user_data} parameter on the
1466 registration call, and including the value of this parameter as one of
1467 the parameters on the callback function. Here is an example of
1468 declarations using this solution in C:
1469
1470 @example
1471 typedef void (event_handler_t) (int event_type,
1472 void *user_data);
1473
1474 void register_callback (int event_type,
1475 event_handler_t *handler,
1476 void *user_data);
1477 @end example
1478
1479 In Scheme, closure can be used to achieve the same functionality without
1480 requiring the library code to store a @code{user-data} for each callback
1481 registration.
1482
1483 @lisp
1484 ;; In the library:
1485
1486 (define (register-callback event-type handler-proc)
1487 @dots{})
1488
1489 ;; In the application:
1490
1491 (define (make-handler event-type user-data)
1492 (lambda ()
1493 @dots{}
1494 <code referencing event-type and user-data>
1495 @dots{}))
1496
1497 (register-callback event-type
1498 (make-handler event-type @dots{}))
1499 @end lisp
1500
1501 As far as the library is concerned, @code{handler-proc} is a procedure
1502 with no arguments, and all the library has to do is call it when the
1503 appropriate event occurs. From the application's point of view, though,
1504 the handler procedure has used closure to capture an environment that
1505 includes all the context that the handler code needs ---
1506 @code{event-type} and @code{user-data} --- to handle the event
1507 correctly.
1508
1509
1510 @node OO Closure
1511 @subsubsection Example 4: Object Orientation
1512
1513 Closure is the capture of an environment, containing persistent variable
1514 bindings, within the definition of a procedure or a set of related
1515 procedures. This is rather similar to the idea in some object oriented
1516 languages of encapsulating a set of related data variables inside an
1517 ``object'', together with a set of ``methods'' that operate on the
1518 encapsulated data. The following example shows how closure can be used
1519 to emulate the ideas of objects, methods and encapsulation in Scheme.
1520
1521 @lisp
1522 (define (make-account)
1523 (let ((balance 0))
1524 (define (get-balance)
1525 balance)
1526 (define (deposit amount)
1527 (set! balance (+ balance amount))
1528 balance)
1529 (define (withdraw amount)
1530 (deposit (- amount)))
1531
1532 (lambda args
1533 (apply
1534 (case (car args)
1535 ((get-balance) get-balance)
1536 ((deposit) deposit)
1537 ((withdraw) withdraw)
1538 (else (error "Invalid method!")))
1539 (cdr args)))))
1540 @end lisp
1541
1542 Each call to @code{make-account} creates and returns a new procedure,
1543 created by the expression in the example code that begins ``(lambda
1544 args''.
1545
1546 @lisp
1547 (define my-account (make-account))
1548
1549 my-account
1550 @result{}
1551 #<procedure args>
1552 @end lisp
1553
1554 This procedure acts as an account object with methods
1555 @code{get-balance}, @code{deposit} and @code{withdraw}. To apply one of
1556 the methods to the account, you call the procedure with a symbol
1557 indicating the required method as the first parameter, followed by any
1558 other parameters that are required by that method.
1559
1560 @lisp
1561 (my-account 'get-balance)
1562 @result{}
1563 0
1564
1565 (my-account 'withdraw 5)
1566 @result{}
1567 -5
1568
1569 (my-account 'deposit 396)
1570 @result{}
1571 391
1572
1573 (my-account 'get-balance)
1574 @result{}
1575 391
1576 @end lisp
1577
1578 Note how, in this example, both the current balance and the helper
1579 procedures @code{get-balance}, @code{deposit} and @code{withdraw}, used
1580 to implement the guts of the account object's methods, are all stored in
1581 variable bindings within the private local environment captured by the
1582 @code{lambda} expression that creates the account object procedure.
1583
1584
1585 @c Local Variables:
1586 @c TeX-master: "guile.texi"
1587 @c End: