mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-16 08:40:19 +02:00
Code Activity

* Documentation work.

Browse source
This commit is contained in:
Neil Jerram 2001-11-11 15:01:52 +00:00
parent a0a9b9ad42
commit 9401323e63
42 changed files with 3992 additions and 3319 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc/maint/ChangeLog
View file

@ -1,3 +1,13 @@
2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
* guile.texi: Replaced by libguile version (after automatically
updating docstrings in the reference manual).
* docstring.el (docstring-manual-directory): Added "/ref" to end.
(docstring-manual-files): Now calculated automatically, since by
definition all the .texi files in doc/ref are reference manual
files.
2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de> 2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* guile.texi: Automated docstring merging. * guile.texi: Automated docstring merging.

35
doc/maint/docstring.el
View file

@ -57,7 +57,7 @@
;;; Code: ;;; Code:
(defvar docstring-manual-directory (expand-file-name "~/Guile/cvs/guile-core/doc") (defvar docstring-manual-directory (expand-file-name "~/Guile/cvs/guile-core/doc/ref")
"*The directory containing the Texinfo source for the Guile reference manual.") "*The directory containing the Texinfo source for the Guile reference manual.")
(defvar docstring-tracking-root (expand-file-name "~/Guile/cvs/guile-core/doc/maint") (defvar docstring-tracking-root (expand-file-name "~/Guile/cvs/guile-core/doc/maint")
@ -72,37 +72,8 @@ for module (a b c) is expected to be in the file
For each entry in this list, the snarfed docstring file for module (a For each entry in this list, the snarfed docstring file for module (a
b c) is looked for in the file <entry>/a/b/c.texi.") b c) is looked for in the file <entry>/a/b/c.texi.")
(defvar docstring-manual-files '("appendices.texi" (defvar docstring-manual-files
"deprecated.texi" (directory-files docstring-manual-directory nil "\\.texi$" t)
"expect.texi"
"gh.texi"
"goops.texi"
"guile.texi"
"indices.texi"
"intro.texi"
"posix.texi"
"scheme-binding.texi"
"scheme-control.texi"
"scheme-data.texi"
"scheme-debug.texi"
"scheme-evaluation.texi"
"scheme-ideas.texi"
"scheme-indices.texi"
"scheme-intro.texi"
"scheme-io.texi"
"scheme-memory.texi"
"scheme-modules.texi"
"scheme-options.texi"
"scheme-procedures.texi"
"scheme-reading.texi"
"scheme-scheduling.texi"
"scheme-translation.texi"
"scheme-utility.texi"
"scm.texi"
"scripts.texi"
"scsh.texi"
"slib.texi"
"tcltk.texi")
"List of Texinfo source files that comprise the Guile reference manual.") "List of Texinfo source files that comprise the Guile reference manual.")
(defvar docstring-new-docstrings-file "new-docstrings.texi" (defvar docstring-new-docstrings-file "new-docstrings.texi"

5412
doc/maint/guile.texi
View file

File diff suppressed because it is too large Load diff

58
doc/ref/ChangeLog
View file

@ -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> 2001-11-06 Thien-Thi Nguyen <ttn@glug.org>
* srfi-modules.texi (SRFI-19, SRFI-19 Constants, SRFI-19 Current * srfi-modules.texi (SRFI-19, SRFI-19 Constants, SRFI-19 Current

4
doc/ref/Makefile.am
View file

@ -23,7 +23,7 @@ AUTOMAKE_OPTIONS = gnu
info_TEXINFOS = guile.texi 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-ideas.texi scheme-data.texi scheme-procedures.texi \
scheme-utility.texi scheme-binding.texi scheme-control.texi \ scheme-utility.texi scheme-binding.texi scheme-control.texi \
scheme-io.texi scheme-evaluation.texi scheme-memory.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-translation.texi scheme-debug.texi deprecated.texi \
scheme-reading.texi scheme-indices.texi slib.texi posix.texi \ scheme-reading.texi scheme-indices.texi slib.texi posix.texi \
expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.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 extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi
# Optionally support building an HTML version of the reference manual. # Optionally support building an HTML version of the reference manual.

0
doc/ref/appendices.texi
View file

179
doc/ref/debugging.texi Normal file
View file

@ -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

115
doc/ref/guile.texi
View file

@ -4,6 +4,7 @@
@setfilename guile.info @setfilename guile.info
@settitle Guile Reference Manual @settitle Guile Reference Manual
@set guile @set guile
@set MANUAL_EDITION 1.1
@c %**end of header @c %**end of header
@c Notes: (distilled from Jim's and Tim's notes, and kept up to date) @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 @sp 10
@comment The title is printed in a large font. @comment The title is printed in a large font.
@title Guile Reference Manual @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} @subtitle For use with Guile @value{VERSION}
@c AUTHORS @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 Language for Extensions. It describes how to use Guile in many useful
and interesting ways. and interesting ways.
This Info file contains edition 1.0 of the reference manual, This Info file contains edition @value{MANUAL_EDITION} of the reference
corresponding to Guile version @value{VERSION}. manual, corresponding to Guile version @value{VERSION}.
@end ifinfo @end ifinfo
@menu @menu
@ -190,12 +191,27 @@ Part I: Introduction to Guile
* What is Guile?:: And what does it do? * What is Guile?:: And what does it do?
* Whirlwind Tour:: An introductory whirlwind tour. * Whirlwind Tour:: An introductory whirlwind tour.
* Obtaining and Installing Guile::
* Reporting Bugs:: Reporting bugs in Guile or this manual. * 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. * Scheme Intro:: Introduction to Guile Scheme.
* Basic Ideas:: Basic ideas in 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. * Data Types:: Data types for generic use.
* Procedures and Macros:: Procedures and macros. * Procedures and Macros:: Procedures and macros.
* Utility Functions:: General utility functions. * Utility Functions:: General utility functions.
@ -211,9 +227,8 @@ Part II: Guile Scheme
* Translation:: Support for translating other languages. * Translation:: Support for translating other languages.
* Debugging:: Internal debugging interface. * Debugging:: Internal debugging interface.
* Deprecated:: Features that are planned to disappear. * 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. * SLIB:: Using the SLIB Scheme library.
* POSIX:: POSIX system calls and networking. * POSIX:: POSIX system calls and networking.
@ -224,26 +239,6 @@ Part III: Guile Modules
* Formatted Output:: The @code{format} procedure. * Formatted Output:: The @code{format} procedure.
* Expect:: Controlling interactive programs with Guile. * Expect:: Controlling interactive programs with Guile.
* The Scheme shell (scsh):: Using scsh interfaces in 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 Indices
@ -258,7 +253,6 @@ Indices
@include preface.texi @include preface.texi
@c preliminary
@iftex @iftex
@page @page
@unnumbered{Part I: Introduction to Guile} @unnumbered{Part I: Introduction to Guile}
@ -266,14 +260,37 @@ Indices
@include intro.texi @include intro.texi
@c programming in Scheme
@iftex
@page @page
@unnumbered{Part II: Guile Scheme} @node Programming Intro
@end iftex @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-intro.texi
@include scheme-ideas.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-data.texi
@include scheme-procedures.texi @include scheme-procedures.texi
@include scheme-utility.texi @include scheme-utility.texi
@ -289,13 +306,10 @@ Indices
@include scheme-translation.texi @include scheme-translation.texi
@include scheme-debug.texi @include scheme-debug.texi
@include deprecated.texi @include deprecated.texi
@include scheme-reading.texi
@include scheme-indices.texi
@c Unix system interface
@iftex @iftex
@page @page
@unnumbered{Part III: Guile Modules} @unnumbered{Part IV: Guile Modules}
@end iftex @end iftex
@include slib.texi @include slib.texi
@ -305,43 +319,14 @@ Indices
@include misc-modules.texi @include misc-modules.texi
@include expect.texi @include expect.texi
@include scsh.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 @iftex
@page @page
@unnumbered{Indices} @unnumbered{Indices}
@end iftex @end iftex
@include indices.texi @include indices.texi
@include scheme-indices.texi
@contents @contents

4
doc/ref/indices.texi
View file

@ -1,3 +1,4 @@
@page
@node Concept Index @node Concept Index
@unnumbered Concept Index @unnumbered Concept Index
@ -41,9 +42,6 @@ in the section @xref{Transforming Scheme name to C name}.
@page @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 @node Type Index
@unnumbered Type Index @unnumbered Type Index

113
doc/ref/intro.texi
View file

@ -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 @page
@node What is Guile? @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 choice, rather than having the tastes of the application's author
imposed on them. imposed on them.
@page @page
@node Whirlwind Tour @node Whirlwind Tour
@chapter A Whirlwind Tour @chapter A Whirlwind Tour
@ -582,6 +584,7 @@ guile> (exit)
$ $
@end example @end example
@node Writing Extensions for Guile @node Writing Extensions for Guile
@section Writing Extensions for Guile @section Writing Extensions for Guile
@ -624,6 +627,7 @@ by Guile.
* A Sample Guile Extension:: * A Sample Guile Extension::
@end menu @end menu
@node A Sample Guile Extension @node A Sample Guile Extension
@subsection 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 To see how these Guile extensions via shared libraries relate to the
module system, see below @xref{Intro to Modules and Extensions}. module system, see below @xref{Intro to Modules and Extensions}.
@node Guile Modules @node Guile Modules
@section 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 Details on the module system beyond this introductory material can be found in
@xref{Modules}. @xref{Modules}.
@menu @menu
* Intro to Using Guile Modules:: * Intro to Using Guile Modules::
* Intro to Writing New Modules:: * Intro to Writing New Modules::
* Intro to Modules and Extensions:: * Intro to Modules and Extensions::
@end menu @end menu
@node Intro to Using Guile Modules @node Intro to Using Guile Modules
@subsection Intro to Using Existing 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 Scheme files can be autoloaded. Thus, we recommend that you define
your modules in Scheme. 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 @page
@node Reporting Bugs @node Reporting Bugs
@chapter Reporting Bugs @chapter Reporting Bugs

69
doc/ref/new-docstrings.texi
View file

@ -304,9 +304,11 @@ If @var{l} does not hold a value for @var{key}, the value
@end deffn @end deffn
@deffn primitive slot-ref-using-class class obj slot_name @deffn primitive slot-ref-using-class class obj slot_name
@end deffn @end deffn
@deffn primitive slot-set-using-class! class obj slot_name value @deffn primitive slot-set-using-class! class obj slot_name value
@end deffn @end deffn
@deffn primitive class-of x @deffn primitive class-of x
@ -319,33 +321,43 @@ on the C level which depends on the loaded GOOPS modules.
@end deffn @end deffn
@deffn primitive %method-more-specific? m1 m2 targs @deffn primitive %method-more-specific? m1 m2 targs
@end deffn @end deffn
@deffn primitive find-method . l @deffn primitive find-method . l
@end deffn @end deffn
@deffn primitive primitive-generic-generic subr @deffn primitive primitive-generic-generic subr
@end deffn @end deffn
@deffn primitive enable-primitive-generic! . subrs @deffn primitive enable-primitive-generic! . subrs
@end deffn @end deffn
@deffn primitive generic-capability? proc @deffn primitive generic-capability? proc
@end deffn @end deffn
@deffn primitive %invalidate-method-cache! gf @deffn primitive %invalidate-method-cache! gf
@end deffn @end deffn
@deffn primitive %invalidate-class class @deffn primitive %invalidate-class class
@end deffn @end deffn
@deffn primitive %modify-class old new @deffn primitive %modify-class old new
@end deffn @end deffn
@deffn primitive %modify-instance old new @deffn primitive %modify-instance old new
@end deffn @end deffn
@deffn primitive %set-object-setter! obj setter @deffn primitive %set-object-setter! obj setter
@end deffn @end deffn
@deffn primitive %allocate-instance class initargs @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 @end deffn
@deffn primitive slot-exists-using-class? class obj slot_name @deffn primitive slot-exists-using-class? class obj slot_name
@end deffn @end deffn
@deffn primitive slot-bound-using-class? class obj slot_name @deffn primitive slot-bound-using-class? class obj slot_name
@end deffn @end deffn
@deffn primitive %fast-slot-set! obj index value @deffn primitive %fast-slot-set! obj index value
@ -460,9 +474,11 @@ Return @code{#t} if @var{obj} is an instance.
@end deffn @end deffn
@deffn primitive %inherit-magic! class dsupers @deffn primitive %inherit-magic! class dsupers
@end deffn @end deffn
@deffn primitive %prep-layout! class @deffn primitive %prep-layout! class
@end deffn @end deffn
@deffn primitive %initialize-object obj initargs @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; The argument @var{msgs} should be a list of strings;
they are printed in turn, each one followed by a newline. they are printed in turn, each one followed by a newline.
@end deffn @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

39
doc/ref/posix.texi
View file

@ -1457,26 +1457,35 @@ all platforms.
@end deffn @end deffn
@deffn primitive setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds @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 Set the timer specified by @var{which_timer} according to the given
@var{interval_seconds}, @var{interval_microseconds}, @var{interval_seconds}, @var{interval_microseconds},
@var{value_seconds}, and @var{value_microseconds} values, and return @var{value_seconds}, and @var{value_microseconds} values.
information about the timer's previous setting. The timers available
are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, and @code{ITIMER_PROF}, Return information about the timer's previous setting.
and the return value will be a list of two cons pairs representing the 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 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 microseconds of the timer @code{it_interval}, and the second pair is
seconds and microseconds of the timer @code{it_value}. the seconds and microseconds of the timer @code{it_value}.
@end deffn @end deffn
@deffn primitive getitimer which_timer @deffn primitive getitimer which_timer
Return information about the timer specified by @var{which_timer}. The Return information about the timer specified by @var{which_timer}
timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, and Errors are handled as described in the guile info pages under ``POSIX
@code{ITIMER_PROF}, and the return value will be a list of two cons Interface Conventions''.
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 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
second pair is the seconds and microseconds of the timer and @code{ITIMER_PROF}.
@code{it_value}.
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 @end deffn
@ -2310,7 +2319,7 @@ documentation before using them.
@deffn primitive crypt key salt @deffn primitive crypt key salt
Encrypt @var{key} using @var{salt} as the salt value to the Encrypt @var{key} using @var{salt} as the salt value to the
crypt(3) library call crypt(3) library call.
@end deffn @end deffn
@code{getpass} is no encryption procedure at all, but it is often used @code{getpass} is no encryption procedure at all, but it is often used

87
doc/ref/preface.texi
View file

@ -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 Language for Extensions. It describes how to use Guile in many useful
and interesting ways. and interesting ways.
This is edition 1.0 of the reference manual, and corresponds to Guile This is edition @value{MANUAL_EDITION} of the reference manual, and
version @value{VERSION}. corresponds to Guile version @value{VERSION}.
@end iftex @end iftex
@ -74,57 +74,74 @@ do not wish that, delete this exception notice.
@chapter Layout of this Manual @chapter Layout of this Manual
@end ifnottex @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 @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 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 be used interactively and as a script interpreter, how to link Guile
into your own applications, and how to write modules of interpreted and 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 compiled code for use with Guile. Everything introduced here is
documented in full by the later parts of the manual. 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: Guile Scheme} documents the core Scheme language and @strong{Part II: Programming with Guile} documents all aspects of
features that Guile implements. Although the basis for this is the practical programming using Guile. This covers both the Scheme level
Scheme language described in R5RS, this part of the manual does not --- where we provide an introduction to the key ideas of the Scheme
assume any prior familiarity with R5RS in particular, or with Scheme in language --- and use of Guile's @code{scm} interface to write new
general. Basic Scheme concepts, standard aspects of the Scheme language primitives and objects in C, and to incorporate Guile into a C
and Guile extensions on top of R5RS are all documented from scratch, and application. It also covers the use of Guile as a POSIX compliant
organized by functionality rather than by the defining standards. script interpreter, and how to use the Guile debugger.
@strong{Part III: Guile Modules} describes some important modules, @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 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 @itemize @bullet
@item @item
the POSIX module, which provides Scheme level procedures for system and 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 @item
the SLIB module, which makes Aubrey Jaffer's portable Scheme library the SLIB module, which makes Aubrey Jaffer's portable Scheme library
available for use in Guile. available for use in Guile.
@end itemize @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 @iftex
@section Manual Conventions @section Manual Conventions

199
doc/ref/program.texi Normal file
View file

@ -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.

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

@ -233,7 +233,7 @@ bound in expression, you can use the @code{bound?} macro from the module
@c NJFIXME explain [env] @c NJFIXME explain [env]
@deffn primitive defined? sym [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 @end deffn

138
doc/ref/scheme-control.texi
View file

@ -12,6 +12,7 @@
* Exceptions:: Throwing and catching exceptions. * Exceptions:: Throwing and catching exceptions.
* Error Reporting:: Procedures for signaling errors. * Error Reporting:: Procedures for signaling errors.
* Dynamic Wind:: Guarding against non-local entrance/exit. * Dynamic Wind:: Guarding against non-local entrance/exit.
* Handling Errors:: How to handle errors in C code.
@end menu @end menu
@ -818,6 +819,143 @@ a-cont
@result{} special-binding @result{} special-binding
@end lisp @end lisp
@end deffn @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 Local Variables:
@c TeX-master: "guile.texi" @c TeX-master: "guile.texi"
@c End: @c End:

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

@ -956,32 +956,33 @@ Return the hyperbolic arctangent of @var{x}.
@subsection Bitwise Operations @subsection Bitwise Operations
@deffn primitive logand n1 n2 @deffn primitive logand n1 n2
Return the integer which is the bit-wise AND of the two integer Return the bitwise AND of the integer arguments.
arguments.
@lisp @lisp
(number->string (logand #b1100 #b1010) 2) (logand) @result{} -1
@result{} "1000" (logand 7) @result{} 7
(logand #b111 #b011 #b001) @result{} 1
@end lisp @end lisp
@end deffn @end deffn
@deffn primitive logior n1 n2 @deffn primitive logior n1 n2
Return the integer which is the bit-wise OR of the two integer Return the bitwise OR of the integer arguments.
arguments.
@lisp @lisp
(number->string (logior #b1100 #b1010) 2) (logior) @result{} 0
@result{} "1110" (logior 7) @result{} 7
(logior #b000 #b001 #b011) @result{} 3
@end lisp @end lisp
@end deffn @end deffn
@deffn primitive logxor n1 n2 @deffn primitive logxor n1 n2
Return the integer which is the bit-wise XOR of the two integer Return the bitwise XOR of the integer arguments. A bit is
arguments. set in the result if it is set in an odd number of arguments.
@lisp @lisp
(number->string (logxor #b1100 #b1010) 2) (logxor) @result{} 0
@result{} "110" (logxor 7) @result{} 7
(logxor #b000 #b001 #b011) @result{} 2
(logxor #b000 #b001 #b011 #b011) @result{} 1
@end lisp @end lisp
@end deffn @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 by appearances of the character @var{chr}. Note that an empty substring
between separator characters will result in an empty string in the between separator characters will result in an empty string in the
result list. result list.
@lisp @lisp
(string-split "root:x:0:0:root:/root:/bin/bash" #\:) (string-split "root:x:0:0:root:/root:/bin/bash" #:)
@result{} @result{}
("root" "x" "0" "0" "root" "/root" "/bin/bash") ("root" "x" "0" "0" "root" "/root" "/bin/bash")
(string-split "::" #\:) (string-split "::" #:)
@result{} @result{}
("" "" "") ("" "" "")
(string-split "" #\:) (string-split "" #:)
@result{} @result{}
("") ("")
@end lisp @end lisp
@ -1554,7 +1556,7 @@ y
@deffnx primitive substring-move-left! str1 start1 end1 str2 start2 @deffnx primitive substring-move-left! str1 start1 end1 str2 start2
@deffnx primitive substring-move-right! 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} 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 @code{substring-move-right!} begins copying from the rightmost character
and moves left, and @code{substring-move-left!} copies from the leftmost and moves left, and @code{substring-move-left!} copies from the leftmost
character moving right. character moving right.
@ -1916,6 +1918,20 @@ Match the compiled regular expression @var{rx} against
provided, begin matching from that position in the string. provided, begin matching from that position in the string.
Return a match structure describing the results of the match, Return a match structure describing the results of the match,
or @code{#f} if no match could be found. 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 @end deffn
@deffn primitive regexp? obj @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, Report on Scheme}) or by a call to the @code{read} procedure,
and its name contains alphabetic characters, then the string and its name contains alphabetic characters, then the string
returned will contain characters in the implementation's 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 upper case, others lower case. If the symbol was returned by
@code{string->symbol}, the case of characters in the string @code{string->symbol}, the case of characters in the string
returned will be the same as the case in the string that was 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. Then use @code{variable-ref} to access its value.
@end deffn @end deffn
@deffn primitive make-undefined-variable [name-hint] @deffn primitive make-undefined-variable
Return a variable object initialized to an undefined value. Return a variable that is initially unbound.
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.
@end deffn @end deffn
@deffn primitive make-variable init [name-hint] @deffn primitive make-variable init
Return a variable object initialized to value @var{init}. Return a variable 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.
@end deffn @end deffn
@deffn primitive variable-bound? var @deffn primitive variable-bound? var
@ -2576,7 +2584,7 @@ value. Return an unspecified value.
@deffn primitive variable? obj @deffn primitive variable? obj
Return @code{#t} iff @var{obj} is a variable object, else Return @code{#t} iff @var{obj} is a variable object, else
return @code{#f} return @code{#f}.
@end deffn @end deffn

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

@ -173,8 +173,8 @@ Return the identifier given to @var{stack} by @code{start-stack}.
Return the length of @var{stack}. Return the length of @var{stack}.
@end deffn @end deffn
@deffn primitive stack-ref stack i @deffn primitive stack-ref stack index
Return the @var{i}'th frame from @var{stack}. Return the @var{index}'th frame from @var{stack}.
@end deffn @end deffn
@deffn primitive stack? obj @deffn primitive stack? obj

4
doc/ref/scheme-indices.texi
View file

@ -1,13 +1,13 @@
@page @page
@node R5RS Index @node R5RS Index
@chapter R5RS Index @unnumbered R5RS Index
@printindex rn @printindex rn
@page @page
@node Guile Extensions Index @node Guile Extensions Index
@chapter Guile Extensions Index @unnumbered Guile Extensions Index
@printindex ge @printindex ge

234
doc/ref/scheme-io.texi
View file

@ -12,6 +12,7 @@
* Block Reading and Writing:: Reading and writing blocks of text. * Block Reading and Writing:: Reading and writing blocks of text.
* Default Ports:: Defaults for input, output and errors. * Default Ports:: Defaults for input, output and errors.
* Port Types:: Types of port and how to make them. * Port Types:: Types of port and how to make them.
* I/O Extensions:: Using and extending ports in C.
@end menu @end menu
@ -119,8 +120,20 @@ unread characters will be read again in last-in first-out order. If
@end deffn @end deffn
@deffn primitive drain-input port @deffn primitive drain-input port
Drain @var{port}'s read buffers (including any pushed-back This procedure clears a port's input buffers, similar
characters) and return the content as a single string. 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 @end deffn
@deffn primitive port-column port @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 It currently contains procedures that help to implement the
@code{(scsh rw)} module in guile-scsh. @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 Read characters from a port or file descriptor into a
string @var{str}. A port must have an underlying file string @var{str}. A port must have an underlying file
descriptor --- a so-called fport. This procedure is 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 @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 Local Variables:
@c TeX-master: "guile.texi" @c TeX-master: "guile.texi"
@c End: @c End:

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

@ -202,7 +202,7 @@ Return @code{#t} if @var{obj} is an operator.
@end deffn @end deffn
@deffn primitive set-object-procedure! obj proc @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. @var{obj} must be either an entity or an operator.
@end deffn @end deffn

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

@ -335,8 +335,8 @@ Guile's configuration at run time.
@deffnx primitive major-version @deffnx primitive major-version
@deffnx primitive minor-version @deffnx primitive minor-version
@deffnx primitive micro-version @deffnx primitive micro-version
Return a string describing Guile's version number, or its major or minor Return a string describing Guile's version number, or its major, minor
version numbers, respectively. and micro version numbers, respectively.
@lisp @lisp
(version) @result{} "1.6.5" (version) @result{} "1.6.5"

355
doc/ref/scm.texi
View file

@ -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 ``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 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.

25
libguile/ChangeLog
View file

@ -1,3 +1,28 @@
2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
* extensions.c (scm_load_extension): Canonicalize docstring
whitespace.
* unif.c (scm_uniform_array_write), ports.c
(scm_current_output_port, scm_force_output), dynwind.c
(scm_dynamic_wind), scmsigs.c (scm_setitimer, scm_getitimer),
filesys.c (scm_open, scm_lstat), struct.c
(scm_make_struct_layout), random.c (scm_random,
scm_random_solid_sphere_x, scm_random_hollow_sphere_x, strop.c
(scm_i_index): Remove superfluous whitespace from end of docstring
lines.
* filesys.c (scm_select), guardians.c (scm_guardian_greedy_p),
strings.c (scm_make_string), variable.c (scm_make_variable,
scm_make_undefined_variable, scm_variable_p, scm_variable_set_x,
scm_variable_bound_p), scmsigs.c (scm_setitimer, scm_getitimer),
posix.c (scm_crypt), struct.c (scm_make_vtable_vtable), hashtab.c
(scm_hash_fold), ports.c (scm_port_for_each): Remove superfluous
newline at end of docstrings.
* modules.c (scm_set_current_module): Add missing newline to
docstring.
2001-11-07 Stefan Jahn <stefan@lkcc.org> 2001-11-07 Stefan Jahn <stefan@lkcc.org>
* win32-socket.[ch]: New files. Defines Winsock-API error codes * win32-socket.[ch]: New files. Defines Winsock-API error codes

64
libguile/extensions.c
View file

@ -117,36 +117,40 @@ scm_c_load_extension (const char *lib, const char *init)
SCM_DEFINE (scm_load_extension, "load-extension", 2, 0, 0, SCM_DEFINE (scm_load_extension, "load-extension", 2, 0, 0,
(SCM lib, SCM init), (SCM lib, SCM init),
"Load and initilize the extension designated by LIB and INIT." "Load and initilize the extension designated by LIB and INIT.\n"
"When there is no pre-registered function for LIB/INIT, this is " "When there is no pre-registered function for LIB/INIT, this is\n"
"equivalent to " "equivalent to\n"
" " "\n"
" (dynamic-call INIT (dynamic-link LIB)) " "@lisp\n"
" " "(dynamic-call INIT (dynamic-link LIB))\n"
"When there is a pre-registered function, that function is called " "@end lisp\n"
"instead. " "\n"
" " "When there is a pre-registered function, that function is called\n"
"Normally, there is no pre-registered function. This option exists " "instead.\n"
"only for situations where dynamic linking is unavailable or unwanted. " "\n"
"In that case, you would statically link your program with the desired " "Normally, there is no pre-registered function. This option exists\n"
"library, and register its init function right after Guile has been " "only for situations where dynamic linking is unavailable or unwanted.\n"
"initialized. " "In that case, you would statically link your program with the desired\n"
" " "library, and register its init function right after Guile has been\n"
"LIB should be a string denoting a shared library without any file type " "initialized.\n"
"suffix such as \".so\". The suffix is provided automatically. It " "\n"
"should also not contain any directory components. Libraries that " "LIB should be a string denoting a shared library without any file type\n"
"implement Guile Extensions should be put into the normal locations for " "suffix such as \".so\". The suffix is provided automatically. It\n"
"shared libraries. We recommend to use the naming convention " "should also not contain any directory components. Libraries that\n"
"libguile-bla-blum for a extension related to a module `(bla blum)'. " "implement Guile Extensions should be put into the normal locations for\n"
" " "shared libraries. We recommend to use the naming convention\n"
"The normal way for a extension to be used is to write a small Scheme " "libguile-bla-blum for a extension related to a module `(bla blum)'.\n"
"file that defines a module, and to load the extension into this " "\n"
"module. When the module is auto-loaded, the extension is loaded as " "The normal way for a extension to be used is to write a small Scheme\n"
"well. For example, " "file that defines a module, and to load the extension into this\n"
" " "module. When the module is auto-loaded, the extension is loaded as\n"
" (define-module (bla blum)) " "well. For example,\n"
" " "\n"
" (load-extension \"libguile-bla-blum\" \"bla_init_blum\")") "@lisp\n"
"(define-module (bla blum))\n"
"\n"
"(load-extension \"libguile-bla-blum\" \"bla_init_blum\")\n"
"@end lisp")
#define FUNC_NAME s_scm_load_extension #define FUNC_NAME s_scm_load_extension
{ {
SCM_VALIDATE_STRING (1, lib); SCM_VALIDATE_STRING (1, lib);

3
libguile/filesys.c
View file

@ -1129,8 +1129,7 @@ SCM_DEFINE (scm_select, "select", 3, 2, 0,
"The @var{usecs} argument is not supported.\n" "The @var{usecs} argument is not supported.\n"
"Multiple values are returned instead of a list.\n" "Multiple values are returned instead of a list.\n"
"Duplicates in the input vectors appear only once in output.\n" "Duplicates in the input vectors appear only once in output.\n"
"An additional @code{select!} interface is provided.\n" "An additional @code{select!} interface is provided.")
)
#define FUNC_NAME s_scm_select #define FUNC_NAME s_scm_select
{ {
struct timeval timeout; struct timeval timeout;

2
libguile/guardians.c
View file

@ -374,7 +374,7 @@ SCM_DEFINE (scm_guardian_destroyed_p, "guardian-destroyed?", 1, 0, 0,
SCM_DEFINE (scm_guardian_greedy_p, "guardian-greedy?", 1, 0, 0, SCM_DEFINE (scm_guardian_greedy_p, "guardian-greedy?", 1, 0, 0,
(SCM guardian), (SCM guardian),
"Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.\n") "Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.")
#define FUNC_NAME s_scm_guardian_greedy_p #define FUNC_NAME s_scm_guardian_greedy_p
{ {
return SCM_BOOL (GREEDY_P (GUARDIAN_DATA (guardian))); return SCM_BOOL (GREEDY_P (GUARDIAN_DATA (guardian)));

2
libguile/hashtab.c
View file

@ -525,7 +525,7 @@ SCM_DEFINE (scm_hash_fold, "hash-fold", 3, 0, 0,
"prior-result is either INIT (for the first application of PROC)\n" "prior-result is either INIT (for the first application of PROC)\n"
"or the return value of the previous application of PROC.\n" "or the return value of the previous application of PROC.\n"
"For example, @code{(hash-fold acons () tab)} will convert a hash\n" "For example, @code{(hash-fold acons () tab)} will convert a hash\n"
"table into an a-list of key-value pairs.\n") "table into an a-list of key-value pairs.")
#define FUNC_NAME s_scm_hash_fold #define FUNC_NAME s_scm_hash_fold
{ {
SCM_VALIDATE_PROC (1,proc); SCM_VALIDATE_PROC (1,proc);

2
libguile/modules.c
View file

@ -77,7 +77,7 @@ static void scm_post_boot_init_modules (void);
SCM_DEFINE (scm_set_current_module, "set-current-module", 1, 0, 0, SCM_DEFINE (scm_set_current_module, "set-current-module", 1, 0, 0,
(SCM module), (SCM module),
"Set the current module to @var{module} and return" "Set the current module to @var{module} and return\n"
"the previous current module.") "the previous current module.")
#define FUNC_NAME s_scm_set_current_module #define FUNC_NAME s_scm_set_current_module
{ {

2
libguile/ports.c
View file

@ -724,7 +724,7 @@ SCM_DEFINE (scm_port_for_each, "port-for-each", 1, 0, 0,
"@var{proc} is applied exactly once to every port that exists\n" "@var{proc} is applied exactly once to every port that exists\n"
"in the system at the time @var{port-for-each} is invoked.\n" "in the system at the time @var{port-for-each} is invoked.\n"
"Changes to the port table while @var{port-for-each} is running\n" "Changes to the port table while @var{port-for-each} is running\n"
"have no effect as far as @var{port-for-each} is concerned.\n") "have no effect as far as @var{port-for-each} is concerned.")
#define FUNC_NAME s_scm_port_for_each #define FUNC_NAME s_scm_port_for_each
{ {
long i; long i;

2
libguile/posix.c
View file

@ -1328,7 +1328,7 @@ SCM_DEFINE (scm_sync, "sync", 0, 0, 0,
SCM_DEFINE (scm_crypt, "crypt", 2, 0, 0, SCM_DEFINE (scm_crypt, "crypt", 2, 0, 0,
(SCM key, SCM salt), (SCM key, SCM salt),
"Encrypt @var{key} using @var{salt} as the salt value to the\n" "Encrypt @var{key} using @var{salt} as the salt value to the\n"
"crypt(3) library call\n") "crypt(3) library call.")
#define FUNC_NAME s_scm_crypt #define FUNC_NAME s_scm_crypt
{ {
char * p; char * p;

4
libguile/scmsigs.c
View file

@ -440,7 +440,7 @@ SCM_DEFINE (scm_setitimer, "setitimer", 5, 0, 0,
"The return value will be a list of two cons pairs representing the\n" "The return value will be a list of two cons pairs representing the\n"
"current state of the given timer. The first pair is the seconds and\n" "current state of the given timer. The first pair is the seconds and\n"
"microseconds of the timer @code{it_interval}, and the second pair is\n" "microseconds of the timer @code{it_interval}, and the second pair is\n"
"the seconds and microseconds of the timer @code{it_value}.\n") "the seconds and microseconds of the timer @code{it_value}.")
#define FUNC_NAME s_scm_setitimer #define FUNC_NAME s_scm_setitimer
{ {
int rv; int rv;
@ -481,7 +481,7 @@ SCM_DEFINE (scm_getitimer, "getitimer", 1, 0, 0,
"The return value will be a list of two cons pairs representing the\n" "The return value will be a list of two cons pairs representing the\n"
"current state of the given timer. The first pair is the seconds and\n" "current state of the given timer. The first pair is the seconds and\n"
"microseconds of the timer @code{it_interval}, and the second pair is\n" "microseconds of the timer @code{it_interval}, and the second pair is\n"
"the seconds and microseconds of the timer @code{it_value}.\n") "the seconds and microseconds of the timer @code{it_value}.")
#define FUNC_NAME s_scm_getitimer #define FUNC_NAME s_scm_getitimer
{ {
int rv; int rv;

2
libguile/strings.c
View file

@ -211,7 +211,7 @@ SCM_DEFINE (scm_make_string, "make-string", 1, 1, 0,
"Return a newly allocated string of\n" "Return a newly allocated string of\n"
"length @var{k}. If @var{chr} is given, then all elements of\n" "length @var{k}. If @var{chr} is given, then all elements of\n"
"the string are initialized to @var{chr}, otherwise the contents\n" "the string are initialized to @var{chr}, otherwise the contents\n"
"of the @var{string} are unspecified.\n") "of the @var{string} are unspecified.")
#define FUNC_NAME s_scm_make_string #define FUNC_NAME s_scm_make_string
{ {
if (SCM_INUMP (k)) if (SCM_INUMP (k))

2
libguile/struct.c
View file

@ -521,7 +521,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
"(define (make-ball type owner) (make-struct type 0 owner))\n\n" "(define (make-ball type owner) (make-struct type 0 owner))\n\n"
"(define ball (make-ball green 'Nisse))\n" "(define ball (make-ball green 'Nisse))\n"
"ball @result{} #<a green ball owned by Nisse>\n" "ball @result{} #<a green ball owned by Nisse>\n"
"@end lisp\n") "@end lisp")
#define FUNC_NAME s_scm_make_vtable_vtable #define FUNC_NAME s_scm_make_vtable_vtable
{ {
SCM fields; SCM fields;

10
libguile/variable.c
View file

@ -78,7 +78,7 @@ make_variable (SCM init)
SCM_DEFINE (scm_make_variable, "make-variable", 1, 0, 0, SCM_DEFINE (scm_make_variable, "make-variable", 1, 0, 0,
(SCM init), (SCM init),
"Return a variable initialized to value @var{init}.\n") "Return a variable initialized to value @var{init}.")
#define FUNC_NAME s_scm_make_variable #define FUNC_NAME s_scm_make_variable
{ {
return make_variable (init); return make_variable (init);
@ -88,7 +88,7 @@ SCM_DEFINE (scm_make_variable, "make-variable", 1, 0, 0,
SCM_DEFINE (scm_make_undefined_variable, "make-undefined-variable", 0, 0, 0, SCM_DEFINE (scm_make_undefined_variable, "make-undefined-variable", 0, 0, 0,
(), (),
"Return a variable that is initially unbound.\n") "Return a variable that is initially unbound.")
#define FUNC_NAME s_scm_make_undefined_variable #define FUNC_NAME s_scm_make_undefined_variable
{ {
return make_variable (SCM_UNDEFINED); return make_variable (SCM_UNDEFINED);
@ -99,7 +99,7 @@ SCM_DEFINE (scm_make_undefined_variable, "make-undefined-variable", 0, 0, 0,
SCM_DEFINE (scm_variable_p, "variable?", 1, 0, 0, SCM_DEFINE (scm_variable_p, "variable?", 1, 0, 0,
(SCM obj), (SCM obj),
"Return @code{#t} iff @var{obj} is a variable object, else\n" "Return @code{#t} iff @var{obj} is a variable object, else\n"
"return @code{#f}\n") "return @code{#f}.")
#define FUNC_NAME s_scm_variable_p #define FUNC_NAME s_scm_variable_p
{ {
return SCM_BOOL (SCM_VARIABLEP (obj)); return SCM_BOOL (SCM_VARIABLEP (obj));
@ -127,7 +127,7 @@ SCM_DEFINE (scm_variable_set_x, "variable-set!", 2, 0, 0,
(SCM var, SCM val), (SCM var, SCM val),
"Set the value of the variable @var{var} to @var{val}.\n" "Set the value of the variable @var{var} to @var{val}.\n"
"@var{var} must be a variable object, @var{val} can be any\n" "@var{var} must be a variable object, @var{val} can be any\n"
"value. Return an unspecified value.\n") "value. Return an unspecified value.")
#define FUNC_NAME s_scm_variable_set_x #define FUNC_NAME s_scm_variable_set_x
{ {
SCM_VALIDATE_VARIABLE (1, var); SCM_VALIDATE_VARIABLE (1, var);
@ -139,7 +139,7 @@ SCM_DEFINE (scm_variable_set_x, "variable-set!", 2, 0, 0,
SCM_DEFINE (scm_variable_bound_p, "variable-bound?", 1, 0, 0, SCM_DEFINE (scm_variable_bound_p, "variable-bound?", 1, 0, 0,
(SCM var), (SCM var),
"Return @code{#t} iff @var{var} is bound to a value.\n" "Return @code{#t} iff @var{var} is bound to a value.\n"
"Throws an error if @var{var} is not a variable object.\n") "Throws an error if @var{var} is not a variable object.")
#define FUNC_NAME s_scm_variable_bound_p #define FUNC_NAME s_scm_variable_bound_p
{ {
SCM_VALIDATE_VARIABLE (1, var); SCM_VALIDATE_VARIABLE (1, var);

6
srfi/ChangeLog
View file

@ -1,3 +1,9 @@
2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
* srfi-13.c (scm_string_unfold, scm_string_unfold_right),
srfi-14.c (scm_char_set_unfold, scm_char_set_unfold_x): Remove
superfluous whitespace at end of docstring lines.
2001-11-06 Thien-Thi Nguyen <ttn@glug.org> 2001-11-06 Thien-Thi Nguyen <ttn@glug.org>
* srfi-19.scm (time-monotonic->time-monotonic): Spurious; * srfi-19.scm (time-monotonic->time-monotonic): Spurious;