doc/ref/guile.texi

   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 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
  80 @c @iftex
  81 @c @cropmarks
  82 @c @end iftex
  83
  84 @dircategory The Algorithmic Language Scheme
  85 @direntry
  86 * Guile Reference: (guile).     The Guile reference manual.
  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
 124 @subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $
 125 @subtitle For use with Guile @value{VERSION}
 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
 135 @c to POSIX system calls and networking, expect, I/O internals and
 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}
 178
 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
 211 @ifnottex
 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
 219 This Info file contains edition @value{MANUAL_EDITION} of the reference
 220 manual, corresponding to Guile version @value{VERSION}.
 221 @end ifnottex
 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.
 228 * Manual Conventions::          Conventional terminology.
 229
 230 Part I: Introduction to Guile
 231
 232 * What is Guile?::              And what does it do?
 233 * Whirlwind Tour::              An introductory whirlwind tour.
 234 * Obtaining and Installing Guile::
 235 * Reporting Bugs::              Reporting bugs in Guile or this manual.
 236
 237 Part II: Programming with Guile
 238
 239 * Programming Intro::           Introduction to this part.
 240 * Programming Overview::        An overview of Guile programming.
 241 * Scheme Intro::                Introduction to Guile Scheme.
 242 * Basic Ideas::                 Basic ideas in Scheme.
 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.
 246 * Guile API::                   Overview of the Guile API.
 247 * Data Representation::         Data representation in Guile.
 248 * GH::                          The deprecated GH interface.
 249 * Debugger User Interface::
 250 * Autoconf Support::            Guile-specific configure.in macros.
 251 * Miscellaneous Tools::         Snarfing, linting, etc.
 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.
 257 * Simple Data Types::           Numbers, strings, booleans and so on.
 258 * Compound Data Types::         Data types for holding other data.
 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.
 273
 274 Part IV: Guile Modules
 275
 276 * SLIB::                        Using the SLIB Scheme library.
 277 * POSIX::                       POSIX system calls and networking.
 278 * SRFI Support::                Support for various SRFIs.
 279 * Readline Support::            Module for using the readline library.
 280 * Value History::               Maintaining a value history in the REPL.
 281 * Pretty Printing::             Nicely formatting Scheme objects for output.
 282 * Formatted Output::            The @code{format} procedure.
 283 * Rx Regexps::                  The Rx regular expression library.
 284 * Expect::                      Controlling interactive programs with Guile.
 285 * The Scheme shell (scsh)::     Using scsh interfaces in Guile.
 286
 287 Indices
 288
 289 * Concept Index::
 290 * Procedure Index::
 291 * Variable Index::
 292 * Type Index::
 293 * R5RS Index::
 294 * Guile Extensions Index::
 295
 296 @end menu
 297
 298 @include preface.texi
 299
 300 @iftex
 301 @page
 302 @unnumbered{Part I: Introduction to Guile}
 303 @end iftex
 304
 305 @include intro.texi
 306
 307 @page
 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
 317 Part III (@pxref{Reference Intro,,Part III --- Guile API Reference}).
 318
 319 We begin in the first chapter of this part by looking at the programming
 320 options available.
 321
 322 @include program.texi
 323 @include scheme-intro.texi
 324 @include scheme-ideas.texi
 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
 332 @include autoconf.texi
 333 @include tools.texi
 334 @include scheme-reading.texi
 335
 336 @page
 337 @node Reference Intro
 338 @unnumbered Part III: Guile API Reference
 339
 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
 345 @include scheme-data.texi
 346 @include scheme-compound.texi
 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
 361
 362 @iftex
 363 @page
 364 @unnumbered{Part IV: Guile Modules}
 365 @end iftex
 366
 367 @include slib.texi
 368 @include posix.texi
 369 @include srfi-modules.texi
 370 @include repl-modules.texi
 371 @include misc-modules.texi
 372 @include expect.texi
 373 @include scsh.texi
 374
 375 @iftex
 376 @page
 377 @unnumbered{Indices}
 378 @end iftex
 379
 380 @include indices.texi
 381 @include scheme-indices.texi
 382
 383 @contents
 384
 385 @bye