mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-10 14:00:21 +02:00
Code Activity

Doc updates, including contribution from Ian Sheldon.

Browse source
This commit is contained in:
Neil Jerram 2002-09-25 00:06:38 +00:00
parent 3553e1d1f0
commit c936bede42
9 changed files with 670 additions and 429 deletions
Download patch file Download diff file Expand all files Collapse all files

33
doc/ref/ChangeLog
View file

@ -1,3 +1,36 @@
2002-09-25 Neil Jerram <neil@ossau.uklinux.net>
* scheme-debug.texi (Debugging): Make sections into nodes.
(Debugging Options): Node removed.
* scheme-options.texi (Feature Tracking): Brought forward before
sections on options.
(Runtime Options): New section, to group options-related nodes.
2002-09-24 Neil Jerram <neil@ossau.uklinux.net>
* scheme-options.texi (Options and Config): Chapter name changed,
and intro text improved.
(Install Config): Brought forward, and renamed Build
Configuration.
The following doc updates are from Ian Sheldon - thanks!
* scheme-data.texi (Appending Strings, Regexp Functions, Match
Structures): Add examples.
(Regular Expressions): Add instruction to use (ice-9 regex)
module.
* slib.texi (SLIB): Remove duplicate `the'.
2002-09-22 Neil Jerram <neil@ossau.uklinux.net>
* scheme-options.texi (General option interface): Mention
eval-options-interface and debug-options-interface.
* scheme-debug.texi (Debugging): New node describing source
properties.
2002-09-19 Neil Jerram <neil@ossau.uklinux.net>
* scheme-utility.texi (Hook Reference): Improvements to hook docs.

4
doc/ref/guile.texi
View file

@ -101,7 +101,7 @@ by the Free Software Foundation.
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle Edition @value{MANUAL_EDITION}, for use with Guile @value{VERSION}
@subtitle $Id: guile.texi,v 1.18 2002-04-20 19:26:40 ossau Exp $
@subtitle $Id: guile.texi,v 1.19 2002-09-25 00:06:38 ossau Exp $
@c AUTHORS
@ -253,7 +253,7 @@ Part IV: Guile API Reference
* Objects:: Low level object orientation support.
* Modules:: Designing reusable code libraries.
* Scheduling:: Threads, mutexes, asyncs and dynamic roots.
* Options and Config:: Runtime options and configuration.
* Options and Config:: Configuration, features and runtime options.
* Translation:: Support for translating other languages.
* Debugging:: Internal debugging interface.
* Deprecated:: Features that are planned to disappear.

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

@ -68,7 +68,7 @@ expressions available.
The readline interface module can be configured in several ways to
better suit the user's needs. Configuration is done via the readline
module's options interface, in a similar way to the evaluator and
debugging options (@pxref{General option interface}.)
debugging options (@pxref{User level options interfaces}.)
Here is the list of readline options generated by typing
@code{(readline-options 'full)} in Guile. You can also see the

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

@ -1901,6 +1901,12 @@ form a longer result string.
@deffnx {C Function} scm_string_append (args)
Return a newly allocated string whose characters form the
concatenation of the given strings, @var{args}.
@example
(let ((h "hello "))
(string-append h "world"))
@result{} "hello world"
@end example
@end deffn
@ -1925,6 +1931,11 @@ as Rx, these functions will not be available. You can tell whether
your Guile installation includes regular expression support by
checking whether @code{(provided? 'regex)} returns true.
The following regexp and string matching features are provided by the
@code{(ice-9 regex)} module. Before using the described functions,
you should load this module by executing @code{(use-modules (ice-9
regex))}.
@menu
* Regexp Functions:: Functions that create and match regexps.
* Match Structures:: Finding what was matched by a regexp.
@ -1932,8 +1943,6 @@ checking whether @code{(provided? 'regex)} returns true.
meta-characters.
@end menu
[FIXME: it may be useful to include an Examples section. Parts of this
interface are bewildering on first glance.]
@node Regexp Functions
@subsection Regexp Functions
@ -1947,7 +1956,6 @@ This regular expression interface was modeled after that
implemented by SCSH, the Scheme Shell. It is intended to be
upwardly compatible with SCSH regular expressions.
@c begin (scm-doc-string "regex.scm" "string-match")
@deffn {Scheme Procedure} string-match pattern str [start]
Compile the string @var{pattern} into a regular expression and compare
it with @var{str}. The optional numeric argument @var{start} specifies
@ -1959,6 +1967,18 @@ expression. @xref{Match Structures}. If @var{str} does not match
@var{pattern} at all, @code{string-match} returns @code{#f}.
@end deffn
Two examples of a match follow. In the first example, the pattern
matches the four digits in the match string. In the second, the pattern
matches nothing.
@example
(string-match "[0-9][0-9][0-9][0-9]" "blah2002")
@result{} #("blah2002" (4 . 8))
(string-match "[A-Za-z]" "123456")
@result{} #f
@end example
Each time @code{string-match} is called, it must compile its
@var{pattern} argument into a regular expression structure. This
operation is expensive, which makes @code{string-match} inefficient if
@ -2030,6 +2050,22 @@ considered the end of a line.
@end table
@end deffn
@lisp
;; Regexp to match uppercase letters
(define r (make-regexp "[A-Z]*"))
;; Regexp to match letters, ignoring case
(define ri (make-regexp "[A-Z]*" regexp/icase))
;; Search for bob using regexp r
(match:substring (regexp-exec r "bob"))
@result{} "" ; no match
;; Search for bob using regexp ri
(match:substring (regexp-exec ri "Bob"))
@result{} "Bob" ; matched case insensitive
@end lisp
@deffn {Scheme Procedure} regexp? obj
@deffnx {C Function} scm_regexp_p (obj)
Return @code{#t} if @var{obj} is a compiled regular expression,
@ -2061,11 +2097,25 @@ The symbol @samp{post}. The portion of the matched string following
the regexp match is written.
@end itemize
@var{port} may be @code{#f}, in which case nothing is written; instead,
@code{regexp-substitute} constructs a string from the specified
@var{item}s and returns that.
The @var{port} argument may be @code{#f}, in which case nothing is
written; instead, @code{regexp-substitute} constructs a string from the
specified @var{item}s and returns that.
@end deffn
The following example takes a regular expression that matches a standard
YYYYMMDD-format date such as @code{"20020828"}. The
@code{regexp-substitute} call returns a string computed from the
information in the match structure, consisting of the fields and text
from the original string reordered and reformatted.
@lisp
(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define s "Date 20020429 12am.")
(define sm (string-match date-regex s))
(regexp-substitute #f sm 'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
@result{} "Date 04-29-2002 12am. (20020429)"
@end lisp
@c begin (scm-doc-string "regex.scm" "regexp-substitute")
@deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
Similar to @code{regexp-substitute}, but can be used to perform global
@ -2092,6 +2142,18 @@ return after processing a single match.
@end itemize
@end deffn
The example above for @code{regexp-substitute} could be rewritten as
follows to remove the @code{string-match} stage:
@lisp
(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
(define s "Date 20020429 12am.")
(regexp-substitute/global #f date-regex s
'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
@result{} "Date 04-29-2002 12am. (20020429)"
@end lisp
@node Match Structures
@subsection Match Structures
@ -2126,19 +2188,54 @@ If the regular expression as a whole matched, but the subexpression
number @var{n} did not match, return @code{#f}.
@end deffn
@lisp
(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
(match:substring s)
@result{} "2002"
;; match starting at offset 6 in the string
(match:substring
(string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6))
@result{} "7654"
@end lisp
@c begin (scm-doc-string "regex.scm" "match:start")
@deffn {Scheme Procedure} match:start match [n]
Return the starting position of submatch number @var{n}.
@end deffn
In the following example, the result is 4, since the match starts at
character index 4:
@lisp
(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
(match:start s)
@result{} 4
@end lisp
@c begin (scm-doc-string "regex.scm" "match:end")
@deffn {Scheme Procedure} match:end match [n]
Return the ending position of submatch number @var{n}.
@end deffn
In the following example, the result is 8, since the match runs between
characters 4 and 8 (i.e. the ``2002'').
@lisp
(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
(match:end s)
@result{} 8
@end lisp
@c begin (scm-doc-string "regex.scm" "match:prefix")
@deffn {Scheme Procedure} match:prefix match
Return the unmatched portion of @var{target} preceding the regexp match.
@lisp
(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
(match:prefix s)
@result{} "blah"
@end lisp
@end deffn
@c begin (scm-doc-string "regex.scm" "match:suffix")
@ -2146,6 +2243,12 @@ Return the unmatched portion of @var{target} preceding the regexp match.
Return the unmatched portion of @var{target} following the regexp match.
@end deffn
@lisp
(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
(match:suffix s)
@result{} "foo"
@end lisp
@c begin (scm-doc-string "regex.scm" "match:count")
@deffn {Scheme Procedure} match:count match
Return the number of parenthesized subexpressions from @var{match}.
@ -2158,6 +2261,13 @@ subexpression, and failed submatches are included in the count.
Return the original @var{target} string.
@end deffn
@lisp
(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo"))
(match:string s)
@result{} "blah2002foo"
@end lisp
@node Backslash Escapes
@subsection Backslash Escapes
@ -2987,8 +3097,8 @@ recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
of the form @code{:NAME} are read as symbols, as required by R5RS.
To enable and disable the alternative non-R5RS keyword syntax, you use
the @code{read-options} procedure documented in @ref{General option
interface} and @ref{Reader options}.
the @code{read-set!} procedure documented in @ref{User level options
interfaces} and @ref{Reader options}.
@smalllisp
(read-set! keywords 'prefix)

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

@ -2,14 +2,63 @@
@node Debugging
@chapter Debugging Infrastructure
@deffn {Scheme Procedure} debug-options-interface [setting]
@deffnx {C Function} scm_debug_options (setting)
Option interface for the debug options. Instead of using
this procedure directly, use the procedures @code{debug-enable},
@code{debug-disable}, @code{debug-set!} and @code{debug-options}.
@end deffn
@menu
* Source Properties:: Remembering the source of an expression.
* Using Traps::
* Capturing the Stack or Innermost Stack Frame::
* Examining the Stack::
* Examining Stack Frames::
* Decoding Memoized Source Expressions::
* Starting a New Stack::
@end menu
@node Source Properties
@section Source Properties
@cindex source properties
As Guile reads in Scheme code from file or from standard input, it
remembers the file name, line number and column number where each
expression begins. These pieces of information are known as the
@dfn{source properties} of the expression. If an expression undergoes
transformation --- for example, if there is a syntax transformer in
effect, or the expression is a macro call --- the source properties are
copied from the untransformed to the transformed expression so that, if
an error occurs when evaluating the transformed expression, Guile's
debugger can point back to the file and location where the expression
originated.
The way that source properties are stored means that Guile can only
associate source properties with parenthesized expressions, and not, for
example, with individual symbols, numbers or strings. The difference
can be seen by typing @code{(xxx)} and @code{xxx} at the Guile prompt
(where the variable @code{xxx} has not been defined):
@example
guile> (xxx)
standard input:2:1: In expression (xxx):
standard input:2:1: Unbound variable: xxx
ABORT: (unbound-variable)
guile> xxx
<unnamed port>: In expression xxx:
<unnamed port>: Unbound variable: xxx
ABORT: (unbound-variable)
@end example
@noindent
In the latter case, no source properties were stored, so the best that
Guile could say regarding the location of the problem was ``<unnamed
port>''.
The recording of source properties is controlled by the read option
named ``positions'' (@pxref{Reader options}). This option is switched
@emph{on} by default, together with the debug options ``debug'' and
``backtrace'' (@pxref{Debugger options}), when Guile is run
interactively; all these options are @emph{off} by default when Guile
runs a script non-interactively.
@node Using Traps
@section Using Traps
@deffn {Scheme Procedure} with-traps thunk
@ -23,6 +72,7 @@ Return @code{#t} if @var{obj} is a debug object.
@end deffn
@node Capturing the Stack or Innermost Stack Frame
@section Capturing the Stack or Innermost Stack Frame
When an error occurs in a running program, or the program hits a
@ -72,6 +122,7 @@ debug object or a continuation.
@end deffn
@node Examining the Stack
@section Examining the Stack
@deffn {Scheme Procedure} stack? obj
@ -104,6 +155,7 @@ which means that default values will be used.
@end deffn
@node Examining Stack Frames
@section Examining Stack Frames
@deffn {Scheme Procedure} frame? obj
@ -172,6 +224,7 @@ output.
@end deffn
@node Decoding Memoized Source Expressions
@section Decoding Memoized Source Expressions
@deffn {Scheme Procedure} memoized? obj
@ -190,6 +243,7 @@ Return the environment of the memoized expression @var{m}.
@end deffn
@node Starting a New Stack
@section Starting a New Stack
@deffn {Scheme Syntax} start-stack id exp

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

@ -144,8 +144,8 @@ Any whitespace before the next token is discarded.
@end deffn
The behaviour of Guile's Scheme reader can be modified by manipulating
its read options. For more information about options, @xref{General
option interface}. If you want to know which reader options are
its read options. For more information about options, @xref{User level
options interfaces}. If you want to know which reader options are
available, @xref{Reader options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there
@ -358,8 +358,8 @@ is implicit).
@c `Evaluator options' under `Options and Config'.
The behaviour of Guile's evaluator can be modified by manipulating the
evaluator options. For more information about options, @xref{General
option interface}. If you want to know which evaluator options are
evaluator options. For more information about options, @xref{User level
options interfaces}. If you want to know which evaluator options are
available, @xref{Evaluator options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there

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

@ -168,18 +168,18 @@ algorithmically @dfn{rename} bindings. In contrast, when using the
providing module's public interface, the entire export list is available
without renaming (@pxref{Using Guile Modules}).
To use a module, it must be found and loaded. All Guile modules have
a unique @dfn{module name}, which is a list of one or more symbols.
Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When
Guile searches for the code of a module, it constructs the name of the
file to load by concatenating the name elements with slashes between
the elements and appending a number of file name extensions from the
list @code{%load-extensions} (@pxref{Loading}). The resulting file
name is then searched in all directories in the variable
@code{%load-path} (@pxref{Install Config}). For example, the
@code{(ice-9 popen)} module would result in the filename
@code{ice-9/popen.scm} and searched in the installation directories of
Guile and in all other directories in the load path.
To use a module, it must be found and loaded. All Guile modules have a
unique @dfn{module name}, which is a list of one or more symbols.
Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile
searches for the code of a module, it constructs the name of the file to
load by concatenating the name elements with slashes between the
elements and appending a number of file name extensions from the list
@code{%load-extensions} (@pxref{Loading}). The resulting file name is
then searched in all directories in the variable @code{%load-path}
(@pxref{Build Config}). For example, the @code{(ice-9 popen)} module
would result in the filename @code{ice-9/popen.scm} and searched in the
installation directories of Guile and in all other directories in the
load path.
@c FIXME::martin: Not sure about this, maybe someone knows better?
Every module has a so-called syntax transformer associated with it.
@ -200,11 +200,11 @@ address these eventually.
To use a Guile module is to access either its public interface or a
custom interface (@pxref{General Information about Modules}). Both
types of access are handled by the syntactic form @code{use-modules},
which accepts one or more interface specifications and, upon
evaluation, arranges for those interfaces to be available to the
current module. This process may include locating and loading code
for a given module if that code has not yet been loaded, following
%load-path (@pxref{Install Config}).
which accepts one or more interface specifications and, upon evaluation,
arranges for those interfaces to be available to the current module.
This process may include locating and loading code for a given module if
that code has not yet been loaded, following %load-path (@pxref{Build
Config}).
An @dfn{interface specification} has one of two forms. The first
variation is simply to name the module, in which case its public

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

@ -1,371 +1,42 @@
@page
@node Options and Config
@chapter Runtime Options and Configuration
@chapter Configuration, Features and Runtime Options
Guile's behaviour can be modified by setting options. For example, is
the language that Guile accepts case sensitive, or should the debugger
automatically show a backtrace on error?
Why is my Guile different from your Guile? There are three kinds of
possible variation:
Guile has two levels of interface for managing options: a low-level
control interface, and a user-level interface which allows the enabling
or disabling of options.
@itemize @bullet
@item
build differences --- different versions of the Guile source code,
installation directories, configuration flags that control pieces of
functionality being included or left out, etc.
Moreover, the options are classified in groups according to whether they
configure @emph{reading}, @emph{printing}, @emph{debugging} or
@emph{evaluating}.
@item
differences in dynamically loaded code --- behaviour and features
provided by modules that can be dynamically loaded into a running Guile
@item
different runtime options --- some of the options that are provided for
controlling Guile's behaviour may be set differently.
@end itemize
Guile provides ``introspective'' variables and procedures to query all
of these possible variations at runtime. For runtime options, it also
provides procedures to change the settings of options and to obtain
documentation on what the options mean.
@menu
* General option interface::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Evaluator trap options::
* Examples of option use::
* Install Config:: Installation and configuration data.
* Build Config:: Build and installation configuration.
* Feature Tracking:: Available features in the Guile process.
* Runtime Options:: Controlling Guile's runtime behaviour.
@end menu
@node General option interface
@section General option interface
We will use the expression @code{<group>} to represent @code{read},
@code{print}, @code{debug} or @code{evaluator}.
@node Build Config
@section Configuration, Build and Installation
@subheading Low level
@c NJFIXME
@deffn {Scheme Procedure} <group>-options-interface
@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
@deffnx {Scheme Procedure} print-options-interface [SOME-INT]
@deffnx {Scheme Procedure} evaluator-traps-interface [SOME-INT]
@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
[FIXME: I have just taken the comments for C routine scm_options that
implements all of these. It needs to be presented better.]
If scm_options is called without arguments, the current option setting
is returned. If the argument is an option setting, options are altered
and the old setting is returned. If the argument isn't a list, a list
of sublists is returned, where each sublist contains option name, value
and documentation string.
@end deffn
@subheading User level
@c @deftp {Data type} scm_option
@c @code{scm_option} is used to represent run time options. It can be a
@c @emph{boolean} type, in which case the option will be set by the strings
@c @code{"yes"} and @code{"no"}. It can be a
@c @end deftp
@c NJFIXME
@deffn {Scheme Procedure} <group>-options [arg]
@deffnx {Scheme Procedure} read-options [arg]
@deffnx {Scheme Procedure} print-options [arg]
@deffnx {Scheme Procedure} debug-options [arg]
@deffnx {Scheme Procedure} traps [arg]
These functions list the options in their group. The optional argument
@var{arg} is a symbol which modifies the form in which the options are
presented.
With no arguments, @code{<group>-options} returns the values of the
options in that particular group. If @var{arg} is @code{'help}, a
description of each option is given. If @var{arg} is @code{'full},
programmers' options are also shown.
@var{arg} can also be a list representing the state of all options. In
this case, the list contains single symbols (for enabled boolean
options) and symbols followed by values.
@end deffn
[FIXME: I don't think 'full is ever any different from 'help. What's
up?]
@c NJFIXME
@deffn {Scheme Procedure} <group>-enable option-symbol
@deffnx {Scheme Procedure} read-enable option-symbol
@deffnx {Scheme Procedure} print-enable option-symbol
@deffnx {Scheme Procedure} debug-enable option-symbol
@deffnx {Scheme Procedure} trap-enable option-symbol
These functions set the specified @var{option-symbol} in their options
group. They only work if the option is boolean, and throw an error
otherwise.
@end deffn
@c NJFIXME
@deffn {Scheme Procedure} <group>-disable option-symbol
@deffnx {Scheme Procedure} read-disable option-symbol
@deffnx {Scheme Procedure} print-disable option-symbol
@deffnx {Scheme Procedure} debug-disable option-symbol
@deffnx {Scheme Procedure} trap-disable option-symbol
These functions turn off the specified @var{option-symbol} in their
options group. They only work if the option is boolean, and throw an
error otherwise.
@end deffn
@c NJFIXME
@deffn syntax <group>-set! option-symbol value
@deffnx syntax read-set! option-symbol value
@deffnx syntax print-set! option-symbol value
@deffnx syntax debug-set! option-symbol value
@deffnx syntax trap-set! option-symbol value
These functions set a non-boolean @var{option-symbol} to the specified
@var{value}.
@end deffn
@node Reader options
@section Reader options
@cindex options - read
@cindex read options
Here is the list of reader options generated by typing
@code{(read-options 'full)} in Guile. You can also see the default
values.
@smalllisp
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
@end smalllisp
Notice that while Standard Scheme is case insensitive, to ease
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
Guile is case-sensitive by default.
To make Guile case insensitive, you can type
@smalllisp
(read-enable 'case-insensitive)
@end smalllisp
@node Printing options
@section Printing options
Here is the list of print options generated by typing
@code{(print-options 'full)} in Guile. You can also see the default
values.
@smallexample
source no Print closures with source.
closure-hook #f Hook for printing closures.
@end smallexample
@node Evaluator options
@section Evaluator options
These are the evaluator options with their default values, as they are
printed by typing @code{(eval-options 'full)} in Guile.
@smallexample
stack 22000 Size of thread stacks (in machine words).
@end smallexample
@node Evaluator trap options
@section Evaluator trap options
[FIXME: These flags, together with their corresponding handlers, are not
user level options. Probably this entire section should be moved to the
documentation about the low-level programmer debugging interface.]
Here is the list of evaluator trap options generated by typing
@code{(traps 'full)} in Guile. You can also see the default values.
@smallexample
exit-frame no Trap when exiting eval or apply.
apply-frame no Trap when entering apply.
enter-frame no Trap when eval enters new frame.
traps yes Enable evaluator traps.
@end smallexample
@deffn apply-frame-handler key cont tailp
Called when a procedure is being applied.
Called if:
@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{apply-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize
If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.
@var{tailp} is true if this is a tail call
@end deffn
@deffn exit-frame-handler key cont retval
Called when a value is returned from a procedure.
Called if:
@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{exit-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize
If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.
@var{retval} is the return value.
@end deffn
@node Debugger options
@section Debugger options
Here is the list of print options generated by typing
@code{(debug-options 'full)} in Guile. You can also see the default
values.
@smallexample
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
@end smallexample
@subsection Stack overflow
@cindex overflow, stack
@cindex stack overflow
Stack overflow errors are caused by a computation trying to use more
stack space than has been enabled by the @code{stack} option. They are
reported like this:
@lisp
(non-tail-recursive-factorial 500)
@print{}
ERROR: Stack overflow
ABORT: (stack-overflow)
@end lisp
If you get an error like this, you can either try rewriting your code to
use less stack space, or increase the maximum stack size. To increase
the maximum stack size, use @code{debug-set!}, for example:
@lisp
(debug-set! stack 200000)
@result{}
(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
(non-tail-recursive-factorial 500)
@result{}
122013682599111006870123878542304692625357434@dots{}
@end lisp
If you prefer to try rewriting your code, you may be able to save stack
space by making some of your procedures @dfn{tail recursive}. For a
description of what this means, see @ref{Proper tail
recursion,,,r5rs,The Revised^5 Report on Scheme}.
@node Examples of option use
@section Examples of option use
Here is an example of a session in which some read and debug option
handling procedures are used. In this example, the user
@enumerate
@item
Notices that the symbols @code{abc} and @code{aBc} are not the same
@item
Examines the @code{read-options}, and sees that @code{case-insensitive}
is set to ``no''.
@item
Enables @code{case-insensitive}
@item
Verifies that now @code{aBc} and @code{abc} are the same
@item
Disables @code{case-insensitive} and enables debugging @code{backtrace}
@item
Reproduces the error of displaying @code{aBc} with backtracing enabled
[FIXME: this last example is lame because there is no depth in the
backtrace. Need to give a better example, possibly putting debugging
option examples in a separate session.]
@end enumerate
@smalllisp
guile> (define abc "hello")
guile> abc
"hello"
guile> aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
Type "(backtrace)" to get more information.
guile> (read-options 'help)
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
guile> (debug-options 'help)
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
guile> (read-enable 'case-insensitive)
(keywords #f case-insensitive positions)
guile> aBc
"hello"
guile> (read-disable 'case-insensitive)
(keywords #f positions)
guile> (debug-enable 'backtrace)
(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
guile> aBc
Backtrace:
0* aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
guile>
@end smalllisp
@node Install Config
@section Installation and Configuration Data
It is often useful to have site-specific information about the current
Guile installation. This chapter describes how to find out about
Guile's configuration at run time.
The following procedures and variables provide information about how
Guile was configured, built and installed on your system.
@deffn {Scheme Procedure} version
@deffnx {Scheme Procedure} major-version
@ -386,33 +57,39 @@ or micro version number, respectively.
@end lisp
@end deffn
@c NJFIXME not in libguile!
@deffn {Scheme Procedure} libguile-config-stamp
Return a string describing the date on which @code{libguile} was
configured. This is used to determine whether the Guile core
interpreter and the ice-9 runtime have grown out of date with one
another.
@end deffn
@deffn {Scheme Procedure} %package-data-dir
@deffnx {C Function} scm_sys_package_data_dir ()
Return the name of the directory where Scheme packages, modules and
libraries are kept. On most Unix systems, this will be
@samp{/usr/local/share/guile}.
Return the name of the directory under which Guile Scheme files in
general are stored. On Unix-like systems, this is usually
@file{/usr/local/share/guile} or @file{/usr/share/guile}.
@end deffn
@deffn {Scheme Procedure} %library-dir
@deffnx {C Function} scm_sys_library_dir ()
Return the directory where the Guile Scheme library files are installed.
E.g., may return "/usr/share/guile/1.3.5".
Return the name of the directory where the Guile Scheme files that
belong to the core Guile installation (as opposed to files from a 3rd
party package) are installed. On Unix-like systems, this is usually
@file{/usr/local/share/guile/<VERSION>} or
@file{/usr/share/guile/<VERSION>}, for example:
@file{/usr/local/share/guile/1.6.0}.
@end deffn
@deffn {Scheme Procedure} %site-dir
@deffnx {C Function} scm_sys_site_dir ()
Return the directory where the Guile site files are installed.
E.g., may return "/usr/share/guile/site".
Return the name of the directory where Guile Scheme files specific to
your site should be installed. On Unix-like systems, this is usually
@file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
@end deffn
@cindex GUILE_LOAD_PATH
@defvar %load-path
List of directories which should be searched for Scheme modules and
libraries. @code{%load-path} is initialized when Guile starts up to
@code{(list (%site-dir) (%library-dir) (%package-data-dir) ".")},
prepended with the contents of the GUILE_LOAD_PATH environment variable,
if it is set.
@end defvar
@deffn {Scheme Procedure} parse-path path [tail]
@deffnx {C Function} scm_parse_path (path, tail)
Parse @var{path}, which is expected to be a colon-separated
@ -432,34 +109,30 @@ directory in @var{path}, we search for @var{filename}
concatenated with each @var{extension}.
@end deffn
@defvar %load-path
List of directories which should be searched for Scheme
modules and libraries.
@end defvar
@defvar %guile-build-info
Alist of information collected during the building of a particular
@code{guile} program. Entries can be grouped into one of several
categories: directories, env vars, and versioning info.
Guile. Entries can be grouped into one of several categories:
directories, env vars, and versioning info.
Briefly, here are the keys in @code{%guile-build-info}, by group:
@itemize @bullet
@item directories
@table @asis
@item directories
srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
@item env vars
@item env vars
LIBS
@item versioning info
@item versioning info
guileversion, libguileinterface, buildstamp
@end itemize
@end table
Values are all strings. The value for @code{LIBS} is typically found also as
a part of "guile-config link" output. The value for @code{guileversion} has
form X.Y.Z, and should be the same as returned by @code{version}. The value
for @code{libguileinterface} is libtool compatible and has form
CURRENT:REVISION:AGE. The value for @code{buildstamp} is the output of the
date(1) command.
Values are all strings. The value for @code{LIBS} is typically found
also as a part of "guile-config link" output. The value for
@code{guileversion} has form X.Y.Z, and should be the same as returned
by @code{(version)}. The value for @code{libguileinterface} is libtool
compatible and has form CURRENT:REVISION:AGE. The value for
@code{buildstamp} is the output of the date(1) command.
In the source, @code{%guile-build-info} is initialized from
libguile/libpath.h, which is completely generated, so deleting this file
@ -646,6 +319,377 @@ is probably safer to do so directly using the @code{defined?} procedure
than to test for the corresponding feature using @code{feature?}.
@node Runtime Options
@section Runtime Options
Guile's runtime behaviour can be modified by setting options. For
example, is the language that Guile accepts case sensitive, or should
the debugger automatically show a backtrace on error?
Guile has two levels of interface for managing options: a low-level
control interface, and a user-level interface which allows the enabling
or disabling of options.
Moreover, the options are classified in groups according to whether they
configure @emph{reading}, @emph{printing}, @emph{debugging} or
@emph{evaluating}.
@menu
* Low level options interfaces::
* User level options interfaces::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Evaluator trap options::
* Examples of option use::
@end menu
@node Low level options interfaces
@subsection Low Level Options Interfaces
@deffn {Scheme Procedure} read-options-interface [setting]
@deffnx {Scheme Procedure} eval-options-interface [setting]
@deffnx {Scheme Procedure} print-options-interface [setting]
@deffnx {Scheme Procedure} debug-options-interface [setting]
@deffnx {Scheme Procedure} evaluator-traps-interface [setting]
@deffnx {C Function} scm_read_options (setting)
@deffnx {C Function} scm_eval_options_interface (setting)
@deffnx {C Function} scm_print_options (setting)
@deffnx {C Function} scm_debug_options (setting)
@deffnx {C Function} scm_evaluator_traps (setting)
If one of these procedures is called with no arguments (or with
@code{setting == SCM_UNDEFINED} in C code), it returns a list describing
the current setting of the read, eval, print, debug or evaluator traps
options respectively. The setting of a boolean option is indicated
simply by the presence or absence of the option symbol in the list. The
setting of a non-boolean option is indicated by the presence of the
option symbol immediately followed by the option's current value.
If called with a list argument, these procedures interpret the list as
an option setting and modify the relevant options accordingly. [FIXME
--- this glosses over a lot of details!]
If called with any other argument, such as @code{'help}, these
procedures return a list of entries like @code{(@var{OPTION-SYMBOL}
@var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the
default value and documentation for each option symbol in the relevant
set of options.
@end deffn
@node User level options interfaces
@subsection User Level Options Interfaces
@c @deftp {Data type} scm_option
@c @code{scm_option} is used to represent run time options. It can be a
@c @emph{boolean} type, in which case the option will be set by the strings
@c @code{"yes"} and @code{"no"}. It can be a
@c @end deftp
@c NJFIXME
@deffn {Scheme Procedure} <group>-options [arg]
@deffnx {Scheme Procedure} read-options [arg]
@deffnx {Scheme Procedure} print-options [arg]
@deffnx {Scheme Procedure} debug-options [arg]
@deffnx {Scheme Procedure} traps [arg]
These functions list the options in their group. The optional argument
@var{arg} is a symbol which modifies the form in which the options are
presented.
With no arguments, @code{<group>-options} returns the values of the
options in that particular group. If @var{arg} is @code{'help}, a
description of each option is given. If @var{arg} is @code{'full},
programmers' options are also shown.
@var{arg} can also be a list representing the state of all options. In
this case, the list contains single symbols (for enabled boolean
options) and symbols followed by values.
@end deffn
[FIXME: I don't think 'full is ever any different from 'help. What's
up?]
@c NJFIXME
@deffn {Scheme Procedure} <group>-enable option-symbol
@deffnx {Scheme Procedure} read-enable option-symbol
@deffnx {Scheme Procedure} print-enable option-symbol
@deffnx {Scheme Procedure} debug-enable option-symbol
@deffnx {Scheme Procedure} trap-enable option-symbol
These functions set the specified @var{option-symbol} in their options
group. They only work if the option is boolean, and throw an error
otherwise.
@end deffn
@c NJFIXME
@deffn {Scheme Procedure} <group>-disable option-symbol
@deffnx {Scheme Procedure} read-disable option-symbol
@deffnx {Scheme Procedure} print-disable option-symbol
@deffnx {Scheme Procedure} debug-disable option-symbol
@deffnx {Scheme Procedure} trap-disable option-symbol
These functions turn off the specified @var{option-symbol} in their
options group. They only work if the option is boolean, and throw an
error otherwise.
@end deffn
@c NJFIXME
@deffn syntax <group>-set! option-symbol value
@deffnx syntax read-set! option-symbol value
@deffnx syntax print-set! option-symbol value
@deffnx syntax debug-set! option-symbol value
@deffnx syntax trap-set! option-symbol value
These functions set a non-boolean @var{option-symbol} to the specified
@var{value}.
@end deffn
@node Reader options
@subsection Reader options
@cindex options - read
@cindex read options
Here is the list of reader options generated by typing
@code{(read-options 'full)} in Guile. You can also see the default
values.
@smalllisp
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
@end smalllisp
Notice that while Standard Scheme is case insensitive, to ease
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
Guile is case-sensitive by default.
To make Guile case insensitive, you can type
@smalllisp
(read-enable 'case-insensitive)
@end smalllisp
@node Printing options
@subsection Printing options
Here is the list of print options generated by typing
@code{(print-options 'full)} in Guile. You can also see the default
values.
@smallexample
source no Print closures with source.
closure-hook #f Hook for printing closures.
@end smallexample
@node Evaluator options
@subsection Evaluator options
These are the evaluator options with their default values, as they are
printed by typing @code{(eval-options 'full)} in Guile.
@smallexample
stack 22000 Size of thread stacks (in machine words).
@end smallexample
@node Evaluator trap options
@subsection Evaluator trap options
[FIXME: These flags, together with their corresponding handlers, are not
user level options. Probably this entire section should be moved to the
documentation about the low-level programmer debugging interface.]
Here is the list of evaluator trap options generated by typing
@code{(traps 'full)} in Guile. You can also see the default values.
@smallexample
exit-frame no Trap when exiting eval or apply.
apply-frame no Trap when entering apply.
enter-frame no Trap when eval enters new frame.
traps yes Enable evaluator traps.
@end smallexample
@deffn apply-frame-handler key cont tailp
Called when a procedure is being applied.
Called if:
@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{apply-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize
If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.
@var{tailp} is true if this is a tail call
@end deffn
@deffn exit-frame-handler key cont retval
Called when a value is returned from a procedure.
Called if:
@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{exit-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize
If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.
@var{retval} is the return value.
@end deffn
@node Debugger options
@subsection Debugger options
Here is the list of print options generated by typing
@code{(debug-options 'full)} in Guile. You can also see the default
values.
@smallexample
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
@end smallexample
@subsubsection Stack overflow
@cindex overflow, stack
@cindex stack overflow
Stack overflow errors are caused by a computation trying to use more
stack space than has been enabled by the @code{stack} option. They are
reported like this:
@lisp
(non-tail-recursive-factorial 500)
@print{}
ERROR: Stack overflow
ABORT: (stack-overflow)
@end lisp
If you get an error like this, you can either try rewriting your code to
use less stack space, or increase the maximum stack size. To increase
the maximum stack size, use @code{debug-set!}, for example:
@lisp
(debug-set! stack 200000)
@result{}
(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
(non-tail-recursive-factorial 500)
@result{}
122013682599111006870123878542304692625357434@dots{}
@end lisp
If you prefer to try rewriting your code, you may be able to save stack
space by making some of your procedures @dfn{tail recursive}. For a
description of what this means, see @ref{Proper tail
recursion,,,r5rs,The Revised^5 Report on Scheme}.
@node Examples of option use
@subsection Examples of option use
Here is an example of a session in which some read and debug option
handling procedures are used. In this example, the user
@enumerate
@item
Notices that the symbols @code{abc} and @code{aBc} are not the same
@item
Examines the @code{read-options}, and sees that @code{case-insensitive}
is set to ``no''.
@item
Enables @code{case-insensitive}
@item
Verifies that now @code{aBc} and @code{abc} are the same
@item
Disables @code{case-insensitive} and enables debugging @code{backtrace}
@item
Reproduces the error of displaying @code{aBc} with backtracing enabled
[FIXME: this last example is lame because there is no depth in the
backtrace. Need to give a better example, possibly putting debugging
option examples in a separate session.]
@end enumerate
@smalllisp
guile> (define abc "hello")
guile> abc
"hello"
guile> aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
Type "(backtrace)" to get more information.
guile> (read-options 'help)
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
guile> (debug-options 'help)
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
guile> (read-enable 'case-insensitive)
(keywords #f case-insensitive positions)
guile> aBc
"hello"
guile> (read-disable 'case-insensitive)
(keywords #f positions)
guile> (debug-enable 'backtrace)
(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
guile> aBc
Backtrace:
0* aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
guile>
@end smalllisp
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

4
doc/ref/slib.texi
View file

@ -2,8 +2,8 @@
@node SLIB
@chapter SLIB
Before the the SLIB facilities can be used, the following Scheme
expression must be executed:
Before the SLIB facilities can be used, the following Scheme expression
must be executed:
@smalllisp
(use-modules (ice-9 slib))