4 @setfilename guile.info
5 @settitle Guile Reference Manual
7 @set MANUAL-EDITION 1.1
10 @include lib-version.texi
13 This reference manual documents Guile, GNU's Ubiquitous Intelligent
14 Language for Extensions. This is edition @value{MANUAL-EDITION}
15 corresponding to Guile @value{VERSION}.
17 Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005 Free
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.2 or
22 any later version published by the Free Software Foundation; with the
23 no Invariant Sections, with the Front-Cover Texts being ``A GNU
24 Manual,'' and with the Back-Cover Text ``You are free to copy and
25 modify this GNU Manual.''. A copy of the license is included in the
26 section entitled ``GNU Free Documentation License''.
32 @c We no longer use the category "primitive" to distinguish C-defined
33 @c Scheme procedures from those defined in Scheme. Instead, the
34 @c reference manual now includes a C declaration as well as a Scheme
35 @c declaration for each procedure that is available in both Scheme and
38 @c When adding a new reference entry to the Guile manual, please
39 @c document it with @deffn using one of the following categories:
46 @c If the entry is for a new primitive, it should have both a @deffn
47 @c {Scheme Procedure} line and a @deffnx {C Function} line; see the
48 @c manual source for plenty of existing examples of this.
50 @c For {C Function} entries where the return type and all parameter
51 @c types are SCM, we omit the SCMs. This is easier to read and also
52 @c gets round the problem that Texinfo doesn't allow a @deftypefnx
55 @c For a list of Guile primitives that are not yet incorporated into the
56 @c reference manual, see the file `new-docstrings.texi', which holds all
57 @c the docstrings snarfed from the libguile C sources for primitives
58 @c that are not in the reference manual. If you have worked with some
59 @c of these concepts, implemented them, or just happen to know what they
60 @c do, please write up a little explanation -- it would be a big help.
61 @c Alternatively, if you know of any reason why some of these should
62 @c *not* go in the manual, please let the mailing list
63 @c <guile-devel@gnu.org> know.
65 @c Define indices that are used in the Guile Scheme part of the
66 @c reference manual to group stuff according to whether it is R5RS or a
70 @c vnew - For (some) new items, indicates the Guile version in which
71 @c item first appeared. In future, this could be made to expand to
72 @c something like a "New in Guile 45!" banner.
77 @c The following, @le{} and @ge{}, are standard tex directives, given
78 @c definitions for use in non-tex.
89 @c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works
90 @c inside or outside $ $.
92 \gdef\cross{\ifmmode\times\else$\times$\fi}
100 @c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give
101 @c different forms for math in tex and info.
113 @c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used
114 @c when the quotes that @code{} gives in info aren't wanted, but the
115 @c fontification in tex or html is wanted. @alias is used rather
116 @c than @macro because backslashes don't work properly in an @macro.
129 @dircategory The Algorithmic Language Scheme
131 * Guile Reference: (guile). The Guile reference manual.
134 @setchapternewpage odd
138 @comment The title is printed in a large font.
139 @title Guile Reference Manual
140 @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
141 @c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $
143 @c See preface.texi for the list of authors
144 @author The Guile Developers
146 @c The following two commands start the copyright page.
148 @vskip 0pt plus 1filll
149 @vskip 0pt plus 1filll
157 @c Where to find Guile examples.
158 @set example-dir doc/examples
161 @node Top, Preface, (dir), (dir)
162 @top The Guile Reference Manual
171 * Introduction to Guile::
173 * Programming in Scheme::
180 * Guile Implementation::
186 * GNU Free Documentation License:: The license of this manual.
200 @include preface.texi
204 @node Programming in Scheme
205 @chapter Programming in Scheme
207 Guile's core language is Scheme, and an awful lot can be achieved simply
208 by using Guile to write and run Scheme programs. In this part of the
209 manual, we explain how to use Guile in this mode, and describe the tools
210 that Guile provides to help you with script writing, debugging and
211 packaging your programs for distribution.
213 For readers who are not yet familiar with the Scheme language, this part
214 includes a chapter that presents the basic concepts of the language, and
215 gives references to freely available Scheme tutorial material on the
218 For detailed reference information on the variables, functions
219 etc. that make up Guile's application programming interface (API),
220 @xref{API Reference}.
223 * Basic Ideas:: Basic ideas in Scheme.
224 * Guile Scheme:: Guile's implementation of Scheme.
225 * Guile Scripting:: How to write Guile scripts.
226 * Using Guile Interactively:: Guile's REPL features.
227 * Using Guile in Emacs:: Guile and Emacs.
228 * Further Reading:: Where to find out more about Scheme.
231 @include scheme-ideas.texi
232 @include scheme-intro.texi
233 @include scheme-scripts.texi
234 @include scheme-using.texi
235 @include scheme-reading.texi
237 @node Programming in C
238 @chapter Programming in C
240 This part of the manual explains the general concepts that you need to
241 understand when interfacing to Guile from C. You will learn about how
242 the latent typing of Scheme is embedded into the static typing of C, how
243 the garbage collection of Guile is made available to C code, and how
244 continuations influence the control flow in a C program.
246 This knowledge should make it straightforward to add new functions to
247 Guile that can be called from Scheme. Adding new data types is also
248 possible and is done by defining @dfn{smobs}.
250 The @ref{Programming Overview} section of this part contains general
251 musings and guidelines about programming with Guile. It explores
252 different ways to design a program around Guile, or how to embed Guile
253 into existing programs.
255 There is also a pedagogical yet detailed explanation of how the data
256 representation of Guile is implemented, see @ref{Data Representation in
257 Scheme} and @ref{The Libguile Runtime Environment}.
259 You don't need to know the details given there to use Guile from C,
260 but they are useful when you want to modify Guile itself or when you
261 are just curious about how it is all done.
263 For detailed reference information on the variables, functions
264 etc. that make up Guile's application programming interface (API),
265 @xref{API Reference}.
268 * Linking Programs With Guile:: More precisely, with the libguile library.
269 * Linking Guile with Libraries:: To extend Guile itself.
270 * General Libguile Concepts:: General concepts for using libguile.
271 * Defining New Types (Smobs):: Adding new types to Guile.
272 * Function Snarfing:: A way to define new functions.
273 * Programming Overview:: An overview of Guile programming.
276 @include libguile-linking.texi
277 @include libguile-extensions.texi
278 @include libguile-concepts.texi
279 @include libguile-smobs.texi
280 @include libguile-snarf.texi
281 @include libguile-program.texi
284 @chapter API Reference
286 Guile provides an application programming interface (@dfn{API}) to
287 developers in two core languages: Scheme and C. This part of the manual
288 contains reference documentation for all of the functionality that is
289 available through both Scheme and C interfaces.
292 * API Overview:: Overview of the Guile API.
293 * The SCM Type:: The fundamental data type for C code.
294 * Initialization:: Initializing Guile.
295 * Snarfing Macros:: Macros for snarfing initialization actions.
296 * Simple Data Types:: Numbers, strings, booleans and so on.
297 * Compound Data Types:: Data types for holding other data.
298 * Smobs:: Defining new data types in C.
299 * Procedures and Macros:: Procedures and macros.
300 * Utility Functions:: General utility functions.
301 * Binding Constructs:: Definitions and variable bindings.
302 * Control Mechanisms:: Controlling the flow of program execution.
303 * Input and Output:: Ports, reading and writing.
304 * Read/Load/Eval/Compile:: Reading and evaluating Scheme code.
305 * Memory Management:: Memory management and garbage collection.
306 * Objects:: Low level object orientation support.
307 * Modules:: Designing reusable code libraries.
308 * Scheduling:: Threads, mutexes, asyncs and dynamic roots.
309 * Options and Config:: Configuration, features and runtime options.
310 * Translation:: Support for translating other languages.
311 * Internationalization:: Support for gettext, etc.
312 * Debugging:: Debugging infrastructure and Scheme interface.
315 @include api-overview.texi
316 @include api-scm.texi
317 @include api-init.texi
318 @include api-snarf.texi
319 @include api-data.texi
320 @include api-compound.texi
321 @include api-smobs.texi
322 @include api-procedures.texi
323 @include api-utility.texi
324 @include api-binding.texi
325 @include api-control.texi
327 @include api-evaluation.texi
328 @include api-memory.texi
329 @include api-modules.texi
330 @include api-scheduling.texi
331 @c object orientation support here
332 @include api-options.texi
333 @include api-translation.texi
334 @include api-i18n.texi
335 @include api-debug.texi
338 @chapter Guile Modules
341 * SLIB:: Using the SLIB Scheme library.
342 * POSIX:: POSIX system calls and networking.
343 * getopt-long:: Command line handling.
344 * SRFI Support:: Support for various SRFIs.
345 * Readline Support:: Module for using the readline library.
346 * Value History:: Maintaining a value history in the REPL.
347 * Pretty Printing:: Nicely formatting Scheme objects for output.
348 * Formatted Output:: The @code{format} procedure.
349 * File Tree Walk:: Traversing the file system.
350 * Queues:: First-in first-out queuing.
351 * Streams:: Sequences of values.
352 * Buffered Input:: Ports made from a reader function.
353 * Expect:: Controlling interactive programs with Guile.
354 * The Scheme shell (scsh):: Using scsh interfaces in Guile.
355 * Tracing:: Tracing program execution.
360 @include mod-getopt-long.texi
361 @include srfi-modules.texi
362 @include repl-modules.texi
363 @include misc-modules.texi
366 @include scheme-debugging.texi
368 @node Guile Implementation
369 @chapter Guile Implementation
371 At some point, after one has been programming in Scheme for some time,
372 another level of Scheme comes into view: its implementation. Knowledge
373 of how Scheme can be implemented turns out to be necessary to become
374 an expert hacker. As Peter Norvig notes in his retrospective on
375 PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of
376 Artificial Intelligence Programming}, an old but still useful text on
377 Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be
378 found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp
379 programmer eventually develops a good `efficiency model'.''
381 By this Norvig means that over time, the Lisp hacker eventually
382 develops an understanding of how much her code ``costs'' in terms of
385 This chapter describes Guile as an implementation of Scheme: its
386 history, how it represents and evaluates its data, and its compiler.
387 This knowledge can help you to make that step from being one who is
388 merely familiar with Scheme to being a real hacker.
391 * History:: A brief history of Guile.
392 * Data Representation in Scheme:: Why things aren't just totally
393 straightforward, in general terms.
394 * The Libguile Runtime Environment:: Low-level details on Guile's C
396 * A Virtual Machine for Guile:: How compiled procedures work.
397 * Compiling to the Virtual Machine:: Not as hard as you might think.
400 @include history.texi
401 @include data-rep.texi
403 @include compiler.texi
405 @include autoconf.texi
414 @include indices.texi
415 @include scheme-indices.texi