summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ChangeLog18
-rw-r--r--doc/Makefile.am3
-rw-r--r--doc/guile.texi7
-rw-r--r--doc/repl-modules.texi79
-rw-r--r--doc/srfi-13-14.texi1093
-rw-r--r--doc/srfi-modules.texi183
6 files changed, 288 insertions, 1095 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index b136680b9..d097ace4a 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,23 @@
2001-05-02 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
+ * srfi-13-14.texi: Added @bullet to various @itemize lists.
+
+ * srfi-modules.texi (SRFI Support): New file and chapter.
+
+ * Makefile.am (guile_TEXINFOS): Added repl-modules.texi and
+ srfi-modules.texi.
+
+ * guile.texi (Top): New menu entries for the new chapters.
+ (Top): @includes for the new chapters.
+ (Top): New menu entry for `SRFI Support', @include for
+ `srfi-modules.texi'.
+
+ * repl-modules.texi: New file.
+ (Readline Support): New chapter for (ice-9 readline).
+ (Value History): New chapter for (ice-9 history).
+
+2001-05-02 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
+
* scheme-modules.texi (Dynamic Libraries): Renamed from `Dynamic
Linking from Marius''.
(The Guile module system): Removed obsolete naming convention.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9975477f7..c51cf392f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -35,7 +35,8 @@ guile_TEXINFOS = preface.texi intro.texi scheme-intro.texi \
scheme-reading.texi scheme-indices.texi slib.texi posix.texi \
expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.texi \
appendices.texi indices.texi script-getopt.texi data-rep.texi \
- extend.texi srfi-13-14.texi AUTHORS
+ extend.texi srfi-13-14.texi repl-modules.texi srfi-modules.texi \
+ AUTHORS
guile_tut_TEXINFOS = guile-tut.texi AUTHORS
diff --git a/doc/guile.texi b/doc/guile.texi
index a163dfaad..6c8c57338 100644
--- a/doc/guile.texi
+++ b/doc/guile.texi
@@ -80,7 +80,7 @@ by the Free Software Foundation.
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.7 2001-04-28 23:38:52 ossau Exp $
+@subtitle $Id: guile.texi,v 1.8 2001-05-02 21:50:15 mgrabmue Exp $
@subtitle For use with Guile @value{VERSION}
@include AUTHORS
@@ -168,7 +168,10 @@ Part III: Guile Modules
* SLIB:: Using the SLIB Scheme library.
* POSIX:: POSIX system calls and networking.
+* SRFI Support:: Support for various SRFIs.
* SRFI-13/14:: String library and character set library.
+* Readline Support:: Module for using the readline library.
+* Value History:: Maintaining a value history in the REPL.
* Expect:: Controlling interactive programs with Guile.
* The Scheme shell (scsh)::
The SCSH compatibility module has been made an
@@ -249,7 +252,9 @@ Indices
@include slib.texi
@include posix.texi
+@include srfi-modules.texi
@include srfi-13-14.texi
+@include repl-modules.texi
@include expect.texi
@include scsh.texi
@include tcltk.texi
diff --git a/doc/repl-modules.texi b/doc/repl-modules.texi
new file mode 100644
index 000000000..3bf68ffc8
--- /dev/null
+++ b/doc/repl-modules.texi
@@ -0,0 +1,79 @@
+@node Readline Support
+@chapter Readline Support
+
+@c FIXME::martin: Review me!
+
+@cindex readline
+@cindex command line history
+Guile comes with an interface module to the readline library. This
+makes interactive use much more convenient, because of the command--line
+editing features of readline. Using @code{(ice-9 readline)}, you can
+navigate through the current input line with the cursor keys, retrieve
+older command lines from the input history and even search through the
+history entries.
+
+The module is not loaded by default and so has to be loaded and
+activated explicitly. This is done with two simple lines of code:
+
+@lisp
+(use-modules (ice-9 readline))
+(activate-readline)
+@end lisp
+
+The first line will load the necessary code, and the second will
+activate readline's features for the REPL. If you plan to use this
+module often, you should save these to lines to your @file{.guile}
+personal startup file.
+
+You will notice that the REPL's behaviour changes a bit when you have
+loaded the readline module. For examle, when you press Enter before
+typing in the closing parentheses of a list, you will see the
+@dfn{continuation} prompt, three dots: @code{...} This gives you a nice
+visual feedback when trying to match parentheses. To make this even
+easier, @dfn{bouncing parentheses} are implemented. That means that
+when you type in a closing parentheses, the cursor will jump to the
+corresponding opening paren for a short time, making it trivial to make
+them match.
+
+Once the readline module is activated, all lines entered interactively
+will be stored in a history and can be recalled later using the
+cursor-up and -down keys. Readline also understands the Emacs keys for
+navigating through the command line and history.
+
+When you quit your Guile session by evaluating @code{(quit)} or pressing
+Ctrl-D, the history will be saved to the file @file{.guile_history} and
+read in when you start Guile for the next time. Thus you can start a
+new Guile session and still have the (probably long--winded) definition
+expressions available.
+
+
+@node Value History
+@chapter Value History
+
+@c FIXME::martin: Review me!
+
+@cindex value history
+Another module which makes command line usage more convenient is
+@code{(ice-9 history)}. This module will change the REPL so that each
+value which is evaluated and printed will be remembered under a name
+constructed from the dollar character (@code{$}) and the number of the
+evaluated expression.
+
+Consider an example session.
+
+@example
+guile> (use-modules (ice-9 history))
+guile> 1
+$1 = 1
+guile> (+ $1 $1)
+$2 = 2
+guile> (* $2 $2)
+$3 = 4
+@end example
+
+After loading the value history module @code{(ice-9 history)}, one
+(trivial) expression is evaluated. The result is stored into the
+variable @code{$1}. This fact is indicated by the output @code{$1 = },
+which is also caused by @code{(ice-9 history)}. In the next line, this
+variable is used two times, to produce the value @code{$2}, which in
+turn is used in the calculation for @code{$3}.
diff --git a/doc/srfi-13-14.texi b/doc/srfi-13-14.texi
index 8d96b9618..e69de29bb 100644
--- a/doc/srfi-13-14.texi
+++ b/doc/srfi-13-14.texi
@@ -1,1093 +0,0 @@
-@node SRFI-13/14
-@chapter SRFI-13 and SRFI-14
-
-This chapter documents the SRFI-13/14 library, which provides the string
-utility procedures defined in SRFI-13 and the character-set procedures
-defined in SRFI-14 for Guile.
-
-@menu
-* Introduction:: What is this all about?
-* Loading SRFI-13/14:: Loading the module into a running Guile.
-* String Functions:: Available string processing procedures.
-* Character-set Procedures:: Procedures for manipulating character sets.
-@end menu
-
-
-@c ===================================================================
-
-@node Introduction
-@section Introduction
-
-The SRFI-13/14 library is a shared library which provides the procedures
-defined in SRFI-13 (string library) and the procedures defined in
-SRFI-14 (character-set library). You should also refer to the SRFI
-documents, which provide some details I will not document here.
-
-If you don't know what SRFI means, and what all the numbers are about,
-you may want to refer to the SRFI home page at
-@url{http://srfi.schemers.org}.
-
-Note that only the procedures from SRFI-13 are documented here which are
-not already contained in Guile. For procedures not documented here
-please refer to the relevant chapters in the Guile Reference Manual, for
-example the documentation of strings and string procedures (REFFIXME).
-
-The SRFI-14 procedures are documented completely.
-
-@menu
-* What can be done:: What is possible with SRFI-13/14
-* What cannot be done:: and what is not?
-@end menu
-
-
-@c ===================================================================
-
-@node What can be done
-@subsection What can be done
-
-All of the procedures defined in SRFI-13, which are not already included
-in the Guile core library, are implemented in the module @code{(srfi
-srfi-13)}. The procedures which are both in Guile and in SRFI-13, but
-which are slightly extended, have been implemented in this module, and
-the bindings overwrite those in the Guile core.
-
-All procedures from SRFI-14 (character-set library) are implemented in
-the module @code{(srfi srfi-14)}, as well as the standard variables
-@code{char-set:letter}, @code{char-set:digit} etc.
-
-
-@c ===================================================================
-
-@node What cannot be done
-@subsection What cannot be done
-
-The procedures which are defined in the section @emph{Low-level
-procedures} of SRFI-13 for parsing optional string indices, substring
-specification checking and Knuth-Morris-Pratt-Searching are not
-implemented.
-
-The procedures @code{string-contains} and @code{string-contains-ci} are
-not implemented very efficiently at the moment. This will be changed as
-soon as possible.
-
-
-@c ===================================================================
-
-@node Loading SRFI-13/14
-@section Loading SRFI-13/14
-
-When Guile is properly installed, it can be loaded into a running Guile
-by using the @code{(srfi srfi-13)} module.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-13))
-guile>
-@end example
-
-When this step causes any errors, Guile is not properly installed.
-
-One possible reason is that Guile cannot find either the Scheme module
-file @file{srfi-13.scm}, or it cannot find the shared object file
-@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the
-Guile load path and that the latter is either installed in some default
-location like @file{/usr/local/lib} or that the directory it was
-installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to
-@file{srfi-14.scm}.
-
-Now you can test whether the SRFI-13 procedures are working by calling
-the @code{string-concatenate} procedure.
-
-@example
-guile> (string-concatenate '("Hello" " " "World!"))
-"Hello World!"
-@end example
-
-The same goes for the SRFI-14 module, of course.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-14))
-guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar"))
-#<charset @{#\a #\b #\f #\o #\r@}>
-guile>
-@end example
-
-
-@c ===================================================================
-
-@node String Functions
-@section String Functions
-
-In this section, we will describe all procedures defined in SRFI-13
-(string library) and implemented by the module @code{(srfi srfi-13)}.
-
-Except for the procedures in the section @emph{Low-level procedures} of
-SRFI-13, all string procedures defined there are implemented completely.
-
-@menu
-* Predicates:: Testing strings.
-* SRFI-13 Constructors:: Constructing strings.
-* SRFI-13 List/String Conversion:: Converstion from/to character lists.
-* SRFI-13 Selection:: Selecting portions from strings.
-* SRFI-13 Modification:: Modifying string in--place.
-* SRFI-13 Comparison:: Comparing strings.
-* Prefixes/Suffixes:: Checking for common pre-/suffixes.
-* Searching:: Searching in strings.
-* Case Mapping:: Changing the case of strings.
-* Reverse/Append:: Append, concatenate and reverse strings.
-* Fold/Unfold/Map:: Fold/Unfold/Map over strings.
-* Replicate/Rotate:: String replication and rotation.
-* Miscellaneous:: Miscellaneous string procedures.
-* Filtering/Deleting:: Deleting characters from strings.
-@end menu
-
-
-@c ===================================================================
-
-@node Predicates
-@subsection Predicates
-
-In addition to the primitives @code{string?} and @code{string-null?},
-which are already in the Guile core, the string predicates
-@code{string-any} and @code{string-every} are defined by SRFI-13.
-
-@deffn primitive string-any pred s [start end]
-Check if the predicate @var{pred} is true for any character in
-the string @var{s}, proceeding from left (index @var{start}) to
-right (index @var{end}). If @code{string-any} returns true,
-the returned true value is the one produced by the first
-successful application of @var{pred}.
-@end deffn
-
-@deffn primitive string-every pred s [start end]
-Check if the predicate @var{pred} is true for every character
-in the string @var{s}, proceeding from left (index @var{start})
-to right (index @var{end}). If @code{string-every} returns
-true, the returned true value is the one produced by the final
-application of @var{pred} to the last character of @var{s}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Constructors
-@subsection Constructors
-
-SRFI-13 defines several procedures for constructing new strings. In
-addition to @code{make-string} and @code{string} (available in the Guile
-core library), the procedure @code{string-tabulate} does exist.
-
-@deffn primitive string-tabulate proc len
-@var{proc} is an integer->char procedure. Construct a string
-of size @var{len} by applying @var{proc} to each index to
-produce the corresponding string element. The order in which
-@var{proc} is applied to the indices is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 List/String Conversion
-@subsection List/String Conversion
-
-The procedure @code{string->list} is extended by SRFI-13, that is why it
-is included in @code{(srfi srfi-13)}. The other procedures are new.
-The Guile core already contains the procedure @code{list->string} for
-converting a list of characters into a string (REFFIXME).
-
-@deffn primitive string->list str [start end]
-Convert the string @var{str} into a list of characters.
-@end deffn
-
-@deffn primitive reverse-list->string chrs
-An efficient implementation of @code{(compose string->list
-reverse)}:
-
-@smalllisp
-(reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
-@end smalllisp
-@end deffn
-
-@deffn primitive string-join ls [delimiter grammar]
-Append the string in the string list @var{ls}, using the string
-@var{delim} as a delimiter between the elements of @var{ls}.
-@var{grammar} is a symbol which specifies how the delimiter is
-placed between the strings, and defaults to the symbol
-@code{infix}.
-
-@table @code
-@item infix
-Insert the separator between list elements. An empty string
-will produce an empty list.
-
-@item string-infix
-Like @code{infix}, but will raise an error if given the empty
-list.
-
-@item suffix
-Insert the separator after every list element.
-
-@item prefix
-Insert the separator before each list element.
-@end table
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Selection
-@subsection Selection
-
-These procedures are called @dfn{selectors}, because they access
-information about the string or select pieces of a given string.
-
-Additional selector procedures are documented in the Strings section
-(REFFIXME), like @code{string-length} or @code{string-ref}.
-
-@code{string-copy} is also available in core Guile, but this version
-accepts additional start/end indices.
-
-@deffn primitive string-copy str [start end]
-Return a freshly allocated copy of the string @var{str}. If
-given, @var{start} and @var{end} delimit the portion of
-@var{str} which is copied.
-@end deffn
-
-@deffn primitive substring/shared str start [end]
-Like @code{substring}, but the result may share memory with the
-argument @var{str}.
-@end deffn
-
-@deffn primitive string-copy! target tstart s [start end]
-Copy the sequence of characters from index range [@var{start},
-@var{end}) in string @var{s} to string @var{target}, beginning
-at index @var{tstart}. The characters are copied left-to-right
-or right-to-left as needed -- the copy is guaranteed to work,
-even if @var{target} and @var{s} are the same string. It is an
-error if the copy operation runs off the end of the target
-string.
-@end deffn
-
-@deffn primitive string-take s n
-@deffnx primitive string-take-right s n
-Return the @var{n} first/last characters of @var{s}.
-@end deffn
-
-@deffn primitive string-drop s n
-@deffnx primitive string-drop-right s n
-Return all but the first/last @var{n} characters of @var{s}.
-@end deffn
-
-@deffn primitive string-pad s len [chr start end]
-@deffnx primitive string-pad-right s len [chr start end]
-Take that characters from @var{start} to @var{end} from the
-string @var{s} and return a new string, right(left)-padded by the
-character @var{chr} to length @var{len}. If the resulting
-string is longer than @var{len}, it is truncated on the right (left).
-@end deffn
-
-@deffn primitive string-trim s [char_pred start end]
-@deffnx primitive string-trim-right s [char_pred start end]
-@deffnx primitive string-trim-both s [char_pred start end]
-Trim @var{s} by skipping over all characters on the left/right/both
-sides of the string that satisfy the parameter @var{char_pred}:
-
-@itemize @bullet
-@item
-if it is the character @var{ch}, characters equal to
-@var{ch} are trimmed,
-
-@item
-if it is a procedure @var{pred} characters that
-satisfy @var{pred} are trimmed,
-
-@item
-if it is a character set, characters in that set are trimmed.
-@end itemize
-
-If called without a @var{char_pred} argument, all whitespace is
-trimmed.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Modification
-@subsection Modification
-
-The procedure @code{string-fill!} is extended from R5RS because it
-accepts optional start/end indices. This bindings shadows the procedure
-of the same name in the Guile core. The second modification procedure
-@code{string-set!} is documented in the Strings section (REFFIXME).
-
-@deffn primitive string-fill! str chr [start end]
-Stores @var{chr} in every element of the given @var{str} and
-returns an unspecified value.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Comparison
-@subsection Comparison
-
-The procedures in this section are used for comparing strings in
-different ways. The comparison predicates differ from those in R5RS in
-that they do not only return @code{#t} or @code{#f}, but the mismatch
-index in the case of a true return value.
-
-@code{string-hash} and @code{string-hash-ci} are for calculating hash
-values for strings, useful for implementing fast lookup mechanisms.
-
-@deffn primitive string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-@deffnx primitive string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
-mismatch index, depending upon whether @var{s1} is less than,
-equal to, or greater than @var{s2}. The mismatch index is the
-largest index @var{i} such that for every 0 <= @var{j} <
-@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
-@var{i} is the first position that does not match. The
-character comparison is done case-insensitively.
-@end deffn
-
-@deffn primitive string= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string<> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string< s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string<= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}.
-@end deffn
-
-@deffn primitive string-ci= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci<> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci< s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci> s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci<= s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-ci>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}. These are the case-insensitive variants.
-@end deffn
-
-@deffn primitive string-hash s [bound start end]
-@deffnx primitive string-hash-ci s [bound start end]
-Return a hash value of the string @var{s} in the range 0 @dots{}
-@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node Prefixes/Suffixes
-@subsection Prefixes/Suffixes
-
-Using these procedures you can determine whether a given string is a
-prefix or suffix of another string or how long a common prefix/suffix
-is.
-
-@deffn primitive string-prefix-length s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-length s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
-Return the length of the longest common prefix/suffix of the two
-strings. @code{string-prefix-length-ci} and
-@code{string-suffix-length-ci} are the case-insensitive variants.
-@end deffn
-
-@deffn primitive string-prefix? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-prefix-ci? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix? s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-suffix-ci? s1 s2 [start1 end1 start2 end2]
-Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and
-@code{string-suffix-ci?} are the case-insensitive variants.
-@end deffn
-
-
-@c ===================================================================
-
-@node Searching
-@subsection Searching
-
-Use these procedures to find out whether a string contains a given
-character or a given substring, or a character from a set of characters.
-
-@deffn primitive string-index s char_pred [start end]
-@deffnx primitive string-index-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurence of a character which
-
-@itemize
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisifies the predicate @var{char_pred}, if it is a
-procedure,
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn primitive string-skip s char_pred [start end]
-@deffnx primitive string-skip-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurence of a character which
-
-@itemize
-@item
-does not equal @var{char_pred}, if it is character,
-
-@item
-does not satisify the predicate @var{char_pred}, if it is
-a procedure.
-
-@item
-is not in the set if @var{char_pred} is a character set.
-@end itemize
-@end deffn
-
-@deffn primitive string-count s char_pred [start end]
-Return the count of the number of characters in the string
-@var{s} which
-
-@itemize @bullet
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisifies the predicate @var{char_pred}, if it is a procedure.
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn primitive string-contains s1 s2 [start1 end1 start2 end2]
-@deffnx primitive string-contains-ci s1 s2 [start1 end1 start2 end2]
-Does string @var{s1} contain string @var{s2}? Return the index
-in @var{s1} where @var{s2} occurs as a substring, or false.
-The optional start/end indices restrict the operation to the
-indicated substrings.
-
-@code{string-contains-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node Case Mapping
-@subsection Alphabetic Case Mapping
-
-These procedures convert the alphabetic case of strings. They are
-similar to the procedures in the Guile core, but are extended to handle
-optional start/end indices.
-
-@deffn primitive string-upcase s [start end]
-@deffnx primitive string-upcase! s [start end]
-Upcase every character in @var{s}. @code{string-upcase!} is the
-side-effecting variant.
-@end deffn
-
-@deffn primitive string-downcase s [start end]
-@deffnx primitive string-downcase! s [start end]
-Downcase every character in @var{s}. @code{string-downcase!} is the
-side--effecting variant.
-@end deffn
-
-@deffn primitive string-titlecase s [start end]
-@deffnx primitive string-titlecase! s [start end]
-Upcase every first character in every word in @var{s}, downcase the
-other characters. @code{string-titlecase!} is the side--effecting
-variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node Reverse/Append
-@subsection Reverse/Append
-
-One appending procedure, @code{string-append} is the same in R5RS and in
-SRFI-13, so it is not redefined.
-
-@deffn primitive string-reverse str [start end]
-@deffnx primitive string-reverse! str [start end]
-Reverse the string @var{str}. The optional arguments
-@var{start} and @var{end} delimit the region of @var{str} to
-operate on.
-
-@code{string-reverse!} modifies the argument string and returns an
-unspecified value.
-@end deffn
-
-@deffn primitive string-append/shared ls @dots{}
-Like @code{string-append}, but the result may share memory
-with the argument strings.
-@end deffn
-
-@deffn primitive string-concatenate ls
-Append the elements of @var{ls} (which must be strings)
-together into a single string. Guaranteed to return a freshly
-allocated string.
-@end deffn
-
-@deffn primitive string-concatenate/shared ls
-Like @code{string-concatenate}, but the result may share memory
-with the strings in the list @var{ls}.
-@end deffn
-
-@deffn primitive string-concatenate-reverse ls final_string end
-Without optional arguments, this procedure is equivalent to
-
-@smalllisp
-(string-concatenate (reverse ls))
-@end smalllisp
-
-If the optional argument @var{final_string} is specified, it is
-consed onto the beginning to @var{ls} before performing the
-list-reverse and string-concatenate operations. If @var{end}
-is given, only the characters of @var{final_string} up to index
-@var{end} are used.
-
-Guaranteed to return a freshly allocated string.
-@end deffn
-
-@deffn primitive string-concatenate-reverse/shared ls final_string end
-Like @code{string-concatenate-reverse}, but the result may
-share memory with the the strings in the @var{ls} arguments.
-@end deffn
-
-
-@c ===================================================================
-
-@node Fold/Unfold/Map
-@subsection Fold/Unfold/Map
-
-@code{string-map}, @code{string-for-each} etc. are for iterating over
-the characters a string is composed of. The fold and unfold procedures
-are list iterators and constructors.
-
-@deffn primitive string-map proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified.
-@end deffn
-
-@deffn primitive string-map! proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified. The string @var{s} is
-modified in-place, the return value is not specified.
-@end deffn
-
-@deffn primitive string-fold kons knil s [start end]
-@deffnx primitive string-fold-right kons knil s [start end]
-Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
-terminating element, from left to right (or right to left, for
-@code{string-fold-right}). @var{kons} must expect two arguments: The
-actual character and the last result of @var{kons}' application.
-@end deffn
-
-@deffn primitive string-unfold p f g seed [base make_final]
-@deffnx primitive string-unfold-right p f g seed [base make_final]
-These are the fundamental string constructors.
-@itemize
-@item @var{g} is used to generate a series of @emph{seed}
-values from the initial @var{seed}: @var{seed}, (@var{g}
-@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
-@dots{}
-@item @var{p} tells us when to stop -- when it returns true
-when applied to one of these seed values.
-@item @var{f} maps each seed value to the corresponding
-character in the result string. These chars are assembled into the
-string in a left-to-right (right-to-left) order.
-@item @var{base} is the optional initial/leftmost (rightmost)
- portion of the constructed string; it default to the empty string.
-@item @var{make_final} is applied to the terminal seed
-value (on which @var{p} returns true) to produce the final/rightmost
-(leftmost) portion of the constructed string. It defaults to
-@code{(lambda (x) "")}.
-@end itemize
-@end deffn
-
-@deffn primitive string-for-each proc s [start end]
-@var{proc} is mapped over @var{s} in left-to-right order. The
-return value is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node Replicate/Rotate
-@subsection Replicate/Rotate
-
-These procedures are special substring procedures, which can also be
-used for replicating strings. They are a bit tricky to use, but
-consider this code fragment, which replicates the input string
-@code{"foo"} so often that the resulting string has a length of six.
-
-@lisp
-(xsubstring "foo" 0 6)
-@result{}
-"foofoo"
-@end lisp
-
-@deffn primitive xsubstring s from [to start end]
-This is the @emph{extended substring} procedure that implements
-replicated copying of a substring of some string.
-
-@var{s} is a string, @var{start} and @var{end} are optional
-arguments that demarcate a substring of @var{s}, defaulting to
-0 and the length of @var{s}. Replicate this substring up and
-down index space, in both the positive and negative directions.
-@code{xsubstring} returns the substring of this string
-beginning at index @var{from}, and ending at @var{to}, which
-defaults to @var{from} + (@var{end} - @var{start}).
-@end deffn
-
-@deffn primitive string-xcopy! target tstart s sfrom [sto start end]
-Exactly the same as @code{xsubstring}, but the extracted text
-is written into the string @var{target} starting at index
-@var{tstart}. The operation is not defined if @code{(eq?
-@var{target} @var{s})} or these arguments share storage -- you
-cannot copy a string on top of itself.
-@end deffn
-
-
-@c ===================================================================
-
-@node Miscellaneous
-@subsection Miscellaneous
-
-@code{string-replace} is for replacing a portion of a string with
-another string and @code{string-tokenize} splits a string into a list of
-strings, breaking it up at a specified character.
-
-@deffn primitive string-replace s1 s2 [start1 end1 start2 end2]
-Return the string @var{s1}, but with the characters
-@var{start1} @dots{} @var{end1} replaced by the characters
-@var{start2} @dots{} @var{end2} from @var{s2}.
-@end deffn
-
-@deffn primitive string-tokenize s [token_char start end]
-Split the string @var{s} into a list of substrings, where each
-substring is a maximal non-empty contiguous sequence of
-characters equal to the character @var{token_char}, or
-whitespace, if @var{token_char} is not given. If
-@var{token_char} is a character set, it is used for finding the
-token borders.
-@end deffn
-
-
-@c ===================================================================
-
-@node Filtering/Deleting
-@subsection Filtering/Deleting
-
-@dfn{Filtering} means to remove all characters from a string which do
-not match a given criteria, @dfn{deleting} means the opposite.
-
-@deffn primitive string-filter s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-satisfy the @var{char_pred} argument. If the argument is a
-procedure, it is applied to each character as a predicate, if
-it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-@deffn primitive string-delete s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-do not satisfy the @var{char_pred} argument. If the argument
-is a procedure, it is applied to each character as a predicate,
-if it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-
-@c ===================================================================
-
-@node Character-set Procedures
-@section Character-set Procedures
-
-SRFI-14 defines the data type @dfn{character set}, and also defines a
-lot of procedures for handling this character type, and a few standard
-character sets like whitespace, alphabetic characters and others.
-
-@menu
-* Character Set Data Type:: Description of the character set data type.
-* Predicates/Comparison:: Testing character sets.
-* Iterating Over Character Sets:: Iterating over the members of a set.
-* Creating Character Sets:: Creating new character sets.
-* Querying Character Sets:: Extracting information from character sets.
-* Character-Set Algebra:: Set-algebra on character sets.
-* Standard Character Sets:: Variables containg standard character sets.
-@end menu
-
-
-@c ===================================================================
-
-@node Character Set Data Type
-@subsection Character Set Data Type
-
-The data type @dfn{charset} implements sets of characters (REFFIXME).
-Because the internal representation of character sets is not visible to
-the user, a lot of procedures for handling them are provided.
-
-Character sets can be created, extended, tested for the membership of a
-characters and be compared to other character sets.
-
-The Guile implementation of character sets deals with 8-bit characters.
-In the standard variables, only the ASCII part of the character range is
-really used, so that for example @dfn{Umlaute} and other accented
-characters are not considered to be letters. In the future, as Guile
-may get support for international character sets, this will change, so
-don't rely on these ``features''.
-
-
-@c ===================================================================
-
-@node Predicates/Comparison
-@subsection Predicates/Comparison
-
-Use these procedures for testing whether an object is a character set,
-or whether several character sets are equal or subsets of each other.
-@code{char-set-hash} can be used for calculating a hash value, maybe for
-usage in fast lookup procedures.
-
-@deffn primitive char-set? obj
-Return @code{#t} if @var{obj} is a character set, @code{#f}
-otherwise.
-@end deffn
-
-@deffn primitive char-set= cs1 @dots{}
-Return @code{#t} if all given character sets are equal.
-@end deffn
-
-@deffn primitive char-set<= cs1 @dots{}
-Return @code{#t} if every character set @var{cs}i is a subset
-of character set @var{cs}i+1.
-@end deffn
-
-@deffn primitive char-set-hash cs [bound]
-Compute a hash value for the character set @var{cs}. If
-@var{bound} is given and not @code{#f}, it restricts the
-returned value to the range 0 @dots{} @var{bound - 1}.
-@end deffn
-
-
-@c ===================================================================
-
-@node Iterating Over Character Sets
-@subsection Iterating Over Character Sets
-
-Character set cursors are a means for iterating over the members of a
-character sets. After creating a character set cursor with
-@code{char-set-cursor}, a cursor can be dereferenced with
-@code{char-set-ref}, advanced to the next member with
-@code{char-set-cursor-next}. Whether a cursor has passed past the last
-element of the set can be checked with @code{end-of-char-set?}.
-
-Additionally, mapping and (un-)folding procedures for character sets are
-provided.
-
-@deffn primitive char-set-cursor cs
-Return a cursor into the character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-ref cs cursor
-Return the character at the current cursor position
-@var{cursor} in the character set @var{cs}. It is an error to
-pass a cursor for which @code{end-of-char-set?} returns true.
-@end deffn
-
-@deffn primitive char-set-cursor-next cs cursor
-Advance the character set cursor @var{cursor} to the next
-character in the character set @var{cs}. It is an error if the
-cursor given satisfies @code{end-of-char-set?}.
-@end deffn
-
-@deffn primitive end-of-char-set? cursor
-Return @code{#t} if @var{cursor} has reached the end of a
-character set, @code{#f} otherwise.
-@end deffn
-
-@deffn primitive char-set-fold kons knil cs
-Fold the procedure @var{kons} over the character set @var{cs},
-initializing it with @var{knil}.
-@end deffn
-
-@deffn primitive char-set-unfold p f g seed [base_cs]
-@deffnx primitive char-set-unfold! p f g seed base_cs
-This is a fundamental constructor for character sets.
-@itemize
-@item @var{g} is used to generate a series of ``seed'' values
-from the initial seed: @var{seed}, (@var{g} @var{seed}),
-(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
-@item @var{p} tells us when to stop -- when it returns true
-when applied to one of the seed values.
-@item @var{f} maps each seed value to a character. These
-characters are added to the base character set @var{base_cs} to
-form the result; @var{base_cs} defaults to the empty set.
-@end itemize
-
-@code{char-set-unfold!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive char-set-for-each proc cs
-Apply @var{proc} to every character in the character set
-@var{cs}. The return value is not specified.
-@end deffn
-
-@deffn primitive char-set-map proc cs
-Map the procedure @var{proc} over every character in @var{cs}.
-@var{proc} must be a character -> character procedure.
-@end deffn
-
-
-@c ===================================================================
-
-@node Creating Character Sets
-@subsection Creating Character Sets
-
-New character sets are produced with these procedures.
-
-@deffn primitive char-set-copy cs
-Return a newly allocated character set containing all
-characters in @var{cs}.
-@end deffn
-
-@deffn primitive char-set char1 @dots{}
-Return a character set containing all given characters.
-@end deffn
-
-@deffn primitive list->char-set char_list [base_cs]
-@deffnx primitive list->char-set! char_list base_cs
-Convert the character list @var{list} to a character set. If
-the character set @var{base_cs} is given, the character in this
-set are also included in the result.
-
-@code{list->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive string->char-set s [base_cs]
-@deffnx primitive string->char-set! s base_cs
-Convert the string @var{str} to a character set. If the
-character set @var{base_cs} is given, the characters in this
-set are also included in the result.
-
-@code{string->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive char-set-filter pred cs [base_cs]
-@deffnx primitive char-set-filter! pred cs base_cs
-Return a character set containing every character from @var{cs}
-so that it satisfies @var{pred}. If provided, the characters
-from @var{base_cs} are added to the result.
-
-@code{char-set-filter!} is the side-effecting variant.
-@end deffn
-
-@deffn primitive ucs-range->char-set lower upper [error? base_cs]
-@deffnx primitive uce-range->char-set! lower upper error? base_cs
-Return a character set containing all characters whose
-character codes lie in the half-open range
-[@var{lower},@var{upper}).
-
-If @var{error} is a true value, an error is signalled if the
-specified range contains characters which are not contained in
-the implemented character range. If @var{error} is @code{#f},
-these characters are silently left out of the resultung
-character set.
-
-The characters in @var{base_cs} are added to the result, if
-given.
-
-@code{ucs-range->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn procedure ->char-set x
-Coerce @var{x} into a character set. @var{x} may be a string, a
-character or a character set.
-@end deffn
-
-
-@c ===================================================================
-
-@node Querying Character Sets
-@subsection Querying Character Sets
-
-Access the elements and other information of a character set with these
-procedures.
-
-@deffn primitive char-set-size cs
-Return the number of elements in character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-count pred cs
-Return the number of the elements int the character set
-@var{cs} which satisfy the predicate @var{pred}.
-@end deffn
-
-@deffn primitive char-set->list cs
-Return a list containing the elements of the character set
-@var{cs}.
-@end deffn
-
-@deffn primitive char-set->string cs
-Return a string containing the elements of the character set
-@var{cs}. The order in which the characters are placed in the
-string is not defined.
-@end deffn
-
-@deffn primitive char-set-contains? cs char
-Return @code{#t} iff the character @var{ch} is contained in the
-character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-every pred cs
-Return a true value if every character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-@deffn primitive char-set-any pred cs
-Return a true value if any character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-
-@c ===================================================================
-
-@node Character-Set Algebra
-@subsection Character-Set Algebra
-
-Character sets can be manipulated with the common set algebra operation,
-such as union, complement, intersection etc. All of these procedures
-provide side--effecting variants, which modify their character set
-argument(s).
-
-@deffn primitive char-set-adjoin cs char1 @dots{}
-@deffnx primitive char-set-adjoin! cs char1 @dots{}
-Add all character arguments to the first argument, which must
-be a character set.
-@end deffn
-
-@deffn primitive char-set-delete cs char1 @dots{}
-@deffnx primitive char-set-delete! cs char1 @dots{}
-Delete all character arguments from the first argument, which
-must be a character set.
-@end deffn
-
-@deffn primitive char-set-complement cs
-@deffnx primitive char-set-complement! cs
-Return the complement of the character set @var{cs}.
-@end deffn
-
-@deffn primitive char-set-union cs1 @dots{}
-@deffnx primitive char-set-union! cs1 @dots{}
-Return the union of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-intersection cs1 @dots{}
-@deffnx primitive char-set-intersection! cs1 @dots{}
-Return the intersection of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-difference cs1 @dots{}
-@deffnx primitive char-set-difference! cs1 @dots{}
-Return the difference of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-xor cs1 @dots{}
-@deffnx primitive char-set-xor! cs1 @dots{}
-Return the exclusive--or of all argument character sets.
-@end deffn
-
-@deffn primitive char-set-diff+intersection cs1 @dots{}
-@deffnx primitive char-set-diff+intersection! cs1 @dots{}
-Return the difference and the intersection of all argument
-character sets.
-@end deffn
-
-
-@c ===================================================================
-
-@node Standard Character Sets
-@subsection Standard Character Sets
-
-In order to make the use of the character set data type and procedures
-useful, several predefined character set variables exist.
-
-@defvar char-set:lower-case
-All lower--case characters.
-@end defvar
-
-@defvar char-set:upper-case
-All upper--case characters.
-@end defvar
-
-@defvar char-set:title-case
-This is empty, because ASCII has no titlecase characters.
-@end defvar
-
-@defvar char-set:letter
-All letters, e.g. the union of @code{char-set:lower-case} and
-@code{char-set:upper-case}.
-@end defvar
-
-@defvar char-set:digit
-All digits.
-@end defvar
-
-@defvar char-set:letter+digit
-The union of @code{char-set:letter} and @code{char-set:digit}.
-@end defvar
-
-@defvar char-set:graphic
-All characters which would put ink on the paper.
-@end defvar
-
-@defvar char-set:printing
-The union of @code{char-set:graphic} and @code{char-set:whitespace}.
-@end defvar
-
-@defvar char-set:whitespace
-All whitespace characters.
-@end defvar
-
-@defvar char-set:blank
-All horizontal whitespace characters, that is @code{#\space} and
-@code{#\tab}.
-@end defvar
-
-@defvar char-set:iso-control
-The ISO control characters with the codes 0--31 and 127.
-@end defvar
-
-@defvar char-set:punctuation
-The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
-@end defvar
-
-@defvar char-set:symbol
-The characters @code{$+<=>^`|~}.
-@end defvar
-
-@defvar char-set:hex-digit
-The hexadecimal digits @code{0123456789abcdefABCDEF}.
-@end defvar
-
-@defvar char-set:ascii
-All ASCII characters.
-@end defvar
-
-@defvar char-set:empty
-The empty character set.
-@end defvar
-
-@defvar char-set:full
-This character set contains all possible characters.
-@end defvar
diff --git a/doc/srfi-modules.texi b/doc/srfi-modules.texi
new file mode 100644
index 000000000..e611414c9
--- /dev/null
+++ b/doc/srfi-modules.texi
@@ -0,0 +1,183 @@
+@node SRFI Support
+@chapter Various SRFI Support Modules
+
+In addition to the string and character--set libraries --- documented in
+the next chapter --- Guile has support for a number of SRFIs. This
+chapter gives an overview over the available SRFIs and some usage hints.
+For complete documentation, we advise you to get the relevant SRFI
+documents from the SRFI home page @url{http://srfi.schemers.org}.
+
+@menu
+* SRFI-2:: and-let*.
+* SRFI-6:: Basic String Ports.
+* SRFI-8:: receive.
+* SRFI-9:: define-record-type.
+* SRFI-10:: Hash--Comma Reader Extension.
+* SRFI-11:: let-values and let-values*.
+* SRFI-17:: Generalized set!
+@end menu
+
+
+@node SRFI-2
+@section SRFI-2 -- and-let*
+
+The syntactic form @code{and-let*} combines the conditional evaluation
+form @code{and} with the binding form @var{let*}. Each argument
+expression will be evaluated sequentially, bound to a variable (if a
+variable name is given), but only as long as no expression returns
+the false value @code{#f}.
+
+Use @code{(use-modules (srfi srfi-2)} to access this syntax form.
+
+
+@node SRFI-6
+@section SRFI-6 -- Basic String Ports
+
+SRFI-6 defines the procedures @code{open-input-string},
+@code{open-output-string} and @code{get-output-string}. These
+procedures are included in the Guile core, so using this module does not
+make any difference at the moment. But it is possible that support for
+SRFI-6 will be factored out of the core library in the future, so using
+this module does not hurt, after all.
+
+@node SRFI-8
+@section SRFI-8 -- receive
+
+@code{receive} is a syntax for making the handling of multiple--value
+procedures easier. It is documented in @xref{Multiple Values}.
+
+
+@node SRFI-9
+@section SRFI-9 -- define-record-type
+
+This is the SRFI way for defining record types. The Guile
+implementation is a layer above Guile's normal record construction
+procedures (REFFIXME). The nice thing about this kind of record
+definition method is that no new names are implicitly created, all
+constructor, accessor and predicates are explicitly given. This reduces
+the risk of variable capture.
+
+The syntax of a record type definition is:
+
+@example
+<record type definition>
+ -> (define-record-type <type name>
+ (<constructor name> <field tag> ...)
+ <predicate name>
+ <field spec> ...)
+<field spec> -> (<field tag> <accessor name>)
+ -> (<field tag> <accessor name> <modifier name>)
+<field tag> -> <identifier>
+<... name> -> <identifier>
+@end example
+
+Usage example:
+
+@example
+guile> (use-modules (srfi srfi-9))
+guile> (define-record-type :foo (make-foo x) foo?
+ (x get-x) (y get-y set-y!))
+guile> (define f (make-foo 1))
+guile> f
+#<:foo x: 1 y: #f>
+guile> (get-x f)
+1
+guile> (set-y! f 2)
+2
+guile> (get-y f)
+2
+guile> f
+#<:foo x: 1 y: 2>
+guile> (foo? f)
+#t
+guile> (foo? 1)
+#f
+@end example
+
+
+@node SRFI-10
+@section SRFI-10 -- Hash--Comma Reader Extension
+
+@cindex hash--comma
+@cindex #,()
+The module @code{(srfi srfi-10)} implements the syntax extension
+@code{#,()}, also called hash-comma, which is defined in SRFI-10.
+
+The support for SRFI-10 consists of the procedure
+@code{define-reader-ctor} for defining new reader constructors and the
+read syntax form
+
+@example
+#,(@var{ctor} @var{datum} ...)
+@end example
+
+where @var{ctor} must be a symbol for which a read constructor was
+defined previouly, using @code{define-reader-ctor}.
+
+Example:
+
+@lisp
+(define-reader-ctor 'file open-input-file)
+(define f '#,(file "/etc/passwd"))
+(read-line f)
+@result{}
+"root:x:0:0:root:/root:/bin/bash"
+@end lisp
+
+Please note the quote before the @code{#,(file ...)} expression. This
+is necessary because ports are not self-evaluating in Guile.
+
+@deffn procedure define-reader-ctor symbol proc
+Define @var{proc} as the reader constructor for hash--comma forms with a
+tag @var{symbol}. @var{proc} will be applied to the datum(s) following
+the tag in the hash--comma expression after the complete form has been
+read in. The result of @var{proc} is returned by the Scheme reader.
+@end deffn
+
+
+@node SRFI-11
+@section SRFI-11 -- let-values
+
+This module implements the binding forms for multiple values
+@code{let-values} and @code{let-values*}. These forms are similar to
+@code{let} and @code{let*} (REFFIXME), but they support binding of the
+values returned by multiple--valued expressions.
+
+Write @code{(use-modules (srfi srfi-11))} to make the bindings
+available.
+
+@lisp
+(let-values (((x y) (values 1 2))
+ ((z f) (values 3 4)))
+ (+ x y z f))
+@result{}
+10
+@end lisp
+
+@code{let-values} performs all bindings simultaneously, which means that
+no expression in the binding clauses may refer to variables bound in the
+same clause list. @code{let-values*}, on the other hand, performs the
+bindings sequentially, just like @code{let*} does for single--valued
+expressions.
+
+
+@node SRFI-17
+@section SRFI-17 -- Generalized set!
+
+This is an implementation of SRFI-17: Generalized set!
+
+It exports the Guile procedure @code{make-procedure-with-setter} under
+the SRFI name @code{getter-with-setter} and exports the standard
+procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
+@code{string-ref} and @code{vector-ref} as procedures with setters, as
+required by the SRFI.
+
+SRFI-17 was heavily criticized during its discussion period but it was
+finalized anyway. One issue was its concept of globally associating
+setter @dfn{properties} with (procedure) values, which is non-Schemy.
+For this reason, this implementation chooses not to provide a way to set
+the setter of a procedure. In fact, @code{(set! (setter @var{proc})
+@var{setter})} signals an error. The only way to attach a setter to a
+procedure is to create a new object (a @dfn{procedure with setter}) via
+the @code{getter-with-setter} procedure. This procedure is also
+specified in the SRFI. Using it avoids the described problems.