   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Miscellaneous
-------------

   `string-replace' is for replacing a portion of a string with another
string and `string-tokenize' splits a string into a list of strings,
breaking it up at a specified character.

 - Scheme Procedure: string-replace s1 s2 [start1 end1 start2 end2]
     Return the string S1, but with the characters START1 ... END1
     replaced by the characters START2 ... END2 from S2.

 - Scheme Procedure: string-tokenize s [token_char start end]
     Split the string S into a list of substrings, where each substring
     is a maximal non-empty contiguous sequence of characters equal to
     the character TOKEN_CHAR, or whitespace, if TOKEN_CHAR is not
     given.  If TOKEN_CHAR is a character set, it is used for finding
     the token borders.

Filtering/Deleting
------------------

   "Filtering" means to remove all characters from a string which do
not match a given criteria, "deleting" means the opposite.

 - Scheme Procedure: string-filter s char_pred [start end]
     Filter the string S, retaining only those characters that satisfy
     the 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.

 - Scheme Procedure: string-delete s char_pred [start end]
     Filter the string S, retaining only those characters that do not
     satisfy the 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.

SRFI-14 - Character-set Library
===============================

   SRFI-14 defines the data type "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.

   All procedures from SRFI-14 (character-set library) are implemented
in the module `(srfi srfi-14)', as well as the standard variables
`char-set:letter', `char-set:digit' etc.

Loading SRFI-14
---------------

   When Guile is properly installed, SRFI-14 support can be loaded into
a running Guile by using the `(srfi srfi-14)' module.

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

Character Set Data Type
-----------------------

   The data type "charset" implements sets of characters (see
Characters).  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 "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".

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.  `char-set-hash' can be used for calculating a hash value, maybe
for usage in fast lookup procedures.

 - Scheme Procedure: char-set? obj
     Return `#t' if OBJ is a character set, `#f' otherwise.

 - Scheme Procedure: char-set= cs1 ...
     Return `#t' if all given character sets are equal.

 - Scheme Procedure: char-set<= cs1 ...
     Return `#t' if every character set CSi is a subset of character
     set CSi+1.

 - Scheme Procedure: char-set-hash cs [bound]
     Compute a hash value for the character set CS.  If BOUND is given
     and not `#f', it restricts the returned value to the range 0 ...
     BOUND - 1.

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
`char-set-cursor', a cursor can be dereferenced with `char-set-ref',
advanced to the next member with `char-set-cursor-next'.  Whether a
cursor has passed past the last element of the set can be checked with
`end-of-char-set?'.

   Additionally, mapping and (un-)folding procedures for character sets
