   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

The Guile Reference Manual
**************************

   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 Info file contains edition 1.0 of the reference manual,
corresponding to Guile version 1.6.4.

Preface

Part I: Introduction to Guile

Part II: Writing and Running Guile Scheme

Part III: Guile as an Extension Language

Part IV: Guile API Reference

Part V: Guile Modules

Indices

The Guile License
*****************

   The license of Guile consists of the GNU GPL plus a special statement
giving blanket permission to link with non-free software.  This is the
license statement as found in any individual file that it applies to:

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License as
     published by the Free Software Foundation; either version 2, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this software; see the file COPYING.  If not, write to
     the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
     Boston, MA 02111-1307 USA

     As a special exception, the Free Software Foundation gives
     permission for additional uses of the text contained in its
     release of GUILE.

     The exception is that, if you link the GUILE library with other
     files to produce an executable, this does not by itself cause the
     resulting executable to be covered by the GNU General Public
     License.  Your use of that executable is in no way restricted on
     account of linking the GUILE library code into it.

     This exception does not however invalidate any other reasons why
     the executable file might be covered by the GNU General Public
     License.

     This exception applies only to the code released by the Free
     Software Foundation under the name GUILE.  If you copy code from
     other Free Software Foundation releases into a copy of GUILE, as
     the General Public License permits, the exception does not apply
     to the code that you add in this way.  To avoid misleading anyone
     as to the status of such modified files, you must delete this
     exception notice from them.

     If you write modifications of your own for GUILE, it is your choice
     whether to permit this exception to apply to your modifications.
     If you do not wish that, delete this exception notice.

Layout of this Manual
*********************

   The manual is divided into five parts.

   *Part I: Introduction to Guile* 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.

   *Part II: Writing and Running Guile Scheme* and *Part III:
Programming with Guile* document all aspects of practical programming
using Guile.  This covers both the Scheme level -- where we provide an
introduction to the key ideas of the Scheme language -- and use of
Guile's `scm' interface to write new primitives and objects in C, and
to incorporate Guile into a C application.  It also covers the use of
Guile as a POSIX compliant script interpreter, and how to use the Guile
debugger.

   *Part IV: Guile API Reference* documents Guile's core API.  Most of
the variables and procedures in Guile's core programming interface are
available in both Scheme and C, and are related systematically such
that the C interface can be inferred from the Scheme interface and vice
versa.  Therefore this part of the manual documents the Guile API in
functionality-based groups with the Scheme and C interfaces presented
side by side.  Where the Scheme and C interfaces for a particular
functional area do differ -- which is sometimes inevitable, given the
differences in the structure of the two languages -- this is pointed
out and explained.  In all cases the overriding principle is that all
the reference documentation for a given functional area is grouped
together.

   *Part V: Guile Modules* describes some important modules,
distributed as part of the Guile distribution, that extend the
functionality provided by the Guile Scheme core.  Two important examples
are:

   * the POSIX module, which provides Scheme level procedures for
     system and network programming that conform to the POSIX standard

   * the SLIB module, which makes Aubrey Jaffer's portable Scheme
     library available for use in Guile.

