summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2001-11-11 15:01:52 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2001-11-11 15:01:52 +0000
commit9401323e63278a7053c54565e8d688f6cbe34f54 (patch)
tree01e0840bac67d78e974b03200f9cf16f894fea37 /doc/ref
parenta0a9b9ad4263e129e46e31a8c0c2e7775b037ee9 (diff)
downloadguile-9401323e63278a7053c54565e8d688f6cbe34f54.tar.gz
* Documentation work.
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/ChangeLog58
-rw-r--r--doc/ref/Makefile.am4
-rw-r--r--doc/ref/appendices.texi0
-rw-r--r--doc/ref/debugging.texi179
-rw-r--r--doc/ref/guile.texi115
-rw-r--r--doc/ref/indices.texi4
-rw-r--r--doc/ref/intro.texi113
-rw-r--r--doc/ref/new-docstrings.texi69
-rw-r--r--doc/ref/posix.texi39
-rw-r--r--doc/ref/preface.texi91
-rw-r--r--doc/ref/program.texi199
-rw-r--r--doc/ref/scheme-binding.texi2
-rw-r--r--doc/ref/scheme-control.texi138
-rwxr-xr-xdoc/ref/scheme-data.texi70
-rw-r--r--doc/ref/scheme-debug.texi4
-rw-r--r--doc/ref/scheme-indices.texi4
-rw-r--r--doc/ref/scheme-io.texi234
-rw-r--r--doc/ref/scheme-memory.texi2
-rw-r--r--doc/ref/scheme-options.texi4
-rw-r--r--doc/ref/scm.texi355
20 files changed, 1163 insertions, 521 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 52476be8e..cdd5ee958 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,61 @@
+2001-11-08 Neil Jerram <neil@ossau.uklinux.net>
+
+ * guile.texi (Top): Added new chapter `Programming Options'.
+
+ * program.texi: New file.
+
+ * Makefile.am (guile_TEXINFOS): Added program.texi.
+
+2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
+
+ * scheme-memory.texi, scheme-io.texi, scheme-debug.texi,
+ scheme-data.texi, scheme-binding.texi, posix.texi,
+ new-docstrings.texi: Automatic updates from improved libguile
+ docstrings.
+
+2001-11-04 Neil Jerram <neil@ossau.uklinux.net>
+
+ * preface.texi: Use MANUAL_EDITION variable.
+ (Manual Layout): Updated to reflect reorg.
+
+ * guile.texi (MANUAL_EDITION): New variable, with value
+ incremented from 1.0 to 1.1 to reflect the reorg described here.
+ (Top): Use MANUAL_EDITION variable.
+
+ * scheme-indices.texi (R5RS Index, Guile Extensions Index): Use
+ @unnumbered rather than @chapter for these indices.
+
+ * guile.texi (Top): A little top-level reshuffling, with the aims
+ that: (1) the `Guile Scheme' (reference) part of the manual
+ becomes the `Guile API Reference', and covers both Scheme and C
+ interfaces; (2) non-API-reference material such as the `Basic
+ Ideas in Scheme' chapter is collected together to form a new part
+ `Programming with Guile'. This new part will contain general
+ documentation on using and programming Guile in both Scheme and C,
+ including - for example - awareness of GC when C programming, how
+ to use the snarf macros, how to debug ...
+ (Top): Move inclusion of scheme-indices.texi so that all indices
+ appear together in the printed manual.
+
+ * Makefile.am (guile_TEXINFOS): Removed appendices.texi, added
+ debugging.texi.
+
+ * appendices.texi: Removed.
+
+ * debugging.texi (Debugger User Interface): New file, same as the
+ material that used to be in appendices.texi, but now a chapter in
+ Part II rather than an appendix.
+
+ * appendices.texi (Obtaining and Installing Guile): Moved to
+ become a chapter in ...
+ * intro.texi: ... Part I: Introduction to Guile.
+
+ * scm.texi (I/O Extensions): Moved to become a section of ...
+ * scheme-io.texi (Input and Output): ... this chapter.
+
+ * scm.texi (Handling Errors): Moved to become a section of ...
+ * scheme-control.texi (Control Mechanisms): ... this chapter.
+
2001-11-06 Thien-Thi Nguyen <ttn@glug.org>
* srfi-modules.texi (SRFI-19, SRFI-19 Constants, SRFI-19 Current
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 99e06b0a8..5fbacd8a7 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -23,7 +23,7 @@ AUTOMAKE_OPTIONS = gnu
info_TEXINFOS = guile.texi
-guile_TEXINFOS = preface.texi intro.texi scheme-intro.texi \
+guile_TEXINFOS = preface.texi intro.texi program.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 \
@@ -31,7 +31,7 @@ guile_TEXINFOS = preface.texi intro.texi scheme-intro.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 \
+ debugging.texi indices.texi script-getopt.texi data-rep.texi \
extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi
# Optionally support building an HTML version of the reference manual.
diff --git a/doc/ref/appendices.texi b/doc/ref/appendices.texi
deleted file mode 100644
index e69de29bb..000000000
--- a/doc/ref/appendices.texi
+++ /dev/null
diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi
new file mode 100644
index 000000000..28607c551
--- /dev/null
+++ b/doc/ref/debugging.texi
@@ -0,0 +1,179 @@
+@page
+@node Debugger User Interface
+@chapter Debugger User Interface
+
+@c --- The title and introduction of this appendix need to
+@c distinguish this clearly from the chapter on the internal
+@c debugging interface.
+
+When debugging a program, programmers often find it helpful to examine
+the program's internal status while it runs: the values of internal
+variables, the choices made in @code{if} and @code{cond} statements, and
+so forth. Guile Scheme provides a debugging interface that programmers
+can use to single-step through Scheme functions and examine symbol
+bindings. This is different from the @ref{Debugging}, which permits
+programmers to debug the Guile interpreter itself. Most programmers
+will be more interested in debugging their own Scheme programs than the
+interpreter which evaluates them.
+
+[FIXME: should we include examples of traditional debuggers
+and explain why they can't be used to debug interpreted Scheme or Lisp?]
+
+@menu
+* Single-Step:: Execute a program or function one step at a time.
+* Trace:: Print a report each time a given function is called.
+* Backtrace:: See a list of the statements that caused an error.
+* Stacks and Frames:: Examine the state of an interrupted program.
+@end menu
+
+
+@node Single-Step
+@section Single-Step
+
+
+@node Trace
+@section Trace
+
+When a function is @dfn{traced}, it means that every call to that
+function is reported to the user during a program run. This can help a
+programmer determine whether a function is being called at the wrong
+time or with the wrong set of arguments.
+
+@defun trace function
+Enable debug tracing on @code{function}. While a program is being run, Guile
+will print a brief report at each call to a traced function,
+advising the user which function was called and the arguments that were
+passed to it.
+@end defun
+
+@defun untrace function
+Disable debug tracing for @code{function}.
+@end defun
+
+Example:
+
+@lisp
+(define (rev ls)
+ (if (null? ls)
+ '()
+ (append (rev (cdr ls))
+ (cons (car ls) '())))) @result{} rev
+
+(trace rev) @result{} (rev)
+
+(rev '(a b c d e))
+@result{} [rev (a b c d e)]
+ | [rev (b c d e)]
+ | | [rev (c d e)]
+ | | | [rev (d e)]
+ | | | | [rev (e)]
+ | | | | | [rev ()]
+ | | | | | ()
+ | | | | (e)
+ | | | (e d)
+ | | (e d c)
+ | (e d c b)
+ (e d c b a)
+ (e d c b a)
+@end lisp
+
+Note the way Guile indents the output, illustrating the depth of
+execution at each function call. This can be used to demonstrate, for
+example, that Guile implements self-tail-recursion properly:
+
+@lisp
+(define (rev ls sl)
+ (if (null? ls)
+ sl
+ (rev (cdr ls)
+ (cons (car ls) sl)))) @result{} rev
+
+(trace rev) @result{} (rev)
+
+(rev '(a b c d e) '())
+@result{} [rev (a b c d e) ()]
+ [rev (b c d e) (a)]
+ [rev (c d e) (b a)]
+ [rev (d e) (c b a)]
+ [rev (e) (d c b a)]
+ [rev () (e d c b a)]
+ (e d c b a)
+ (e d c b a)
+@end lisp
+
+Since the tail call is effectively optimized to a @code{goto} statement,
+there is no need for Guile to create a new stack frame for each
+iteration. Using @code{trace} here helps us see why this is so.
+
+@node Backtrace
+@appendixsec Backtrace
+
+@node Stacks and Frames
+@appendixsec Stacks and Frames
+
+When a running program is interrupted, usually upon reaching an error or
+breakpoint, its state is represented by a @dfn{stack} of suspended
+function calls, each of which is called a @dfn{frame}. The programmer
+can learn more about the program's state at the point of interruption by
+inspecting and modifying these frames.
+
+@deffn primitive stack? obj
+Return @code{#t} if @var{obj} is a calling stack.
+@end deffn
+
+@deffn primitive make-stack
+@end deffn
+
+@deffn syntax start-stack id exp
+Evaluate @var{exp} on a new calling stack with identity @var{id}. If
+@var{exp} is interrupted during evaluation, backtraces will not display
+frames farther back than @var{exp}'s top-level form. This macro is a
+way of artificially limiting backtraces and stack procedures, largely as
+a convenience to the user.
+@end deffn
+
+@deffn primitive stack-id stack
+Return the identifier given to @var{stack} by @code{start-stack}.
+@end deffn
+
+@deffn primitive stack-ref
+@end deffn
+
+@deffn primitive stack-length
+@end deffn
+
+@deffn primitive frame?
+@end deffn
+
+@deffn primitive last-stack-frame
+@end deffn
+
+@deffn primitive frame-number
+@end deffn
+
+@deffn primitive frame-source
+@end deffn
+
+@deffn primitive frame-procedure
+@end deffn
+
+@deffn primitive frame-arguments
+@end deffn
+
+@deffn primitive frame-previous
+@end deffn
+
+@deffn primitive frame-next
+@end deffn
+
+@deffn primitive frame-real?
+@end deffn
+
+@deffn primitive frame-procedure?
+@end deffn
+
+@deffn primitive frame-evaluating-args?
+@end deffn
+
+@deffn primitive frame-overflow
+@end deffn
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 7d5e0ba01..fdd6df748 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -4,6 +4,7 @@
@setfilename guile.info
@settitle Guile Reference Manual
@set guile
+@set MANUAL_EDITION 1.1
@c %**end of header
@c Notes: (distilled from Jim's and Tim's notes, and kept up to date)
@@ -80,7 +81,7 @@ 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.5 2001-10-27 16:53:34 ghouston Exp $
+@subtitle $Id: guile.texi,v 1.6 2001-11-11 15:01:51 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@c AUTHORS
@@ -175,8 +176,8 @@ 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}.
+This Info file contains edition @value{MANUAL_EDITION} of the reference
+manual, corresponding to Guile version @value{VERSION}.
@end ifinfo
@menu
@@ -190,12 +191,27 @@ Part I: Introduction to Guile
* What is Guile?:: And what does it do?
* Whirlwind Tour:: An introductory whirlwind tour.
+* Obtaining and Installing Guile::
* Reporting Bugs:: Reporting bugs in Guile or this manual.
-Part II: Guile Scheme
+Part II: Programming with Guile
+* Programming Intro:: Intoduction to programming with Guile.
+* Programming Options:: Programming Options in Guile.
* Scheme Intro:: Introduction to Guile Scheme.
* Basic Ideas:: Basic ideas in Scheme.
+* Guile Scripting:: How to write Guile scripts.
+* Command Line Handling:: Command line options and arguments.
+* Libguile Intro:: Using Guile as an extension language.
+* Scheme Primitives:: Writing Scheme primitives in C.
+* Data Representation:: Data representation in Guile.
+* GH:: The deprecated GH interface.
+* Debugger User Interface::
+* Further Reading:: Where to find out more about Scheme programming.
+
+Part III: Guile API Reference
+
+* Reference Intro:: Introduction to the Guile API reference.
* Data Types:: Data types for generic use.
* Procedures and Macros:: Procedures and macros.
* Utility Functions:: General utility functions.
@@ -211,9 +227,8 @@ Part II: Guile Scheme
* 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.
-Part III: Guile Modules
+Part IV: Guile Modules
* SLIB:: Using the SLIB Scheme library.
* POSIX:: POSIX system calls and networking.
@@ -224,26 +239,6 @@ Part III: Guile Modules
* Formatted Output:: The @code{format} procedure.
* Expect:: Controlling interactive programs with Guile.
* The Scheme shell (scsh):: Using scsh interfaces in Guile.
-@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
@@ -258,7 +253,6 @@ Indices
@include preface.texi
-@c preliminary
@iftex
@page
@unnumbered{Part I: Introduction to Guile}
@@ -266,14 +260,37 @@ Indices
@include intro.texi
-@c programming in Scheme
-@iftex
@page
-@unnumbered{Part II: Guile Scheme}
-@end iftex
+@node Programming Intro
+@unnumbered Part II: Programming with Guile
+
+In this part of the manual, we aim to present a wide ranging picture of
+what it means to program using Guile, to provide guidance, practical
+guidelines and tips for @emph{how} to program in Guile, and to document
+the tools that are available to help you with your programming. For
+detailed reference information on the variables, functions etc. that
+make up Guile's application programming interface (API), please refer to
+Part III (@pxref{Reference Intro,,Part III: Programming with Guile}).
+We begin in the first chapter of this part by looking at the programming
+options available.
+
+@include program.texi
@include scheme-intro.texi
@include scheme-ideas.texi
+@include scripts.texi
+@include script-getopt.texi
+@include extend.texi
+@include scm.texi
+@include data-rep.texi
+@include gh.texi
+@include debugging.texi
+@include scheme-reading.texi
+
+@page
+@node Reference Intro
+@unnumbered Part III: Guile API Reference
+
@include scheme-data.texi
@include scheme-procedures.texi
@include scheme-utility.texi
@@ -289,13 +306,10 @@ Indices
@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}
+@unnumbered{Part IV: Guile Modules}
@end iftex
@include slib.texi
@@ -305,43 +319,14 @@ Indices
@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
+@include scheme-indices.texi
@contents
diff --git a/doc/ref/indices.texi b/doc/ref/indices.texi
index a35592e90..11ab7476b 100644
--- a/doc/ref/indices.texi
+++ b/doc/ref/indices.texi
@@ -1,3 +1,4 @@
+@page
@node Concept Index
@unnumbered Concept Index
@@ -41,9 +42,6 @@ in the section @xref{Transforming Scheme name to C name}.
@page
-@c Spell out this node fully, because it is the last real node
-@c in the top-level menu. Leaving off the pointers here causes
-@c spurious makeinfo errors.
@node Type Index
@unnumbered Type Index
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index fdbbbf85b..9391a1d48 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -1,4 +1,5 @@
-@c $Id: intro.texi,v 1.2 2001-08-27 21:25:44 ossau Exp $
+@c $Id: intro.texi,v 1.3 2001-11-11 15:01:51 ossau Exp $
+
@page
@node What is Guile?
@@ -50,6 +51,7 @@ can program applications which use Guile in the language of their
choice, rather than having the tastes of the application's author
imposed on them.
+
@page
@node Whirlwind Tour
@chapter A Whirlwind Tour
@@ -582,6 +584,7 @@ guile> (exit)
$
@end example
+
@node Writing Extensions for Guile
@section Writing Extensions for Guile
@@ -624,6 +627,7 @@ by Guile.
* A Sample Guile Extension::
@end menu
+
@node A Sample Guile Extension
@subsection A Sample Guile Extension
@@ -688,6 +692,7 @@ environment variable.
To see how these Guile extensions via shared libraries relate to the
module system, see below @xref{Intro to Modules and Extensions}.
+
@node Guile Modules
@section Guile Modules
@@ -701,13 +706,13 @@ anyway. Guile will provide reasonable backwards compatability.)
Details on the module system beyond this introductory material can be found in
@xref{Modules}.
-
@menu
* Intro to Using Guile Modules::
* Intro to Writing New Modules::
* Intro to Modules and Extensions::
@end menu
+
@node Intro to Using Guile Modules
@subsection Intro to Using Existing Modules
@@ -848,6 +853,110 @@ There is also a way to manipulate the module system from C but only
Scheme files can be autoloaded. Thus, we recommend that you define
your modules in Scheme.
+
+@page
+@node Obtaining and Installing Guile
+@chapter Obtaining and Installing Guile
+
+Here is the information you will need to get and install Guile and extra
+packages and documentation you might need or find interesting.
+
+@menu
+* The Basic Guile Package::
+* Packages not shipped with Guile::
+@end menu
+
+
+@node The Basic Guile Package
+@section The Basic Guile Package
+
+Guile can be obtained from the main GNU archive site
+@url{ftp://prep.ai.mit.edu/pub/gnu} or any of its mirrors. The file
+will be named guile-version.tar.gz. The current version is
+@value{VERSION}, so the file you should grab is:
+
+@url{ftp://prep.ai.mit.edu/pub/gnu/guile-@value{VERSION}.tar.gz}
+
+To unbundle Guile use the instruction
+@example
+zcat guile-@value{VERSION}.tar.gz | tar xvf -
+@end example
+which will create a directory called @file{guile-@value{VERSION}} with
+all the sources. You can look at the file @file{INSTALL} for detailed
+instructions on how to build and install Guile, but you should be able
+to just do
+@example
+cd guile-@value{VERSION}
+./configure
+make install
+@end example
+
+This will install the Guile executable @file{guile}, the Guile library
+@file{libguile.a} and various associated header files and support
+libraries. It will also install the Guile tutorial and reference manual.
+
+@c [[include instructions for getting R5RS]]
+
+Since this manual frequently refers to the Scheme ``standard'', also
+known as R5RS, or the
+@iftex
+``Revised$^5$ Report on the Algorithmic Language Scheme'',
+@end iftex
+@ifinfo
+``Revised^5 Report on the Algorithmic Language Scheme'',
+@end ifinfo
+we have included the report in the Guile distribution;
+@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
+Language Scheme}.
+This will also be installed in your info directory.
+
+
+@node Packages not shipped with Guile
+@section Packages not shipped with Guile
+
+We ship the Guile tutorial and reference manual with the Guile
+distribution. Since the Scheme standard (R5RS) is a stable document, we
+ship that too.
+
+Here are references (usually World Wide Web URLs) to some other freely
+redistributable documents and packages which you might find useful if
+you are using Guile.
+
+@table @strong
+@item SCSH
+the Scheme Shell. Gary Houston has ported SCSH to Guile. The relevant
+chapter (@pxref{The Scheme shell (scsh)}) has references to the SCSH web
+page with all its documentation.
+
+@item SLIB
+a portable Scheme library maintained by Aubrey Jaffer. SLIB can be
+obtained by ftp from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}.
+
+The SLIB package should be unpacked somewhere in Guile's load path. It
+will typically be unpacked in @file{/usr/local/share/guile/site}, so
+that it will be @file{/usr/local/share/guile/site/slib}.
+
+Guile might have been installed with a different prefix, in which case
+the load path can be checked from inside the interpreter with:
+
+@smalllisp
+guile> %load-path
+("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")
+@end smalllisp
+
+The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with
+Guile.
+
+@item JACAL
+a symbolic math package by Aubrey Jaffer. The latest version of Jacal
+can be obtained from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}, and
+should be unpacked in @file{/usr/local/share/guile/site/slib} so that
+it will be in @file{/usr/local/share/guile/site/slib/jacal}.
+
+The relevant section (@pxref{JACAL}) has details on how to use Jacal.
+@end table
+
+
@page
@node Reporting Bugs
@chapter Reporting Bugs
diff --git a/doc/ref/new-docstrings.texi b/doc/ref/new-docstrings.texi
index 8bce646e6..e795fd3ef 100644
--- a/doc/ref/new-docstrings.texi
+++ b/doc/ref/new-docstrings.texi
@@ -304,9 +304,11 @@ If @var{l} does not hold a value for @var{key}, the value
@end deffn
@deffn primitive slot-ref-using-class class obj slot_name
+
@end deffn
@deffn primitive slot-set-using-class! class obj slot_name value
+
@end deffn
@deffn primitive class-of x
@@ -319,33 +321,43 @@ on the C level which depends on the loaded GOOPS modules.
@end deffn
@deffn primitive %method-more-specific? m1 m2 targs
+
@end deffn
@deffn primitive find-method . l
+
@end deffn
@deffn primitive primitive-generic-generic subr
+
@end deffn
@deffn primitive enable-primitive-generic! . subrs
+
@end deffn
@deffn primitive generic-capability? proc
+
@end deffn
@deffn primitive %invalidate-method-cache! gf
+
@end deffn
@deffn primitive %invalidate-class class
+
@end deffn
@deffn primitive %modify-class old new
+
@end deffn
@deffn primitive %modify-instance old new
+
@end deffn
@deffn primitive %set-object-setter! obj setter
+
@end deffn
@deffn primitive %allocate-instance class initargs
@@ -367,9 +379,11 @@ Set the slot named @var{slot_name} of @var{obj} to @var{value}.
@end deffn
@deffn primitive slot-exists-using-class? class obj slot_name
+
@end deffn
@deffn primitive slot-bound-using-class? class obj slot_name
+
@end deffn
@deffn primitive %fast-slot-set! obj index value
@@ -460,9 +474,11 @@ Return @code{#t} if @var{obj} is an instance.
@end deffn
@deffn primitive %inherit-magic! class dsupers
+
@end deffn
@deffn primitive %prep-layout! class
+
@end deffn
@deffn primitive %initialize-object obj initargs
@@ -530,3 +546,56 @@ this specific @var{msg}. Do nothing otherwise.
The argument @var{msgs} should be a list of strings;
they are printed in turn, each one followed by a newline.
@end deffn
+
+@deffn primitive valid-object-procedure? proc
+Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}. It is always valid to use a closure constructed by @code{lambda}.
+@end deffn
+
+@deffn primitive %get-pre-modules-obarray
+Return the obarray that is used for all new bindings before the module system is booted. The first call to @code{set-current-module} will boot the module system.
+@end deffn
+
+@deffn primitive standard-interface-eval-closure module
+Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
+@end deffn
+
+@deffn primitive env-module env
+Return the module of @var{ENV}, a lexical environment.
+@end deffn
+
+@deffn primitive load-extension lib init
+Load and initilize the extension designated by LIB and INIT.
+When there is no pre-registered function for LIB/INIT, this is
+equivalent to
+
+@lisp
+(dynamic-call INIT (dynamic-link LIB))
+@end lisp
+
+When there is a pre-registered function, that function is called
+instead.
+
+Normally, there is no pre-registered function. This option exists
+only for situations where dynamic linking is unavailable or unwanted.
+In that case, you would statically link your program with the desired
+library, and register its init function right after Guile has been
+initialized.
+
+LIB should be a string denoting a shared library without any file type
+suffix such as ".so". The suffix is provided automatically. It
+should also not contain any directory components. Libraries that
+implement Guile Extensions should be put into the normal locations for
+shared libraries. We recommend to use the naming convention
+libguile-bla-blum for a extension related to a module `(bla blum)'.
+
+The normal way for a extension to be used is to write a small Scheme
+file that defines a module, and to load the extension into this
+module. When the module is auto-loaded, the extension is loaded as
+well. For example,
+
+@lisp
+(define-module (bla blum))
+
+(load-extension "libguile-bla-blum" "bla_init_blum")
+@end lisp
+@end deffn
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 4d4473422..f2237f2c1 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -1457,26 +1457,35 @@ all platforms.
@end deffn
@deffn primitive setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-
Set the timer specified by @var{which_timer} according to the given
@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values, and return
-information about the timer's previous setting. The timers available
-are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, and @code{ITIMER_PROF},
-and the return value will be a list of two cons pairs representing the
+@var{value_seconds}, and @var{value_microseconds} values.
+
+Return information about the timer's previous setting.
+Errors are handled as described in the guile info pages under ``POSIX
+Interface Conventions''.
+
+The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
+and @code{ITIMER_PROF}.
+
+The return value will be a list of two cons pairs representing the
current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is the
-seconds and microseconds of the timer @code{it_value}.
+microseconds of the timer @code{it_interval}, and the second pair is
+the seconds and microseconds of the timer @code{it_value}.
@end deffn
@deffn primitive getitimer which_timer
-Return information about the timer specified by @var{which_timer}. The
-timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, and
-@code{ITIMER_PROF}, and the return value will be a list of two cons
-pairs representing the current state of the given timer. The first pair
-is the seconds and microseconds of the timer @code{it_interval}, and the
-second pair is the seconds and microseconds of the timer
-@code{it_value}.
+Return information about the timer specified by @var{which_timer}
+Errors are handled as described in the guile info pages under ``POSIX
+Interface Conventions''.
+
+The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
+and @code{ITIMER_PROF}.
+
+The return value will be a list of two cons pairs representing the
+current state of the given timer. The first pair is the seconds and
+microseconds of the timer @code{it_interval}, and the second pair is
+the seconds and microseconds of the timer @code{it_value}.
@end deffn
@@ -2310,7 +2319,7 @@ documentation before using them.
@deffn primitive crypt key salt
Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call
+crypt(3) library call.
@end deffn
@code{getpass} is no encryption procedure at all, but it is often used
diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi
index 90e53e9ac..0a6ce32ba 100644
--- a/doc/ref/preface.texi
+++ b/doc/ref/preface.texi
@@ -6,8 +6,8 @@ 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 is edition 1.0 of the reference manual, and corresponds to Guile
-version @value{VERSION}.
+This is edition @value{MANUAL_EDITION} of the reference manual, and
+corresponds to Guile version @value{VERSION}.
@end iftex
@@ -74,57 +74,74 @@ do not wish that, delete this exception notice.
@chapter Layout of this Manual
@end ifnottex
-This manual is divided into five parts.
+The manual is divided into three parts.
@strong{Part I: Introduction to Guile} provides an overview of what
Guile is and how you can use it. A whirlwind tour shows how Guile can
be used interactively and as a script interpreter, how to link Guile
into your own applications, and how to write modules of interpreted and
-compiled code for use with Guile. All of the ideas introduced here are
-documented in full by the later parts of the manual.
-
-@strong{Part II: Guile Scheme} documents the core Scheme language and
-features that Guile implements. Although the basis for this is the
-Scheme language described in R5RS, this part of the manual does not
-assume any prior familiarity with R5RS in particular, or with Scheme in
-general. Basic Scheme concepts, standard aspects of the Scheme language
-and Guile extensions on top of R5RS are all documented from scratch, and
-organized by functionality rather than by the defining standards.
-
-@strong{Part III: Guile Modules} describes some important modules,
+compiled code for use with Guile. Everything introduced here is
+documented again and in full by the later parts of the manual. This
+part also explains how to obtain and install new versions of Guile, and
+how to report bugs effectively.
+
+@strong{Part II: Programming with Guile} documents all aspects of
+practical programming using Guile. This covers both the Scheme level
+--- where we provide an introduction to the key ideas of the Scheme
+language --- and use of Guile's @code{scm} interface to write new
+primitives and objects in C, and to incorporate Guile into a C
+application. It also covers the use of Guile as a POSIX compliant
+script interpreter, and how to use the Guile debugger.
+
+@c @strong{Part V: Extending Applications Using Guile} explains the options
+@c available for using Guile as a application extension language. At the
+@c simpler end of the scale, an application might use Guile to define some
+@c application-specific primitives in C and then load an application Scheme
+@c file. In this case most of the application code is written on the
+@c Scheme level, and uses the application-specific primitives as an
+@c extension to standard Scheme. At the other end of the scale, an
+@c application might be predominantly written in C --- with its main
+@c control loop implemented in C --- but make occasional forays into Scheme
+@c to, say, read configuration data or run user-defined customization code.
+@c This part of the manual covers the complete range of application
+@c extension options.
+
+@strong{Part III: Guile API Reference} documents Guile's core API. Most
+of the variables and procedures in Guile's core programming interface
+are available in both Scheme and C, and are related systematically such
+that the C interface can be inferred from the Scheme interface and vice
+versa. Therefore this part of the manual documents the Guile API in
+functionality-based groups with the Scheme and C interfaces presented
+side by side. Where the Scheme and C interfaces for a particular
+functional area do differ --- which is sometimes inevitable, given the
+differences in the structure of the two languages --- this is pointed
+out and explained. In all cases the overriding principle is that all
+the reference documentation for a given functional area is grouped
+together.
+
+@c the core Scheme language and features that Guile implements. Although
+@c the basis for this is the Scheme language described in R5RS, this part
+@c of the manual does not assume any prior familiarity with R5RS in
+@c particular, or with Scheme in general. Basic Scheme concepts, standard
+@c aspects of the Scheme language and Guile extensions on top of R5RS are
+@c all documented from scratch, and organized by functionality rather than
+@c by the defining standards.
+
+@strong{Part IV: Guile Modules} describes some important modules,
distributed as part of the Guile distribution, that extend the
-functionality provided by the Guile Scheme core, most notably:
+functionality provided by the Guile Scheme core. Two important examples
+are:
@itemize @bullet
@item
the POSIX module, which provides Scheme level procedures for system and
-network programming, conforming to the POSIX standard
+network programming that conform to the POSIX standard
@item
the SLIB module, which makes Aubrey Jaffer's portable Scheme library
available for use in Guile.
@end itemize
-@strong{Part IV: Guile Scripting} documents the use of Guile as a script
-interpreter, and illustrates this with a series of examples.
-
-@strong{Part V: Extending Applications Using Guile} explains the options
-available for using Guile as a application extension language. At the
-simpler end of the scale, an application might use Guile to define some
-application-specific primitives in C and then load an application Scheme
-file. In this case most of the application code is written on the
-Scheme level, and uses the application-specific primitives as an
-extension to standard Scheme. At the other end of the scale, an
-application might be predominantly written in C --- with its main
-control loop implemented in C --- but make occasional forays into Scheme
-to, say, read configuration data or run user-defined customization code.
-This part of the manual covers the complete range of application
-extension options.
-
-Finally, the appendices explain how to obtain the latest version of
-Guile, how to install it, where to find modules to work with Guile, and
-how to use the Guile debugger.
-
@iftex
@section Manual Conventions
diff --git a/doc/ref/program.texi b/doc/ref/program.texi
new file mode 100644
index 000000000..b6d268981
--- /dev/null
+++ b/doc/ref/program.texi
@@ -0,0 +1,199 @@
+@page
+@node Programming Options
+@chapter Programming Options in Guile
+
+What does it mean to program using Guile?
+
+If you are an application developer, and want to combine Guile in some
+way with your application, there is a range of possibilities available
+to you@dots{}
+
+@itemize @bullet
+@item
+You could choose to write your whole application in Scheme (or one of
+the other high level languages that Guile supports through translation),
+and simply use Guile as an interpreter (and hopefully in the future a
+compiler) for Scheme.
+
+@item
+You could write a small amount of C code that implements domain-specific
+@dfn{primitive} functions for your application and connects these to the
+Scheme level of Guile, and then write the rest of your application,
+using these application-specific primitives, in Scheme.
+
+@item
+You could write almost all of your application in C, and only call out
+to Guile occasionally for specific actions such as reading a
+configuration file or executing a user-specified extension.
+@end itemize
+
+Underlying these choices are two basic questions.
+
+@itemize @bullet
+@item
+Which parts of the application do you write in C, and which in Scheme
+(or another high level translated language)?
+
+@item
+How do you design the interface between the C and Scheme parts of your
+application?
+@end itemize
+
+These are of course design questions, and the right design for any given
+application will always depend upon the particular requirements that you
+are trying to meet. In the Guile world, however, there are some
+generally applicable considerations that can help you when searching for
+the answers.
+
+@menu
+* Available Functionality:: What functionality is already available?
+* Basic Constraints:: Functional and performance constraints.
+* Style Choices:: Your preferred programming style.
+* Program Control:: What controls program execution?
+* User Programming:: How about application users?
+@end menu
+
+
+@node Available Functionality
+@section What Functionality is Already Available?
+
+Suppose, for the sake of argument, that you would prefer to write your
+whole application in Scheme. Then the API available to you consists of:
+
+@itemize @bullet
+@item
+standard Scheme
+
+@item
+plus the extensions to standard Scheme provided by
+Guile in its core distribution
+
+@item
+plus any additional functionality that you or others have packaged so
+that it can be loaded as a Guile Scheme module.
+@end itemize
+
+A module in the last category can either be a pure Scheme module --- in
+other words a collection of utility procedures coded in Scheme --- or a
+module that provides a Scheme interface to an extension library coded in
+C --- in other words a nice package where someone else has done the work
+of wrapping up some useful C code for you. The set of available modules
+is growing quickly and already includes such useful examples as
+@code{(gtk gtk)}, which makes Gtk+ drawing functions available in
+Scheme, and @code{(database postgres)}, which provides SQL access to a
+Postgres database.
+
+In practice, therefore, it is quite feasible that your application can
+be implemented by combining together a selection of pre-existing modules
+with new application code written in Scheme, and approach may
+suffice for the application that you want to write.
+
+If it does not suffice, because the functionality that your application
+needs is not already available in this form (and assuming that it's
+impossible or unacceptable for performance reasons to write the new
+functionality in Scheme), you will need to write some C code.
+
+@itemize @bullet
+@item
+If the required function is already written (e.g. in a library), you
+only need a little glue to connect it to the world of Guile.
+
+@item
+If not, you need to write the basic code as well.
+@end itemize
+
+In either case, two general considerations are important. Firstly, what
+is the interface by which the functionality is presented to the Scheme
+world? Does the interface consist only of function calls (for example,
+a simple drawing interface), or does it need to include @dfn{objects} of
+some kind that can be passed between C and Scheme and manipulated by
+both worlds. Secondly, how does the lifetime and memory management of
+objects in the C code relate to the garbage collection governed approach
+of Scheme objects? In the case where the basic C code is not already
+written, most of the difficulties of memory management can be avoided by
+using Guile's C interface features from the start.
+
+For further information, tips and guidelines on writing C code for
+Guile, or for connecting existing C code to the Guile world, see
+REFFIXME.
+
+
+@node Basic Constraints
+@section Functional and Performance Constraints
+
+
+@node Style Choices
+@section Your Preferred Programming Style
+
+
+@node Program Control
+@section What Controls Program Execution?
+
+What indeed?
+
+
+@node User Programming
+@section How About Application Users?
+
+So far we have considered what Guile programming means for an
+application developer. But what if you are instead @emph{using} an
+existing Guile-based application, and want to know what your
+options are for programming and extending this application?
+
+The answer to this question varies from one application to another,
+because the options available depend inevitably on whether the
+application developer has provided any hooks for you to hang your own
+code on and, if there are such hooks, what they allow you to
+do.@footnote{Of course, in the world of free software, you always have
+the freedom to modify the application's source code to your own
+requirements. Here we are concerned with the extension options that the
+application has provided for without your needing to modify its source
+code.} For example@dots{}
+
+@itemize @bullet
+@item
+If the application permits you to load and execute any Guile code, the
+world is your oyster. You can extend the application in any way that
+you choose.
+
+@item
+A more cautious application might allow you to load and execute Guile
+code, but only in a @dfn{safe} environment, where the interface
+available is restricted by the application from the standard Guile API.
+
+@item
+Or a really fearful application might not provide a hook to really
+execute user code at all, but just use Scheme syntax as a convenient way
+for users to specify application data or configuration options.
+@end itemize
+
+In the last two cases, what you can do is, by definition, restricted by
+the application, and you should refer to the application's own manual to
+find out your options.
+
+The most well known example of the first case is Emacs, with its
+extension language Emacs Lisp: as well as being a text editor, Emacs
+supports the loading and execution of arbitrary Emacs Lisp code. The
+result of such openness has been dramatic: Emacs now benefits from
+user-contributed Emacs Lisp libraries that extend the basic editing
+function to do everything from reading news to psychoanalysis and
+playing adventure games. The only limitation is that extensions are
+restricted to the functionality provided by Emacs's built-in set of
+primitive operations. For example, you can interact and display data by
+manipulating the contents of an Emacs buffer, but you can't popup and
+draw a window with a layout that is totally different to the Emacs
+standard.
+
+This situation with a Guile application that supports the loading of
+arbitrary user code is similar, except perhaps even more so, because
+Guile also supports the loading of extension libraries written in C.
+This last point enables user code to add new primitive operations to
+Guile, and so to bypass the limitation present in Emacs Lisp.
+
+At this point, the distinction between an application developer and an
+application user becomes rather blurred. Instead of seeing yourself as
+a user extending an application, you could equally well say that you are
+developing a new application of your own using some of the primitive
+functionality provided by the original application. As such, all the
+discussions of the preceding sections of this chapter are relevant to
+how you can proceed with developing your extension.
diff --git a/doc/ref/scheme-binding.texi b/doc/ref/scheme-binding.texi
index b37bced03..5e476141e 100644
--- a/doc/ref/scheme-binding.texi
+++ b/doc/ref/scheme-binding.texi
@@ -233,7 +233,7 @@ bound in expression, you can use the @code{bound?} macro from the module
@c NJFIXME explain [env]
@deffn primitive defined? sym [env]
-Return @code{#t} if @var{sym} is defined in the top-level environment.
+Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
@end deffn
diff --git a/doc/ref/scheme-control.texi b/doc/ref/scheme-control.texi
index dd5f9be53..d7b95151b 100644
--- a/doc/ref/scheme-control.texi
+++ b/doc/ref/scheme-control.texi
@@ -12,6 +12,7 @@
* Exceptions:: Throwing and catching exceptions.
* Error Reporting:: Procedures for signaling errors.
* Dynamic Wind:: Guarding against non-local entrance/exit.
+* Handling Errors:: How to handle errors in C code.
@end menu
@@ -818,6 +819,143 @@ a-cont
@result{} special-binding
@end lisp
@end deffn
+
+
+@node Handling Errors
+@section 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
+
+
+@subsection 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 Local Variables:
@c TeX-master: "guile.texi"
@c End:
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
index 0adf9abfc..235644c63 100755
--- a/doc/ref/scheme-data.texi
+++ b/doc/ref/scheme-data.texi
@@ -956,32 +956,33 @@ Return the hyperbolic arctangent of @var{x}.
@subsection Bitwise Operations
@deffn primitive logand n1 n2
-Return the integer which is the bit-wise AND of the two integer
-arguments.
+Return the bitwise AND of the integer arguments.
@lisp
-(number->string (logand #b1100 #b1010) 2)
- @result{} "1000"
+(logand) @result{} -1
+(logand 7) @result{} 7
+(logand #b111 #b011 #b001) @result{} 1
@end lisp
@end deffn
@deffn primitive logior n1 n2
-Return the integer which is the bit-wise OR of the two integer
-arguments.
+Return the bitwise OR of the integer arguments.
@lisp
-(number->string (logior #b1100 #b1010) 2)
- @result{} "1110"
+(logior) @result{} 0
+(logior 7) @result{} 7
+(logior #b000 #b001 #b011) @result{} 3
@end lisp
@end deffn
@deffn primitive logxor n1 n2
-Return the integer which is the bit-wise XOR of the two integer
-arguments.
-
+Return the bitwise XOR of the integer arguments. A bit is
+set in the result if it is set in an odd number of arguments.
@lisp
-(number->string (logxor #b1100 #b1010) 2)
- @result{} "110"
+(logxor) @result{} 0
+(logxor 7) @result{} 7
+(logxor #b000 #b001 #b011) @result{} 2
+(logxor #b000 #b001 #b011 #b011) @result{} 1
@end lisp
@end deffn
@@ -1468,16 +1469,17 @@ Split the string @var{str} into the a list of the substrings delimited
by appearances of the character @var{chr}. Note that an empty substring
between separator characters will result in an empty string in the
result list.
+
@lisp
-(string-split "root:x:0:0:root:/root:/bin/bash" #\:)
+(string-split "root:x:0:0:root:/root:/bin/bash" #:)
@result{}
("root" "x" "0" "0" "root" "/root" "/bin/bash")
-(string-split "::" #\:)
+(string-split "::" #:)
@result{}
("" "" "")
-(string-split "" #\:)
+(string-split "" #:)
@result{}
("")
@end lisp
@@ -1554,7 +1556,7 @@ y
@deffnx primitive substring-move-left! str1 start1 end1 str2 start2
@deffnx primitive substring-move-right! str1 start1 end1 str2 start2
Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
-into @var{str2} beginning at position @var{end2}.
+into @var{str2} beginning at position @var{start2}.
@code{substring-move-right!} begins copying from the rightmost character
and moves left, and @code{substring-move-left!} copies from the leftmost
character moving right.
@@ -1916,6 +1918,20 @@ Match the compiled regular expression @var{rx} against
provided, begin matching from that position in the string.
Return a match structure describing the results of the match,
or @code{#f} if no match could be found.
+
+The @var{flags} arguments change the matching behavior.
+The following flags may be supplied:
+
+@table @code
+@item regexp/notbol
+Operator @samp{^} always fails (unless @code{regexp/newline}
+is used). Use this when the beginning of the string should
+not be considered the beginning of a line.
+@item regexp/noteol
+Operator @samp{$} always fails (unless @code{regexp/newline}
+is used). Use this when the end of the string should not be
+considered the end of a line.
+@end table
@end deffn
@deffn primitive regexp? obj
@@ -2394,7 +2410,7 @@ part of an object returned as the value of a literal expression
Report on Scheme}) or by a call to the @code{read} procedure,
and its name contains alphabetic characters, then the string
returned will contain characters in the implementation's
-preferred standard case--some implementations will prefer
+preferred standard case---some implementations will prefer
upper case, others lower case. If the symbol was returned by
@code{string->symbol}, the case of characters in the string
returned will be the same as the case in the string that was
@@ -2541,20 +2557,12 @@ Return the built-in variable with the name @var{name}.
Then use @code{variable-ref} to access its value.
@end deffn
-@deffn primitive make-undefined-variable [name-hint]
-Return a variable object initialized to an undefined value.
-If given, uses @var{name-hint} as its internal (debugging)
-name, otherwise just treat it as an anonymous variable.
-Remember, of course, that multiple bindings to the same
-variable may exist, so @var{name-hint} is just that---a hint.
+@deffn primitive make-undefined-variable
+Return a variable that is initially unbound.
@end deffn
-@deffn primitive make-variable init [name-hint]
-Return a variable object initialized to value @var{init}.
-If given, uses @var{name-hint} as its internal (debugging)
-name, otherwise just treat it as an anonymous variable.
-Remember, of course, that multiple bindings to the same
-variable may exist, so @var{name-hint} is just that---a hint.
+@deffn primitive make-variable init
+Return a variable initialized to value @var{init}.
@end deffn
@deffn primitive variable-bound? var
@@ -2576,7 +2584,7 @@ value. Return an unspecified value.
@deffn primitive variable? obj
Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}
+return @code{#f}.
@end deffn
diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi
index d9387f5d0..170d7e382 100644
--- a/doc/ref/scheme-debug.texi
+++ b/doc/ref/scheme-debug.texi
@@ -173,8 +173,8 @@ Return the identifier given to @var{stack} by @code{start-stack}.
Return the length of @var{stack}.
@end deffn
-@deffn primitive stack-ref stack i
-Return the @var{i}'th frame from @var{stack}.
+@deffn primitive stack-ref stack index
+Return the @var{index}'th frame from @var{stack}.
@end deffn
@deffn primitive stack? obj
diff --git a/doc/ref/scheme-indices.texi b/doc/ref/scheme-indices.texi
index 03a21bb30..46a87b3d8 100644
--- a/doc/ref/scheme-indices.texi
+++ b/doc/ref/scheme-indices.texi
@@ -1,13 +1,13 @@
@page
@node R5RS Index
-@chapter R5RS Index
+@unnumbered R5RS Index
@printindex rn
@page
@node Guile Extensions Index
-@chapter Guile Extensions Index
+@unnumbered Guile Extensions Index
@printindex ge
diff --git a/doc/ref/scheme-io.texi b/doc/ref/scheme-io.texi
index 07a258868..a121823a5 100644
--- a/doc/ref/scheme-io.texi
+++ b/doc/ref/scheme-io.texi
@@ -12,6 +12,7 @@
* Block Reading and Writing:: Reading and writing blocks of text.
* Default Ports:: Defaults for input, output and errors.
* Port Types:: Types of port and how to make them.
+* I/O Extensions:: Using and extending ports in C.
@end menu
@@ -119,8 +120,20 @@ unread characters will be read again in last-in first-out order. If
@end deffn
@deffn primitive drain-input port
-Drain @var{port}'s read buffers (including any pushed-back
-characters) and return the content as a single string.
+This procedure clears a port's input buffers, similar
+to the way that force-output clears the output buffer. The
+contents of the buffers are returned as a single string, e.g.,
+
+@lisp
+(define p (open-input-file ...))
+(drain-input p) => empty string, nothing buffered yet.
+(unread-char (read-char p) p)
+(drain-input p) => initial chars from p, up to the buffer size.
+@end lisp
+
+Draining the buffers may be useful for cleanly finishing
+buffered I/O so that the file descriptor can be used directly
+for further input.
@end deffn
@deffn primitive port-column port
@@ -419,7 +432,7 @@ The Block-string-I/O module can be accessed with:
It currently contains procedures that help to implement the
@code{(scsh rw)} module in guile-scsh.
-@deffn primitive read-string!/partial str [port_or_fdes start end]
+@deffn primitive read-string!/partial str [port_or_fdes [start [end]]]
Read characters from a port or file descriptor into a
string @var{str}. A port must have an underlying file
descriptor --- a so-called fport. This procedure is
@@ -830,6 +843,221 @@ modes for this port: see the documentation for @code{open-file} in
@end deffn
+@node I/O Extensions
+@section 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
+@subsection C Port Interface
+
+This section describes how to use Scheme ports from C.
+
+@subsubsection 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.
+
+@subsubsection 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.
+
+@subsubsection 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.
+
+@subsubsection 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
+
+@subsubsection 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
+
+@subsubsection 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
+@subsection 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
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
diff --git a/doc/ref/scheme-memory.texi b/doc/ref/scheme-memory.texi
index 6a1f21e9c..e29fd8607 100644
--- a/doc/ref/scheme-memory.texi
+++ b/doc/ref/scheme-memory.texi
@@ -202,7 +202,7 @@ Return @code{#t} if @var{obj} is an operator.
@end deffn
@deffn primitive set-object-procedure! obj proc
-Return the object procedure of @var{obj} to @var{proc}.
+Set the object procedure of @var{obj} to @var{proc}.
@var{obj} must be either an entity or an operator.
@end deffn
diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi
index d591008fe..d009a4d01 100644
--- a/doc/ref/scheme-options.texi
+++ b/doc/ref/scheme-options.texi
@@ -335,8 +335,8 @@ Guile's configuration at run time.
@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.
+Return a string describing Guile's version number, or its major, minor
+and micro version numbers, respectively.
@lisp
(version) @result{} "1.6.5"
diff --git a/doc/ref/scm.texi b/doc/ref/scm.texi
index 2cda191d8..948823afb 100644
--- a/doc/ref/scm.texi
+++ b/doc/ref/scm.texi
@@ -101,358 +101,3 @@ 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.