Commit | Line | Data |
---|---|---|
38a93523 NJ |
1 | \input texinfo |
2 | @c -*-texinfo-*- | |
3 | @c %**start of header | |
4 | @setfilename guile.info | |
5 | @settitle Guile Reference Manual | |
370babab | 6 | @set guile |
9401323e | 7 | @set MANUAL_EDITION 1.1 |
38a93523 NJ |
8 | @c %**end of header |
9 | ||
2a946b44 | 10 | @c Notes |
370babab | 11 | @c |
2a946b44 NJ |
12 | @c We no longer use the category "primitive" to distinguish C-defined |
13 | @c Scheme procedures from those defined in Scheme. Instead, the | |
14 | @c reference manual now includes a C declaration as well as a Scheme | |
15 | @c declaration for each procedure that is available in both Scheme and | |
16 | @c C. | |
370babab | 17 | @c |
2a946b44 NJ |
18 | @c When adding a new reference entry to the Guile manual, please |
19 | @c document it with @deffn using one of the following categories: | |
20 | @c | |
21 | @c {Scheme Procedure} | |
22 | @c {Scheme Syntax} | |
23 | @c {C Function} | |
24 | @c {C Macro} | |
25 | @c | |
26 | @c If the entry is for a new primitive, it should have both a @deffn | |
27 | @c {Scheme Procedure} line and a @deffnx {C Function} line; see the | |
28 | @c manual source for plenty of existing examples of this. | |
29 | @c | |
30 | @c For {C Function} entries where the return type and all parameter | |
31 | @c types are SCM, we omit the SCMs. This is easier to read and also | |
32 | @c gets round the problem that Texinfo doesn't allow a @deftypefnx | |
33 | @c inside a @deffn. | |
38a93523 | 34 | @c |
370babab NJ |
35 | @c For a list of Guile primitives that are not yet incorporated into the |
36 | @c reference manual, see the file `new-docstrings.texi', which holds all | |
37 | @c the docstrings snarfed from the libguile C sources for primitives | |
38 | @c that are not in the reference manual. If you have worked with some | |
39 | @c of these concepts, implemented them, or just happen to know what they | |
40 | @c do, please write up a little explanation -- it would be a big help. | |
2a946b44 NJ |
41 | @c Alternatively, if you know of any reason why some of these should |
42 | @c *not* go in the manual, please let the mailing list | |
43 | @c <guile-devel@gnu.org> know. | |
38a93523 NJ |
44 | |
45 | @c Define indices that are used in the Guile Scheme part of the | |
46 | @c reference manual to group stuff according to whether it is R5RS or a | |
47 | @c Guile extension. | |
5c4b24e1 | 48 | @defcodeindex rn |
38a93523 NJ |
49 | @defcodeindex ge |
50 | ||
51 | @include version.texi | |
52 | ||
198586ed NJ |
53 | @c Macros for describing version information. I've initially defined |
54 | @c all of these to expand to nothing, but they could perhaps be made to | |
55 | @c expand to something like "New in Guile 45!" in future. | |
56 | ||
57 | @c vnew - indicates the Guile version in which item first appeared. | |
58 | @macro vnew{VERSION} | |
59 | @end macro | |
60 | ||
61 | @c vdeprecated - indicates that the item has been deprecated, and the | |
62 | @c Guile version in which the deprecation started. | |
63 | @macro vdeprecated{VERSION} | |
64 | @end macro | |
65 | ||
66 | @c vgone - a way of tracking items that are no longer here. In this | |
67 | @c case, VERSION is the last Guile version in which the item was present. | |
68 | @macro vgone{WHAT, VERSION} | |
69 | @end macro | |
70 | ||
71 | @c vchanged - indicates the Guile version in which item's behaviour | |
72 | @c significantly changed. | |
73 | @macro vchanged{VERSION} | |
74 | @end macro | |
75 | ||
76 | @c vnote - catchall for any additional notes. | |
77 | @macro vnote{NOTE} | |
78 | @end macro | |
79 | ||
38a93523 NJ |
80 | @c @iftex |
81 | @c @cropmarks | |
82 | @c @end iftex | |
83 | ||
84 | @dircategory The Algorithmic Language Scheme | |
85 | @direntry | |
c16da59f | 86 | * Guile Reference: (guile). The Guile reference manual. |
38a93523 NJ |
87 | @end direntry |
88 | ||
89 | @setchapternewpage off | |
90 | ||
91 | @ifinfo | |
92 | Guile Reference Manual | |
93 | Copyright (C) 1996 Free Software Foundation @* | |
94 | Copyright (C) 1997 Free Software Foundation @* | |
95 | Copyright (C) 2000 Free Software Foundation @* | |
96 | Copyright (C) 2001 Free Software Foundation | |
97 | ||
98 | Permission is granted to make and distribute verbatim copies of | |
99 | this manual provided the copyright notice and this permission notice | |
100 | are preserved on all copies. | |
101 | ||
102 | @ignore | |
103 | Permission is granted to process this file through TeX and print the | |
104 | results, provided the printed document carries copying permission | |
105 | notice identical to this one except for the removal of this paragraph | |
106 | (this paragraph not being relevant to the printed manual). | |
107 | @end ignore | |
108 | ||
109 | Permission is granted to copy and distribute modified versions of this | |
110 | manual under the conditions for verbatim copying, provided that the entire | |
111 | resulting derived work is distributed under the terms of a permission | |
112 | notice identical to this one. | |
113 | ||
114 | Permission is granted to copy and distribute translations of this manual | |
115 | into another language, under the above conditions for modified versions, | |
116 | except that this permission notice may be stated in a translation approved | |
117 | by the Free Software Foundation. | |
118 | @end ifinfo | |
119 | ||
120 | @titlepage | |
121 | @sp 10 | |
122 | @comment The title is printed in a large font. | |
123 | @title Guile Reference Manual | |
801892e7 | 124 | @subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $ |
38a93523 | 125 | @subtitle For use with Guile @value{VERSION} |
b45898ca NJ |
126 | |
127 | @c AUTHORS | |
128 | ||
129 | @c The Guile reference and tutorial manuals were written and edited | |
130 | @c largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the | |
131 | @c original tutorial on Guile's data representation and the C API for | |
132 | @c accessing Guile objects. | |
133 | ||
134 | @c Significant portions were contributed by Gary Houston (contributions | |
85a9b4ed | 135 | @c to POSIX system calls and networking, expect, I/O internals and |
b45898ca NJ |
136 | @c extensions, slib installation, error handling) and Tim Pierce |
137 | @c (sections on script interpreter triggers, alists, function tracing). | |
138 | ||
139 | @c Tom Lord contributed a great deal of material with early Guile | |
140 | @c snapshots; although most of this text has been rewritten, all of it | |
141 | @c was important, and some of the structure remains. | |
142 | ||
143 | @c Aubrey Jaffer wrote the SCM Scheme implementation and manual upon | |
144 | @c which the Guile program and manual are based. Some portions of the | |
145 | @c SCM and SLIB manuals have been included here verbatim. | |
146 | ||
147 | @c Since Guile 1.4, Neil Jerram has been maintaining and improving the | |
148 | @c reference manual. Among other contributions, he wrote the Basic | |
149 | @c Ideas chapter, developed the tools for keeping the manual in sync | |
150 | @c with snarfed libguile docstrings, and reorganized the structure so as | |
151 | @c to accommodate docstrings for all Guile's primitives. | |
152 | ||
153 | @c Martin Grabmueller has made substantial contributions throughout the | |
154 | @c reference manual in preparation for the Guile 1.6 release, including | |
155 | @c filling out a lot of the documentation of Scheme data types, control | |
156 | @c mechanisms and procedures. In addition, he wrote the documentation | |
157 | @c for Guile's SRFI modules and modules associated with the Guile REPL. | |
158 | ||
159 | @author Mark Galassi | |
160 | @author Cygnus Solution and Los Alamos National Laboratory | |
161 | @author @email{rosalia@@cygnus.com} | |
162 | @author | |
163 | @author Jim Blandy | |
164 | @author Free Software Foundation and MIT AI Lab | |
165 | @author @email{jimb@@red-bean.com} | |
166 | @author | |
167 | @author Gary Houston | |
168 | @author @email{ghouston@@arglist.com} | |
169 | @author | |
170 | @author Tim Pierce | |
171 | @author @email{twp@@skepsis.com} | |
172 | @author | |
173 | @author Neil Jerram | |
174 | @author @email{neil@@ossau.uklinux.net} | |
175 | @author | |
176 | @author Martin Grabmueller | |
177 | @author @email{mgrabmue@@cs.tu-berlin.de} | |
370babab | 178 | |
38a93523 NJ |
179 | @c The following two commands start the copyright page. |
180 | @page | |
181 | @vskip 0pt plus 1filll | |
182 | @vskip 0pt plus 1filll | |
183 | Copyright @copyright{} 1996 Free Software Foundation | |
184 | ||
185 | Copyright @copyright{} 1997 Free Software Foundation | |
186 | ||
187 | Copyright @copyright{} 2000 Free Software Foundation | |
188 | ||
189 | Permission is granted to make and distribute verbatim copies of | |
190 | this manual provided the copyright notice and this permission notice | |
191 | are preserved on all copies. | |
192 | ||
193 | Permission is granted to copy and distribute modified versions of this | |
194 | manual under the conditions for verbatim copying, provided that the entire | |
195 | resulting derived work is distributed under the terms of a permission | |
196 | notice identical to this one. | |
197 | ||
198 | Permission is granted to copy and distribute translations of this manual | |
199 | into another language, under the above conditions for modified versions, | |
200 | except that this permission notice may be stated in a translation approved | |
201 | by Free Software Foundation. | |
202 | @end titlepage | |
203 | ||
204 | @c @smallbook | |
205 | @finalout | |
206 | @headings double | |
207 | ||
208 | @c Where to find Guile examples. | |
209 | @set example-dir doc/examples | |
210 | ||
801892e7 | 211 | @ifnottex |
38a93523 NJ |
212 | @node Top, Guile License, (dir), (dir) |
213 | @top The Guile Reference Manual | |
214 | ||
215 | This reference manual documents Guile, GNU's Ubiquitous Intelligent | |
216 | Language for Extensions. It describes how to use Guile in many useful | |
217 | and interesting ways. | |
218 | ||
9401323e NJ |
219 | This Info file contains edition @value{MANUAL_EDITION} of the reference |
220 | manual, corresponding to Guile version @value{VERSION}. | |
801892e7 | 221 | @end ifnottex |
38a93523 NJ |
222 | |
223 | @menu | |
224 | Preface | |
225 | ||
226 | * Guile License:: Conditions for copying and using Guile. | |
227 | * Manual Layout:: How to read the rest of this manual. | |
370babab | 228 | * Manual Conventions:: Conventional terminology. |
38a93523 NJ |
229 | |
230 | Part I: Introduction to Guile | |
231 | ||
232 | * What is Guile?:: And what does it do? | |
73ede592 | 233 | * Whirlwind Tour:: An introductory whirlwind tour. |
9401323e | 234 | * Obtaining and Installing Guile:: |
38a93523 NJ |
235 | * Reporting Bugs:: Reporting bugs in Guile or this manual. |
236 | ||
9401323e | 237 | Part II: Programming with Guile |
38a93523 | 238 | |
85a9b4ed | 239 | * Programming Intro:: Introduction to this part. |
226297eb | 240 | * Programming Overview:: An overview of Guile programming. |
38a93523 NJ |
241 | * Scheme Intro:: Introduction to Guile Scheme. |
242 | * Basic Ideas:: Basic ideas in Scheme. | |
9401323e NJ |
243 | * Guile Scripting:: How to write Guile scripts. |
244 | * Command Line Handling:: Command line options and arguments. | |
245 | * Libguile Intro:: Using Guile as an extension language. | |
a7a7bb95 | 246 | * Guile API:: Overview of the Guile API. |
9401323e NJ |
247 | * Data Representation:: Data representation in Guile. |
248 | * GH:: The deprecated GH interface. | |
249 | * Debugger User Interface:: | |
dc81cfeb | 250 | * Autoconf Support:: Guile-specific configure.in macros. |
73ede592 | 251 | * Miscellaneous Tools:: Snarfing, linting, etc. |
9401323e NJ |
252 | * Further Reading:: Where to find out more about Scheme programming. |
253 | ||
254 | Part III: Guile API Reference | |
255 | ||
256 | * Reference Intro:: Introduction to the Guile API reference. | |
4c731ece NJ |
257 | * Simple Data Types:: Numbers, strings, booleans and so on. |
258 | * Compound Data Types:: Data types for holding other data. | |
38a93523 NJ |
259 | * Procedures and Macros:: Procedures and macros. |
260 | * Utility Functions:: General utility functions. | |
261 | * Binding Constructs:: Definitions and variable bindings. | |
262 | * Control Mechanisms:: Controlling the flow of program execution. | |
263 | * Input and Output:: Ports, reading and writing. | |
264 | * Read/Load/Eval:: Reading and evaluating Scheme code. | |
265 | * Memory Management:: Memory management and garbage collection. | |
266 | * Objects:: Low level object orientation support. | |
267 | * Modules:: Designing reusable code libraries. | |
268 | * Scheduling:: Threads, mutexes, asyncs and dynamic roots. | |
269 | * Options and Config:: Runtime options and configuration. | |
270 | * Translation:: Support for translating other languages. | |
271 | * Debugging:: Internal debugging interface. | |
272 | * Deprecated:: Features that are planned to disappear. | |
38a93523 | 273 | |
9401323e | 274 | Part IV: Guile Modules |
38a93523 NJ |
275 | |
276 | * SLIB:: Using the SLIB Scheme library. | |
277 | * POSIX:: POSIX system calls and networking. | |
fc8529c7 | 278 | * SRFI Support:: Support for various SRFIs. |
fc8529c7 MG |
279 | * Readline Support:: Module for using the readline library. |
280 | * Value History:: Maintaining a value history in the REPL. | |
c2537425 MG |
281 | * Pretty Printing:: Nicely formatting Scheme objects for output. |
282 | * Formatted Output:: The @code{format} procedure. | |
2a946b44 | 283 | * Rx Regexps:: The Rx regular expression library. |
38a93523 | 284 | * Expect:: Controlling interactive programs with Guile. |
a42b5e5b | 285 | * The Scheme shell (scsh):: Using scsh interfaces in Guile. |
38a93523 NJ |
286 | |
287 | Indices | |
288 | ||
289 | * Concept Index:: | |
290 | * Procedure Index:: | |
291 | * Variable Index:: | |
292 | * Type Index:: | |
255ea784 NJ |
293 | * R5RS Index:: |
294 | * Guile Extensions Index:: | |
38a93523 NJ |
295 | |
296 | @end menu | |
297 | ||
298 | @include preface.texi | |
299 | ||
38a93523 NJ |
300 | @iftex |
301 | @page | |
302 | @unnumbered{Part I: Introduction to Guile} | |
303 | @end iftex | |
304 | ||
305 | @include intro.texi | |
306 | ||
38a93523 | 307 | @page |
9401323e NJ |
308 | @node Programming Intro |
309 | @unnumbered Part II: Programming with Guile | |
310 | ||
311 | In this part of the manual, we aim to present a wide ranging picture of | |
312 | what it means to program using Guile, to provide guidance, practical | |
313 | guidelines and tips for @emph{how} to program in Guile, and to document | |
314 | the tools that are available to help you with your programming. For | |
315 | detailed reference information on the variables, functions etc. that | |
316 | make up Guile's application programming interface (API), please refer to | |
a7a7bb95 | 317 | Part III (@pxref{Reference Intro,,Part III --- Guile API Reference}). |
38a93523 | 318 | |
9401323e NJ |
319 | We begin in the first chapter of this part by looking at the programming |
320 | options available. | |
321 | ||
322 | @include program.texi | |
38a93523 NJ |
323 | @include scheme-intro.texi |
324 | @include scheme-ideas.texi | |
9401323e NJ |
325 | @include scripts.texi |
326 | @include script-getopt.texi | |
327 | @include extend.texi | |
328 | @include scm.texi | |
329 | @include data-rep.texi | |
330 | @include gh.texi | |
331 | @include debugging.texi | |
dc81cfeb | 332 | @include autoconf.texi |
73ede592 | 333 | @include tools.texi |
9401323e NJ |
334 | @include scheme-reading.texi |
335 | ||
336 | @page | |
337 | @node Reference Intro | |
338 | @unnumbered Part III: Guile API Reference | |
339 | ||
a7a7bb95 NJ |
340 | Guile provides an application programming interface (@dfn{API}) to |
341 | developers in two core languages: Scheme and C. This part of the manual | |
342 | contains reference documentation for all of the functionality that is | |
343 | available through both Scheme and C interfaces. | |
344 | ||
38a93523 | 345 | @include scheme-data.texi |
4c731ece | 346 | @include scheme-compound.texi |
38a93523 NJ |
347 | @include scheme-procedures.texi |
348 | @include scheme-utility.texi | |
349 | @include scheme-binding.texi | |
350 | @include scheme-control.texi | |
351 | @include scheme-io.texi | |
352 | @include scheme-evaluation.texi | |
353 | @include scheme-memory.texi | |
354 | @include scheme-modules.texi | |
355 | @include scheme-scheduling.texi | |
356 | @c object orientation support here | |
357 | @include scheme-options.texi | |
358 | @include scheme-translation.texi | |
359 | @include scheme-debug.texi | |
360 | @include deprecated.texi | |
38a93523 | 361 | |
38a93523 NJ |
362 | @iftex |
363 | @page | |
9401323e | 364 | @unnumbered{Part IV: Guile Modules} |
38a93523 NJ |
365 | @end iftex |
366 | ||
367 | @include slib.texi | |
368 | @include posix.texi | |
fc8529c7 | 369 | @include srfi-modules.texi |
fc8529c7 | 370 | @include repl-modules.texi |
c2537425 | 371 | @include misc-modules.texi |
38a93523 NJ |
372 | @include expect.texi |
373 | @include scsh.texi | |
38a93523 | 374 | |
38a93523 NJ |
375 | @iftex |
376 | @page | |
377 | @unnumbered{Indices} | |
378 | @end iftex | |
379 | ||
380 | @include indices.texi | |
9401323e | 381 | @include scheme-indices.texi |
38a93523 NJ |
382 | |
383 | @contents | |
384 | ||
385 | @bye |