mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-11 22:31:12 +02:00
Code Activity

* Split documentation into per-manual subdirectories.

Browse source
This commit is contained in:
Neil Jerram 2001-08-24 11:58:36 +00:00
parent 0923df6aa1
commit ad36a10117
65 changed files with 166 additions and 16070 deletions
Download patch file Download diff file Expand all files Collapse all files

5
ChangeLog
View file

@ -1,3 +1,8 @@
2001-08-24 Neil Jerram <neil@ossau.uklinux.net>
* configure.in (AC_CONFIG_FILES): Add Makefiles for per-manual
subdirectories.
2001-08-15 Rob Browning <rlb@defaultvalue.org>
* configure.in

4
configure.in
View file

@ -634,6 +634,10 @@ AC_CONFIG_FILES([
qt/time/Makefile
guile-config/Makefile
doc/Makefile
doc/ref/Makefile
doc/tutorial/Makefile
doc/goops/Makefile
doc/r5rs/Makefile
examples/Makefile
examples/scripts/Makefile
examples/box/Makefile

0
doc/ChangeLog-guile-doc-ref
View file

0
doc/ChangeLog-guile-doc-tutorial
View file

51
doc/Makefile.am
View file

@ -19,45 +19,13 @@
## to the Free Software Foundation, Inc., 59 Temple Place, Suite
## 330, Boston, MA 02111-1307 USA
AUTOMAKE_OPTIONS = foreign
AUTOMAKE_OPTIONS = gnu
SUBDIRS = ref tutorial goops r5rs
# pending the papers from Robert Merkel
# man_MANS = guile.1
info_TEXINFOS = guile.texi r5rs.texi goops.texi guile-tut.texi
guile_TEXINFOS = preface.texi intro.texi scheme-intro.texi \
scheme-ideas.texi scheme-data.texi scheme-procedures.texi \
scheme-utility.texi scheme-binding.texi scheme-control.texi \
scheme-io.texi scheme-evaluation.texi scheme-memory.texi \
scheme-modules.texi scheme-scheduling.texi scheme-options.texi \
scheme-translation.texi scheme-debug.texi deprecated.texi \
scheme-reading.texi scheme-indices.texi slib.texi posix.texi \
expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.texi \
appendices.texi indices.texi script-getopt.texi data-rep.texi \
extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi \
AUTHORS
guile_tut_TEXINFOS = AUTHORS
goops_TEXINFOS = goops-tutorial.texi hierarchy.eps hierarchy.txt AUTHORS
# Optionally support building an HTML version of the reference manual.
if HTMLDOC
htmldir = $(prefix)/html/guile-$(VERSION)
html_DATA = guile_toc.html $(shell ls guile_*.html 2>/dev/null) guile-tut_toc.html $(shell ls guile-tut_*.html 2>/dev/null)
guile_toc.html: guile.texi $(guile_TEXINFOS)
$(TEXI2HTML) -split_chapter guile.texi
guile-tut_toc.html: guile-tut.texi
$(TEXI2HTML) -split_chapter guile-tut.texi
endif
EXAMPLE_SMOB_FILES = \
ChangeLog Makefile README COPYING image-type.c image-type.h myguile.c
@ -71,18 +39,5 @@ dist-hook:
cd example-smob; \
cp $(EXAMPLE_SMOB_FILES) $$dest)
## The following two kluges were added so that CVS checkouts would
## build when not configured with `--enable-maintainer-mode'. They
## were removed again since they relied on internal automake features.
# This rule overrides automake's rule for version.texi. It causes
# version.texi to be created even in non-maintainer-mode.
#$(srcdir)/version.texi: stamp-vti
# @:
# And the same for version-tutorial.texi.
#$(srcdir)/version-tutorial.texi: stamp-vti1
# @:
# pending the papers from Robert Merkel
# EXTRA_DIST = guile.1

0
doc/api.txt
View file

0
doc/appendices.texi
View file

2075
doc/data-rep.texi
View file

File diff suppressed because it is too large Load diff

0
doc/deprecated.texi
View file

1165
doc/env.texi
View file

File diff suppressed because it is too large Load diff

0
doc/expect.texi
View file

0
doc/extend.texi
View file

0
doc/format.texi
View file

0
doc/gh.texi
View file

0
doc/goops-tutorial.texi
View file

0
doc/goops.texi
View file

2
doc/goops/goops.texi
View file

@ -40,7 +40,7 @@ are preserved on all copies.
@titlepage
@title Goops Manual
@subtitle For use with GOOPS @value{VERSION}
@include ../AUTHORS
@include AUTHORS
@c The following two commands
@c start the copyright page.

0
doc/guile-tut.texi
View file

301
doc/guile.texi
View file

@ -1,301 +0,0 @@
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guile.info
@settitle Guile Reference Manual
@set guile
@c %**end of header
@c Notes: (distilled from Jim's and Tim's notes, and kept up to date)
@c
@c Remember to use "primitive" whereever appropriate.
@c FIXME: gotta change existing "subr" uses to "Primitive".
@c [JimB:] In my text for the Guile snarfer, I've used the term "subr"
@c to denote a C function made available to the Scheme world as a
@c function. This terminology is weird, but consistent with the
@c function names and also with Emacs Lisp, which I assume takes
@c Maclisp's lead.
@c
@c When adding a new function to the Guile manual, please document
@c it with @deffn as one of `primitive', `procedure', or `syntax'.
@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 a great reason why some of these should
@c *not* go in the manual, please let me 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
@defcodeindex ge
@include version.texi
@c @iftex
@c @cropmarks
@c @end iftex
@dircategory The Algorithmic Language Scheme
@direntry
* Guile Reference: (guile). The Guile reference manual.
@end direntry
@setchapternewpage off
@ifinfo
Guile Reference Manual
Copyright (C) 1996 Free Software Foundation @*
Copyright (C) 1997 Free Software Foundation @*
Copyright (C) 2000 Free Software Foundation @*
Copyright (C) 2001 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end ifinfo
@titlepage
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle $Id: guile.texi,v 1.12 2001-06-29 21:43:17 mgrabmue Exp $
@subtitle For use with Guile @value{VERSION}
@include AUTHORS
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@vskip 0pt plus 1filll
Copyright @copyright{} 1996 Free Software Foundation
Copyright @copyright{} 1997 Free Software Foundation
Copyright @copyright{} 2000 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by Free Software Foundation.
@end titlepage
@c @smallbook
@finalout
@headings double
@c Where to find Guile examples.
@set example-dir doc/examples
@ifinfo
@node Top, Guile License, (dir), (dir)
@top The Guile Reference Manual
This reference manual documents Guile, GNU's Ubiquitous Intelligent
Language for Extensions. It describes how to use Guile in many useful
and interesting ways.
This Info file contains edition 1.0 of the reference manual,
corresponding to Guile version @value{VERSION}.
@end ifinfo
@menu
Preface
* Guile License:: Conditions for copying and using Guile.
* Manual Layout:: How to read the rest of this manual.
* Manual Conventions:: Conventional terminology.
Part I: Introduction to Guile
* What is Guile?:: And what does it do?
* Whirlwind Tour:: An introductory whirlwind tour.
* Reporting Bugs:: Reporting bugs in Guile or this manual.
Part II: Guile Scheme
* Scheme Intro:: Introduction to Guile Scheme.
* Basic Ideas:: Basic ideas in Scheme.
* Data Types:: Data types for generic use.
* Procedures and Macros:: Procedures and macros.
* 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.
* Read/Load/Eval:: Reading and evaluating Scheme code.
* Memory Management:: Memory management and garbage collection.
* Objects:: Low level object orientation support.
* Modules:: Designing reusable code libraries.
* Scheduling:: Threads, mutexes, asyncs and dynamic roots.
* Options and Config:: Runtime options and configuration.
* Translation:: Support for translating other languages.
* Debugging:: Internal debugging interface.
* Deprecated:: Features that are planned to disappear.
* Further Reading:: Where to find out more about Scheme programming.
* R5RS Index::
* Guile Extensions Index::
Part III: Guile Modules
* SLIB:: Using the SLIB Scheme library.
* POSIX:: POSIX system calls and networking.
* SRFI Support:: Support for various SRFIs.
* Readline Support:: Module for using the readline library.
* Value History:: Maintaining a value history in the REPL.
* Pretty Printing:: Nicely formatting Scheme objects for output.
* Formatted Output:: The @code{format} procedure.
* Expect:: Controlling interactive programs with Guile.
* The Scheme shell (scsh)::
The SCSH compatibility module has been made an
add-on, so maybe it shouldn't be documented here
(though it is nice to have a link from here to the
Guile-scsh manual, if one exists).
@c * Tcl/Tk Interface::
Part IV: Guile Scripting
* Guile Scripting:: How to write Guile scripts.
* Command Line Handling:: Command line options and arguments.
Part V: Extending Applications Using Guile
* Libguile Intro:: Using Guile as an extension language.
* Data Representation:: Data representation in Guile.
* Scheme Primitives:: Writing Scheme primitives in C.
* I/O Extensions:: Using and extending ports in C.
* Handling Errors:: How to handle errors in C code.
* GH:: The deprecated GH interface.
Appendices
* Obtaining and Installing Guile::
* Debugger User Interface::
Indices
* Concept Index::
* Procedure Index::
* Variable Index::
* Type Index::
@end menu
@include preface.texi
@c preliminary
@iftex
@page
@unnumbered{Part I: Introduction to Guile}
@end iftex
@include intro.texi
@c programming in Scheme
@iftex
@page
@unnumbered{Part II: Guile Scheme}
@end iftex
@include scheme-intro.texi
@include scheme-ideas.texi
@include scheme-data.texi
@include scheme-procedures.texi
@include scheme-utility.texi
@include scheme-binding.texi
@include scheme-control.texi
@include scheme-io.texi
@include scheme-evaluation.texi
@include scheme-memory.texi
@include scheme-modules.texi
@include scheme-scheduling.texi
@c object orientation support here
@include scheme-options.texi
@include scheme-translation.texi
@include scheme-debug.texi
@include deprecated.texi
@include scheme-reading.texi
@include scheme-indices.texi
@c Unix system interface
@iftex
@page
@unnumbered{Part III: Guile Modules}
@end iftex
@include slib.texi
@include posix.texi
@include srfi-modules.texi
@include repl-modules.texi
@include misc-modules.texi
@include expect.texi
@include scsh.texi
@c @include tcltk.texi
@c Guile as an scripting language
@iftex
@page
@unnumbered{Part IV: Guile Scripting}
@end iftex
@include scripts.texi
@include script-getopt.texi
@c Guile as an extension language
@iftex
@page
@unnumbered{Part V: Extending Applications Using Guile}
@end iftex
@include extend.texi
@include data-rep.texi
@include scm.texi
@include gh.texi
@c Appendices
@iftex
@page
@unnumbered{Appendices}
@end iftex
@include appendices.texi
@c Indices
@iftex
@page
@unnumbered{Indices}
@end iftex
@include indices.texi
@contents
@bye

0
doc/hierarchy.eps
View file

0
doc/hierarchy.txt
View file

0
doc/indices.texi
View file

1022
doc/intro.texi
View file

File diff suppressed because it is too large Load diff

0
doc/misc-modules.texi
View file

0
doc/mop.text
View file

0
doc/new-docstrings.texi
View file

2328
doc/posix.texi
View file

File diff suppressed because it is too large Load diff

0
doc/preface.texi
View file

0
doc/r5rs.texi
View file

4
doc/ref/guile.texi
View file

@ -80,9 +80,9 @@ by the Free Software Foundation.
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle $Id: guile.texi,v 1.2 2001-08-24 10:16:15 ossau Exp $
@subtitle $Id: guile.texi,v 1.2.2.1 2001-08-24 11:58:36 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@include ../AUTHORS
@include AUTHORS
@c The following two commands start the copyright page.
@page

21
doc/ref/intro.texi
View file

@ -1,4 +1,4 @@
@c $Id: intro.texi,v 1.1 2001-08-24 09:40:29 ossau Exp $
@c $Id: intro.texi,v 1.1.2.1 2001-08-24 11:58:36 ossau Exp $
@page
@node What is Guile?
@ -359,7 +359,7 @@ manual. Once you've compiled your source files, you need to link them
against the Guile object code library, @code{libguile}.
On most systems, you should not need to do tell the compiler and linker
explicitely where they can find @file{libguile.h} and @file{libguile}.
explicitly where they can find @file{libguile.h} and @file{libguile}.
When Guile has been installed in a peculiar way, or when you are on a
peculiar system, things might not be so easy and you might need to pass
additional @code{-I} or @code{-L} options to the compiler. Guile
@ -410,7 +410,7 @@ Why must the caller do all the real work from @var{main_func}? Guile's
garbage collector scans the stack to find all local variables that
reference Scheme objects. To do this, it needs to know the bounds of
the stack that might contain such references. Because there is no
protable way in C to find the base of the stack, @code{scm_boot_guile}
portable way in C to find the base of the stack, @code{scm_boot_guile}
assumes that all references are above its own stack frame. If you try
to manipulate Scheme objects after this function returns, it's the luck
of the draw whether Guile's storage manager will be able to find the
@ -632,7 +632,7 @@ available to Scheme. First we need to write the appropriate glue code
to convert the arguments and return values of the functions from Scheme
to C and back. Additionally, we need a function that will add them to
the set of Guile primitives. Because this is just an example, we will
only implement this for the @code{j0} function, tho.
only implement this for the @code{j0} function.
Consider the following file @file{bessel.c}.
@ -729,7 +729,7 @@ guile -c '(write %load-path) (newline)'
Suppose you want to use the procedures and variables exported by the
module @code{(ice-9 popen)}, which provides the means for communicating
with other processes over pipes. Add the following line to your
currently running Guile REPL or the top of you script file.
currently running Guile REPL or the top of your script file.
@lisp
(use-modules (ice-9 popen))
@ -840,7 +840,7 @@ is the current one. Thus, the call to @code{scm_c_define_gsubr} will
put the new definition for @code{j0} into it, just as we want it.
The definitions made in the C code are not automatically exported from
a module. You need to explicitely list the ones you want to export in
a module. You need to explicitly list the ones you want to export in
@code{export} statements or with the @code{:export} option of
@code{define-module}.
@ -961,7 +961,7 @@ Of course, if the bug is that Guile gets a fatal signal, then one can't
miss it. But if the bug is incorrect results, the maintainer might fail
to notice what is wrong. Why leave it to chance?
If the manifestation of the bug is an Guile error message, it is
If the manifestation of the bug is a Guile error message, it is
important to report the precise text of the error message, and a
backtrace showing how the Scheme program arrived at the error.
@ -978,7 +978,7 @@ programs that you must load into Guile in order to cause the problem to
occur.
@item
If the problem does depend on an init file or other Lisp programs that
If the problem does depend on an init file or other Scheme programs that
are not part of the standard Guile distribution, then you should make
sure it is not a bug in those programs by complaining to their
maintainers first. After they verify that they are using Guile in a way
@ -988,7 +988,7 @@ that is supposed to work, they should report the bug.
If you wish to mention something in the Guile source, show the line of
code with a few lines of context. Don't just give a line number.
The line numbers in the development sources don't match those in your
The line numbers in the development sources might not match those in your
sources. It would take extra work for the maintainers to determine what
code is in your version at a given line number, and we could not be
certain.
@ -1001,8 +1001,7 @@ very long, and using GDB is easy. You can find the GDB distribution,
including the GDB manual in online form, in most of the same places you
can find the Guile distribution. To run Guile under GDB, you should
switch to the @file{libguile} subdirectory in which Guile was compiled, then
do @code{gdb .libs/guile}.
@c fixme: libguile/.libs is for libtool-enabled systems -- what about rest?
do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
However, you need to think when you collect the additional information
if you want it to show what causes the bug.

290
doc/ref/scheme-data.texi
View file

@ -52,8 +52,8 @@ sections of this manual that cover them.
* Pairs:: Scheme's basic building block.
* Lists:: Special list functions supported by Guile.
* Vectors:: One-dimensional arrays of Scheme objects.
* Records::
* Structures::
* Records::
* Structures::
* Arrays:: Arrays of values.
* Association Lists and Hash Tables:: Dictionary data types.
* Hooks:: User-customizable event lists.
@ -206,7 +206,7 @@ The @code{number?} predicate may be applied to any Scheme value to
discover whether the value is any of the supported numerical types.
@deffn primitive number? obj
Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
Return @code{#t} if @var{obj} is any kind of number, @code{#f} otherwise.
@end deffn
For example:
@ -276,7 +276,7 @@ completely invisible to the Scheme level programmer.
@c on the C level, where the conversion is not so automatic - NJ
@deffn primitive integer? x
Return @code{#t} if @var{x} is an integer number, @code{#f} else.
Return @code{#t} if @var{x} is an integer number, @code{#f} otherwise.
@lisp
(integer? 487)
@ -339,7 +339,7 @@ and in such a way that the new kinds of number integrate seamlessly
with those that are already implemented.
@deffn primitive real? obj
Return @code{#t} if @var{obj} is a real number, @code{#f} else.
Return @code{#t} if @var{obj} is a real number, @code{#f} otherwise.
Note that the sets of integer and rational values form subsets
of the set of real numbers, so the predicate will also be fulfilled
if @var{obj} is an integer number or a rational number.
@ -347,7 +347,7 @@ if @var{obj} is an integer number or a rational number.
@deffn primitive rational? x
Return @code{#t} if @var{x} is a rational number, @code{#f}
else. Note that the set of integer values forms a subset of
otherwise. Note that the set of integer values forms a subset of
the set of rational numbers, i. e. the predicate will also be
fulfilled if @var{x} is an integer number. Real numbers
will also satisfy this predicate, because of their limited
@ -386,7 +386,7 @@ properties of inexactness and limited precision as single real numbers.
@deffn primitive complex? x
Return @code{#t} if @var{x} is a complex number, @code{#f}
else. Note that the sets of real, rational and integer
otherwise. Note that the sets of real, rational and integer
values form subsets of the set of complex numbers, i. e. the
predicate will also be fulfilled if @var{x} is a real,
rational or integer number.
@ -418,7 +418,7 @@ otherwise.
@deffn primitive inexact? x
Return @code{#t} if @var{x} is an inexact number, @code{#f}
else.
otherwise.
@end deffn
@deffn primitive inexact->exact z
@ -1125,7 +1125,7 @@ the sum of whose squares is equal to 1.0.
Thinking of vect as coordinates in space of
dimension n = (vector-length vect), the coordinates
are uniformly distributed over the surface of the
unit n-shere.
unit n-sphere.
@end deffn
@deffn primitive random:normal [state]
@ -1146,7 +1146,7 @@ Fills vect with inexact real random numbers
the sum of whose squares is less than 1.0.
Thinking of vect as coordinates in space of
dimension n = (vector-length vect), the coordinates
are uniformly distributed within the unit n-shere.
are uniformly distributed within the unit n-sphere.
The sum of the squares of the numbers is returned.
@end deffn
@ -1389,7 +1389,7 @@ characters enclosed in double quotes (@code{"}). @footnote{Actually, the
current implementation restricts strings to a length of 2^24
characters.} If you want to insert a double quote character into a
string literal, it must be prefixed with a backslash @code{\} character
(called an @emph{escape character}).
(called an @dfn{escape character}).
The following are examples of string literals:
@ -1410,8 +1410,7 @@ fulfills some specified property.
@rnindex string?
@deffn primitive string? obj
Return @code{#t} iff @var{obj} is a string, else returns
@code{#f}.
Return @code{#t} iff @var{obj} is a string, else @code{#f}.
@end deffn
@deffn primitive string-null? str
@ -1522,9 +1521,9 @@ exact integers satisfying:
@node String Modification
@subsection String Modification
These procedures are for modifying strings in-place. That means, that
not a new string is the result of a string operation, but that the
actual memory representation of a string is modified.
These procedures are for modifying strings in-place. This means that the
result of the operation is not a new string; instead, the original string's
memory representation is modified.
@rnindex string-set!
@deffn primitive string-set! str k chr
@ -1821,7 +1820,7 @@ A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
describes a whole class of strings. A full description of regular
expressions and their syntax is beyond the scope of this manual;
an introduction can be found in the Emacs manual (@pxref{Regexps,
, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, or
, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
in many general Unix reference books.
If your system does not include a POSIX regular expression library, and
@ -2132,7 +2131,7 @@ to this cumbersome escape syntax.
@node Rx Interface
@subsection Rx Interface
@c FIXME::martin: Shouldn't this be removed or moved to the
@c FIXME::martin: Shouldn't this be removed or moved to the
@c ``Guile Modules'' chapter? The functions are not available in
@c plain Guile...
@ -2279,8 +2278,6 @@ Test whether obj is a compiled regular expression.
@node Symbols and Variables
@section Symbols and Variables
@c FIXME::martin: Review me!
Symbols are a data type with a special property. On the one hand,
symbols are used for denoting variables in a Scheme program, on the
other they can be used as literal data as well.
@ -2301,8 +2298,6 @@ be used for interacting with the module system.
@subsection Symbols
@tpindex Symbols
@c FIXME::martin: Review me!
Symbols are especially useful because two symbols which are spelled the
same way are equivalent in the sense of @code{eq?}. That means that
they are actually the same Scheme object. The advantage is that symbols
@ -2315,7 +2310,7 @@ association lists (@pxref{Association Lists}) or hash tables
lot, and does not cause any performance loss.
The read syntax for symbols is a sequence of letters, digits, and
@emph{extended alphabetic characters} that begins with a character that
@dfn{extended alphabetic characters} that begins with a character that
cannot begin a number is an identifier. In addition, @code{+},
@code{-}, and @code{...} are identifiers.
@ -2323,7 +2318,7 @@ Extended alphabetic characters may be used within identifiers as if
they were letters. The following are extended alphabetic characters:
@example
! $ % & * + - . / : < = > ? @@ ^ _ ~
! $ % & * + - . / : < = > ? @@ ^ _ ~
@end example
In addition to the read syntax defined above (which is taken from R5RS
@ -2417,8 +2412,6 @@ standard case is lower case:
@node Symbol Tables
@subsection Symbol Tables
@c FIXME::martin: Review me!
@c FIXME::martin: Are all these procedures still relevant?
Guile symbol tables are hash tables. Each hash table, also called an
@ -2428,14 +2421,6 @@ Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
table (with an undefined value) if none is yet present.
@c FIXME::martin: According to NEWS, removed. Remove here too, or
@c leave for compatibility?
@c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
@c @deffn primitive builtin-bindings
@c Create and return a copy of the global symbol table, removing all
@c unbound symbols.
@c @end deffn
@deffn primitive gensym [prefix]
Create a new symbol with a name constructed from a prefix and
a counter value. The string @var{prefix} can be specified as
@ -2522,8 +2507,6 @@ otherwise.
@subsection Variables
@tpindex Variables
@c FIXME::martin: Review me!
Variables are objects with two fields. They contain a value and they
can contain a symbol, which is the name of the variable. A variable is
said to be bound if it does not contain the object denoting unbound
@ -2766,8 +2749,6 @@ ABORT: (unbound-variable)
@node Keyword Procedures
@subsection Keyword Procedures
@c FIXME::martin: Review me!
The following procedures can be used for converting symbols to keywords
and back.
@ -2814,12 +2795,10 @@ This is the inverse of @code{make-keyword-from-dash-symbol}.
@section Pairs
@tpindex Pairs
@c FIXME::martin: Review me!
Pairs are used to combine two Scheme objects into one compound object.
Hence the name: A pair stores a pair of objects.
The data type @emph{pair} is extremely important in Scheme, just like in
The data type @dfn{pair} is extremely important in Scheme, just like in
any other Lisp dialect. The reason is that pairs are not only used to
make two values available as one object, but that pairs are used for
constructing lists of values. Because lists are so important in Scheme,
@ -2856,7 +2835,7 @@ examples is as follows.
A new pair is made by calling the procedure @code{cons} with two
arguments. Then the argument values are stored into a newly allocated
pair, and the pair is returned. The name @code{cons} stands for
@emph{construct}. Use the procedure @code{pair?} to test whether a
"construct". Use the procedure @code{pair?} to test whether a
given Scheme object is a pair or not.
@rnindex cons
@ -2872,8 +2851,8 @@ Return @code{#t} if @var{x} is a pair; otherwise return
@code{#f}.
@end deffn
The two parts of a pair are traditionally called @emph{car} and
@emph{cdr}. They can be retrieved with procedures of the same name
The two parts of a pair are traditionally called @dfn{car} and
@dfn{cdr}. They can be retrieved with procedures of the same name
(@code{car} and @code{cdr}), and can be modified with the procedures
@code{set-car!} and @code{set-cdr!}. Since a very common operation in
Scheme programs is to access the car of a pair, or the car of the cdr of
@ -2916,12 +2895,10 @@ by @code{set-cdr!} is unspecified.
@section Lists
@tpindex Lists
@c FIXME::martin: Review me!
A very important data type in Scheme---as well as in all other Lisp
dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
Scheme does not have a real datatype @emph{list}. Lists are made up of
chained @emph{pairs}, and only exist by definition---a list is a chain
Scheme does not have a real datatype @dfn{list}. Lists are made up of
@dfn{chained pairs}, and only exist by definition---a list is a chain
of pairs which looks like a list.}
This is the short definition of what a list is:
@ -2939,7 +2916,7 @@ or a pair which has a list in its cdr.
@c FIXME::martin: What is a proper, what an improper list?
@c What is a circular list?
@c FIXME::martin: Maybe steal some graphics from the Elisp reference
@c FIXME::martin: Maybe steal some graphics from the Elisp reference
@c manual?
@menu
@ -2948,7 +2925,7 @@ or a pair which has a list in its cdr.
* List Constructors:: Creating new lists.
* List Selection:: Selecting from lists, getting their length.
* Append/Reverse:: Appending and reversing lists.
* List Modifification:: Modifying list structure.
* List Modification:: Modifying existing lists.
* List Searching:: Searching for list elements
* List Mapping:: Applying procedures to lists.
@end menu
@ -2956,8 +2933,6 @@ or a pair which has a list in its cdr.
@node List Syntax
@subsection List Read Syntax
@c FIXME::martin: Review me!
The syntax for lists is an opening parentheses, then all the elements of
the list (separated by whitespace) and finally a closing
parentheses.@footnote{Note that there is no separation character between
@ -2991,8 +2966,6 @@ applications (@pxref{Simple Invocation}).
@node List Predicates
@subsection List Predicates
@c FIXME::martin: Review me!
Often it is useful to test whether a given Scheme object is a list or
not. List-processing procedures could use this information to test
whether their input is valid, or they could do different things
@ -3006,7 +2979,7 @@ Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
The predicate @code{null?} is often used in list-processing code to
tell whether a given list has run out of elements. That is, a loop
somehow deals with the elements of a list until the list satisfies
@code{null?}. Then, teh algorithm terminates.
@code{null?}. Then, the algorithm terminates.
@rnindex null?
@deffn primitive null? x
@ -3057,8 +3030,6 @@ use the procedure @code{copy-tree} (@pxref{Copying}).
@node List Selection
@subsection List Selection
@c FIXME::martin: Review me!
These procedures are used to get some information about a list, or to
retrieve one or more elements of a list.
@ -3096,8 +3067,6 @@ return it.
@node Append/Reverse
@subsection Append and Reverse
@c FIXME::martin: Review me!
@code{append} and @code{append!} are used to concatenate two or more
lists in order to form a new list. @code{reverse} and @code{reverse!}
return lists with the same elements as their arguments, but in reverse
@ -3154,14 +3123,11 @@ of the modified list is not lost, it is wise to save the return value of
@code{reverse!}
@end deffn
@node List Modifification
@node List Modification
@subsection List Modification
@c FIXME::martin: Review me!
The following procedures modify existing list. @code{list-set!} and
@code{list-cdr-set!} change which elements a list contains, the various
deletion procedures @code{delq}, @code{delv} etc.
The following procedures modify an existing list, either by changing
elements of the list, or by changing the list structure itself.
@deffn primitive list-set! list k val
Set the @var{k}th element of @var{list} to @var{val}.
@ -3224,11 +3190,9 @@ Like @code{delete!}, but only deletes the first occurrence of
@node List Searching
@subsection List Searching
@c FIXME::martin: Review me!
The following procedures search lists for particular elements. They use
different comparison predicates for comparing list elements with the
object to be seached. When they fail, they return @code{#f}, otherwise
object to be searched. When they fail, they return @code{#f}, otherwise
they return the sublist whose car is equal to the search object, where
equality depends on the equality predicate used.
@ -3262,7 +3226,7 @@ the non-empty lists returned by @code{(list-tail @var{lst}
empty list) is returned.
@end deffn
[FIXME: is there any reason to have the `sloppy' functions available at
[FIXME: Is there any reason to have the `sloppy' functions available at
high level at all? Maybe these docs should be relegated to a "Guile
Internals" node or something. -twp]
@ -3287,14 +3251,12 @@ not for high-level Scheme programs.
@node List Mapping
@subsection List Mapping
@c FIXME::martin: Review me!
List processing is very convenient in Scheme because the process of
iterating over the elements of a list can be highly abstracted. The
procedures in this section are the most basic iterating procedures for
lists. They take a procedure and one or more lists as arguments, and
apply the procedure to each element of the list. They differ in what
the result of the invocation is.
apply the procedure to each element of the list. They differ in their
return value.
@rnindex map
@c begin (texi-doc-string "guile" "map")
@ -3322,20 +3284,17 @@ return value is not specified.
@section Vectors
@tpindex Vectors
@c FIXME::martin: Review me!
@c FIXME::martin: Should the subsections of this section be nodes
@c of their own, or are the resulting nodes too short, then?
Vectors are sequences of Scheme objects. Unlike lists, the length of a
vector, once the vector is created, cannot be changed. The advantage of
vectors over lists is that the time required to access one element of a
vector is constant, whereas lists have an access time linear to the
index of the accessed element in the list.
vectors over lists is that the time required to access one element of a vector
given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
is constant, whereas lists have an access time linear to the position of the
accessed element in the list.
Note that the vectors documented in this section can contain any kind of
Scheme object, it is even possible to have different types of objects in
the same vector.
Vectors can contain any kind of Scheme object; it is even possible to have
different types of objects in the same vector. For vectors containing
vectors, you may wish to use arrays, instead. Note, too, that some array
procedures operate happily on vectors (@pxref{Arrays}).
@subsection Vector Read Syntax
@ -3346,7 +3305,7 @@ parentheses, all elements of the vector in their respective read syntax,
and finally a closing parentheses. The following are examples of the
read syntax for vectors; where the first vector only contains numbers
and the second three different object types: a string, a symbol and a
number in hexidecimal notation.
number in hexadecimal notation.
@lisp
#(1 2 3)
@ -3366,8 +3325,8 @@ Return @code{#t} if @var{obj} is a vector, otherwise return
@rnindex make-vector
@deffn primitive make-vector k [fill]
Return a newly allocated vector of @var{k} elements. If a
second argument is given, then each element is initialized to
@var{fill}. Otherwise the initial contents of each element is
second argument is given, then each position is initialized to
@var{fill}. Otherwise the initial contents of each position are
unspecified.
@end deffn
@ -3375,8 +3334,8 @@ unspecified.
@rnindex list->vector
@deffn primitive vector . l
@deffnx primitive list->vector l
Return a newly allocated vector whose elements contain the
given arguments. Analogous to @code{list}.
Return a newly allocated vector composed of the given arguments.
Analogous to @code{list}.
@lisp
(vector 'a 'b 'c) @result{} #(a b c)
@ -3385,8 +3344,7 @@ given arguments. Analogous to @code{list}.
@rnindex vector->list
@deffn primitive vector->list v
Return a newly allocated list of the objects contained in the
elements of @var{vector}.
Return a newly allocated list composed of the elements of @var{v}.
@lisp
(vector->list '#(dah dah didah)) @result{} (dah dah didah)
@ -3400,35 +3358,37 @@ A vector created by any of the vector constructor procedures
(@pxref{Vectors}) documented above can be modified using the
following procedures.
According to R5RS, using any of these procedures on literally entered
vectors is an error, because these vectors are considered to be
constant, although Guile currently does not detect this error.
@emph{NOTE:} According to R5RS, using any of these procedures on
literally entered vectors is an error, because these vectors are
considered to be constant, although Guile currently does not detect this
error.
@rnindex vector-set!
@deffn primitive vector-set! vector k obj
Store @var{obj} in position @var{k} of @var{vector}.
@var{k} must be a valid index of @var{vector}.
@code{Vector-set!} stores @var{obj} in element @var{k} of @var{vector}.
The value returned by @samp{vector-set!} is unspecified.
@lisp
(let ((vec (vector 0 '(2 2 2 2) "Anna")))
(vector-set! vec 1 '("Sue" "Sue"))
vec) @result{} #(0 ("Sue" "Sue") "Anna")
(vector-set! '#(0 1 2) 1 "doe") @result{} @emph{error} ; constant vector
@end lisp
@end deffn
@rnindex vector-fill!
@deffn primitive vector-fill! v fill
Store @var{fill} in every element of @var{vector}. The value
Store @var{fill} in every position of @var{vector}. The value
returned by @code{vector-fill!} is unspecified.
@end deffn
@deffn primitive vector-move-left! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-left!}.
Vector version of @code{substring-move-left!} (@pxref{String
Modification}).
@end deffn
@deffn primitive vector-move-right! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-right!}.
Vector version of @code{substring-move-right!} (@pxref{String
Modification}).
@end deffn
@subsection Vector Selection
@ -3438,14 +3398,13 @@ size or what elements are contained in the vector.
@rnindex vector-length
@deffn primitive vector-length vector
Returns the number of elements in @var{vector} as an exact integer.
Return the number of elements in @var{vector} as an exact integer.
@end deffn
@rnindex vector-ref
@deffn primitive vector-ref vector k
Return the contents of position @var{k} of @var{vector}.
@var{k} must be a valid index of @var{vector}.
@samp{Vector-ref} returns the contents of element @var{k} of
@var{vector}.
@lisp
(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
(vector-ref '#(1 1 2 3 5 8 13 21)
@ -3460,14 +3419,11 @@ Returns the number of elements in @var{vector} as an exact integer.
@node Records
@section Records
[FIXME: this is pasted in from Tom Lord's original guile.texi and should
be reviewed]
A @dfn{record type} is a first class object representing a user-defined
data type. A @dfn{record} is an instance of a record type.
@deffn procedure record? obj
Returns @code{#t} if @var{obj} is a record of any type and @code{#f}
Return @code{#t} if @var{obj} is a record of any type and @code{#f}
otherwise.
Note that @code{record?} may be true of any Scheme value; there is no
@ -3475,17 +3431,17 @@ promise that records are disjoint with other Scheme types.
@end deffn
@deffn procedure make-record-type type-name field-names
Returns a @dfn{record-type descriptor}, a value representing a new data
Return a @dfn{record-type descriptor}, a value representing a new data
type disjoint from all others. The @var{type-name} argument must be a
string, but is only used for debugging purposes (such as the printed
representation of a record of the new type). The @var{field-names}
argument is a list of symbols naming the @dfn{fields} of a record of the
new type. It is an error if the list contains any duplicates. It is
unspecified how record-type descriptors are represented.@refill
unspecified how record-type descriptors are represented.
@end deffn
@deffn procedure record-constructor rtd [field-names]
Returns a procedure for constructing new members of the type represented
Return a procedure for constructing new members of the type represented
by @var{rtd}. The returned procedure accepts exactly as many arguments
as there are symbols in the given list, @var{field-names}; these are
used, in order, as the initial values of those fields in a new record,
@ -3494,28 +3450,28 @@ fields not named in that list are unspecified. The @var{field-names}
argument defaults to the list of field names in the call to
@code{make-record-type} that created the type represented by @var{rtd};
if the @var{field-names} argument is provided, it is an error if it
contains any duplicates or any symbols not in the default list.@refill
contains any duplicates or any symbols not in the default list.
@end deffn
@deffn procedure record-predicate rtd
Returns a procedure for testing membership in the type represented by
Return a procedure for testing membership in the type represented by
@var{rtd}. The returned procedure accepts exactly one argument and
returns a true value if the argument is a member of the indicated record
type; it returns a false value otherwise.@refill
type; it returns a false value otherwise.
@end deffn
@deffn procedure record-accessor rtd field-name
Returns a procedure for reading the value of a particular field of a
Return a procedure for reading the value of a particular field of a
member of the type represented by @var{rtd}. The returned procedure
accepts exactly one argument which must be a record of the appropriate
type; it returns the current value of the field named by the symbol
@var{field-name} in that record. The symbol @var{field-name} must be a
member of the list of field-names in the call to @code{make-record-type}
that created the type represented by @var{rtd}.@refill
that created the type represented by @var{rtd}.
@end deffn
@deffn procedure record-modifier rtd field-name
Returns a procedure for writing the value of a particular field of a
Return a procedure for writing the value of a particular field of a
member of the type represented by @var{rtd}. The returned procedure
accepts exactly two arguments: first, a record of the appropriate type,
and second, an arbitrary Scheme value; it modifies the field named by
@ -3523,31 +3479,31 @@ the symbol @var{field-name} in that record to contain the given value.
The returned value of the modifier procedure is unspecified. The symbol
@var{field-name} must be a member of the list of field-names in the call
to @code{make-record-type} that created the type represented by
@var{rtd}.@refill
@var{rtd}.
@end deffn
@deffn procedure record-type-descriptor record
Returns a record-type descriptor representing the type of the given
Return a record-type descriptor representing the type of the given
record. That is, for example, if the returned descriptor were passed to
@code{record-predicate}, the resulting predicate would return a true
value when passed the given record. Note that it is not necessarily the
case that the returned descriptor is the one that was passed to
@code{record-constructor} in the call that created the constructor
procedure that created the given record.@refill
procedure that created the given record.
@end deffn
@deffn procedure record-type-name rtd
Returns the type-name associated with the type represented by rtd. The
Return the type-name associated with the type represented by rtd. The
returned value is @code{eqv?} to the @var{type-name} argument given in
the call to @code{make-record-type} that created the type represented by
@var{rtd}.@refill
@var{rtd}.
@end deffn
@deffn procedure record-type-fields rtd
Returns a list of the symbols naming the fields in members of the type
Return a list of the symbols naming the fields in members of the type
represented by @var{rtd}. The returned value is @code{equal?} to the
field-names argument given in the call to @code{make-record-type} that
created the type represented by @var{rtd}.@refill
created the type represented by @var{rtd}.
@end deffn
@ -3671,7 +3627,7 @@ A pair object in which the first field is held constant could be:
"prpw"
@end example
Binary fields, (fields of type "u"), hold one @emph{word} each. The
Binary fields, (fields of type "u"), hold one @dfn{word} each. The
size of a word is a machine dependent value defined to be equal to the
value of the C expression: @code{sizeof (long)}.
@ -3885,7 +3841,7 @@ Return the vtable tag of the structure @var{handle}.
@node Conventional Arrays
@subsection Conventional Arrays
@dfn{Conventional arrays} are a collection of cells organised into an
@dfn{Conventional arrays} are a collection of cells organized into an
arbitrary number of dimensions. Each cell can hold any kind of Scheme
value and can be accessed in constant time by supplying an index for
each dimension. This contrasts with uniform arrays, which use memory
@ -3894,7 +3850,7 @@ where inserting and deleting cells is more efficient, but more time
is usually required to access a particular cell.
A conventional array is displayed as @code{#} followed by the @dfn{rank}
(number of dimensions) followed by the cells, organised into dimensions
(number of dimensions) followed by the cells, organized into dimensions
using parentheses. The nesting depth of the parentheses is equal to
the rank.
@ -3932,8 +3888,13 @@ and is described elsewhere.
@end deffn
@deffn procedure make-array initial-value bound1 bound2 @dots{}
Creates and returns an array that has as many dimensions as there are
@var{bound}s and fills it with @var{initial-value}.
Create and return an array that has as many dimensions as there are
@var{bound}s and fill it with @var{initial-value}. Each @var{bound}
may be a positive non-zero integer @var{N}, in which case the index for
that dimension can range from 0 through @var{N-1}; or an explicit index
range specifier in the form @code{(LOWER UPPER)}, where both @var{lower}
and @var{upper} are integers, possibly less than zero, and possibly the
same number (however, @var{lower} cannot be greater than @var{upper}).
@end deffn
@c array-ref's type is `compiled-closure'. There's some weird stuff
@ -3950,9 +3911,10 @@ Return @code{#t} if its arguments would be acceptable to
@code{array-ref}.
@end deffn
@c fixme: why do these sigs differ? -ttn 2001/07/19 01:14:12
@deffn primitive array-set! v obj . args
@deffnx primitive uniform-array-set1! v obj args
Sets the element at the @code{(index1, index2)} element in @var{array} to
Set the element at the @code{(index1, index2)} element in @var{array} to
@var{new-value}. The value returned by array-set! is unspecified.
@end deffn
@ -4033,7 +3995,7 @@ examples:
@end deffn
@deffn procedure array-shape array
Returns a list of inclusive bounds of integers.
Return a list of inclusive bounds of integers.
@example
(array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
@end example
@ -4059,20 +4021,20 @@ Return a list consisting of all the elements, in order, of
@deffn primitive array-copy! src dst
@deffnx primitive array-copy-in-order! src dst
Copies every element from vector or array @var{source} to the
Copy every element from vector or array @var{source} to the
corresponding element of @var{destination}. @var{destination} must have
the same rank as @var{source}, and be at least as large in each
dimension. The order is unspecified.
@end deffn
@deffn primitive array-fill! ra fill
Stores @var{fill} in every element of @var{array}. The value returned
Store @var{fill} in every element of @var{array}. The value returned
is unspecified.
@end deffn
@c begin (texi-doc-string "guile" "array-equal?")
@deffn primitive array-equal? ra0 ra1
Returns @code{#t} iff all arguments are arrays with the same shape, the
Return @code{#t} iff all arguments are arrays with the same shape, the
same type, and have corresponding elements which are either
@code{equal?} or @code{array-equal?}. This function differs from
@code{equal?} in that a one dimensional shared array may be
@ -4083,7 +4045,7 @@ same type, and have corresponding elements which are either
@deffnx primitive array-contents array strict
If @var{array} may be @dfn{unrolled} into a one dimensional shared array
without changing their order (last subscript changing fastest), then
@code{array-contents} returns that shared array, otherwise it returns
@code{array-contents} return that shared array, otherwise return
@code{#f}. All arrays made by @var{make-array} and
@var{make-uniform-array} may be unrolled, some arrays made by
@var{make-shared-array} may not be.
@ -4107,12 +4069,12 @@ unspecified. The order of application is unspecified.
@end deffn
@deffn primitive array-for-each proc ra0 . lra
@var{proc} is applied to each tuple of elements of @var{array0} @dots{}
Apply @var{proc} to each tuple of elements of @var{array0} @dots{}
in row-major order. The value returned is unspecified.
@end deffn
@deffn primitive array-index-map! ra proc
applies @var{proc} to the indices of each element of @var{array} in
Apply @var{proc} to the indices of each element of @var{array} in
turn, storing the result in the corresponding element. The value
returned and the order of application are unspecified.
@ -4190,16 +4152,16 @@ except that a single character from the above table is put between
long integers is displayed in the form @code{'#e(3 5 9)}.
@deffn primitive array? v [prot]
Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
Return @code{#t} if the @var{obj} is an array, and @code{#f} if not.
The @var{prototype} argument is used with uniform arrays and is described
elsewhere.
@end deffn
@deffn procedure make-uniform-array prototype bound1 bound2 @dots{}
Creates and returns a uniform array of type corresponding to
Create and return a uniform array of type corresponding to
@var{prototype} that has as many dimensions as there are @var{bound}s
and fills it with @var{prototype}.
and fill it with @var{prototype}.
@end deffn
@deffn primitive array-prototype ra
@ -4217,7 +4179,7 @@ done.
@end deffn
@deffn primitive uniform-vector-fill! uve fill
Stores @var{fill} in every element of @var{uve}. The value returned is
Store @var{fill} in every element of @var{uve}. The value returned is
unspecified.
@end deffn
@ -4237,7 +4199,7 @@ fill the array, otherwise @var{prototype} is used.
@deffn primitive uniform-array-read! ra [port_or_fd [start [end]]]
@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]
Attempts to read all elements of @var{ura}, in lexicographic order, as
Attempt to read all elements of @var{ura}, in lexicographic order, as
binary objects from @var{port-or-fdes}.
If an end of file is encountered during
uniform-array-read! the objects up to that point only are put into @var{ura}
@ -4255,7 +4217,7 @@ returned by @code{(current-input-port)}.
@deffn primitive uniform-array-write v [port_or_fd [start [end]]]
@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]
Writes all elements of @var{ura} as binary objects to
Write all elements of @var{ura} as binary objects to
@var{port-or-fdes}.
The optional arguments @var{start}
@ -4299,7 +4261,7 @@ within the specified range @code{#f} is returned.
@end deffn
@deffn primitive bit-invert! v
Modifies @var{bv} by replacing each element with its negation.
Modify @var{bv} by replacing each element with its negation.
@end deffn
@deffn primitive bit-set*! v kv obj
@ -4406,12 +4368,12 @@ because association lists are so useful, Guile also provides specific
procedures for manipulating them.
@menu
* Alist Key Equality::
* Adding or Setting Alist Entries::
* Retrieving Alist Entries::
* Removing Alist Entries::
* Sloppy Alist Functions::
* Alist Example::
* Alist Key Equality::
* Adding or Setting Alist Entries::
* Retrieving Alist Entries::
* Removing Alist Entries::
* Sloppy Alist Functions::
* Alist Example::
@end menu
@node Alist Key Equality
@ -4544,7 +4506,7 @@ use @code{list-copy} to copy the old association list before modifying
it.
@deffn primitive acons key value alist
Adds a new key-value pair to @var{alist}. A new pair is
Add a new key-value pair to @var{alist}. A new pair is
created whose car is @var{key} and whose cdr is @var{value}, and the
pair is consed onto @var{alist}, and the new list is returned. This
function is @emph{not} destructive; @var{alist} is not modified.
@ -4578,12 +4540,12 @@ is @code{(KEY . VALUE)}, not just the value.
@deffn primitive assq key alist
@deffnx primitive assv key alist
@deffnx primitive assoc key alist
Fetches the entry in @var{alist} that is associated with @var{key}. To
Fetch the entry in @var{alist} that is associated with @var{key}. To
decide whether the argument @var{key} matches a particular entry in
@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
cannot be found in @var{alist} (according to whichever equality
predicate is in use), then @code{#f} is returned. These functions
predicate is in use), then return @code{#f}. These functions
return the entire alist entry found (i.e. both the key and the value).
@end deffn
@ -5128,13 +5090,13 @@ arguments. When the procedures have been added, we can invoke them
using @code{run-hook}.
@lisp
(add-hook! hook (lambda (x y)
(display "Foo: ")
(display (+ x y))
(add-hook! hook (lambda (x y)
(display "Foo: ")
(display (+ x y))
(newline)))
(add-hook! hook (lambda (x y)
(display "Bar: ")
(display (* x y))
(add-hook! hook (lambda (x y)
(display "Bar: ")
(display (* x y))
(newline)))
(run-hook hook 3 4)
@print{} Bar: 12
@ -5146,14 +5108,14 @@ added. This can be changed by providing the optional third argument
on the second call to @code{add-hook!}.
@lisp
(add-hook! hook (lambda (x y)
(display "Foo: ")
(display (+ x y))
(add-hook! hook (lambda (x y)
(display "Foo: ")
(display (+ x y))
(newline)))
(add-hook! hook (lambda (x y)
(display "Bar: ")
(display (* x y))
(newline))
(add-hook! hook (lambda (x y)
(display "Bar: ")
(display (* x y))
(newline))
#t) ; @r{<- Change here!}
(run-hook hook 3 4)
@print{} Foo: 7

26
doc/ref/scheme-debug.texi
View file

@ -139,30 +139,8 @@ Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be
either a debug object or a continuation).
@var{args} should be a list containing any combination of
integer, procedure and @code{#t} values.
These values specify various ways of cutting away uninteresting
stack frames from the top and bottom of the stack that
@code{make-stack} returns. They come in pairs like this:
@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
@var{outer_cut_2} @dots{})}.
Each @var{inner_cut_N} can be @code{#t}, an integer, or a
procedure. @code{#t} means to cut away all frames up to but
excluding the first user module frame. An integer means to cut
away exactly that number of frames. A procedure means to cut
away all frames up to but excluding the application frame whose
procedure matches the specified one.
Each @var{outer_cut_N} can be an integer or a procedure. An
integer means to cut away that number of frames. A procedure
means to cut away frames down to but excluding the application
frame whose procedure matches the specified one.
If the @var{outer_cut_N} of the last pair is missing, it is
taken as 0.
@var{args} must be a list of integers and specifies how the
resulting stack will be narrowed.
@end deffn
@deffn primitive stack-id stack

2
doc/ref/scheme-evaluation.texi
View file

@ -352,7 +352,7 @@ is implicit).
The behaviour of Guile's evaluator can be modified by manipulating the
evaluator options. For more information about options, @xref{General
option interface}. If you want to know which evaluator options are
option interface}. If you want to know which reader options are
available, @xref{Evaluator options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there

6
doc/ref/scheme-ideas.texi
View file

@ -188,9 +188,9 @@ of an existing variable.
@code{define} syntax that can be used when defining new procedures.
@item
REFFIXME, to read about an alternative form of the @code{set!} syntax
that helps with changing a single value in the depths of a compound data
structure.)
@ref{Procedures with Setters}, to read about an alternative form of the
@code{set!} syntax that helps with changing a single value in the depths
of a compound data structure.)
@end itemize

2
doc/ref/scheme-modules.texi
View file

@ -698,7 +698,7 @@ module @samp{(math bessel)}. First we need to write the appropriate
glue code to convert the arguments and return values of the functions
from Scheme to C and back. Additionally, we need a function that will
add them to the set of Guile primitives. Because this is just an
example, we will only implement this for the @code{j0} function, tho.
example, we will only implement this for the @code{j0} function.
@c FIXME::martin: Change all gh_ references to their scm_ equivalents.

58
doc/ref/scheme-options.texi
View file

@ -20,7 +20,6 @@ configure @emph{reading}, @emph{printing}, @emph{debugging} or
* Printing options::
* Debugger options::
* Evaluator options::
* Evaluator trap options::
* Examples of option use::
* Install Config:: Installation and configuration data.
@end menu
@ -154,6 +153,7 @@ closure-hook #f Hook for printing closures.
@node Evaluator options
@section Evaluator options
These are the evaluator options with their default values, as they are
printed by typing @code{(eval-options 'full)} in Guile.
@ -161,12 +161,6 @@ printed by typing @code{(eval-options 'full)} in Guile.
stack 22000 Size of thread stacks (in machine words).
@end smallexample
@node Evaluator trap options
@section Evaluator trap options
[FIXME: These flags, together with their corresponding handlers, are not
user level options. Probably this entire section should be moved to the
documentation about the low-level programmer debugging interface.]
Here is the list of evaluator trap options generated by typing
@code{(traps 'full)} in Guile. You can also see the default values.
@ -174,58 +168,8 @@ Here is the list of evaluator trap options generated by typing
exit-frame no Trap when exiting eval or apply.
apply-frame no Trap when entering apply.
enter-frame no Trap when eval enters new frame.
traps yes Enable evaluator traps.
@end smallexample
@deffn apply-frame-handler key cont tailp
Called when a procedure is being applied.
Called if:
@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{apply-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize
If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.
@var{tailp} is true if this is a tail call
@end deffn
@deffn exit-frame-handler key cont retval
Called when a value is returned from a procedure.
Called if:
@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{exit-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize
If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.
@var{retval} is the return value.
@end deffn
@node Debugger options
@section Debugger options

10
doc/ref/scm.texi
View file

@ -4,8 +4,6 @@
@c - according to the menu in guile.texi - NJ 2001/1/26
@chapter Relationship between Scheme and C functions
@c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
Scheme procedures marked "primitive functions" have a regular interface
when calling from C, reflected in two areas: the name of a C function, and
the convention for passing non-required arguments to this function.
@ -78,7 +76,7 @@ Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
(">=" . "_geq")
("<" . "_less")
(">" . "_gr")
("@" . "at"))))
("@@" . "at"))))
(while transforms
(let ((trigger (concat "\\(.*\\)"
(regexp-quote (caar transforms))
@ -233,9 +231,9 @@ All of the elements of the ptob, apart from @code{name}, are procedures
which collectively implement the port behaviour. Creating a new port
type mostly involves writing these procedures.
@code{scm_make_port_type} initialises three elements of the structure
@code{scm_make_port_type} initializes three elements of the structure
(@code{name}, @code{fill_input} and @code{write}) from its arguments.
The remaining elements are initialised with default values and can be
The remaining elements are initialized with default values and can be
set later if required.
@table @code
@ -456,3 +454,5 @@ Exception handlers can also be installed from C, using
scm_internal_catch, scm_lazy_catch, or scm_stack_catch from
libguile/throw.c. These have not yet been documented, however the
source contains some useful comments.
@c scm.texi ends here

0
doc/repl-modules.texi
View file

0
doc/scheme-binding.texi
View file

0
doc/scheme-control.texi
View file

5192
doc/scheme-data.texi
View file

File diff suppressed because it is too large Load diff

165
doc/scheme-debug.texi
View file

@ -1,165 +0,0 @@
@page
@node Debugging
@chapter Internal Debugging Interface
--- The name of this chapter needs to clearly distinguish it
from the appendix describing the debugger UI. The intro
should have a pointer to the UI appendix.
@deffn primitive display-error stack port subr message args rest
Display an error message to the output port @var{port}.
@var{stack} is the saved stack for the error, @var{subr} is
the name of the procedure in which the error occured and
@var{message} is the actual error message, which may contain
formatting instructions. These will format the arguments in
the list @var{args} accordingly. @var{rest} is currently
ignored.
@end deffn
@deffn primitive display-application frame [port [indent]]
Display a procedure application @var{frame} to the output port
@var{port}. @var{indent} specifies the indentation of the
output.
@end deffn
@deffn primitive display-backtrace stack port [first [depth]]
Display a backtrace to the output port @var{port}. @var{stack}
is the stack to take the backtrace from, @var{first} specifies
where in the stack to start and @var{depth} how much frames
to display. Both @var{first} and @var{depth} can be @code{#f},
which means that default values will be used.
@end deffn
@deffn primitive backtrace
Display a backtrace of the stack saved by the last error
to the current output port.
@end deffn
@deffn primitive malloc-stats
Return an alist ((@var{what} . @var{n}) ...) describing number
of malloced objects.
@var{what} is the second argument to @code{scm_must_malloc},
@var{n} is the number of objects of that type currently
allocated.
@end deffn
@deffn primitive debug-options-interface [setting]
Option interface for the debug options. Instead of using
this procedure directly, use the procedures @code{debug-enable},
@code{debug-disable}, @code{debug-set!} and @var{debug-options}.
@end deffn
@deffn primitive with-traps thunk
Call @var{thunk} with traps enabled.
@end deffn
@deffn primitive memoized? obj
Return @code{#t} if @var{obj} is memoized.
@end deffn
@deffn primitive unmemoize m
Unmemoize the memoized expression @var{m},
@end deffn
@deffn primitive memoized-environment m
Return the environment of the memoized expression @var{m}.
@end deffn
@deffn primitive procedure-name proc
Return the name of the procedure @var{proc}
@end deffn
@deffn primitive procedure-source proc
Return the source of the procedure @var{proc}.
@end deffn
@deffn primitive procedure-environment proc
Return the environment of the procedure @var{proc}.
@end deffn
@deffn primitive debug-object? obj
Return @code{#t} if @var{obj} is a debug object.
@end deffn
@deffn primitive frame-arguments frame
Return the arguments of @var{frame}.
@end deffn
@deffn primitive frame-evaluating-args? frame
Return @code{#t} if @var{frame} contains evaluated arguments.
@end deffn
@deffn primitive frame-next frame
Return the next frame of @var{frame}, or @code{#f} if
@var{frame} is the last frame in its stack.
@end deffn
@deffn primitive frame-number frame
Return the frame number of @var{frame}.
@end deffn
@deffn primitive frame-overflow? frame
Return @code{#t} if @var{frame} is an overflow frame.
@end deffn
@deffn primitive frame-previous frame
Return the previous frame of @var{frame}, or @code{#f} if
@var{frame} is the first frame in its stack.
@end deffn
@deffn primitive frame-procedure frame
Return the procedure for @var{frame}, or @code{#f} if no
procedure is associated with @var{frame}.
@end deffn
@deffn primitive frame-procedure? frame
Return @code{#t} if a procedure is associated with @var{frame}.
@end deffn
@deffn primitive frame-real? frame
Return @code{#t} if @var{frame} is a real frame.
@end deffn
@deffn primitive frame-source frame
Return the source of @var{frame}.
@end deffn
@deffn primitive frame? obj
Return @code{#t} if @var{obj} is a stack frame.
@end deffn
@deffn primitive last-stack-frame obj
Return a stack which consists of a single frame, which is the
last stack frame for @var{obj}. @var{obj} must be either a
debug object or a continuation.
@end deffn
@deffn primitive make-stack obj . args
Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be
either a debug object or a continuation).
@var{args} must be a list of integers and specifies how the
resulting stack will be narrowed.
@end deffn
@deffn primitive stack-id stack
Return the identifier given to @var{stack} by @code{start-stack}.
@end deffn
@deffn primitive stack-length stack
Return the length of @var{stack}.
@end deffn
@deffn primitive stack-ref stack i
Return the @var{i}'th frame from @var{stack}.
@end deffn
@deffn primitive stack? obj
Return @code{#t} if @var{obj} is a calling stack.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

419
doc/scheme-evaluation.texi
View file

@ -1,419 +0,0 @@
@page
@node Read/Load/Eval
@chapter Reading and Evaluating Scheme Code
This chapter describes Guile functions that are concerned with reading,
loading and evaluating Scheme code at run time.
@menu
* Scheme Syntax:: Standard and extended Scheme syntax.
* Scheme Read:: Reading Scheme code.
* Fly Evaluation:: Procedures for on the fly evaluation.
* Loading:: Loading Scheme code from file.
* Delayed Evaluation:: Postponing evaluation until it is needed.
* Local Evaluation:: Evaluation in a local environment.
* Evaluator Behaviour:: Modifying Guile's evaluator.
@end menu
@node Scheme Syntax
@section Scheme Syntax: Standard and Guile Extensions
@menu
* Expression Syntax::
* Comments::
* Block Comments::
* Case Sensitivity::
* Keyword Syntax::
* Reader Extensions::
@end menu
@node Expression Syntax
@subsection Expression Syntax
@node Comments
@subsection Comments
@c FIXME::martin: Review me!
Comments in Scheme source files are written by starting them with a
semicolon character (@code{;}). The comment then reaches up to the end
of the line. Comments can begin at any column, and the may be inserted
on the same line as Scheme code.
@lisp
; Comment
;; Comment too
(define x 1) ; Comment after expression
(let ((y 1))
;; Display something.
(display y)
;;; Comment at left margin.
(display (+ y 1)))
@end lisp
It is common to use a single semicolon for comments following
expressions on a line, to use two semicolons for comments which are
indented like code, and three semicolons for comments which start at
column 0, even if they are inside an indented code block. This
convention is used when indenting code in Emacs' Scheme mode.
@node Block Comments
@subsection Block Comments
@c FIXME::martin: Review me!
@cindex multiline comments
In addition to the standard line comments defined by R5RS, Guile has
another comment type for multiline comments, called @dfn{block
comments}. This type of comment begins with the character sequence
@code{#!} and ends with the characters @code{!#}, which must appear on a
line of their own. These comments are compatible with the block
comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
(scsh)}). The characters @code{#!} were chosen because they are the
magic characters used in shell scripts for indicating that the name of
the program for executing the script follows on the same line.
Thus a Guile script often starts like this.
@lisp
#! /usr/local/bin/guile -s
!#
@end lisp
More details on Guile scripting can be found in the scripting section
(@pxref{Guile Scripting}).
@node Case Sensitivity
@subsection Case Sensitivity
@c FIXME::martin: Review me!
Scheme as defined in R5RS is not case sensitive when reading symbols.
Guile, on the contrary is case sensitive by default, so the identifiers
@lisp
guile-whuzzy
Guile-Whuzzy
@end lisp
are the same in R5RS Scheme, but are different in Guile.
It is possible to turn off case sensitivity in Guile by setting the
reader option @code{case-insensitive}. More on reader options can be
found at (@pxref{Reader options}).
@lisp
(read-enable 'case-insensitive)
@end lisp
Note that this is seldom a problem, because Scheme programmers tend not
to use uppercase letters in their identifiers anyway.
@node Keyword Syntax
@subsection Keyword Syntax
@node Reader Extensions
@subsection Reader Extensions
@deffn primitive read-hash-extend chr proc
Install the procedure @var{proc} for reading expressions
starting with the character sequence @code{#} and @var{chr}.
@var{proc} will be called with two arguments: the character
@var{chr} and the port to read further data from. The object
returned will be the return value of @code{read}.
@end deffn
@node Scheme Read
@section Reading Scheme Code
@rnindex read
@deffn primitive read [port]
Read an s-expression from the input port @var{port}, or from
the current input port if @var{port} is not specified.
Any whitespace before the next token is discarded.
@end deffn
The behaviour of Guile's Scheme reader can be modified by manipulating
its read options. For more information about options, @xref{General
option interface}. If you want to know which reader options are
available, @xref{Reader options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there
@c actually a difference between 'help and 'full?
@deffn procedure read-options [setting]
Display the current settings of the read options. If @var{setting} is
omitted, only a short form of the current read options is printed.
Otherwise, @var{setting} should be one of the following symbols:
@table @code
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn
@deffn procedure read-enable option-name
@deffnx procedure read-disable option-name
@deffnx procedure read-set! option-name value
Modify the read options. @code{read-enable} should be used with boolean
options and switches them on, @code{read-disable} switches them off.
@code{read-set!} can be used to set an option to a specific value.
@end deffn
@deffn primitive read-options-interface [setting]
Option interface for the read options. Instead of using
this procedure directly, use the procedures @code{read-enable},
@code{read-disable}, @code{read-set!} and @code{read-options}.
@end deffn
@node Fly Evaluation
@section Procedures for On the Fly Evaluation
@rnindex eval
@c ARGFIXME environment/environment specifier
@deffn primitive eval exp environment
Evaluate @var{exp}, a list representing a Scheme expression, in the
environment given by @var{environment specifier}.
@end deffn
@rnindex interaction-environment
@deffn primitive interaction-environment
Return a specifier for the environment that contains
implementation--defined bindings, typically a superset of those
listed in the report. The intent is that this procedure will
return the environment in which the implementation would
evaluate expressions dynamically typed by the user.
@end deffn
@deffn primitive eval-string string
Evaluate @var{string} as the text representation of a Scheme
form or forms, and return whatever value they produce.
Evaluation takes place in the environment returned by the
procedure @code{interaction-environment}.
@end deffn
@deffn primitive apply:nconc2last lst
Given a list (@var{arg1} @dots{} @var{args}), this function
conses the @var{arg1} @dots{} arguments onto the front of
@var{args}, and returns the resulting list. Note that
@var{args} is a list; thus, the argument to this function is
a list whose last element is a list.
Note: Rather than do new consing, @code{apply:nconc2last}
destroys its argument, so use with care.
@end deffn
@rnindex apply
@deffn primitive apply proc arg1 @dots{} args
@var{proc} must be a procedure and @var{args} must be a list. Call
@var{proc} with the elements of the list @code{(append (list @var{arg1}
@dots{}) @var{args})} as the actual arguments.
@end deffn
@deffn primitive primitive-eval exp
Evaluate @var{exp} in the top-level environment specified by
the current module.
@end deffn
@deffn primitive eval2 obj env_thunk
Evaluate @var{exp}, a Scheme expression, in the environment
designated by @var{lookup}, a symbol-lookup function.
Do not use this version of eval, it does not play well
with the module system. Use @code{eval} or
@code{primitive-eval} instead.
@end deffn
@deffn primitive read-and-eval! [port]
Read a form from @var{port} (standard input by default), and evaluate it
(memoizing it in the process) in the top-level environment. If no data
is left to be read from @var{port}, an @code{end-of-file} error is
signalled.
@end deffn
@node Loading
@section Loading Scheme Code from File
@rnindex load
@deffn procedure load filename
Load @var{filename} and evaluate its contents in the top-level
environment. The load paths are not searched. If the variable
@code{%load-hook} is defined, it should be bound to a procedure that
will be called before any code is loaded. See documentation for
@code{%load-hook} later in this section.
@end deffn
@deffn procedure load-from-path filename
Similar to @code{load}, but searches for @var{filename} in the load
paths.
@end deffn
@deffn primitive primitive-load filename
Load the file named @var{filename} and evaluate its contents in
the top-level environment. The load paths are not searched;
@var{filename} must either be a full pathname or be a pathname
relative to the current directory. If the variable
@code{%load-hook} is defined, it should be bound to a procedure
that will be called before any code is loaded. See the
documentation for @code{%load-hook} later in this section.
@end deffn
@deffn primitive primitive-load-path filename
Search @var{%load-path} for the file named @var{filename} and
load it into the top-level environment. If @var{filename} is a
relative pathname and is not found in the list of search paths,
an error is signalled.
@end deffn
@deffn primitive %search-load-path filename
Search @var{%load-path} for the file named @var{filename},
which must be readable by the current user. If @var{filename}
is found in the list of paths to search or is an absolute
pathname, return its full pathname. Otherwise, return
@code{#f}. Filenames may have any of the optional extensions
in the @code{%load-extensions} list; @code{%search-load-path}
will try each extension automatically.
@end deffn
@defvar %load-hook
A procedure to be run whenever @code{primitive-load} is called. If this
procedure is defined, it will be called with the filename argument that
was passed to @code{primitive-load}.
@example
(define %load-hook (lambda (file)
(display "Loading ")
(display file)
(write-line "...."))) @result{} undefined
(load-from-path "foo.scm")
@print{} Loading /usr/local/share/guile/site/foo.scm....
@end example
@end defvar
@deffn primitive current-load-port
Return the current-load-port.
The load port is used internally by @code{primitive-load}.
@end deffn
@defvar %load-extensions
A list of default file extensions for files containing Scheme code.
@code{%search-load-path} tries each of these extensions when looking for
a file to load. By default, @code{%load-extensions} is bound to the
list @code{("" ".scm")}.
@end defvar
@node Delayed Evaluation
@section Delayed Evaluation
[delay]
@deffn primitive promise? obj
Return true if @var{obj} is a promise, i.e. a delayed computation
(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
@end deffn
@rnindex force
@deffn primitive force x
If the promise @var{x} has not been computed yet, compute and
return @var{x}, otherwise just return the previously computed
value.
@end deffn
@node Local Evaluation
@section Local Evaluation
[the-environment]
@deffn primitive local-eval exp [env]
Evaluate @var{exp} in its environment. If @var{env} is supplied,
it is the environment in which to evaluate @var{exp}. Otherwise,
@var{exp} must be a memoized code object (in which case, its environment
is implicit).
@end deffn
@node Evaluator Behaviour
@section Evaluator Behaviour
@c FIXME::martin: Maybe this node name is bad, but the old name clashed with
@c `Evaluator options' under `Options and Config'.
The behaviour of Guile's evaluator can be modified by manipulating the
evaluator options. For more information about options, @xref{General
option interface}. If you want to know which reader options are
available, @xref{Evaluator options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there
@c actually a difference between 'help and 'full?
@deffn procedure eval-options [setting]
Display the current settings of the evaluator options. If @var{setting}
is omitted, only a short form of the current evaluator options is
printed. Otherwise, @var{setting} should be one of the following
symbols:
@table @code
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn
@deffn procedure eval-enable option-name
@deffnx procedure eval-disable option-name
@deffnx procedure eval-set! option-name value
Modify the evaluator options. @code{eval-enable} should be used with boolean
options and switches them on, @code{eval-disable} switches them off.
@code{eval-set!} can be used to set an option to a specific value.
@end deffn
@deffn primitive eval-options-interface [setting]
Option interface for the evaluation options. Instead of using
this procedure directly, use the procedures @code{eval-enable},
@code{eval-disable}, @code{eval-set!} and @code{eval-options}.
@end deffn
@c FIXME::martin: Why aren't these procedure named like the other options
@c procedures?
@deffn procedure traps [setting]
Display the current settings of the evaluator traps options. If
@var{setting} is omitted, only a short form of the current evaluator
traps options is printed. Otherwise, @var{setting} should be one of the
following symbols:
@table @code
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn
@deffn procedure trap-enable option-name
@deffnx procedure trap-disable option-name
@deffnx procedure trap-set! option-name value
Modify the evaluator options. @code{trap-enable} should be used with boolean
options and switches them on, @code{trap-disable} switches them off.
@code{trap-set!} can be used to set an option to a specific value.
@end deffn
@deffn primitive evaluator-traps-interface [setting]
Option interface for the evaluator trap options.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

1458
doc/scheme-ideas.texi
View file

File diff suppressed because it is too large Load diff

0
doc/scheme-indices.texi
View file

0
doc/scheme-intro.texi
View file

0
doc/scheme-io.texi
View file

0
doc/scheme-memory.texi
View file

826
doc/scheme-modules.texi
View file

@ -1,826 +0,0 @@
@page
@node Modules
@chapter Modules
@cindex modules
When programs become large, naming conflicts can occur when a function
or global variable defined in one file has the same name as a function
or global variable in another file. Even just a @emph{similarity}
between function names can cause hard-to-find bugs, since a programmer
might type the wrong function name.
The approach used to tackle this problem is called @emph{information
encapsulation}, which consists of packaging functional units into a
given name space that is clearly separated from other name spaces.
@cindex encapsulation
@cindex information encapsulation
@cindex name space
The language features that allow this are usually called @emph{the
module system} because programs are broken up into modules that are
compiled separately (or loaded separately in an interpreter).
Older languages, like C, have limited support for name space
manipulation and protection. In C a variable or function is public by
default, and can be made local to a module with the @code{static}
keyword. But you cannot reference public variables and functions from
another module with different names.
More advanced module systems have become a common feature in recently
designed languages: ML, Python, Perl, and Modula 3 all allow the
@emph{renaming} of objects from a foreign module, so they will not
clutter the global name space.
@cindex name space - private
@menu
* Scheme and modules:: How modules are handled in standard Scheme.
* The Guile module system:: How Guile does it.
* Dynamic Libraries:: Loading libraries of compiled code at run time.
@end menu
@node Scheme and modules
@section Scheme and modules
Scheme, as defined in R5RS, does @emph{not} have a module system at all.
Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
implemented a provide/require mechanism for many Scheme implementations.
Library files in SLIB @emph{provide} a feature, and when user programs
@emph{require} that feature, the library file is loaded in.
For example, the file @file{random.scm} in the SLIB package contains the
line
@smalllisp
(provide 'random)
@end smalllisp
so to use its procedures, a user would type
@smalllisp
(require 'random)
@end smalllisp
and they would magically become available, @emph{but still have the same
names!} So this method is nice, but not as good as a full-featured
module system.
@node The Guile module system
@section The Guile module system
In 1996 Tom Lord implemented a full-featured module system for Guile which
allows loading Scheme source files into a private name space. This system has
been in available since Guile version 1.4.
@c fixme: Actually, was it available before? 1.4 seems a bit late...
For Guile version 1.5.0 and later, the system has been improved to have better
integration from C code, more fine-grained user control over interfaces, and
documentation.
Although it is anticipated that the module system implementation will
change in the future, the Scheme programming interface described in this
manual should be considered stable. The C programming interface is
considered relatively stable, although at the time of this writing,
there is still some flux.
@c fixme: Review: Need better C code interface commentary.
@menu
* General Information about Modules:: Guile module basics.
* Using Guile Modules:: How to use existing modules.
* Creating Guile Modules:: How to package your code into modules.
* More Module Procedures:: Low-level module code.
* Module System Quirks:: Strange things to be aware of.
* Included Guile Modules:: Which modules come with Guile?
@end menu
@node General Information about Modules
@subsection General Information about Modules
A Guile module is a collection of named procedures, variables and
macros, altogether called the @dfn{bindings}, since they bind, or
associate, a symbol (the name) to a Scheme object (procedure, variable,
or macro). Within a module, all bindings are visible. Certain bindings
can be declared @dfn{public}, in which case they are added to the
module's so-called @dfn{export list}; this set of public bindings is
called the module's @dfn{public interface} (@pxref{Creating Guile
Modules}).
A client module @dfn{uses} a providing module's bindings by either
accessing the providing module's public interface, or by building a
custom interface (and then accessing that). In a custom interface, the
client module can @dfn{select} which bindings to access and can also
algorithmically @dfn{rename} bindings. In contrast, when using the
providing module's public interface, the entire export list is available
without renaming (@pxref{Using Guile Modules}).
To use a module, it must be found and loaded. All Guile modules have a
unique @dfn{module name}, which is a list of one or more symbols.
Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile
searches for the code of a module, it constructs the name of the file to
load by concatenating the name elements with slashes between the
elements and appending a number of file name extensions from the list
@code{%load-extensions} (REFFIXME). The resulting file name is then
searched in all directories in the variable @code{%load-path}. For
example, the @code{(ice-9 popen)} module would result in the filename
@code{ice-9/popen.scm} and searched in the installation directory of
Guile and in all other directories in the load path.
@c FIXME::martin: Not sure about this, maybe someone knows better?
Every module has a so-called syntax transformer associated with it.
This is a procedure which performs all syntax transformation for the
time the module is read in and evaluated. When working with modules,
you can manipulate the current syntax transformer using the
@code{use-syntax} syntactic form or the @code{#:use-syntax} module
definition option (@pxref{Creating Guile Modules}).
Please note that there are some problems with the current module system
you should keep in mind (@pxref{Module System Quirks}). We hope to
address these eventually.
@node Using Guile Modules
@subsection Using Guile Modules
To use a Guile module is to access either its public interface or a
custom interface (@pxref{General Information about Modules}). Both
types of access are handled by the syntactic form @code{use-modules},
which accepts one or more interface specifications and, upon evaluation,
arranges for those interfaces to be available to the current module.
This process may include locating and loading code for a given module if
that code has not yet been loaded (REFFIXME %load-path).
An @dfn{interface specification} has one of two forms. The first
variation is simply to name the module, in which case its public
interface is the one accessed. For example:
@smalllisp
(use-modules (ice-9 popen))
@end smalllisp
Here, the interface specification is @code{(ice-9 popen)}, and the
result is that the current module now has access to @code{open-pipe},
@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included
Guile Modules}).
Note in the previous example that if the current module had already
defined @code{open-pipe}, that definition would be overwritten by the
definition in @code{(ice-9 popen)}. For this reason (and others), there
is a second variation of interface specification that not only names a
module to be accessed, but also selects bindings from it and renames
them to suit the current module's needs. For example:
@smalllisp
(use-modules ((ice-9 popen)
:select ((open-pipe . pipe-open) close-pipe)
:rename (symbol-prefix-proc 'unixy:)))
@end smalllisp
Here, the interface specification is more complex than before, and the
result is that a custom interface with only two bindings is created and
subsequently accessed by the current module. The mapping of old to new
names is as follows:
@c Use `smallexample' since `table' is ugly. --ttn
@smallexample
(ice-9 popen) sees: current module sees:
open-pipe unixy:pipe-open
close-pipe unixy:close-pipe
@end smallexample
This example also shows how to use the convenience procedure
@code{symbol-prefix-proc}.
@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
@deffn procedure symbol-prefix-proc prefix-sym
Return a procedure that prefixes its arg (a symbol) with
@var{prefix-sym}.
@c Insert gratuitous C++ slam here. --ttn
@end deffn
@c begin (scm-doc-string "boot-9.scm" "use-modules")
@deffn syntax use-modules spec @dots{}
Resolve each interface specification @var{spec} into an interface and
arrange for these to be accessible by the current module. The return
value is unspecified.
@var{spec} can be a list of symbols, in which case it names a module
whose public interface is found and used.
@var{spec} can also be of the form:
@smalllisp
(MODULE-NAME [:select SELECTION] [:rename RENAMER])
@end smalllisp
in which case a custom interface is newly created and used.
@var{module-name} is a list of symbols, as above; @var{selection} is a
list of selection-specs; and @var{renamer} is a procedure that takes a
symbol and returns its new name. A selection-spec is either a symbol or
a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
the used module and @var{seen} is the name in the using module. Note
that @var{seen} is also passed through @var{renamer}.
The @code{:select} and @code{:rename} clauses are optional. If both are
omitted, the returned interface has no bindings. If the @code{:select}
clause is omitted, @var{renamer} operates on the used module's public
interface.
Signal error if module name is not resolvable.
@end deffn
@c FIXME::martin: Is this correct, and is there more to say?
@c FIXME::martin: Define term and concept `system transformer' somewhere.
@deffn syntax use-syntax module-name
Load the module @code{module-name} and use its system
transformer as the system transformer for the currently defined module,
as well as installing it as the current system transformer.
@end deffn
@node Creating Guile Modules
@subsection Creating Guile Modules
When you want to create your own modules, you have to take the following
steps:
@itemize @bullet
@item
Create a Scheme source file and add all variables and procedures you wish
to export, or which are required by the exported procedures.
@item
Add a @code{define-module} form at the beginning.
@item
Export all bindings which should be in the public interface, either
by using @code{define-public} or @code{export} (both documented below).
@end itemize
@c begin (scm-doc-string "boot-9.scm" "define-module")
@deffn syntax define-module module-name [options @dots{}]
@var{module-name} is of the form @code{(hierarchy file)}. One
example of this is
@smalllisp
(define-module (ice-9 popen))
@end smalllisp
@code{define-module} makes this module available to Guile programs under
the given @var{module-name}.
The @var{options} are keyword/value pairs which specify more about the
defined module. The recognized options and their meaning is shown in
the following table.
@c fixme: Should we use "#:" or ":"?
@table @code
@item #:use-module @var{interface-specification}
Equivalent to a @code{(use-modules @var{interface-specification})}
(@pxref{Using Guile Modules}).
@item #:use-syntax @var{module}
Use @var{module} when loading the currently defined module, and install
it as the syntax transformer.
@item #:autoload @var{module} @var{symbol}
Load @var{module} whenever @var{symbol} is accessed.
@item #:export @var{list}
Export all identifiers in @var{list}, which must be a list of symbols.
This is equivalent to @code{(export @var{list})} in the module body.
@item #:no-backtrace
Tell Guile not to record information for procedure backtraces when
executing the procedures in this module.
@item #:pure
Create a @dfn{pure} module, that is a module which does not contain any
of the standard procedure bindings except for the syntax forms. This is
useful if you want to create @dfn{safe} modules, that is modules which
do not know anything about dangerous procedures.
@end table
@end deffn
@c end
@deffn syntax export variable @dots{}
Add all @var{variable}s (which must be symbols) to the list of exported
bindings of the current module.
@end deffn
@c begin (scm-doc-string "boot-9.scm" "define-public")
@deffn syntax define-public @dots{}
Equivalent to @code{(begin (define foo ...) (export foo))}.
@end deffn
@c end
@node More Module Procedures
@subsection More Module Procedures
@c FIXME::martin: Review me!
@c FIXME::martin: Should this procedure be documented and supported
@c at all?
The procedures in this section are useful if you want to dig into the
innards of Guile's module system. If you don't know precisely what you
do, you should probably avoid using any of them.
@deffn primitive standard-eval-closure module
Return an eval closure for the module @var{module}.
@end deffn
@node Module System Quirks
@subsection Module System Quirks
Although the programming interfaces are relatively stable, the Guile
module system itself is still evolving. Here are some situations where
usage surpasses design.
@itemize @bullet
@item
When using a module which exports a macro definition, the other module
must export all bindings the macro expansion uses, too, because the
expanded code would otherwise not be able to see these definitions and
issue a ``variable unbound'' error, or worse, would use another binding
which might be present in the scope of the expansion.
@item
When two or more used modules export bindings with the same names, the
last accessed module wins, and the exported binding of that last module
will silently be used. This might lead to hard-to-find errors because
wrong procedures or variables are used. To avoid this kind of
@dfn{name-clash} situation, use a custom interface specification
(@pxref{Using Guile Modules}). (We include this entry for the possible
benefit of users of Guile versions previous to 1.5.0, when custom
interfaces were added to the module system.)
@item
[Add other quirks here.]
@end itemize
@node Included Guile Modules
@subsection Included Guile Modules
@c FIXME::martin: Review me!
Some modules are included in the Guile distribution; here are references
to the entries in this manual which describe them in more detail:
@table @strong
@item boot-9
boot-9 is Guile's initialization module, and it is always loaded when
Guile starts up.
@item (ice-9 debug)
Mikael Djurfeldt's source-level debugging support for Guile
(@pxref{Debugger User Interface}).
@item (ice-9 threads)
Guile's support for multi threaded execution (@pxref{Scheduling}).
@item (ice-9 rdelim)
Line- and character-delimited input (@pxref{Line/Delimited}).
@item (ice-9 rw)
Block string input/output (@pxref{Block Reading and Writing}).
@item (ice-9 documentation)
Online documentation (REFFIXME).
@item (srfi srfi-1)
A library providing a lot of useful list and pair processing
procedures (@pxref{SRFI-1}).
@item (srfi srfi-2)
Support for @code{and-let*} (@pxref{SRFI-2}).
@item (srfi srfi-4)
Support for homogeneous numeric vectors (@pxref{SRFI-4}).
@item (srfi srfi-6)
Support for some additional string port procedures (@pxref{SRFI-6}).
@item (srfi srfi-8)
Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
@item (srfi srfi-9)
Record definition with @code{define-record-type} (@pxref{SRFI-9}).
@item (srfi srfi-10)
Read hash extension @code{#,()} (@pxref{SRFI-10}).
@item (srfi srfi-11)
Multiple-value handling with @code{let-values} and @code{let-values*}
(@pxref{SRFI-11}).
@item (srfi srfi-13)
String library (@pxref{SRFI-13}).
@item (srfi srfi-14)
Character-set library (@pxref{SRFI-14}).
@item (srfi srfi-17)
Getter-with-setter support (@pxref{SRFI-17}).
@item (ice-9 slib)
This module contains hooks for using Aubrey Jaffer's portable Scheme
library SLIB from Guile (@pxref{SLIB}).
@c FIXME::martin: This module is not in the distribution. Remove it
@c from here?
@item (ice-9 jacal)
This module contains hooks for using Aubrey Jaffer's symbolic math
packge Jacal from Guile (@pxref{JACAL}).
@end table
@node Dynamic Libraries
@section Dynamic Libraries
Most modern Unices have something called @dfn{shared libraries}. This
ordinarily means that they have the capability to share the executable
image of a library between several running programs to save memory and
disk space. But generally, shared libraries give a lot of additional
flexibility compared to the traditional static libraries. In fact,
calling them `dynamic' libraries is as correct as calling them `shared'.
Shared libraries really give you a lot of flexibility in addition to the
memory and disk space savings. When you link a program against a shared
library, that library is not closely incorporated into the final
executable. Instead, the executable of your program only contains
enough information to find the needed shared libraries when the program
is actually run. Only then, when the program is starting, is the final
step of the linking process performed. This means that you need not
recompile all programs when you install a new, only slightly modified
version of a shared library. The programs will pick up the changes
automatically the next time they are run.
Now, when all the necessary machinery is there to perform part of the
linking at run-time, why not take the next step and allow the programmer
to explicitly take advantage of it from within his program? Of course,
many operating systems that support shared libraries do just that, and
chances are that Guile will allow you to access this feature from within
your Scheme programs. As you might have guessed already, this feature
is called @dfn{dynamic linking}@footnote{Some people also refer to the
final linking stage at program startup as `dynamic linking', so if you
want to make yourself perfectly clear, it is probably best to use the
more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
in his libtool documentation.}
As with many aspects of Guile, there is a low-level way to access the
dynamic linking apparatus, and a more high-level interface that
integrates dynamically linked libraries into the module system.
@menu
* Low level dynamic linking::
* Compiled Code Modules::
* Dynamic Linking and Compiled Code Modules::
@end menu
@node Low level dynamic linking
@subsection Low level dynamic linking
When using the low level procedures to do your dynamic linking, you have
complete control over which library is loaded when and what get's done
with it.
@deffn primitive dynamic-link library
Find the shared library denoted by @var{library} (a string) and link it
into the running Guile application. When everything works out, return a
Scheme object suitable for representing the linked object file.
Otherwise an error is thrown. How object files are searched is system
dependent.
Normally, @var{library} is just the name of some shared library file
that will be searched for in the places where shared libraries usually
reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
@end deffn
@deffn primitive dynamic-object? val
Determine whether @var{val} represents a dynamically linked object file.
@end deffn
@deffn primitive dynamic-unlink dynobj
Unlink the indicated object file from the application. The argument
@var{dynobj} should be one of the values returned by
@code{dynamic-link}. When @code{dynamic-unlink} has been called on
@var{dynobj}, it is no longer usable as an argument to the functions
below and you will get type mismatch errors when you try to.
@end deffn
@deffn primitive dynamic-func function dynobj
Search the C function indicated by @var{function} (a string or symbol)
in @var{dynobj} and return some Scheme object that can later be used
with @code{dynamic-call} to actually call this function. Right now,
these Scheme objects are formed by casting the address of the function
to @code{long} and converting this number to its Scheme representation.
Regardless whether your C compiler prepends an underscore @samp{_} to
the global names in a program, you should @strong{not} include this
underscore in @var{function}. Guile knows whether the underscore is
needed or not and will add it when necessary.
@end deffn
@deffn primitive dynamic-call function dynobj
Call the C function indicated by @var{function} and @var{dynobj}. The
function is passed no arguments and its return value is ignored. When
@var{function} is something returned by @code{dynamic-func}, call that
function and ignore @var{dynobj}. When @var{function} is a string (or
symbol, etc.), look it up in @var{dynobj}; this is equivalent to
@smallexample
(dynamic-call (dynamic-func @var{function} @var{dynobj} #f))
@end smallexample
Interrupts are deferred while the C function is executing (with
@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
@end deffn
@deffn primitive dynamic-args-call function dynobj args
Call the C function indicated by @var{function} and @var{dynobj}, just
like @code{dynamic-call}, but pass it some arguments and return its
return value. The C function is expected to take two arguments and
return an @code{int}, just like @code{main}:
@smallexample
int c_func (int argc, char **argv);
@end smallexample
The parameter @var{args} must be a list of strings and is converted into
an array of @code{char *}. The array is passed in @var{argv} and its
size in @var{argc}. The return value is converted to a Scheme number
and returned from the call to @code{dynamic-args-call}.
@end deffn
When dynamic linking is disabled or not supported on your system,
the above functions throw errors, but they are still available.
Here is a small example that works on GNU/Linux:
@smallexample
(define libc-obj (dynamic-link "libc.so"))
libc-obj
@result{} #<dynamic-object "libc.so">
(dynamic-args-call 'rand libc-obj '())
@result{} 269167349
(dynamic-unlink libc-obj)
libc-obj
@result{} #<dynamic-object "libc.so" (unlinked)>
@end smallexample
As you can see, after calling @code{dynamic-unlink} on a dynamically
linked library, it is marked as @samp{(unlinked)} and you are no longer
able to use it with @code{dynamic-call}, etc. Whether the library is
really removed from you program is system-dependent and will generally
not happen when some other parts of your program still use it. In the
example above, @code{libc} is almost certainly not removed from your
program because it is badly needed by almost everything.
The functions to call a function from a dynamically linked library,
@code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
They are mostly intended to be used for calling specially written
initialization functions that will then add new primitives to Guile.
For example, we do not expect that you will dynamically link
@file{libX11} with @code{dynamic-link} and then construct a beautiful
graphical user interface just by using @code{dynamic-call} and
@code{dynamic-args-call}. Instead, the usual way would be to write a
special Guile<->X11 glue library that has intimate knowledge about both
Guile and X11 and does whatever is necessary to make them inter-operate
smoothly. This glue library could then be dynamically linked into a
vanilla Guile interpreter and activated by calling its initialization
function. That function would add all the new types and primitives to
the Guile interpreter that it has to offer.
From this setup the next logical step is to integrate these glue
libraries into the module system of Guile so that you can load new
primitives into a running system just as you can load new Scheme code.
There is, however, another possibility to get a more thorough access to
the functions contained in a dynamically linked library. Anthony Green
has written @file{libffi}, a library that implements a @dfn{foreign
function interface} for a number of different platforms. With it, you
can extend the Spartan functionality of @code{dynamic-call} and
@code{dynamic-args-call} considerably. There is glue code available in
the Guile contrib archive to make @file{libffi} accessible from Guile.
@node Compiled Code Modules
@subsection Putting Compiled Code into Modules
@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
The new primitives that you add to Guile with @code{gh_new_procedure}
or with any of the other mechanisms are normally placed into the same
module as all the other builtin procedures (like @code{display}).
However, it is also possible to put new primitives into their own
module.
The mechanism for doing so is not very well thought out and is likely to
change when the module system of Guile itself is revised, but it is
simple and useful enough to document it as it stands.
What @code{gh_new_procedure} and the functions used by the snarfer
really do is to add the new primitives to whatever module is the
@emph{current module} when they are called. This is analogous to the
way Scheme code is put into modules: the @code{define-module} expression
at the top of a Scheme source file creates a new module and makes it the
current module while the rest of the file is evaluated. The
@code{define} expressions in that file then add their new definitions to
this current module.
Therefore, all we need to do is to make sure that the right module is
current when calling @code{gh_new_procedure} for our new primitives.
Unfortunately, there is not yet an easy way to access the module system
from C, so we are better off with a more indirect approach. Instead of
adding our primitives at initialization time we merely register with
Guile that we are ready to provide the contents of a certain module,
should it ever be needed.
@deftypefun void scm_register_module_xxx (char *@var{name}, void (*@var{initfunc})(void))
Register with Guile that @var{initfunc} will provide the contents of the
module @var{name}.
The function @var{initfunc} should perform the usual initialization
actions for your new primitives, like calling @code{gh_new_procedure} or
including the file produced by the snarfer. When @var{initfunc} is
called, the current module is a newly created module with a name as
indicated by @var{name}. Each definition that is added to it will be
automatically exported.
The string @var{name} indicates the hierachical name of the new module.
It should consist of the individual components of the module name
separated by single spaces. That is, the Scheme module name @code{(foo
bar)}, which is a list, should be written as @code{"foo bar"} for the
@var{name} parameter.
You can call @code{scm_register_module_xxx} at any time, even before
Guile has been initialized. This might be useful when you want to put
the call to it in some initialization code that is magically called
before main, like constructors for global C++ objects.
An example for @code{scm_register_module_xxx} appears in the next section.
@end deftypefun
Now, instead of calling the initialization function at program startup,
you should simply call @code{scm_register_module_xxx} and pass it the
initialization function. When the named module is later requested by
Scheme code with @code{use-modules} for example, Guile will notice that
it knows how to create this module and will call the initialization
function at the right time in the right context.
@node Dynamic Linking and Compiled Code Modules
@subsection Dynamic Linking and Compiled Code Modules
The most interesting application of dynamically linked libraries is
probably to use them for providing @emph{compiled code modules} to
Scheme programs. As much fun as programming in Scheme is, every now and
then comes the need to write some low-level C stuff to make Scheme even
more fun.
Not only can you put these new primitives into their own module (see the
previous section), you can even put them into a shared library that is
only then linked to your running Guile image when it is actually
needed.
An example will hopefully make everything clear. Suppose we want to
make the Bessel functions of the C library available to Scheme in the
module @samp{(math bessel)}. First we need to write the appropriate
glue code to convert the arguments and return values of the functions
from Scheme to C and back. Additionally, we need a function that will
add them to the set of Guile primitives. Because this is just an
example, we will only implement this for the @code{j0} function.
@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
@smallexample
#include <math.h>
#include <guile/gh.h>
SCM
j0_wrapper (SCM x)
@{
return gh_double2scm (j0 (gh_scm2double (x)));
@}
void
init_math_bessel ()
@{
gh_new_procedure1_0 ("j0", j0_wrapper);
@}
@end smallexample
We can already try to bring this into action by manually calling the low
level functions for performing dynamic linking. The C source file needs
to be compiled into a shared library. Here is how to do it on
GNU/Linux, please refer to the @code{libtool} documentation for how to
create dynamically linkable libraries portably.
@smallexample
gcc -shared -o libbessel.so -fPIC bessel.c
@end smallexample
Now fire up Guile:
@smalllisp
(define bessel-lib (dynamic-link "./libbessel.so"))
(dynamic-call "init_math_bessel" bessel-lib)
(j0 2)
@result{} 0.223890779141236
@end smalllisp
The filename @file{./libbessel.so} should be pointing to the shared
library produced with the @code{gcc} command above, of course. The
second line of the Guile interaction will call the
@code{init_math_bessel} function which in turn will register the C
function @code{j0_wrapper} with the Guile interpreter under the name
@code{j0}. This function becomes immediately available and we can call
it from Scheme.
Fun, isn't it? But we are only half way there. This is what
@code{apropos} has to say about @code{j0}:
@smallexample
(apropos 'j0)
@print{} the-root-module: j0 #<primitive-procedure j0>
@end smallexample
As you can see, @code{j0} is contained in the root module, where all
the other Guile primitives like @code{display}, etc live. In general,
a primitive is put into whatever module is the @dfn{current module} at
the time @code{gh_new_procedure} is called. To put @code{j0} into its
own module named @samp{(math bessel)}, we need to make a call to
@code{scm_register_module_xxx}. Additionally, to have Guile perform
the dynamic linking automatically, we need to put @file{libbessel.so}
into a place where Guile can find it. The call to
@code{scm_register_module_xxx} should be contained in a specially
named @dfn{module init function}. Guile knows about this special name
and will call that function automatically after having linked in the
shared library. For our example, we add the following code to
@file{bessel.c}:
@smallexample
void scm_init_math_bessel_module ()
@{
scm_register_module_xxx ("math bessel", init_math_bessel);
@}
@end smallexample
The general pattern for the name of a module init function is:
@samp{scm_init_}, followed by the name of the module where the
individual hierarchical components are concatenated with underscores,
followed by @samp{_module}. It should call
@code{scm_register_module_xxx} with the correct module name and the
appropriate initialization function. When that initialization function
will be called, a newly created module with the right name will be the
@emph{current module} so that all definitions that the initialization
functions makes will end up in the correct module.
After @file{libbessel.so} has been rebuild, we need to place the shared
library into the right place. When Guile tries to autoload the
@samp{(math bessel)} module, it looks not only for a file called
@file{math/bessel.scm} in its @code{%load-path}, but also for
@file{math/libbessel.so}. So all we need to do is to create a directory
called @file{math} somewhere in Guile's @code{%load-path} and place
@file{libbessel.so} there. Normally, the current directory @file{.} is
in the @code{%load-path}, so we just use that for this example.
@smallexample
% mkdir maths
% cd maths
% ln -s ../libbessel.so .
% cd ..
% guile
guile> (use-modules (math bessel))
guile> (j0 2)
0.223890779141236
guile> (apropos 'j0)
@print{} bessel: j0 #<primitive-procedure j0>
@end smallexample
That's it!
Note that we used a symlink to make @file{libbessel.so} appear in the
right spot. This is probably not a bad idea in general. The
directories that the @file{%load-path} normally contains are supposed to
contain only architecture independent files. They are not really the
right place for a shared library. You might want to install the
libraries somewhere below @samp{exec_prefix} and then symlink to them
from the architecture independent directory. This will at least work on
heterogenous systems where the architecture dependent stuff resides in
the same place on all machines (which seems like a good idea to me
anyway).
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

342
doc/scheme-options.texi
View file

@ -1,342 +0,0 @@
@page
@node Options and Config
@chapter Runtime Options and Configuration
Guile's behaviour can be modified by setting options. For example, is
the language that Guile accepts case sensitive, or should the debugger
automatically show a backtrace on error?
Guile has two levels of interface for managing options: a low-level
control interface, and a user-level interface which allows the enabling
or disabling of options.
Moreover, the options are classified in groups according to whether they
configure @emph{reading}, @emph{printing}, @emph{debugging} or
@emph{evaluating}.
@menu
* General option interface::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Examples of option use::
* Install Config:: Installation and configuration data.
@end menu
@node General option interface
@section General option interface
We will use the expression @code{<group>} to represent @code{read},
@code{print}, @code{debug} or @code{evaluator}.
@subheading Low level
@c NJFIXME
@deffn primitive <group>-options-interface
@deffnx primitive read-options-interface [SOME-INT]
@deffnx primitive print-options-interface [SOME-INT]
@deffnx primitive evaluator-traps-interface [SOME-INT]
@deffnx primitive read-options-interface [SOME-INT]
[FIXME: I have just taken the comments for C routine scm_options that
implements all of these. It needs to be presented better.]
If scm_options is called without arguments, the current option setting
is returned. If the argument is an option setting, options are altered
and the old setting is returned. If the argument isn't a list, a list
of sublists is returned, where each sublist contains option name, value
and documentation string.
@end deffn
@subheading User level
@c @deftp {Data type} scm_option
@c @code{scm_option} is used to represent run time options. It can be a
@c @emph{boolean} type, in which case the option will be set by the strings
@c @code{"yes"} and @code{"no"}. It can be a
@c @end deftp
@c NJFIXME
@deffn procedure <group>-options [arg]
@deffnx procedure read-options [arg]
@deffnx procedure print-options [arg]
@deffnx procedure debug-options [arg]
@deffnx procedure traps [arg]
These functions list the options in their group. The optional argument
@var{arg} is a symbol which modifies the form in which the options are
presented.
With no arguments, @code{<group>-options} returns the values of the
options in that particular group. If @var{arg} is @code{'help}, a
description of each option is given. If @var{arg} is @code{'full},
programmers' options are also shown.
@var{arg} can also be a list representing the state of all options. In
this case, the list contains single symbols (for enabled boolean
options) and symbols followed by values.
@end deffn
[FIXME: I don't think 'full is ever any different from 'help. What's
up?]
@c NJFIXME
@deffn procedure <group>-enable option-symbol
@deffnx procedure read-enable option-symbol
@deffnx procedure print-enable option-symbol
@deffnx procedure debug-enable option-symbol
@deffnx procedure trap-enable option-symbol
These functions set the specified @var{option-symbol} in their options
group. They only work if the option is boolean, and throw an error
otherwise.
@end deffn
@c NJFIXME
@deffn procedure <group>-disable option-symbol
@deffnx procedure read-disable option-symbol
@deffnx procedure print-disable option-symbol
@deffnx procedure debug-disable option-symbol
@deffnx procedure trap-disable option-symbol
These functions turn off the specified @var{option-symbol} in their
options group. They only work if the option is boolean, and throw an
error otherwise.
@end deffn
@c NJFIXME
@deffn syntax <group>-set! option-symbol value
@deffnx syntax read-set! option-symbol value
@deffnx syntax print-set! option-symbol value
@deffnx syntax debug-set! option-symbol value
@deffnx syntax trap-set! option-symbol value
These functions set a non-boolean @var{option-symbol} to the specified
@var{value}.
@end deffn
@node Reader options
@section Reader options
@cindex options - read
@cindex read options
Here is the list of reader options generated by typing
@code{(read-options 'full)} in Guile. You can also see the default
values.
@smalllisp
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
@end smalllisp
Notice that while Standard Scheme is case insensitive, to ease
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
Guile is case-sensitive by default.
To make Guile case insensitive, you can type
@smalllisp
(read-enable 'case-insensitive)
@end smalllisp
@node Printing options
@section Printing options
Here is the list of print options generated by typing
@code{(print-options 'full)} in Guile. You can also see the default
values.
@smallexample
source no Print closures with source.
closure-hook #f Hook for printing closures.
@end smallexample
@node Evaluator options
@section Evaluator options
These are the evaluator options with their default values, as they are
printed by typing @code{(eval-options 'full)} in Guile.
@smallexample
stack 22000 Size of thread stacks (in machine words).
@end smallexample
Here is the list of evaluator trap options generated by typing
@code{(traps 'full)} in Guile. You can also see the default values.
@smallexample
exit-frame no Trap when exiting eval or apply.
apply-frame no Trap when entering apply.
enter-frame no Trap when eval enters new frame.
@end smallexample
@node Debugger options
@section Debugger options
Here is the list of print options generated by typing
@code{(debug-options 'full)} in Guile. You can also see the default
values.
@smallexample
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
@end smallexample
@node Examples of option use
@section Examples of option use
Here is an example of a session in which some read and debug option
handling procedures are used. In this example, the user
@enumerate
@item
Notices that the symbols @code{abc} and @code{aBc} are not the same
@item
Examines the @code{read-options}, and sees that @code{case-insensitive}
is set to ``no''.
@item
Enables @code{case-insensitive}
@item
Verifies that now @code{aBc} and @code{abc} are the same
@item
Disables @code{case-insensitive} and enables debugging @code{backtrace}
@item
Reproduces the error of displaying @code{aBc} with backtracing enabled
[FIXME: this last example is lame because there is no depth in the
backtrace. Need to give a better example, possibly putting debugging
option examples in a separate session.]
@end enumerate
@smalllisp
guile> (define abc "hello")
guile> abc
"hello"
guile> aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
Type "(backtrace)" to get more information.
guile> (read-options 'help)
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
guile> (debug-options 'help)
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
guile> (read-enable 'case-insensitive)
(keywords #f case-insensitive positions)
guile> aBc
"hello"
guile> (read-disable 'case-insensitive)
(keywords #f positions)
guile> (debug-enable 'backtrace)
(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
guile> aBc
Backtrace:
0* aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
guile>
@end smalllisp
@node Install Config
@section Installation and Configuration Data
It is often useful to have site-specific information about the current
Guile installation. This chapter describes how to find out about
Guile's configuration at run time.
@deffn primitive version
@deffnx primitive major-version
@deffnx primitive minor-version
@deffnx primitive micro-version
Return a string describing Guile's version number, or its major or minor
version numbers, respectively.
@lisp
(version) @result{} "1.6.5"
(major-version) @result{} "1"
(minor-version) @result{} "6"
(micro-version) @result{} "5"
@end lisp
@end deffn
@c NJFIXME not in libguile!
@deffn primitive libguile-config-stamp
Return a string describing the date on which @code{libguile} was
configured. This is used to determine whether the Guile core
interpreter and the ice-9 runtime have grown out of date with one
another.
@end deffn
@deffn primitive %package-data-dir
Return the name of the directory where Scheme packages, modules and
libraries are kept. On most Unix systems, this will be
@samp{/usr/local/share/guile}.
@end deffn
@deffn primitive %library-dir
Return the directory where the Guile Scheme library files are installed.
E.g., may return "/usr/share/guile/1.3.5".
@end deffn
@deffn primitive %site-dir
Return the directory where the Guile site files are installed.
E.g., may return "/usr/share/guile/site".
@end deffn
@deffn primitive parse-path path [tail]
Parse @var{path}, which is expected to be a colon-separated
string, into a list and return the resulting list with
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
is returned.
@end deffn
@deffn primitive search-path path filename [extensions]
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory.
If we find one, return its full filename; otherwise, return
@code{#f}. If @var{filename} is absolute, return it unchanged.
If given, @var{extensions} is a list of strings; for each
directory in @var{path}, we search for @var{filename}
concatenated with each @var{extension}.
@end deffn
@defvar %load-path
Return the list of directories which should be searched for Scheme
modules and libraries.
@end defvar
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

0
doc/scheme-procedures.texi
View file

0
doc/scheme-reading.texi
View file

0
doc/scheme-scheduling.texi
View file

0
doc/scheme-translation.texi
View file

0
doc/scheme-utility.texi
View file

458
doc/scm.texi
View file

@ -1,458 +0,0 @@
@page
@node Scheme Primitives
@c @chapter Writing Scheme primitives in C
@c - according to the menu in guile.texi - NJ 2001/1/26
@chapter Relationship between Scheme and C functions
Scheme procedures marked "primitive functions" have a regular interface
when calling from C, reflected in two areas: the name of a C function, and
the convention for passing non-required arguments to this function.
@c Although the vast majority of functions support these relationships,
@c there are some exceptions.
@menu
* Transforming Scheme name to C name::
* Structuring argument lists for C functions::
@c * Exceptions to the regularity::
@end menu
@node Transforming Scheme name to C name
@section Transforming Scheme name to C name
Normally, the name of a C function can be derived given its Scheme name,
using some simple textual transformations:
@itemize @bullet
@item
Replace @code{-} (hyphen) with @code{_} (underscore).
@item
Replace @code{?} (question mark) with "_p".
@item
Replace @code{!} (exclamation point) with "_x".
@item
Replace internal @code{->} with "_to_".
@item
Replace @code{<=} (less than or equal) with "_leq".
@item
Replace @code{>=} (greater than or equal) with "_geq".
@item
Replace @code{<} (less than) with "_less".
@item
Replace @code{>} (greater than) with "_gr".
@item
Replace @code{@@} with "at". [Omit?]
@item
Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).
@item
[Anything else? --ttn, 2000/01/16 15:17:28]
@end itemize
Here is an Emacs Lisp command that prompts for a Scheme function name and
inserts the corresponding C function name into the buffer.
@example
(defun insert-scheme-to-C (name &optional use-gh)
"Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
(interactive "sScheme name: \nP")
(let ((transforms '(("-" . "_")
("?" . "_p")
("!" . "_x")
("->" . "_to_")
("<=" . "_leq")
(">=" . "_geq")
("<" . "_less")
(">" . "_gr")
("@@" . "at"))))
(while transforms
(let ((trigger (concat "\\(.*\\)"
(regexp-quote (caar transforms))
"\\(.*\\)"))
(sub (cdar transforms))
(m nil))
(while (setq m (string-match trigger name))
(setq name (concat (match-string 1 name)
sub
(match-string 2 name)))))
(setq transforms (cdr transforms))))
(insert (if use-gh "gh_" "scm_") name))
@end example
@node Structuring argument lists for C functions
@section Structuring argument lists for C functions
The C function's arguments will be all of the Scheme procedure's
argumements, both required and optional; if the Scheme procedure takes a
``rest'' argument, that will be a final argument to the C function. The
C function's arguments, as well as its return type, will be @code{SCM}.
@c @node Exceptions to the regularity
@c @section Exceptions to the regularity
@c
@c There are some exceptions to the regular structure described above.
@page
@node I/O Extensions
@chapter Using and Extending Ports in C
@menu
* C Port Interface:: Using ports from C.
* Port Implementation:: How to implement a new port type in C.
@end menu
@node C Port Interface
@section C Port Interface
This section describes how to use Scheme ports from C.
@subsection Port basics
There are two main data structures. A port type object (ptob) is of
type @code{scm_ptob_descriptor}. A port instance is of type
@code{scm_port}. Given an @code{SCM} variable which points to a port,
the corresponding C port object can be obtained using the
@code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
@code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
global array.
@subsection Port buffers
An input port always has a read buffer and an output port always has a
write buffer. However the size of these buffers is not guaranteed to be
more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
which is used when no other buffer is allocated). The way in which the
buffers are allocated depends on the implementation of the ptob. For
example in the case of an fport, buffers may be allocated with malloc
when the port is created, but in the case of an strport the underlying
string is used as the buffer.
@subsection The @code{rw_random} flag
Special treatment is required for ports which can be seeked at random.
Before various operations, such as seeking the port or changing from
input to output on a bidirectional port or vice versa, the port
implemention must be given a chance to update its state. The write
buffer is updated by calling the @code{flush} ptob procedure and the
input buffer is updated by calling the @code{end_input} ptob procedure.
In the case of an fport, @code{flush} causes buffered output to be
written to the file descriptor, while @code{end_input} causes the
descriptor position to be adjusted to account for buffered input which
was never read.
The special treatment must be performed if the @code{rw_random} flag in
the port is non-zero.
@subsection The @code{rw_active} variable
The @code{rw_active} variable in the port is only used if
@code{rw_random} is set. It's defined as an enum with the following
values:
@table @code
@item SCM_PORT_READ
the read buffer may have unread data.
@item SCM_PORT_WRITE
the write buffer may have unwritten data.
@item SCM_PORT_NEITHER
neither the write nor the read buffer has data.
@end table
@subsection Reading from a port.
To read from a port, it's possible to either call existing libguile
procedures such as @code{scm_getc} and @code{scm_read_line} or to read
data from the read buffer directly. Reading from the buffer involves
the following steps:
@enumerate
@item
Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
@item
Fill the read buffer, if it's empty, using @code{scm_fill_input}.
@item Read the data from the buffer and update the read position in
the buffer. Steps 2) and 3) may be repeated as many times as required.
@item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
@item update the port's line and column counts.
@end enumerate
@subsection Writing to a port.
To write data to a port, calling @code{scm_lfwrite} should be sufficient for
most purposes. This takes care of the following steps:
@enumerate
@item
End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
@item
Pass the data to the ptob implementation using the @code{write} ptob
procedure. The advantage of using the ptob @code{write} instead of
manipulating the write buffer directly is that it allows the data to be
written in one operation even if the port is using the single-byte
@code{shortbuf}.
@item
Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
is set.
@end enumerate
@node Port Implementation
@section Port Implementation
This section describes how to implement a new port type in C.
As described in the previous section, a port type object (ptob) is
a structure of type @code{scm_ptob_descriptor}. A ptob is created by
calling @code{scm_make_port_type}.
All of the elements of the ptob, apart from @code{name}, are procedures
which collectively implement the port behaviour. Creating a new port
type mostly involves writing these procedures.
@code{scm_make_port_type} initializes three elements of the structure
(@code{name}, @code{fill_input} and @code{write}) from its arguments.
The remaining elements are initialized with default values and can be
set later if required.
@table @code
@item name
A pointer to a NUL terminated string: the name of the port type. This
is the only element of @code{scm_ptob_descriptor} which is not
a procedure. Set via the first argument to @code{scm_make_port_type}.
@item mark
Called during garbage collection to mark any SCM objects that a port
object may contain. It doesn't need to be set unless the port has
@code{SCM} components. Set using @code{scm_set_port_mark}.
@item free
Called when the port is collected during gc. It
should free any resources used by the port.
Set using @code{scm_set_port_free}.
@item print
Called when @code{write} is called on the port object, to print a
port description. e.g., for an fport it may produce something like:
@code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}.
@item equalp
Not used at present. Set using @code{scm_set_port_equalp}.
@item close
Called when the port is closed, unless it was collected during gc. It
should free any resources used by the port.
Set using @code{scm_set_port_close}.
@item write
Accept data which is to be written using the port. The port implementation
may choose to buffer the data instead of processing it directly.
Set via the third argument to @code{scm_make_port_type}.
@item flush
Complete the processing of buffered output data. Reset the value of
@code{rw_active} to @code{SCM_PORT_NEITHER}.
Set using @code{scm_set_port_flush}.
@item end_input
Perform any synchronisation required when switching from input to output
on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
Set using @code{scm_set_port_end_input}.
@item fill_input
Read new data into the read buffer and return the first character. It
can be assumed that the read buffer is empty when this procedure is called.
Set via the second argument to @code{scm_make_port_type}.
@item input_waiting
Return a lower bound on the number of bytes that could be read from the
port without blocking. It can be assumed that the current state of
@code{rw_active} is @code{SCM_PORT_NEITHER}.
Set using @code{scm_set_port_input_waiting}.
@item seek
Set the current position of the port. The procedure can not make
any assumptions about the value of @code{rw_active} when it's
called. It can reset the buffers first if desired by using something
like:
@example
if (pt->rw_active == SCM_PORT_READ)
scm_end_input (object);
else if (pt->rw_active == SCM_PORT_WRITE)
ptob->flush (object);
@end example
However note that this will have the side effect of discarding any data
in the unread-char buffer, in addition to any side effects from the
@code{end_input} and @code{flush} ptob procedures. This is undesirable
when seek is called to measure the current position of the port, i.e.,
@code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
implementations take care to avoid this problem.
The procedure is set using @code{scm_set_port_seek}.
@item truncate
Truncate the port data to be specified length. It can be assumed that the
current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
Set using @code{scm_set_port_truncate}.
@end table
@node Handling Errors
@chapter How to Handle Errors in C Code
Error handling is based on @code{catch} and @code{throw}. Errors are
always thrown with a @var{key} and four arguments:
@itemize @bullet
@item
@var{key}: a symbol which indicates the type of error. The symbols used
by libguile are listed below.
@item
@var{subr}: the name of the procedure from which the error is thrown, or
@code{#f}.
@item
@var{message}: a string (possibly language and system dependent)
describing the error. The tokens @code{~A} and @code{~S} can be
embedded within the message: they will be replaced with members of the
@var{args} list when the message is printed. @code{~A} indicates an
argument printed using @code{display}, while @code{~S} indicates an
argument printed using @code{write}. @var{message} can also be
@code{#f}, to allow it to be derived from the @var{key} by the error
handler (may be useful if the @var{key} is to be thrown from both C and
Scheme).
@item
@var{args}: a list of arguments to be used to expand @code{~A} and
@code{~S} tokens in @var{message}. Can also be @code{#f} if no
arguments are required.
@item
@var{rest}: a list of any additional objects required. e.g., when the
key is @code{'system-error}, this contains the C errno value. Can also
be @code{#f} if no additional objects are required.
@end itemize
In addition to @code{catch} and @code{throw}, the following Scheme
facilities are available:
@deffn primitive scm-error key subr message args rest
Throw an error, with arguments
as described above.
@end deffn
@deffn procedure error msg arg @dots{}
Throw an error using the key @code{'misc-error}. The error
message is created by displaying @var{msg} and writing the @var{args}.
@end deffn
The following are the error keys defined by libguile and the situations
in which they are used:
@itemize @bullet
@item
@code{error-signal}: thrown after receiving an unhandled fatal signal
such as SIGSEV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw
contains the coded signal number (at present this is not the same as the
usual Unix signal number).
@item
@code{system-error}: thrown after the operating system indicates an
error condition. The @var{rest} argument in the throw contains the
errno value.
@item
@code{numerical-overflow}: numerical overflow.
@item
@code{out-of-range}: the arguments to a procedure do not fall within the
accepted domain.
@item
@code{wrong-type-arg}: an argument to a procedure has the wrong thpe.
@item
@code{wrong-number-of-args}: a procedure was called with the wrong number
of arguments.
@item
@code{memory-allocation-error}: memory allocation error.
@item
@code{stack-overflow}: stack overflow error.
@item
@code{regex-error}: errors generated by the regular expression library.
@item
@code{misc-error}: other errors.
@end itemize
@section C Support
SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
Throws an error, after converting the char * arguments to Scheme strings.
subr is the Scheme name of the procedure, NULL is converted to #f.
Likewise a NULL message is converted to #f.
The following procedures invoke scm_error with various error keys and
arguments. The first three call scm_error with the system-error key
and automatically supply errno in the "rest" argument: scm_syserror
generates messages using strerror, scm_sysmissing is used when
facilities are not available. Care should be taken that the errno
value is not reset (e.g. due to an interrupt).
@itemize @bullet
@item
void scm_syserror (char *subr);
@item
void scm_syserror_msg (char *subr, char *message, SCM args);
@item
void scm_sysmissing (char *subr);
@item
void scm_num_overflow (char *subr);
@item
void scm_out_of_range (char *subr, SCM bad_value);
@item
void scm_wrong_num_args (SCM proc);
@item
void scm_wrong_type_arg (char *subr, int pos, SCM bad_value);
@item
void scm_memory_error (char *subr);
@item
static void scm_regex_error (char *subr, int code); (only used in rgx.c).
@end itemize
Exception handlers can also be installed from C, using
scm_internal_catch, scm_lazy_catch, or scm_stack_catch from
libguile/throw.c. These have not yet been documented, however the
source contains some useful comments.
@c scm.texi ends here

0
doc/script-getopt.texi
View file

0
doc/scripts.texi
View file

0
doc/scsh.texi
View file

0
doc/slib.texi
View file

0
doc/srfi-modules.texi
View file

0
doc/tcltk.texi
View file

0
doc/texinfo.tex
View file

4
doc/tutorial/guile-tut.texi
View file

@ -4,7 +4,7 @@
@settitle Guile Tutorial
@set guile-tut
@include version.texi
@include version-tutorial.texi
@dircategory The Algorithmic Language Scheme
@direntry
@ -27,7 +27,7 @@
@title Guile Tutorial
@subtitle For use with Guile @value{VERSION}
@subtitle Last updated @value{UPDATED}
@include ../AUTHORS
@include AUTHORS
@page
@vskip 0pt plus 1filll