summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/ChangeLog33
-rw-r--r--doc/ref/guile.texi4
-rw-r--r--doc/ref/repl-modules.texi2
-rwxr-xr-xdoc/ref/scheme-data.texi126
-rw-r--r--doc/ref/scheme-debug.texi70
-rw-r--r--doc/ref/scheme-evaluation.texi8
-rw-r--r--doc/ref/scheme-modules.texi34
-rw-r--r--doc/ref/scheme-options.texi688
-rw-r--r--doc/ref/slib.texi4
9 files changed, 605 insertions, 364 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index b541a74d6..bbd18a228 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -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.
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index c819fb53d..22b308757 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -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.
diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi
index b136bd865..ea57e365b 100644
--- a/doc/ref/repl-modules.texi
+++ b/doc/ref/repl-modules.texi
@@ -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
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
index b34a969a1..e557ecd6b 100755
--- a/doc/ref/scheme-data.texi
+++ b/doc/ref/scheme-data.texi
@@ -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)
diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi
index 670bd0884..66526557f 100644
--- a/doc/ref/scheme-debug.texi
+++ b/doc/ref/scheme-debug.texi
@@ -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
diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi
index 6357c78cf..bb0f4b2e6 100644
--- a/doc/ref/scheme-evaluation.texi
+++ b/doc/ref/scheme-evaluation.texi
@@ -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
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi
index 460891060..5ff76c9b5 100644
--- a/doc/ref/scheme-modules.texi
+++ b/doc/ref/scheme-modules.texi
@@ -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
diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi
index 63b7a2c57..0492ce9ed 100644
--- a/doc/ref/scheme-options.texi
+++ b/doc/ref/scheme-options.texi
@@ -1,10 +1,330 @@
@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:
+
+@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.
+
+@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
+* Build Config:: Build and installation configuration.
+* Feature Tracking:: Available features in the Guile process.
+* Runtime Options:: Controlling Guile's runtime behaviour.
+@end menu
+
+
+@node Build Config
+@section Configuration, Build and Installation
+
+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
+@deffnx {Scheme Procedure} minor-version
+@deffnx {Scheme Procedure} micro-version
+@deffnx {C Function} scm_version ()
+@deffnx {C Function} scm_major_version ()
+@deffnx {C Function} scm_minor_version ()
+@deffnx {C Function} scm_micro_version ()
+Return a string describing Guile's version number, or its major, minor
+or micro version number, respectively.
+
+@lisp
+(version) @result{} "1.6.0"
+(major-version) @result{} "1"
+(minor-version) @result{} "6"
+(micro-version) @result{} "0"
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} %package-data-dir
+@deffnx {C Function} scm_sys_package_data_dir ()
+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 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 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
+string, into a list and return the resulting list with
+@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
+is returned.
+@end deffn
+
+@deffn {Scheme Procedure} search-path path filename [extensions]
+@deffnx {C Function} scm_search_path (path, filename, extensions)
+Search @var{path} for a directory containing a file named
+@var{filename}. The file must be readable, and not a directory.
+If we find one, return its full filename; otherwise, return
+@code{#f}. If @var{filename} is absolute, return it unchanged.
+If given, @var{extensions} is a list of strings; for each
+directory in @var{path}, we search for @var{filename}
+concatenated with each @var{extension}.
+@end deffn
+
+@defvar %guile-build-info
+Alist of information collected during the building of a particular
+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:
+
+@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
+LIBS
+@item versioning info
+guileversion, libguileinterface, buildstamp
+@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.
+
+In the source, @code{%guile-build-info} is initialized from
+libguile/libpath.h, which is completely generated, so deleting this file
+before a build guarantees up-to-date values for that build.
+@end defvar
+
+
+@node Feature Tracking
+@section Feature Tracking
+
+Guile has a Scheme level variable @code{*features*} that keeps track to
+some extent of the features that are available in a running Guile.
+@code{*features*} is a list of symbols, for example @code{threads}, each
+of which describes a feature of the running Guile process.
+
+@defvar *features*
+A list of symbols describing available features of the Guile process.
+@end defvar
+
+You shouldn't modify the @code{*features*} variable directly using
+@code{set!}. Instead, see the procedures that are provided for this
+purpose in the following subsection.
+
+@menu
+* Feature Manipulation:: Checking for and advertising features.
+* Common Feature Symbols:: Commonly available features.
+@end menu
+
+
+@node Feature Manipulation
+@subsection Feature Manipulation
+
+To check whether a particular feature is available, use the
+@code{provided?} procedure:
+
+@deffn {Scheme Procedure} provided? feature
+@deffnx {Deprecated Scheme Procedure} feature? feature
+Return @code{#t} if the specified @var{feature} is available, otherwise
+@code{#f}.
+@end deffn
+
+To advertise a feature from your own Scheme code, you can use the
+@code{provide} procedure:
+
+@deffn {Scheme Procedure} provide feature
+Add @var{feature} to the list of available features in this Guile
+process.
+@end deffn
+
+For C code, the equivalent function takes its feature name as a
+@code{char *} argument for convenience:
+
+@deftypefn {C Function} void scm_add_feature (const char *str)
+Add a symbol with name @var{str} to the list of available features in
+this Guile process.
+@end deftypefn
+
+
+@node Common Feature Symbols
+@subsection Common Feature Symbols
+
+In general, a particular feature may be available for one of two
+reasons. Either because the Guile library was configured and compiled
+with that feature enabled --- i.e. the feature is built into the library
+on your system. Or because some C or Scheme code that was dynamically
+loaded by Guile has added that feature to the list.
+
+In the first category, here are the features that the current version of
+Guile may define (depending on how it is built), and what they mean.
+
+@table @code
+@item array
+Indicates support for arrays (@pxref{Arrays}).
+
+@item array-for-each
+Indicates availability of @code{array-for-each} and other array mapping
+procedures (@pxref{Array Mapping}).
+
+@item char-ready?
+Indicates that the @code{char-ready?} function is available
+(@pxref{Reading}).
+
+@item complex
+Indicates support for complex numbers.
+
+@item current-time
+Indicates availability of time-related functions: @code{times},
+@code{get-internal-run-time} and so on (@pxref{Time}).
+
+@item debug-extensions
+Indicates that the debugging evaluator is available, together with the
+options for controlling it.
+
+@item delay
+Indicates support for promises (@pxref{Delayed Evaluation}).
+
+@item EIDs
+Indicates that the @code{geteuid} and @code{getegid} really return
+effective user and group IDs (@pxref{Processes}).
+
+@item inexact
+Indicates support for inexact numbers.
+
+@item i/o-extensions
+Indicates availability of the following extended I/O procedures:
+@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
+@code{fileno}, @code{isatty?}, @code{fdopen},
+@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
+File Descriptors}).
+
+@item net-db
+Indicates availability of network database functions:
+@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
+@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
+@code{scm_setserv}, and their `byXXX' variants (@pxref{Network
+Databases}).
+
+@item posix
+Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
+@code{kill}, @code{execl} and so on (@pxref{POSIX}).
+
+@item random
+Indicates availability of random number generation functions:
+@code{random}, @code{copy-random-state}, @code{random-uniform} and so on
+(@pxref{Random}).
+
+@item reckless
+Indicates that Guile was built with important checks omitted --- you
+should never see this!
+
+@item regex
+Indicates support for POSIX regular expressions using
+@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
+Functions}).
+
+@item socket
+Indicates availability of socket-related functions: @code{socket},
+@code{bind}, @code{connect} and so on (@pxref{Network Sockets and
+Communication}).
+
+@item sort
+Indicates availability of sorting and merging functions
+(@pxref{Sorting}).
+
+@item system
+Indicates that the @code{system} function is available
+(@pxref{Processes}).
+
+@item threads
+Indicates support for multithreading (@pxref{Threads}).
+
+@item values
+Indicates support for multiple return values using @code{values} and
+@code{call-with-values} (@pxref{Multiple Values}).
+@end table
+
+Available features in the second category depend, by definition, on what
+additional code your Guile process has loaded in. The following table
+lists features that you might encounter for this reason.
+
+@table @code
+@item defmacro
+Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
+
+@item describe
+Indicates that the @code{(oop goops describe)} module has been loaded,
+which provides a procedure for describing the contents of GOOPS
+instances.
+
+@item readline
+Indicates that Guile has loaded in Readline support, for command line
+editing (@pxref{Readline Support}).
+
+@item record
+Indicates support for record definition using @code{make-record-type}
+and friends (@pxref{Records}).
+@end table
+
+Although these tables may seem exhaustive, it is probably unwise in
+practice to rely on them, as the correspondences between feature symbols
+and available procedures/behaviour are not strictly defined. If you are
+writing code that needs to check for the existence of some procedure, it
+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
@@ -15,43 +335,52 @@ configure @emph{reading}, @emph{printing}, @emph{debugging} or
@emph{evaluating}.
@menu
-* General option interface::
+* Low level options interfaces::
+* User level options interfaces::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Evaluator trap options::
* Examples of option use::
-* Install Config:: Installation and configuration data.
-* Feature Tracking:: Available features in the Guile process.
@end menu
-@node General option interface
-@section General option interface
-We will use the expression @code{<group>} to represent @code{read},
-@code{print}, @code{debug} or @code{evaluator}.
-
-@subheading Low level
-
-@c NJFIXME
-@deffn {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.
+@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
-@subheading User level
+@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
@@ -115,7 +444,7 @@ These functions set a non-boolean @var{option-symbol} to the specified
@node Reader options
-@section Reader options
+@subsection Reader options
@cindex options - read
@cindex read options
@@ -141,7 +470,7 @@ To make Guile case insensitive, you can type
@end smalllisp
@node Printing options
-@section 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
@@ -154,7 +483,7 @@ closure-hook #f Hook for printing closures.
@node Evaluator options
-@section 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.
@@ -163,8 +492,9 @@ printed by typing @code{(eval-options 'full)} in Guile.
stack 22000 Size of thread stacks (in machine words).
@end smallexample
+
@node Evaluator trap options
-@section Evaluator trap options
+@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.]
@@ -230,7 +560,7 @@ debug object, otherwise it is a restartable continuation.
@end deffn
@node Debugger options
-@section 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
@@ -251,7 +581,7 @@ breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
@end smallexample
-@subsection Stack overflow
+@subsubsection Stack overflow
@cindex overflow, stack
@cindex stack overflow
@@ -287,7 +617,7 @@ recursion,,,r5rs,The Revised^5 Report on Scheme}.
@node Examples of option use
-@section 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
@@ -360,292 +690,6 @@ guile>
@end smalllisp
-@node Install Config
-@section Installation and Configuration Data
-
-It is often useful to have site-specific information about the current
-Guile installation. This chapter describes how to find out about
-Guile's configuration at run time.
-
-@deffn {Scheme Procedure} version
-@deffnx {Scheme Procedure} major-version
-@deffnx {Scheme Procedure} minor-version
-@deffnx {Scheme Procedure} micro-version
-@deffnx {C Function} scm_version ()
-@deffnx {C Function} scm_major_version ()
-@deffnx {C Function} scm_minor_version ()
-@deffnx {C Function} scm_micro_version ()
-Return a string describing Guile's version number, or its major, minor
-or micro version number, respectively.
-
-@lisp
-(version) @result{} "1.6.0"
-(major-version) @result{} "1"
-(minor-version) @result{} "6"
-(micro-version) @result{} "0"
-@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}.
-@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".
-@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".
-@end deffn
-
-@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
-string, into a list and return the resulting list with
-@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
-is returned.
-@end deffn
-
-@deffn {Scheme Procedure} search-path path filename [extensions]
-@deffnx {C Function} scm_search_path (path, filename, extensions)
-Search @var{path} for a directory containing a file named
-@var{filename}. The file must be readable, and not a directory.
-If we find one, return its full filename; otherwise, return
-@code{#f}. If @var{filename} is absolute, return it unchanged.
-If given, @var{extensions} is a list of strings; for each
-directory in @var{path}, we search for @var{filename}
-concatenated with each @var{extension}.
-@end deffn
-
-@defvar %load-path
-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.
-
-Briefly, here are the keys in @code{%guile-build-info}, by group:
-@itemize @bullet
-@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
-LIBS
-@item versioning info
-guileversion, libguileinterface, buildstamp
-@end itemize
-
-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
-before a build guarantees up-to-date values for that build.
-@end defvar
-
-
-@node Feature Tracking
-@section Feature Tracking
-
-Guile has a Scheme level variable @code{*features*} that keeps track to
-some extent of the features that are available in a running Guile.
-@code{*features*} is a list of symbols, for example @code{threads}, each
-of which describes a feature of the running Guile process.
-
-@defvar *features*
-A list of symbols describing available features of the Guile process.
-@end defvar
-
-You shouldn't modify the @code{*features*} variable directly using
-@code{set!}. Instead, see the procedures that are provided for this
-purpose in the following subsection.
-
-@menu
-* Feature Manipulation:: Checking for and advertising features.
-* Common Feature Symbols:: Commonly available features.
-@end menu
-
-
-@node Feature Manipulation
-@subsection Feature Manipulation
-
-To check whether a particular feature is available, use the
-@code{provided?} procedure:
-
-@deffn {Scheme Procedure} provided? feature
-@deffnx {Deprecated Scheme Procedure} feature? feature
-Return @code{#t} if the specified @var{feature} is available, otherwise
-@code{#f}.
-@end deffn
-
-To advertise a feature from your own Scheme code, you can use the
-@code{provide} procedure:
-
-@deffn {Scheme Procedure} provide feature
-Add @var{feature} to the list of available features in this Guile
-process.
-@end deffn
-
-For C code, the equivalent function takes its feature name as a
-@code{char *} argument for convenience:
-
-@deftypefn {C Function} void scm_add_feature (const char *str)
-Add a symbol with name @var{str} to the list of available features in
-this Guile process.
-@end deftypefn
-
-
-@node Common Feature Symbols
-@subsection Common Feature Symbols
-
-In general, a particular feature may be available for one of two
-reasons. Either because the Guile library was configured and compiled
-with that feature enabled --- i.e. the feature is built into the library
-on your system. Or because some C or Scheme code that was dynamically
-loaded by Guile has added that feature to the list.
-
-In the first category, here are the features that the current version of
-Guile may define (depending on how it is built), and what they mean.
-
-@table @code
-@item array
-Indicates support for arrays (@pxref{Arrays}).
-
-@item array-for-each
-Indicates availability of @code{array-for-each} and other array mapping
-procedures (@pxref{Array Mapping}).
-
-@item char-ready?
-Indicates that the @code{char-ready?} function is available
-(@pxref{Reading}).
-
-@item complex
-Indicates support for complex numbers.
-
-@item current-time
-Indicates availability of time-related functions: @code{times},
-@code{get-internal-run-time} and so on (@pxref{Time}).
-
-@item debug-extensions
-Indicates that the debugging evaluator is available, together with the
-options for controlling it.
-
-@item delay
-Indicates support for promises (@pxref{Delayed Evaluation}).
-
-@item EIDs
-Indicates that the @code{geteuid} and @code{getegid} really return
-effective user and group IDs (@pxref{Processes}).
-
-@item inexact
-Indicates support for inexact numbers.
-
-@item i/o-extensions
-Indicates availability of the following extended I/O procedures:
-@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
-@code{fileno}, @code{isatty?}, @code{fdopen},
-@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
-File Descriptors}).
-
-@item net-db
-Indicates availability of network database functions:
-@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
-@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
-@code{scm_setserv}, and their `byXXX' variants (@pxref{Network
-Databases}).
-
-@item posix
-Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
-@code{kill}, @code{execl} and so on (@pxref{POSIX}).
-
-@item random
-Indicates availability of random number generation functions:
-@code{random}, @code{copy-random-state}, @code{random-uniform} and so on
-(@pxref{Random}).
-
-@item reckless
-Indicates that Guile was built with important checks omitted --- you
-should never see this!
-
-@item regex
-Indicates support for POSIX regular expressions using
-@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
-Functions}).
-
-@item socket
-Indicates availability of socket-related functions: @code{socket},
-@code{bind}, @code{connect} and so on (@pxref{Network Sockets and
-Communication}).
-
-@item sort
-Indicates availability of sorting and merging functions
-(@pxref{Sorting}).
-
-@item system
-Indicates that the @code{system} function is available
-(@pxref{Processes}).
-
-@item threads
-Indicates support for multithreading (@pxref{Threads}).
-
-@item values
-Indicates support for multiple return values using @code{values} and
-@code{call-with-values} (@pxref{Multiple Values}).
-@end table
-
-Available features in the second category depend, by definition, on what
-additional code your Guile process has loaded in. The following table
-lists features that you might encounter for this reason.
-
-@table @code
-@item defmacro
-Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
-
-@item describe
-Indicates that the @code{(oop goops describe)} module has been loaded,
-which provides a procedure for describing the contents of GOOPS
-instances.
-
-@item readline
-Indicates that Guile has loaded in Readline support, for command line
-editing (@pxref{Readline Support}).
-
-@item record
-Indicates support for record definition using @code{make-record-type}
-and friends (@pxref{Records}).
-@end table
-
-Although these tables may seem exhaustive, it is probably unwise in
-practice to rely on them, as the correspondences between feature symbols
-and available procedures/behaviour are not strictly defined. If you are
-writing code that needs to check for the existence of some procedure, it
-is probably safer to do so directly using the @code{defined?} procedure
-than to test for the corresponding feature using @code{feature?}.
-
-
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi
index 4d9e8c14c..a4eea1c19 100644
--- a/doc/ref/slib.texi
+++ b/doc/ref/slib.texi
@@ -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))