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.
10 In this chapter, we introduce the basic concepts that underpin the
11 elegance and power of the Scheme language.
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.
19 The style of this introductory material aims about halfway between the
20 terse precision of R5RS and the discursive randomness of a Scheme
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 * Further Reading:: Where to find out more about Scheme.
33 @subsection Data Types, Values and Variables
35 This section discusses the representation of data types and values, what
36 it means for Scheme to be a @dfn{latently typed} language, and the role
37 of variables. We conclude by introducing the Scheme syntaxes for
38 defining a new variable, and for changing the value of an existing
42 * Latent Typing:: Scheme as a "latently typed" language.
43 * Values and Variables:: About data types, values and variables.
44 * Definition:: Defining variables and setting their values.
49 @subsubsection Latent Typing
51 The term @dfn{latent typing} is used to describe a computer language,
52 such as Scheme, for which you cannot, @emph{in general}, simply look at
53 a program's source code and determine what type of data will be
54 associated with a particular variable, or with the result of a
55 particular expression.
57 Sometimes, of course, you @emph{can} tell from the code what the type of
58 an expression will be. If you have a line in your program that sets the
59 variable @code{x} to the numeric value 1, you can be certain that,
60 immediately after that line has executed (and in the absence of multiple
61 threads), @code{x} has the numeric value 1. Or if you write a procedure
62 that is designed to concatenate two strings, it is likely that the rest
63 of your application will always invoke this procedure with two string
64 parameters, and quite probable that the procedure would go wrong in some
65 way if it was ever invoked with parameters that were not both strings.
67 Nevertheless, the point is that there is nothing in Scheme which
68 requires the procedure parameters always to be strings, or @code{x}
69 always to hold a numeric value, and there is no way of declaring in your
70 program that such constraints should always be obeyed. In the same
71 vein, there is no way to declare the expected type of a procedure's
74 Instead, the types of variables and expressions are only known -- in
75 general -- at run time. If you @emph{need} to check at some point that
76 a value has the expected type, Scheme provides run time procedures that
77 you can invoke to do so. But equally, it can be perfectly valid for two
78 separate invocations of the same procedure to specify arguments with
79 different types, and to return values with different types.
81 The next subsection explains what this means in practice, for the ways
82 that Scheme programs use data types, values and variables.
85 @node Values and Variables
86 @subsubsection Values and Variables
88 Scheme provides many data types that you can use to represent your data.
89 Primitive types include characters, strings, numbers and procedures.
90 Compound types, which allow a group of primitive and compound values to
91 be stored together, include lists, pairs, vectors and multi-dimensional
92 arrays. In addition, Guile allows applications to define their own data
93 types, with the same status as the built-in standard Scheme types.
95 As a Scheme program runs, values of all types pop in and out of
96 existence. Sometimes values are stored in variables, but more commonly
97 they pass seamlessly from being the result of one computation to being
98 one of the parameters for the next.
100 Consider an example. A string value is created because the interpreter
101 reads in a literal string from your program's source code. Then a
102 numeric value is created as the result of calculating the length of the
103 string. A second numeric value is created by doubling the calculated
104 length. Finally the program creates a list with two elements -- the
105 doubled length and the original string itself -- and stores this list in
108 All of the values involved here -- in fact, all values in Scheme --
109 carry their type with them. In other words, every value ``knows,'' at
110 runtime, what kind of value it is. A number, a string, a list,
113 A variable, on the other hand, has no fixed type. A variable --
114 @code{x}, say -- is simply the name of a location -- a box -- in which
115 you can store any kind of Scheme value. So the same variable in a
116 program may hold a number at one moment, a list of procedures the next,
117 and later a pair of strings. The ``type'' of a variable -- insofar as
118 the idea is meaningful at all -- is simply the type of whatever value
119 the variable happens to be storing at a particular moment.
123 @subsubsection Defining and Setting Variables
125 To define a new variable, you use Scheme's @code{define} syntax like
129 (define @var{variable-name} @var{value})
132 This makes a new variable called @var{variable-name} and stores
133 @var{value} in it as the variable's initial value. For example:
136 ;; Make a variable `x' with initial numeric value 1.
139 ;; Make a variable `organization' with an initial string value.
140 (define organization "Free Software Foundation")
143 (In Scheme, a semicolon marks the beginning of a comment that continues
144 until the end of the line. So the lines beginning @code{;;} are
147 Changing the value of an already existing variable is very similar,
148 except that @code{define} is replaced by the Scheme syntax @code{set!},
152 (set! @var{variable-name} @var{new-value})
155 Remember that variables do not have fixed types, so @var{new-value} may
156 have a completely different type from whatever was previously stored in
157 the location named by @var{variable-name}. Both of the following
158 examples are therefore correct.
161 ;; Change the value of `x' to 5.
164 ;; Change the value of `organization' to the FSF's street number.
165 (set! organization 545)
168 In these examples, @var{value} and @var{new-value} are literal numeric
169 or string values. In general, however, @var{value} and @var{new-value}
170 can be any Scheme expression. Even though we have not yet covered the
171 forms that Scheme expressions can take (@pxref{About Expressions}), you
172 can probably guess what the following @code{set!} example does@dots{}
178 (Note: this is not a complete description of @code{define} and
179 @code{set!}, because we need to introduce some other aspects of Scheme
180 before the missing pieces can be filled in. If, however, you are
181 already familiar with the structure of Scheme, you may like to read
182 about those missing pieces immediately by jumping ahead to the following
187 @ref{Lambda Alternatives}, to read about an alternative form of the
188 @code{define} syntax that can be used when defining new procedures.
191 @ref{Procedures with Setters}, to read about an alternative form of the
192 @code{set!} syntax that helps with changing a single value in the depths
193 of a compound data structure.)
196 @xref{Internal Definitions}, to read about using @code{define} other
197 than at top level in a Scheme program, including a discussion of when it
198 works to use @code{define} rather than @code{set!} to change the value
199 of an existing variable.
203 @node About Procedures
204 @subsection The Representation and Use of Procedures
206 This section introduces the basics of using and creating Scheme
207 procedures. It discusses the representation of procedures as just
208 another kind of Scheme value, and shows how procedure invocation
209 expressions are constructed. We then explain how @code{lambda} is used
210 to create new procedures, and conclude by presenting the various
211 shorthand forms of @code{define} that can be used instead of writing an
212 explicit @code{lambda} expression.
215 * Procedures as Values:: Procedures are values like everything else.
216 * Simple Invocation:: How to write a simple procedure invocation.
217 * Creating a Procedure:: How to create your own procedures.
218 * Lambda Alternatives:: Other ways of writing procedure definitions.
222 @node Procedures as Values
223 @subsubsection Procedures as Values
225 One of the great simplifications of Scheme is that a procedure is just
226 another type of value, and that procedure values can be passed around
227 and stored in variables in exactly the same way as, for example, strings
228 and lists. When we talk about a built-in standard Scheme procedure such
229 as @code{open-input-file}, what we actually mean is that there is a
230 pre-defined top level variable called @code{open-input-file}, whose
231 value is a procedure that implements what R5RS says that
232 @code{open-input-file} should do.
234 Note that this is quite different from many dialects of Lisp ---
235 including Emacs Lisp --- in which a program can use the same name with
236 two quite separate meanings: one meaning identifies a Lisp function,
237 while the other meaning identifies a Lisp variable, whose value need
238 have nothing to do with the function that is associated with the first
239 meaning. In these dialects, functions and variables are said to live in
240 different @dfn{namespaces}.
242 In Scheme, on the other hand, all names belong to a single unified
243 namespace, and the variables that these names identify can hold any kind
244 of Scheme value, including procedure values.
246 One consequence of the ``procedures as values'' idea is that, if you
247 don't happen to like the standard name for a Scheme procedure, you can
250 For example, @code{call-with-current-continuation} is a very important
251 standard Scheme procedure, but it also has a very long name! So, many
252 programmers use the following definition to assign the same procedure
253 value to the more convenient name @code{call/cc}.
256 (define call/cc call-with-current-continuation)
259 Let's understand exactly how this works. The definition creates a new
260 variable @code{call/cc}, and then sets its value to the value of the
261 variable @code{call-with-current-continuation}; the latter value is a
262 procedure that implements the behaviour that R5RS specifies under the
263 name ``call-with-current-continuation''. So @code{call/cc} ends up
264 holding this value as well.
266 Now that @code{call/cc} holds the required procedure value, you could
267 choose to use @code{call-with-current-continuation} for a completely
268 different purpose, or just change its value so that you will get an
269 error if you accidentally use @code{call-with-current-continuation} as a
270 procedure in your program rather than @code{call/cc}. For example:
273 (set! call-with-current-continuation "Not a procedure any more!")
276 Or you could just leave @code{call-with-current-continuation} as it was.
277 It's perfectly fine for more than one variable to hold the same
281 @node Simple Invocation
282 @subsubsection Simple Procedure Invocation
284 A procedure invocation in Scheme is written like this:
287 (@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
290 In this expression, @var{procedure} can be any Scheme expression whose
291 value is a procedure. Most commonly, however, @var{procedure} is simply
292 the name of a variable whose value is a procedure.
294 For example, @code{string-append} is a standard Scheme procedure whose
295 behaviour is to concatenate together all the arguments, which are
296 expected to be strings, that it is given. So the expression
299 (string-append "/home" "/" "andrew")
303 is a procedure invocation whose result is the string value
304 @code{"/home/andrew"}.
306 Similarly, @code{string-length} is a standard Scheme procedure that
307 returns the length of a single string argument, so
310 (string-length "abc")
314 is a procedure invocation whose result is the numeric value 3.
316 Each of the parameters in a procedure invocation can itself be any
317 Scheme expression. Since a procedure invocation is itself a type of
318 expression, we can put these two examples together to get
321 (string-length (string-append "/home" "/" "andrew"))
325 --- a procedure invocation whose result is the numeric value 12.
327 (You may be wondering what happens if the two examples are combined the
328 other way round. If we do this, we can make a procedure invocation
329 expression that is @emph{syntactically} correct:
332 (string-append "/home" (string-length "abc"))
336 but when this expression is executed, it will cause an error, because
337 the result of @code{(string-length "abc")} is a numeric value, and
338 @code{string-append} is not designed to accept a numeric value as one of
342 @node Creating a Procedure
343 @subsubsection Creating and Using a New Procedure
345 Scheme has lots of standard procedures, and Guile provides all of these
346 via predefined top level variables. All of these standard procedures
347 are documented in the later chapters of this reference manual.
349 Before very long, though, you will want to create new procedures that
350 encapsulate aspects of your own applications' functionality. To do
351 this, you can use the famous @code{lambda} syntax.
353 For example, the value of the following Scheme expression
356 (lambda (name address) @var{expression} @dots{})
360 is a newly created procedure that takes two arguments:
361 @code{name} and @code{address}. The behaviour of the
362 new procedure is determined by the sequence of @var{expression}s in the
363 @dfn{body} of the procedure definition. (Typically, these
364 @var{expression}s would use the arguments in some way, or else there
365 wouldn't be any point in giving them to the procedure.) When invoked,
366 the new procedure returns a value that is the value of the last
367 @var{expression} in the procedure body.
369 To make things more concrete, let's suppose that the two arguments are
370 both strings, and that the purpose of this procedure is to form a
371 combined string that includes these arguments. Then the full lambda
372 expression might look like this:
375 (lambda (name address)
376 (string-append "Name=" name ":Address=" address))
379 We noted in the previous subsection that the @var{procedure} part of a
380 procedure invocation expression can be any Scheme expression whose value
381 is a procedure. But that's exactly what a lambda expression is! So we
382 can use a lambda expression directly in a procedure invocation, like
386 ((lambda (name address)
387 (string-append "Name=" name ":Address=" address))
393 This is a valid procedure invocation expression, and its result is the
397 "Name=FSF:Address=Cambridge"
400 It is more common, though, to store the procedure value in a variable ---
403 (define make-combined-string
404 (lambda (name address)
405 (string-append "Name=" name ":Address=" address)))
409 --- and then to use the variable name in the procedure invocation:
412 (make-combined-string "FSF" "Cambridge")
416 Which has exactly the same result.
418 It's important to note that procedures created using @code{lambda} have
419 exactly the same status as the standard built in Scheme procedures, and
420 can be invoked, passed around, and stored in variables in exactly the
424 @node Lambda Alternatives
425 @subsubsection Lambda Alternatives
427 Since it is so common in Scheme programs to want to create a procedure
428 and then store it in a variable, there is an alternative form of the
429 @code{define} syntax that allows you to do just that.
431 A @code{define} expression of the form
434 (define (@var{name} [@var{arg1} [@var{arg2} @dots{}]])
435 @var{expression} @dots{})
439 is exactly equivalent to the longer form
443 (lambda ([@var{arg1} [@var{arg2} @dots{}]])
444 @var{expression} @dots{}))
447 So, for example, the definition of @code{make-combined-string} in the
448 previous subsection could equally be written:
451 (define (make-combined-string name address)
452 (string-append "Name=" name ":Address=" address))
455 This kind of procedure definition creates a procedure that requires
456 exactly the expected number of arguments. There are two further forms
457 of the @code{lambda} expression, which create a procedure that can
458 accept a variable number of arguments:
461 (lambda (@var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
463 (lambda @var{args} @var{expression} @dots{})
467 The corresponding forms of the alternative @code{define} syntax are:
470 (define (@var{name} @var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
472 (define (@var{name} . @var{args}) @var{expression} @dots{})
476 For details on how these forms work, see @xref{Lambda}.
478 (It could be argued that the alternative @code{define} forms are rather
479 confusing, especially for newcomers to the Scheme language, as they hide
480 both the role of @code{lambda} and the fact that procedures are values
481 that are stored in variables in the some way as any other kind of value.
482 On the other hand, they are very convenient, and they are also a good
483 example of another of Scheme's powerful features: the ability to specify
484 arbitrary syntactic transformations at run time, which can be applied to
485 subsequently read input.)
488 @node About Expressions
489 @subsection Expressions and Evaluation
491 So far, we have met expressions that @emph{do} things, such as the
492 @code{define} expressions that create and initialize new variables, and
493 we have also talked about expressions that have @emph{values}, for
494 example the value of the procedure invocation expression:
497 (string-append "/home" "/" "andrew")
501 but we haven't yet been precise about what causes an expression like
502 this procedure invocation to be reduced to its ``value'', or how the
503 processing of such expressions relates to the execution of a Scheme
506 This section clarifies what we mean by an expression's value, by
507 introducing the idea of @dfn{evaluation}. It discusses the side effects
508 that evaluation can have, explains how each of the various types of
509 Scheme expression is evaluated, and describes the behaviour and use of
510 the Guile REPL as a mechanism for exploring evaluation. The section
511 concludes with a very brief summary of Scheme's common syntactic
515 * Evaluating:: How a Scheme program is executed.
516 * Tail Calls:: Space-safe recursion.
517 * The REPL:: Interacting with the Guile interpreter.
518 * Syntax Summary:: Common syntactic expressions -- in brief.
523 @subsubsection Evaluating Expressions and Executing Programs
525 In Scheme, the process of executing an expression is known as
526 @dfn{evaluation}. Evaluation has two kinds of result:
530 the @dfn{value} of the evaluated expression
533 the @dfn{side effects} of the evaluation, which consist of any effects of
534 evaluating the expression that are not represented by the value.
537 Of the expressions that we have met so far, @code{define} and
538 @code{set!} expressions have side effects --- the creation or
539 modification of a variable --- but no value; @code{lambda} expressions
540 have values --- the newly constructed procedures --- but no side
541 effects; and procedure invocation expressions, in general, have either
542 values, or side effects, or both.
544 It is tempting to try to define more intuitively what we mean by
545 ``value'' and ``side effects'', and what the difference between them is.
546 In general, though, this is extremely difficult. It is also
547 unnecessary; instead, we can quite happily define the behaviour of a
548 Scheme program by specifying how Scheme executes a program as a whole,
549 and then by describing the value and side effects of evaluation for each
550 type of expression individually.
553 So, some@footnote{These definitions are approximate. For the whole
554 and detailed truth, see @ref{Formal syntax and semantics,R5RS
555 syntax,,r5rs,The Revised(5) Report on the Algorithmic Language
556 Scheme}.} definitions@dots{}
561 A Scheme program consists of a sequence of expressions.
564 A Scheme interpreter executes the program by evaluating these
565 expressions in order, one by one.
572 a piece of literal data, such as a number @code{2.3} or a string
573 @code{"Hello world!"}
577 a procedure invocation expression
579 one of Scheme's special syntactic expressions.
584 The following subsections describe how each of these types of expression
588 @c * Eval Literal:: Evaluating literal data.
589 @c * Eval Variable:: Evaluating variable references.
590 @c * Eval Procedure:: Evaluating procedure invocation expressions.
591 @c * Eval Special:: Evaluating special syntactic expressions.
594 @c @node Eval Literal
596 @subsubheading Evaluating Literal Data
598 When a literal data expression is evaluated, the value of the expression
599 is simply the value that the expression describes. The evaluation of a
600 literal data expression has no side effects.
607 the value of the expression @code{"abc"} is the string value
611 the value of the expression @code{3+4i} is the complex number 3 + 4i
614 the value of the expression @code{#(1 2 3)} is a three-element vector
615 containing the numeric values 1, 2 and 3.
618 For any data type which can be expressed literally like this, the syntax
619 of the literal data expression for that data type --- in other words,
620 what you need to write in your code to indicate a literal value of that
621 type --- is known as the data type's @dfn{read syntax}. This manual
622 specifies the read syntax for each such data type in the section that
623 describes that data type.
625 Some data types do not have a read syntax. Procedures, for example,
626 cannot be expressed as literal data; they must be created using a
627 @code{lambda} expression (@pxref{Creating a Procedure}) or implicitly
628 using the shorthand form of @code{define} (@pxref{Lambda Alternatives}).
631 @c @node Eval Variable
632 @subsubheading Evaluating a Variable Reference
634 When an expression that consists simply of a variable name is evaluated,
635 the value of the expression is the value of the named variable. The
636 evaluation of a variable reference expression has no side effects.
641 (define key "Paul Evans")
645 the value of the expression @code{key} is the string value @code{"Paul
646 Evans"}. If @var{key} is then modified by
653 the value of the expression @code{key} is the numeric value 3.74.
655 If there is no variable with the specified name, evaluation of the
656 variable reference expression signals an error.
659 @c @node Eval Procedure
660 @subsubheading Evaluating a Procedure Invocation Expression
662 This is where evaluation starts getting interesting! As already noted,
663 a procedure invocation expression has the form
666 (@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
670 where @var{procedure} must be an expression whose value, when evaluated,
673 The evaluation of a procedure invocation expression like this proceeds
678 evaluating individually the expressions @var{procedure}, @var{arg1},
679 @var{arg2}, and so on
682 calling the procedure that is the value of the @var{procedure}
683 expression with the list of values obtained from the evaluations of
684 @var{arg1}, @var{arg2} etc. as its parameters.
687 For a procedure defined in Scheme, ``calling the procedure with the list
688 of values as its parameters'' means binding the values to the
689 procedure's formal parameters and then evaluating the sequence of
690 expressions that make up the body of the procedure definition. The
691 value of the procedure invocation expression is the value of the last
692 evaluated expression in the procedure body. The side effects of calling
693 the procedure are the combination of the side effects of the sequence of
694 evaluations of expressions in the procedure body.
696 For a built-in procedure, the value and side-effects of calling the
697 procedure are best described by that procedure's documentation.
699 Note that the complete side effects of evaluating a procedure invocation
700 expression consist not only of the side effects of the procedure call,
701 but also of any side effects of the preceding evaluation of the
702 expressions @var{procedure}, @var{arg1}, @var{arg2}, and so on.
704 To illustrate this, let's look again at the procedure invocation
708 (string-length (string-append "/home" "/" "andrew"))
711 In the outermost expression, @var{procedure} is @code{string-length} and
712 @var{arg1} is @code{(string-append "/home" "/" "andrew")}.
716 Evaluation of @code{string-length}, which is a variable, gives a
717 procedure value that implements the expected behaviour for
721 Evaluation of @code{(string-append "/home" "/" "andrew")}, which is
722 another procedure invocation expression, means evaluating each of
726 @code{string-append}, which gives a procedure value that implements the
727 expected behaviour for ``string-append''
730 @code{"/home"}, which gives the string value @code{"/home"}
733 @code{"/"}, which gives the string value @code{"/"}
736 @code{"andrew"}, which gives the string value @code{"andrew"}
739 and then invoking the procedure value with this list of string values as
740 its arguments. The resulting value is a single string value that is the
741 concatenation of all the arguments, namely @code{"/home/andrew"}.
744 In the evaluation of the outermost expression, the interpreter can now
745 invoke the procedure value obtained from @var{procedure} with the value
746 obtained from @var{arg1} as its arguments. The resulting value is a
747 numeric value that is the length of the argument string, which is 12.
750 @c @node Eval Special
751 @subsubheading Evaluating Special Syntactic Expressions
753 When a procedure invocation expression is evaluated, the procedure and
754 @emph{all} the argument expressions must be evaluated before the
755 procedure can be invoked. Special syntactic expressions are special
756 because they are able to manipulate their arguments in an unevaluated
757 form, and can choose whether to evaluate any or all of the argument
760 Why is this needed? Consider a program fragment that asks the user
761 whether or not to delete a file, and then deletes the file if the user
765 (if (string=? (read-answer "Should I delete this file?")
770 If the outermost @code{(if @dots{})} expression here was a procedure
771 invocation expression, the expression @code{(delete-file file)}, whose
772 side effect is to actually delete a file, would already have been
773 evaluated before the @code{if} procedure even got invoked! Clearly this
774 is no use --- the whole point of an @code{if} expression is that the
775 @dfn{consequent} expression is only evaluated if the condition of the
776 @code{if} expression is ``true''.
778 Therefore @code{if} must be special syntax, not a procedure. Other
779 special syntaxes that we have already met are @code{define}, @code{set!}
780 and @code{lambda}. @code{define} and @code{set!} are syntax because
781 they need to know the variable @emph{name} that is given as the first
782 argument in a @code{define} or @code{set!} expression, not that
783 variable's value. @code{lambda} is syntax because it does not
784 immediately evaluate the expressions that define the procedure body;
785 instead it creates a procedure object that incorporates these
786 expressions so that they can be evaluated in the future, when that
787 procedure is invoked.
789 The rules for evaluating each special syntactic expression are specified
790 individually for each special syntax. For a summary of standard special
791 syntax, see @xref{Syntax Summary}.
795 @subsubsection Tail calls
799 Scheme is ``properly tail recursive'', meaning that tail calls or
800 recursions from certain contexts do not consume stack space or other
801 resources and can therefore be used on arbitrarily large data or for
802 an arbitrarily long calculation. Consider for example,
818 @code{foo} prints numbers infinitely, starting from the given @var{n}.
819 It's implemented by printing @var{n} then recursing to itself to print
820 @math{@var{n}+1} and so on. This recursion is a tail call, it's the
821 last thing done, and in Scheme such tail calls can be made without
824 Or consider a case where a value is returned, a version of the SRFI-1
825 @code{last} function (@pxref{SRFI-1 Selectors}) returning the last
829 (define (my-last lst)
830 (if (null? (cdr lst))
832 (my-last (cdr lst))))
834 (my-last '(1 2 3)) @result{} 3
837 If the list has more than one element, @code{my-last} applies itself
838 to the @code{cdr}. This recursion is a tail call, there's no code
839 after it, and the return value is the return value from that call. In
840 Scheme this can be used on an arbitrarily long list argument.
843 A proper tail call is only available from certain contexts, namely the
844 following special form positions,
848 @code{and} --- last expression
851 @code{begin} --- last expression
854 @code{case} --- last expression in each clause
857 @code{cond} --- last expression in each clause, and the call to a
858 @code{=>} procedure is a tail call
861 @code{do} --- last result expression
864 @code{if} --- ``true'' and ``false'' leg expressions
867 @code{lambda} --- last expression in body
870 @code{let}, @code{let*}, @code{letrec}, @code{let-syntax},
871 @code{letrec-syntax} --- last expression in body
874 @code{or} --- last expression
878 The following core functions make tail calls,
882 @code{apply} --- tail call to given procedure
885 @code{call-with-current-continuation} --- tail call to the procedure
886 receiving the new continuation
889 @code{call-with-values} --- tail call to the values-receiving
893 @code{eval} --- tail call to evaluate the form
896 @code{string-any}, @code{string-every} --- tail call to predicate on
897 the last character (if that point is reached)
901 The above are just core functions and special forms. Tail calls in
902 other modules are described with the relevant documentation, for
903 example SRFI-1 @code{any} and @code{every} (@pxref{SRFI-1 Searching}).
905 It will be noted there are a lot of places which could potentially be
906 tail calls, for instance the last call in a @code{for-each}, but only
907 those explicitly described are guaranteed.
911 @subsubsection Using the Guile REPL
913 If you start Guile without specifying a particular program for it to
914 execute, Guile enters its standard Read Evaluate Print Loop --- or
915 @dfn{REPL} for short. In this mode, Guile repeatedly reads in the next
916 Scheme expression that the user types, evaluates it, and prints the
919 The REPL is a useful mechanism for exploring the evaluation behaviour
920 described in the previous subsection. If you type @code{string-append},
921 for example, the REPL replies @code{#<primitive-procedure
922 string-append>}, illustrating the relationship between the variable
923 @code{string-append} and the procedure value stored in that variable.
925 In this manual, the notation @result{} is used to mean ``evaluates
926 to''. Wherever you see an example of the form
935 feel free to try it out yourself by typing @var{expression} into the
936 REPL and checking that it gives the expected @var{result}.
940 @subsubsection Summary of Common Syntax
942 This subsection lists the most commonly used Scheme syntactic
943 expressions, simply so that you will recognize common special syntax
944 when you see it. For a full description of each of these syntaxes,
945 follow the appropriate reference.
947 @code{lambda} (@pxref{Lambda}) is used to construct procedure objects.
949 @code{define} (@pxref{Top Level}) is used to create a new variable and
950 set its initial value.
952 @code{set!} (@pxref{Top Level}) is used to modify an existing variable's
955 @code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
956 create an inner lexical environment for the evaluation of a sequence of
957 expressions, in which a specified set of local variables is bound to the
958 values of a corresponding set of expressions. For an introduction to
959 environments, see @xref{About Closure}.
961 @code{begin} (@pxref{begin}) executes a sequence of expressions in order
962 and returns the value of the last expression. Note that this is not the
963 same as a procedure which returns its last argument, because the
964 evaluation of a procedure invocation expression does not guarantee to
965 evaluate the arguments in order.
967 @code{if} and @code{cond} (@pxref{if cond case}) provide conditional
968 evaluation of argument expressions depending on whether one or more
969 conditions evaluate to ``true'' or ``false''.
971 @code{case} (@pxref{if cond case}) provides conditional evaluation of
972 argument expressions depending on whether a variable has one of a
973 specified group of values.
975 @code{and} (@pxref{and or}) executes a sequence of expressions in order
976 until either there are no expressions left, or one of them evaluates to
979 @code{or} (@pxref{and or}) executes a sequence of expressions in order
980 until either there are no expressions left, or one of them evaluates to
985 @subsection The Concept of Closure
989 The concept of @dfn{closure} is the idea that a lambda expression
990 ``captures'' the variable bindings that are in lexical scope at the
991 point where the lambda expression occurs. The procedure created by the
992 lambda expression can refer to and mutate the captured bindings, and the
993 values of those bindings persist between procedure calls.
995 This section explains and explores the various parts of this idea in
999 * About Environments:: Names, locations, values and environments.
1000 * Local Variables:: Local variables and local environments.
1001 * Chaining:: Environment chaining.
1002 * Lexical Scope:: The meaning of lexical scoping.
1003 * Closure:: Explaining the concept of closure.
1004 * Serial Number:: Example 1: a serial number generator.
1005 * Shared Variable:: Example 2: a shared persistent variable.
1006 * Callback Closure:: Example 3: the callback closure problem.
1007 * OO Closure:: Example 4: object orientation.
1010 @node About Environments
1011 @subsubsection Names, Locations, Values and Environments
1016 @cindex top level environment
1017 @cindex environment, top level
1019 We said earlier that a variable name in a Scheme program is associated
1020 with a location in which any kind of Scheme value may be stored.
1021 (Incidentally, the term ``vcell'' is often used in Lisp and Scheme
1022 circles as an alternative to ``location''.) Thus part of what we mean
1023 when we talk about ``creating a variable'' is in fact establishing an
1024 association between a name, or identifier, that is used by the Scheme
1025 program code, and the variable location to which that name refers.
1026 Although the value that is stored in that location may change, the
1027 location to which a given name refers is always the same.
1029 We can illustrate this by breaking down the operation of the
1030 @code{define} syntax into three parts: @code{define}
1034 creates a new location
1037 establishes an association between that location and the name specified
1038 as the first argument of the @code{define} expression
1041 stores in that location the value obtained by evaluating the second
1042 argument of the @code{define} expression.
1045 A collection of associations between names and locations is called an
1046 @dfn{environment}. When you create a top level variable in a program
1047 using @code{define}, the name-location association for that variable is
1048 added to the ``top level'' environment. The ``top level'' environment
1049 also includes name-location associations for all the procedures that are
1050 supplied by standard Scheme.
1052 It is also possible to create environments other than the top level one,
1053 and to create variable bindings, or name-location associations, in those
1054 environments. This ability is a key ingredient in the concept of
1055 closure; the next subsection shows how it is done.
1058 @node Local Variables
1059 @subsubsection Local Variables and Environments
1061 @cindex local variable
1062 @cindex variable, local
1063 @cindex local environment
1064 @cindex environment, local
1066 We have seen how to create top level variables using the @code{define}
1067 syntax (@pxref{Definition}). It is often useful to create variables
1068 that are more limited in their scope, typically as part of a procedure
1069 body. In Scheme, this is done using the @code{let} syntax, or one of
1070 its modified forms @code{let*} and @code{letrec}. These syntaxes are
1071 described in full later in the manual (@pxref{Local Bindings}). Here
1072 our purpose is to illustrate their use just enough that we can see how
1073 local variables work.
1075 For example, the following code uses a local variable @code{s} to
1076 simplify the computation of the area of a triangle given the lengths of
1085 (let ((s (/ (+ a b c) 2)))
1086 (sqrt (* s (- s a) (- s b) (- s c)))))
1089 The effect of the @code{let} expression is to create a new environment
1090 and, within this environment, an association between the name @code{s}
1091 and a new location whose initial value is obtained by evaluating
1092 @code{(/ (+ a b c) 2)}. The expressions in the body of the @code{let},
1093 namely @code{(sqrt (* s (- s a) (- s b) (- s c)))}, are then evaluated
1094 in the context of the new environment, and the value of the last
1095 expression evaluated becomes the value of the whole @code{let}
1096 expression, and therefore the value of the variable @code{area}.
1100 @subsubsection Environment Chaining
1102 @cindex shadowing an imported variable binding
1103 @cindex chaining environments
1105 In the example of the previous subsection, we glossed over an important
1106 point. The body of the @code{let} expression in that example refers not
1107 only to the local variable @code{s}, but also to the top level variables
1108 @code{a}, @code{b}, @code{c} and @code{sqrt}. (@code{sqrt} is the
1109 standard Scheme procedure for calculating a square root.) If the body
1110 of the @code{let} expression is evaluated in the context of the
1111 @emph{local} @code{let} environment, how does the evaluation get at the
1112 values of these top level variables?
1114 The answer is that the local environment created by a @code{let}
1115 expression automatically has a reference to its containing environment
1116 --- in this case the top level environment --- and that the Scheme
1117 interpreter automatically looks for a variable binding in the containing
1118 environment if it doesn't find one in the local environment. More
1119 generally, every environment except for the top level one has a
1120 reference to its containing environment, and the interpreter keeps
1121 searching back up the chain of environments --- from most local to top
1122 level --- until it either finds a variable binding for the required
1123 identifier or exhausts the chain.
1125 This description also determines what happens when there is more than
1126 one variable binding with the same name. Suppose, continuing the
1127 example of the previous subsection, that there was also a pre-existing
1128 top level variable @code{s} created by the expression:
1131 (define s "Some beans, my lord!")
1134 Then both the top level environment and the local @code{let} environment
1135 would contain bindings for the name @code{s}. When evaluating code
1136 within the @code{let} body, the interpreter looks first in the local
1137 @code{let} environment, and so finds the binding for @code{s} created by
1138 the @code{let} syntax. Even though this environment has a reference to
1139 the top level environment, which also has a binding for @code{s}, the
1140 interpreter doesn't get as far as looking there. When evaluating code
1141 outside the @code{let} body, the interpreter looks up variable names in
1142 the top level environment, so the name @code{s} refers to the top level
1145 Within the @code{let} body, the binding for @code{s} in the local
1146 environment is said to @dfn{shadow} the binding for @code{s} in the top
1151 @subsubsection Lexical Scope
1153 The rules that we have just been describing are the details of how
1154 Scheme implements ``lexical scoping''. This subsection takes a brief
1155 diversion to explain what lexical scope means in general and to present
1156 an example of non-lexical scoping.
1158 ``Lexical scope'' in general is the idea that
1162 an identifier at a particular place in a program always refers to the
1163 same variable location --- where ``always'' means ``every time that the
1164 containing expression is executed'', and that
1167 the variable location to which it refers can be determined by static
1168 examination of the source code context in which that identifier appears,
1169 without having to consider the flow of execution through the program as
1173 In practice, lexical scoping is the norm for most programming languages,
1174 and probably corresponds to what you would intuitively consider to be
1175 ``normal''. You may even be wondering how the situation could possibly
1176 --- and usefully --- be otherwise. To demonstrate that another kind of
1177 scoping is possible, therefore, and to compare it against lexical
1178 scoping, the following subsection presents an example of non-lexical
1179 scoping and examines in detail how its behavior differs from the
1180 corresponding lexically scoped code.
1183 @c * Scoping Example:: An example of non-lexical scoping.
1187 @c @node Scoping Example
1188 @subsubheading An Example of Non-Lexical Scoping
1190 To demonstrate that non-lexical scoping does exist and can be useful, we
1191 present the following example from Emacs Lisp, which is a ``dynamically
1195 (defvar currency-abbreviation "USD")
1197 (defun currency-string (units hundredths)
1198 (concat currency-abbreviation
1199 (number-to-string units)
1201 (number-to-string hundredths)))
1203 (defun french-currency-string (units hundredths)
1204 (let ((currency-abbreviation "FRF"))
1205 (currency-string units hundredths)))
1208 The question to focus on here is: what does the identifier
1209 @code{currency-abbreviation} refer to in the @code{currency-string}
1210 function? The answer, in Emacs Lisp, is that all variable bindings go
1211 onto a single stack, and that @code{currency-abbreviation} refers to the
1212 topmost binding from that stack which has the name
1213 ``currency-abbreviation''. The binding that is created by the
1214 @code{defvar} form, to the value @code{"USD"}, is only relevant if none
1215 of the code that calls @code{currency-string} rebinds the name
1216 ``currency-abbreviation'' in the meanwhile.
1218 The second function @code{french-currency-string} works precisely by
1219 taking advantage of this behaviour. It creates a new binding for the
1220 name ``currency-abbreviation'' which overrides the one established by
1221 the @code{defvar} form.
1224 ;; Note! This is Emacs Lisp evaluation, not Scheme!
1225 (french-currency-string 33 44)
1230 Now let's look at the corresponding, @emph{lexically scoped} Scheme
1234 (define currency-abbreviation "USD")
1236 (define (currency-string units hundredths)
1237 (string-append currency-abbreviation
1238 (number->string units)
1240 (number->string hundredths)))
1242 (define (french-currency-string units hundredths)
1243 (let ((currency-abbreviation "FRF"))
1244 (currency-string units hundredths)))
1247 According to the rules of lexical scoping, the
1248 @code{currency-abbreviation} in @code{currency-string} refers to the
1249 variable location in the innermost environment at that point in the code
1250 which has a binding for @code{currency-abbreviation}, which is the
1251 variable location in the top level environment created by the preceding
1252 @code{(define currency-abbreviation @dots{})} expression.
1254 In Scheme, therefore, the @code{french-currency-string} procedure does
1255 not work as intended. The variable binding that it creates for
1256 ``currency-abbreviation'' is purely local to the code that forms the
1257 body of the @code{let} expression. Since this code doesn't directly use
1258 the name ``currency-abbreviation'' at all, the binding is pointless.
1261 (french-currency-string 33 44)
1266 This begs the question of how the Emacs Lisp behaviour can be
1267 implemented in Scheme. In general, this is a design question whose
1268 answer depends upon the problem that is being addressed. In this case,
1269 the best answer may be that @code{currency-string} should be
1270 redesigned so that it can take an optional third argument. This third
1271 argument, if supplied, is interpreted as a currency abbreviation that
1272 overrides the default.
1274 It is possible to change @code{french-currency-string} so that it mostly
1275 works without changing @code{currency-string}, but the fix is inelegant,
1276 and susceptible to interrupts that could leave the
1277 @code{currency-abbreviation} variable in the wrong state:
1280 (define (french-currency-string units hundredths)
1281 (set! currency-abbreviation "FRF")
1282 (let ((result (currency-string units hundredths)))
1283 (set! currency-abbreviation "USD")
1287 The key point here is that the code does not create any local binding
1288 for the identifier @code{currency-abbreviation}, so all occurrences of
1289 this identifier refer to the top level variable.
1293 @subsubsection Closure
1295 Consider a @code{let} expression that doesn't contain any
1299 (let ((s (/ (+ a b c) 2)))
1300 (sqrt (* s (- s a) (- s b) (- s c))))
1304 When the Scheme interpreter evaluates this, it
1308 creates a new environment with a reference to the environment that was
1309 current when it encountered the @code{let}
1312 creates a variable binding for @code{s} in the new environment, with
1313 value given by @code{(/ (+ a b c) 2)}
1316 evaluates the expression in the body of the @code{let} in the context of
1317 the new local environment, and remembers the value @code{V}
1320 forgets the local environment
1323 continues evaluating the expression that contained the @code{let}, using
1324 the value @code{V} as the value of the @code{let} expression, in the
1325 context of the containing environment.
1328 After the @code{let} expression has been evaluated, the local
1329 environment that was created is simply forgotten, and there is no longer
1330 any way to access the binding that was created in this environment. If
1331 the same code is evaluated again, it will follow the same steps again,
1332 creating a second new local environment that has no connection with the
1333 first, and then forgetting this one as well.
1335 If the @code{let} body contains a @code{lambda} expression, however, the
1336 local environment is @emph{not} forgotten. Instead, it becomes
1337 associated with the procedure that is created by the @code{lambda}
1338 expression, and is reinstated every time that that procedure is called.
1339 In detail, this works as follows.
1343 When the Scheme interpreter evaluates a @code{lambda} expression, to
1344 create a procedure object, it stores the current environment as part of
1345 the procedure definition.
1348 Then, whenever that procedure is called, the interpreter reinstates the
1349 environment that is stored in the procedure definition and evaluates the
1350 procedure body within the context of that environment.
1353 The result is that the procedure body is always evaluated in the context
1354 of the environment that was current when the procedure was created.
1356 This is what is meant by @dfn{closure}. The next few subsections
1357 present examples that explore the usefulness of this concept.
1361 @subsubsection Example 1: A Serial Number Generator
1363 This example uses closure to create a procedure with a variable binding
1364 that is private to the procedure, like a local variable, but whose value
1365 persists between procedure calls.
1368 (define (make-serial-number-generator)
1369 (let ((current-serial-number 0))
1371 (set! current-serial-number (+ current-serial-number 1))
1372 current-serial-number)))
1374 (define entry-sn-generator (make-serial-number-generator))
1376 (entry-sn-generator)
1380 (entry-sn-generator)
1385 When @code{make-serial-number-generator} is called, it creates a local
1386 environment with a binding for @code{current-serial-number} whose
1387 initial value is 0, then, within this environment, creates a procedure.
1388 The local environment is stored within the created procedure object and
1389 so persists for the lifetime of the created procedure.
1391 Every time the created procedure is invoked, it increments the value of
1392 the @code{current-serial-number} binding in the captured environment and
1393 then returns the current value.
1395 Note that @code{make-serial-number-generator} can be called again to
1396 create a second serial number generator that is independent of the
1397 first. Every new invocation of @code{make-serial-number-generator}
1398 creates a new local @code{let} environment and returns a new procedure
1399 object with an association to this environment.
1402 @node Shared Variable
1403 @subsubsection Example 2: A Shared Persistent Variable
1405 This example uses closure to create two procedures, @code{get-balance}
1406 and @code{deposit}, that both refer to the same captured local
1407 environment so that they can both access the @code{balance} variable
1408 binding inside that environment. The value of this variable binding
1409 persists between calls to either procedure.
1411 Note that the captured @code{balance} variable binding is private to
1412 these two procedures: it is not directly accessible to any other code.
1413 It can only be accessed indirectly via @code{get-balance} or
1414 @code{deposit}, as illustrated by the @code{withdraw} procedure.
1417 (define get-balance #f)
1426 (set! balance (+ balance amount))
1429 (define (withdraw amount)
1430 (deposit (- amount)))
1445 An important detail here is that the @code{get-balance} and
1446 @code{deposit} variables must be set up by @code{define}ing them at top
1447 level and then @code{set!}ing their values inside the @code{let} body.
1448 Using @code{define} within the @code{let} body would not work: this
1449 would create variable bindings within the local @code{let} environment
1450 that would not be accessible at top level.
1453 @node Callback Closure
1454 @subsubsection Example 3: The Callback Closure Problem
1456 A frequently used programming model for library code is to allow an
1457 application to register a callback function for the library to call when
1458 some particular event occurs. It is often useful for the application to
1459 make several such registrations using the same callback function, for
1460 example if several similar library events can be handled using the same
1461 application code, but the need then arises to distinguish the callback
1462 function calls that are associated with one callback registration from
1463 those that are associated with different callback registrations.
1465 In languages without the ability to create functions dynamically, this
1466 problem is usually solved by passing a @code{user_data} parameter on the
1467 registration call, and including the value of this parameter as one of
1468 the parameters on the callback function. Here is an example of
1469 declarations using this solution in C:
1472 typedef void (event_handler_t) (int event_type,
1475 void register_callback (int event_type,
1476 event_handler_t *handler,
1480 In Scheme, closure can be used to achieve the same functionality without
1481 requiring the library code to store a @code{user-data} for each callback
1487 (define (register-callback event-type handler-proc)
1490 ;; In the application:
1492 (define (make-handler event-type user-data)
1495 <code referencing event-type and user-data>
1498 (register-callback event-type
1499 (make-handler event-type @dots{}))
1502 As far as the library is concerned, @code{handler-proc} is a procedure
1503 with no arguments, and all the library has to do is call it when the
1504 appropriate event occurs. From the application's point of view, though,
1505 the handler procedure has used closure to capture an environment that
1506 includes all the context that the handler code needs ---
1507 @code{event-type} and @code{user-data} --- to handle the event
1512 @subsubsection Example 4: Object Orientation
1514 Closure is the capture of an environment, containing persistent variable
1515 bindings, within the definition of a procedure or a set of related
1516 procedures. This is rather similar to the idea in some object oriented
1517 languages of encapsulating a set of related data variables inside an
1518 ``object'', together with a set of ``methods'' that operate on the
1519 encapsulated data. The following example shows how closure can be used
1520 to emulate the ideas of objects, methods and encapsulation in Scheme.
1523 (define (make-account)
1525 (define (get-balance)
1527 (define (deposit amount)
1528 (set! balance (+ balance amount))
1530 (define (withdraw amount)
1531 (deposit (- amount)))
1536 ((get-balance) get-balance)
1538 ((withdraw) withdraw)
1539 (else (error "Invalid method!")))
1543 Each call to @code{make-account} creates and returns a new procedure,
1544 created by the expression in the example code that begins ``(lambda
1548 (define my-account (make-account))
1555 This procedure acts as an account object with methods
1556 @code{get-balance}, @code{deposit} and @code{withdraw}. To apply one of
1557 the methods to the account, you call the procedure with a symbol
1558 indicating the required method as the first parameter, followed by any
1559 other parameters that are required by that method.
1562 (my-account 'get-balance)
1566 (my-account 'withdraw 5)
1570 (my-account 'deposit 396)
1574 (my-account 'get-balance)
1579 Note how, in this example, both the current balance and the helper
1580 procedures @code{get-balance}, @code{deposit} and @code{withdraw}, used
1581 to implement the guts of the account object's methods, are all stored in
1582 variable bindings within the private local environment captured by the
1583 @code{lambda} expression that creates the account object procedure.
1587 @c TeX-master: "guile.texi"