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 @include version.texi
  10
  11 @copying
  12 This reference manual documents Guile, GNU's Ubiquitous Intelligent
  13 Language for Extensions, manual edition @value{MANUAL-EDITION}
  14 corresponding to Guile @value{VERSION}.
  15
  16 Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 Free Software
  17 Foundation.
  18
  19 Permission is granted to copy, distribute and/or modify this
  20 document under the terms of the GNU Free Documentation License,
  21 Version 1.2 or any later version published by the Free Software
  22 Foundation; with the no Invariant Sections, with the Front-Cover
  23 Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in
  24 (a) below.  A copy of the license is included in the section
  25 entitled "GNU Free Documentation License".
  26
  27 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
  28 this GNU Manual.''
  29 @end copying
  30
  31
  32 @c Notes
  33 @c
  34 @c We no longer use the category "primitive" to distinguish C-defined
  35 @c Scheme procedures from those defined in Scheme.  Instead, the
  36 @c reference manual now includes a C declaration as well as a Scheme
  37 @c declaration for each procedure that is available in both Scheme and
  38 @c C.
  39 @c
  40 @c When adding a new reference entry to the Guile manual, please
  41 @c document it with @deffn using one of the following categories:
  42 @c
  43 @c   {Scheme Procedure}
  44 @c   {Scheme Syntax}
  45 @c   {C Function}
  46 @c   {C Macro}
  47 @c
  48 @c If the entry is for a new primitive, it should have both a @deffn
  49 @c {Scheme Procedure} line and a @deffnx {C Function} line; see the
  50 @c manual source for plenty of existing examples of this.
  51 @c
  52 @c For {C Function} entries where the return type and all parameter
  53 @c types are SCM, we omit the SCMs.  This is easier to read and also
  54 @c gets round the problem that Texinfo doesn't allow a @deftypefnx
  55 @c inside a @deffn.
  56 @c
  57 @c For a list of Guile primitives that are not yet incorporated into the
  58 @c reference manual, see the file `new-docstrings.texi', which holds all
  59 @c the docstrings snarfed from the libguile C sources for primitives
  60 @c that are not in the reference manual.  If you have worked with some
  61 @c of these concepts, implemented them, or just happen to know what they
  62 @c do, please write up a little explanation -- it would be a big help.
  63 @c Alternatively, if you know of any reason why some of these should
  64 @c *not* go in the manual, please let the mailing list
  65 @c <guile-devel@gnu.org> know.
  66
  67 @c Define indices that are used in the Guile Scheme part of the
  68 @c reference manual to group stuff according to whether it is R5RS or a
  69 @c Guile extension.
  70 @defcodeindex rn
  71
  72 @c vnew - For (some) new items, indicates the Guile version in which
  73 @c item first appeared.  In future, this could be made to expand to
  74 @c something like a "New in Guile 45!" banner.
  75 @macro vnew{VERSION}
  76 @end macro
  77
  78
  79 @c  @cross{} is a \times symbol in tex, or an "x" in info.  In tex it works
  80 @c  inside or outside $ $.
  81 @tex
  82 \gdef\cross{\ifmmode\times\else$\times$\fi}
  83 @end tex
  84 @ifnottex
  85 @macro cross
  86 x
  87 @end macro
  88 @end ifnottex
  89
  90 @c  @m{T,N} is $T$ in tex or @math{N} otherwise.  This is an easy way to give
  91 @c  different forms for math in tex and info.
  92 @iftex
  93 @macro m {T,N}
  94 @tex$\T\$@end tex
  95 @end macro
  96 @end iftex
  97 @ifnottex
  98 @macro m {T,N}
  99 @math{\N\}
 100 @end macro
 101 @end ifnottex
 102
 103 @c  @nicode{S} is plain S in info, or @code{S} elsewhere.  This can be
 104 @c  used when the quotes that @code{} gives in info aren't wanted, but
 105 @c  the fontification in tex or html is wanted.
 106 @ifinfo
 107 @macro nicode {S}
 108 \S\
 109 @end macro
 110 @end ifinfo
 111 @ifnotinfo
 112 @macro nicode {S}
 113 @code{\S\}
 114 @end macro
 115 @end ifnotinfo
 116
 117
 118 @c @iftex
 119 @c @cropmarks
 120 @c @end iftex
 121
 122 @dircategory The Algorithmic Language Scheme
 123 @direntry
 124 * Guile Reference: (guile).     The Guile reference manual.
 125 @end direntry
 126
 127 @setchapternewpage off
 128
 129 @titlepage
 130 @sp 10
 131 @comment The title is printed in a large font.
 132 @title Guile Reference Manual
 133 @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
 134 @subtitle $Id: guile.texi,v 1.29 2004-02-18 20:07:19 mvo Exp $
 135
 136 @c See preface.texi for the list of authors
 137 @author The Guile Developers
 138
 139 @c The following two commands start the copyright page.
 140 @page
 141 @vskip 0pt plus 1filll
 142 @vskip 0pt plus 1filll
 143 @insertcopying
 144 @end titlepage
 145
 146 @c @smallbook
 147 @finalout
 148 @headings double
 149
 150 @c Where to find Guile examples.
 151 @set example-dir doc/examples
 152
 153 @ifnottex
 154 @node Top, Contributors, (dir), (dir)
 155 @top The Guile Reference Manual
 156
 157 @insertcopying
 158 @sp 1
 159 @end ifnottex
 160
 161 @menu
 162 Preface
 163
 164 * Contributors::                Contributors to this manual.
 165 * Guile License::               Conditions for copying and using Guile.
 166 * Manual Layout::               How to read the rest of this manual.
 167 * Manual Conventions::          Conventional terminology.
 168
 169 Part I: Introduction to Guile
 170
 171 * What is Guile?::              And what does it do?
 172 * Whirlwind Tour::              An introductory whirlwind tour.
 173 * Obtaining and Installing Guile::
 174 * Reporting Bugs::              Reporting bugs in Guile or this manual.
 175
 176 Part II: Writing and Running Guile Scheme
 177
 178 * Running Intro::               Introduction to this part.
 179 * Guile Scheme::                Guile's implementation of Scheme.
 180 * Guile Scripting::             How to write Guile scripts.
 181 * Command Line Handling::       Command line options and arguments.
 182 * Debugging Features::          Features for debugging errors.
 183 * Autoconf Support::            Guile-specific configure.in macros.
 184 * Miscellaneous Tools::         Snarfing, linting, etc.
 185 * Basic Ideas::                 Basic ideas in Scheme.
 186 * Further Reading::             Where to find out more about Scheme.
 187
 188 Part III: Guile as an Extension Language
 189
 190 * Programming Intro::           Introduction to this part.
 191 * Libguile Intro::              Using Guile as an extension language.
 192 * Programming Overview::        An overview of Guile programming.
 193 * Data Representation::         Data representation in Guile.
 194 * GH::                          The deprecated GH interface.
 195
 196 Part IV: Guile API Reference
 197
 198 * Reference Intro::             Introduction to the Guile API reference.
 199 * API Overview::                Overview of the Guile API.
 200 * Simple Data Types::           Numbers, strings, booleans and so on.
 201 * Compound Data Types::         Data types for holding other data.
 202 * Procedures and Macros::       Procedures and macros.
 203 * Utility Functions::           General utility functions.
 204 * Binding Constructs::          Definitions and variable bindings.
 205 * Control Mechanisms::          Controlling the flow of program execution.
 206 * Input and Output::            Ports, reading and writing.
 207 * Read/Load/Eval::              Reading and evaluating Scheme code.
 208 * Memory Management::           Memory management and garbage collection.
 209 * Objects::                     Low level object orientation support.
 210 * Modules::                     Designing reusable code libraries.
 211 * Scheduling::                  Threads, mutexes, asyncs and dynamic roots.
 212 * Options and Config::          Configuration, features and runtime options.
 213 * Translation::                 Support for translating other languages.
 214 * Debugging::                   Internal debugging interface.
 215 * Deprecated::                  Features that are planned to disappear.
 216
 217 Part V: Guile Modules
 218
 219 * SLIB::                        Using the SLIB Scheme library.
 220 * POSIX::                       POSIX system calls and networking.
 221 * SRFI Support::                Support for various SRFIs.
 222 * Readline Support::            Module for using the readline library.
 223 * Value History::               Maintaining a value history in the REPL.
 224 * Pretty Printing::             Nicely formatting Scheme objects for output.
 225 * Formatted Output::            The @code{format} procedure.
 226 * Rx Regexps::                  The Rx regular expression library.
 227 * File Tree Walk::              Traversing the file system.
 228 * Queues::                      First-in first-out queuing.
 229 * Expect::                      Controlling interactive programs with Guile.
 230 * The Scheme shell (scsh)::     Using scsh interfaces in Guile.
 231
 232 Appendices
 233
 234 * GNU Free Documentation License::  The license of this manual.
 235
 236 Indices
 237
 238 * Concept Index::
 239 * Procedure Index::
 240 * Variable Index::
 241 * Type Index::
 242 * R5RS Index::
 243
 244 @end menu
 245
 246 @contents
 247
 248 @include preface.texi
 249
 250 @iftex
 251 @page
 252 @unnumbered{Part I: Introduction to Guile}
 253 @end iftex
 254
 255 @include intro.texi
 256
 257 @page
 258 @node Running Intro
 259 @unnumbered Part II: Writing and Running Guile Scheme
 260
 261 Guile's core language is Scheme, and an awful lot can be achieved simply
 262 by using Guile to write and run Scheme programs.  In this part of the
 263 manual, we explain how to use Guile in this mode, and describe the tools
 264 that Guile provides to help you with script writing, debugging and
 265 packaging your programs for distribution.
 266
 267 For readers who are not yet familiar with the Scheme language, this part
 268 includes a chapter that presents the basic concepts of the language, and
 269 gives references to freely available Scheme tutorial material on the
 270 web.
 271
 272 For detailed reference information on the variables, functions etc. that
 273 make up Guile's application programming interface (API), please refer to
 274 Part IV (@pxref{Reference Intro,,Part IV --- Guile API Reference}).
 275
 276 @include scheme-intro.texi
 277 @include scripts.texi
 278 @include script-getopt.texi
 279 @include debugging.texi
 280 @include autoconf.texi
 281 @include tools.texi
 282 @include scheme-ideas.texi
 283 @include scheme-reading.texi
 284
 285 @page
 286 @node Programming Intro
 287 @unnumbered Part III: Guile as an Extension Language
 288
 289 In this part of the manual, we aim to present a wide ranging picture of
 290 what it means to use Guile as an application extension language, to
 291 provide guidance, practical guidelines and tips for @emph{how} to
 292 program in Guile, and to document the tools that are available to help
 293 you with your programming.  For detailed reference information on the
 294 variables, functions etc. that make up Guile's application programming
 295 interface (API), please refer to Part IV (@pxref{Reference Intro,,Part
 296 IV --- Guile API Reference}).
 297
 298 @include extend.texi
 299 @include program.texi
 300 @include data-rep.texi
 301 @include gh.texi
 302
 303 @page
 304 @node Reference Intro
 305 @unnumbered Part IV: Guile API Reference
 306
 307 Guile provides an application programming interface (@dfn{API}) to
 308 developers in two core languages: Scheme and C.  This part of the manual
 309 contains reference documentation for all of the functionality that is
 310 available through both Scheme and C interfaces.
 311
 312 @include scm.texi
 313 @include scheme-data.texi
 314 @include scheme-compound.texi
 315 @include scheme-procedures.texi
 316 @include scheme-utility.texi
 317 @include scheme-binding.texi
 318 @include scheme-control.texi
 319 @include scheme-io.texi
 320 @include scheme-evaluation.texi
 321 @include scheme-memory.texi
 322 @include scheme-modules.texi
 323 @include scheme-scheduling.texi
 324 @c object orientation support here
 325 @include scheme-options.texi
 326 @include scheme-translation.texi
 327 @include scheme-debug.texi
 328 @include deprecated.texi
 329
 330 @iftex
 331 @page
 332 @unnumbered{Part V: Guile Modules}
 333 @end iftex
 334
 335 @include slib.texi
 336 @include posix.texi
 337 @include srfi-modules.texi
 338 @include repl-modules.texi
 339 @include misc-modules.texi
 340 @include expect.texi
 341 @include scsh.texi
 342
 343 @include fdl.texi
 344
 345 @iftex
 346 @page
 347 @unnumbered{Indices}
 348 @end iftex
 349
 350 @include indices.texi
 351 @include scheme-indices.texi
 352
 353 @bye