Conventions used in this Manual
*******************************

   We use some conventions in this manual.

   * For some procedures, notably type predicates, we use "iff" to mean
     `if and only if'.  The construct is usually something like:
     `Return VAL iff CONDITION', where VAL is usually ``#t'' or
     `non-`#f''.  This typically means that VAL is returned if
     CONDITION holds, and that `#f' is returned otherwise.

   * 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 `=>' is used to tell which value is returned by an
     evaluation:

          (+ 1 2)
          =>
          3

     Some procedures produce some output besides returning a value.
     This is denoted by the symbol `-|'.

          (begin (display 1) (newline) 'hooray)
          -| 1
          =>
          hooray

What is Guile?
**************

   Guile is an interpreter for the Scheme programming language, packaged
for use in a wide variety of environments.  Guile implements Scheme as
described in the Revised^5 Report on the Algorithmic Language Scheme
(usually known as R5RS), providing clean and general data and control
structures.  Guile goes beyond the rather austere language presented in
R5RS, extending it with a module system, full access to POSIX system
calls, networking support, multiple threads, dynamic linking, a foreign
function call interface, powerful string processing, and many other
features needed for programming in the real world.

   Like a shell, Guile can run interactively, reading expressions from
the user, evaluating them, and displaying the results, or as a script
interpreter, reading and executing Scheme code from a file.  However,
Guile is also packaged as an object library, allowing other applications
to easily incorporate a complete Scheme interpreter.  An application can
use Guile as an extension language, a clean and powerful configuration
language, or as multi-purpose "glue", connecting primitives provided by
the application.  It is easy to call Scheme code from C code and vice
versa, giving the application designer full control of how and when to
invoke the interpreter.  Applications can add new functions, data types,
control structures, and even syntax to Guile, creating a domain-specific
language tailored to the task at hand, but based on a robust language
design.

   Guile's module system allows one to break up a large program into
manageable sections with well-defined interfaces between them.  Modules
may contain a mixture of interpreted and compiled code; Guile can use
either static or dynamic linking to incorporate compiled code.  Modules
also encourage developers to package up useful collections of routines
for general distribution; as of this writing, one can find Emacs
interfaces, database access routines, compilers, GUI toolkit interfaces,
and HTTP client functions, among others.

   In the future, we hope to expand Guile to support other languages
like Tcl and Perl by translating them to Scheme code.  This means that
users can program applications which use Guile in the language of their
choice, rather than having the tastes of the application's author
imposed on them.

A Whirlwind Tour
****************

   This chapter presents a quick tour of all the ways that Guile can be
used.  There are additional examples in the `examples/' directory in
the Guile source distribution.

Running Guile Interactively
===========================

   In its simplest form, Guile acts as an interactive interpreter for
the Scheme programming language, reading and evaluating Scheme
expressions the user enters from the terminal.  Here is a sample
interaction between Guile and a user; the user's input appears after
the `$' and `guile>' prompts:

     $ guile
     guile> (+ 1 2 3)                ; add some numbers
     6
     guile> (define (factorial n)    ; define a function
              (if (zero? n) 1 (* n (factorial (- n 1)))))
     guile> (factorial 20)
     2432902008176640000
     guile> (getpwnam "jimb")        ; find my entry in /etc/passwd
     #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
       "/usr/local/bin/bash")
     guile> C-d
     $

Guile Scripts
=============

   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.

   Before we present the details, here is a trivial Guile script:

     #!/usr/local/bin/guile -s
     !#
     (display "Hello, world!")
     (newline)

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:

   * The first two characters of the file must be `#!'.

     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 `!#' on a line by
     themselves.  (This is an extension to the syntax described in
     R5RS, added to support shell scripts.)

   * Immediately after those two characters must come the full pathname
     to the Guile interpreter.  On most systems, this would be
     `/usr/local/bin/guile'.

   * Then must come a space, followed by a command-line argument to
     pass to Guile; this should be `-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
     The Meta Switch.

   * Follow this with a newline.

   * The second line of the script should contain only the characters
     `!#' -- 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 `#!'
     characters.

   * The rest of the file should be a Scheme program.

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

   The function `command-line' returns the name of the script file and
any command-line arguments passed by the user, as a list of strings.

   For example, consider the following script file:
     #!/usr/local/bin/guile -s
     !#
     (write (command-line))
     (newline)

   If you put that text in a file called `foo' in the current
directory, then you could make it executable and try it out like this:
     $ chmod a+x foo
     $ ./foo
     ("./foo")
     $ ./foo bar baz
     ("./foo" "bar" "baz")
     $

   As another example, here is a simple replacement for the POSIX
