Improve docs on symbols.

[bpt/guile.git] / doc / sources / old-intro.texi

@node Introduction
@chapter 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
@code{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 @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

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
(@pxref{Modules}), the Unix system programming tools (@pxref{POSIX
system calls and networking} and @pxref{The Scheme shell (scsh)}), an
interface to @emph{libtool} to make it easier to add C libraries as
primitives (@pxref{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 @footnote{R4RS is
the Revised^4 Report on the Algorithmic Language Scheme, the closest
thing to a standard Scheme specification today} Scheme standard
(@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is
not.

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

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

@menu
* Getting started::             
* Guile feature list::          
* What you need to use Guile::  
* Roadmap to the Manual::       
* Motivation for Guile::        
* History of Guile::            
@end menu

@node Getting started
@section 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 (@pxref{Obtaining and
Installing Guile}).


@node Guile feature list
@section Guile feature list

In a reductionist view, Guile could be regarded as:
@itemize @bullet
@item
An R4RS-compliant Scheme interpreter.

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

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

@item
An embeddable version of the same interpreter, called @emph{libguile}.

@item
A portable high level API on top of libguile (the @code{gh_} interface).

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

@table @strong
@item Rx
a regular expression library.

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

@item Tk
an interface to John Ousterhout's Tk toolkit.

@end table

@item
A set of tools for implementing other languages @emph{on top of Scheme},
and an example implementation of a language called @emph{Ctax}.


@end itemize


@node What you need to use Guile
@section What you need to use Guile


@node Roadmap to the Manual
@section Roadmap to the Manual

@node Motivation for Guile
@section Motivation for Guile

@node History of Guile
@section History of Guile

@page
@node Using Guile
@chapter Using Guile

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

@page
@node Invoking Guile
@appendix 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.

@table @samp
@item -h
@itemx --help
Display a helpful message.
@item -v
@item --version
Display the current version.
@item --emacs
To be used for emacs editing support.
@item -s @var{file}
Process @var{file} as a script then quit.  This is a terminating option:
any further command line arguments can be accessed by the script using
the @code{(program-arguments)} procedure.

An executable script can start with the following:

@smallexample
#!/usr/bin/guile -s
!#
@end smallexample

Note the @code{!#} 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 @code{#!}  and
@code{!#} may be used to mark block comments (@pxref{Block
comments and interpreter triggers}).  If the closing @code{!#}
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 @samp{-s} option at the
beginning of the Guile script, so that Guile knows not to behave
in an interactive fashion.

@end table