are provided.

 - Scheme Procedure: char-set-cursor cs
     Return a cursor into the character set CS.

 - Scheme Procedure: char-set-ref cs cursor
     Return the character at the current cursor position CURSOR in the
     character set CS.  It is an error to pass a cursor for which
     `end-of-char-set?' returns true.

 - Scheme Procedure: char-set-cursor-next cs cursor
     Advance the character set cursor CURSOR to the next character in
     the character set CS.  It is an error if the cursor given
     satisfies `end-of-char-set?'.

 - Scheme Procedure: end-of-char-set? cursor
     Return `#t' if CURSOR has reached the end of a character set, `#f'
     otherwise.

 - Scheme Procedure: char-set-fold kons knil cs
     Fold the procedure KONS over the character set CS, initializing it
     with KNIL.

 - Scheme Procedure: char-set-unfold p f g seed [base_cs]
 - Scheme Procedure: char-set-unfold! p f g seed base_cs
     This is a fundamental constructor for character sets.
        * G is used to generate a series of "seed" values from the
          initial seed: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ...

        * P tells us when to stop - when it returns true when applied
          to one of the seed values.

        * F maps each seed value to a character. These characters are
          added to the base character set BASE_CS to form the result;
          BASE_CS defaults to the empty set.

     `char-set-unfold!' is the side-effecting variant.

 - Scheme Procedure: char-set-for-each proc cs
     Apply PROC to every character in the character set CS.  The return
     value is not specified.

 - Scheme Procedure: char-set-map proc cs
     Map the procedure PROC over every character in CS.  PROC must be a
     character -> character procedure.

Creating Character Sets
-----------------------

   New character sets are produced with these procedures.

 - Scheme Procedure: char-set-copy cs
     Return a newly allocated character set containing all characters
     in CS.

 - Scheme Procedure: char-set char1 ...
     Return a character set containing all given characters.

 - Scheme Procedure: list->char-set char_list [base_cs]
 - Scheme Procedure: list->char-set! char_list base_cs
     Convert the character list LIST to a character set.  If the
     character set BASE_CS is given, the character in this set are also
     included in the result.

     `list->char-set!' is the side-effecting variant.

 - Scheme Procedure: string->char-set s [base_cs]
 - Scheme Procedure: string->char-set! s base_cs
     Convert the string STR to a character set.  If the character set
     BASE_CS is given, the characters in this set are also included in
     the result.

     `string->char-set!' is the side-effecting variant.

 - Scheme Procedure: char-set-filter pred cs [base_cs]
 - Scheme Procedure: char-set-filter! pred cs base_cs
     Return a character set containing every character from CS so that
     it satisfies PRED.  If provided, the characters from BASE_CS are
     added to the result.

     `char-set-filter!' is the side-effecting variant.

 - Scheme Procedure: ucs-range->char-set lower upper [error? base_cs]
 - Scheme Procedure: 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 [LOWER,UPPER).

     If 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 ERROR is `#f', these characters
     are silently left out of the resulting character set.

     The characters in BASE_CS are added to the result, if given.

     `ucs-range->char-set!' is the side-effecting variant.

 - Scheme Procedure: ->char-set x
     Coerce X into a character set.  X may be a string, a character or
     a character set.

Querying Character Sets
-----------------------

   Access the elements and other information of a character set with
these procedures.

 - Scheme Procedure: char-set-size cs
     Return the number of elements in character set CS.

 - Scheme Procedure: char-set-count pred cs
     Return the number of the elements int the character set CS which
     satisfy the predicate PRED.

 - Scheme Procedure: char-set->list cs
     Return a list containing the elements of the character set CS.

 - Scheme Procedure: char-set->string cs
     Return a string containing the elements of the character set CS.
     The order in which the characters are placed in the string is not
     defined.

 - Scheme Procedure: char-set-contains? cs char
     Return `#t' iff the character CH is contained in the character set
     CS.

 - Scheme Procedure: char-set-every pred cs
     Return a true value if every character in the character set CS
     satisfies the predicate PRED.

 - Scheme Procedure: char-set-any pred cs
     Return a true value if any character in the character set CS
     satisfies the predicate PRED.

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

 - Scheme Procedure: char-set-adjoin cs char1 ...
 - Scheme Procedure: char-set-adjoin! cs char1 ...
     Add all character arguments to the first argument, which must be a
     character set.

 - Scheme Procedure: char-set-delete cs char1 ...
 - Scheme Procedure: char-set-delete! cs char1 ...
     Delete all character arguments from the first argument, which must
     be a character set.

 - Scheme Procedure: char-set-complement cs
 - Scheme Procedure: char-set-complement! cs
     Return the complement of the character set CS.

 - Scheme Procedure: char-set-union cs1 ...
 - Scheme Procedure: char-set-union! cs1 ...
     Return the union of all argument character sets.

 - Scheme Procedure: char-set-intersection cs1 ...
 - Scheme Procedure: char-set-intersection! cs1 ...
     Return the intersection of all argument character sets.

 - Scheme Procedure: char-set-difference cs1 ...
 - Scheme Procedure: char-set-difference! cs1 ...
     Return the difference of all argument character sets.

 - Scheme Procedure: char-set-xor cs1 ...
 - Scheme Procedure: char-set-xor! cs1 ...
     Return the exclusive-or of all argument character sets.

 - Scheme Procedure: char-set-diff+intersection cs1 ...
 - Scheme Procedure: char-set-diff+intersection! cs1 ...
     Return the difference and the intersection of all argument
     character sets.

Standard Character Sets
-----------------------

   In order to make the use of the character set data type and
procedures useful, several predefined character set variables exist.

 - Variable: char-set:lower-case
     All lower-case characters.

 - Variable: char-set:upper-case
     All upper-case characters.

 - Variable: char-set:title-case
     This is empty, because ASCII has no titlecase characters.

 - Variable: char-set:letter
     All letters, e.g. the union of `char-set:lower-case' and
     `char-set:upper-case'.

 - Variable: char-set:digit
     All digits.

 - Variable: char-set:letter+digit
     The union of `char-set:letter' and `char-set:digit'.

 - Variable: char-set:graphic
     All characters which would put ink on the paper.

 - Variable: char-set:printing
     The union of `char-set:graphic' and `char-set:whitespace'.

 - Variable: char-set:whitespace
     All whitespace characters.

 - Variable: char-set:blank
     All horizontal whitespace characters, that is `#\space' and
     `#\tab'.

 - Variable: char-set:iso-control
     The ISO control characters with the codes 0-31 and 127.

 - Variable: char-set:punctuation
     The characters `!"#%&'()*,-./:;?@[\\]_{}'

 - Variable: char-set:symbol
     The characters `$+<=>^`|~'.

 - Variable: char-set:hex-digit
     The hexadecimal digits `0123456789abcdefABCDEF'.

 - Variable: char-set:ascii
     All ASCII characters.

 - Variable: char-set:empty
     The empty character set.

 - Variable: char-set:full
     This character set contains all possible characters.

