4 @setfilename guile.info
5 @documentencoding UTF-8
6 @settitle Guile Reference Manual
11 @include effective-version.texi
14 This manual documents Guile version @value{VERSION}.
16 Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009,
17 2010, 2011, 2012 Free Software Foundation.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
23 copy of the license is included in the section entitled ``GNU Free
24 Documentation License.''
30 @c We no longer use the category "primitive" to distinguish C-defined
31 @c Scheme procedures from those defined in Scheme. Instead, the
32 @c reference manual now includes a C declaration as well as a Scheme
33 @c declaration for each procedure that is available in both Scheme and
36 @c When adding a new reference entry to the Guile manual, please
37 @c document it with @deffn using one of the following categories:
44 @c If the entry is for a new primitive, it should have both a @deffn
45 @c {Scheme Procedure} line and a @deffnx {C Function} line; see the
46 @c manual source for plenty of existing examples of this.
48 @c For {C Function} entries where the return type and all parameter
49 @c types are SCM, we omit the SCMs. This is easier to read and also
50 @c gets round the problem that Texinfo doesn't allow a @deftypefnx
53 @c For a list of Guile primitives that are not yet incorporated into the
54 @c reference manual, see the file `new-docstrings.texi', which holds all
55 @c the docstrings snarfed from the libguile C sources for primitives
56 @c that are not in the reference manual. If you have worked with some
57 @c of these concepts, implemented them, or just happen to know what they
58 @c do, please write up a little explanation -- it would be a big help.
59 @c Alternatively, if you know of any reason why some of these should
60 @c *not* go in the manual, please let the mailing list
61 @c <guile-devel@gnu.org> know.
63 @c Define indices that are used in the Guile Scheme part of the
64 @c reference manual to group stuff according to whether it is R5RS or a
68 @c vnew - For (some) new items, indicates the Guile version in which
69 @c item first appeared. In future, this could be made to expand to
70 @c something like a "New in Guile 45!" banner.
75 @c The following, @le{} and @ge{}, are standard tex directives, given
76 @c definitions for use in non-tex.
87 @c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works
88 @c inside or outside $ $.
90 \gdef\cross{\ifmmode\times\else$\times$\fi}
98 @c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give
99 @c different forms for math in tex and info.
111 @c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used
112 @c when the quotes that @code{} gives in info aren't wanted, but the
113 @c fontification in tex or html is wanted. @alias is used rather
114 @c than @macro because backslashes don't work properly in an @macro.
127 @dircategory The Algorithmic Language Scheme
129 * Guile Reference: (guile). The Guile reference manual.
132 @setchapternewpage odd
136 @comment The title is printed in a large font.
137 @title Guile Reference Manual
138 @subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION}
139 @c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $
141 @c See preface.texi for the list of authors
142 @author The Guile Developers
144 @c The following two commands start the copyright page.
146 @vskip 0pt plus 1filll
147 @vskip 0pt plus 1filll
155 @c Where to find Guile examples.
156 @set example-dir doc/examples
159 @node Top, Preface, (dir), (dir)
160 @top The Guile Reference Manual
174 * Programming in Scheme::
184 * Guile Implementation::
188 * GNU Free Documentation License:: The license of this manual.
202 @include preface.texi
208 @include scheme-ideas.texi
209 @include scheme-reading.texi
211 @node Programming in Scheme
212 @chapter Programming in Scheme
214 Guile's core language is Scheme, and a lot can be achieved simply by using Guile
215 to write and run Scheme programs --- as opposed to having to dive into C code.
216 In this part of the manual, we explain how to use Guile in this mode, and
217 describe the tools that Guile provides to help you with script writing,
218 debugging, and packaging your programs for distribution.
220 For detailed reference information on the variables, functions, and so
221 on that make up Guile's application programming interface (API), see
225 * Guile Scheme:: Guile's implementation of Scheme.
226 * Invoking Guile:: Selecting optional features when starting Guile.
227 * Guile Scripting:: How to write Guile scripts.
228 * Using Guile Interactively:: Guile's REPL features.
229 * Using Guile in Emacs:: Guile and Emacs.
230 * Using Guile Tools:: A guild of scheming wizards.
231 * Installing Site Packages:: Installing Scheme code.
234 @include scheme-intro.texi
235 @include guile-invoke.texi
236 @include scheme-scripts.texi
237 @include scheme-using.texi
239 @node Programming in C
240 @chapter Programming in C
242 This part of the manual explains the general concepts that you need to
243 understand when interfacing to Guile from C. You will learn about how
244 the latent typing of Scheme is embedded into the static typing of C, how
245 the garbage collection of Guile is made available to C code, and how
246 continuations influence the control flow in a C program.
248 This knowledge should make it straightforward to add new functions to
249 Guile that can be called from Scheme. Adding new data types is also
250 possible and is done by defining @dfn{smobs}.
252 The @ref{Programming Overview} section of this part contains general
253 musings and guidelines about programming with Guile. It explores
254 different ways to design a program around Guile, or how to embed Guile
255 into existing programs.
257 For a pedagogical yet detailed explanation of how the data representation of
258 Guile is implemented, @xref{Data Representation}. You don't need to know the
259 details given there to use Guile from C, but they are useful when you want to
260 modify Guile itself or when you are just curious about how it is all done.
262 For detailed reference information on the variables, functions
263 etc. that make up Guile's application programming interface (API),
264 @xref{API Reference}.
267 * Parallel Installations:: Finding the right Guile.
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.
274 * Autoconf Support:: Putting m4 to good use.
277 @include libguile-parallel.texi
278 @include libguile-linking.texi
279 @include libguile-extensions.texi
280 @include libguile-concepts.texi
281 @include libguile-smobs.texi
282 @include libguile-snarf.texi
283 @include libguile-program.texi
284 @include libguile-autoconf.texi
288 @chapter API Reference
290 Guile provides an application programming interface (@dfn{API}) to
291 developers in two core languages: Scheme and C. This part of the manual
292 contains reference documentation for all of the functionality that is
293 available through both Scheme and C interfaces.
296 * API Overview:: Overview of the Guile API.
297 * Deprecation:: Obsolete back-compatible APIs.
298 * The SCM Type:: The fundamental data type for C code.
299 * Initialization:: Initializing Guile.
300 * Snarfing Macros:: Macros for snarfing initialization actions.
301 * Simple Data Types:: Numbers, strings, booleans and so on.
302 * Compound Data Types:: Data types for holding other data.
303 * Smobs:: Defining new data types in C.
304 * Procedures:: Procedures.
305 * Macros:: Extending the syntax of Scheme.
306 * Utility Functions:: General utility functions.
307 * Binding Constructs:: Definitions and variable bindings.
308 * Control Mechanisms:: Controlling the flow of program execution.
309 * Input and Output:: Ports, reading and writing.
310 * Regular Expressions:: Pattern matching and substitution.
311 * LALR(1) Parsing:: Generating LALR(1) parsers.
312 * PEG Parsing:: Parsing Expression Grammars.
313 * Read/Load/Eval/Compile:: Reading and evaluating Scheme code.
314 * Memory Management:: Memory management and garbage collection.
315 * Modules:: Designing reusable code libraries.
316 * Foreign Function Interface:: Interacting with C procedures and data.
317 * Scheduling:: Threads, mutexes, asyncs and dynamic roots.
318 * Options and Config:: Configuration, features and runtime options.
319 * Other Languages:: Emacs Lisp, ECMAScript, and more.
320 * Internationalization:: Support for gettext, etc.
321 * Debugging:: Debugging infrastructure and Scheme interface.
322 * Code Coverage:: Gathering code coverage data.
325 @include api-overview.texi
326 @include api-deprecated.texi
327 @include api-scm.texi
328 @include api-init.texi
329 @include api-snarf.texi
330 @include api-data.texi
331 @include api-compound.texi
332 @include api-smobs.texi
333 @include api-procedures.texi
334 @include api-macros.texi
335 @include api-utility.texi
336 @include api-binding.texi
337 @include api-control.texi
339 @include api-regex.texi
340 @include api-lalr.texi
341 @include api-peg.texi
342 @include api-evaluation.texi
343 @include api-memory.texi
344 @include api-modules.texi
345 @include api-foreign.texi
346 @include api-scheduling.texi
347 @c object orientation support here
348 @include api-options.texi
349 @include api-languages.texi
350 @include api-i18n.texi
351 @include api-debug.texi
352 @include api-coverage.texi
355 @chapter Guile Modules
358 * SLIB:: Using the SLIB Scheme library.
359 * POSIX:: POSIX system calls and networking.
360 * Web:: HTTP, the web, and all that.
361 * getopt-long:: Command line handling.
362 * SRFI Support:: Support for various SRFIs.
363 * R6RS Support:: Modules defined by the R6RS.
364 * Pattern Matching:: Generic pattern matching constructs.
365 * Readline Support:: Module for using the readline library.
366 * Pretty Printing:: Nicely formatting Scheme objects for output.
367 * Formatted Output:: The @code{format} procedure.
368 * File Tree Walk:: Traversing the file system.
369 * Queues:: First-in first-out queuing.
370 * Streams:: Sequences of values.
371 * Buffered Input:: Ports made from a reader function.
372 * Expect:: Controlling interactive programs with Guile.
373 * sxml-match:: Pattern matching of SXML.
374 * The Scheme shell (scsh):: Using scsh interfaces in Guile.
375 * Curried Definitions:: Extended @code{define} syntax.
381 @include mod-getopt-long.texi
382 @include srfi-modules.texi
385 @include repl-modules.texi
386 @include misc-modules.texi
389 @c XXX: Would be nicer if it were close to the (sxml simple) documentation.
390 @include sxml-match.texi
393 @include curried.texi
395 @node Standard Library
396 @chapter Standard Library
399 @include standard-library.texi
404 @node Guile Implementation
405 @chapter Guile Implementation
407 At some point, after one has been programming in Scheme for some time,
408 another level of Scheme comes into view: its implementation. Knowledge
409 of how Scheme can be implemented turns out to be necessary to become
410 an expert hacker. As Peter Norvig notes in his retrospective on
411 PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of
412 Artificial Intelligence Programming}, an old but still useful text on
413 Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be
414 found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp
415 programmer eventually develops a good `efficiency model'.''
417 By this Norvig means that over time, the Lisp hacker eventually
418 develops an understanding of how much her code ``costs'' in terms of
421 This chapter describes Guile as an implementation of Scheme: its
422 history, how it represents and evaluates its data, and its compiler.
423 This knowledge can help you to make that step from being one who is
424 merely familiar with Scheme to being a real hacker.
427 * History:: A brief history of Guile.
428 * Data Representation:: How Guile represents Scheme data.
429 * A Virtual Machine for Guile:: How compiled procedures work.
430 * Compiling to the Virtual Machine:: Not as hard as you might think.
433 @include history.texi
434 @include data-rep.texi
436 @include compiler.texi
438 @node GNU Free Documentation License
439 @appendix GNU Free Documentation License
443 @include indices.texi
444 @include scheme-indices.texi