code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Preface
@chapter Preface

This reference manual documents Guile, GNU's Ubiquitous Intelligent
Language for Extensions.  It describes how to use Guile in many useful
and interesting ways.

This is edition @value{MANUAL-EDITION} of the reference manual, and
corresponds to Guile version @value{VERSION}.

@menu
* Manual Layout::
* Manual Conventions::
* Contributors::
* Guile License::
@end menu

@node Manual Layout
@section Layout of this Manual

The manual is divided into five chapters.

@table @strong
@item Chapter 1: Introduction to Guile
This part provides an overview of what Guile is and how you can use
it.  A whirlwind tour shows how Guile can be used interactively and as
a script interpreter, how to link Guile into your own applications,
and how to write modules of interpreted and compiled code for use with
Guile.  Everything introduced here is documented again and in full by
the later parts of the manual.  This part also explains how to obtain
and install new versions of Guile, and how to report bugs effectively.

@item Chapter 2: Programming in Scheme
This part provides an overview over programming in Scheme with Guile.
It covers how to invoke the @code{guile} program from the command-line
and how to write scripts in Scheme.  It also gives an introduction
into the basic ideas of Scheme itself and to the various extensions
that Guile offers beyond standard Scheme.

@item Chapter 3: Programming in C
This part provides an overview of how to use Guile in a C program.  It
discusses the fundamental concepts that you need to understand to
access the features of Guile, such as dynamic types and the garbage
collector.  It explains in a tutorial like manner how to define new
data types and functions for the use by Scheme programs.

@item Chapter 4: Guile API Reference
This part of the manual documents the Guile @acronym{API} in
functionality-based groups with the Scheme and C interfaces presented
side by side.

@item Chapter 5: Guile Modules
Describes some important modules, distributed as part of the Guile
distribution, that extend the functionality provided by the Guile
Scheme core.

@end table

@node Manual Conventions
@section Conventions used in this Manual

We use some conventions in this manual.

@itemize @bullet

