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. This is edition @value{MANUAL-EDITION}
14 corresponding to Guile @value{VERSION}.
16 Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 Free Software
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.2 or
21 any later version published by the Free Software Foundation; with the
22 no Invariant Sections, with the Front-Cover Texts being ``A GNU
23 Manual,'' and with the Back-Cover Text ``You are free to copy and
24 modify this GNU Manual.''. A copy of the license is included in the
25 section entitled "GNU Free Documentation License".
31 @c We no longer use the category "primitive" to distinguish C-defined
32 @c Scheme procedures from those defined in Scheme. Instead, the
33 @c reference manual now includes a C declaration as well as a Scheme
34 @c declaration for each procedure that is available in both Scheme and
37 @c When adding a new reference entry to the Guile manual, please
38 @c document it with @deffn using one of the following categories:
45 @c If the entry is for a new primitive, it should have both a @deffn
46 @c {Scheme Procedure} line and a @deffnx {C Function} line; see the
47 @c manual source for plenty of existing examples of this.
49 @c For {C Function} entries where the return type and all parameter
50 @c types are SCM, we omit the SCMs. This is easier to read and also
51 @c gets round the problem that Texinfo doesn't allow a @deftypefnx
54 @c For a list of Guile primitives that are not yet incorporated into the
55 @c reference manual, see the file `new-docstrings.texi', which holds all
56 @c the docstrings snarfed from the libguile C sources for primitives
57 @c that are not in the reference manual. If you have worked with some
58 @c of these concepts, implemented them, or just happen to know what they
59 @c do, please write up a little explanation -- it would be a big help.
60 @c Alternatively, if you know of any reason why some of these should
61 @c *not* go in the manual, please let the mailing list
62 @c <guile-devel@gnu.org> know.
64 @c Define indices that are used in the Guile Scheme part of the
65 @c reference manual to group stuff according to whether it is R5RS or a
69 @c vnew - For (some) new items, indicates the Guile version in which
70 @c item first appeared. In future, this could be made to expand to
71 @c something like a "New in Guile 45!" banner.
76 @c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works
77 @c inside or outside $ $.
79 \gdef\cross{\ifmmode\times\else$\times$\fi}
87 @c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give
88 @c different forms for math in tex and info.
100 @c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used
101 @c when the quotes that @code{} gives in info aren't wanted, but the
102 @c fontification in tex or html is wanted. @alias is used rather
103 @c than @macro because backslashes don't work properly in an @macro.
116 @dircategory The Algorithmic Language Scheme
118 * Guile Reference: (guile). The Guile reference manual.
121 @setchapternewpage odd
125 @comment The title is printed in a large font.
126 @title Guile Reference Manual
127 @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
128 @c @subtitle $Id: guile.texi,v 1.32 2004-07-24 00:45:02 kryde Exp $
130 @c See preface.texi for the list of authors
131 @author The Guile Developers
133 @c The following two commands start the copyright page.
135 @vskip 0pt plus 1filll
136 @vskip 0pt plus 1filll
144 @c Where to find Guile examples.
145 @set example-dir doc/examples
148 @node Top, Preface, (dir), (dir)
149 @top The Guile Reference Manual
158 * Introduction to Guile::
160 * Programming in Scheme::
169 * Data Representation:: All the details.
170 * GNU Free Documentation License:: The license of this manual.
184 @include preface.texi
188 @node Programming in Scheme
189 @chapter Programming in Scheme
191 Guile's core language is Scheme, and an awful lot can be achieved simply
192 by using Guile to write and run Scheme programs. In this part of the
193 manual, we explain how to use Guile in this mode, and describe the tools
194 that Guile provides to help you with script writing, debugging and
195 packaging your programs for distribution.
197 For readers who are not yet familiar with the Scheme language, this part
198 includes a chapter that presents the basic concepts of the language, and
199 gives references to freely available Scheme tutorial material on the
202 For detailed reference information on the variables, functions
203 etc. that make up Guile's application programming interface (API),
204 @xref{API Reference}.
207 * Basic Ideas:: Basic ideas in Scheme.
208 * Guile Scheme:: Guile's implementation of Scheme.
209 * Guile Scripting:: How to write Guile scripts.
210 * Debugging Features:: Features for finding errors.
211 * Further Reading:: Where to find out more about Scheme.
214 @include scheme-ideas.texi
215 @include scheme-intro.texi
216 @include scripts.texi
217 @include debugging.texi
218 @include scheme-reading.texi
220 @node Programming in C
221 @chapter Programming in C
223 This part of the manual explains the general concepts that you need to
224 understand when interfacing to Guile from C. You will learn about how
225 the latent typing of Scheme is embedded into the static typing of C, how
226 the garbage collection of Guile is made available to C code, and how
227 continuations influence the control flow in a C program.
229 This knowledge should make it straightforward to add new functions to
230 Guile that can be called from Scheme. Adding new data types is also
231 possible and is done by defining @dfn{smobs}.
233 The @ref{Programming Overview} section of this part contains general
234 musings and guidelines about programming with Guile. It explores
235 different ways to design aprogram around Guile, or how to embed Guile
236 into existing programs.
238 There is also a pedagogical yet detailed explanation of how the data
239 representation of Guile is implemented, @xref{Data Representation}.
240 You don't need to know the details given there to use Guile from C,
241 but they are useful when you want to modify Guile itself or when you
242 are just curious about how it is all done.
244 For detailed reference information on the variables, functions
245 etc. that make up Guile's application programming interface (API),
246 @xref{API Reference}.
249 * Linking Programs With Guile:: More precisely, with the libguile library.
250 * Linking Guile with Libraries:: To extend Guile itself.
251 * General Libguile Concepts:: General concepts for using libguile.
252 * Defining New Types (Smobs):: Adding new types to Guile.
253 * Function Snarfing:: A way to define new functions.
254 * Programming Overview:: An overview of Guile programming.
257 @include libguile-linking.texi
258 @include libguile-extensions.texi
259 @include libguile-concepts.texi
260 @include libguile-smobs.texi
261 @include libguile-snarf.texi
262 @include program.texi
265 @chapter API Reference
267 Guile provides an application programming interface (@dfn{API}) to
268 developers in two core languages: Scheme and C. This part of the manual
269 contains reference documentation for all of the functionality that is
270 available through both Scheme and C interfaces.
273 * API Overview:: Overview of the Guile API.
274 * The SCM Type:: The fundamental data type for C code.
275 * Initialization:: Initializing Guile.
276 * Snarfing Macros:: Macros for snarfing initialization actions.
277 * Simple Data Types:: Numbers, strings, booleans and so on.
278 * Compound Data Types:: Data types for holding other data.
279 * Smobs:: Defining new data types in C.
280 * Procedures and Macros:: Procedures and macros.
281 * Utility Functions:: General utility functions.
282 * Binding Constructs:: Definitions and variable bindings.
283 * Control Mechanisms:: Controlling the flow of program execution.
284 * Input and Output:: Ports, reading and writing.
285 * Read/Load/Eval:: Reading and evaluating Scheme code.
286 * Memory Management:: Memory management and garbage collection.
287 * Objects:: Low level object orientation support.
288 * Modules:: Designing reusable code libraries.
289 * Scheduling:: Threads, mutexes, asyncs and dynamic roots.
290 * Options and Config:: Configuration, features and runtime options.
291 * Translation:: Support for translating other languages.
292 * Debugging:: Internal debugging interface.
293 * Deprecated:: Features that are planned to disappear.
294 * GH:: The deprecated GH interface.
298 @include scheme-scm.texi
299 @include ref-init.texi
300 @include scheme-snarf.texi
301 @include scheme-data.texi
302 @include scheme-compound.texi
303 @include scheme-smobs.texi
304 @include scheme-procedures.texi
305 @include scheme-utility.texi
306 @include scheme-binding.texi
307 @include scheme-control.texi
308 @include scheme-io.texi
309 @include scheme-evaluation.texi
310 @include scheme-memory.texi
311 @include scheme-modules.texi
312 @include scheme-scheduling.texi
313 @c object orientation support here
314 @include scheme-options.texi
315 @include scheme-translation.texi
316 @include scheme-debug.texi
317 @include deprecated.texi
321 @chapter Guile Modules
324 * SLIB:: Using the SLIB Scheme library.
325 * POSIX:: POSIX system calls and networking.
326 * getopt-long:: Command line handling.
327 * SRFI Support:: Support for various SRFIs.
328 * Readline Support:: Module for using the readline library.
329 * Value History:: Maintaining a value history in the REPL.
330 * Pretty Printing:: Nicely formatting Scheme objects for output.
331 * Formatted Output:: The @code{format} procedure.
332 * Rx Regexps:: The Rx regular expression library.
333 * File Tree Walk:: Traversing the file system.
334 * Queues:: First-in first-out queuing.
335 * Expect:: Controlling interactive programs with Guile.
336 * The Scheme shell (scsh):: Using scsh interfaces in Guile.
341 @include mod-getopt-long.texi
342 @include srfi-modules.texi
343 @include repl-modules.texi
344 @include misc-modules.texi
348 @include data-rep.texi
356 @include indices.texi
357 @include scheme-indices.texi