Preface
*******

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

Layout of this Manual
=====================

The manual is divided into five chapters.

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

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

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

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

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

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.  To clarify: VAL will only be returned when CONDITION is true.

  * 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

     As you can see, this code prints 1 (denoted by -|), and returns hooray (denoted by =>).  Do not confuse the two.

Contributors to this Manual
===========================

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

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

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

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

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

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

The Guile License
=================

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

  * The Guile library (libguile) and supporting files are published under the terms of the GNU Lesser General Public License version 3 or later. See the files COPYING.LESSER and COPYING.

  * The Guile readline module is published under the terms of the GNU General Public License version 3 or later.  See the file COPYING.

  * The manual you're now reading is published under the terms of the GNU Free Documentation License (see GNU Free Documentation License).

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

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

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

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