@item
For some procedures, notably type predicates, we use @dfn{iff} to mean
``if and only if''.  The construct is usually something like: `Return
@var{val} iff @var{condition}', where @var{val} is usually
``@nicode{#t}'' or ``non-@nicode{#f}''.  This typically means that
@var{val} is returned if @var{condition} holds, and that @samp{#f} is
returned otherwise.  To clarify: @var{val} will @strong{only} be
returned when @var{condition} is true.
@cindex iff

@item
In examples and procedure descriptions and all other places where the
evaluation of Scheme expression is shown, we use some notation for
denoting the output and evaluation results of expressions.

The symbol @samp{@result{}} is used to tell which value is returned by
an evaluation:

@lisp
(+ 1 2)
@result{} 3
@end lisp

Some procedures produce some output besides returning a value.  This
is denoted by the symbol @samp{@print{}}.

@lisp
(begin (display 1) (newline) 'hooray)
@print{} 1
@result{} hooray
@end lisp

As you can see, this code prints @samp{1} (denoted by
@samp{@print{}}), and returns @code{hooray} (denoted by
@samp{@result{}}).  Do not confuse the two.

@c Add other conventions here.

@end itemize

@node Contributors
@section Contributors to this Manual

The Guile reference and tutorial manuals were written and edited
largely by Mark Galassi and Jim Blandy.  In particular, Jim wrote the
original tutorial on Guile's data representation and the C API for
accessing Guile objects.

Significant portions were contributed by Gary Houston (contributions
to POSIX system calls and networking, expect, I/O internals and
extensions, slib installation, error handling) and Tim Pierce
(sections on script interpreter triggers, alists, function tracing).

Tom Lord contributed a great deal of material with early Guile
snapshots; although most of this text has been rewritten, all of it
was important, and some of the structure remains.

Aubrey Jaffer wrote the SCM Scheme implementation and manual upon
which the Guile program and manual are based.  Some portions of the
SCM and SLIB manuals have been included here verbatim.

Since Guile 1.4, Neil Jerram has been maintaining and improving the
reference manual.  Among other contributions, he wrote the Basic
Ideas chapter, developed the tools for keeping the manual in sync
with snarfed libguile docstrings, and reorganized the structure so as
to accommodate docstrings for all Guile's primitives.

Martin Grabmueller has made substantial contributions throughout the
reference manual in preparation for the Guile 1.6 release, including
filling out a lot of the documentation of Scheme data types, control
mechanisms and procedures.  In addition, he wrote the documentation
for Guile's SRFI modules and modules associated with the Guile REPL.

@node Guile License
@section The Guile License
@cindex copying
@cindex GPL
@cindex LGPL
@cindex license

Guile is Free Software.  Guile is copyrighted, not public domain, and
there are restrictions on its distribution or redistribution, but
these restrictions are designed to permit everything a cooperating
person would want to do.

@itemize @bullet
@item
The Guile library (libguile) and supporting files are published under
the terms of the GNU Lesser General Public License version 2.1.  See
the file @file{COPYING.LIB}.

@item
The Guile readline module is published under the terms of the GNU
General Public License version 2.  See the file @file{COPYING}.

@item
The manual you're now reading is published under the terms of the GNU
Free Documentation License (@pxref{GNU Free Documentation License}).
@end itemize

C code linking to the Guile library is subject to terms of that
library.  Basically such code may be published on any terms, provided
users can re-link against a new or modified version of Guile.

C code linking to the Guile readline module is subject to the terms of
that module.  Basically such code must be published on Free terms.

Scheme level code written to be run by Guile (but not derived from
Guile itself) is not resticted in any way, and may be published on any
terms.  We encourage authors to publish on Free terms.

You must be aware there is no warranty whatsoever for Guile.  This is
described in full in the licenses.

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

license: unknown


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Readline Support
@section Readline Support

@c FIXME::martin: Review me!

@cindex readline
@cindex command line history
Guile comes with an interface module to the readline library
(@pxref{Top,,, readline, GNU Readline Library}).  This
makes interactive use much more convenient, because of the command-line
editing features of readline.  Using @code{(ice-9 readline)}, you can
navigate through the current input line with the cursor keys, retrieve
older command lines from the input history and even search through the
history entries.

@menu
* Loading Readline Support::    How to load readline support into Guile.
* Readline Options::            How to modify readline's behaviour.
* Readline Functions::          Programming with readline.
@end menu

@node Loading Readline Support
@subsection Loading Readline Support

The module is not loaded by default and so has to be loaded and
activated explicitly.  This is done with two simple lines of code:

@lisp
(use-modules (ice-9 readline))
(activate-readline)
@end lisp

@c FIXME::martin: Review me!

The first line will load the necessary code, and the second will
activate readline's features for the REPL.  If you plan to use this
module often, you should save these to lines to your @file{.guile}
personal startup file.

You will notice that the REPL's behaviour changes a bit when you have
loaded the readline module.  For example, when you press Enter before
typing in the closing parentheses of a list, you will see the
@dfn{continuation} prompt, three dots: @code{...}  This gives you a nice
visual feedback when trying to match parentheses.  To make this even
easier, @dfn{bouncing parentheses} are implemented.  That means that
when you type in a closing parentheses, the cursor will jump to the
corresponding opening parenthesis for a short time, making it trivial to make
them match.

Once the readline module is activated, all lines entered interactively
will be stored in a history and can be recalled later using the
cursor-up and -down keys.  Readline also understands the Emacs keys for
navigating through the command line and history.

@cindex @file{.guile_history}
When you quit your Guile session by evaluating @code{(quit)} or pressing
Ctrl-D, the history will be saved to the file @file{.guile_history} and
read in when you start Guile for the next time.  Thus you can start a
new Guile session and still have the (probably long-winded) definition
expressions available.

@cindex @env{GUILE_HISTORY}
@cindex @file{.inputrc}
You can specify a different history file by setting the environment
variable @env{GUILE_HISTORY}.  And you can make Guile specific
customizations to your @file{.inputrc} by testing for application
@samp{Guile} (@pxref{Conditional Init Constructs,,, readline, GNU
Readline Library}).  For instance to define a key inserting a matched
pair of parentheses,

@example
$if Guile
  "\C-o": "()\C-b"
$endif
@end example

@node Readline Options
@subsection Readline Options

@c FIXME::martin: Review me!

@cindex readline options
The readline interface module can be configured in several ways to
better suit the user's needs.  Configuration is done via the readline
module's options interface, in a similar way to the evaluator and
debugging options (@pxref{Runtime Options}).

@findex readline-options
@findex readline-enable
@findex readline-disable
@findex readline-set!
Here is the list of readline options generated by typing
@code{(readline-options 'full)} in Guile.  You can also see the
default values.

@smalllisp
bounce-parens   500   Time (ms) to show matching opening parenthesis (0 = off).
history-length  200   History length.
history-file    yes   Use history file.
@end smalllisp

The history length specifies how many input lines will be remembered.
If the history contains that many lines and additional lines are
entered, the oldest lines will be lost.  You can switch on/off the
usage of the history file using the following call.

@lisp
(readline-disable 'history)
@end lisp

The readline options interface can only be used @emph{after} loading
the readline module, because it is defined in that module.

@node Readline Functions
@subsection Readline Functions

The following functions are provided by

@example
(use-modules (ice-9 readline))
@end example

There are two ways to use readline from Scheme code, either make calls
to @code{readline} directly to get line by line input, or use the
readline port below with all the usual reading functions.

@defun readline [prompt]
Read a line of input from the user and return it as a string (without
a newline at the end).  @var{prompt} is the prompt to show, or the
default is the string set in @code{set-readline-prompt!} below.

@example
(readline "Type something: ") @result{} "hello"
@end example
@end defun

@defun set-readline-input-port! port
@defunx set-readline-output-port! port
Set the input and output port the readline function should read from
and write to.  @var{port} must be a file port (@pxref{File Ports}),
and should usually be a terminal.

The default is the @code{current-input-port} and
@code{current-output-port} (@pxref{Default Ports}) when @code{(ice-9
readline)} loads, which in an interactive user session means the Unix
``standard input'' and ``standard output''.
@end defun

@subsubsection Readline Port

@defun readline-port
Return a buffered input port (@pxref{Buffered Input}) which calls the
@code{readline} function above to get input.  This port can be used
with all the usual reading functions (@code{read}, @code{read-char},
etc), and the user gets the interactive editing features of readline.

There's only a single readline port created.  @code{readline-port}
creates it when first called, and on subsequent calls just returns
what it previously made.
@end defun

@defun activate-readline
If the @code{current-input-port} is a terminal (@pxref{Terminals and
Ptys,, @code{isatty?}}) then enable readline for all reading from
@code{current-input-port} (@pxref{Default Ports}) and enable readline
features in the interactive REPL (@pxref{The REPL}).

@example
(activate-readline)
(read-char)
@end example

@code{activate-readline} enables readline on @code{current-input-port}
simply by a @code{set-current-input-port} to the @code{readline-port}
above.  An application can do that directly if the extra REPL features
that @code{activate-readline} adds are not wanted.
@end defun

@defun set-readline-prompt! prompt1 [prompt2]
Set the prompt string to print when reading input.  This is used when
reading through @code{readline-port}, and is also the default prompt
for the @code{readline} function above.

@var{prompt1} is the initial prompt shown.  If a user might enter an
expression across multiple lines, then @var{prompt2} is a different
prompt to show further input required.  In the Guile REPL for instance
this is an ellipsis (@samp{...}).

See @code{set-buffered-input-continuation?!} (@pxref{Buffered Input})
for an application to indicate the boundaries of logical expressions
(assuming of course an application has such a notion).
@end defun

@subsubsection Completion

@defun with-readline-completion-function completer thunk
Call @code{(@var{thunk})} with @var{completer} as the readline tab
completion function to be used in any readline calls within that
@var{thunk}.  @var{completer} can be @code{#f} for no completion.

@var{completer} will be called as @code{(@var{completer} text state)},
as described in (@pxref{How Completing Works,,, readline, GNU Readline
Library}).  @var{text} is a partial word to be completed, and each
@var{completer} call should return a possible completion string or
@code{#f} when no more.  @var{state} is @code{#f} for the first call
asking about a new @var{text} then @code{#t} while getting further
completions of that @var{text}.

Here's an example @var{completer} for user login names from the
password file (@pxref{User Information}), much like readline's own
@code{rl_username_completion_function},

@example
(define (username-completer-function text state)
  (if (not state)
      (setpwent))  ;; new, go to start of database
  (let more ((pw (getpwent)))
    (if pw
        (if (string-prefix? text (passwd:name pw))
            (passwd:name pw)     ;; this name matches, return it
            (more (getpwent)))   ;; doesn't match, look at next
        (begin
          ;; end of database, close it and return #f
          (endpwent)
          #f))))
@end example
@end defun

@defun apropos-completion-function text state
A completion function offering completions for Guile functions and
variables (all @code{define}s).  This is the default completion
function.
@c
@c  FIXME: Cross reference the ``apropos'' stuff when it's documented.
@c
@end defun

@defun filename-completion-function text state
A completion function offering filename completions.  This is
readline's @code{rl_filename_completion_function} (@pxref{Completion
Functions,,, readline, GNU Readline Library}).
@end defun

@defun make-completion-function string-list
Return a completion function which offers completions from the
possibilities in @var{string-list}.  Matching is case-sensitive.
@end defun

@page
@node Value History
@section Value History

@c FIXME::martin: Review me!

@cindex value history
Another module which makes command line usage more convenient is
@code{(ice-9 history)}.  This module will change the REPL so that each
value which is evaluated and printed will be remembered under a name
constructed from the dollar character (@code{$}) and the number of the
evaluated expression.

Consider an example session.

@example
guile> (use-modules (ice-9 history))
guile> 1
$1 = 1
guile> (+ $1 $1)
$2 = 2
guile> (* $2 $2)
$3 = 4
@end example

After loading the value history module @code{(ice-9 history)}, one
(trivial) expression is evaluated.  The result is stored into the
variable @code{$1}.  This fact is indicated by the output @code{$1 = },
which is also caused by @code{(ice-9 history)}.  In the next line, this
variable is used two times, to produce the value @code{$2}, which in
turn is used in the calculation for @code{$3}.

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Tracing
@section Tracing

The @code{(ice-9 debug)} module implements tracing of procedure
applications.  When a procedure is @dfn{traced}, it means that every
call to that procedure is reported to the user during a program run.
The idea is that you can mark a collection of procedures for tracing,
and Guile will subsequently print out a line of the form

@smalllisp
|  |  [@var{procedure} @var{args} @dots{}]
@end smalllisp

whenever a marked procedure is about to be applied to its arguments.
This can help a programmer determine whether a function is being called
at the wrong time or with the wrong set of arguments.

In addition, the indentation of the output is useful for demonstrating
how the traced applications are or are not tail recursive with respect
to each other.  Thus, a trace of a non-tail recursive factorial
implementation looks like this:

@smalllisp
[fact1 4]
|  [fact1 3]
|  |  [fact1 2]
|  |  |  [fact1 1]
|  |  |  |  [fact1 0]
|  |  |  |  1
|  |  |  1
|  |  2
|  6
24
@end smalllisp

While a typical tail recursive implementation would look more like this:

@smalllisp
[fact2 4]
[facti 1 4]
[facti 4 3]
[facti 12 2]
[facti 24 1]
[facti 24 0]
24
@end smalllisp

@deffn {Scheme Procedure} trace procedure
Enable tracing for @code{procedure}.  While a program is being run,
Guile will print a brief report at each call to a traced procedure,
advising the user which procedure was called and the arguments that were
passed to it.
@end deffn

@deffn {Scheme Procedure} untrace procedure
Disable tracing for @code{procedure}.
@end deffn

Here is another example:

@lisp
(define (rev ls)
  (if (null? ls)
      '()
      (append (rev (cdr ls))
              (cons (car ls) '())))) @result{} rev

(trace rev) @result{} (rev)

(rev '(a b c d e))
@result{} [rev (a b c d e)]
   |  [rev (b c d e)]
   |  |  [rev (c d e)]
   |  |  |  [rev (d e)]
   |  |  |  |  [rev (e)]
   |  |  |  |  |  [rev ()]
   |  |  |  |  |  ()
   |  |  |  |  (e)
   |  |  |  (e d)
   |  |  (e d c)
   |  (e d c b)
   (e d c b a)
   (e d c b a)
@end lisp

Note the way Guile indents the output, illustrating the depth of
execution at each procedure call.  This can be used to demonstrate, for
example, that Guile implements self-tail-recursion properly:

@lisp
(define (rev ls sl)
  (if (null? ls)
      sl
      (rev (cdr ls)
           (cons (car ls) sl)))) @result{} rev

(trace rev) @result{} (rev)

(rev '(a b c d e) '())
@result{} [rev (a b c d e) ()]
   [rev (b c d e) (a)]
   [rev (c d e) (b a)]
   [rev (d e) (c b a)]
   [rev (e) (d c b a)]
   [rev () (e d c b a)]
   (e d c b a)
   (e d c b a)
@end lisp

Since the tail call is effectively optimized to a @code{goto} statement,
there is no need for Guile to create a new stack frame for each
iteration.  Tracing reveals this optimization in operation.

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Basic Ideas
@section Basic Ideas in Scheme

In this chapter, we introduce the basic concepts that underpin the
elegance and power of the Scheme language.

Readers who already possess a background knowledge of Scheme may happily
skip this chapter.  For the reader who is new to the language, however,
the following discussions on data, procedures, expressions and closure
are designed to provide a minimum level of Scheme understanding that is
more or less assumed by the reference chapters that follow.

The style of this introductory material aims about halfway between the
terse precision of R5RS and the discursive randomness of a Scheme
tutorial.

@menu
* About Data::                  Latent typing, types, values and variables.
* About Procedures::            The representation and use of procedures.
* About Expressions::           All kinds of expressions and their meaning.
* About Closure::               Closure, scoping and environments.
@end menu

@node About Data
@subsection Data Types, Values and Variables

This section discusses the representation of data types and values, what
it means for Scheme to be a @dfn{latently typed} language, and the role
of variables.  We conclude by introducing the Scheme syntaxes for
defining a new variable, and for changing the value of an existing
variable.

@menu
* Latent Typing::               Scheme as a "latently typed" language.
* Values and Variables::        About data types, values and variables.
* Definition::                  Defining variables and setting their values.
@end menu

@node Latent Typing
@subsubsection Latent Typing

The term @dfn{latent typing} is used to describe a computer language,
such as Scheme, for which you cannot, @emph{in general}, simply look at
a program's source code and determine what type of data will be
associated with a particular variable, or with the result of a
particular expression.

Sometimes, of course, you @emph{can} tell from the code what the type of
an expression will be.  If you have a line in your program that sets the
variable @code{x} to the numeric value 1, you can be certain that,
immediately after that line has executed (and in the absence of multiple
threads), @code{x} has the numeric value 1.  Or if you write a procedure
that is designed to concatenate two strings, it is likely that the rest
of your application will always invoke this procedure with two string
parameters, and quite probable that the procedure would go wrong in some
way if it was ever invoked with parameters that were not both strings.

Nevertheless, the point is that there is nothing in Scheme which
requires the procedure parameters always to be strings, or @code{x}
always to hold a numeric value, and there is no way of declaring in your
program that such constraints should always be obeyed.  In the same
vein, there is no way to declare the expected type of a procedure's
return value.

Instead, the types of variables and expressions are only known -- in
general -- at run time.  If you @emph{need} to check at some point that
a value has the expected type, Scheme provides run time procedures that
you can invoke to do so.  But equally, it can be perfectly valid for two
separate invocations of the same procedure to specify arguments with
different types, and to return values with different types.

The next subsection explains what this means in practice, for the ways
that Scheme programs use data types, values and variables.

@node Values and Variables
@subsubsection Values and Variables

Scheme provides many data types that you can use to represent your data.
Primitive types include characters, strings, numbers and procedures.
Compound types, which allow a group of primitive and compound values to
be stored together, include lists, pairs, vectors and multi-dimensional
arrays.  In addition, Guile allows applications to define their own data
types, with the same status as the built-in standard Scheme types.

As a Scheme program runs, values of all types pop in and out of
existence.  Sometimes values are stored in variables, but more commonly
they pass seamlessly from being the result of one computation to being
one of the parameters for the next.

Consider an example.  A string value is created because the interpreter
reads in a literal string from your program's source code.  Then a
numeric value is created as the result of calculating the length of the
string.  A second numeric value is created by doubling the calculated
length.  Finally the program creates a list with two elements -- the
doubled length and the original string itself -- and stores this list in
a program variable.

All of the values involved here -- in fact, all values in Scheme --
carry their type with them.  In other words, every value ``knows,'' at
runtime, what kind of value it is.  A number, a string, a list,
whatever.

A variable, on the other hand, has no fixed type.  A variable --
@code{x}, say -- is simply the name of a location -- a box -- in which
you can store any kind of Scheme value.  So the same variable in a
program may hold a number at one moment, a list of procedures the next,
and later a pair of strings.  The ``type'' of a variable -- insofar as
the idea is meaningful at all -- is simply the type of whatever value
the variable happens to be storing at a particular moment.

@node Definition
@subsubsection Defining and Setting Variables

To define a new variable, you use Scheme's @code{define} syntax like
this:

@lisp
(define @var{variable-name} @var{value})
@end lisp

This makes a new variable called @var{variable-name} and stores
@var{value} in it as the variable's initial value.  For example:

@lisp
;; Make a variable `x' with initial numeric value 1.
(define x 1)

