@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 reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions, manual edition @value{MANUAL-EDITION}
-corresponding to Guile @value{VERSION}.
-
-Copyright 1996, 1997, 2000, 2001, 2002, 2003 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.
+This manual documents Guile version @value{VERSION}.
+
+Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010 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.3 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
-@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
-
@c Notes
@c
@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
@end macro
@end ifnottex
-@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be
-@c used when the quotes that @code{} gives in info aren't wanted, but
-@c the fontification in tex or html is wanted.
+@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
-@macro nicode {S}
-\S\
-@end macro
+@alias nicode=asis
@end ifinfo
@ifnotinfo
-@macro nicode {S}
-@code{\S\}
-@end macro
+@alias nicode=code
@end ifnotinfo
* Guile Reference: (guile). The Guile reference manual.
@end direntry
-@setchapternewpage off
+@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.24 2003-08-29 23:02:36 kryde 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
@set example-dir doc/examples
@ifnottex
-@node Top, Guile License, (dir), (dir)
+@node Top, Preface, (dir), (dir)
@top The Guile Reference Manual
@insertcopying
@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::
+
+* Hello Guile!::
+* Hello Scheme!::
+
+* Programming in Scheme::
+* Programming in C::
+
+* API Reference::
+
+* Guile Modules::
+* Standard Library::
+
+* GOOPS::
-Part I: Introduction to Guile
+* Guile Implementation::
-* 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.
+* Autoconf Support::
-Part II: Writing and Running Guile Scheme
+Appendices
-* Running Intro:: Introduction to this part.
+* GNU Free Documentation License:: The license of this manual.
+
+Indices
+
+* Concept Index::
+* Procedure Index::
+* Variable Index::
+* Type Index::
+* R5RS Index::
+
+@end menu
+
+@contents
+
+@include preface.texi
+
+@include intro.texi
+
+@include tour.texi
+
+@include scheme-ideas.texi
+@include scheme-reading.texi
+
+@node Programming in Scheme
+@chapter Programming in Scheme
+
+Guile's core language is Scheme, and a lot can be achieved simply by using Guile
+to write and run Scheme programs --- as opposed to having to dive into C code.
+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 detailed reference information on the variables, functions
+etc. that make up Guile's application programming interface (API),
+@xref{API Reference}.
+
+@menu
* 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.
+* Using Guile Interactively:: Guile's REPL features.
+* Using Guile in Emacs:: Guile and Emacs.
+@end menu
+
+@include scheme-intro.texi
+@include scheme-scripts.texi
+@include scheme-using.texi
+
+@node Programming in C
+@chapter Programming in C
-Part III: Guile as an Extension Language
+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.
-* Programming Intro:: Introduction to this part.
-* Libguile Intro:: Using Guile as an extension language.
+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.
+
+For a pedagogical yet detailed explanation of how the data representation of
+Guile is implemented, @xref{Data Representation}. 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.
-* Data Representation:: Data representation in Guile.
-* GH:: The deprecated GH interface.
+@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
-Part IV: Guile API Reference
+@node API Reference
+@chapter API Reference
-* Reference Intro:: Introduction to the 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.
+
+@menu
* API Overview:: Overview of the Guile API.
+* Discouraged and Deprecated:: Obsolete back-compatible APIs.
+* 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.
-* Procedures and Macros:: Procedures and macros.
+* Smobs:: Defining new data types in C.
+* Procedures:: Procedures.
+* Macros:: Extending the syntax of Scheme.
* 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.
+* LALR(1) Parsing:: Generating LALR(1) parsers.
+* 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.
+* Foreign Function Interface:: Interacting with C procedures and data.
* 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.
+* Other Languages:: Emacs Lisp, ECMAScript, and more.
+* Internationalization:: Support for gettext, etc.
+* Debugging:: Debugging infrastructure and Scheme interface.
+* Code Coverage:: Gathering code coverage data.
+@end menu
-Part V: Guile Modules
+@include api-overview.texi
+@include api-discdepr.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-macros.texi
+@include api-utility.texi
+@include api-binding.texi
+@include api-control.texi
+@include api-io.texi
+@include api-lalr.texi
+@include api-evaluation.texi
+@include api-memory.texi
+@include api-modules.texi
+@include api-foreign.texi
+@include api-scheduling.texi
+@c object orientation support here
+@include api-options.texi
+@include api-languages.texi
+@include api-i18n.texi
+@include api-debug.texi
+@include api-coverage.texi
+@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.
+* R6RS Support:: Modules defined by the R6RS.
* 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.
+* 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.
+* sxml-match:: Pattern matching of SXML.
* The Scheme shell (scsh):: Using scsh interfaces in Guile.
-
-Indices
-
-* Concept Index::
-* Procedure Index::
-* Variable Index::
-* Type Index::
-* R5RS Index::
-
+* Tracing:: Tracing program execution.
@end menu
-@contents
+@include slib.texi
+@include posix.texi
+@include mod-getopt-long.texi
+@include srfi-modules.texi
+@include r6rs.texi
+@include repl-modules.texi
+@include misc-modules.texi
+@include expect.texi
-@include preface.texi
+@c XXX: Would be nicer if it were close to the (sxml simple) documentation.
+@include sxml-match.texi
-@iftex
-@page
-@unnumbered{Part I: Introduction to Guile}
-@end iftex
+@include scsh.texi
+@include scheme-debugging.texi
-@include intro.texi
+@node Standard Library
+@chapter Standard Library
-@page
-@node Running Intro
-@unnumbered Part II: Writing and Running Guile Scheme
+@lowersections
+@include standard-library.texi
+@raisesections
-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.
+@include goops.texi
-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.
+@node Guile Implementation
+@chapter Guile Implementation
-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}).
+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'.''
-@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
+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.
-@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
+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.
-@page
-@node Reference Intro
-@unnumbered Part IV: Guile API Reference
+@menu
+* History:: A brief history of Guile.
+* Data Representation:: How Guile represents Scheme data.
+* A Virtual Machine for Guile:: How compiled procedures work.
+* Compiling to the Virtual Machine:: Not as hard as you might think.
+@end menu
-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 history.texi
+@include data-rep.texi
+@include vm.texi
+@include compiler.texi
-@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
+@include autoconf.texi
-@iftex
-@page
-@unnumbered{Part V: Guile Modules}
-@end iftex
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
-@include slib.texi
-@include posix.texi
-@include srfi-modules.texi
-@include repl-modules.texi
-@include misc-modules.texi
-@include expect.texi
-@include scsh.texi
+@include fdl.texi
@iftex
@page
HCoop / bpt / guile.git / blobdiff