@setfilename guile.info
@settitle Guile Reference Manual
@set guile
-@set MANUAL_EDITION 1.1
+@set MANUAL-REVISION 1
@c %**end of header
+@include version.texi
+@include lib-version.texi
+@include effective-version.texi
+
+@copying
+This manual documents Guile version @value{VERSION}.
+
+Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009 Free
+Software Foundation.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with
+no Invariant Sections, with the Front-Cover Texts being ``A GNU
+Manual,'' and with the Back-Cover Text ``You are free to copy and
+modify this GNU Manual.''. A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
+@end copying
+
@c Notes
@c
@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 The following, @le{} and @ge{}, are standard tex directives, given
+@c definitions for use in non-tex.
+@c
+@ifnottex
+@macro ge
+>=
+@end macro
+@macro le
+<=
+@end macro
+@end ifnottex
+
+@c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works
+@c inside or outside $ $.
+@tex
+\gdef\cross{\ifmmode\times\else$\times$\fi}
+@end tex
+@ifnottex
+@macro cross
+x
+@end macro
+@end ifnottex
+
+@c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give
+@c different forms for math in tex and info.
+@iftex
+@macro m {T,N}
+@tex$\T\$@end tex
+@end macro
+@end iftex
+@ifnottex
+@macro m {T,N}
+@math{\N\}
+@end macro
+@end ifnottex
+
+@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used
+@c when the quotes that @code{} gives in info aren't wanted, but the
+@c fontification in tex or html is wanted. @alias is used rather
+@c than @macro because backslashes don't work properly in an @macro.
+@ifinfo
+@alias nicode=asis
+@end ifinfo
+@ifnotinfo
+@alias nicode=code
+@end ifnotinfo
+
+
@c @iftex
@c @cropmarks
@c @end iftex
* 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
+@setchapternewpage odd
@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}
+@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION}
+@c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $
+
+@c See preface.texi for the list of authors
+@author The Guile Developers
@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.
+@insertcopying
@end titlepage
@c @smallbook
@set example-dir doc/examples
@ifnottex
-@node Top, Guile License, (dir), (dir)
+@node Top, Preface, (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}.
+@insertcopying
+@sp 1
@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.
+* Preface::
+* Introduction to Guile::
-Part I: Introduction to Guile
+* Programming in Scheme::
+* Programming in C::
-* 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.
+* API Reference::
-Part II: Writing and Running Guile Scheme
+* Guile Modules::
-* 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.
+* GOOPS::
-Part III: Guile as an Extension Language
+* Guile Implementation::
-* 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.
+* Autoconf Support::
-Part IV: Guile API Reference
+Appendices
-* 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.
+* GNU Free Documentation License:: The license of this manual.
Indices
@end menu
-@include preface.texi
+@contents
-@iftex
-@page
-@unnumbered{Part I: Introduction to Guile}
-@end iftex
+@include preface.texi
@include intro.texi
-@page
-@node Running Intro
-@unnumbered Part II: Writing and Running Guile Scheme
+@node Programming in Scheme
+@chapter Programming in 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
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}).
+For detailed reference information on the variables, functions
+etc. that make up Guile's application programming interface (API),
+@xref{API Reference}.
+
+@menu
+* Basic Ideas:: Basic ideas in Scheme.
+* Guile Scheme:: Guile's implementation of Scheme.
+* Guile Scripting:: How to write Guile scripts.
+* Using Guile Interactively:: Guile's REPL features.
+* Using Guile in Emacs:: Guile and Emacs.
+* Further Reading:: Where to find out more about Scheme.
+@end menu
-@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-intro.texi
+@include scheme-scripts.texi
+@include scheme-using.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
+@node Programming in C
+@chapter Programming in C
-@page
-@node Reference Intro
-@unnumbered Part IV: Guile API Reference
+This part of the manual explains the general concepts that you need to
+understand when interfacing to Guile from C. You will learn about how
+the latent typing of Scheme is embedded into the static typing of C, how
+the garbage collection of Guile is made available to C code, and how
+continuations influence the control flow in a C program.
+
+This knowledge should make it straightforward to add new functions to
+Guile that can be called from Scheme. Adding new data types is also
+possible and is done by defining @dfn{smobs}.
+
+The @ref{Programming Overview} section of this part contains general
+musings and guidelines about programming with Guile. It explores
+different ways to design a program around Guile, or how to embed Guile
+into existing programs.
+
+There is also a pedagogical yet detailed explanation of how the data
+representation of Guile is implemented, see @ref{Data Representation in
+Scheme} and @ref{The Libguile Runtime Environment}.
+
+You don't need to know the details given there to use Guile from C,
+but they are useful when you want to modify Guile itself or when you
+are just curious about how it is all done.
+
+For detailed reference information on the variables, functions
+etc. that make up Guile's application programming interface (API),
+@xref{API Reference}.
+
+@menu
+* Linking Programs With Guile:: More precisely, with the libguile library.
+* Linking Guile with Libraries:: To extend Guile itself.
+* General Libguile Concepts:: General concepts for using libguile.
+* Defining New Types (Smobs):: Adding new types to Guile.
+* Function Snarfing:: A way to define new functions.
+* Programming Overview:: An overview of Guile programming.
+@end menu
+
+@include libguile-linking.texi
+@include libguile-extensions.texi
+@include libguile-concepts.texi
+@include libguile-smobs.texi
+@include libguile-snarf.texi
+@include libguile-program.texi
+
+@node API Reference
+@chapter 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
+@menu
+* API Overview:: Overview of the Guile API.
+* The SCM Type:: The fundamental data type for C code.
+* Initialization:: Initializing Guile.
+* Snarfing Macros:: Macros for snarfing initialization actions.
+* Simple Data Types:: Numbers, strings, booleans and so on.
+* Compound Data Types:: Data types for holding other data.
+* Smobs:: Defining new data types in C.
+* 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/Compile:: 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.
+* Internationalization:: Support for gettext, etc.
+* Debugging:: Debugging infrastructure and Scheme interface.
+@end menu
+
+@include api-overview.texi
+@include api-scm.texi
+@include api-init.texi
+@include api-snarf.texi
+@include api-data.texi
+@include api-compound.texi
+@include api-smobs.texi
+@include api-procedures.texi
+@include api-utility.texi
+@include api-binding.texi
+@include api-control.texi
+@include api-io.texi
+@include api-evaluation.texi
+@include api-memory.texi
+@include api-modules.texi
+@include api-scheduling.texi
@c object orientation support here
-@include scheme-options.texi
-@include scheme-translation.texi
-@include scheme-debug.texi
-@include deprecated.texi
+@include api-options.texi
+@include api-translation.texi
+@include api-i18n.texi
+@include api-debug.texi
-@iftex
-@page
-@unnumbered{Part V: Guile Modules}
-@end iftex
+@node Guile Modules
+@chapter Guile Modules
+
+@menu
+* SLIB:: Using the SLIB Scheme library.
+* POSIX:: POSIX system calls and networking.
+* getopt-long:: Command line handling.
+* 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.
+* File Tree Walk:: Traversing the file system.
+* Queues:: First-in first-out queuing.
+* Streams:: Sequences of values.
+* Buffered Input:: Ports made from a reader function.
+* Expect:: Controlling interactive programs with Guile.
+* The Scheme shell (scsh):: Using scsh interfaces in Guile.
+* Tracing:: Tracing program execution.
+@end menu
@include slib.texi
@include posix.texi
+@include mod-getopt-long.texi
@include srfi-modules.texi
@include repl-modules.texi
@include misc-modules.texi
@include expect.texi
@include scsh.texi
+@include scheme-debugging.texi
+
+@include goops.texi
+
+@node Guile Implementation
+@chapter Guile Implementation
+
+At some point, after one has been programming in Scheme for some time,
+another level of Scheme comes into view: its implementation. Knowledge
+of how Scheme can be implemented turns out to be necessary to become
+an expert hacker. As Peter Norvig notes in his retrospective on
+PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of
+Artificial Intelligence Programming}, an old but still useful text on
+Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be
+found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp
+programmer eventually develops a good `efficiency model'.''
+
+By this Norvig means that over time, the Lisp hacker eventually
+develops an understanding of how much her code ``costs'' in terms of
+space and time.
+
+This chapter describes Guile as an implementation of Scheme: its
+history, how it represents and evaluates its data, and its compiler.
+This knowledge can help you to make that step from being one who is
+merely familiar with Scheme to being a real hacker.
+
+@menu
+* History:: A brief history of Guile.
+* Data Representation in Scheme:: Why things aren't just totally
+ straightforward, in general terms.
+* The Libguile Runtime Environment:: Low-level details on Guile's C
+ runtime library.
+* A Virtual Machine for Guile:: How compiled procedures work.
+* Compiling to the Virtual Machine:: Not as hard as you might think.
+@end menu
+
+@include history.texi
+@include data-rep.texi
+@include vm.texi
+@include compiler.texi
+
+@include autoconf.texi
+
+@include fdl.texi
@iftex
@page
@include indices.texi
@include scheme-indices.texi
-@contents
-
@bye
HCoop / bpt / guile.git / blobdiff