4 @setfilename guile.info
5 @settitle Guile Reference Manual
10 @c This file started life as a copy of guile-ref.texi, which I then
11 @c modified to reflect the organization described in
12 @c sources/jimb-org.texi.
16 @c Remember to use "subr" whereever appropriate.
17 @c Actually, use "primitive", not "subr." Why coin a new term?
18 @c FIXME: gotta change existing "subr" uses to "Primitive".
19 @c In my text for the Guile snarfer, I've used the term "subr" to denote
20 @c a C function made available to the Scheme world as a function. This
21 @c terminology is weird, but consistent with the function names and also
22 @c with Emacs Lisp, which I assume takes Maclisp's lead.
26 @c When adding a new function to the Guile manual, please document
27 @c it with @deffn as one of `primitive', `procedure', or `syntax'.
29 @c The following Guile primitives are not documented. We have a lot
32 @c arbiters.c: make-arbiter, try-arbiter, release-arbiter
33 @c async.c: async, async-mark, system-async, system-async-mark,
34 @c run-asyncs, noop, set-tick-rate, set-switch-rate,
35 @c unmask-signals, mask-signals
36 @c backtrace.c: backtrace, display-error, display-application,
38 @c chars.c: char-is-both?
39 @c debug.c: single-step, memoized?, unmemoize, memoized-environment,
40 @c procedure-name, procedure-source, procedure-environment,
41 @c local-eval, debug-object?, debug-hang
42 @c dynl.c: c-registered-modules, c-clear-registered-modules,
43 @c dynamic-link, dynamic-object?, dynamic-unlink, dynamic-func,
44 @c dynamic-call, dynamic-args-call
45 @c eval.c: procedure->syntax, procedure->macro, procedure->memoizing-macro,
46 @c macro-name, macro-transformer
47 @c fluids.c: make-fluid, fluid?, fluid-ref, fluid-set, with-fluids*
48 @c gc.c: map-free-list, unhash-name
49 @c kw.c: make-keyword-from-dash-symbol
50 @c net_db.c: sethost, setnet, setproto, setserv
51 @c print.c: current-pstate
52 @c procs.c: make-cclo, closure?, thunk?
53 @c read.c: read-hash-extend
54 @c readline.c: readline, add-history
55 @c srcprop.c: source-properties, set-source-properties!,
56 @c source-property, set-source-property!
57 @c stacks.c: make-stack, stack-ref, stack-length,
58 @c frame?, last-stack-frame, frame-number, frame-source,
59 @c frame-procedure, frame-arguments, frame-previous, frame-next,
60 @c frame-real?, frame-procedure?, frame-evaluating-args?,
62 @c struct.c: struct-vtable-tag
63 @c symbols.c: builtin-weak-bindings
65 @c threads.c: single-active-thread?, yield, call-with-new-thread,
66 @c make-condition-variable, wait-condition-variable,
67 @c signal-condition-variable
68 @c throw.c: lazy-catch, vector-set-length!
69 @c unif.c: uniform-vector-ref, uniform-array-set1!
70 @c variable.c: make-variable, make-undefined-variable, variable?,
71 @c variable-ref, variable-set!, builtin-variable, variable-bound?
72 @c weaks.c: make-weak-vector, weak-vector, list->weak-vector,
73 @c weak-vector? make-weak-key-hash-table,
74 @c make-weak-value-hash-table, make-doubly-weak-hash-table,
75 @c weak-key-hash-table?, weak-value-hash-table?,
76 @c doubly-weak-hash-table?
78 @c If you have worked with some of these concepts, implemented them,
79 @c or just happen to know what they do, please write up a little
80 @c explanation -- it would be a big help. Alternatively, if you
81 @c know of a great reason why some of these should *not* go in the
82 @c manual, please let me know.
84 @c The following functions are currently left undocumented for various reasons.
85 @c * should be documented in a section on debugging or Guile internals:
86 @c ports.c: pt-size, pt-member
87 @c eval.c: apply:nconc2last
91 @c Define indices that are used in the Guile Scheme part of the
92 @c reference manual to group stuff according to whether it is R5RS or a
103 @dircategory The Algorithmic Language Scheme
105 * Guile Reference: (guile). The Guile reference manual.
108 @setchapternewpage off
111 Guile Reference Manual
112 Copyright (C) 1996 Free Software Foundation @*
113 Copyright (C) 1997 Free Software Foundation @*
114 Copyright (C) 2000 Free Software Foundation @*
115 Copyright (C) 2001 Free Software Foundation
117 Permission is granted to make and distribute verbatim copies of
118 this manual provided the copyright notice and this permission notice
119 are preserved on all copies.
122 Permission is granted to process this file through TeX and print the
123 results, provided the printed document carries copying permission
124 notice identical to this one except for the removal of this paragraph
125 (this paragraph not being relevant to the printed manual).
128 Permission is granted to copy and distribute modified versions of this
129 manual under the conditions for verbatim copying, provided that the entire
130 resulting derived work is distributed under the terms of a permission
131 notice identical to this one.
133 Permission is granted to copy and distribute translations of this manual
134 into another language, under the above conditions for modified versions,
135 except that this permission notice may be stated in a translation approved
136 by the Free Software Foundation.
141 @comment The title is printed in a large font.
142 @title Guile Reference Manual
143 @subtitle $Id: guile.texi,v 1.6 2001-04-28 09:00:31 ossau Exp $
144 @subtitle For use with Guile @value{VERSION}
146 @author Cygnus Solution and Los Alamos National Laboratory
147 @author @email{rosalia@@cygnus.com}
150 @author Free Software Foundation and MIT AI Lab
151 @author @email{jimb@@red-bean.com}
154 @author @email{ghouston@@arglist.com}
157 @author @email{twp@@skepsis.com}
160 @author @email{neil@@ossau.uklinux.net}
161 @c The following two commands start the copyright page.
163 @vskip 0pt plus 1filll
164 @vskip 0pt plus 1filll
165 Copyright @copyright{} 1996 Free Software Foundation
167 Copyright @copyright{} 1997 Free Software Foundation
169 Copyright @copyright{} 2000 Free Software Foundation
171 Permission is granted to make and distribute verbatim copies of
172 this manual provided the copyright notice and this permission notice
173 are preserved on all copies.
175 Permission is granted to copy and distribute modified versions of this
176 manual under the conditions for verbatim copying, provided that the entire
177 resulting derived work is distributed under the terms of a permission
178 notice identical to this one.
180 Permission is granted to copy and distribute translations of this manual
181 into another language, under the above conditions for modified versions,
182 except that this permission notice may be stated in a translation approved
183 by Free Software Foundation.
190 @c Where to find Guile examples.
191 @set example-dir doc/examples
194 @node Top, Guile License, (dir), (dir)
195 @top The Guile Reference Manual
197 This reference manual documents Guile, GNU's Ubiquitous Intelligent
198 Language for Extensions. It describes how to use Guile in many useful
199 and interesting ways.
201 This Info file contains edition 1.0 of the reference manual,
202 corresponding to Guile version @value{VERSION}.
208 * Guile License:: Conditions for copying and using Guile.
209 * Manual Layout:: How to read the rest of this manual.
211 Part I: Introduction to Guile
213 * What is Guile?:: And what does it do?
214 * Whirlwind Tour:: An introductory whirlwind tour.
215 * Reporting Bugs:: Reporting bugs in Guile or this manual.
217 Part II: Guile Scheme
219 * Scheme Intro:: Introduction to Guile Scheme.
220 * Basic Ideas:: Basic ideas in Scheme.
221 * Data Types:: Data types for generic use.
222 * Procedures and Macros:: Procedures and macros.
223 * Utility Functions:: General utility functions.
224 * Binding Constructs:: Definitions and variable bindings.
225 * Control Mechanisms:: Controlling the flow of program execution.
226 * Input and Output:: Ports, reading and writing.
227 * Read/Load/Eval:: Reading and evaluating Scheme code.
228 * Memory Management:: Memory management and garbage collection.
229 * Objects:: Low level object orientation support.
230 * Modules:: Designing reusable code libraries.
231 * Scheduling:: Threads, mutexes, asyncs and dynamic roots.
232 * Options and Config:: Runtime options and configuration.
233 * Translation:: Support for translating other languages.
234 * Debugging:: Internal debugging interface.
235 * Deprecated:: Features that are planned to disappear.
236 * Further Reading:: Where to find out more about Scheme programming.
238 * Guile Extensions Index::
240 Part III: Guile Modules
242 * SLIB:: Using the SLIB Scheme library.
243 * POSIX:: POSIX system calls and networking.
244 * SRFI-13/14:: String library and character set library.
245 * Expect:: Controlling interactive programs with Guile.
246 * The Scheme shell (scsh)::
247 The SCSH compatibility module has been made an
248 add-on, so maybe it shouldn't be documented here
249 (though it is nice to have a link from here to the
250 Guile-scsh manual, if one exists).
253 Part IV: Guile Scripting
255 * Guile Scripting:: How to write Guile scripts.
256 * Command Line Handling:: Command line options and arguments.
258 Part V: Extending Applications Using Guile
260 * Libguile Intro:: Using Guile as an extension language.
261 * GH:: GH: a portable C to Scheme interface.
262 * Data Representation:: Data representation in Guile.
263 * Scheme Primitives:: Writing Scheme primitives in C.
264 * I/O Extensions:: Using and extending ports in C.
265 * Handling Errors:: How to handle errors in C code.
269 * Obtaining and Installing Guile::
270 * Debugger User Interface::
281 @include preface.texi
286 @unnumbered{Part I: Introduction to Guile}
291 @c programming in Scheme
294 @unnumbered{Part II: Guile Scheme}
297 @include scheme-intro.texi
298 @include scheme-ideas.texi
299 @include scheme-data.texi
300 @include scheme-procedures.texi
301 @include scheme-utility.texi
302 @include scheme-binding.texi
303 @include scheme-control.texi
304 @include scheme-io.texi
305 @include scheme-evaluation.texi
306 @include scheme-memory.texi
307 @include scheme-modules.texi
308 @include scheme-scheduling.texi
309 @c object orientation support here
310 @include scheme-options.texi
311 @include scheme-translation.texi
312 @include scheme-debug.texi
313 @include deprecated.texi
314 @include scheme-reading.texi
315 @include scheme-indices.texi
317 @c Unix system interface
320 @unnumbered{Part III: Guile Modules}
325 @include srfi-13-14.texi
330 @c Guile as an scripting language
333 @unnumbered{Part IV: Guile Scripting}
336 @include scripts.texi
337 @include script-getopt.texi
339 @c Guile as an extension language
342 @unnumbered{Part V: Extending Applications Using Guile}
347 @include data-rep.texi
353 @unnumbered{Appendices}
356 @include appendices.texi
364 @include indices.texi