`echo' command:
     #!/usr/local/bin/guile -s
     !#
     (for-each (lambda (s) (display s) (display " "))
       (cdr (command-line)))
     (newline)

 - Scheme Procedure: command-line
 - Scheme Procedure: program-arguments
     Return a list of the command-line arguments passed to the currently
     running program.  If the program invoked Guile with the `-s', `-c'
     or `--' switches, these procedures ignore everything up to and
     including those switches.

Scripting Examples
------------------

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

`guile -- a b c'
     Run Guile interactively; `(command-line)' will return
     `("/usr/local/bin/guile" "a" "b" "c")'.

`guile -s /u/jimb/ex2 a b c'
     Load the file `/u/jimb/ex2'; `(command-line)' will return
     `("/u/jimb/ex2" "a" "b" "c")'.

`guile -c '(write %load-path) (newline)''
     Write the value of the variable `%load-path', print a newline, and
     exit.

`guile -e main -s /u/jimb/ex4 foo'
     Load the file `/u/jimb/ex4', and then call the function `main',
     passing it the list `("/u/jimb/ex4" "foo")'.

`guile -l first -ds -l last -s script'
     Load the files `first', `script', and `last', in that order.  The
     `-ds' switch says when to process the `-s' switch.  For a more
     motivated example, see the scripts below.

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

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

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

   However, suppose we want to use the definition of `fact' in this
file from another script.  We can't simply `load' the script file, and
then use `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:

     #!/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))
   This version packages the actions the script should perform in a
function, `main'.  This allows us to load the file purely for its
definitions, without any extraneous computation taking place.  Then we
used the meta switch `\' and the entry point switch `-e' to tell Guile
to call `main' after loading the script.
     $ fact 50
     30414093201713378043612608166064768844377641568960512000000000000

   Suppose that we now want to write a script which computes the
`choose' function: given a set of M distinct objects, `(choose N M)' is
the number of distinct subsets containing N objects each.  It's easy to
write `choose' given `fact', so we might write the script this way:
     #!/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)))

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

Linking Programs With Guile
===========================

   The Guile interpreter is available as an object library, to be linked
into applications using Scheme as a configuration or extension
language.  This chapter covers the mechanics of linking your program
with Guile on a typical POSIX system.

   Parts III and IV of this manual describe the C functions Guile
provides.  Furthermore, any Scheme function described in this manual as
a "Primitive" is also callable from C; see Primitives.

   The header file `<libguile.h>' provides declarations for all of
Guile's functions and constants.  You should `#include' it at the head
of any C source file that uses identifiers described in this manual.
Once you've compiled your source files, you need to link them against
the Guile object code library, `libguile'.

   On most systems, you should not need to tell the compiler and linker
explicitly where they can find `libguile.h' and `libguile'.  When Guile
has been installed in a peculiar way, or when you are on a peculiar
system, things might not be so easy and you might need to pass
additional `-I' or `-L' options to the compiler.  Guile provides the
utility program `guile-config' to help you find the right values for
these options.  You would typically run `guile-config' during the
configuration phase of your program and use the obtained information in
the Makefile.

Guile Initialization Functions
------------------------------

   To initialize Guile, you can use one of two functions.  The first,
`scm_boot_guile', is the most portable way to initialize Guile.  It
should be used whenever you have control over the main function of your
program because it never returns.  The second function,
`scm_init_guile', does return and can thus be used in more situations.
However, `scm_init_guile' is not as widely available as
`scm_boot_guile' because it needs to rely on non-portable code to find
the stack bounds.  When Guile does not know how to find these bounds on
your system, it will not provide `scm_init_guile'.

   When you can tolerate the limits of `scm_boot_guile', you should use
it in favor of `scm_init_guile' since that will make your program more
portable.

 - Function: void scm_boot_guile (int ARGC, char **ARGV, void
          (*MAIN_FUNC) (), void *CLOSURE)
     Initialize the Guile Scheme interpreter.  Then call MAIN_FUNC,
     passing it CLOSURE, ARGC, and ARGV.  MAIN_FUNC should do all the
     work of the program (initializing other packages, defining
     application-specific functions, reading user input, and so on)
     before returning.  When MAIN_FUNC returns, call `exit (0)';
     `scm_boot_guile' never returns.  If you want some other exit value,
     have MAIN_FUNC call exit itself.

     `scm_boot_guile' arranges for the Scheme `command-line' function
     to return the strings given by ARGC and ARGV.  If MAIN_FUNC
     modifies ARGC or ARGV, it should call `scm_set_program_arguments'
     with the final list, so Scheme code will know which arguments have
     been processed.

     Why must the caller do all the real work from MAIN_FUNC?  Guile's
     garbage collector scans the stack to find all local variables that
     reference Scheme objects.  To do this, it needs to know the bounds
     of the stack that might contain such references.  Because there is
     no portable way in C to find the base of the stack,
     `scm_boot_guile' assumes that all references are above its own
     stack frame.  If you try to manipulate Scheme objects after this
     function returns, it's the luck of the draw whether Guile's
     storage manager will be able to find the objects you allocate.
     So, `scm_boot_guile' function exits, rather than returning, to
     discourage you from making that mistake.

     See `scm_init_guile', below, for a function that can find the real
     base of the stack, but not in a portable way.

 - Function: void scm_init_guile ()
     Initialize the Guile Scheme interpreter.

     In contrast to `scm_boot_guile', this function knows how to find
     the true base of the stack and thus does not need to usurp the
     control flow of your program.  However, since finding the stack
     base can not be done portably, this function might not be
     available in all installations of Guile.  If you can, you should
     use `scm_boot_guile' instead.

     Note that `scm_init_guile' does not inform Guile about the command
     line arguments that should be returned by the Scheme function
     `command-line'.  You can use `scm_set_program_arguments' to do
     this.

   One common way to use Guile is to write a set of C functions which
perform some useful task, make them callable from Scheme, and then link
the program with Guile.  This yields a Scheme interpreter just like
`guile', but augmented with extra functions for some specific
application -- a special-purpose scripting language.

   In this situation, the application should probably process its
command-line arguments in the same manner as the stock Guile
interpreter.  To make that straightforward, Guile provides this
function:

 - Function: void scm_shell (int ARGC, char **ARGV)
     Process command-line arguments in the manner of the `guile'
     executable.  This includes loading the normal Guile initialization
     files, interacting with the user or running any scripts or
     expressions specified by `-s' or `-e' options, and then exiting.
     See Invoking Guile, for more details.

     Since this function does not return, you must do all
     application-specific initialization before calling this function.

A Sample Guile Main Program
---------------------------

   Here is `simple-guile.c', source code for a `main' and an
`inner_main' function that will produce a complete Guile interpreter.

     /* simple-guile.c --- how to start up the Guile
        interpreter from C code.  */

     /* Get declarations for all the scm_ functions.  */
     #include <libguile.h>

     static void
     inner_main (void *closure, int argc, char **argv)
     {
       /* module initializations would go here */
       scm_shell (argc, argv);
     }

     int
     main (int argc, char **argv)
     {
       scm_boot_guile (argc, argv, inner_main, 0);
       return 0; /* never reached */
     }

   The `main' function calls `scm_boot_guile' to initialize Guile,
passing it `inner_main'.  Once `scm_boot_guile' is ready, it invokes
`inner_main', which calls `scm_shell' to process the command-line
arguments in the usual way.

   Here is a Makefile which you can use to compile the above program.
It uses `guile-config' to learn about the necessary compiler and linker
flags.
     # Use GCC, if you have it installed.
     CC=gcc

     # Tell the C compiler where to find <libguile.h>
     CFLAGS=`guile-config compile`

     # Tell the linker what libraries to use and where to find them.
     LIBS=`guile-config link`

     simple-guile: simple-guile.o
             ${CC} simple-guile.o ${LIBS} -o simple-guile

     simple-guile.o: simple-guile.c
             ${CC} -c ${CFLAGS} simple-guile.c

   If you are using the GNU Autoconf package to make your application
more portable, Autoconf will settle many of the details in the Makefile
above automatically, making it much simpler and more portable; we
recommend using Autoconf with Guile.  Guile also provides the
`GUILE_FLAGS' macro for autoconf that performs all necessary checks.
Here is a `configure.in' file for `simple-guile' that uses this macro.
Autoconf can use as this file as template to generate a `configure'
script.  In order for Autoconf to find the `GUILE_FLAGS' macro, you
will need to run `aclocal' first.  This is not really Guile specific,
so you should refer to the Autoconf documentation REFFIXME when in
doubt.
     AC_INIT(simple-guile.c)

     # Find a C compiler.
     AC_PROG_CC

     # Check for Guile
     GUILE_FLAGS

     # Generate a Makefile, based on the results.
     AC_OUTPUT(Makefile)

   Here is a `Makefile.in' template, from which the `configure' script
produces a Makefile customized for the host system:
     # The configure script fills in these values.
     CC=@CC@
     CFLAGS=@GUILE_CFLAGS@
     LIBS=@GUILE_LDFLAGS@

     simple-guile: simple-guile.o
             ${CC} simple-guile.o ${LIBS} -o simple-guile
     simple-guile.o: simple-guile.c
             ${CC} -c ${CFLAGS} simple-guile.c

   The developer should use Autoconf to generate the `configure' script
from the `configure.in' template, and distribute `configure' with the
application.  Here's how a user might go about building the application:

     $ ls
     Makefile.in     configure*      configure.in    simple-guile.c
     $ ./configure
     creating cache ./config.cache
     checking for gcc... (cached) gcc
     checking whether the C compiler (gcc  ) works... yes
     checking whether the C compiler (gcc  ) is a cross-compiler... no
     checking whether we are using GNU C... (cached) yes
     checking whether gcc accepts -g... (cached) yes
     checking for Guile... yes
     creating ./config.status
     creating Makefile
     $ make
     gcc -c -I/usr/local/include simple-guile.c
     gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
     $ ./simple-guile
     guile> (+ 1 2 3)
     6
     guile> (getpwnam "jimb")
     #("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
       "/usr/local/bin/bash")
     guile> (exit)
     $

Writing Extensions for Guile
============================

   The previous sections have briefly explained how to write programs
that make use of an embedded Guile interpreter.  But sometimes, all you
want to do is make new primitive procedures and data types available to
the Scheme programmer.  Writing a new version of `guile' is
inconvenient in this case and it would in fact make the life of the
users of your new features needlessly hard.

   For example, suppose that there is a program `guile-db' that is a
version of Guile with additional features for accessing a database.
People who want to write Scheme programs that use these features would
have to use `guile-db' instead of the usual `guile' program.  Now
suppose that there is also a program `guile-gtk' that extends Guile
with access to the popular Gtk+ toolkit for graphical user interfaces.
People who want to write GUIs in Scheme would have to use `guile-gtk'.
Now, what happens when you want to write a Scheme application that uses
a GUI to let the user access a database?  You would have to write a
_third_ program that incorporates both the database stuff and the GUI
stuff.  This might not be easy (because `guile-gtk' might be a quite
obscure program, say) and taking this example further makes it easy to
see that this approach can not work in practice.

   It would have been much better if both the database features and the
GUI feature had been provided as libraries that can just be linked with
`guile'.  Guile makes it easy to do just this, and we encourage you to
make your extensions to Guile available as libraries whenever possible.

   You write the new primitive procedures and data types in the normal
fashion, and link them into a shared library instead of into a
stand-alone program.  The shared library can then be loaded dynamically
by Guile.

A Sample Guile Extension
------------------------

   This section explains how to make the Bessel functions of the C
library available to Scheme.  First we need to write the appropriate
glue code to convert the arguments and return values of the functions
from Scheme to C and back.  Additionally, we need a function that will
add them to the set of Guile primitives.  Because this is just an
example, we will only implement this for the `j0' function.

   Consider the following file `bessel.c'.

     #include <math.h>
     #include <libguile.h>

     SCM
     j0_wrapper (SCM x)
     {
       return scm_make_real (j0 (scm_num2dbl (x, "j0")));
     }

     void
     init_bessel ()
     {
       scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
     }

   This C source file needs to be compiled into a shared library.  Here
is how to do it on GNU/Linux:

     gcc -shared -o libguile-bessel.so -fPIC bessel.c

   For creating shared libraries portably, we recommend the use of `GNU
Libtool'.

   A shared library can be loaded into a running Guile process with the
function `load-extension'.  In addition to the name of the library to
load, this function also expects the name of function from that library
that will be called to initialize it.  For our example, we are going to
call the function `init_bessel' which will make `j0_wrapper' available
to Scheme programs with the name `j0'.  Note that we do not specify a
filename extension such as `.so' when invoking `load-extension'.  The
right extension for the host platform will be provided automatically.

     (load-extension "libguile-bessel" "init_bessel")
     (j0 2)
     => 0.223890779141236

   For this to work, `load-extension' must be able to find
`libguile-bessel', of course.  It will look in the places that are
usual for your operating system, and it will additionally look into the
directories listed in the `LTDL_LIBRARY_PATH' environment variable.

   To see how these Guile extensions via shared libraries relate to the
module system, see below Intro to Modules and Extensions.

Guile Modules
=============

   Guile has support for dividing a program into "modules".  By using
modules, you can group related code together and manage the composition
of complete programs from largely independent parts.

   (Although the module system implementation is in flux, feel free to
use it anyway.  Guile will provide reasonable backwards compatibility.)

   Details on the module system beyond this introductory material can
be found in Modules.

Intro to Using Existing Modules
-------------------------------

   Guile comes with a lot of useful modules, for example for string
processing or command line parsing.  Additionally, there exist many
Guile modules written by other Guile hackers, but which have to be
installed manually.

   Existing modules have to be placed in places where Guile looks for
them by default or in colon-separated directories in the environment
variable `GUILE_LOAD_PATH'.  When this variable is set, those
directories are searched first, then the the default.  The following
command shows the complete list of directories searched:

     guile -c '(write %load-path) (newline)'

   Suppose you want to use the procedures and variables exported by the
module `(ice-9 popen)', which provides the means for communicating with
other processes over pipes.  Add the following line to your currently
running Guile REPL or the top of your script file.

     (use-modules (ice-9 popen))

   This will load the module and make the procedures exported by
`(ice-9 popen)' automatically available.  The next step could be to
open a pipe to `ls' and read the contents of the current directory, one
line at a time.

     (define p (open-input-pipe "ls -l"))
     (read-line p)
     =>
     "total 30"
     (read-line p)
     =>
     "drwxr-sr-x    2 mgrabmue mgrabmue     1024 Mar 29 19:57 CVS"

Intro to Writing New Modules
----------------------------

   Of course it is possible to write modules yourself.  Using modules
for structuring your programs makes them more readable and lets you
distribute them more easily.  Also, explicitly defining the procedures
and variables which are exported from a module adds documentation to the
source and specifies the interface a module provides.

   In Guile, you can create new modules and switch to existing modules
in order to add bindings to them using the syntactic form
`define-module'.

     (define-module (foo bar))

     (define (frob x) x)

   Will create the module `(foo bar)'.(1) All definitions following
this statement will add bindings to the module `(foo bar)', and these
bindings will not be visible outside of the module.  To make the
bindings accessible to other modules, you have to export them
explicitly using one of the following means:

   * Export them with the `export' form:
          (export frob)

   * Include them into the `define-module' form with the keyword
     `export':
          (define-module (foo bar)
            #:export (frob))

   * Change the definition of `frob' to use `define-public', which is a
     combination of `define' and `export'.
          (define-public (frob x) x)

   After exporting, other modules can access the exported items simply
by using `use-modules' to load the module `(foo bar)'.

   ---------- Footnotes ----------

   (1) It is only convention that the module names in this section have
two elements.  One or more than two elements are perfectly fine, such
as `(foo)' or `(foo bar braz)'

Intro to Modules and Extensions
-------------------------------

   In addition to Scheme code you can also put things that are defined
in C into a module.

   You do this by writing a small Scheme file that defines the module.
That Scheme file in turn invokes `load-extension' to make the features
defined in C available.  This works since all definitions made by
`scm_c_define_gsubr' etc. go into the _current module_ and
`define-module' causes the newly defined module to be current while the
code that follows it is executed.

   Suppose we want to put the Bessel function `j0' from the example
extension into a module called `(math bessel)'.  We would have to write
a Scheme file with this contents

     (define-module (math bessel))

     (export j0)

     (load-extension "libguile-bessel" "init_bessel")

   This file should of course be saved in the right place for
autoloading, for example as `/usr/local/share/guile/math/bessel.scm'.

   When `init_bessel' is called, the new `(math bessel)' module is the
current one.  Thus, the call to `scm_c_define_gsubr' will put the new
definition for `j0' into it, just as we want it.

   The definitions made in the C code are not automatically exported
from a module.  You need to explicitly list the ones you want to export
in `export' statements or with the `:export' option of `define-module'.

   There is also a way to manipulate the module system from C but only
Scheme files can be autoloaded.  Thus, we recommend that you define
your modules in Scheme.

Obtaining and Installing Guile
******************************

   Here is the information you will need to get and install Guile and
extra packages and documentation you might need or find interesting.

The Basic Guile Package
=======================

   Guile can be obtained from the main GNU archive site
<ftp://ftp.gnu.org> or any of its mirrors.  The file will be named
guile-version.tar.gz.  The current version is 1.6.4, so the file you
should grab is:

   <ftp://ftp.gnu.org/pub/gnu/guile-1.6.4.tar.gz>

   To unbundle Guile use the instruction

     zcat guile-1.6.4.tar.gz | tar xvf -

   which will create a directory called `guile-1.6.4' with all the
sources.  You can look at the file `INSTALL' for detailed instructions
on how to build and install Guile, but you should be able to just do

     cd guile-1.6.4
     ./configure
     make
     make install

   This will install the Guile executable `guile', the Guile library
`-lguile' and various associated header files and support libraries. It
will also install the Guile tutorial and reference manual.

   Since this manual frequently refers to the Scheme "standard", also
known as R5RS, or the "Revised^5 Report on the Algorithmic Language
Scheme", we have included the report in the Guile distribution; see
Introduction (r5rs).  This will also be installed in your info
directory.

Packages not shipped with Guile
===============================

   We ship the Guile tutorial and reference manual with the Guile
distribution.  Since the Scheme standard (R5RS) is a stable document, we
ship that too.

   Here are references (usually World Wide Web URLs) to some other
freely redistributable documents and packages which you might find
useful if you are using Guile.

*SCSH*
     the Scheme Shell.  Gary Houston has ported SCSH to Guile.  The
     relevant chapter (see The Scheme shell (scsh)) has references
     to the SCSH web page with all its documentation.

*SLIB*
     a portable Scheme library maintained by Aubrey Jaffer.  SLIB can be
     obtained by ftp from <ftp://prep.ai.mit.edu/pub/gnu/jacal/>.

     The SLIB package should be unpacked somewhere in Guile's load
     path.  It will typically be unpacked in
     `/usr/local/share/guile/site', so that it will be
     `/usr/local/share/guile/site/slib'.

     Guile might have been installed with a different prefix, in which
     case the load path can be checked from inside the interpreter with:

          guile> %load-path
          ("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")

     The relevant chapter (see SLIB) has details on how to use SLIB
     with Guile.

*JACAL*
     a symbolic math package by Aubrey Jaffer.  The latest version of
     Jacal can be obtained from <ftp://prep.ai.mit.edu/pub/gnu/jacal/>,
     and should be unpacked in `/usr/local/share/guile/site/slib' so
     that it will be in `/usr/local/share/guile/site/slib/jacal'.

     The relevant section (see JACAL) has details on how to use
     Jacal.