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 |
c73543af | 7 | @set MANUAL-EDITION 1.1 |
38a93523 | 8 | @c %**end of header |
d3830c6b KR |
9 | @include version.texi |
10 | ||
11 | @copying | |
12 | This reference manual documents Guile, GNU's Ubiquitous Intelligent | |
3229f68b | 13 | Language for Extensions. This is edition @value{MANUAL-EDITION} |
d3830c6b KR |
14 | corresponding to Guile @value{VERSION}. |
15 | ||
c6ae9c77 | 16 | Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 Free Software |
5ad1686a | 17 | Foundation. |
d3830c6b | 18 | |
3229f68b MV |
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". | |
d3830c6b KR |
26 | @end copying |
27 | ||
38a93523 | 28 | |
2a946b44 | 29 | @c Notes |
370babab | 30 | @c |
2a946b44 NJ |
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 | |
35 | @c C. | |
370babab | 36 | @c |
2a946b44 NJ |
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: | |
39 | @c | |
40 | @c {Scheme Procedure} | |
41 | @c {Scheme Syntax} | |
42 | @c {C Function} | |
43 | @c {C Macro} | |
44 | @c | |
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. | |
48 | @c | |
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 | |
52 | @c inside a @deffn. | |
38a93523 | 53 | @c |
370babab NJ |
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. | |
2a946b44 NJ |
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. | |
38a93523 NJ |
63 | |
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 | |
66 | @c Guile extension. | |
5c4b24e1 | 67 | @defcodeindex rn |
38a93523 | 68 | |
0624ce33 NJ |
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. | |
198586ed NJ |
72 | @macro vnew{VERSION} |
73 | @end macro | |
74 | ||
20685804 | 75 | |
27281a53 KR |
76 | @c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works |
77 | @c inside or outside $ $. | |
78 | @tex | |
79 | \gdef\cross{\ifmmode\times\else$\times$\fi} | |
80 | @end tex | |
81 | @ifnottex | |
82 | @macro cross | |
83 | x | |
84 | @end macro | |
85 | @end ifnottex | |
86 | ||
d6f53bd5 KR |
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. | |
89 | @iftex | |
90 | @macro m {T,N} | |
91 | @tex$\T\$@end tex | |
92 | @end macro | |
93 | @end iftex | |
94 | @ifnottex | |
95 | @macro m {T,N} | |
96 | @math{\N\} | |
97 | @end macro | |
98 | @end ifnottex | |
99 | ||
7ac44f03 KR |
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. | |
20685804 | 104 | @ifinfo |
7ac44f03 | 105 | @alias nicode=asis |
20685804 KR |
106 | @end ifinfo |
107 | @ifnotinfo | |
7ac44f03 | 108 | @alias nicode=code |
20685804 KR |
109 | @end ifnotinfo |
110 | ||
111 | ||
38a93523 NJ |
112 | @c @iftex |
113 | @c @cropmarks | |
114 | @c @end iftex | |
115 | ||
116 | @dircategory The Algorithmic Language Scheme | |
117 | @direntry | |
c16da59f | 118 | * Guile Reference: (guile). The Guile reference manual. |
38a93523 NJ |
119 | @end direntry |
120 | ||
3229f68b | 121 | @setchapternewpage odd |
38a93523 | 122 | |
38a93523 NJ |
123 | @titlepage |
124 | @sp 10 | |
125 | @comment The title is printed in a large font. | |
126 | @title Guile Reference Manual | |
c73543af | 127 | @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION} |
7ac44f03 | 128 | @c @subtitle $Id: guile.texi,v 1.32 2004-07-24 00:45:02 kryde Exp $ |
391b4ae0 MV |
129 | |
130 | @c See preface.texi for the list of authors | |
131 | @author The Guile Developers | |
370babab | 132 | |
38a93523 NJ |
133 | @c The following two commands start the copyright page. |
134 | @page | |
135 | @vskip 0pt plus 1filll | |
136 | @vskip 0pt plus 1filll | |
d3830c6b | 137 | @insertcopying |
38a93523 NJ |
138 | @end titlepage |
139 | ||
140 | @c @smallbook | |
141 | @finalout | |
142 | @headings double | |
143 | ||
144 | @c Where to find Guile examples. | |
145 | @set example-dir doc/examples | |
146 | ||
801892e7 | 147 | @ifnottex |
3229f68b | 148 | @node Top, Preface, (dir), (dir) |
38a93523 NJ |
149 | @top The Guile Reference Manual |
150 | ||
d3830c6b KR |
151 | @insertcopying |
152 | @sp 1 | |
801892e7 | 153 | @end ifnottex |
38a93523 NJ |
154 | |
155 | @menu | |
9401323e | 156 | |
3229f68b MV |
157 | * Preface:: |
158 | * Introduction to Guile:: | |
9401323e | 159 | |
3229f68b MV |
160 | * Programming in Scheme:: |
161 | * Programming in C:: | |
38a93523 | 162 | |
3229f68b | 163 | * API Reference:: |
38a93523 | 164 | |
3229f68b | 165 | * Guile Modules:: |
38a93523 | 166 | |
c6ae9c77 MV |
167 | Appendices |
168 | ||
3229f68b | 169 | * Data Representation:: All the details. |
c6ae9c77 MV |
170 | * GNU Free Documentation License:: The license of this manual. |
171 | ||
38a93523 NJ |
172 | Indices |
173 | ||
174 | * Concept Index:: | |
175 | * Procedure Index:: | |
176 | * Variable Index:: | |
177 | * Type Index:: | |
255ea784 | 178 | * R5RS Index:: |
38a93523 NJ |
179 | |
180 | @end menu | |
181 | ||
05c4ffe1 KR |
182 | @contents |
183 | ||
38a93523 NJ |
184 | @include preface.texi |
185 | ||
38a93523 NJ |
186 | @include intro.texi |
187 | ||
3229f68b MV |
188 | @node Programming in Scheme |
189 | @chapter Programming in Scheme | |
9401323e | 190 | |
ce9d0562 NJ |
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. | |
38a93523 | 196 | |
ce9d0562 NJ |
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 | |
200 | web. | |
201 | ||
3229f68b MV |
202 | For detailed reference information on the variables, functions |
203 | etc. that make up Guile's application programming interface (API), | |
204 | @xref{API Reference}. | |
205 | ||
206 | @menu | |
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. | |
212 | @end menu | |
9401323e | 213 | |
3229f68b | 214 | @include scheme-ideas.texi |
38a93523 | 215 | @include scheme-intro.texi |
9401323e | 216 | @include scripts.texi |
9401323e NJ |
217 | @include debugging.texi |
218 | @include scheme-reading.texi | |
219 | ||
3229f68b MV |
220 | @node Programming in C |
221 | @chapter Programming in C | |
222 | ||
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. | |
228 | ||
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}. | |
232 | ||
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. | |
237 | ||
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. | |
243 | ||
244 | For detailed reference information on the variables, functions | |
245 | etc. that make up Guile's application programming interface (API), | |
246 | @xref{API Reference}. | |
247 | ||
248 | @menu | |
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. | |
255 | @end menu | |
256 | ||
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 | |
ce9d0562 | 262 | @include program.texi |
ce9d0562 | 263 | |
3229f68b MV |
264 | @node API Reference |
265 | @chapter API Reference | |
9401323e | 266 | |
a7a7bb95 NJ |
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. | |
271 | ||
3229f68b MV |
272 | @menu |
273 | * API Overview:: Overview of the Guile API. | |
98f445f4 | 274 | * The SCM Type:: The fundamental data type for C code. |
3229f68b MV |
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. | |
295 | @end menu | |
296 | ||
ce9d0562 | 297 | @include scm.texi |
3229f68b MV |
298 | @include scheme-scm.texi |
299 | @include ref-init.texi | |
300 | @include scheme-snarf.texi | |
38a93523 | 301 | @include scheme-data.texi |
4c731ece | 302 | @include scheme-compound.texi |
3229f68b | 303 | @include scheme-smobs.texi |
38a93523 NJ |
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 | |
3229f68b | 318 | @include gh.texi |
38a93523 | 319 | |
3229f68b MV |
320 | @node Guile Modules |
321 | @chapter Guile Modules | |
322 | ||
323 | @menu | |
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. | |
337 | @end menu | |
38a93523 NJ |
338 | |
339 | @include slib.texi | |
340 | @include posix.texi | |
3229f68b | 341 | @include mod-getopt-long.texi |
fc8529c7 | 342 | @include srfi-modules.texi |
fc8529c7 | 343 | @include repl-modules.texi |
c2537425 | 344 | @include misc-modules.texi |
38a93523 NJ |
345 | @include expect.texi |
346 | @include scsh.texi | |
38a93523 | 347 | |
3229f68b | 348 | @include data-rep.texi |
c6ae9c77 MV |
349 | @include fdl.texi |
350 | ||
38a93523 NJ |
351 | @iftex |
352 | @page | |
353 | @unnumbered{Indices} | |
354 | @end iftex | |
355 | ||
356 | @include indices.texi | |
9401323e | 357 | @include scheme-indices.texi |
38a93523 | 358 | |
38a93523 | 359 | @bye |