4 @setfilename guile.info
5 @settitle Guile Reference Manual
7 @set MANUAL-EDITION 1.1
12 This reference manual documents Guile, GNU's Ubiquitous Intelligent
13 Language for Extensions, manual edition @value{MANUAL-EDITION}
14 corresponding to Guile @value{VERSION}.
16 Copyright 1996, 1997, 2000, 2001, 2002, 2003, 2004 Free Software
19 Permission is granted to make and distribute verbatim copies of
20 this manual provided the copyright notice and this permission notice
21 are preserved on all copies.
23 Permission is granted to copy and distribute modified versions of this
24 manual under the conditions for verbatim copying, provided that the entire
25 resulting derived work is distributed under the terms of a permission
26 notice identical to this one.
28 Permission is granted to copy and distribute translations of this manual
29 into another language, under the above conditions for modified versions,
30 except that this permission notice may be stated in a translation approved
31 by Free Software Foundation.
35 Permission is granted to process this file through TeX and print the
36 results, provided the printed document carries copying permission
37 notice identical to this one except for the removal of this paragraph
38 (this paragraph not being relevant to the printed manual).
44 @c We no longer use the category "primitive" to distinguish C-defined
45 @c Scheme procedures from those defined in Scheme. Instead, the
46 @c reference manual now includes a C declaration as well as a Scheme
47 @c declaration for each procedure that is available in both Scheme and
50 @c When adding a new reference entry to the Guile manual, please
51 @c document it with @deffn using one of the following categories:
58 @c If the entry is for a new primitive, it should have both a @deffn
59 @c {Scheme Procedure} line and a @deffnx {C Function} line; see the
60 @c manual source for plenty of existing examples of this.
62 @c For {C Function} entries where the return type and all parameter
63 @c types are SCM, we omit the SCMs. This is easier to read and also
64 @c gets round the problem that Texinfo doesn't allow a @deftypefnx
67 @c For a list of Guile primitives that are not yet incorporated into the
68 @c reference manual, see the file `new-docstrings.texi', which holds all
69 @c the docstrings snarfed from the libguile C sources for primitives
70 @c that are not in the reference manual. If you have worked with some
71 @c of these concepts, implemented them, or just happen to know what they
72 @c do, please write up a little explanation -- it would be a big help.
73 @c Alternatively, if you know of any reason why some of these should
74 @c *not* go in the manual, please let the mailing list
75 @c <guile-devel@gnu.org> know.
77 @c Define indices that are used in the Guile Scheme part of the
78 @c reference manual to group stuff according to whether it is R5RS or a
82 @c vnew - For (some) new items, indicates the Guile version in which
83 @c item first appeared. In future, this could be made to expand to
84 @c something like a "New in Guile 45!" banner.
89 @c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give
90 @c different forms for math in tex and info.
102 @c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be
103 @c used when the quotes that @code{} gives in info aren't wanted, but
104 @c the fontification in tex or html is wanted.
121 @dircategory The Algorithmic Language Scheme
123 * Guile Reference: (guile). The Guile reference manual.
126 @setchapternewpage off
130 @comment The title is printed in a large font.
131 @title Guile Reference Manual
132 @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
133 @subtitle $Id: guile.texi,v 1.26 2004-01-10 21:40:26 kryde Exp $
137 @c The Guile reference and tutorial manuals were written and edited
138 @c largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the
139 @c original tutorial on Guile's data representation and the C API for
140 @c accessing Guile objects.
142 @c Significant portions were contributed by Gary Houston (contributions
143 @c to POSIX system calls and networking, expect, I/O internals and
144 @c extensions, slib installation, error handling) and Tim Pierce
145 @c (sections on script interpreter triggers, alists, function tracing).
147 @c Tom Lord contributed a great deal of material with early Guile
148 @c snapshots; although most of this text has been rewritten, all of it
149 @c was important, and some of the structure remains.
151 @c Aubrey Jaffer wrote the SCM Scheme implementation and manual upon
152 @c which the Guile program and manual are based. Some portions of the
153 @c SCM and SLIB manuals have been included here verbatim.
155 @c Since Guile 1.4, Neil Jerram has been maintaining and improving the
156 @c reference manual. Among other contributions, he wrote the Basic
157 @c Ideas chapter, developed the tools for keeping the manual in sync
158 @c with snarfed libguile docstrings, and reorganized the structure so as
159 @c to accommodate docstrings for all Guile's primitives.
161 @c Martin Grabmueller has made substantial contributions throughout the
162 @c reference manual in preparation for the Guile 1.6 release, including
163 @c filling out a lot of the documentation of Scheme data types, control
164 @c mechanisms and procedures. In addition, he wrote the documentation
165 @c for Guile's SRFI modules and modules associated with the Guile REPL.
168 @author Cygnus Solution and Los Alamos National Laboratory
169 @author @email{rosalia@@cygnus.com}
172 @author Free Software Foundation and MIT AI Lab
173 @author @email{jimb@@red-bean.com}
176 @author @email{ghouston@@arglist.com}
179 @author @email{twp@@skepsis.com}
182 @author @email{neil@@ossau.uklinux.net}
184 @author Martin Grabmueller
185 @author @email{mgrabmue@@cs.tu-berlin.de}
187 @c The following two commands start the copyright page.
189 @vskip 0pt plus 1filll
190 @vskip 0pt plus 1filll
198 @c Where to find Guile examples.
199 @set example-dir doc/examples
202 @node Top, Guile License, (dir), (dir)
203 @top The Guile Reference Manual
212 * Guile License:: Conditions for copying and using Guile.
213 * Manual Layout:: How to read the rest of this manual.
214 * Manual Conventions:: Conventional terminology.
216 Part I: Introduction to Guile
218 * What is Guile?:: And what does it do?
219 * Whirlwind Tour:: An introductory whirlwind tour.
220 * Obtaining and Installing Guile::
221 * Reporting Bugs:: Reporting bugs in Guile or this manual.
223 Part II: Writing and Running Guile Scheme
225 * Running Intro:: Introduction to this part.
226 * Guile Scheme:: Guile's implementation of Scheme.
227 * Guile Scripting:: How to write Guile scripts.
228 * Command Line Handling:: Command line options and arguments.
229 * Debugging Features:: Features for debugging errors.
230 * Autoconf Support:: Guile-specific configure.in macros.
231 * Miscellaneous Tools:: Snarfing, linting, etc.
232 * Basic Ideas:: Basic ideas in Scheme.
233 * Further Reading:: Where to find out more about Scheme.
235 Part III: Guile as an Extension Language
237 * Programming Intro:: Introduction to this part.
238 * Libguile Intro:: Using Guile as an extension language.
239 * Programming Overview:: An overview of Guile programming.
240 * Data Representation:: Data representation in Guile.
241 * GH:: The deprecated GH interface.
243 Part IV: Guile API Reference
245 * Reference Intro:: Introduction to the Guile API reference.
246 * API Overview:: Overview of the Guile API.
247 * Simple Data Types:: Numbers, strings, booleans and so on.
248 * Compound Data Types:: Data types for holding other data.
249 * Procedures and Macros:: Procedures and macros.
250 * Utility Functions:: General utility functions.
251 * Binding Constructs:: Definitions and variable bindings.
252 * Control Mechanisms:: Controlling the flow of program execution.
253 * Input and Output:: Ports, reading and writing.
254 * Read/Load/Eval:: Reading and evaluating Scheme code.
255 * Memory Management:: Memory management and garbage collection.
256 * Objects:: Low level object orientation support.
257 * Modules:: Designing reusable code libraries.
258 * Scheduling:: Threads, mutexes, asyncs and dynamic roots.
259 * Options and Config:: Configuration, features and runtime options.
260 * Translation:: Support for translating other languages.
261 * Debugging:: Internal debugging interface.
262 * Deprecated:: Features that are planned to disappear.
264 Part V: Guile Modules
266 * SLIB:: Using the SLIB Scheme library.
267 * POSIX:: POSIX system calls and networking.
268 * SRFI Support:: Support for various SRFIs.
269 * Readline Support:: Module for using the readline library.
270 * Value History:: Maintaining a value history in the REPL.
271 * Pretty Printing:: Nicely formatting Scheme objects for output.
272 * Formatted Output:: The @code{format} procedure.
273 * Rx Regexps:: The Rx regular expression library.
274 * File Tree Walk:: Traversing the file system.
275 * Queues:: First-in first-out queuing.
276 * Expect:: Controlling interactive programs with Guile.
277 * The Scheme shell (scsh):: Using scsh interfaces in Guile.
291 @include preface.texi
295 @unnumbered{Part I: Introduction to Guile}
302 @unnumbered Part II: Writing and Running Guile Scheme
304 Guile's core language is Scheme, and an awful lot can be achieved simply
305 by using Guile to write and run Scheme programs. In this part of the
306 manual, we explain how to use Guile in this mode, and describe the tools
307 that Guile provides to help you with script writing, debugging and
308 packaging your programs for distribution.
310 For readers who are not yet familiar with the Scheme language, this part
311 includes a chapter that presents the basic concepts of the language, and
312 gives references to freely available Scheme tutorial material on the
315 For detailed reference information on the variables, functions etc. that
316 make up Guile's application programming interface (API), please refer to
317 Part IV (@pxref{Reference Intro,,Part IV --- Guile API Reference}).
319 @include scheme-intro.texi
320 @include scripts.texi
321 @include script-getopt.texi
322 @include debugging.texi
323 @include autoconf.texi
325 @include scheme-ideas.texi
326 @include scheme-reading.texi
329 @node Programming Intro
330 @unnumbered Part III: Guile as an Extension Language
332 In this part of the manual, we aim to present a wide ranging picture of
333 what it means to use Guile as an application extension language, to
334 provide guidance, practical guidelines and tips for @emph{how} to
335 program in Guile, and to document the tools that are available to help
336 you with your programming. For detailed reference information on the
337 variables, functions etc. that make up Guile's application programming
338 interface (API), please refer to Part IV (@pxref{Reference Intro,,Part
339 IV --- Guile API Reference}).
342 @include program.texi
343 @include data-rep.texi
347 @node Reference Intro
348 @unnumbered Part IV: Guile API Reference
350 Guile provides an application programming interface (@dfn{API}) to
351 developers in two core languages: Scheme and C. This part of the manual
352 contains reference documentation for all of the functionality that is
353 available through both Scheme and C interfaces.
356 @include scheme-data.texi
357 @include scheme-compound.texi
358 @include scheme-procedures.texi
359 @include scheme-utility.texi
360 @include scheme-binding.texi
361 @include scheme-control.texi
362 @include scheme-io.texi
363 @include scheme-evaluation.texi
364 @include scheme-memory.texi
365 @include scheme-modules.texi
366 @include scheme-scheduling.texi
367 @c object orientation support here
368 @include scheme-options.texi
369 @include scheme-translation.texi
370 @include scheme-debug.texi
371 @include deprecated.texi
375 @unnumbered{Part V: Guile Modules}
380 @include srfi-modules.texi
381 @include repl-modules.texi
382 @include misc-modules.texi
391 @include indices.texi
392 @include scheme-indices.texi