Introduction
************

Guile is an interpreter for Scheme, a clean, economical programming language in the Lisp family.  You can invoke Guile from the shell to evaluate Scheme expressions interactively, or use it as an interpreter for script files.  However, Guile is also packaged as a library, to be embedded as an extension language into other applications.  The application can supplement the base language with special-purpose functions and datatypes, allowing the user to customize and extend it by writing Scheme code.

In its simplest form, Guile is an ordinary interpreter.  The guile program can read and evaluate Scheme expressions entered 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 can also interpret script files.  For example, here is a Guile script containing a script which displays the

application can supplement the base language with its own functions, datatypes and syntax, allowing the user to extend and

Guile interpret

.  An application the Guile interpreter to allow

, allowing applications to incorporate the Scheme interpreter for customization

[[interactive]] [[script interpreter]] [[embedded]]

[[other languages]] The concept of an extension language library does not originate with Guile.  However, Guile is the first to offer users a choice of languages to program in.

Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future.

Scheme is powerful enough that other languages can be conveniently translated into it,

However, unlike other extension packages, Guile gives users a choice of languages to program in.  Guile can

In this sense, Guile resembles the Tcl and Python packages, providing both an ordinary interpreter and an extension language library. However, unlike those packages, Guile supports more than one programming language.

; users can write Scheme code to control and customize applications which incorporate Guile

, adding their own functions, datatypes, and syntax, to allow the user to programm

link it into your own programs to make them

Guile is a library containing an interpreter for Scheme, a complete but economical programming language, which the developer can customize to suit the application at hand by adding new functions, data types, and control structures.  These may be implemented in C, and then ``exported'' for use by the interpreted code.  Because Guile already provides a full-featured interpreter, the developer need not neglect the language's design in order to concentrate on code relevant to the task. In this way, Guile provides a framework for the construction of domain-specific languages.

Guile provides first-class functions, a rich set of data types, exception handling, a module system, and a powerful macro facility. Guile also supports dynamic linking and direct access to Unix system calls.  Releases in the near future will support a source-level debugger and bindings for the Tk user interface toolkit.

Guile is a framework for writing applications controlled by specialized languages.  In its simplest form, Guile is an interpreter for Scheme, a clean, economical programming language in the Lisp family.  However, Guile is packaged as a library, allowing applications to link against it and use Scheme as their extension language.  The application can add primitive functions to the language, implement new data types, and even adjust the language's syntax.

[the introduction is probably not what Jim has in mind; I just took the one I had in earlier, since the file had the same name intro.texi]

Guile is an implementation of the Scheme programming language, but, like other modern implementations of Scheme, it adds many features that the community of Scheme programmers considers necessary for an ``industrial strength'' language.

Examples of extensions to Scheme are the module system (see Modules), the Unix system programming tools (see POSIX system calls and networking and see The Scheme shell (scsh)), an interface to libtool to make it easier to add C libraries as primitives (see Linking Guile with your code), and (FIXME add more).

On top of these extensions, which many other Scheme implementations provide, Guile also offers the possibility of writing routines in other languages and running them simultaneously with Scheme.  The desire to implement other languages (in particular Emacs Lisp) on top of Scheme is responsible for Guile's only deviation from the R4RS  (R4RS is the Revised^4 Report on the Algorithmic Language Scheme, the closest thing to a standard Scheme specification today) Scheme standard (r4rs): Guile is case sensitive, whereas ``standard'' Scheme is not.

But even more fundamentally, Guile is meant to be an embeddable Scheme interpreter.  This means that a lot of work has gone into packaging the interpreter as a C library (see A Portable C to Scheme Interface and see Scheme data representation).

This reference manual is mainly driven by the need to document all the features that go beyond standard Scheme.

Getting started
===============

We assume that you know how to program in Scheme, although we do not assume advanced knowledge.  If you don't know Scheme, there are many good books on Scheme at all levels, and the Guile Tutorial might give you a good enough feel for the language.  We also assume that you know how to program in C, since there will be many examples of how to program in C using Guile as a library.

Many diverse topics from the world of Unix hacking will be covered here, such as shared libraries, socket programming, garbage collection, and so forth.  If at any time you feel you don't have enough background on a given topic, just go up a level or two in the manual, and you will find that the chapter begins with a few paragraphs that introduce the topic. If you are still lost, read through the Guile tutorial and then come back to this reference manual.

To run the core Guile interpreter and extension library you need no more than a basically configured GNU/Unix system and the Guile sources.  You should download and install the Guile sources (see Obtaining and Installing Guile).

Guile feature list
==================

In a reductionist view, Guile could be regarded as:

  * An R4RS-compliant Scheme interpreter.

  * Some Scheme features that go beyond the R4RS standard, notably a module system, exception handling primitives and an interface to Aubrey Jaffer's SLIB.

  * A symbolic debugger for Scheme, and gdb extensions to facilitate debugging libguile programs.

  * An embeddable version of the same interpreter, called libguile.

  * A portable high level API on top of libguile (the gh_ interface).

  * A collection of bundled C libraries with a Guile API.  As we write, this list includes:

     Rx
          a regular expression library.

     Unix
          a low-level interface to the POSIX system calls, socket library and other Unix system services.

     Tk
          an interface to John Ousterhout's Tk toolkit.

  * A set of tools for implementing other languages on top of Scheme, and an example implementation of a language called Ctax.

What you need to use Guile
==========================

Roadmap to the Manual
=====================

Motivation for Guile
====================

History of Guile
================

Using Guile
***********

[I think that this might go in the appendix in Jim's view of the manual]

Invoking Guile
**************

--- mentions read-eval-print loops --- both the SCSH and GAWK manuals relegate invocation details to an appendix.  We can give examples in the introduction.

-h
--help
     Display a helpful message.

-v

--version
     Display the current version.

--emacs
     To be used for emacs editing support.

-s FILE
     Process FILE as a script then quit.  This is a terminating option: any further command line arguments can be accessed by the script using the (program-arguments) procedure.

     An executable script can start with the following:

          #!/usr/bin/guile -s
          !#

     Note the !# token on the second line.  It is very important to include this token when writing Guile scripts.  Guile and SCSH, the Scheme shell, share the convention that #!  and !# may be used to mark block comments (see Block comments and interpreter triggers).  If the closing !# token is not included, then Guile will consider the block comment to be unclosed, and the script will probably not compile correctly.

     It is also important to include the -s option at the beginning of the Guile script, so that Guile knows not to behave in an interactive fashion.