Doc updates, including contribution from Ian Sheldon.

[bpt/guile.git] / doc / ref / guile.texi

\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guile.info
@settitle Guile Reference Manual
@set guile
@set MANUAL_EDITION 1.1
@c %**end of header

@c Notes
@c
@c We no longer use the category "primitive" to distinguish C-defined
@c Scheme procedures from those defined in Scheme.  Instead, the
@c reference manual now includes a C declaration as well as a Scheme
@c declaration for each procedure that is available in both Scheme and
@c C.
@c
@c When adding a new reference entry to the Guile manual, please
@c document it with @deffn using one of the following categories:
@c
@c   {Scheme Procedure}
@c   {Scheme Syntax}
@c   {C Function}
@c   {C Macro}
@c
@c If the entry is for a new primitive, it should have both a @deffn
@c {Scheme Procedure} line and a @deffnx {C Function} line; see the
@c manual source for plenty of existing examples of this.
@c
@c For {C Function} entries where the return type and all parameter
@c types are SCM, we omit the SCMs.  This is easier to read and also
@c gets round the problem that Texinfo doesn't allow a @deftypefnx
@c inside a @deffn.
@c
@c For a list of Guile primitives that are not yet incorporated into the
@c reference manual, see the file `new-docstrings.texi', which holds all
@c the docstrings snarfed from the libguile C sources for primitives
@c that are not in the reference manual.  If you have worked with some
@c of these concepts, implemented them, or just happen to know what they
@c do, please write up a little explanation -- it would be a big help.
@c Alternatively, if you know of any reason why some of these should
@c *not* go in the manual, please let the mailing list
@c <guile-devel@gnu.org> know.

@c Define indices that are used in the Guile Scheme part of the
@c reference manual to group stuff according to whether it is R5RS or a
@c Guile extension.
@defcodeindex rn

@include version.texi

@c vnew - For (some) new items, indicates the Guile version in which
@c item first appeared.  In future, this could be made to expand to
@c something like a "New in Guile 45!" banner.
@macro vnew{VERSION}
@end macro

@c @iftex
@c @cropmarks
@c @end iftex

@dircategory The Algorithmic Language Scheme
@direntry
* Guile Reference: (guile).     The Guile reference manual.
@end direntry

@setchapternewpage off

@ifinfo
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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

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.
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle Edition @value{MANUAL_EDITION}, for use with Guile @value{VERSION}
@subtitle $Id: guile.texi,v 1.19 2002-09-25 00:06:38 ossau Exp $

@c AUTHORS

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

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

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

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

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

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

@author Mark Galassi
@author Cygnus Solution and Los Alamos National Laboratory
@author @email{rosalia@@cygnus.com}
@author
@author Jim Blandy
@author Free Software Foundation and MIT AI Lab
@author @email{jimb@@red-bean.com}
@author
@author Gary Houston
@author @email{ghouston@@arglist.com}
@author
@author Tim Pierce
@author @email{twp@@skepsis.com}
@author
@author Neil Jerram
@author @email{neil@@ossau.uklinux.net}
@author
@author Martin Grabmueller
@author @email{mgrabmue@@cs.tu-berlin.de}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@vskip 0pt plus 1filll
Copyright @copyright{} 1996 Free Software Foundation

Copyright @copyright{} 1997 Free Software Foundation

Copyright @copyright{} 2000 Free Software Foundation

Copyright @copyright{} 2001 Free Software Foundation

Copyright @copyright{} 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 Free Software Foundation.
@end titlepage

@c @smallbook
@finalout
@headings double

@c Where to find Guile examples.
@set example-dir doc/examples

@ifnottex
@node Top, Guile License, (dir), (dir)
@top 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 @value{MANUAL_EDITION} of the reference
manual, corresponding to Guile version @value{VERSION}.
@end ifnottex

@menu
Preface

* Guile License::               Conditions for copying and using Guile.
* Manual Layout::               How to read the rest of this manual.
* Manual Conventions::          Conventional terminology.

Part I: Introduction to Guile

* What is Guile?::              And what does it do?
* Whirlwind Tour::              An introductory whirlwind tour.
* Obtaining and Installing Guile::
* Reporting Bugs::              Reporting bugs in Guile or this manual.

Part II: Writing and Running Guile Scheme

* Running Intro::               Introduction to this part.
* Guile Scheme::                Guile's implementation of Scheme.
* Guile Scripting::             How to write Guile scripts.
* Command Line Handling::       Command line options and arguments.
* Debugging Features::          Features for debugging errors.
* Autoconf Support::            Guile-specific configure.in macros.
* Miscellaneous Tools::         Snarfing, linting, etc.
* Basic Ideas::                 Basic ideas in Scheme.
* Further Reading::             Where to find out more about Scheme.

Part III: Guile as an Extension Language

* Programming Intro::           Introduction to this part.
* Libguile Intro::              Using Guile as an extension language.
* Programming Overview::        An overview of Guile programming.
* Data Representation::         Data representation in Guile.
* GH::                          The deprecated GH interface.

Part IV: Guile API Reference

* Reference Intro::             Introduction to the Guile API reference.
* API Overview::                Overview of the Guile API.
* Simple Data Types::           Numbers, strings, booleans and so on.
* Compound Data Types::         Data types for holding other data.
* Procedures and Macros::       Procedures and macros.
* Utility Functions::           General utility functions.
* Binding Constructs::          Definitions and variable bindings.
* Control Mechanisms::          Controlling the flow of program execution.
* Input and Output::            Ports, reading and writing.
* Read/Load/Eval::              Reading and evaluating Scheme code.
* Memory Management::           Memory management and garbage collection.
* Objects::                     Low level object orientation support.
* Modules::                     Designing reusable code libraries.
* Scheduling::                  Threads, mutexes, asyncs and dynamic roots.
* Options and Config::          Configuration, features and runtime options.
* Translation::                 Support for translating other languages.
* Debugging::                   Internal debugging interface.
* Deprecated::                  Features that are planned to disappear.

Part V: Guile Modules

* SLIB::                        Using the SLIB Scheme library.
* POSIX::                       POSIX system calls and networking.
* SRFI Support::                Support for various SRFIs.
* Readline Support::            Module for using the readline library.
* Value History::               Maintaining a value history in the REPL.
* Pretty Printing::             Nicely formatting Scheme objects for output.
* Formatted Output::            The @code{format} procedure.
* Rx Regexps::                  The Rx regular expression library.
* Expect::                      Controlling interactive programs with Guile.
* The Scheme shell (scsh)::     Using scsh interfaces in Guile.

Indices

* Concept Index::
* Procedure Index::
* Variable Index::
* Type Index::
* R5RS Index::

@end menu

@include preface.texi

@iftex
@page
@unnumbered{Part I: Introduction to Guile}
@end iftex

@include intro.texi

@page
@node Running Intro
@unnumbered Part II: Writing and Running Guile Scheme

Guile's core language is Scheme, and an awful lot can be achieved simply
by using Guile to write and run Scheme programs.  In this part of the
manual, we explain how to use Guile in this mode, and describe the tools
that Guile provides to help you with script writing, debugging and
packaging your programs for distribution.

For readers who are not yet familiar with the Scheme language, this part
includes a chapter that presents the basic concepts of the language, and
gives references to freely available Scheme tutorial material on the
web.

For detailed reference information on the variables, functions etc. that
make up Guile's application programming interface (API), please refer to
Part IV (@pxref{Reference Intro,,Part IV --- Guile API Reference}).

@include scheme-intro.texi
@include scripts.texi
@include script-getopt.texi
@include debugging.texi
@include autoconf.texi
@include tools.texi
@include scheme-ideas.texi
@include scheme-reading.texi

@page
@node Programming Intro
@unnumbered Part III: Guile as an Extension Language

In this part of the manual, we aim to present a wide ranging picture of
what it means to use Guile as an application extension language, to
provide guidance, practical guidelines and tips for @emph{how} to
program in Guile, and to document the tools that are available to help
you with your programming.  For detailed reference information on the
variables, functions etc. that make up Guile's application programming
interface (API), please refer to Part IV (@pxref{Reference Intro,,Part
IV --- Guile API Reference}).

@include extend.texi
@include program.texi
@include data-rep.texi
@include gh.texi

@page
@node Reference Intro
@unnumbered Part IV: Guile API Reference

Guile provides an application programming interface (@dfn{API}) to
developers in two core languages: Scheme and C.  This part of the manual
contains reference documentation for all of the functionality that is
available through both Scheme and C interfaces.

@include scm.texi
@include scheme-data.texi
@include scheme-compound.texi
@include scheme-procedures.texi
@include scheme-utility.texi
@include scheme-binding.texi
@include scheme-control.texi
@include scheme-io.texi
@include scheme-evaluation.texi
@include scheme-memory.texi
@include scheme-modules.texi
@include scheme-scheduling.texi
@c object orientation support here
@include scheme-options.texi
@include scheme-translation.texi
@include scheme-debug.texi
@include deprecated.texi

@iftex
@page
@unnumbered{Part V: Guile Modules}
@end iftex

@include slib.texi
@include posix.texi
@include srfi-modules.texi
@include repl-modules.texi
@include misc-modules.texi
@include expect.texi
@include scsh.texi

@iftex
@page
@unnumbered{Indices}
@end iftex

@include indices.texi
@include scheme-indices.texi

@contents

@bye