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

@c Jim's notes:

@c Remember to use "subr" whereever appropriate.
@c Actually, use "primitive", not "subr."  Why coin a new term?
@c FIXME: gotta change existing "subr" uses to "Primitive".
@c In my text for the Guile snarfer, I've used the term "subr" to denote
@c a C function made available to the Scheme world as a function.  This
@c terminology is weird, but consistent with the function names and also
@c with Emacs Lisp, which I assume takes Maclisp's lead.

@c Tim's notes:

@c When adding a new function to the Guile manual, please document
@c it with @deffn as one of `primitive', `procedure', or `syntax'.
@c
@c The following Guile primitives are not documented.  We have a lot
@c of work to do.
@c
@c   arbiters.c: make-arbiter, try-arbiter, release-arbiter
@c   async.c: async, async-mark, system-async, system-async-mark,
@c      run-asyncs, noop, set-tick-rate, set-switch-rate,
@c      unmask-signals, mask-signals
@c   backtrace.c: backtrace, display-error, display-application,
@c      display-backtrace
@c   chars.c: char-is-both?
@c   debug.c: single-step, memoized?, unmemoize, memoized-environment,
@c      procedure-name, procedure-source, procedure-environment,
@c      local-eval, debug-object?, debug-hang
@c   dynl.c: c-registered-modules, c-clear-registered-modules,
@c      dynamic-link, dynamic-object?, dynamic-unlink, dynamic-func,
@c      dynamic-call, dynamic-args-call
@c   eval.c: procedure->syntax, procedure->macro, procedure->memoizing-macro,
@c      macro-name, macro-transformer
@c   fluids.c: make-fluid, fluid?, fluid-ref, fluid-set, with-fluids*
@c   gc.c: map-free-list, unhash-name
@c   kw.c: make-keyword-from-dash-symbol
@c   net_db.c: sethost, setnet, setproto, setserv
@c   print.c: current-pstate
@c   procs.c: make-cclo, closure?, thunk?
@c   read.c: read-hash-extend
@c   readline.c: readline, add-history
@c   srcprop.c: source-properties, set-source-properties!,
@c      source-property, set-source-property!
@c   stacks.c: make-stack, stack-ref, stack-length,
@c      frame?, last-stack-frame, frame-number, frame-source,
@c      frame-procedure, frame-arguments, frame-previous, frame-next,
@c      frame-real?, frame-procedure?, frame-evaluating-args?,
@c      frame-overflow
@c   struct.c: struct-vtable-tag
@c   symbols.c: builtin-weak-bindings
@c   tag.c: tag
@c   threads.c: single-active-thread?, yield, call-with-new-thread,
@c      make-condition-variable, wait-condition-variable,
@c      signal-condition-variable
@c   throw.c: lazy-catch, vector-set-length!
@c   unif.c: uniform-vector-ref, uniform-array-set1!
@c   variable.c: make-variable, make-undefined-variable, variable?,
@c      variable-ref, variable-set!, builtin-variable, variable-bound?
@c   weaks.c: make-weak-vector, weak-vector, list->weak-vector,
@c      weak-vector? make-weak-key-hash-table,
@c      make-weak-value-hash-table, make-doubly-weak-hash-table,
@c      weak-key-hash-table?, weak-value-hash-table?,
@c      doubly-weak-hash-table?
@c
@c If you have worked with some of these concepts, implemented them,
@c or just happen to know what they do, please write up a little
@c explanation -- it would be a big help.  Alternatively, if you
@c know of a great reason why some of these should *not* go in the
@c manual, please let me know.
@c
@c The following functions are currently left undocumented for various reasons.
@c   * should be documented in a section on debugging or Guile internals:
@c       ports.c: pt-size, pt-member
@c       eval.c: apply:nconc2last
@c   * trivial underlying implementations of R4RS functions:
@c       numbers.c: $asinh, $acosh, $atanh, $sqrt, $abs, $exp, $log, $sin,
@c              $cos, $tan, $asin, $acos, $atan, $sinh, $cosh, $tanh, $expt,
@c              $atan2
@c
@c Thanks. -twp

@include version.texi

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

@dircategory The Algorithmic Language Scheme
@direntry
* guile-ref: (guile-ref).  The Guile Reference Manual.
@end direntry

@setchapternewpage off

@ifinfo
Guile Reference Manual
Copyright (C) 1996 Free Software Foundation @*
Copyright (C) 1997 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 $Id: guile-ref.texi,v 1.25 2000/05/03 22:50:24 mvo Exp $
@subtitle For use with Guile @value{VERSION}
@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@@actrix.gen.nz}
@author
@author Tim Pierce
@author @email{twp@@skepsis.com}
@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

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

