guile/doc/ref/guile.texi

\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guile.info
@documentencoding UTF-8
@settitle Guile Reference Manual
@set guile
@set MANUAL-REVISION 1
@c %**end of header
@include version.texi
@include effective-version.texi

@copying
This manual documents Guile version @value{VERSION}.

Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
Inc. @*
Copyright (C) 2021 Maxime Devos

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''

Additionally, the documentation of the 125, 126, 128, 151 and 160 SRFI
modules is adapted from their specification text, which is made
available under the following Expat license:

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

@end copying

@c Notes
@c
@c We no longer use the category "primitive" to distinguish C-defined
@c Scheme procedures from those defined in Scheme.  Instead, the
@c reference manual now includes a C declaration as well as a Scheme
@c declaration for each procedure that is available in both Scheme and
@c C.
@c
@c When adding a new reference entry to the Guile manual, please
@c document it with @deffn using one of the following categories:
@c
@c   {Scheme Procedure}
@c   {Scheme Syntax}
@c   {C Function}
@c   {C Macro}
@c
@c If the entry is for a new primitive, it should have both a @deffn
@c {Scheme Procedure} line and a @deffnx {C Function} line; see the
@c manual source for plenty of existing examples of this.
@c
@c For {C Function} entries where the return type and all parameter
@c types are SCM, we omit the SCMs.  This is easier to read and also
@c gets round the problem that Texinfo doesn't allow a @deftypefnx
@c inside a @deffn.
@c
@c For a list of Guile primitives that are not yet incorporated into the
@c reference manual, see the file `new-docstrings.texi', which holds all
@c the docstrings snarfed from the libguile C sources for primitives
@c that are not in the reference manual.  If you have worked with some
@c of these concepts, implemented them, or just happen to know what they
@c do, please write up a little explanation -- it would be a big help.
@c Alternatively, if you know of any reason why some of these should
@c *not* go in the manual, please let the mailing list
@c <guile-devel@gnu.org> know.

@c Define indices that are used in the Guile Scheme part of the
@c reference manual to group stuff according to whether it is R5RS or a
@c Guile extension.
@defcodeindex rn

@c vnew - For (some) new items, indicates the Guile version in which
@c item first appeared.  In future, this could be made to expand to
@c something like a "New in Guile 45!" banner.
@macro vnew{VERSION}
@end macro


@c  The following, @le{} and @ge{}, are standard tex directives, given
@c  definitions for use in non-tex.
@c
@ifnottex
@macro ge
>=
@end macro
@macro le
<=
@end macro
@end ifnottex

@c  @cross{} is a \times symbol in tex, or an "x" in info.  In tex it works
@c  inside or outside $ $.
@tex
\gdef\cross{\ifmmode\times\else$\times$\fi}
@end tex
@ifnottex
@macro cross
x
@end macro
@end ifnottex

@c  @m{T,N} is $T$ in tex or @math{N} otherwise.  This is an easy way to give
@c  different forms for math in tex and info.
@iftex
@macro m {T,N}
@tex$\T\$@end tex
@end macro
@end iftex
@ifnottex
@macro m {T,N}
@math{\N\}
@end macro
@end ifnottex

@c  @nicode{S} is plain S in info, or @code{S} elsewhere.  This can be used
@c  when the quotes that @code{} gives in info aren't wanted, but the
@c  fontification in tex or html is wanted.  @alias is used rather
@c  than @macro because backslashes don't work properly in an @macro.
@ifinfo
@alias nicode=asis
@end ifinfo
@ifnotinfo
@alias nicode=code
@end ifnotinfo


@c @iftex
@c @cropmarks
@c @end iftex

@dircategory The Algorithmic Language Scheme
@direntry
* Guile Reference: (guile).     The Guile reference manual.
@end direntry

@setchapternewpage odd

@titlepage
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION}, for use with Guile @value{VERSION}
@c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $

@c See preface.texi for the list of authors
@author The Guile Developers

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c @smallbook
@finalout
@headings double

@c Where to find Guile examples.
@set example-dir doc/examples

@ifnottex
@node Top, Preface, (dir), (dir)
@top The Guile Reference Manual

@insertcopying
@sp 1
@end ifnottex

@menu

* Preface::
* Introduction::

* Hello Guile!::
* Hello Scheme!::

* Programming in Scheme::
* Programming in C::

* API Reference::

* Guile Modules::

* GOOPS::

* Guile Implementation::

Appendices

* GNU Free Documentation License::  The license of this manual.

Indices

* Concept Index::
* Procedure Index::
* Variable Index::
* Type Index::
* R5RS Index::

@end menu

@contents

@include preface.texi

@include intro.texi

@include tour.texi

@include scheme-ideas.texi
@include scheme-reading.texi

@node Programming in Scheme
@chapter Programming in Scheme

Guile's core language is Scheme, and a lot can be achieved simply by using Guile
to write and run Scheme programs --- as opposed to having to dive into C code.
In this part of the manual, we explain how to use Guile in this mode, and
describe the tools that Guile provides to help you with script writing,
debugging, and packaging your programs for distribution.

For detailed reference information on the variables, functions, and so
on that make up Guile's application programming interface (API), see
@ref{API Reference}.

@menu
* Guile Scheme::                Guile's implementation of Scheme.
* Invoking Guile::              Selecting optional features when starting Guile.
* Guile Scripting::             How to write Guile scripts.
* Using Guile Interactively::   Guile's REPL features.
* Using Guile in Emacs::        Guile and Emacs.
* Using Guile Tools::           A guild of scheming wizards.
* Installing Site Packages::    Installing Scheme code.
* Distributing Guile Code::     Building and distributing your code.
@end menu

@include scheme-intro.texi
@include guile-invoke.texi
@include scheme-scripts.texi
@include scheme-using.texi

@node Programming in C
@chapter Programming in C

This part of the manual explains the general concepts that you need to
understand when interfacing to Guile from C.  You will learn about how
the latent typing of Scheme is embedded into the static typing of C, how
the garbage collection of Guile is made available to C code, and how
continuations influence the control flow in a C program.

This knowledge should make it straightforward to add new functions to
Guile that can be called from Scheme.  Adding new data types is also
possible and is done by defining @dfn{foreign objects}.

The @ref{Programming Overview} section of this part contains general
musings and guidelines about programming with Guile.  It explores
different ways to design a program around Guile, or how to embed Guile
into existing programs.

For a pedagogical yet detailed explanation of how the data representation of
Guile is implemented, @xref{Data Representation}. You don't need to know the
details given there to use Guile from C, but they are useful when you want to
modify Guile itself or when you are just curious about how it is all done.

For detailed reference information on the variables, functions
etc. that make up Guile's application programming interface (API),
@xref{API Reference}.

@menu
* Parallel Installations::      Finding the right Guile.
* Linking Programs With Guile:: More precisely, with the libguile library.
* Linking Guile with Libraries::  To extend Guile itself. 
* General Libguile Concepts::   General concepts for using libguile.
* Defining New Foreign Object Types::  Adding new types to Guile.
* Function Snarfing::           A way to define new functions.
* Programming Overview::        An overview of Guile programming.
* Autoconf Support::            Putting m4 to good use.
@end menu

@include libguile-parallel.texi
@include libguile-linking.texi
@include libguile-extensions.texi
@include libguile-concepts.texi
@include libguile-foreign-objects.texi
@include libguile-snarf.texi
@include libguile-program.texi
@include libguile-autoconf.texi


@node API Reference
@chapter API Reference

Guile provides an application programming interface (@dfn{API}) to
developers in two core languages: Scheme and C.  This part of the manual
contains reference documentation for all of the functionality that is
available through both Scheme and C interfaces.

@menu
* API Overview::                Overview of the Guile API.
* Deprecation::                 Obsolete back-compatible APIs.
* The SCM Type::                The fundamental data type for C code.
* Initialization::              Initializing Guile.
* Snarfing Macros::             Macros for snarfing initialization actions.
* Data Types::                  Representing values in Guile.
* Procedures::                  Procedures.
* Macros::                      Extending the syntax of Scheme.
* Utility Functions::           General utility functions.
* Binding Constructs::          Definitions and variable bindings.
* Control Mechanisms::          Controlling the flow of program execution.
* Input and Output::            Ports, reading and writing.
* Regular Expressions::         Pattern matching and substitution.
* LALR(1) Parsing::             Generating LALR(1) parsers.
* PEG Parsing::                 Parsing Expression Grammars.
* Read/Load/Eval/Compile::      Reading and evaluating Scheme code.
* Memory Management::           Memory management and garbage collection.
* Modules::                     Designing reusable code libraries.
* Foreign Function Interface::  Interacting with C procedures and data.
* Foreign Objects::             Defining new data types in C.
* Smobs::                       Use foreign objects instead.
* Scheduling::                  Threads, mutexes, asyncs and dynamic roots.
* Options and Config::          Configuration, features and runtime options.
* Other Languages::             Emacs Lisp, ECMAScript, and more.
* Internationalization::        Support for gettext, etc.
* Debugging::                   Debugging infrastructure and Scheme interface.
* Code Coverage::               Gathering code coverage data.
@end menu

@include api-overview.texi
@include api-deprecated.texi
@include api-scm.texi
@include api-init.texi
@include api-snarf.texi
@include api-data.texi
@include api-procedures.texi
@include api-macros.texi
@include api-utility.texi
@include api-binding.texi
@include api-control.texi
@include api-io.texi
@include api-regex.texi
@include api-lalr.texi
@include api-peg.texi
@include api-evaluation.texi
@include api-memory.texi
@include api-modules.texi
@include api-foreign.texi
@include api-foreign-objects.texi
@include api-smobs.texi
@include api-scheduling.texi
@c object orientation support here
@include api-options.texi
@include api-languages.texi
@include api-i18n.texi
@include api-debug.texi
@include api-coverage.texi

@node Guile Modules
@chapter Guile Modules

@menu
* SLIB::                        Using the SLIB Scheme library.
* POSIX::                       POSIX system calls and networking.
* Web::                         HTTP, the web, and all that.
* getopt-long::                 Command line handling.
* SRFI Support::                Support for various SRFIs.
* R6RS Support::                Modules defined by the R6RS.
* R7RS Support::                Modules defined by the R7RS.
* Pattern Matching::            Generic pattern matching constructs.
* Readline Support::            Module for using the readline library.
* Pretty Printing::             Nicely formatting Scheme objects for output.
* Formatted Output::            The @code{format} procedure.
* File Tree Walk::              Traversing the file system.
* Queues::                      First-in first-out queuing.
* Streams::                     Sequences of values.
* Buffered Input::              Ports made from a reader function.
* Expect::			Controlling interactive programs with Guile.
* sxml-match::                  Pattern matching of SXML.
* The Scheme shell (scsh)::     Using scsh interfaces in Guile.
* Curried Definitions::         Extended @code{define} syntax.
* Statprof::                    An easy-to-use statistical profiler.
* SXML::                        Parsing, transforming, and serializing XML.
* Texinfo Processing::          Munging documents written in Texinfo.
@end menu

@include slib.texi
@include posix.texi
@include web.texi
@include mod-getopt-long.texi
@include srfi-modules.texi
@include r6rs.texi
@include r7rs.texi
@include match.texi
@include repl-modules.texi
@include misc-modules.texi
@include expect.texi

@c XXX: Would be nicer if it were close to the (sxml simple) documentation.
@include sxml-match.texi

@include scsh.texi
@include curried.texi

@include statprof.texi
@include sxml.texi
@include texinfo.texi

@include goops.texi

@node Guile Implementation
@chapter Guile Implementation

At some point, after one has been programming in Scheme for some time,
another level of Scheme comes into view: its implementation. Knowledge
of how Scheme can be implemented turns out to be necessary to become
an expert hacker. As Peter Norvig notes in his retrospective on
PAIP@footnote{PAIP is the common abbreviation for @cite{Paradigms of
Artificial Intelligence Programming}, an old but still useful text on
Lisp. Norvig's retrospective sums up the lessons of PAIP, and can be
found at @uref{http://norvig.com/Lisp-retro.html}.}, ``The expert Lisp
programmer eventually develops a good `efficiency model'.''

By this Norvig means that over time, the Lisp hacker eventually
develops an understanding of how much her code ``costs'' in terms of
space and time.

This chapter describes Guile as an implementation of Scheme: its
history, how it represents and evaluates its data, and its compiler.
This knowledge can help you to make that step from being one who is
merely familiar with Scheme to being a real hacker.

@menu
* History::                          A brief history of Guile.
* Data Representation::              How Guile represents Scheme data.
* A Virtual Machine for Guile::      How compiled procedures work.
* Compiling to the Virtual Machine:: Not as hard as you might think.
@end menu

@include history.texi
@include data-rep.texi
@include vm.texi
@include compiler.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@include indices.texi
@include scheme-indices.texi

@bye