;; Make a variable `organization' with an initial string value.
(define organization "Free Software Foundation")
@end lisp

(In Scheme, a semicolon marks the beginning of a comment that continues
until the end of the line.  So the lines beginning @code{;;} are
comments.)

Changing the value of an already existing variable is very similar,
except that @code{define} is replaced by the Scheme syntax @code{set!},
like this:

@lisp
(set! @var{variable-name} @var{new-value})
@end lisp

Remember that variables do not have fixed types, so @var{new-value} may
have a completely different type from whatever was previously stored in
the location named by @var{variable-name}.  Both of the following
examples are therefore correct.

@lisp
;; Change the value of `x' to 5.
(set! x 5)

;; Change the value of `organization' to the FSF's street number.
(set! organization 545)
@end lisp

In these examples, @var{value} and @var{new-value} are literal numeric
or string values.  In general, however, @var{value} and @var{new-value}
can be any Scheme expression.  Even though we have not yet covered the
forms that Scheme expressions can take (@pxref{About Expressions}), you
can probably guess what the following @code{set!} example does@dots{}

@lisp
(set! x (+ x 1))
@end lisp

(Note: this is not a complete description of @code{define} and
@code{set!}, because we need to introduce some other aspects of Scheme
before the missing pieces can be filled in.  If, however, you are
already familiar with the structure of Scheme, you may like to read
about those missing pieces immediately by jumping ahead to the following
references.

@itemize @bullet
@item
@ref{Lambda Alternatives}, to read about an alternative form of the
@code{define} syntax that can be used when defining new procedures.

@item
@ref{Procedures with Setters}, to read about an alternative form of the
@code{set!} syntax that helps with changing a single value in the depths
of a compound data structure.)

@item
@xref{Internal Definitions}, to read about using @code{define} other
than at top level in a Scheme program, including a discussion of when it
works to use @code{define} rather than @code{set!} to change the value
of an existing variable.
@end itemize

@node About Procedures
@subsection The Representation and Use of Procedures

This section introduces the basics of using and creating Scheme
procedures.  It discusses the representation of procedures as just
another kind of Scheme value, and shows how procedure invocation
expressions are constructed.  We then explain how @code{lambda} is used
to create new procedures, and conclude by presenting the various
shorthand forms of @code{define} that can be used instead of writing an
explicit @code{lambda} expression.

@menu
* Procedures as Values::        Procedures are values like everything else.
* Simple Invocation::           How to write a simple procedure invocation.
* Creating a Procedure::        How to create your own procedures.
* Lambda Alternatives::         Other ways of writing procedure definitions.
@end menu

@node Procedures as Values
@subsubsection Procedures as Values

One of the great simplifications of Scheme is that a procedure is just
another type of value, and that procedure values can be passed around
and stored in variables in exactly the same way as, for example, strings
and lists.  When we talk about a built-in standard Scheme procedure such
as @code{open-input-file}, what we actually mean is that there is a
pre-defined top level variable called @code{open-input-file}, whose
value is a procedure that implements what R5RS says that
@code{open-input-file} should do.

Note that this is quite different from many dialects of Lisp ---
including Emacs Lisp --- in which a program can use the same name with
two quite separate meanings: one meaning identifies a Lisp function,
while the other meaning identifies a Lisp variable, whose value need
have nothing to do with the function that is associated with the first
meaning.  In these dialects, functions and variables are said to live in
different @dfn{namespaces}.

In Scheme, on the other hand, all names belong to a single unified
namespace, and the variables that these names identify can hold any kind
of Scheme value, including procedure values.

One consequence of the ``procedures as values'' idea is that, if you
don't happen to like the standard name for a Scheme procedure, you can
change it.

For example, @code{call-with-current-continuation} is a very important
standard Scheme procedure, but it also has a very long name!  So, many
programmers use the following definition to assign the same procedure
value to the more convenient name @code{call/cc}.

@lisp
(define call/cc call-with-current-continuation)
@end lisp

Let's understand exactly how this works.  The definition creates a new
variable @code{call/cc}, and then sets its value to the value of the
variable @code{call-with-current-continuation}; the latter value is a
procedure that implements the behaviour that R5RS specifies under the
name ``call-with-current-continuation''.  So @code{call/cc} ends up
holding this value as well.

Now that @code{call/cc} holds the required procedure value, you could
choose to use @code{call-with-current-continuation} for a completely
different purpose, or just change its value so that you will get an
error if you accidentally use @code{call-with-current-continuation} as a
procedure in your program rather than @code{call/cc}.  For example:

@lisp
(set! call-with-current-continuation "Not a procedure any more!")
@end lisp

Or you could just leave @code{call-with-current-continuation} as it was.
It's perfectly fine for more than one variable to hold the same
procedure value.

@node Simple Invocation
@subsubsection Simple Procedure Invocation

A procedure invocation in Scheme is written like this:

@lisp
(@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
@end lisp

In this expression, @var{procedure} can be any Scheme expression whose
value is a procedure.  Most commonly, however, @var{procedure} is simply
the name of a variable whose value is a procedure.

For example, @code{string-append} is a standard Scheme procedure whose
behaviour is to concatenate together all the arguments, which are
expected to be strings, that it is given.  So the expression

@lisp
(string-append "/home" "/" "andrew")
@end lisp

@noindent
is a procedure invocation whose result is the string value
@code{"/home/andrew"}.

Similarly, @code{string-length} is a standard Scheme procedure that
returns the length of a single string argument, so

@lisp
(string-length "abc")
@end lisp

@noindent
is a procedure invocation whose result is the numeric value 3.

Each of the parameters in a procedure invocation can itself be any
Scheme expression.  Since a procedure invocation is itself a type of
expression, we can put these two examples together to get

@lisp
(string-length (string-append "/home" "/" "andrew"))
@end lisp

@noindent
--- a procedure invocation whose result is the numeric value 12.

(You may be wondering what happens if the two examples are combined the
other way round.  If we do this, we can make a procedure invocation
expression that is @emph{syntactically} correct:

@lisp
(string-append "/home" (string-length "abc"))
@end lisp

@noindent
but when this expression is executed, it will cause an error, because
the result of @code{(string-length "abc")} is a numeric value, and
@code{string-append} is not designed to accept a numeric value as one of
its arguments.)

@node Creating a Procedure
@subsubsection Creating and Using a New Procedure

Scheme has lots of standard procedures, and Guile provides all of these
via predefined top level variables.  All of these standard procedures
are documented in the later chapters of this reference manual.

Before very long, though, you will want to create new procedures that
encapsulate aspects of your own applications' functionality.  To do
this, you can use the famous @code{lambda} syntax.

For example, the value of the following Scheme expression

@lisp
(lambda (name address) @var{expression} @dots{})
@end lisp

@noindent
is a newly created procedure that takes two arguments:
@code{name} and @code{address}.  The behaviour of the
new procedure is determined by the sequence of @var{expression}s in the
@dfn{body} of the procedure definition.  (Typically, these
@var{expression}s would use the arguments in some way, or else there
wouldn't be any point in giving them to the procedure.)  When invoked,
the new procedure returns a value that is the value of the last
@var{expression} in the procedure body.

To make things more concrete, let's suppose that the two arguments are
both strings, and that the purpose of this procedure is to form a
combined string that includes these arguments.  Then the full lambda
expression might look like this:

@lisp
(lambda (name address)
  (string-append "Name=" name ":Address=" address))
@end lisp

We noted in the previous subsection that the @var{procedure} part of a
procedure invocation expression can be any Scheme expression whose value
is a procedure.  But that's exactly what a lambda expression is!  So we
can use a lambda expression directly in a procedure invocation, like
this:

@lisp
((lambda (name address)
   (string-append "Name=" name ":Address=" address))
 "FSF"
 "Cambridge")
@end lisp

@noindent
This is a valid procedure invocation expression, and its result is the
string @code{"Name=FSF:Address=Cambridge"}.

It is more common, though, to store the procedure value in a variable ---

@lisp
(define make-combined-string
  (lambda (name address)
    (string-append "Name=" name ":Address=" address)))
@end lisp

@noindent
--- and then to use the variable name in the procedure invocation:

@lisp
(make-combined-string "FSF" "Cambridge")
@end lisp

@noindent
Which has exactly the same result.

It's important to note that procedures created using @code{lambda} have
exactly the same status as the standard built in Scheme procedures, and
can be invoked, passed around, and stored in variables in exactly the
same ways.

@node Lambda Alternatives
@subsubsection Lambda Alternatives

Since it is so common in Scheme programs to want to create a procedure
and then store it in a variable, there is an alternative form of the
@code{define} syntax that allows you to do just that.

A @code{define} expression of the form

@lisp
(define (@var{name} [@var{arg1} [@var{arg2} @dots{}]])
  @var{expression} @dots{})
@end lisp

@noindent
is exactly equivalent to the longer form

@lisp
(define @var{name}
  (lambda ([@var{arg1} [@var{arg2} @dots{}]])
    @var{expression} @dots{}))
@end lisp

So, for example, the definition of @code{make-combined-string} in the
previous subsection could equally be written:

@lisp
(define (make-combined-string name address)
  (string-append "Name=" name ":Address=" address))
@end lisp

This kind of procedure definition creates a procedure that requires
exactly the expected number of arguments.  There are two further forms
of the @code{lambda} expression, which create a procedure that can
accept a variable number of arguments:

@lisp
(lambda (@var{arg1} @dots{} . @var{args}) @var{expression} @dots{})

(lambda @var{args} @var{expression} @dots{})
@end lisp

@noindent
The corresponding forms of the alternative @code{define} syntax are:

@lisp
(define (@var{name} @var{arg1} @dots{} . @var{args}) @var{expression} @dots{})

(define (@var{name} . @var{args}) @var{expression} @dots{})
@end lisp

@noindent
For details on how these forms work, see @xref{Lambda}.

(It could be argued that the alternative @code{define} forms are rather
confusing, especially for newcomers to the Scheme language, as they hide
both the role of @code{lambda} and the fact that procedures are values
that are stored in variables in the some way as any other kind of value.
On the other hand, they are very convenient, and they are also a good
example of another of Scheme's powerful features: the ability to specify
arbitrary syntactic transformations at run time, which can be applied to
subsequently read input.)

@node About Expressions
@subsection Expressions and Evaluation

So far, we have met expressions that @emph{do} things, such as the
@code{define} expressions that create and initialize new variables, and
we have also talked about expressions that have @emph{values}, for
example the value of the procedure invocation expression:

@lisp
(string-append "/home" "/" "andrew")
@end lisp

@noindent
but we haven't yet been precise about what causes an expression like
this procedure invocation to be reduced to its ``value'', or how the
processing of such expressions relates to the execution of a Scheme
program as a whole.

This section clarifies what we mean by an expression's value, by
introducing the idea of @dfn{evaluation}.  It discusses the side effects
that evaluation can have, explains how each of the various types of
Scheme expression is evaluated, and describes the behaviour and use of
the Guile REPL as a mechanism for exploring evaluation.  The section
concludes with a very brief summary of Scheme's common syntactic
expressions.

@menu
* Evaluating::                  How a Scheme program is executed.
* Tail Calls::                  Space-safe recursion.
* The REPL::                    Interacting with the Guile interpreter.
* Syntax Summary::              Common syntactic expressions -- in brief.
@end menu

@node Evaluating
@subsubsection Evaluating Expressions and Executing Programs

In Scheme, the process of executing an expression is known as
@dfn{evaluation}.  Evaluation has two kinds of result:

@itemize @bullet
@item
the @dfn{value} of the evaluated expression

@item
the @dfn{side effects} of the evaluation, which consist of any effects of
evaluating the expression that are not represented by the value.
@end itemize

Of the expressions that we have met so far, @code{define} and
@code{set!} expressions have side effects --- the creation or
modification of a variable --- but no value; @code{lambda} expressions
have values --- the newly constructed procedures --- but no side
effects; and procedure invocation expressions, in general, have either
values, or side effects, or both.

It is tempting to try to define more intuitively what we mean by
``value'' and ``side effects'', and what the difference between them is.
In general, though, this is extremely difficult.  It is also
unnecessary; instead, we can quite happily define the behaviour of a
Scheme program by specifying how Scheme executes a program as a whole,
and then by describing the value and side effects of evaluation for each
type of expression individually.

@noindent
So, some@footnote{These definitions are approximate.  For the whole and
detailed truth, see @xref{Formal syntax and semantics,R5RS
syntax,,r5rs}.} definitions@dots{}

@itemize @bullet

@item
A Scheme program consists of a sequence of expressions.

@item
A Scheme interpreter executes the program by evaluating these
expressions in order, one by one.

@item
An expression can be

@itemize @bullet
@item
a piece of literal data, such as a number @code{2.3} or a string
@code{"Hello world!"}
@item
a variable name
@item
a procedure invocation expression
@item
one of Scheme's special syntactic expressions.
@end itemize
@end itemize

@noindent
The following subsections describe how each of these types of expression
is evaluated.

@c @menu
@c * Eval Literal::                Evaluating literal data.
@c * Eval Variable::               Evaluating variable references.
@c * Eval Procedure::              Evaluating procedure invocation expressions.
@c * Eval Special::                Evaluating special syntactic expressions.
@c @end menu

@c @node Eval Literal

@subsubheading Evaluating Literal Data

When a literal data expression is evaluated, the value of the expression
is simply the value that the expression describes.  The evaluation of a
literal data expression has no side effects.

@noindent
So, for example,

@itemize @bullet
@item
the value of the expression @code{"abc"} is the string value
@code{"abc"}

@item
the value of the expression @code{3+4i} is the complex number 3 + 4i

@item
the value of the expression @code{#(1 2 3)} is a three-element vector
containing the numeric values 1, 2 and 3.
@end itemize

For any data type which can be expressed literally like this, the syntax
of the literal data expression for that data type --- in other words,
what you need to write in your code to indicate a literal value of that
type --- is known as the data type's @dfn{read syntax}.  This manual
specifies the read syntax for each such data type in the section that
describes that data type.

Some data types do not have a read syntax.  Procedures, for example,
cannot be expressed as literal data; they must be created using a
@code{lambda} expression (@pxref{Creating a Procedure}) or implicitly
using the shorthand form of @code{define} (@pxref{Lambda Alternatives}).

@c @node Eval Variable
@subsubheading Evaluating a Variable Reference

When an expression that consists simply of a variable name is evaluated,
the value of the expression is the value of the named variable.  The
evaluation of a variable reference expression has no side effects.

So, after

@lisp
(define key "Paul Evans")
@end lisp

@noindent
the value of the expression @code{key} is the string value @code{"Paul
Evans"}.  If @var{key} is then modified by

@lisp
(set! key 3.74)
@end lisp

@noindent
the value of the expression @code{key} is the numeric value 3.74.

If there is no variable with the specified name, evaluation of the
variable reference expression signals an error.

@c @node Eval Procedure
@subsubheading Evaluating a Procedure Invocation Expression

This is where evaluation starts getting interesting!  As already noted,
a procedure invocation expression has the form

@lisp
(@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
@end lisp

@noindent
where @var{procedure} must be an expression whose value, when evaluated,
is a procedure.

The evaluation of a procedure invocation expression like this proceeds
by

@itemize @bullet
@item
evaluating individually the expressions @var{procedure}, @var{arg1},
@var{arg2}, and so on

@item
calling the procedure that is the value of the @var{procedure}
expression with the list of values obtained from the evaluations of
@var{arg1}, @var{arg2} etc. as its parameters.
@end itemize

For a procedure defined in Scheme, ``calling the procedure with the list
of values as its parameters'' means binding the values to the
procedure's formal parameters and then evaluating the sequence of
expressions that make up the body of the procedure definition.  The
value of the procedure invocation expression is the value of the last
evaluated expression in the procedure body.  The side effects of calling
the procedure are the combination of the side effects of the sequence of
evaluations of expressions in the procedure body.

For a built-in procedure, the value and side-effects of calling the
procedure are best described by that procedure's documentation.

Note that the complete side effects of evaluating a procedure invocation
expression consist not only of the side effects of the procedure call,
but also of any side effects of the preceding evaluation of the
expressions @var{procedure}, @var{arg1}, @var{arg2}, and so on.

To illustrate this, let's look again at the procedure invocation
expression:

@lisp
(string-length (string-append "/home" "/" "andrew"))
@end lisp

In the outermost expression, @var{procedure} is @code{string-length} and
@var{arg1} is @code{(string-append "/home" "/" "andrew")}.

@itemize @bullet
@item
Evaluation of @code{string-length}, which is a variable, gives a
procedure value that implements the expected behaviour for
``string-length''.

@item
Evaluation of @code{(string-append "/home" "/" "andrew")}, which is
another procedure invocation expression, means evaluating each of

@itemize @bullet
@item
@code{string-append}, which gives a procedure value that implements the
expected behaviour for ``string-append''

@item
@code{"/home"}, which gives the string value @code{"/home"}

@item
@code{"/"}, which gives the string value @code{"/"}

@item
@code{"andrew"}, which gives the string value @code{"andrew"}
@end itemize

and then invoking the procedure value with this list of string values as
its arguments.  The resulting value is a single string value that is the
concatenation of all the arguments, namely @code{"/home/andrew"}.
@end itemize

In the evaluation of the outermost expression, the interpreter can now
invoke the procedure value obtained from @var{procedure} with the value
obtained from @var{arg1} as its arguments.  The resulting value is a
numeric value that is the length of the argument string, which is 12.

@c @node Eval Special
@subsubheading Evaluating Special Syntactic Expressions

When a procedure invocation expression is evaluated, the procedure and
@emph{all} the argument expressions must be evaluated before the
procedure can be invoked.  Special syntactic expressions are special
because they are able to manipulate their arguments in an unevaluated
form, and can choose whether to evaluate any or all of the argument
expressions.

Why is this needed?  Consider a program fragment that asks the user
whether or not to delete a file, and then deletes the file if the user
answers yes.

@lisp
(if (string=? (read-answer "Should I delete this file?")
              "yes")
    (delete-file file))
@end lisp

If the outermost @code{(if @dots{})} expression here was a procedure
invocation expression, the expression @code{(delete-file file)}, whose
side effect is to actually delete a file, would already have been
evaluated before the @code{if} procedure even got invoked!  Clearly this
is no use --- the whole point of an @code{if} expression is that the
@dfn{consequent} expression is only evaluated if the condition of the
@code{if} expression is ``true''.

Therefore @code{if} must be special syntax, not a procedure.  Other
special syntaxes that we have already met are @code{define}, @code{set!}
and @code{lambda}.  @code{define} and @code{set!} are syntax because
they need to know the variable @emph{name} that is given as the first
argument in a @code{define} or @code{set!} expression, not that
variable's value.  @code{lambda} is syntax because it does not
immediately evaluate the expressions that define the procedure body;
instead it creates a procedure object that incorporates these
expressions so that they can be evaluated in the future, when that
procedure is invoked.

The rules for evaluating each special syntactic expression are specified
individually for each special syntax.  For a summary of standard special
syntax, see @xref{Syntax Summary}.

@node Tail Calls
@subsubsection Tail calls
@cindex tail calls
@cindex recursion

Scheme is ``properly tail recursive'', meaning that tail calls or
recursions from certain contexts do not consume stack space or other
resources and can therefore be used on arbitrarily large data or for
an arbitrarily long calculation.  Consider for example,

@example
(define (foo n)
  (display n)
  (newline)
  (foo (1+ n)))

(foo 1)
@print{}
1
2
3
@dots{}
@end example

@code{foo} prints numbers infinitely, starting from the given @var{n}.
It's implemented by printing @var{n} then recursing to itself to print
@math{@var{n}+1} and so on.  This recursion is a tail call, it's the
last thing done, and in Scheme such tail calls can be made without
limit.

Or consider a case where a value is returned, a version of the SRFI-1
@code{last} function (@pxref{SRFI-1 Selectors}) returning the last
element of a list,

@example
(define (my-last lst)
  (if (null? (cdr lst))
      (car lst)
      (my-last (cdr lst))))

(my-last '(1 2 3)) @result{} 3
@end example

If the list has more than one element, @code{my-last} applies itself
to the @code{cdr}.  This recursion is a tail call, there's no code
after it, and the return value is the return value from that call.  In
Scheme this can be used on an arbitrarily long list argument.

@sp 1
A proper tail call is only available from certain contexts, namely the
following special form positions,

@itemize @bullet
@item
@code{and} --- last expression

@item
@code{begin} --- last expression

@item
@code{case} --- last expression in each clause

@item
@code{cond} --- last expression in each clause, and the call to a
@code{=>} procedure is a tail call

@item
@code{do} --- last result expression

@item
@code{if} --- ``true'' and ``false'' leg expressions

@item
@code{lambda} --- last expression in body

@item
@code{let}, @code{let*}, @code{letrec}, @code{let-syntax},
@code{letrec-syntax} --- last expression in body

@item
@code{or} --- last expression
@end itemize

@noindent
The following core functions make tail calls,

@itemize @bullet
@item
@code{apply} --- tail call to given procedure

@item
@code{call-with-current-continuation} --- tail call to the procedure
receiving the new continuation

@item
@code{call-with-values} --- tail call to the values-receiving
procedure

@item
@code{eval} --- tail call to evaluate the form

@item
@code{string-any}, @code{string-every} --- tail call to predicate on
the last character (if that point is reached)
@end itemize

@sp 1
The above are just core functions and special forms.  Tail calls in
other modules are described with the relevant documentation, for
example SRFI-1 @code{any} and @code{every} (@pxref{SRFI-1 Searching}).

It will be noted there are a lot of places which could potentially be
tail calls, for instance the last call in a @code{for-each}, but only
those explicitly described are guaranteed.

@node The REPL
@subsubsection Using the Guile REPL

If you start Guile without specifying a particular program for it to
execute, Guile enters its standard Read Evaluate Print Loop --- or
@dfn{REPL} for short.  In this mode, Guile repeatedly reads in the next
Scheme expression that the user types, evaluates it, and prints the
resulting value.

The REPL is a useful mechanism for exploring the evaluation behaviour
described in the previous subsection.  If you type @code{string-append},
for example, the REPL replies @code{#<primitive-procedure
string-append>}, illustrating the relationship between the variable
@code{string-append} and the procedure value stored in that variable.

In this manual, the notation @result{} is used to mean ``evaluates
to''.  Wherever you see an example of the form

@lisp
@var{expression}
@result{}
@var{result}
@end lisp

@noindent
feel free to try it out yourself by typing @var{expression} into the
REPL and checking that it gives the expected @var{result}.

@node Syntax Summary
@subsubsection Summary of Common Syntax

This subsection lists the most commonly used Scheme syntactic
expressions, simply so that you will recognize common special syntax
when you see it.  For a full description of each of these syntaxes,
follow the appropriate reference.

@code{lambda} (@pxref{Lambda}) is used to construct procedure objects.

@code{define} (@pxref{Top Level}) is used to create a new variable and
set its initial value.

@code{set!} (@pxref{Top Level}) is used to modify an existing variable's
value.

@code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
create an inner lexical environment for the evaluation of a sequence of
expressions, in which a specified set of local variables is bound to the
values of a corresponding set of expressions.  For an introduction to
environments, see @xref{About Closure}.

@code{begin} (@pxref{begin}) executes a sequence of expressions in order
and returns the value of the last expression.  Note that this is not the
same as a procedure which returns its last argument, because the
evaluation of a procedure invocation expression does not guarantee to
evaluate the arguments in order.

@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
evaluation of argument expressions depending on whether one or more
conditions evaluate to ``true'' or ``false''.

@code{case} (@pxref{if cond case}) provides conditional evaluation of
argument expressions depending on whether a variable has one of a
specified group of values.

@code{and} (@pxref{and or}) executes a sequence of expressions in order
until either there are no expressions left, or one of them evaluates to
``false''.

@code{or} (@pxref{and or}) executes a sequence of expressions in order
until either there are no expressions left, or one of them evaluates to
``true''.

@node About Closure
@subsection The Concept of Closure

@cindex closure

The concept of @dfn{closure} is the idea that a lambda expression
``captures'' the variable bindings that are in lexical scope at the
point where the lambda expression occurs.  The procedure created by the
lambda expression can refer to and mutate the captured bindings, and the
values of those bindings persist between procedure calls.

This section explains and explores the various parts of this idea in
more detail.

@menu
* About Environments::          Names, locations, values and environments.
* Local Variables::             Local variables and local environments.
* Chaining::                    Environment chaining.
* Lexical Scope::               The meaning of lexical scoping.
* Closure::                     Explaining the concept of closure.
* Serial Number::               Example 1: a serial number generator.
* Shared Variable::             Example 2: a shared persistent variable.
* Callback Closure::            Example 3: the callback closure problem.
* OO Closure::                  Example 4: object orientation.
@end menu

@node About Environments
@subsubsection Names, Locations, Values and Environments

@cindex location
@cindex environment
@cindex vcell
@cindex top level environment
@cindex environment, top level

We said earlier that a variable name in a Scheme program is associated
with a location in which any kind of Scheme value may be stored.
(Incidentally, the term ``vcell'' is often used in Lisp and Scheme
circles as an alternative to ``location''.)  Thus part of what we mean
when we talk about ``creating a variable'' is in fact establishing an
association between a name, or identifier, that is used by the Scheme
program code, and the variable location to which that name refers.
Although the value that is stored in that location may change, the
location to which a given name refers is always the same.

We can illustrate this by breaking down the operation of the
@code{define} syntax into three parts: @code{define}

@itemize @bullet
@item
creates a new location

@item
establishes an association between that location and the name specified
as the first argument of the @code{define} expression

@item
stores in that location the value obtained by evaluating the second
argument of the @code{define} expression.
@end itemize

A collection of associations between names and locations is called an
@dfn{environment}.  When you create a top level variable in a program
using @code{define}, the name-location association for that variable is
added to the ``top level'' environment.  The ``top level'' environment
also includes name-location associations for all the procedures that are
supplied by standard Scheme.

It is also possible to create environments other than the top level one,
and to create variable bindings, or name-location associations, in those
environments.  This ability is a key ingredient in the concept of
closure; the next subsection shows how it is done.

@node Local Variables
@subsubsection Local Variables and Environments

@cindex local variable
@cindex variable, local
@cindex local environment
@cindex environment, local

We have seen how to create top level variables using the @code{define}
syntax (@pxref{Definition}).  It is often useful to create variables
that are more limited in their scope, typically as part of a procedure
body.  In Scheme, this is done using the @code{let} syntax, or one of
its modified forms @code{let*} and @code{letrec}.  These syntaxes are
described in full later in the manual (@pxref{Local Bindings}).  Here
our purpose is to illustrate their use just enough that we can see how
local variables work.

For example, the following code uses a local variable @code{s} to
simplify the computation of the area of a triangle given the lengths of
its three sides.

@lisp
(define a 5.3)
(define b 4.7)
(define c 2.8)

(define area
  (let ((s (/ (+ a b c) 2)))
    (sqrt (* s (- s a) (- s b) (- s c)))))
@end lisp

The effect of the @code{let} expression is to create a new environment
and, within this environment, an association between the name @code{s}
and a new location whose initial value is obtained by evaluating
@code{(/ (+ a b c) 2)}.  The expressions in the body of the @code{let},
namely @code{(sqrt (* s (- s a) (- s b) (- s c)))}, are then evaluated
in the context of the new environment, and the value of the last
expression evaluated becomes the value of the whole @code{let}
expression, and therefore the value of the variable @code{area}.

@node Chaining
@subsubsection Environment Chaining

@cindex shadowing an imported variable binding
@cindex chaining environments

In the example of the previous subsection, we glossed over an important
point.  The body of the @code{let} expression in that example refers not
only to the local variable @code{s}, but also to the top level variables
@code{a}, @code{b}, @code{c} and @code{sqrt}.  (@code{sqrt} is the
standard Scheme procedure for calculating a square root.)  If the body
of the @code{let} expression is evaluated in the context of the
@emph{local} @code{let} environment, how does the evaluation get at the
values of these top level variables?

The answer is that the local environment created by a @code{let}
expression automatically has a reference to its containing environment
--- in this case the top level environment --- and that the Scheme
interpreter automatically looks for a variable binding in the containing
environment if it doesn't find one in the local environment.  More
generally, every environment except for the top level one has a
reference to its containing environment, and the interpreter keeps
searching back up the chain of environments --- from most local to top
level --- until it either finds a variable binding for the required
identifier or exhausts the chain.

This description also determines what happens when there is more than
one variable binding with the same name.  Suppose, continuing the
example of the previous subsection, that there was also a pre-existing
top level variable @code{s} created by the expression:

@lisp
(define s "Some beans, my lord!")
@end lisp

Then both the top level environment and the local @code{let} environment
would contain bindings for the name @code{s}.  When evaluating code
within the @code{let} body, the interpreter looks first in the local
@code{let} environment, and so finds the binding for @code{s} created by
the @code{let} syntax.  Even though this environment has a reference to
the top level environment, which also has a binding for @code{s}, the
interpreter doesn't get as far as looking there.  When evaluating code
outside the @code{let} body, the interpreter looks up variable names in
the top level environment, so the name @code{s} refers to the top level
variable.

Within the @code{let} body, the binding for @code{s} in the local
environment is said to @dfn{shadow} the binding for @code{s} in the top
level environment.

@node Lexical Scope
@subsubsection Lexical Scope

The rules that we have just been describing are the details of how
Scheme implements ``lexical scoping''.  This subsection takes a brief
diversion to explain what lexical scope means in general and to present
an example of non-lexical scoping.

``Lexical scope'' in general is the idea that

@itemize @bullet
@item
an identifier at a particular place in a program always refers to the
same variable location --- where ``always'' means ``every time that the
containing expression is executed'', and that

@item
the variable location to which it refers can be determined by static
examination of the source code context in which that identifier appears,
without having to consider the flow of execution through the program as
a whole.
@end itemize

In practice, lexical scoping is the norm for most programming languages,
and probably corresponds to what you would intuitively consider to be
``normal''.  You may even be wondering how the situation could possibly
--- and usefully --- be otherwise.  To demonstrate that another kind of
scoping is possible, therefore, and to compare it against lexical
scoping, the following subsection presents an example of non-lexical
scoping and examines in detail how its behavior differs from the
corresponding lexically scoped code.

@c @menu
@c * Scoping Example::             An example of non-lexical scoping.
@c @end menu

@c @node Scoping Example
@subsubheading An Example of Non-Lexical Scoping

To demonstrate that non-lexical scoping does exist and can be useful, we
present the following example from Emacs Lisp, which is a ``dynamically
scoped'' language.

@lisp
(defvar currency-abbreviation "USD")

(defun currency-string (units hundredths)
  (concat currency-abbreviation
          (number-to-string units)
          "."
          (number-to-string hundredths)))

(defun french-currency-string (units hundredths)
  (let ((currency-abbreviation "FRF"))
    (currency-string units hundredths)))
@end lisp

The question to focus on here is: what does the identifier
@code{currency-abbreviation} refer to in the @code{currency-string}
function?  The answer, in Emacs Lisp, is that all variable bindings go
onto a single stack, and that @code{currency-abbreviation} refers to the
topmost binding from that stack which has the name
``currency-abbreviation''.  The binding that is created by the
@code{defvar} form, to the value @code{"USD"}, is only relevant if none
of the code that calls @code{currency-string} rebinds the name
``currency-abbreviation'' in the meanwhile.

The second function @code{french-currency-string} works precisely by
taking advantage of this behaviour.  It creates a new binding for the
name ``currency-abbreviation'' which overrides the one established by
the @code{defvar} form.

@lisp
;; Note!  This is Emacs Lisp evaluation, not Scheme!
(french-currency-string 33 44)
@result{}
"FRF33.44"
@end lisp

Now let's look at the corresponding, @emph{lexically scoped} Scheme
code:

@lisp
(define currency-abbreviation "USD")

(define (currency-string units hundredths)
  (string-append currency-abbreviation
                 (number->string units)
                 "."
                 (number->string hundredths)))

(define (french-currency-string units hundredths)
  (let ((currency-abbreviation "FRF"))
    (currency-string units hundredths)))
@end lisp

According to the rules of lexical scoping, the
@code{currency-abbreviation} in @code{currency-string} refers to the
variable location in the innermost environment at that point in the code
which has a binding for @code{currency-abbreviation}, which is the
variable location in the top level environment created by the preceding
@code{(define currency-abbreviation @dots{})} expression.

In Scheme, therefore, the @code{french-currency-string} procedure does
not work as intended.  The variable binding that it creates for
``currency-abbreviation'' is purely local to the code that forms the
body of the @code{let} expression.  Since this code doesn't directly use
the name ``currency-abbreviation'' at all, the binding is pointless.

@lisp
(french-currency-string 33 44)
@result{}
"USD33.44"
@end lisp

This begs the question of how the Emacs Lisp behaviour can be
implemented in Scheme.  In general, this is a design question whose
answer depends upon the problem that is being addressed.  In this case,
the best answer may be that @code{currency-string} should be
redesigned so that it can take an optional third argument.  This third
argument, if supplied, is interpreted as a currency abbreviation that
overrides the default.

It is possible to change @code{french-currency-string} so that it mostly
works without changing @code{currency-string}, but the fix is inelegant,
and susceptible to interrupts that could leave the
@code{currency-abbreviation} variable in the wrong state:

@lisp
(define (french-currency-string units hundredths)
  (set! currency-abbreviation "FRF")
  (let ((result (currency-string units hundredths)))
    (set! currency-abbreviation "USD")
    result))
@end lisp

The key point here is that the code does not create any local binding
for the identifier @code{currency-abbreviation}, so all occurrences of
this identifier refer to the top level variable.

@node Closure
@subsubsection Closure

Consider a @code{let} expression that doesn't contain any
@code{lambda}s:

@lisp
(let ((s (/ (+ a b c) 2)))
  (sqrt (* s (- s a) (- s b) (- s c))))
@end lisp

@noindent
When the Scheme interpreter evaluates this, it

@itemize @bullet
@item
creates a new environment with a reference to the environment that was
current when it encountered the @code{let}

@item
creates a variable binding for @code{s} in the new environment, with
value given by @code{(/ (+ a b c) 2)}

@item
evaluates the expression in the body of the @code{let} in the context of
the new local environment, and remembers the value @code{V}

@item
forgets the local environment

@item
continues evaluating the expression that contained the @code{let}, using
the value @code{V} as the value of the @code{let} expression, in the
context of the containing environment.
@end itemize

After the @code{let} expression has been evaluated, the local
environment that was created is simply forgotten, and there is no longer
any way to access the binding that was created in this environment.  If
the same code is evaluated again, it will follow the same steps again,
creating a second new local environment that has no connection with the
first, and then forgetting this one as well.

If the @code{let} body contains a @code{lambda} expression, however, the
local environment is @emph{not} forgotten.  Instead, it becomes
associated with the procedure that is created by the @code{lambda}
expression, and is reinstated every time that that procedure is called.
In detail, this works as follows.

@itemize @bullet
@item
When the Scheme interpreter evaluates a @code{lambda} expression, to
create a procedure object, it stores the current environment as part of
the procedure definition.

@item
Then, whenever that procedure is called, the interpreter reinstates the
environment that is stored in the procedure definition and evaluates the
procedure body within the context of that environment.
@end itemize

The result is that the procedure body is always evaluated in the context
of the environment that was current when the procedure was created.

This is what is meant by @dfn{closure}.  The next few subsections
present examples that explore the usefulness of this concept.

@node Serial Number
@subsubsection Example 1: A Serial Number Generator

This example uses closure to create a procedure with a variable binding
that is private to the procedure, like a local variable, but whose value
persists between procedure calls.

@lisp
(define (make-serial-number-generator)
  (let ((current-serial-number 0))
    (lambda ()
      (set! current-serial-number (+ current-serial-number 1))
      current-serial-number)))

(define entry-sn-generator (make-serial-number-generator))

(entry-sn-generator)
@result{}
1

(entry-sn-generator)
@result{}
2
@end lisp

When @code{make-serial-number-generator} is called, it creates a local
environment with a binding for @code{current-serial-number} whose
initial value is 0, then, within this environment, creates a procedure.
The local environment is stored within the created procedure object and
so persists for the lifetime of the created procedure.

Every time the created procedure is invoked, it increments the value of
the @code{current-serial-number} binding in the captured environment and
then returns the current value.

Note that @code{make-serial-number-generator} can be called again to
create a second serial number generator that is independent of the
first.  Every new invocation of @code{make-serial-number-generator}
creates a new local @code{let} environment and returns a new procedure
object with an association to this environment.

@node Shared Variable
@subsubsection Example 2: A Shared Persistent Variable

This example uses closure to create two procedures, @code{get-balance}
and @code{deposit}, that both refer to the same captured local
environment so that they can both access the @code{balance} variable
binding inside that environment.  The value of this variable binding
persists between calls to either procedure.

Note that the captured @code{balance} variable binding is private to
these two procedures: it is not directly accessible to any other code.
It can only be accessed indirectly via @code{get-balance} or
@code{deposit}, as illustrated by the @code{withdraw} procedure.

@lisp
(define get-balance #f)
(define deposit #f)

(let ((balance 0))
  (set! get-balance
        (lambda ()
          balance))
  (set! deposit
        (lambda (amount)
          (set! balance (+ balance amount))
          balance)))

(define (withdraw amount)
  (deposit (- amount)))

(get-balance)
@result{}
0

(deposit 50)
@result{}
50

(withdraw 75)
@result{}
-25
@end lisp

An important detail here is that the @code{get-balance} and
@code{deposit} variables must be set up by @code{define}ing them at top
level and then @code{set!}ing their values inside the @code{let} body.
Using @code{define} within the @code{let} body would not work: this
would create variable bindings within the local @code{let} environment
that would not be accessible at top level.

@node Callback Closure
@subsubsection Example 3: The Callback Closure Problem

A frequently used programming model for library code is to allow an
application to register a callback function for the library to call when
some particular event occurs.  It is often useful for the application to
make several such registrations using the same callback function, for
example if several similar library events can be handled using the same
application code, but the need then arises to distinguish the callback
function calls that are associated with one callback registration from
those that are associated with different callback registrations.

In languages without the ability to create functions dynamically, this
problem is usually solved by passing a @code{user_data} parameter on the
registration call, and including the value of this parameter as one of
the parameters on the callback function.  Here is an example of
declarations using this solution in C:

@example
typedef void (event_handler_t) (int event_type,
                                void *user_data);

void register_callback (int event_type,
                        event_handler_t *handler,
                        void *user_data);
@end example

In Scheme, closure can be used to achieve the same functionality without
requiring the library code to store a @code{user-data} for each callback
registration.

@lisp
;; In the library:

(define (register-callback event-type handler-proc)
  @dots{})

;; In the application:

(define (make-handler event-type user-data)
  (lambda ()
    @dots{}
    <code referencing event-type and user-data>
    @dots{}))

(register-callback event-type
                   (make-handler event-type @dots{}))
@end lisp

As far as the library is concerned, @code{handler-proc} is a procedure
with no arguments, and all the library has to do is call it when the
appropriate event occurs.  From the application's point of view, though,
the handler procedure has used closure to capture an environment that
includes all the context that the handler code needs ---
@code{event-type} and @code{user-data} --- to handle the event
correctly.

@node OO Closure
@subsubsection Example 4: Object Orientation

Closure is the capture of an environment, containing persistent variable
bindings, within the definition of a procedure or a set of related
procedures.  This is rather similar to the idea in some object oriented
languages of encapsulating a set of related data variables inside an
``object'', together with a set of ``methods'' that operate on the
encapsulated data.  The following example shows how closure can be used
to emulate the ideas of objects, methods and encapsulation in Scheme.

@lisp
(define (make-account)
  (let ((balance 0))
    (define (get-balance)
      balance)
    (define (deposit amount)
      (set! balance (+ balance amount))
      balance)
    (define (withdraw amount)
      (deposit (- amount)))

    (lambda args
      (apply
        (case (car args)
          ((get-balance) get-balance)
          ((deposit) deposit)
          ((withdraw) withdraw)
          (else (error "Invalid method!")))
        (cdr args)))))
@end lisp

Each call to @code{make-account} creates and returns a new procedure,
created by the expression in the example code that begins ``(lambda
args''.

@lisp
(define my-account (make-account))

my-account
@result{}
#<procedure args>
@end lisp

This procedure acts as an account object with methods
@code{get-balance}, @code{deposit} and @code{withdraw}.  To apply one of
the methods to the account, you call the procedure with a symbol
indicating the required method as the first parameter, followed by any
other parameters that are required by that method.

@lisp
(my-account 'get-balance)
@result{}
0

(my-account 'withdraw 5)
@result{}
-5

(my-account 'deposit 396)
@result{}
391

(my-account 'get-balance)
@result{}
391
@end lisp

Note how, in this example, both the current balance and the helper
procedures @code{get-balance}, @code{deposit} and @code{withdraw}, used
to implement the guts of the account object's methods, are all stored in
variable bindings within the private local environment captured by the
@code{lambda} expression that creates the account object procedure.

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node R5RS Index
@unnumbered R5RS Index

@printindex rn

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Guile Scheme
@section Guile's Implementation of Scheme

Guile's core language is Scheme, which is specified and described in the
series of reports known as @dfn{RnRS}.  @dfn{RnRS} is shorthand for the
@iftex
@dfn{Revised$^n$ Report on the Algorithmic Language Scheme}.
@end iftex
@ifnottex
@dfn{Revised^n Report on the Algorithmic Language Scheme}.
@end ifnottex
The current latest revision of RnRS is version 5
(@pxref{Top,R5RS,,r5rs}), and Guile 1.4 is fully compliant with the
Scheme specification in this revision.

But Guile, like most Scheme implementations, also goes beyond R5RS in
many ways, because R5RS does not give specifications (or even
recommendations) regarding many issues that are important in practical
programming.  Some of the areas where Guile extends R5RS are:

@itemize @bullet
@item
Guile's interactive documentation system

@item
Guile's support for POSIX-compliant network programming

@item
GOOPS -- Guile's framework for object oriented programming.
@end itemize

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Further Reading
@section Further Reading

@itemize @bullet

@item
The website @url{http://www.schemers.org} is a good starting point for
all things Scheme.

@item
Dorai Sitaram's online Scheme tutorial, @dfn{Teach Yourself Scheme in
Fixnum Days}, at
@url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html}.
Includes a nice explanation of continuations.

@item
The complete text of @dfn{Structure and Interpretation of Computer
Programs}, the classic introduction to computer science and Scheme by
Hal Abelson, Jerry Sussman and Julie Sussman, is now available online at
@url{http://mitpress.mit.edu/sicp/sicp.html}.  This site also provides
teaching materials related to the book, and all the source code used in
the book, in a form suitable for loading and running.
@end itemize

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Guile Scripting
@section Guile Scripting

Like AWK, Perl, or any shell, Guile can interpret script files.  A Guile
script is simply a file of Scheme code with some extra information at
the beginning which tells the operating system how to invoke Guile, and
then tells Guile how to handle the Scheme code.

@menu
* The Top of a Script File::    How to start a Guile script.
* Invoking Guile::              Command line options understood by Guile.
* The Meta Switch::             Passing complex argument lists to Guile
                                from shell scripts.
* Command Line Handling::       Accessing the command line from a script.
* Scripting Examples::
@end menu

@node The Top of a Script File
@subsection The Top of a Script File

The first line of a Guile script must tell the operating system to use
Guile to evaluate the script, and then tell Guile how to go about doing
that.  Here is the simplest case:

@itemize @bullet

@item
The first two characters of the file must be @samp{#!}.

The operating system interprets this to mean that the rest of the line
is the name of an executable that can interpret the script.  Guile,
however, interprets these characters as the beginning of a multi-line
comment, terminated by the characters @samp{!#} on a line by themselves.
(This is an extension to the syntax described in R5RS, added to support
shell scripts.)

@item
Immediately after those two characters must come the full pathname to
the Guile interpreter.  On most systems, this would be
@samp{/usr/local/bin/guile}.

@item
Then must come a space, followed by a command-line argument to pass to
Guile; this should be @samp{-s}.  This switch tells Guile to run a
script, instead of soliciting the user for input from the terminal.
There are more elaborate things one can do here; see @ref{The Meta
Switch}.

@item
Follow this with a newline.

@item
The second line of the script should contain only the characters
@samp{!#} --- just like the top of the file, but reversed.  The
operating system never reads this far, but Guile treats this as the end
of the comment begun on the first line by the @samp{#!} characters.

@item
The rest of the file should be a Scheme program.

@end itemize

Guile reads the program, evaluating expressions in the order that they
appear.  Upon reaching the end of the file, Guile exits.

@node Invoking Guile
@subsection Invoking Guile
@cindex invocation

Here we describe Guile's command-line processing in detail.  Guile
processes its arguments from left to right, recognizing the switches
described below.  For examples, see @ref{Scripting Examples}.

@table @code

@item -s @var{script} @var{arg...}
Read and evaluate Scheme source code from the file @var{script}, as the
@code{load} function would.  After loading @var{script}, exit.  Any
command-line arguments @var{arg...} following @var{script} become the
script's arguments; the @code{command-line} function returns a list of
strings of the form @code{(@var{script} @var{arg...})}.

@item -c @var{expr} @var{arg...}
Evaluate @var{expr} as Scheme code, and then exit.  Any command-line
arguments @var{arg...} following @var{expr} become command-line arguments; the
@code{command-line} function returns a list of strings of the form
@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
Guile executable.

@item -- @var{arg...}
Run interactively, prompting the user for expressions and evaluating
them.  Any command-line arguments @var{arg...} following the @code{--}
become command-line arguments for the interactive session; the
@code{command-line} function returns a list of strings of the form
@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
Guile executable.

@item -L @var{directory}
Add @var{directory} to the front of Guile's module load path.  The
given directories are searched in the order given on the command line
and before any directories in the GUILE_LOAD_PATH environment
variable.  Paths added here are @emph{not} in effect during execution
of the user's @file{.guile} file.

@item -l @var{file}
Load Scheme source code from @var{file}, and continue processing the
command line.

@item -e @var{function}
Make @var{function} the @dfn{entry point} of the script.  After loading
the script file (with @code{-s}) or evaluating the expression (with
@code{-c}), apply @var{function} to a list containing the program name
and the command-line arguments --- the list provided by the
@code{command-line} function.

A @code{-e} switch can appear anywhere in the argument list, but Guile
always invokes the @var{function} as the @emph{last} action it performs.
This is weird, but because of the way script invocation works under
POSIX, the @code{-s} option must always come last in the list.

The @var{function} is most often a simple symbol that names a function
that is defined in the script.  It can also be of the form @code{(@@
@var{module-name} @var{symbol})} and in that case, the symbol is
looked up in the module named @var{module-name}.

For compatibility with some versions of Guile 1.4, you can also use the
form @code{(symbol ...)} (that is, a list of only symbols that doesn't
start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
main)}, or @code{(symbol ...)  symbol} (that is, a list of only symbols
followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
symbol)}.  We recommend to use the equivalent forms directly since they
corresponf to the @code{(@@ ...)}  read syntax that can be used in
normal code, @xref{Using Guile Modules}.

@xref{Scripting Examples}.

@item -ds
Treat a final @code{-s} option as if it occurred at this point in the
command line; load the script here.

This switch is necessary because, although the POSIX script invocation
mechanism effectively requires the @code{-s} option to appear last, the
programmer may well want to run the script before other actions
requested on the command line.  For examples, see @ref{Scripting
Examples}.

@item \
Read more command-line arguments, starting from the second line of the
script file.  @xref{The Meta Switch}.

@item --emacs
Assume Guile is running as an inferior process of Emacs, and use a
special protocol to communicate with Emacs's Guile interaction mode.
This switch sets the global variable use-emacs-interface to @code{#t}.

This switch is still experimental.

@item --use-srfi=@var{list}
The option @code{--use-srfi} expects a comma-separated list of numbers,
each representing a SRFI number to be loaded into the interpreter
before starting evaluating a script file or the REPL.  Additionally,
the feature identifier for the loaded SRFIs is recognized by
`cond-expand' when using this option.