SRFI-16 - case-lambda
=====================

   The syntactic form `case-lambda' creates procedures, just like
`lambda', but has syntactic extensions for writing procedures of
varying arity easier.

   The syntax of the `case-lambda' form is defined in the following
EBNF grammar.

     <case-lambda>
        --> (case-lambda <case-lambda-clause>)
     <case-lambda-clause>
        --> (<formals> <definition-or-command>*)
     <formals>
        --> (<identifier>*)
          | (<identifier>* . <identifier>)
          | <identifier>

   The value returned by a `case-lambda' form is a procedure which
matches the number of actual arguments against the formals in the
various clauses, in order.  "Formals" means a formal argument list just
like with `lambda' (see Lambda). The first matching clause is
selected, the corresponding values from the actual parameter list are
bound to the variable names in the clauses and the body of the clause is
evaluated.  If no clause matches, an error is signalled.

   The following (silly) definition creates a procedure FOO which acts
differently, depending on the number of actual arguments.  If one
argument is given, the constant `#t' is returned, two arguments are
added and if more arguments are passed, their product is calculated.

     (define foo (case-lambda
                   ((x) #t)
                   ((x y) (+ x y))
                   (z
                     (apply * z))))
     (foo 'bar)
     =>
     #t
     (foo 2 4)
     =>
     6
     (foo 3 3 3)
     =>
     27
     (foo)
     =>
     1

   The last expression evaluates to 1 because the last clause is
matched, Z is bound to the empty list and the following multiplication,
applied to zero arguments, yields 1.

SRFI-17 - Generalized set!
==========================

   This is an implementation of SRFI-17: Generalized set!

   It exports the Guile procedure `make-procedure-with-setter' under
the SRFI name `getter-with-setter' and exports the standard procedures
`car', `cdr', ..., `cdddr', `string-ref' and `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 "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, `(set!  (setter PROC) SETTER)'
signals an error.  The only way to attach a setter to a procedure is to
create a new object (a "procedure with setter") via the
`getter-with-setter' procedure. This procedure is also specified in the
SRFI.  Using it avoids the described problems.

SRFI-19 - Time/Date Library
===========================

   This is an implementation of SRFI-19: Time/Date Library

   It depends on SRFIs: 6 (see SRFI-6), 8 (see SRFI-8), 9
(see SRFI-9).

   This section documents constants and procedure signatures.

SRFI-19 Constants
-----------------

   All these are bound to their symbol names:

                time-duration
                time-monotonic
                time-process
                time-tai
                time-thread
                time-utc

SRFI-19 Current time and clock resolution
-----------------------------------------

                (current-date . tz-offset)
                (current-julian-day)
                (current-modified-julian-day)
                (current-time . clock-type)
                (time-resolution . clock-type)

SRFI-19 Time object and accessors
---------------------------------

                (make-time type nanosecond second)
                (time? obj)
                (time-type time)
                (time-nanosecond time)
                (time-second time)
                (set-time-type! time type)
                (set-time-nanosecond! time nsec)
                (set-time-second! time sec)
                (copy-time time)

SRFI-19 Time comparison procedures
----------------------------------

   Args are all `time' values.

                (time<=? t1 t2)
                (time<? t1 t2)
                (time=? t1 t2)
                (time>=? t1 t2)
                (time>? t1 t2)

SRFI-19 Time arithmetic procedures
----------------------------------

   The `foo!' variants modify in place.  Time difference is expressed
in `time-duration' values.

                (time-difference t1 t2)
                (time-difference! t1 t2)
                (add-duration time duration)
                (add-duration! time duration)
                (subtract-duration time duration)
                (subtract-duration! time duration)

SRFI-19 Date object and accessors
---------------------------------

                (make-date nsecs seconds minutes hours
                           date month year offset)
                (date? obj)
                (date-nanosecond date)
                (date-second date)
                (date-minute date)
                (date-hour date)
                (date-day date)
                (date-month date)
                (date-year date)
                (date-zone-offset date)
                (date-year-day date)
                (date-week-day date)
                (date-week-number date day-of-week-starting-week)

SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-----------------------------------------------------------

                (date->julian-day date)
                (date->modified-julian-day date)
                (date->time-monotonic date)
                (date->time-tai date)
                (date->time-utc date)
                (julian-day->date jdn . tz-offset)
                (julian-day->time-monotonic jdn)
                (julian-day->time-tai jdn)
                (julian-day->time-utc jdn)
                (modified-julian-day->date jdn . tz-offset)
                (modified-julian-day->time-monotonic jdn)
                (modified-julian-day->time-tai jdn)
                (modified-julian-day->time-utc jdn)
                (time-monotonic->date time . tz-offset)
                (time-monotonic->time-tai time-in)
                (time-monotonic->time-tai! time-in)
                (time-monotonic->time-utc time-in)
                (time-monotonic->time-utc! time-in)
                (time-tai->date time . tz-offset)
                (time-tai->julian-day time)
                (time-tai->modified-julian-day time)
                (time-tai->time-monotonic time-in)
                (time-tai->time-monotonic! time-in)
                (time-tai->time-utc time-in)
                (time-tai->time-utc! time-in)
                (time-utc->date time . tz-offset)
                (time-utc->julian-day time)
                (time-utc->modified-julian-day time)
                (time-utc->time-monotonic time-in)
                (time-utc->time-monotonic! time-in)
                (time-utc->time-tai time-in)
                (time-utc->time-tai! time-in)

SRFI-19 Date to string/string to date converters
------------------------------------------------

                (date->string date . format-string)
                (string->date input-string template-string)

Readline Support
****************

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

Loading Readline Support
========================

   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:

     (use-modules (ice-9 readline))
     (activate-readline)

   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 `.guile' personal
startup file.

   You will notice that the REPL's behaviour changes a bit when you have
loaded the readline module.  For example, when you press Enter before
typing in the closing parentheses of a list, you will see the
"continuation" prompt, three dots: `...'  This gives you a nice visual
feedback when trying to match parentheses.  To make this even easier,
"bouncing parentheses" are implemented.  That means that when you type
in a closing parentheses, the cursor will jump to the corresponding
opening parenthesis 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 `(quit)' or pressing
Ctrl-D, the history will be saved to the 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.

Readline Options
================

   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 (see User level options interfaces.)

   Here is the list of readline options generated by typing
`(readline-options 'full)' in Guile.  You can also see the default
values.

     bounce-parens   500   Time (ms) to show matching opening parenthesis (0 = off).
     history-length  200   History length.
     history-file    yes   Use history file.

   The history length specifies how many input lines will be remembered.
If the history contains that many lines and additional lines are
entered, the oldest lines will be lost.  You can switch on/off the
usage of the history file using the following call.

     (readline-disable 'history)

   The readline options interface can only be used _after_ loading the
readline module, because it is defined in that module.

Value History
*************

   Another module which makes command line usage more convenient is
`(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 (`$') and the number of the
evaluated expression.

   Consider an example session.

     guile> (use-modules (ice-9 history))
     guile> 1
     $1 = 1
     guile> (+ $1 $1)
     $2 = 2
     guile> (* $2 $2)
     $3 = 4

   After loading the value history module `(ice-9 history)', one
(trivial) expression is evaluated.  The result is stored into the
variable `$1'.  This fact is indicated by the output `$1 = ', which is
also caused by `(ice-9 history)'.  In the next line, this variable is
used two times, to produce the value `$2', which in turn is used in the
calculation for `$3'.

Pretty Printing
***************

   The module `(ice-9 pretty-print)' provides the procedure
`pretty-print', which provides nicely formatted output of Scheme
objects.  This is especially useful for deeply nested or complex data
structures, such as lists and vectors.

   The module is loaded by simply saying.

     (use-modules (ice-9 pretty-print))

   This makes the procedure `pretty-print' available.  As an example
how `pretty-print' will format the output, see the following:

     (pretty-print '(define (foo) (lambda (x)
     (cond ((zero? x) #t) ((negative? x) -x) (else (if (= x 1) 2 (* x x x)))))))
     -|
     (define (foo)
       (lambda (x)
         (cond ((zero? x) #t)
               ((negative? x) -x)
               (else (if (= x 1) 2 (* x x x))))))

 - Scheme Procedure: pretty-print obj [port]
     Print the textual representation of the Scheme object OBJ to PORT.
     PORT defaults to the current output port, if not given.

   Beware: Since `pretty-print' uses it's own write procedure, it's
output will not be the same as for example the output of `write'.
Consider the following example.

     (write (lambda (x) x))
     -|
     #<procedure #f (x)>

     (pretty-print (lambda (x) x))
     -|
     #[procedure]

   The reason is that `pretty-print' does not know as much about
Guile's object types as the builtin procedures.  This is particularly
important for smobs, for which a write procedure can be defined and be
used by `write', but not by `pretty-print'.

Formatted Output
****************

   Outputting messages or other texts which are composed of literal
strings, variable contents, newlines and other formatting can be
cumbersome, when only the standard procedures like `display', `write'
and `newline' are available.  Additionally, one often wants to collect
the output in strings.  With the standard routines, the user is
required to set up a string port, add this port as a parameter to the
output procedure calls and then retrieve the resulting string from the
string port.

   The `format' procedure, to be found in module `(ice-9 format)', can
do all this, and even more.  If you are a C programmer, you can think
of this procedure as Guile's `fprintf'.

 - Scheme Procedure: format destination format-string args ...
     The first parameter is the DESTINATION, it determines where the
     output of `format' will go.

    `#t'
          Send the formatted output to the current output port and
          return `#t'.

    `#f'
          Return the formatted output as a string.

    Any number value
          Send the formatted output to the current error port and return
          `#t'.

    A valid output port
          Send the formatted output to the port DESTINATION and return
          `#t'.

     The second parameter is the format string.  It has a similar
     function to the format string in calls to `printf' or `fprintf' in
     C.  It is output to the specified destination, but all escape
     sequences are replaced by the results of formatting the
     corresponding sequence.

     Note that escape sequences are marked with the character `~'
     (tilde), and not with a `%' (percent sign), as in C.

     The escape sequences in the following table are supported.  When
     there appears "corresponding ARG', that means any of the additional
     arguments, after dropping all arguments which have been used up by
     escape sequences which have been processed earlier.  Some of the
     format characters (the characters following the tilde) can be
     prefixed by `:', `@', or `:@', to modify the behaviour of the
     format character.  How the modified behaviour differs from the
     default behaviour is described for every character in the table
     where appropriate.

    `~~'
          Output a single `~' (tilde) character.

    `~%'
          Output a newline character, thus advancing to the next output
          line.

    `~&'
          Start a new line, that is, output a newline character if not
          already at the start of a line.

    `~_'
          Output a single space character.

    `~/'
          Output a single tabulator character.

    `~|'
          Output a page separator (formfeed) character.

    `~t'
          Advance to the next tabulator position.

    `~y'
          Pretty-print the corresponding ARG.

    `~a'
          Output the corresponding ARG like `display'.

    `~s'
          Output the corresponding ARG like `write'.

    `~d'
          Output the corresponding ARG as a decimal number.

    `~x'
          Output the corresponding ARG as a hexadecimal number.

    `~o'
          Output the corresponding ARG as an octal number.

    `~b'
          Output the corresponding ARG as a binary number.

    `~r'
          Output the corresponding ARG as a number word, e.g. 10 prints
          as `ten'.  If prefixed with `:', `tenth' is printed, if
          prefixed with `:@', Roman numbers are printed.

    `~f'
          Output the corresponding ARG as a fixed format floating point
          number, such as `1.34'.

    `~e'
          Output the corresponding ARG in exponential notation, such as
          `1.34E+0'.

    `~g'
          This works either like `~f' or like `~e', whichever produces
          less characters to be written.

    `~$'
          Like `~f', but only with two digits after the decimal point.

    `~i'
          Output the corresponding ARG as a complex number.

    `~c'
          Output the corresponding ARG as a character.  If prefixed with
          `@', it is printed like with `write'.  If prefixed with `:',
          control characters are treated specially, for example
          `#\newline' will be printed as `^J'.

    `~p'
          "Plural".  If the corresponding ARG is 1, nothing is printed
          (or `y' if prefixed with `@' or `:@'), otherwise `s' is
          printed (or `ies' if prefixed with `@' or `:@').

    `~?, ~k'
          Take the corresponding argument as a format string, and the
          following argument as a list of values.  Then format the
          values with respect to the format string.

    `~!'
          Flush the output to the output port.

    `~#\newline (tilde-newline)'
          Continuation lines.

    `~*'
          Argument jumping. Navigate in the argument list as specified
          by the corresponding argument.  If prefixed with `:', jump
          backwards in the argument list, if prefixed by `:@', jump to
          the parameter with the absolute index, otherwise jump forward
          in the argument list.

    `~('
          Case conversion begin.  If prefixed by `:', the following
          output string will be capitalized, if prefixed by `@', the
          first character will be capitalized, if prefixed by `:@' it
          will be upcased and otherwise it will be downcased.
          Conversion stops when the "Case conversion end" `~)'sequence
          is encountered.

    `~)'
          Case conversion end.  Stop any case conversion currently in
          effect.

    `~['
          Conditional begin.

    `~;'
          Conditional separator.

    `~]'
          Conditional end.

    `~{'
          Iteration begin.

    `~}'
          Iteration end.

    `~^'
          Up and out.

    `~''
          Character parameter.

    `~0 ... ~9, ~-, ~+'
          Numeric parameter.

    `~v'
          Variable parameter from next argument.

    `~#'
          Parameter is number of remaining args.  The number of the
          remaining arguments is prepended to the list of unprocessed
          arguments.

    `~,'
          Parameter separators.

    `~q'
          Inquiry message.  Insert a copyright message into the output.

     If any type conversions should fail (for example when using an
     escape sequence for number output, but the argument is a string),
     an error will be signalled.

   You may have noticed that Guile contains a `format' procedure even
when the module `(ice-9 format)' is not loaded.  The default `format'
procedure does not support all escape sequences documented in this
chapter, and will signal an error if you try to use one of them.  The
reason for providing two versions of `format' is that the full-featured
module is fairly large and requires some time to get loaded.  So the
Guile maintainers decided not to load the large version of `format' by
default, so that the start-up time of the interpreter is not
unnecessarily increased.

The Rx Regular Expression Library
*********************************

   [FIXME: this is taken from Gary and Mark's quick summaries and
should be reviewed and expanded.  Rx is pretty stable, so could already
be done!]

   The `guile-lang-allover' package provides an interface to Tom Lord's
Rx library (currently only to POSIX regular expressions).  Use of the
library requires a two step process: compile a regular expression into
an efficient structure, then use the structure in any number of string
comparisons.

   For example, given the regular expression `abc.' (which matches any
string containing `abc' followed by any single character):

     guile> (define r (regcomp "abc."))
     guile> r
     #<rgx abc.>
     guile> (regexec r "abc")
     #f
     guile> (regexec r "abcd")
     #((0 . 4))
     guile>

   The definitions of `regcomp' and `regexec' are as follows:

 - Scheme Procedure: regcomp pattern [flags]
     Compile the regular expression pattern using POSIX rules.  Flags is
     optional and should be specified using symbolic names:

      - Variable: REG_EXTENDED
          use extended POSIX syntax

      - Variable: REG_ICASE
          use case-insensitive matching

      - Variable: REG_NEWLINE
          allow anchors to match after newline characters in the string
          and prevents `.' or `[^...]' from matching newlines.

     The `logior' procedure can be used to combine multiple flags.  The
     default is to use POSIX basic syntax, which makes `+' and `?'
     literals and `\+' and `\?' operators.  Backslashes in PATTERN must
     be escaped if specified in a literal string e.g., `"\\(a\\)\\?"'.

 - Scheme Procedure: regexec regex string [match-pick] [flags]
     Match STRING against the compiled POSIX regular expression REGEX.
     MATCH-PICK and FLAGS are optional.  Possible flags (which can be
     combined using the logior procedure) are:

      - Variable: REG_NOTBOL
          The beginning of line operator won't match the beginning of
          STRING (presumably because it's not the beginning of a line)

      - Variable: REG_NOTEOL
          Similar to REG_NOTBOL, but prevents the end of line operator
          from matching the end of STRING.

     If no match is possible, regexec returns #f.  Otherwise MATCH-PICK
     determines the return value:

     `#t' or unspecified: a newly-allocated vector is returned,
     containing pairs with the indices of the matched part of STRING
     and any substrings.

     `""': a list is returned: the first element contains a nested list
     with the matched part of STRING surrounded by the the unmatched
     parts.  Remaining elements are matched substrings (if any).  All
     returned substrings share memory with STRING.

     `#f': regexec returns #t if a match is made, otherwise #f.

     vector: the supplied vector is returned, with the first element
     replaced by a pair containing the indices of the matched portion
     of STRING and further elements replaced by pairs containing the
     indices of matched substrings (if any).

     list: a list will be returned, with each member of the list
     specified by a code in the corresponding position of the supplied
     list:

     a number: the numbered matching substring (0 for the entire match).

     `#\<': the beginning of STRING to the beginning of the part matched
     by regex.

     `#\>': the end of the matched part of STRING to the end of STRING.

     `#\c': the "final tag", which seems to be associated with the "cut
     operator", which doesn't seem to be available through the posix
     interface.

     e.g., `(list #\< 0 1 #\>)'.  The returned substrings share memory
     with STRING.

   Here are some other procedures that might be used when using regular
expressions:

 - Scheme Procedure: compiled-regexp? obj
     Test whether obj is a compiled regular expression.

 - Scheme Procedure: regexp->dfa regex [flags]

 - Scheme Procedure: dfa-fork dfa

 - Scheme Procedure: reset-dfa! dfa

 - Scheme Procedure: dfa-final-tag dfa

 - Scheme Procedure: dfa-continuable? dfa

 - Scheme Procedure: advance-dfa! dfa string

Expect
******

   The macros in this section are made available with:

     (use-modules (ice-9 expect))

   `expect' is a macro for selecting actions based on the output from a
port.  The name comes from a tool of similar functionality by Don Libes.
Actions can be taken when a particular string is matched, when a timeout
occurs, or when end-of-file is seen on the port.  The `expect' macro is
described below; `expect-strings' is a front-end to `expect' based on
regexec (see the regular expression documentation).

 - Macro: expect-strings clause ...
     By default, `expect-strings' will read from the current input port.
     The first term in each clause consists of an expression evaluating
     to a string pattern (regular expression).  As characters are read
     one-by-one from the port, they are accumulated in a buffer string
     which is matched against each of the patterns.  When a pattern
     matches, the remaining expression(s) in the clause are evaluated
     and the value of the last is returned.  For example:

          (with-input-from-file "/etc/passwd"
            (lambda ()
              (expect-strings
                ("^nobody" (display "Got a nobody user.\n")
                           (display "That's no problem.\n"))
                ("^daemon" (display "Got a daemon user.\n")))))

     The regular expression is compiled with the `REG_NEWLINE' flag, so
     that the ^ and $ anchors will match at any newline, not just at
     the start and end of the string.

     There are two other ways to write a clause:

     The expression(s) to evaluate can be omitted, in which case the
     result of the regular expression match (converted to strings, as
     obtained from regexec with match-pick set to "") will be returned
     if the pattern matches.

     The symbol `=>' can be used to indicate that the expression is a
     procedure which will accept the result of a successful regular
     expression match.  E.g.,

          ("^daemon" => write)
          ("^d\\(aemon\\)" => (lambda args (for-each write args)))
          ("^da\\(em\\)on" => (lambda (all sub)
                                   (write all) (newline)
                                   (write sub) (newline)))

     The order of the substrings corresponds to the order in which the
     opening brackets occur.

     A number of variables can be used to control the behaviour of
     `expect' (and `expect-strings').  Most have default top-level
     bindings to the value `#f', which produces the default behaviour.
     They can be redefined at the top level or locally bound in a form
     enclosing the expect expression.

    `expect-port'
          A port to read characters from, instead of the current input
          port.

    `expect-timeout'
          `expect' will terminate after this number of seconds,
          returning `#f' or the value returned by expect-timeout-proc.

    `expect-timeout-proc'
          A procedure called if timeout occurs.  The procedure takes a
          single argument: the accumulated string.

    `expect-eof-proc'
          A procedure called if end-of-file is detected on the input
          port.  The procedure takes a single argument: the accumulated
          string.

    `expect-char-proc'
          A procedure to be called every time a character is read from
          the port.  The procedure takes a single argument: the
          character which was read.

    `expect-strings-compile-flags'
          Flags to be used when compiling a regular expression, which
          are passed to `make-regexp' Regexp Functions.  The
          default value is `regexp/newline'.

    `expect-strings-exec-flags'
          Flags to be used when executing a regular expression, which
          are passed to regexp-exec Regexp Functions.  The
          default value is `regexp/noteol', which prevents `$' from
          matching the end of the string while it is still accumulating,
          but still allows it to match after a line break or at the end
          of file.

     Here's an example using all of the variables:

          (let ((expect-port (open-input-file "/etc/passwd"))
                (expect-timeout 1)
                (expect-timeout-proc
                  (lambda (s) (display "Times up!\n")))
                (expect-eof-proc
                  (lambda (s) (display "Reached the end of the file!\n")))
                (expect-char-proc display)
                (expect-strings-compile-flags (logior regexp/newline regexp/icase))
                (expect-strings-exec-flags 0))
             (expect-strings
               ("^nobody"  (display "Got a nobody user\n"))))

 - Macro: expect clause ...
     `expect' is used in the same way as `expect-strings', but tests
     are specified not as patterns, but as procedures.  The procedures
     are called in turn after each character is read from the port,
     with two arguments: the value of the accumulated string and a flag
     to indicate whether end-of-file has been reached.  The flag will
     usually be `#f', but if end-of-file is reached, the procedures are
     called an additional time with the final accumulated string and
     `#t'.

     The test is successful if the procedure returns a non-false value.

     If the `=>' syntax is used, then if the test succeeds it must
     return a list containing the arguments to be provided to the
     corresponding expression.

     In the following example, a string will only be matched at the
     beginning of the file:

          (let ((expect-port (open-input-file "/etc/passwd")))
            (expect
               ((lambda (s eof?) (string=? s "fnord!"))
                  (display "Got a nobody user!\n"))))

     The control variables described for `expect-strings' also
     influence the behaviour of `expect', with the exception of
     variables whose names begin with `expect-strings-'.

The Scheme shell (scsh)
***********************

   An incomplete port of the Scheme shell (scsh) is available for Guile
as a separate package.  The current status of guile-scsh can be found at
<http://arglist.com/guile/>.

   For information about scsh see
<http://www-swiss.ai.mit.edu/ftpdir/scsh/>.

   The closest emulation of scsh can be obtained by running:

     (load-from-path "scsh/init")

   See the USAGE file supplied with guile-scsh for more details.