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