@example
guile --use-srfi=8,13
@end example

@item --debug
Start with the debugging evaluator and enable backtraces.  Using the
debugging evaluator will give you better error messages but it will
slow down execution.  By default, the debugging evaluator is only used
when entering an interactive session.  When executing a script with
@code{-s} or @code{-c}, the normal, faster evaluator is used by default.

@vnew{1.8}
@item --no-debug
Do not use the debugging evaluator, even when entering an interactive
session.

@item -h@r{, }--help
Display help on invoking Guile, and then exit.

@item -v@r{, }--version
Display the current version of Guile, and then exit.

@end table

@node The Meta Switch
@subsection The Meta Switch

Guile's command-line switches allow the programmer to describe
reasonably complicated actions in scripts.  Unfortunately, the POSIX
script invocation mechanism only allows one argument to appear on the
@samp{#!} line after the path to the Guile executable, and imposes
arbitrary limits on that argument's length.  Suppose you wrote a script
starting like this:
@example
#!/usr/local/bin/guile -e main -s
!#
(define (main args)
  (map (lambda (arg) (display arg) (display " "))
       (cdr args))
  (newline))
@end example
The intended meaning is clear: load the file, and then call @code{main}
on the command-line arguments.  However, the system will treat
everything after the Guile path as a single argument --- the string
@code{"-e main -s"} --- which is not what we want.

As a workaround, the meta switch @code{\} allows the Guile programmer to
specify an arbitrary number of options without patching the kernel.  If
the first argument to Guile is @code{\}, Guile will open the script file
whose name follows the @code{\}, parse arguments starting from the
file's second line (according to rules described below), and substitute
them for the @code{\} switch.

Working in concert with the meta switch, Guile treats the characters
@samp{#!} as the beginning of a comment which extends through the next
line containing only the characters @samp{!#}.  This sort of comment may
appear anywhere in a Guile program, but it is most useful at the top of
a file, meshing magically with the POSIX script invocation mechanism.

Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
@example
#!/usr/local/bin/guile \
-e main -s
!#
(define (main args)
        (map (lambda (arg) (display arg) (display " "))
             (cdr args))
        (newline))
@end example

Suppose a user invokes this script as follows:
@example
$ /u/jimb/ekko a b c
@end example

Here's what happens:
@itemize @bullet

@item
the operating system recognizes the @samp{#!} token at the top of the
file, and rewrites the command line to:
@example
/usr/local/bin/guile \ /u/jimb/ekko a b c
@end example
This is the usual behavior, prescribed by POSIX.

@item
When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
@file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
and @code{-s} from it, and substitutes them for the @code{\} switch.
Thus, Guile's command line now reads:
@example
/usr/local/bin/guile -e main -s /u/jimb/ekko a b c
@end example

@item
Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
file of Scheme code (treating the first three lines as a comment), and
then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.

@end itemize

When Guile sees the meta switch @code{\}, it parses command-line
argument from the script file according to the following rules:
@itemize @bullet

@item
Each space character terminates an argument.  This means that two
spaces in a row introduce an argument @code{""}.

@item
The tab character is not permitted (unless you quote it with the
backslash character, as described below), to avoid confusion.

@item
The newline character terminates the sequence of arguments, and will
also terminate a final non-empty argument.  (However, a newline
following a space will not introduce a final empty-string argument;
it only terminates the argument list.)

@item
The backslash character is the escape character.  It escapes backslash,
space, tab, and newline.  The ANSI C escape sequences like @code{\n} and
@code{\t} are also supported.  These produce argument constituents; the
two-character combination @code{\n} doesn't act like a terminating
newline.  The escape sequence @code{\@var{NNN}} for exactly three octal
digits reads as the character whose ASCII code is @var{NNN}.  As above,
characters produced this way are argument constituents.  Backslash
followed by other characters is not allowed.

@end itemize

@node Command Line Handling
@subsection Command Line Handling

@c This section was written and contributed by Martin Grabmueller.

The ability to accept and handle command line arguments is very
important when writing Guile scripts to solve particular problems, such
as extracting information from text files or interfacing with existing
command line applications.  This chapter describes how Guile makes
command line arguments available to a Guile script, and the utilities
that Guile provides to help with the processing of command line
arguments.

When a Guile script is invoked, Guile makes the command line arguments
accessible via the procedure @code{command-line}, which returns the
arguments as a list of strings.

For example, if the script

@example
#! /usr/local/bin/guile -s
!#
(write (command-line))
(newline)
@end example

@noindent
is saved in a file @file{cmdline-test.scm} and invoked using the command
line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
is

@example
("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
@end example

If the script invocation includes a @code{-e} option, specifying a
procedure to call after loading the script, Guile will call that
procedure with @code{(command-line)} as its argument.  So a script that
uses @code{-e} doesn't need to refer explicitly to @code{command-line}
in its code.  For example, the script above would have identical
behaviour if it was written instead like this:

@example
#! /usr/local/bin/guile \
-e main -s
!#
(define (main args)
  (write args)
  (newline))
@end example

(Note the use of the meta switch @code{\} so that the script invocation
can include more than one Guile option: @xref{The Meta Switch}.)

These scripts use the @code{#!} POSIX convention so that they can be
executed using their own file names directly, as in the example command
line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}.  But they
can also be executed by typing out the implied Guile command line in
full, as in:

@example
$ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
@end example

@noindent
or

@example
$ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
@end example

Even when a script is invoked using this longer form, the arguments that
the script receives are the same as if it had been invoked using the
short form.  Guile ensures that the @code{(command-line)} or @code{-e}
arguments are independent of how the script is invoked, by stripping off
the arguments that Guile itself processes.

A script is free to parse and handle its command line arguments in any
way that it chooses.  Where the set of possible options and arguments is
complex, however, it can get tricky to extract all the options, check
the validity of given arguments, and so on.  This task can be greatly
simplified by taking advantage of the module @code{(ice-9 getopt-long)},
which is distributed with Guile, @xref{getopt-long}.

@node Scripting Examples
@subsection Scripting Examples

To start with, here are some examples of invoking Guile directly:

@table @code

@item guile -- a b c
Run Guile interactively; @code{(command-line)} will return @*
@code{("/usr/local/bin/guile" "a" "b" "c")}.

@item guile -s /u/jimb/ex2 a b c
Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
@code{("/u/jimb/ex2" "a" "b" "c")}.

@item guile -c '(write %load-path) (newline)'
Write the value of the variable @code{%load-path}, print a newline,
and exit.

@item guile -e main -s /u/jimb/ex4 foo
Load the file @file{/u/jimb/ex4}, and then call the function
@code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.

@item guile -l first -ds -l last -s script
Load the files @file{first}, @file{script}, and @file{last}, in that
order.  The @code{-ds} switch says when to process the @code{-s}
switch.  For a more motivated example, see the scripts below.

@end table

Here is a very simple Guile script:
@example
#!/usr/local/bin/guile -s
!#
(display "Hello, world!")
(newline)
@end example
The first line marks the file as a Guile script.  When the user invokes
it, the system runs @file{/usr/local/bin/guile} to interpret the script,
passing @code{-s}, the script's filename, and any arguments given to the
script as command-line arguments.  When Guile sees @code{-s
@var{script}}, it loads @var{script}.  Thus, running this program
produces the output:
@example
Hello, world!
@end example

Here is a script which prints the factorial of its argument:
@example
#!/usr/local/bin/guile -s
!#
(define (fact n)
  (if (zero? n) 1
    (* n (fact (- n 1)))))

(display (fact (string->number (cadr (command-line)))))
(newline)
@end example
In action:
@example
$ fact 5
120
$
@end example

However, suppose we want to use the definition of @code{fact} in this
file from another script.  We can't simply @code{load} the script file,
and then use @code{fact}'s definition, because the script will try to
compute and display a factorial when we load it.  To avoid this problem,
we might write the script this way:

@example
#!/usr/local/bin/guile \
-e main -s
!#
(define (fact n)
  (if (zero? n) 1
    (* n (fact (- n 1)))))

(define (main args)
  (display (fact (string->number (cadr args))))
  (newline))
@end example
This version packages the actions the script should perform in a
function, @code{main}.  This allows us to load the file purely for its
definitions, without any extraneous computation taking place.  Then we
used the meta switch @code{\} and the entry point switch @code{-e} to
tell Guile to call @code{main} after loading the script.
@example
$ fact 50
30414093201713378043612608166064768844377641568960512000000000000
@end example

Suppose that we now want to write a script which computes the
@code{choose} function: given a set of @var{m} distinct objects,
@code{(choose @var{n} @var{m})} is the number of distinct subsets
containing @var{n} objects each.  It's easy to write @code{choose} given
@code{fact}, so we might write the script this way:
@example
#!/usr/local/bin/guile \
-l fact -e main -s
!#
(define (choose n m)
  (/ (fact m) (* (fact (- m n)) (fact n))))

(define (main args)
  (let ((n (string->number (cadr args)))
        (m (string->number (caddr args))))
    (display (choose n m))
    (newline)))
@end example

The command-line arguments here tell Guile to first load the file
@file{fact}, and then run the script, with @code{main} as the entry
point.  In other words, the @code{choose} script can use definitions
made in the @code{fact} script.  Here are some sample runs:
@example
$ choose 0 4
1
$ choose 1 4
4
$ choose 2 4
6
$ choose 3 4
4
$ choose 4 4
1
$ choose 50 100
100891344545564193334812497256
@end example

@c Local Variables:
@c TeX-master: "guile.texi"
@c End: