-@page
-@node What is Guile?
-@chapter 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
-@tex
-Revised$^5$
-@end tex
-@ifnottex
-Revised^5
-@end ifnottex
-Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}),
-providing clean and general data and control structures. Guile goes
-beyond the rather austere language presented in @acronym{R5RS}, extending it with
-a module system, full access to @acronym{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
-then 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, @acronym{GUI}
-toolkit interfaces, and @acronym{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.
-
-
-@page
-@node Whirlwind Tour
-@chapter A Whirlwind Tour
-
-This chapter presents a quick tour of all the ways that Guile can be
-used. There are additional examples in the @file{examples/}
-directory in the Guile source distribution.
-
-@menu
-* Running Guile Interactively::
-* Guile Scripts::
-* Linking Programs With Guile::
-* Writing Extensions for Guile::
-* Guile Modules::
-@end menu
-
-
-@node Running Guile Interactively
-@section 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 @code{$} and
-@code{guile>} prompts:
-
-@example
-$ 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> @kbd{C-d}
-$
-@end example
-
-@c [[When we get a fancier read-eval-print loop, with features for bouncing
-@c around among modules, referring to the value of the last expression,
-@c etc. then this section will get longer.]]
-
-
-@node Guile Scripts
-@section 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:
-
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-
-@menu
-* The Top of a Script File:: How to start a Guile script.
-* Scripting Examples:: Simple Guile scripts, explained.
-@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.
-
-The function @code{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:
-@example
-#!/usr/local/bin/guile -s
-!#
-(write (command-line))
-(newline)
-@end example
-
-If you put that text in a file called @file{foo} in the current
-directory, then you could make it executable and try it out like this:
-@example
-$ chmod a+x foo
-$ ./foo
-("./foo")
-$ ./foo bar baz
-("./foo" "bar" "baz")
-$
-@end example
-
-As another example, here is a simple replacement for the POSIX
-@code{echo} command:
-@example
-#!/usr/local/bin/guile -s
-!#
-(for-each (lambda (s) (display s) (display " "))
- (cdr (command-line)))
-(newline)
-@end example
-
-@deffn {Scheme Procedure} command-line
-@deffnx {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 @samp{-s},
-@samp{-c} or @samp{--} switches, these procedures ignore everything up
-to and including those switches.
-@end deffn
-
-
-@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
-
-
-@node Linking Programs With Guile
-@section 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 @ref{Primitives}.
-
-The header file @code{<libguile.h>} provides declarations for all of
-Guile's functions and constants. You should @code{#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, @code{libguile}.
-
-On most systems, you should not need to tell the compiler and linker
-explicitly where they can find @file{libguile.h} and @file{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 @code{-I} or @code{-L} options to the compiler. Guile
-provides the utility program @code{guile-config} to help you find the
-right values for these options. You would typically run
-@code{guile-config} during the configuration phase of your program and
-use the obtained information in the Makefile.
-
-@menu
-* Guile Initialization Functions:: What to call first.
-* A Sample Guile Main Program:: Sources and makefiles.
-@end menu
-
-
-@node Guile Initialization Functions
-@subsection Guile Initialization Functions
-
-To initialize Guile, you can use one of two functions. The first,
-@code{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,
-@code{scm_init_guile}, does return and can thus be used in more
-situations. However, @code{scm_init_guile} is not as widely available
-as @code{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 @code{scm_init_guile}.
-
-When you can tolerate the limits of @code{scm_boot_guile}, you should
-use it in favor of @code{scm_init_guile} since that will make your
-program more portable.
-
-@deftypefun void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (), void *@var{closure})
-Initialize the Guile Scheme interpreter. Then call @var{main_func},
-passing it @var{closure}, @var{argc}, and @var{argv}. @var{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 @var{main_func} returns, call @code{exit (0)};
-@code{scm_boot_guile} never returns. If you want some other exit value,
-have @var{main_func} call exit itself.
-
-@code{scm_boot_guile} arranges for the Scheme @code{command-line}
-function to return the strings given by @var{argc} and @var{argv}. If
-@var{main_func} modifies @var{argc} or @var{argv}, it should call
-@code{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 @var{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, @code{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, @code{scm_boot_guile} function exits, rather
-than returning, to discourage you from making that mistake.
-
-See @code{scm_init_guile}, below, for a function that can find the real
-base of the stack, but not in a portable way.
-@end deftypefun
-
-@deftypefun void scm_init_guile ()
-Initialize the Guile Scheme interpreter.
-
-In contrast to @code{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 @code{scm_boot_guile} instead.
-
-Note that @code{scm_init_guile} does not inform Guile about the command
-line arguments that should be returned by the Scheme function
-@code{command-line}. You can use @code{scm_set_program_arguments} to do
-this.
-@end deftypefun
-
-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
-@code{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:
-
-@deftypefun void scm_shell (int @var{argc}, char **@var{argv})
-Process command-line arguments in the manner of the @code{guile}
-executable. This includes loading the normal Guile initialization
-files, interacting with the user or running any scripts or expressions
-specified by @code{-s} or @code{-e} options, and then exiting.
-@xref{Invoking Guile}, for more details.
-
-Since this function does not return, you must do all
-application-specific initialization before calling this function.
-@end deftypefun
-
-
-@node A Sample Guile Main Program
-@subsection A Sample Guile Main Program
-
-Here is @file{simple-guile.c}, source code for a @code{main} and an
-@code{inner_main} function that will produce a complete Guile
-interpreter.
-
-@example
-/* 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 */
-@}
-@end example
-
-The @code{main} function calls @code{scm_boot_guile} to initialize
-Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
-ready, it invokes @code{inner_main}, which calls @code{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 @code{guile-config} to learn about the necessary compiler and
-linker flags.
-@example
-# 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
-@end example
-
-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 @code{GUILE_FLAGS}
-macro for autoconf that performs all necessary checks. Here is a
-@file{configure.in} file for @code{simple-guile} that uses this macro.
-Autoconf can use as this file as template to generate a @code{configure}
-script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
-will need to run @code{aclocal} first. This is not really Guile
-specific, so you should refer to the Autoconf documentation REFFIXME
-when in doubt.
-@example
-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)
-@end example
-
-Here is a @code{Makefile.in} template, from which the @code{configure}
-script produces a Makefile customized for the host system:
-@example
-# 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
-@end example
-
-The developer should use Autoconf to generate the @file{configure}
-script from the @file{configure.in} template, and distribute
-@file{configure} with the application. Here's how a user might go about
-building the application:
-
-@example
-$ 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)
-$
-@end example
-
-
-@node Writing Extensions for Guile
-@section 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 @code{guile} is
-inconvenient in this case and it would in fact make the life of the
-users of your new features needlessly hard.
-
-@c [[ the following is probably a bit long-winded ]]
-
-For example, suppose that there is a program @code{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 @code{guile-db} instead of the usual @code{guile} program.
-Now suppose that there is also a program @code{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
-@code{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 @emph{third} program that incorporates both the
-database stuff and the GUI stuff. This might not be easy (because
-@code{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
-@code{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.
-
-@menu
-* A Sample Guile Extension::
-@end menu
-
-
-@node A Sample Guile Extension
-@subsection 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 @code{j0} function.
-
-Consider the following file @file{bessel.c}.
-
-@smallexample
-#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);
-@}
-@end smallexample
-
-This C source file needs to be compiled into a shared library. Here is
-how to do it on GNU/Linux:
-
-@smallexample
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
-@end smallexample
-
-For creating shared libraries portably, we recommend the use of
-@code{GNU Libtool}.
-
-A shared library can be loaded into a running Guile process with the
-function @code{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 @code{init_bessel} which will make
-@code{j0_wrapper} available to Scheme programs with the name
-@code{j0}. Note that we do not specify a filename extension such as
-@file{.so} when invoking @code{load-extension}. The right extension for
-the host platform will be provided automatically.
-
-@smalllisp
-(load-extension "libguile-bessel" "init_bessel")
-(j0 2)
-@result{} 0.223890779141236
-@end smalllisp
-
-For this to work, @code{load-extension} must be able to find
-@file{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 @code{LTDL_LIBRARY_PATH}
-environment variable.
-
-To see how these Guile extensions via shared libraries relate to the
-module system, see below @xref{Intro to Modules and Extensions}.
-
-
-@node Guile Modules
-@section Guile Modules
-
-Guile has support for dividing a program into @dfn{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
-@xref{Modules}.
-
-@menu
-* Intro to Using Guile Modules::
-* Intro to Writing New Modules::
-* Intro to Modules and Extensions::
-@end menu
-
-
-@node Intro to Using Guile Modules
-@subsection 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
-@code{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:
-
-@smallexample
-guile -c '(write %load-path) (newline)'
-@end smallexample
-
-Suppose you want to use the procedures and variables exported by the
-module @code{(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.
-
-@lisp
-(use-modules (ice-9 popen))
-@end lisp
-
-This will load the module and make the procedures exported by
-@code{(ice-9 popen)} automatically available. The next step could be
-to open a pipe to @file{ls} and read the contents of the current
-directory, one line at a time. For the latter, we use the function
-@code{read-line}, which can be found in the module @code{(ice-9
-rdelim)}, so we use that module as well.
-
-@lisp
-(use-modules (ice-9 rdelim))
-(define p (open-input-pipe "ls -l"))
-(read-line p)
-@result{}
-"total 30"
-(read-line p)
-@result{}
-"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
-@end lisp
-
-The macro @code{use-modules} can take any number of modules to use.
-Therefore, we could have written the two @code{use-modules} statements
-in the code above as
-
-@lisp
-(use-modules (ice-9 popen) (ice-9 rdelim))
-@end lisp
-
-@node Intro to Writing New Modules
-@subsection 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
-@code{define-module}.
-
-@lisp
-(define-module (foo bar))
-
-(define (frob x) x)
-@end lisp
-
-Will create the module @code{(foo bar)}.@footnote{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 @code{(foo)} or @code{(foo
-bar braz)}} All definitions following this statement will add bindings
-to the module @code{(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:
-
-@itemize @bullet
-@item
-Export them with the @code{export} form:
-@lisp
-(export frob)
-@end lisp
-
-@item
-Include them into the @code{define-module} form with the keyword
-@code{export}:
-@lisp
-(define-module (foo bar)
- #:export (frob))
-@end lisp
-
-@item
-Change the definition of @code{frob} to use @code{define-public}, which
-is a combination of @code{define} and @code{export}.
-@lisp
-(define-public (frob x) x)
-@end lisp
-@end itemize
-
-After exporting, other modules can access the exported items simply by
-using @code{use-modules} to load the module @code{(foo bar)}.
-
-
-@node Intro to Modules and Extensions
-@subsection 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 @code{load-extension} to make the
-features defined in C available. This works since all definitions
-made by @code{scm_c_define_gsubr} etc. go into the @emph{current
-module} and @code{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 @code{j0} from the example
-extension into a module called @code{(math bessel)}. We would have to
-write a Scheme file with this contents
-
-@smallexample
-(define-module (math bessel))
-
-(export j0)
-
-(load-extension "libguile-bessel" "init_bessel")
-@end smallexample
-
-This file should of course be saved in the right place for
-autoloading, for example as
-@file{/usr/local/share/guile/math/bessel.scm}.
-
-When @code{init_bessel} is called, the new @code{(math bessel)} module
-is the current one. Thus, the call to @code{scm_c_define_gsubr} will
-put the new definition for @code{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
-@code{export} statements or with the @code{:export} option of
-@code{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.
-
-
-@page
-@node Obtaining and Installing Guile
-@chapter 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.
-
-@menu
-* The Basic Guile Package::
-* Packages not shipped with Guile::
-@end menu
-
-
-@node The Basic Guile Package
-@section The Basic Guile Package
-
-Guile can be obtained from the main GNU archive site
-@url{ftp://ftp.gnu.org} or any of its mirrors. The file
-will be named guile-version.tar.gz. The current version is
-@value{VERSION}, so the file you should grab is:
-
-@url{ftp://ftp.gnu.org/pub/gnu/guile-@value{VERSION}.tar.gz}
-
-To unbundle Guile use the instruction
-
-@example
-zcat guile-@value{VERSION}.tar.gz | tar xvf -
-@end example
-
-which will create a directory called @file{guile-@value{VERSION}} with
-all the sources. You can look at the file @file{INSTALL} for detailed
-instructions on how to build and install Guile, but you should be able
-to just do
-
-@example
-cd guile-@value{VERSION}
-./configure
-make
-make install
-@end example
-
-This will install the Guile executable @file{guile}, the Guile library
-@file{-lguile} and various associated header files and support
-libraries. It will also install the Guile tutorial and reference
-manual.
-
-@c [[include instructions for getting R5RS]]
-
-Since this manual frequently refers to the Scheme ``standard'', also
-known as R5RS, or the
-@iftex
-``Revised$^5$ Report on the Algorithmic Language Scheme'',
-@end iftex
-@ifnottex
-``Revised^5 Report on the Algorithmic Language Scheme'',
-@end ifnottex
-we have included the report in the Guile distribution;
-@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
-Language Scheme}.
-This will also be installed in your info directory.
-
-
-@node Packages not shipped with Guile
-@section 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.
-
-@table @strong
-@item SCSH
-the Scheme Shell. Gary Houston has ported SCSH to Guile. The relevant
-chapter (@pxref{The Scheme shell (scsh)}) has references to the SCSH web
-page with all its documentation.
-
-@item SLIB
-a portable Scheme library maintained by Aubrey Jaffer. SLIB can be
-obtained by ftp from @url{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 @file{/usr/local/share/guile/site}, so
-that it will be @file{/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:
-
-@smalllisp
-guile> %load-path
-("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")
-@end smalllisp
-
-The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with
-Guile.
-
-@item JACAL
-a symbolic math package by Aubrey Jaffer. The latest version of Jacal
-can be obtained from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}, and
-should be unpacked in @file{/usr/local/share/guile/site/slib} so that
-it will be in @file{/usr/local/share/guile/site/slib/jacal}.
-
-The relevant section (@pxref{JACAL}) has details on how to use Jacal.
-@end table
-
-
-@page
-@node Reporting Bugs
-@chapter Reporting Bugs
-
-Any problems with the installation should be reported to
-@email{bug-guile@@gnu.org}.
-
-Whenever you have found a bug in Guile you are encouraged to report it
-to the Guile developers, so they can fix it. They may also be able to
-suggest workarounds when it is not possible for you to apply the bug-fix
-or install a new version of Guile yourself.
-
-Before sending in bug reports, please check with the following list that
-you really have found a bug.
-
-@itemize @bullet
-@item
-Whenever documentation and actual behavior differ, you have certainly
-found a bug, either in the documentation or in the program.
-
-@item
-When Guile crashes, it is a bug.
-
-@item
-When Guile hangs or takes forever to complete a task, it is a bug.
-
-@item
-When calculations produce wrong results, it is a bug.
-
-@item
-When Guile signals an error for valid Scheme programs, it is a bug.
-
-@item
-When Guile does not signal an error for invalid Scheme programs, it may
-be a bug, unless this is explicitly documented.
-
-@item
-When some part of the documentation is not clear and does not make sense
-to you even after re-reading the section, it is a bug.
-@end itemize
-
-When you write a bug report, please make sure to include as much of the
-information described below in the report. If you can't figure out some
-of the items, it is not a problem, but the more information we get, the
-more likely we can diagnose and fix the bug.
-
-@itemize @bullet
-@item
-The version number of Guile. Without this, we won't know whether there
-is any point in looking for the bug in the current version of Guile.
-
-You can get the version number by invoking the command
-
-@example
-$ guile --version
-Guile 1.4.1
-Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
-Guile may be distributed under the terms of the GNU General Public License;
-certain other uses are permitted as well. For details, see the file
-`COPYING', which is included in the Guile distribution.
-There is no warranty, to the extent permitted by law.
-@end example
-
-@item
-The type of machine you are using, and the operating system name and
-version number. On GNU systems, you can get it with @file{uname}.
-
-@example
-$ uname -a
-Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
-@end example
-
-@item
-The operands given to the @file{configure} command when Guile was
-installed. It's often useful to augment this with the output of the
-command @code{guile-config info}.
-
-@item
-A complete list of any modifications you have made to the Guile source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Guile. But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes. A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
-@item
-Details of any other deviations from the standard procedure for
-installing Guile.
-
-@item
-The complete text of any source files needed to reproduce the bug.
-
-If you can tell us a way to cause the problem without loading any source
-files, please do so. This makes it much easier to debug. If you do
-need files, make sure you arrange for us to see their exact contents.
-
-@item
-The precise Guile invocation command line we need to type to reproduce
-the bug.
-
-@item
-A description of what behavior you observe that you believe is
-incorrect. For example, "The Guile process gets a fatal signal," or,
-"The resulting output is as follows, which I think is wrong."
-
-Of course, if the bug is that Guile gets a fatal signal, then one can't
-miss it. But if the bug is incorrect results, the maintainer might fail
-to notice what is wrong. Why leave it to chance?
-
-If the manifestation of the bug is a Guile error message, it is
-important to report the precise text of the error message, and a
-backtrace showing how the Scheme program arrived at the error.
-
-This can be done using the procedure @code{backtrace} in the REPL.
-
-@item
-Check whether any programs you have loaded into Guile, including your
-@file{.guile} file, set any variables that may affect the functioning of
-Guile. Also, see whether the problem happens in a freshly started Guile
-without loading your @file{.guile} file (start Guile with the @code{-q}
-switch to prevent loading the init file). If the problem does
-@emph{not} occur then, you must report the precise contents of any
-programs that you must load into Guile in order to cause the problem to
-occur.
-
-@item
-If the problem does depend on an init file or other Scheme programs that
-are not part of the standard Guile distribution, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first. After they verify that they are using Guile in a way
-that is supposed to work, they should report the bug.
-
-@item
-If you wish to mention something in the Guile source, show the line of
-code with a few lines of context. Don't just give a line number.
-
-The line numbers in the development sources might not match those in your
-sources. It would take extra work for the maintainers to determine what
-code is in your version at a given line number, and we could not be
-certain.
-
-@item
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy. You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Guile distribution. To run Guile under GDB, you should
-switch to the @file{libguile} subdirectory in which Guile was compiled, then
-do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-For example, many people send just a backtrace, but that is not very
-useful by itself. A simple backtrace with arguments often conveys
-little about what is happening inside Guile, because most of the
-arguments listed in the backtrace are pointers to Scheme objects. The
-numeric values of these pointers have no significance whatever; all that
-matters is the contents of the objects they point to (and most of the
-contents are themselves pointers).
-@end itemize
-
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2010, 2011, 2013
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Introduction
+@chapter Introduction
+
+Guile is an implementation of the Scheme programming language. Scheme
+(@url{http://schemers.org/}) is an elegant and conceptually simple
+dialect of Lisp, originated by Guy Steele and Gerald Sussman, and since
+evolved by the series of reports known as RnRS (the
+@tex
+Revised$^n$
+@end tex
+@ifnottex
+Revised^n
+@end ifnottex
+Reports on Scheme).
+
+Unlike, for example, Python or Perl, Scheme has no benevolent
+dictator. There are many Scheme implementations, with different
+characteristics and with communities and academic activities around
+them, and the language develops as a result of the interplay between
+these. Guile's particular characteristics are that
+
+@itemize
+@item
+it is easy to combine with other code written in C
+@item
+it has a historical and continuing connection with the GNU Project
+@item
+it emphasizes interactive and incremental programming
+@item
+it actually supports several languages, not just Scheme.
+@end itemize
+
+@noindent
+The next few sections explain what we mean by these points. The sections after
+that cover how you can obtain and install Guile, and the typographical
+conventions that we use in this manual.
+
+@menu
+* Guile and Scheme::
+* Combining with C::
+* Guile and the GNU Project::
+* Interactive Programming::
+* Supporting Multiple Languages::
+* Obtaining and Installing Guile::
+* Organisation of this Manual::
+* Typographical Conventions::
+@end menu
+
+@node Guile and Scheme
+@section Guile and Scheme
+
+Guile implements Scheme as described in the
+@tex
+Revised$^5$
+@end tex
+@ifnottex
+Revised^5
+@end ifnottex
+Report on the Algorithmic Language Scheme (usually known as
+@acronym{R5RS}), providing clean and general data and control
+structures. Guile goes beyond the rather austere language presented
+in @acronym{R5RS}, extending it with a module system, full access to
+@acronym{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.
+
+The Scheme community has recently agreed and published R6RS, the
+latest installment in the RnRS series. R6RS significantly expands the
+core Scheme language, and standardises many non-core functions that
+implementations---including Guile---have previously done in
+different ways. Guile has been updated to incorporate some of the
+features of R6RS, and to adjust some existing features to conform to
+the R6RS specification, but it is by no means a complete R6RS
+implementation. @xref{R6RS Support}.
+
+Between R5RS and R6RS, the SRFI process (@url{http://srfi.schemers.org/})
+standardised interfaces for many practical needs, such as multithreaded
+programming and multidimensional arrays. Guile supports many SRFIs, as
+documented in detail in @ref{SRFI Support}.
+
+In summary, so far as relationship to the Scheme standards is
+concerned, Guile is an R5RS implementation with many extensions, some
+of which conform to SRFIs or to the relevant parts of R6RS.
+
+@node Combining with C
+@section Combining with C Code
+
+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. Guile also provides an object
+library, @dfn{libguile}, that allows other applications to easily incorporate a
+complete Scheme interpreter. An application can then 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.
+
+This kind of combination is helped by four aspects of Guile's design
+and history. First is that Guile has always been targeted as an
+extension language. Hence its C API has always been of great
+importance, and has been developed accordingly. Second and third are
+rather technical points---that Guile uses conservative garbage
+collection, and that it implements the Scheme concept of continuations
+by copying and reinstating the C stack---but whose practical
+consequence is that most existing C code can be glued into Guile as
+is, without needing modifications to cope with strange Scheme
+execution flows. Last is the module system, which helps extensions to
+coexist without stepping on each others' toes.
+
+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, @acronym{GUI}
+toolkit interfaces, and @acronym{HTTP} client functions, among others.
+
+@node Guile and the GNU Project
+@section Guile and the GNU Project
+
+Guile was conceived by the GNU Project following the fantastic success
+of Emacs Lisp as an extension language within Emacs. Just as Emacs
+Lisp allowed complete and unanticipated applications to be written
+within the Emacs environment, the idea was that Guile should do the
+same for other GNU Project applications. This remains true today.
+
+The idea of extensibility is closely related to the GNU project's
+primary goal, that of promoting software freedom. Software freedom
+means that people receiving a software package can modify or enhance
+it to their own desires, including in ways that may not have occurred
+at all to the software's original developers. For programs written in
+a compiled language like C, this freedom covers modifying and
+rebuilding the C code; but if the program also provides an extension
+language, that is usually a much friendlier and lower-barrier-of-entry
+way for the user to start making their own changes.
+
+Guile is now used by GNU project applications such as AutoGen, Lilypond, Denemo,
+Mailutils, TeXmacs and Gnucash, and we hope that there will be many more in
+future.
+
+@node Interactive Programming
+@section Interactive Programming
+
+Non-free software has no interest in its users being able to see how it works.
+They are supposed to just accept it, or to report problems and hope that the
+source code owners will choose to work on them.
+
+Free software aims to work reliably just as much as non-free software does, but
+it should also empower its users by making its workings available. This is
+useful for many reasons, including education, auditing and enhancements, as well
+as for debugging problems.
+
+The ideal free software system achieves this by making it easy for interested
+users to see the source code for a feature that they are using, and to follow
+through that source code step-by-step, as it runs. In Emacs, good examples of
+this are the source code hyperlinks in the help system, and @code{edebug}.
+Then, for bonus points and maximising the ability for the user to experiment
+quickly with code changes, the system should allow parts of the source code to
+be modified and reloaded into the running program, to take immediate effect.
+
+Guile is designed for this kind of interactive programming, and this
+distinguishes it from many Scheme implementations that instead prioritise
+running a fixed Scheme program as fast as possible---because there are
+tradeoffs between performance and the ability to modify parts of an already
+running program. There are faster Schemes than Guile, but Guile is a GNU
+project and so prioritises the GNU vision of programming freedom and
+experimentation.
+
+@node Supporting Multiple Languages
+@section Supporting Multiple Languages
+
+Since the 2.0 release, Guile's architecture supports compiling any language to
+its core virtual machine bytecode, and Scheme is just one of the supported
+languages. Other supported languages are Emacs Lisp, ECMAScript (commonly known
+as Javascript) and Brainfuck, and work is under discussion for Lua, Ruby and
+Python.
+
+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.
+
+@node Obtaining and Installing Guile
+@section Obtaining and Installing Guile
+
+Guile can be obtained from the main GNU archive site
+@url{ftp://ftp.gnu.org} or any of its mirrors. The file will be named
+guile-@var{version}.tar.gz. The current version is @value{VERSION}, so the
+file you should grab is:
+
+@url{ftp://ftp.gnu.org/gnu/guile/guile-@value{VERSION}.tar.gz}
+
+To unbundle Guile use the instruction
+
+@example
+zcat guile-@value{VERSION}.tar.gz | tar xvf -
+@end example
+
+@noindent
+which will create a directory called @file{guile-@value{VERSION}} with
+all the sources. You can look at the file @file{INSTALL} for detailed
+instructions on how to build and install Guile, but you should be able
+to just do
+
+@example
+cd guile-@value{VERSION}
+./configure
+make
+make install
+@end example
+
+This will install the Guile executable @file{guile}, the Guile library
+@file{libguile} and various associated header files and support libraries. It
+will also install the Guile reference manual.
+
+@c [[include instructions for getting R5RS]]
+
+Since this manual frequently refers to the Scheme ``standard'', also
+known as R5RS, or the
+@tex
+``Revised$^5$ Report on the Algorithmic Language Scheme'',
+@end tex
+@ifnottex
+``Revised^5 Report on the Algorithmic Language Scheme'',
+@end ifnottex
+we have included the report in the Guile distribution; see
+@ref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
+Language Scheme}.
+This will also be installed in your info directory.
+
+@node Organisation of this Manual
+@section Organisation of this Manual
+
+The rest of this manual is organised into the following chapters.
+
+@table @strong
+@item Chapter 2: Hello Guile!
+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.
+
+@item Chapter 3: Hello Scheme!
+For readers new to Scheme, this chapter provides an introduction to the basic
+ideas of the Scheme language. This material would apply to any Scheme
+implementation and so does not make reference to anything Guile-specific.
+
+@item Chapter 4: Programming in Scheme
+Provides an overview of 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 introduces the extensions that Guile offers beyond standard
+Scheme.
+
+@item Chapter 5: Programming in C
+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 6: 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 7: Guile Modules
+Describes some important modules, distributed as part of the Guile
+distribution, that extend the functionality provided by the Guile
+Scheme core.
+
+@item Chapter 8: GOOPS
+Describes GOOPS, an object oriented extension to Guile that provides
+classes, multiple inheritance and generic functions.
+
+@end table
+
+@node Typographical Conventions
+@section Typographical Conventions
+
+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{}}).
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / blobdiff