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