@ifinfo
@node Top, Introduction, (dir), (dir)
@top The Guile Reference Manual
@end ifinfo

@menu
Part I: Preliminaries

* Introduction::
* The Guile License::
* Running Guile Interactively::
* Guile Scripts::
* Linking Programs With Guile::
* Writing Guile Modules::

Part II: Scheme Extensions

Guile provides many features and extensions not present in
standard Scheme: a module system, threads, a regular expression
interface, and so on.  Some other Scheme implementations provide
these and similar features: we have endeavored to maintain
compatibility with many of these systems.

* Extensions to Scheme::        Guile supports many features not in R4RS.
* SLIB::                        Using the SLIB Scheme library.
* Evaluation::                  Running and evaluating code on the fly.
* Lists::                       Special list functions supported by Guile.
* Data Structures::		Records, hash tables, etc.
* Strings::                     Special things about strings.
* Characters::			New character names.
* Property Lists::              Managing metainformation about Scheme objects.
* Ports::                       I/O in Scheme.
* Bitwise Operations::          Logical AND, OR, NOT, and so on.
* Regular Expressions::         Pattern matching and substitution.
* Keywords::                    Self-quoting, customizable display keywords.
* Exceptions::                  Signalling and handling fatal errors.
* Modules::                     Designing reusable code libraries.
* Module Internals::            [FIXME: I think this should be a subnode
                                       of Modules. -twp]
* Dynamic Linking from Marius::
* Dynamic Wind::
* Threads and Dynamic Roots::
* Reflection::
* Weak References::
* Garbage Collection::
* Configuration Data::		Version info, library directories, etc.
* Internal Debugging Interface::

Part III: Unix Programming

Guile may be used as a system programming language (for writing daemons,
system tools, database clients or network interfaces).  Guile's ``POSIX
interface'' -- the code that permits you to use Unix system and library
calls -- is described below.

* Conventions::                 Conventions employed by the POSIX interface.
* Ports and File Descriptors::	Scheme ``ports'' and Unix file descriptors
				  have different representations.
* File System::			stat, chown, chmod, etc.
* User Information::		Retrieving a user's GECOS (/etc/passwd) entry.
* Time::			gettimeofday, localtime, strftime, etc.
* Processes::			getuid, getpid, etc.
* Signals::                     sigaction, kill, pause, alarm, etc.
* Terminals and Ptys::		ttyname, tcsetpgrp, etc.
* Pipes::			Communicating data between processes.
* Networking::			gethostbyaddr, getnetent, socket, bind, listen.
* System Identification::	`uname' and getting info about this machine.
* Locales::                     setlocale, etc.
* Expect::			Controlling interactive programs with Guile.
* The Scheme shell (scsh)::
	The SCSH compatibility module has been made an
	add-on, so maybe it shouldn't be documented here
	(though it is nice to have a link from here to the
	Guile-scsh manual, if one exists).
* Tcl/Tk Interface::

Part IV: Guile Extension Language

All of the functions that make up the Guile interpreter can be found in
the `libguile' library.  You may link other programs with this library
and thereby use Scheme as an extension language for those programs.
This section of the manual describes how to do that.

Using Scheme with C --- a Portable Interface

* A Portable C to Scheme Interface::
* gh preliminaries::
* Data types and constants defined by gh::
* Starting and controlling the interpreter::
* Error messages::
* Executing Scheme code::
* Defining new Scheme procedures in C::
* Converting data between C and Scheme::
* Type predicates::
* Equality predicates::
* Memory allocation and garbage collection::
* Calling Scheme procedures from C::
* Mixing gh and scm APIs::

Using Scheme with C --- Guile's Low-Level Interface

* Scheme data representation::
* Relationship between Scheme and C functions::
* I/O internals::
* libguile error handling::
* snarfing::

Appendices and Indices

* Obtaining and Installing Guile::
* Reporting Bugs::
* Internals::
* debugger user interface::

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

@end menu


@c preliminary
@iftex
@page
@unnumbered{Part I: Preliminaries}
@end iftex

@include intro.texi

@c programming in Scheme
@iftex
@page
@unnumbered{Part II: Scheme Extensions}
@end iftex

@include scheme.texi

@c Unix system interface
@iftex
@page
@unnumbered{Part III: Unix Programming}
@end iftex

@include posix.texi

@c Guile as an extension language
@iftex
@page
@unnumbered{Part IV: Using Scheme with C --- a Portable Interface}
@end iftex

@include gh.texi

@iftex
@page
@unnumbered{Part V: Using Scheme with C --- Guile's Low-Level Interface}
@end iftex

@include scm.texi

@c Appendices and Indices
@iftex
@page
@unnumbered{Appendices and Indices}
@end iftex

@include appendices.texi

@contents

@bye
