Commit | Line | Data |
---|---|---|
38a93523 NJ |
1 | \input texinfo |
2 | @c -*-texinfo-*- | |
3 | @c %**start of header | |
4 | @setfilename guile.info | |
9813088c | 5 | @documentencoding UTF-8 |
38a93523 | 6 | @settitle Guile Reference Manual |
370babab | 7 | @set guile |
a7c5a2e5 | 8 | @set MANUAL-REVISION 1 |
38a93523 | 9 | @c %**end of header |
d3830c6b | 10 | @include version.texi |
22b5f518 | 11 | @include effective-version.texi |
d3830c6b KR |
12 | |
13 | @copying | |
a7c5a2e5 | 14 | This manual documents Guile version @value{VERSION}. |
d3830c6b | 15 | |
644350c8 | 16 | Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009, |
f974224d | 17 | 2010, 2011, 2012, 2013, 2014 Free Software Foundation. |
d3830c6b | 18 | |
3229f68b | 19 | Permission is granted to copy, distribute and/or modify this document |
31d328de | 20 | under the terms of the GNU Free Documentation License, Version 1.3 or |
d9241a37 LC |
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.'' | |
d3830c6b KR |
25 | @end copying |
26 | ||
38a93523 | 27 | |
2a946b44 | 28 | @c Notes |
370babab | 29 | @c |
2a946b44 NJ |
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 | |
34 | @c C. | |
370babab | 35 | @c |
2a946b44 NJ |
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: | |
38 | @c | |
39 | @c {Scheme Procedure} | |
40 | @c {Scheme Syntax} | |
41 | @c {C Function} | |
42 | @c {C Macro} | |
43 | @c | |
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. | |
47 | @c | |
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 | |
51 | @c inside a @deffn. | |
38a93523 | 52 | @c |
370babab NJ |
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. | |
2a946b44 NJ |
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. | |
38a93523 NJ |
62 | |
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 | |
65 | @c Guile extension. | |
5c4b24e1 | 66 | @defcodeindex rn |
38a93523 | 67 | |
0624ce33 NJ |
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. | |
198586ed NJ |
71 | @macro vnew{VERSION} |
72 | @end macro | |
73 | ||
20685804 | 74 | |
17bf4bfa KR |
75 | @c The following, @le{} and @ge{}, are standard tex directives, given |
76 | @c definitions for use in non-tex. | |
77 | @c | |
78 | @ifnottex | |
79 | @macro ge | |
80 | >= | |
81 | @end macro | |
82 | @macro le | |
83 | <= | |
84 | @end macro | |
85 | @end ifnottex | |
86 | ||
27281a53 KR |
87 | @c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works |
88 | @c inside or outside $ $. | |
89 | @tex | |
90 | \gdef\cross{\ifmmode\times\else$\times$\fi} | |
91 | @end tex | |
92 | @ifnottex | |
93 | @macro cross | |
94 | x | |
95 | @end macro | |
96 | @end ifnottex | |
97 | ||
d6f53bd5 KR |
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. | |
100 | @iftex | |
101 | @macro m {T,N} | |
102 | @tex$\T\$@end tex | |
103 | @end macro | |
104 | @end iftex | |
105 | @ifnottex | |
106 | @macro m {T,N} | |
107 | @math{\N\} | |
108 | @end macro | |
109 | @end ifnottex | |
110 | ||
7ac44f03 KR |
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. | |
20685804 | 115 | @ifinfo |
7ac44f03 | 116 | @alias nicode=asis |
20685804 KR |
117 | @end ifinfo |
118 | @ifnotinfo | |
7ac44f03 | 119 | @alias nicode=code |
20685804 KR |
120 | @end ifnotinfo |
121 | ||
122 | ||
38a93523 NJ |
123 | @c @iftex |
124 | @c @cropmarks | |
125 | @c @end iftex | |
126 | ||
127 | @dircategory The Algorithmic Language Scheme | |
128 | @direntry | |
c16da59f | 129 | * Guile Reference: (guile). The Guile reference manual. |
38a93523 NJ |
130 | @end direntry |
131 | ||
3229f68b | 132 | @setchapternewpage odd |
38a93523 | 133 | |
38a93523 NJ |
134 | @titlepage |
135 | @sp 10 | |
136 | @comment The title is printed in a large font. | |
137 | @title Guile Reference Manual | |
a7c5a2e5 | 138 | @subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION} |
24dbb5ed | 139 | @c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $ |
391b4ae0 MV |
140 | |
141 | @c See preface.texi for the list of authors | |
142 | @author The Guile Developers | |
370babab | 143 | |
38a93523 NJ |
144 | @c The following two commands start the copyright page. |
145 | @page | |
146 | @vskip 0pt plus 1filll | |
147 | @vskip 0pt plus 1filll | |
d3830c6b | 148 | @insertcopying |
38a93523 NJ |
149 | @end titlepage |
150 | ||
151 | @c @smallbook | |
152 | @finalout | |
153 | @headings double | |
154 | ||
155 | @c Where to find Guile examples. | |
156 | @set example-dir doc/examples | |
157 | ||
801892e7 | 158 | @ifnottex |
3229f68b | 159 | @node Top, Preface, (dir), (dir) |
38a93523 NJ |
160 | @top The Guile Reference Manual |
161 | ||
d3830c6b KR |
162 | @insertcopying |
163 | @sp 1 | |
801892e7 | 164 | @end ifnottex |
38a93523 NJ |
165 | |
166 | @menu | |
9401323e | 167 | |
3229f68b | 168 | * Preface:: |
3d9af0c9 | 169 | * Introduction:: |
9401323e | 170 | |
45a272c5 | 171 | * Hello Guile!:: |
d665f75f NJ |
172 | * Hello Scheme!:: |
173 | ||
3229f68b MV |
174 | * Programming in Scheme:: |
175 | * Programming in C:: | |
38a93523 | 176 | |
3229f68b | 177 | * API Reference:: |
38a93523 | 178 | |
3229f68b | 179 | * Guile Modules:: |
38a93523 | 180 | |
eb12b401 NJ |
181 | * GOOPS:: |
182 | ||
090d51ed | 183 | * Guile Implementation:: |
8680d53b | 184 | |
c6ae9c77 MV |
185 | Appendices |
186 | ||
187 | * GNU Free Documentation License:: The license of this manual. | |
188 | ||
38a93523 NJ |
189 | Indices |
190 | ||
191 | * Concept Index:: | |
192 | * Procedure Index:: | |
193 | * Variable Index:: | |
194 | * Type Index:: | |
255ea784 | 195 | * R5RS Index:: |
38a93523 NJ |
196 | |
197 | @end menu | |
198 | ||
05c4ffe1 KR |
199 | @contents |
200 | ||
38a93523 NJ |
201 | @include preface.texi |
202 | ||
38a93523 NJ |
203 | @include intro.texi |
204 | ||
45a272c5 | 205 | @include tour.texi |
45a272c5 | 206 | |
d665f75f | 207 | @include scheme-ideas.texi |
d665f75f NJ |
208 | @include scheme-reading.texi |
209 | ||
3229f68b MV |
210 | @node Programming in Scheme |
211 | @chapter Programming in Scheme | |
9401323e | 212 | |
1d84577c NJ |
213 | Guile's core language is Scheme, and a lot can be achieved simply by using Guile |
214 | to write and run Scheme programs --- as opposed to having to dive into C code. | |
215 | In this part of the manual, we explain how to use Guile in this mode, and | |
216 | describe the tools that Guile provides to help you with script writing, | |
94906b75 | 217 | debugging, and packaging your programs for distribution. |
ce9d0562 | 218 | |
94906b75 MH |
219 | For detailed reference information on the variables, functions, and so |
220 | on that make up Guile's application programming interface (API), see | |
221 | @ref{API Reference}. | |
3229f68b MV |
222 | |
223 | @menu | |
3229f68b | 224 | * Guile Scheme:: Guile's implementation of Scheme. |
94906b75 | 225 | * Invoking Guile:: Selecting optional features when starting Guile. |
3229f68b | 226 | * Guile Scripting:: How to write Guile scripts. |
46f7666d NJ |
227 | * Using Guile Interactively:: Guile's REPL features. |
228 | * Using Guile in Emacs:: Guile and Emacs. | |
715146aa | 229 | * Using Guile Tools:: A guild of scheming wizards. |
24cc7832 | 230 | * Installing Site Packages:: Installing Scheme code. |
3229f68b | 231 | @end menu |
9401323e | 232 | |
38a93523 | 233 | @include scheme-intro.texi |
94906b75 | 234 | @include guile-invoke.texi |
07d83abe | 235 | @include scheme-scripts.texi |
46f7666d | 236 | @include scheme-using.texi |
9401323e | 237 | |
3229f68b MV |
238 | @node Programming in C |
239 | @chapter Programming in C | |
240 | ||
241 | This part of the manual explains the general concepts that you need to | |
242 | understand when interfacing to Guile from C. You will learn about how | |
243 | the latent typing of Scheme is embedded into the static typing of C, how | |
244 | the garbage collection of Guile is made available to C code, and how | |
245 | continuations influence the control flow in a C program. | |
246 | ||
247 | This knowledge should make it straightforward to add new functions to | |
248 | Guile that can be called from Scheme. Adding new data types is also | |
249 | possible and is done by defining @dfn{smobs}. | |
250 | ||
251 | The @ref{Programming Overview} section of this part contains general | |
252 | musings and guidelines about programming with Guile. It explores | |
8c3fa3e5 | 253 | different ways to design a program around Guile, or how to embed Guile |
3229f68b MV |
254 | into existing programs. |
255 | ||
0f7e6c56 AW |
256 | For a pedagogical yet detailed explanation of how the data representation of |
257 | Guile is implemented, @xref{Data Representation}. You don't need to know the | |
258 | details given there to use Guile from C, but they are useful when you want to | |
259 | modify Guile itself or when you are just curious about how it is all done. | |
3229f68b MV |
260 | |
261 | For detailed reference information on the variables, functions | |
262 | etc. that make up Guile's application programming interface (API), | |
263 | @xref{API Reference}. | |
264 | ||
265 | @menu | |
d32df132 | 266 | * Parallel Installations:: Finding the right Guile. |
3229f68b MV |
267 | * Linking Programs With Guile:: More precisely, with the libguile library. |
268 | * Linking Guile with Libraries:: To extend Guile itself. | |
269 | * General Libguile Concepts:: General concepts for using libguile. | |
270 | * Defining New Types (Smobs):: Adding new types to Guile. | |
271 | * Function Snarfing:: A way to define new functions. | |
272 | * Programming Overview:: An overview of Guile programming. | |
d32df132 | 273 | * Autoconf Support:: Putting m4 to good use. |
3229f68b MV |
274 | @end menu |
275 | ||
d32df132 | 276 | @include libguile-parallel.texi |
3229f68b MV |
277 | @include libguile-linking.texi |
278 | @include libguile-extensions.texi | |
279 | @include libguile-concepts.texi | |
280 | @include libguile-smobs.texi | |
281 | @include libguile-snarf.texi | |
237be238 | 282 | @include libguile-program.texi |
d32df132 AW |
283 | @include libguile-autoconf.texi |
284 | ||
ce9d0562 | 285 | |
3229f68b MV |
286 | @node API Reference |
287 | @chapter API Reference | |
9401323e | 288 | |
a7a7bb95 NJ |
289 | Guile provides an application programming interface (@dfn{API}) to |
290 | developers in two core languages: Scheme and C. This part of the manual | |
291 | contains reference documentation for all of the functionality that is | |
292 | available through both Scheme and C interfaces. | |
293 | ||
3229f68b MV |
294 | @menu |
295 | * API Overview:: Overview of the Guile API. | |
1435c7dc | 296 | * Deprecation:: Obsolete back-compatible APIs. |
98f445f4 | 297 | * The SCM Type:: The fundamental data type for C code. |
3229f68b MV |
298 | * Initialization:: Initializing Guile. |
299 | * Snarfing Macros:: Macros for snarfing initialization actions. | |
300 | * Simple Data Types:: Numbers, strings, booleans and so on. | |
301 | * Compound Data Types:: Data types for holding other data. | |
302 | * Smobs:: Defining new data types in C. | |
e4955559 AW |
303 | * Procedures:: Procedures. |
304 | * Macros:: Extending the syntax of Scheme. | |
3229f68b MV |
305 | * Utility Functions:: General utility functions. |
306 | * Binding Constructs:: Definitions and variable bindings. | |
307 | * Control Mechanisms:: Controlling the flow of program execution. | |
308 | * Input and Output:: Ports, reading and writing. | |
96ca59d8 | 309 | * Regular Expressions:: Pattern matching and substitution. |
358663ca | 310 | * LALR(1) Parsing:: Generating LALR(1) parsers. |
00ce5125 | 311 | * Read/Load/Eval/Compile:: Reading and evaluating Scheme code. |
3229f68b | 312 | * Memory Management:: Memory management and garbage collection. |
3229f68b | 313 | * Modules:: Designing reusable code libraries. |
726b8ba3 | 314 | * Foreign Function Interface:: Interacting with C procedures and data. |
3229f68b MV |
315 | * Scheduling:: Threads, mutexes, asyncs and dynamic roots. |
316 | * Options and Config:: Configuration, features and runtime options. | |
e6709db6 | 317 | * Other Languages:: Emacs Lisp, ECMAScript, and more. |
089a0a34 | 318 | * Internationalization:: Support for gettext, etc. |
c9ef3741 | 319 | * Debugging:: Debugging infrastructure and Scheme interface. |
36b5e394 | 320 | * Code Coverage:: Gathering code coverage data. |
3229f68b MV |
321 | @end menu |
322 | ||
07d83abe | 323 | @include api-overview.texi |
1435c7dc | 324 | @include api-deprecated.texi |
07d83abe MV |
325 | @include api-scm.texi |
326 | @include api-init.texi | |
327 | @include api-snarf.texi | |
328 | @include api-data.texi | |
329 | @include api-compound.texi | |
330 | @include api-smobs.texi | |
331 | @include api-procedures.texi | |
e4955559 | 332 | @include api-macros.texi |
07d83abe MV |
333 | @include api-utility.texi |
334 | @include api-binding.texi | |
335 | @include api-control.texi | |
336 | @include api-io.texi | |
96ca59d8 | 337 | @include api-regex.texi |
2115b8eb | 338 | @include api-lalr.texi |
07d83abe MV |
339 | @include api-evaluation.texi |
340 | @include api-memory.texi | |
341 | @include api-modules.texi | |
726b8ba3 | 342 | @include api-foreign.texi |
07d83abe | 343 | @include api-scheduling.texi |
38a93523 | 344 | @c object orientation support here |
07d83abe | 345 | @include api-options.texi |
e6709db6 | 346 | @include api-languages.texi |
089a0a34 | 347 | @include api-i18n.texi |
07d83abe | 348 | @include api-debug.texi |
36b5e394 | 349 | @include api-coverage.texi |
38a93523 | 350 | |
3229f68b MV |
351 | @node Guile Modules |
352 | @chapter Guile Modules | |
353 | ||
354 | @menu | |
355 | * SLIB:: Using the SLIB Scheme library. | |
356 | * POSIX:: POSIX system calls and networking. | |
8db7e094 | 357 | * Web:: HTTP, the web, and all that. |
3229f68b MV |
358 | * getopt-long:: Command line handling. |
359 | * SRFI Support:: Support for various SRFIs. | |
845cbcfe | 360 | * R6RS Support:: Modules defined by the R6RS. |
358663ca | 361 | * Pattern Matching:: Generic pattern matching constructs. |
3229f68b | 362 | * Readline Support:: Module for using the readline library. |
3229f68b MV |
363 | * Pretty Printing:: Nicely formatting Scheme objects for output. |
364 | * Formatted Output:: The @code{format} procedure. | |
3229f68b MV |
365 | * File Tree Walk:: Traversing the file system. |
366 | * Queues:: First-in first-out queuing. | |
71abb271 | 367 | * Streams:: Sequences of values. |
40296bab | 368 | * Buffered Input:: Ports made from a reader function. |
3229f68b | 369 | * Expect:: Controlling interactive programs with Guile. |
400a5dcb | 370 | * sxml-match:: Pattern matching of SXML. |
3229f68b | 371 | * The Scheme shell (scsh):: Using scsh interfaces in Guile. |
98553883 | 372 | * Curried Definitions:: Extended @code{define} syntax. |
58c4a39d AW |
373 | * Statprof:: An easy-to-use statistical profiler. |
374 | * SXML:: Parsing, transforming, and serializing XML. | |
29ace173 | 375 | * Texinfo Processing:: Munging documents written in Texinfo. |
3229f68b | 376 | @end menu |
38a93523 NJ |
377 | |
378 | @include slib.texi | |
379 | @include posix.texi | |
8db7e094 | 380 | @include web.texi |
3229f68b | 381 | @include mod-getopt-long.texi |
fc8529c7 | 382 | @include srfi-modules.texi |
845cbcfe | 383 | @include r6rs.texi |
358663ca | 384 | @include match.texi |
fc8529c7 | 385 | @include repl-modules.texi |
c2537425 | 386 | @include misc-modules.texi |
38a93523 | 387 | @include expect.texi |
400a5dcb LC |
388 | |
389 | @c XXX: Would be nicer if it were close to the (sxml simple) documentation. | |
390 | @include sxml-match.texi | |
391 | ||
38a93523 | 392 | @include scsh.texi |
98553883 | 393 | @include curried.texi |
38a93523 | 394 | |
58c4a39d AW |
395 | @include statprof.texi |
396 | @include sxml.texi | |
397 | @include texinfo.texi | |
c55cb58a | 398 | |
eb12b401 NJ |
399 | @include goops.texi |
400 | ||
090d51ed AW |
401 | @node Guile Implementation |
402 | @chapter Guile Implementation | |
8680d53b | 403 | |
0b8f3ac5 AW |
404 | At some point, after one has been programming in Scheme for some time, |
405 | another level of Scheme comes into view: its implementation. Knowledge | |
406 | of how Scheme can be implemented turns out to be necessary to become | |
407 | an expert hacker. As Peter Norvig notes in his retrospective on | |
408 | PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of | |
409 | Artificial Intelligence Programming}, an old but still useful text on | |
410 | Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be | |
411 | found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp | |
412 | programmer eventually develops a good `efficiency model'.'' | |
413 | ||
414 | By this Norvig means that over time, the Lisp hacker eventually | |
415 | develops an understanding of how much her code ``costs'' in terms of | |
416 | space and time. | |
417 | ||
418 | This chapter describes Guile as an implementation of Scheme: its | |
419 | history, how it represents and evaluates its data, and its compiler. | |
420 | This knowledge can help you to make that step from being one who is | |
421 | merely familiar with Scheme to being a real hacker. | |
8680d53b AW |
422 | |
423 | @menu | |
0f7e6c56 AW |
424 | * History:: A brief history of Guile. |
425 | * Data Representation:: How Guile represents Scheme data. | |
426 | * A Virtual Machine for Guile:: How compiled procedures work. | |
427 | * Compiling to the Virtual Machine:: Not as hard as you might think. | |
8680d53b AW |
428 | @end menu |
429 | ||
430 | @include history.texi | |
3229f68b | 431 | @include data-rep.texi |
8680d53b AW |
432 | @include vm.texi |
433 | @include compiler.texi | |
434 | ||
31d328de LC |
435 | @node GNU Free Documentation License |
436 | @appendix GNU Free Documentation License | |
437 | ||
c6ae9c77 MV |
438 | @include fdl.texi |
439 | ||
38a93523 | 440 | @include indices.texi |
9401323e | 441 | @include scheme-indices.texi |
38a93523 | 442 | |
38a93523 | 443 | @bye |