guile/doc/ref/r6rs.texi

@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  2010, 2011, 2012, 2013,
@c   2014, 2019 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node R6RS Support
@section R6RS Support
@cindex R6RS

@xref{R6RS Libraries}, for more information on how to define R6RS libraries, and
their integration with Guile modules.

@menu
* R6RS Incompatibilities::              Guile mostly implements R6RS.
* R6RS Standard Libraries::             Modules defined by the R6RS.
@end menu

@node R6RS Incompatibilities
@subsection Incompatibilities with the R6RS

There are some incompatibilities between Guile and the R6RS.  Some of 
them are intentional, some of them are bugs, and some are simply 
unimplemented features.  Please let the Guile developers know if you 
find one that is not on this list.

@itemize
@item
The R6RS specifies many situations in which a conforming implementation
must signal a specific error.  Guile doesn't really care about that too
much---if a correct R6RS program would not hit that error, we don't 
bother checking for it.

@item
Multiple @code{library} forms in one file are not yet supported.  This 
is because the expansion of @code{library} sets the current module, but
does not restore it.  This is a bug.

@item
R6RS unicode escapes within strings are disabled by default, because
they conflict with Guile's already-existing escapes. The same is the
case for R6RS treatment of escaped newlines in strings.

R6RS behavior can be turned on via a reader option. @xref{String
Syntax}, for more information.

@item
Guile does not yet support Unicode escapes in symbols, such as
@code{H\x65;llo} (the same as @code{Hello}), or @code{\x3BB;} (the same
as @code{λ}).

@item
A @code{set!} to a variable transformer may only expand to an 
expression, not a definition---even if the original @code{set!} 
expression was in definition context.

@item
Instead of using the algorithm detailed in chapter 10 of the R6RS,
expansion of toplevel forms happens sequentially.

For example, while the expansion of the following set of toplevel
definitions does the correct thing:

@example
(begin
 (define even?
   (lambda (x)
     (or (= x 0) (odd? (- x 1)))))
 (define-syntax odd?
   (syntax-rules ()
     ((odd? x) (not (even? x)))))
 (even? 10))
@result{} #t
@end example

@noindent
The same definitions outside of the @code{begin} wrapper do not:

@example
(define even?
  (lambda (x)
    (or (= x 0) (odd? (- x 1)))))
(define-syntax odd?
  (syntax-rules ()
    ((odd? x) (not (even? x)))))
(even? 10)
<unnamed port>:4:18: In procedure even?:
<unnamed port>:4:18: Wrong type to apply: #<syntax-transformer odd?>
@end example

This is because when expanding the right-hand-side of @code{even?}, the
reference to @code{odd?} is not yet marked as a syntax transformer, so
it is assumed to be a function.

This bug will only affect top-level programs, not code in @code{library}
forms.  Fixing it for toplevel forms seems doable, but tricky to
implement in a backward-compatible way. Suggestions and/or patches would
be appreciated.

@item
The @code{(rnrs io ports)} module is incomplete.  Work is
ongoing to fix this.

@item
Guile does not prevent use of textual I/O procedures on binary ports, or
vice versa.  All ports in Guile support both binary and textual I/O.
@xref{Encoding}, for full details.

@item
Guile's implementation of @code{equal?} may fail to terminate when
applied to arguments containing cycles.
@end itemize

Guile exposes a procedure in the root module to choose R6RS defaults
over Guile's historical defaults.

@deffn {Scheme Procedure} install-r6rs!
Alter Guile's default settings to better conform to the R6RS.

While Guile's defaults may evolve over time, the current changes that
this procedure imposes are to add @code{.sls} and @code{.guile.sls} to
the set of supported @code{%load-extensions}, to better support R6RS
conventions.  @xref{Load Paths}.  Also, enable R6RS unicode escapes in
strings; see the discussion above.
@end deffn

Finally, note that the @code{--r6rs} command-line argument will call
@code{install-r6rs!} before calling user code.  R6RS users probably want
to pass this argument to their Guile.

@node R6RS Standard Libraries
@subsection R6RS Standard Libraries

In contrast with earlier versions of the Revised Report, the R6RS 
organizes the procedures and syntactic forms required of conforming
implementations into a set of ``standard libraries'' which can be
imported as necessary by user programs and libraries.  Here we briefly 
list the libraries that have been implemented for Guile.

We do not attempt to document these libraries fully here, as most of 
their functionality is already available in Guile itself.  The 
expectation is that most Guile users will use the well-known and 
well-documented Guile modules.  These R6RS libraries are mostly useful
to users who want to port their code to other R6RS systems.

The documentation in the following sections reproduces some of the 
content of the library section of the Report, but is mostly intended to
provide supplementary information about Guile's implementation of the
R6RS standard libraries.  For complete documentation, design rationales
and further examples, we advise you to consult the ``Standard 
Libraries'' section of the Report (@pxref{Standard Libraries,
R6RS Standard Libraries,, r6rs, The Revised^6 Report on the Algorithmic
Language Scheme}).

@menu
* Library Usage::               What to know about Guile's library support.
* rnrs base::                   The base library.
* rnrs unicode::                Access to Unicode operations.
* rnrs bytevectors::            Functions for working with binary data.
* rnrs lists::                  List utilities.
* rnrs sorting::                Sorting for lists and vectors.
* rnrs control::                Additional control structures.

* R6RS Records::                A note about R6RS records.
* rnrs records syntactic::      Syntactic API for R6RS records.
* rnrs records procedural::     Procedural API for R6RS records.
* rnrs records inspection::     Reflection on R6RS records.

* rnrs exceptions::             Handling exceptional situations.
* rnrs conditions::             Data structures for exceptions.

* R6RS I/O Conditions::         Predefined I/O error types.
* R6RS Transcoders::            Characters and bytes.
* rnrs io ports::               Support for port-based I/O.
* R6RS File Ports::             Working with files.
* rnrs io simple::              High-level I/O API.

* rnrs files::                  Functions for working with files.
* rnrs programs::               Functions for working with processes.
* rnrs arithmetic fixnums::     Fixed-precision arithmetic operations.
* rnrs arithmetic flonums::     Floating-point arithmetic operations.
* rnrs arithmetic bitwise::     Exact bitwise arithmetic operations.
* rnrs syntax-case::            Support for `syntax-case' macros.
* rnrs hashtables::             Hashtables.
* rnrs enums::                  Enumerations.
* rnrs::                        The composite library.
* rnrs eval::                   Support for on-the-fly evaluation.
* rnrs mutable-pairs::          Support for mutable pairs.
* rnrs mutable-strings::        Support for mutable strings.
* rnrs r5rs::                   Compatibility layer for R5RS Scheme.

@end menu

@node Library Usage
@subsubsection Library Usage

Guile implements the R6RS `library' form as a transformation to a native
Guile module definition.  As a consequence of this, all of the libraries
described in the following subsections, in addition to being available
for use by R6RS libraries and top-level programs, can also be imported 
as if they were normal Guile modules---via a @code{use-modules} form, 
say.  For example, the R6RS ``composite'' library can be imported by:

@lisp
  (import (rnrs (6)))
@end lisp

@lisp
  (use-modules ((rnrs) :version (6)))
@end lisp

For more information on Guile's library implementation, see 
(@pxref{R6RS Libraries}).

@node rnrs base
@subsubsection rnrs base

The @code{(rnrs base (6))} library exports the procedures and syntactic
forms described in the main section of the Report 
(@pxref{Base library, R6RS Base library,, r6rs, 
The Revised^6 Report on the Algorithmic Language Scheme}).  They are
grouped below by the existing manual sections to which they correspond.

@deffn {Scheme Procedure} boolean? obj
@deffnx {Scheme Procedure} not x
@xref{Booleans}, for documentation.
@end deffn

@deffn {Scheme Procedure} symbol? obj
@deffnx {Scheme Procedure} symbol->string sym
@deffnx {Scheme Procedure} string->symbol str
@xref{Symbol Primitives}, for documentation.
@end deffn

@deffn {Scheme Procedure} char? obj
@deffnx {Scheme Procedure} char=? 
@deffnx {Scheme Procedure} char<? 
@deffnx {Scheme Procedure} char>? 
@deffnx {Scheme Procedure} char<=? 
@deffnx {Scheme Procedure} char>=?
@deffnx {Scheme Procedure} integer->char n
@deffnx {Scheme Procedure} char->integer chr
@xref{Characters}, for documentation.
@end deffn

@deffn {Scheme Procedure} list? x
@deffnx {Scheme Procedure} null? x
@xref{List Predicates}, for documentation.
@end deffn

@deffn {Scheme Procedure} pair? x
@deffnx {Scheme Procedure} cons x y
@deffnx {Scheme Procedure} car pair
@deffnx {Scheme Procedure} cdr pair
@deffnx {Scheme Procedure} caar pair
@deffnx {Scheme Procedure} cadr pair
@deffnx {Scheme Procedure} cdar pair
@deffnx {Scheme Procedure} cddr pair
@deffnx {Scheme Procedure} caaar pair
@deffnx {Scheme Procedure} caadr pair
@deffnx {Scheme Procedure} cadar pair
@deffnx {Scheme Procedure} cdaar pair
@deffnx {Scheme Procedure} caddr pair
@deffnx {Scheme Procedure} cdadr pair
@deffnx {Scheme Procedure} cddar pair
@deffnx {Scheme Procedure} cdddr pair
@deffnx {Scheme Procedure} caaaar pair
@deffnx {Scheme Procedure} caaadr pair
@deffnx {Scheme Procedure} caadar pair
@deffnx {Scheme Procedure} cadaar pair
@deffnx {Scheme Procedure} cdaaar pair
@deffnx {Scheme Procedure} cddaar pair
@deffnx {Scheme Procedure} cdadar pair
@deffnx {Scheme Procedure} cdaadr pair
@deffnx {Scheme Procedure} cadadr pair
@deffnx {Scheme Procedure} caaddr pair
@deffnx {Scheme Procedure} caddar pair
@deffnx {Scheme Procedure} cadddr pair
@deffnx {Scheme Procedure} cdaddr pair
@deffnx {Scheme Procedure} cddadr pair
@deffnx {Scheme Procedure} cdddar pair
@deffnx {Scheme Procedure} cddddr pair
@xref{Pairs}, for documentation.
@end deffn

@deffn {Scheme Procedure} number? obj
@xref{Numerical Tower}, for documentation.
@end deffn

@deffn {Scheme Procedure} string? obj
@xref{String Predicates}, for documentation.
@end deffn

@deffn {Scheme Procedure} procedure? obj
@xref{Procedure Properties}, for documentation.
@end deffn

@deffn {Scheme Syntax} define name value
@deffnx {Scheme Syntax} set! variable-name value
@xref{Definition}, for documentation.
@end deffn

@deffn {Scheme Syntax} define-syntax keyword expression
@deffnx {Scheme Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
@deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
@xref{Defining Macros}, for documentation.
@end deffn

@deffn {Scheme Syntax} identifier-syntax exp
@xref{Identifier Macros}, for documentation.
@end deffn

@deffn {Scheme Syntax} syntax-rules literals (pattern template) ...
@xref{Syntax Rules}, for documentation.
@end deffn

@deffn {Scheme Syntax} lambda formals body
@xref{Lambda}, for documentation.
@end deffn

@deffn {Scheme Syntax} let bindings body
@deffnx {Scheme Syntax} let* bindings body
@deffnx {Scheme Syntax} letrec bindings body
@deffnx {Scheme Syntax} letrec* bindings body
@xref{Local Bindings}, for documentation.
@end deffn

@deffn {Scheme Syntax} let-values bindings body
@deffnx {Scheme Syntax} let*-values bindings body
@xref{SRFI-11}, for documentation.
@end deffn

@deffn {Scheme Syntax} begin expr1 expr2 ...
@xref{begin}, for documentation.
@end deffn

@deffn {Scheme Syntax} quote expr
@deffnx {Scheme Syntax} quasiquote expr
@deffnx {Scheme Syntax} unquote expr
@deffnx {Scheme Syntax} unquote-splicing expr
@xref{Expression Syntax}, for documentation.
@end deffn
	 
@deffn {Scheme Syntax} if test consequence [alternate]
@deffnx {Scheme Syntax} cond clause1 clause2 ...
@deffnx {Scheme Syntax} case key clause1 clause2 ...
@xref{Conditionals}, for documentation.
@end deffn

@deffn {Scheme Syntax} and expr ...
@deffnx {Scheme Syntax} or expr ...
@xref{and or}, for documentation.
@end deffn

@deffn {Scheme Procedure} eq? x y
@deffnx {Scheme Procedure} eqv? x y
@deffnx {Scheme Procedure} equal? x y
@deffnx {Scheme Procedure} symbol=? symbol1 symbol2 ...
@xref{Equality}, for documentation.

@code{symbol=?} is identical to @code{eq?}.
@end deffn

@deffn {Scheme Procedure} complex? z
@xref{Complex Numbers}, for documentation.
@end deffn

@deffn {Scheme Procedure} real-part z
@deffnx {Scheme Procedure} imag-part z
@deffnx {Scheme Procedure} make-rectangular real_part imaginary_part
@deffnx {Scheme Procedure} make-polar x y
@deffnx {Scheme Procedure} magnitude z
@deffnx {Scheme Procedure} angle z
@xref{Complex}, for documentation.
@end deffn

@deffn {Scheme Procedure} sqrt z
@deffnx {Scheme Procedure} exp z
@deffnx {Scheme Procedure} expt z1 z2
@deffnx {Scheme Procedure} log z
@deffnx {Scheme Procedure} sin z
@deffnx {Scheme Procedure} cos z
@deffnx {Scheme Procedure} tan z
@deffnx {Scheme Procedure} asin z
@deffnx {Scheme Procedure} acos z
@deffnx {Scheme Procedure} atan z
@xref{Scientific}, for documentation.
@end deffn

@deffn {Scheme Procedure} real? x
@deffnx {Scheme Procedure} rational? x
@deffnx {Scheme Procedure} numerator x
@deffnx {Scheme Procedure} denominator x
@deffnx {Scheme Procedure} rationalize x eps
@xref{Reals and Rationals}, for documentation.
@end deffn
	 
@deffn {Scheme Procedure} exact? x
@deffnx {Scheme Procedure} inexact? x
@deffnx {Scheme Procedure} exact z
@deffnx {Scheme Procedure} inexact z
@xref{Exactness}, for documentation.  The @code{exact} and 
@code{inexact} procedures are identical to the @code{inexact->exact} and
@code{exact->inexact} procedures provided by Guile's code library.
@end deffn

@deffn {Scheme Procedure} integer? x
@xref{Integers}, for documentation.
@end deffn

@deffn {Scheme Procedure} odd? n
@deffnx {Scheme Procedure} even? n
@deffnx {Scheme Procedure} gcd x ...
@deffnx {Scheme Procedure} lcm x ...
@deffnx {Scheme Procedure} exact-integer-sqrt k
@xref{Integer Operations}, for documentation.
@end deffn

@deffn {Scheme Procedure} =
@deffnx {Scheme Procedure} < 
@deffnx {Scheme Procedure} >
@deffnx {Scheme Procedure} <= 
@deffnx {Scheme Procedure} >=
@deffnx {Scheme Procedure} zero? x
@deffnx {Scheme Procedure} positive? x
@deffnx {Scheme Procedure} negative? x
@xref{Comparison}, for documentation.
@end deffn

@deffn {Scheme Procedure} for-each f lst1 lst2 ...
@xref{SRFI-1 Fold and Map}, for documentation.
@end deffn

@deffn {Scheme Procedure} list elem @dots{}
@xref{List Constructors}, for documentation.
@end deffn

@deffn {Scheme Procedure} length lst
@deffnx {Scheme Procedure} list-ref lst k
@deffnx {Scheme Procedure} list-tail lst k
@xref{List Selection}, for documentation.
@end deffn

@deffn {Scheme Procedure} append lst @dots{} obj
@deffnx {Scheme Procedure} append
@deffnx {Scheme Procedure} reverse lst
@xref{Append/Reverse}, for documentation.
@end deffn

@deffn {Scheme Procedure} number->string n [radix]
@deffnx {Scheme Procedure} string->number str [radix]
@xref{Conversion}, for documentation.
@end deffn

@deffn {Scheme Procedure} string char ...
@deffnx {Scheme Procedure} make-string k [chr]
@deffnx {Scheme Procedure} list->string lst
@xref{String Constructors}, for documentation.
@end deffn

@deffn {Scheme Procedure} string->list str [start [end]]
@xref{List/String Conversion}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-length str
@deffnx {Scheme Procedure} string-ref str k
@deffnx {Scheme Procedure} string-copy str [start [end]]
@deffnx {Scheme Procedure} substring str start [end]
@xref{String Selection}, for documentation.
@end deffn

@deffn {Scheme Procedure} string=? s1 s2 s3 @dots{}
@deffnx {Scheme Procedure} string<? s1 s2 s3 @dots{}
@deffnx {Scheme Procedure} string>? s1 s2 s3 @dots{}
@deffnx {Scheme Procedure} string<=? s1 s2 s3 @dots{}
@deffnx {Scheme Procedure} string>=? s1 s2 s3 @dots{}
@xref{String Comparison}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-append arg @dots{}
@xref{Reversing and Appending Strings}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-for-each proc s [start [end]]
@xref{Mapping Folding and Unfolding}, for documentation.
@end deffn

@deffn {Scheme Procedure} + z1 ...
@deffnx {Scheme Procedure} - z1 z2 ...
@deffnx {Scheme Procedure} * z1 ...
@deffnx {Scheme Procedure} / z1 z2 ...
@deffnx {Scheme Procedure} max x1 x2 ...
@deffnx {Scheme Procedure} min x1 x2 ...
@deffnx {Scheme Procedure} abs x
@deffnx {Scheme Procedure} truncate x
@deffnx {Scheme Procedure} floor x
@deffnx {Scheme Procedure} ceiling x
@deffnx {Scheme Procedure} round x
@xref{Arithmetic}, for documentation.
@end deffn

@rnindex div
@rnindex mod
@rnindex div-and-mod
@deffn {Scheme Procedure} div x y
@deffnx {Scheme Procedure} mod x y
@deffnx {Scheme Procedure} div-and-mod x y
These procedures accept two real numbers @var{x} and @var{y}, where the
divisor @var{y} must be non-zero.  @code{div} returns the integer @var{q}
and @code{mod} returns the real number @var{r} such that
@math{@var{x} = @var{q}*@var{y} + @var{r}} and @math{0 <= @var{r} < abs(@var{y})}.
@code{div-and-mod} returns both @var{q} and @var{r}, and is more
efficient than computing each separately.  Note that when @math{@var{y} > 0},
@code{div} returns @math{floor(@var{x}/@var{y})}, otherwise
it returns @math{ceiling(@var{x}/@var{y})}.

@lisp
(div 123 10) @result{} 12
(mod 123 10) @result{} 3
(div-and-mod 123 10) @result{} 12 and 3
(div-and-mod 123 -10) @result{} -12 and 3
(div-and-mod -123 10) @result{} -13 and 7
(div-and-mod -123 -10) @result{} 13 and 7
(div-and-mod -123.2 -63.5) @result{} 2.0 and 3.8
(div-and-mod 16/3 -10/7) @result{} -3 and 22/21
@end lisp
@end deffn

@rnindex div0
@rnindex mod0
@rnindex div0-and-mod0
@deffn {Scheme Procedure} div0 x y
@deffnx {Scheme Procedure} mod0 x y
@deffnx {Scheme Procedure} div0-and-mod0 x y
These procedures accept two real numbers @var{x} and @var{y}, where the
divisor @var{y} must be non-zero.  @code{div0} returns the
integer @var{q} and @code{mod0} returns the real number
@var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
@math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}.  @code{div0-and-mod0}
returns both @var{q} and @var{r}, and is more efficient than computing
each separately.

Note that @code{div0} returns @math{@var{x}/@var{y}} rounded to the
nearest integer.  When @math{@var{x}/@var{y}} lies exactly half-way
between two integers, the tie is broken according to the sign of
@var{y}.  If @math{@var{y} > 0}, ties are rounded toward positive
infinity, otherwise they are rounded toward negative infinity.
This is a consequence of the requirement that
@math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}.

@lisp
(div0 123 10) @result{} 12
(mod0 123 10) @result{} 3
(div0-and-mod0 123 10) @result{} 12 and 3
(div0-and-mod0 123 -10) @result{} -12 and 3
(div0-and-mod0 -123 10) @result{} -12 and -3
(div0-and-mod0 -123 -10) @result{} 12 and -3
(div0-and-mod0 -123.2 -63.5) @result{} 2.0 and 3.8
(div0-and-mod0 16/3 -10/7) @result{} -4 and -8/21
@end lisp
@end deffn

@deffn {Scheme Procedure} real-valued? obj
@deffnx {Scheme Procedure} rational-valued? obj
@deffnx {Scheme Procedure} integer-valued? obj
These procedures return @code{#t} if and only if their arguments can,
respectively, be coerced to a real, rational, or integer value without a
loss of numerical precision. 

@code{real-valued?} will return @code{#t} for complex numbers whose 
imaginary parts are zero.
@end deffn

@deffn {Scheme Procedure} nan? x
@deffnx {Scheme Procedure} infinite? x
@deffnx {Scheme Procedure} finite? x
@code{nan?} returns @code{#t} if @var{x} is a NaN value, @code{#f}
otherwise.  @code{infinite?} returns @code{#t} if @var{x} is an infinite
value, @code{#f} otherwise.  @code{finite?} returns @code{#t} if @var{x}
is neither infinite nor a NaN value, otherwise it returns @code{#f}.
Every real number satisfies exactly one of these predicates.  An
exception is raised if @var{x} is not real.
@end deffn

@deffn {Scheme Syntax} assert expr 
Raises an @code{&assertion} condition if @var{expr} evaluates to 
@code{#f}; otherwise evaluates to the value of @var{expr}.
@end deffn

@deffn {Scheme Procedure} error who message irritant1 ...
@deffnx {Scheme Procedure} assertion-violation who message irritant1 ...
These procedures raise compound conditions based on their arguments:
If @var{who} is not @code{#f}, the condition will include a @code{&who}
condition whose @code{who} field is set to @var{who}; a @code{&message}
condition will be included with a @code{message} field equal to 
@var{message}; an @code{&irritants} condition will be included with its
@code{irritants} list given by @code{irritant1 ...}.

@code{error} produces a compound condition with the simple conditions
described above, as well as an @code{&error} condition;
@code{assertion-violation} produces one that includes an 
@code{&assertion} condition.
@end deffn

@deffn {Scheme Procedure} vector-map proc v
@deffnx {Scheme Procedure} vector-for-each proc v
These procedures implement the @code{map} and @code{for-each} contracts
over vectors.
@end deffn

@deffn {Scheme Procedure} vector arg @dots{}
@deffnx {Scheme Procedure} vector? obj
@deffnx {Scheme Procedure} make-vector len
@deffnx {Scheme Procedure} make-vector len fill
@deffnx {Scheme Procedure} list->vector l
@deffnx {Scheme Procedure} vector->list v
@xref{Vector Creation}, for documentation.
@end deffn

@deffn {Scheme Procedure} vector-length vector
@deffnx {Scheme Procedure} vector-ref vector k
@deffnx {Scheme Procedure} vector-set! vector k obj
@deffnx {Scheme Procedure} vector-fill! v fill
@xref{Vector Accessors}, for documentation.
@end deffn

@deffn {Scheme Procedure} call-with-current-continuation proc
@deffnx {Scheme Procedure} call/cc proc
@xref{Continuations}, for documentation.
@end deffn

@deffn {Scheme Procedure} values arg @dots{}
@deffnx {Scheme Procedure} call-with-values producer consumer
@xref{Multiple Values}, for documentation.
@end deffn

@deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
@xref{Dynamic Wind}, for documentation.
@end deffn

@deffn {Scheme Procedure} apply proc arg @dots{} arglst
@xref{Fly Evaluation}, for documentation.
@end deffn

@node rnrs unicode
@subsubsection rnrs unicode

The @code{(rnrs unicode (6))} library provides procedures for 
manipulating Unicode characters and strings.

@deffn {Scheme Procedure} char-upcase char
@deffnx {Scheme Procedure} char-downcase char
@deffnx {Scheme Procedure} char-titlecase char
@deffnx {Scheme Procedure} char-foldcase char
These procedures translate their arguments from one Unicode character
set to another.  @code{char-upcase}, @code{char-downcase}, and
@code{char-titlecase} are identical to their counterparts in the
Guile core library; @xref{Characters}, for documentation.

@code{char-foldcase} returns the result of applying @code{char-upcase}
to its argument, followed by @code{char-downcase}---except in the case
of the Turkic characters @code{U+0130} and @code{U+0131}, for which the
procedure acts as the identity function.
@end deffn

@deffn {Scheme Procedure} char-ci=? char1 char2 char3 ...
@deffnx {Scheme Procedure} char-ci<? char1 char2 char3 ...
@deffnx {Scheme Procedure} char-ci>? char1 char2 char3 ...
@deffnx {Scheme Procedure} char-ci<=? char1 char2 char3 ...
@deffnx {Scheme Procedure} char-ci>=? char1 char2 char3 ...
These procedures facilitate case-insensitive comparison of Unicode
characters.  They are identical to the procedures provided by Guile's
core library.  @xref{Characters}, for documentation.
@end deffn

@deffn {Scheme Procedure} char-alphabetic? char
@deffnx {Scheme Procedure} char-numeric? char
@deffnx {Scheme Procedure} char-whitespace? char
@deffnx {Scheme Procedure} char-upper-case? char
@deffnx {Scheme Procedure} char-lower-case? char
@deffnx {Scheme Procedure} char-title-case? char
These procedures implement various Unicode character set predicates.  
They are identical to the procedures provided by Guile's core library.
@xref{Characters}, for documentation.
@end deffn

@deffn {Scheme Procedure} char-general-category char
@xref{Characters}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-upcase string
@deffnx {Scheme Procedure} string-downcase string
@deffnx {Scheme Procedure} string-titlecase string
@deffnx {Scheme Procedure} string-foldcase string
These procedures perform Unicode case folding operations on their input.
@xref{Alphabetic Case Mapping}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-ci=? string1 string2 string3 ...
@deffnx {Scheme Procedure} string-ci<? string1 string2 string3 ...
@deffnx {Scheme Procedure} string-ci>? string1 string2 string3 ...
@deffnx {Scheme Procedure} string-ci<=? string1 string2 string3 ...
@deffnx {Scheme Procedure} string-ci>=? string1 string2 string3 ...
These procedures perform case-insensitive comparison on their input.
@xref{String Comparison}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-normalize-nfd string
@deffnx {Scheme Procedure} string-normalize-nfkd string
@deffnx {Scheme Procedure} string-normalize-nfc string
@deffnx {Scheme Procedure} string-normalize-nfkc string
These procedures perform Unicode string normalization operations on 
their input.  @xref{String Comparison}, for documentation.
@end deffn

@node rnrs bytevectors
@subsubsection rnrs bytevectors

The @code{(rnrs bytevectors (6))} library provides procedures for 
working with blocks of binary data.  This functionality is documented
in its own section of the manual; @xref{Bytevectors}.

@node rnrs lists
@subsubsection rnrs lists

The @code{(rnrs lists (6))} library provides procedures additional
procedures for working with lists.

@deffn {Scheme Procedure} find proc list
This procedure is identical to the one defined in Guile's SRFI-1
implementation.  @xref{SRFI-1 Searching}, for documentation.
@end deffn

@deffn {Scheme Procedure} for-all proc list1 list2 ...
@deffnx {Scheme Procedure} exists proc list1 list2 ...

The @code{for-all} procedure is identical to the @code{every} procedure
defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's 
@code{any}.  @xref{SRFI-1 Searching}, for documentation.
@end deffn

@deffn {Scheme Procedure} filter proc list
@deffnx {Scheme Procedure} partition proc list
These procedures are identical to the ones provided by SRFI-1.  
@xref{List Modification}, for a description of @code{filter};
@xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
@end deffn

@deffn {Scheme Procedure} fold-right combine nil list1 list2 @dots{}
This procedure is identical the @code{fold-right} procedure provided by
SRFI-1.  @xref{SRFI-1 Fold and Map}, for documentation.
@end deffn

@deffn {Scheme Procedure} fold-left combine nil list1 list2 @dots{}
This procedure is like @code{fold} from SRFI-1, but @var{combine} is
called with the seed as the first argument.  @xref{SRFI-1 Fold and Map},
for documentation.
@end deffn

@deffn {Scheme Procedure} remp proc list
@deffnx {Scheme Procedure} remove obj list
@deffnx {Scheme Procedure} remv obj list
@deffnx {Scheme Procedure} remq obj list
@code{remove}, @code{remv}, and @code{remq} are identical to the
@code{delete}, @code{delv}, and @code{delq} procedures provided by
Guile's core library, (@pxref{List Modification}).  @code{remp} is
identical to the alternate @code{remove} procedure provided by SRFI-1;
@xref{SRFI-1 Deleting}.
@end deffn

@deffn {Scheme Procedure} memp proc list
@deffnx {Scheme Procedure} member obj list
@deffnx {Scheme Procedure} memv obj list
@deffnx {Scheme Procedure} memq obj list
@code{member}, @code{memv}, and @code{memq} are identical to the 
procedures provided by Guile's core library; @xref{List Searching}, 
for their documentation.  @code{memp} uses the specified predicate
function @code{proc} to test elements of the list @var{list}---it 
behaves similarly to @code{find}, except that it returns the first 
sublist of @var{list} whose @code{car} satisfies @var{proc}.
@end deffn

@deffn {Scheme Procedure} assp proc alist
@deffnx {Scheme Procedure} assoc obj alist
@deffnx {Scheme Procedure} assv obj alist
@deffnx {Scheme Procedure} assq obj alist
@code{assoc}, @code{assv}, and @code{assq} are identical to the 
procedures provided by Guile's core library; 
@xref{Alist Key Equality}, for their documentation.  @code{assp} uses
the specified predicate function @code{proc} to test keys in the
association list @var{alist}.
@end deffn

@deffn {Scheme Procedure} cons* obj1 ... obj
@deffnx {Scheme Procedure} cons* obj
This procedure is identical to the one exported by Guile's core
library.  @xref{List Constructors}, for documentation.
@end deffn

@node rnrs sorting
@subsubsection rnrs sorting

The @code{(rnrs sorting (6))} library provides procedures for sorting
lists and vectors.

@deffn {Scheme Procedure} list-sort proc list
@deffnx {Scheme Procedure} vector-sort proc vector
These procedures return their input sorted in ascending order, without
modifying the original data.  @var{proc} must be a procedure that takes
two elements from the input list or vector as arguments, and returns a
true value if the first is ``less'' than the second, @code{#f} 
otherwise.  @code{list-sort} returns a list; @code{vector-sort} returns 
a vector.

Both @code{list-sort} and @code{vector-sort} are implemented in terms of
the @code{stable-sort} procedure from Guile's core library.  
@xref{Sorting}, for a discussion of the behavior of that procedure.
@end deffn

@deffn {Scheme Procedure} vector-sort! proc vector
Performs a destructive, ``in-place'' sort of @var{vector}, using 
@var{proc} as described above to determine an ascending ordering of
elements.  @code{vector-sort!} returns an unspecified value.

This procedure is implemented in terms of the @code{sort!} procedure
from Guile's core library.  @xref{Sorting}, for more information.
@end deffn

@node rnrs control
@subsubsection rnrs control

The @code{(rnrs control (6))} library provides syntactic forms useful 
for constructing conditional expressions and controlling the flow of
execution.

@deffn {Scheme Syntax} when test expression1 expression2 ...
@deffnx {Scheme Syntax} unless test expression1 expression2 ...
The @code{when} form is evaluated by evaluating the specified @var{test}
expression; if the result is a true value, the @var{expression}s that
follow it are evaluated in order, and the value of the final 
@var{expression} becomes the value of the entire @code{when} expression.

The @code{unless} form behaves similarly, with the exception that the 
specified @var{expression}s are only evaluated if the value of 
@var{test} is false.
@end deffn

@deffn {Scheme Syntax} do ((variable init step) ...) (test expression ...) command ...
This form is identical to the one provided by Guile's core library.
@xref{while do}, for documentation.
@end deffn

@deffn {Scheme Syntax} case-lambda clause ...
This form is identical to the one provided by Guile's core library.
@xref{Case-lambda}, for documentation.
@end deffn

@node R6RS Records
@subsubsection R6RS Records

The manual sections below describe Guile's implementation of R6RS
records, which provide support for user-defined data types.  The R6RS
records API provides a superset of the features provided by Guile's
``native'' records, as well as those of the SRFI-9 records API;
@xref{Records}, and @ref{SRFI-9 Records}, for a description of those
interfaces.

As with SRFI-9 and Guile's native records, R6RS records are constructed
using a record-type descriptor that specifies attributes like the
record's name, its fields, and the mutability of those fields.

R6RS records extend this framework to support single inheritance via the
specification of a ``parent'' type for a record type at definition time.
Accessors and mutator procedures for the fields of a parent type may be 
applied to records of a subtype of this parent.  A record type may be 
@dfn{sealed}, in which case it cannot be used as the parent of another 
record type.

The inheritance mechanism for record types also informs the process of
initializing the fields of a record and its parents.  Constructor
procedures that generate new instances of a record type are obtained
from a record constructor descriptor, which encapsulates the record-type
descriptor of the record to be constructed along with a @dfn{protocol}
procedure that defines how constructors for record subtypes delegate to
the constructors of their parent types.

A protocol is a procedure used by the record system at construction time
to bind arguments to the fields of the record being constructed.  The 
protocol procedure is passed a procedure @var{n} that accepts the 
arguments required to construct the record's parent type; this 
procedure, when invoked, will return a procedure @var{p} that accepts 
the arguments required to construct a new instance of the record type 
itself and returns a new instance of the record type.

The protocol should in turn return a procedure that uses @var{n} and
@var{p} to initialize the fields of the record type and its parent
type(s).  This procedure will be the constructor returned by 

As a trivial example, consider the hypothetical record type 
@code{pixel}, which encapsulates an x-y location on a screen, and
@code{voxel}, which has @code{pixel} as its parent type and stores an
additional coordinate.  The following protocol produces a constructor
procedure that accepts all three coordinates, uses the first two to 
initialize the fields of @code{pixel}, and binds the third to the single
field of @code{voxel}.

@lisp
  (lambda (n)
    (lambda (x y z)
      (let ((p (n x y)))
        (p z))))
@end lisp

It may be helpful to think of protocols as ``constructor factories''
that produce chains of delegating constructors glued together by the
helper procedure @var{n}.

An R6RS record type may be declared to be @dfn{nongenerative} via the
use of a unique generated or user-supplied symbol---or 
@dfn{uid}---such that subsequent record type declarations with the same
uid and attributes will return the previously-declared record-type 
descriptor.

R6RS record types may also be declared to be @dfn{opaque}, in which case
the various predicates and introspection procedures defined in
@code{(rnrs records introspection)} will behave as if records of this
type are not records at all.

Note that while the R6RS records API shares much of its namespace with
both the SRFI-9 and native Guile records APIs, it is not currently
compatible with either.

@node rnrs records syntactic
@subsubsection rnrs records syntactic

The @code{(rnrs records syntactic (6))} library exports the syntactic
API for working with R6RS records.

@deffn {Scheme Syntax} define-record-type name-spec record-clause @dots{}
Defines a new record type, introducing bindings for a record-type
descriptor, a record constructor descriptor, a constructor procedure,
a record predicate, and accessor and mutator procedures for the new
record type's fields.

@var{name-spec} must either be an identifier or must take the form
@code{(record-name constructor-name predicate-name)}, where 
@var{record-name}, @var{constructor-name}, and @var{predicate-name} are
all identifiers and specify the names to which, respectively, the 
record-type descriptor, constructor, and predicate procedures will be
bound.  If @var{name-spec} is only an identifier, it specifies the name
to which the generated record-type descriptor will be bound.

Each @var{record-clause} must be one of the following:

@itemize @bullet
@item
@code{(fields field-spec*)}, where each @var{field-spec} specifies a
field of the new record type and takes one of the following forms:
@itemize @bullet
@item
@code{(immutable field-name accessor-name)}, which specifies an 
immutable field with the name @var{field-name} and binds an accessor 
procedure for it to the name given by @var{accessor-name}
@item
@code{(mutable field-name accessor-name mutator-name)}, which specifies
a mutable field with the name @var{field-name} and binds accessor and 
mutator procedures to @var{accessor-name} and @var{mutator-name},
respectively
@item
@code{(immutable field-name)}, which specifies an immutable field with
the name @var{field-name}; an accessor procedure for it will be created
and named by appending record name and @var{field-name} with a hyphen
separator
@item
@code{(mutable field-name}), which specifies a mutable field with the
name @var{field-name}; an accessor procedure for it will be created and
named as described above; a mutator procedure will also be created and
named by appending @code{-set!} to the accessor name
@item
@code{field-name}, which specifies an immutable field with the name
@var{field-name}; an access procedure for it will be created and named
as described above
@end itemize
@item
@code{(parent parent-name)}, where @var{parent-name} is a symbol giving
the name of the record type to be used as the parent of the new record
type
@item
@code{(protocol expression)}, where @var{expression} evaluates to a
protocol procedure which behaves as described above, and is used to
create a record constructor descriptor for the new record type
@item
@code{(sealed sealed?)}, where @var{sealed?} is a boolean value that
specifies whether or not the new record type is sealed
@item
@code{(opaque opaque?)}, where @var{opaque?} is a boolean value that
specifies whether or not the new record type is opaque
@item
@code{(nongenerative [uid])}, which specifies that the record type is
nongenerative via the optional uid @var{uid}.  If @var{uid} is not 
specified, a unique uid will be generated at expansion time
@item
@code{(parent-rtd parent-rtd parent-cd)}, a more explicit form of the
@code{parent} form above; @var{parent-rtd} and @var{parent-cd} should
evaluate to a record-type descriptor and a record constructor 
descriptor, respectively
@end itemize
@end deffn

@deffn {Scheme Syntax} record-type-descriptor record-name
Evaluates to the record-type descriptor associated with the type
specified by @var{record-name}.
@end deffn

@deffn {Scheme Syntax} record-constructor-descriptor record-name
Evaluates to the record-constructor descriptor associated with the type
specified by @var{record-name}.
@end deffn

@node rnrs records procedural
@subsubsection rnrs records procedural

The @code{(rnrs records procedural (6))} library exports the procedural
API for working with R6RS records.

@deffn {Scheme Procedure} make-record-type-descriptor name parent uid sealed? opaque? fields
Returns a new record-type descriptor with the specified characteristics:
@var{name} must be a symbol giving the name of the new record type; 
@var{parent} must be either @code{#f} or a non-sealed record-type 
descriptor for the returned record type to extend; @var{uid} must be
either @code{#f}, indicating that the record type is generative, or 
a symbol giving the type's nongenerative uid; @var{sealed?} and  
@var{opaque?} must be boolean values that specify the sealedness and
opaqueness of the record type; @var{fields} must be a vector of zero or
more field specifiers of the form @code{(mutable name)} or
@code{(immutable name)}, where name is a symbol giving a name for the
field.

If @var{uid} is not @code{#f}, it must be a symbol
@end deffn

@deffn {Scheme Procedure} record-type-descriptor? obj
Returns @code{#t} if @var{obj} is a record-type descriptor, @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} make-record-constructor-descriptor rtd parent-constructor-descriptor protocol
Returns a new record constructor descriptor that can be used to produce
constructors for the record type specified by the record-type descriptor
@var{rtd} and whose delegation and binding behavior are specified by the
protocol procedure @var{protocol}.

@var{parent-constructor-descriptor} specifies a record constructor 
descriptor for the parent type of @var{rtd}, if one exists.  If 
@var{rtd} represents a base type, then 
@var{parent-constructor-descriptor} must be @code{#f}.  If @var{rtd}
is an extension of another type, @var{parent-constructor-descriptor} may
still be @code{#f}, but protocol must also be @code{#f} in this case.
@end deffn

@deffn {Scheme Procedure} record-constructor rcd
Returns a record constructor procedure by invoking the protocol
defined by the record-constructor descriptor @var{rcd}.
@end deffn

@deffn {Scheme Procedure} record-predicate rtd
Returns the record predicate procedure for the record-type descriptor
@var{rtd}.
@end deffn 

@deffn {Scheme Procedure} record-accessor rtd k
Returns the record field accessor procedure for the @var{k}th field of
the record-type descriptor @var{rtd}.
@end deffn

@deffn {Scheme Procedure} record-mutator rtd k
Returns the record field mutator procedure for the @var{k}th field of
the record-type descriptor @var{rtd}.  An @code{&assertion} condition
will be raised if this field is not mutable.
@end deffn

@node rnrs records inspection
@subsubsection rnrs records inspection

The @code{(rnrs records inspection (6))} library provides procedures
useful for accessing metadata about R6RS records.

@deffn {Scheme Procedure} record? obj
Return @code{#t} if the specified object is a non-opaque R6RS record,
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} record-rtd record
Returns the record-type descriptor for @var{record}.  An
@code{&assertion} is raised if @var{record} is opaque.
@end deffn

@deffn {Scheme Procedure} record-type-name rtd
Returns the name of the record-type descriptor @var{rtd}.
@end deffn

@deffn {Scheme Procedure} record-type-parent rtd
Returns the parent of the record-type descriptor @var{rtd}, or @code{#f}
if it has none.
@end deffn

@deffn {Scheme Procedure} record-type-uid rtd
Returns the uid of the record-type descriptor @var{rtd}, or @code{#f} if
it has none.
@end deffn

@deffn {Scheme Procedure} record-type-generative? rtd
Returns @code{#t} if the record-type descriptor @var{rtd} is generative,
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} record-type-sealed? rtd
Returns @code{#t} if the record-type descriptor @var{rtd} is sealed,
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} record-type-opaque? rtd
Returns @code{#t} if the record-type descriptor @var{rtd} is opaque,
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} record-type-field-names rtd
Returns a vector of symbols giving the names of the fields defined by
the record-type descriptor @var{rtd} (and not any of its sub- or
supertypes).
@end deffn

@deffn {Scheme Procedure} record-field-mutable? rtd k
Returns @code{#t} if the field at index @var{k} of the record-type
descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable.
@end deffn

@node rnrs exceptions
@subsubsection rnrs exceptions

The @code{(rnrs exceptions (6))} library provides functionality related
to signaling and handling exceptional situations.  This functionality
re-exports Guile's core exception-handling primitives.
@xref{Exceptions}, for a full discussion.  @xref{SRFI-34}, for a similar
pre-R6RS facility.  In Guile, SRFI-34, SRFI-35, and R6RS exception
handling are all built on the same core facilities, and so are
interoperable.

@deffn {Scheme Procedure} with-exception-handler handler thunk
@xref{Raising and Handling Exceptions}, for more information on
@code{with-exception-handler}.
@end deffn

@deffn {Scheme Syntax} guard (variable clause1 clause2 ...) body
Evaluates the expression given by @var{body}, first creating an ad hoc 
exception handler that binds a raised exception to @var{variable} and
then evaluates the specified @var{clause}s as if they were part of a 
@code{cond} expression, with the value of the first matching clause 
becoming the value of the @code{guard} expression 
(@pxref{Conditionals}).  If none of the clause's test expressions 
evaluates to @code{#t}, the exception is re-raised, with the exception
handler that was current before the evaluation of the @code{guard} form.

For example, the expression

@lisp
(guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz)) 
  (raise 'bar))
@end lisp

evaluates to @code{baz}.
@end deffn

@deffn {Scheme Procedure} raise obj
Equivalent to core Guile @code{(raise-exception @var{obj})}.
@xref{Raising and Handling Exceptions}.  p(Unfortunately, @code{raise}
is already bound to a different function in core Guile.
@xref{Signals}.)
@end deffn

@deffn {Scheme Procedure} raise-continuable obj
Equivalent to core Guile @code{(raise-exception @var{obj} #:continuable?
#t)}.  @xref{Raising and Handling Exceptions}.
@end deffn


@node rnrs conditions
@subsubsection rnrs conditions

The @code{(rnrs condition (6))} library provides forms and procedures
for constructing new condition types, as well as a library of 
pre-defined condition types that represent a variety of common 
exceptional situations.  Conditions are records of a subtype of the
@code{&condition} record type, which is neither sealed nor opaque.
@xref{R6RS Records}.

Conditions may be manipulated singly, as @dfn{simple conditions}, or 
when composed with other conditions to form @dfn{compound conditions}.
Compound conditions do not ``nest''---constructing a new compound
condition out of existing compound conditions will ``flatten'' them
into their component simple conditions.  For example, making a new
condition out of a @code{&message} condition and a compound condition
that contains an @code{&assertion} condition and another @code{&message} 
condition will produce a compound condition that contains two 
@code{&message} conditions and one @code{&assertion} condition.

The record type predicates and field accessors described below can
operate on either simple or compound conditions.  In the latter case,
the predicate returns @code{#t} if the compound condition contains a
component simple condition of the appropriate type; the field accessors
return the requisite fields from the first component simple condition 
found to be of the appropriate type.

Guile's R6RS layer uses core exception types from the @code{(ice-9
exceptions)} module as the basis for its R6RS condition system.  Guile
prefers to use the term ``exception object'' and ``exception type''
rather than ``condition'' or ``condition type'', but that's just a
naming difference.  Guile also has different names for the types in the
condition hierarchy.  @xref{Exception Objects}, for full details.

This library is quite similar to the SRFI-35 conditions module
(@pxref{SRFI-35}).  Among other minor differences, the @code{(rnrs
conditions)} library features slightly different semantics around
condition field accessors, and comes with a larger number of pre-defined
condition types.  The two APIs are compatible; the @code{condition?}
predicate from one API will return @code{#t} when applied to a condition
object created in the other.   of the condition types are the same,
also.

@deffn {Condition Type} &condition
@deffnx {Scheme Procedure} condition? obj
The base record type for conditions.  Known as @code{&exception} in core
Guile.
@end deffn

@deffn {Scheme Procedure} condition condition1 ...
@deffnx {Scheme Procedure} simple-conditions condition
The @code{condition} procedure creates a new compound condition out of
its condition arguments, flattening any specified compound conditions 
into their component simple conditions as described above.

@code{simple-conditions} returns a list of the component simple 
conditions of the compound condition @code{condition}, in the order in
which they were specified at construction time.
@end deffn

@deffn {Scheme Procedure} condition-predicate rtd
@deffnx {Scheme Procedure} condition-accessor rtd proc
These procedures return condition predicate and accessor procedures for
the specified condition record type @var{rtd}.
@end deffn

@deffn {Scheme Syntax} define-condition-type condition-type supertype constructor predicate field-spec ...
Evaluates to a new record type definition for a condition type with the
name @var{condition-type} that has the condition type @var{supertype} as
its parent.  A default constructor, which binds its arguments to the 
fields of this type and its parent types, will be bound to the 
identifier @var{constructor}; a condition predicate will be bound to
@var{predicate}.  The fields of the new type, which are immutable, are 
specified by the @var{field-spec}s, each of which must be of the form:
@lisp
(field accessor)
@end lisp
where @var{field} gives the name of the field and @var{accessor} gives
the name for a binding to an accessor procedure created for this field.
@end deffn

@deffn {Condition Type} &message
@deffnx {Scheme Procedure} make-message-condition message
@deffnx {Scheme Procedure} message-condition? obj
@deffnx {Scheme Procedure} condition-message condition
A type that includes a message describing the condition that occurred.
@end deffn

@deffn {Condition Type} &warning
@deffnx {Scheme Procedure} make-warning
@deffnx {Scheme Procedure} warning? obj
A base type for representing non-fatal conditions during execution.
@end deffn

@deffn {Condition Type} &serious
@deffnx {Scheme Procedure} make-serious-condition
@deffnx {Scheme Procedure} serious-condition? obj
A base type for conditions representing errors serious enough that
cannot be ignored.  Known as @code{&error} in core Guile.
@end deffn

@deffn {Condition Type} &error
@deffnx {Scheme Procedure} make-error
@deffnx {Scheme Procedure} error? obj
A base type for conditions representing errors.  Known as
@code{&external-error} in core Guile.
@end deffn

@deffn {Condition Type} &violation
@deffnx {Scheme Procedure} make-violation
@deffnx {Scheme Procedure} violation?
A subtype of @code{&serious} that can be used to represent violations of
a language or library standard.  Known as @code{&programming-error} in
core Guile.
@end deffn

@deffn {Condition Type} &assertion
@deffnx {Scheme Procedure} make-assertion-violation
@deffnx {Scheme Procedure} assertion-violation? obj
A subtype of @code{&violation} that indicates an invalid call to a
procedure.  Known as @code{&assertion-failure} in core Guile.
@end deffn

@deffn {Condition Type} &irritants
@deffnx {Scheme Procedure} make-irritants-condition irritants
@deffnx {Scheme Procedure} irritants-condition? obj
@deffnx {Scheme Procedure} condition-irritants condition
A base type used for storing information about the causes of another
condition in a compound condition.
@end deffn

@deffn {Condition Type} &who
@deffnx {Scheme Procedure} make-who-condition who
@deffnx {Scheme Procedure} who-condition? obj
@deffnx {Scheme Procedure} condition-who condition
A base type used for storing the identity, a string or symbol, of the
entity responsible for another condition in a compound condition.
@end deffn

@deffn {Condition Type} &non-continuable
@deffnx {Scheme Procedure} make-non-continuable-violation
@deffnx {Scheme Procedure} non-continuable-violation? obj
A subtype of @code{&violation} used to indicate that an exception 
handler invoked by @code{raise} has returned locally.
@end deffn

@deffn {Condition Type} &implementation-restriction
@deffnx {Scheme Procedure} make-implementation-restriction-violation
@deffnx {Scheme Procedure} implementation-restriction-violation? obj
A subtype of @code{&violation} used to indicate a violation of an
implementation restriction.
@end deffn

@deffn {Condition Type} &lexical
@deffnx {Scheme Procedure} make-lexical-violation
@deffnx {Scheme Procedure} lexical-violation? obj
A subtype of @code{&violation} used to indicate a syntax violation at
the level of the datum syntax.
@end deffn

@deffn {Condition Type} &syntax
@deffnx {Scheme Procedure} make-syntax-violation form subform
@deffnx {Scheme Procedure} syntax-violation? obj
@deffnx {Scheme Procedure} syntax-violation-form condition
@deffnx {Scheme Procedure} syntax-violation-subform condition
A subtype of @code{&violation} that indicates a syntax violation.  The
@var{form} and @var{subform} fields, which must be datum values,
indicate the syntactic form responsible for the condition.
@end deffn

@deffn {Condition Type} &undefined
@deffnx {Scheme Procedure} make-undefined-violation
@deffnx {Scheme Procedure} undefined-violation? obj
A subtype of @code{&violation} that indicates a reference to an unbound
identifier.  Known as @code{&undefined-variable} in core Guile.
@end deffn

@node R6RS I/O Conditions
@subsubsection I/O Conditions

These condition types are exported by both the 
@code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.

@deffn {Condition Type} &i/o
@deffnx {Scheme Procedure} make-i/o-error
@deffnx {Scheme Procedure} i/o-error? obj
A condition supertype for more specific I/O errors.
@end deffn

@deffn {Condition Type} &i/o-read
@deffnx {Scheme Procedure} make-i/o-read-error
@deffnx {Scheme Procedure} i/o-read-error? obj
A subtype of @code{&i/o}; represents read-related I/O errors.
@end deffn

@deffn {Condition Type} &i/o-write
@deffnx {Scheme Procedure} make-i/o-write-error
@deffnx {Scheme Procedure} i/o-write-error? obj
A subtype of @code{&i/o}; represents write-related I/O errors.
@end deffn

@deffn {Condition Type} &i/o-invalid-position
@deffnx {Scheme Procedure} make-i/o-invalid-position-error position
@deffnx {Scheme Procedure} i/o-invalid-position-error? obj
@deffnx {Scheme Procedure} i/o-error-position condition
A subtype of @code{&i/o}; represents an error related to an attempt to
set the file position to an invalid position.
@end deffn

@deffn {Condition Type} &i/o-filename
@deffnx {Scheme Procedure} make-io-filename-error filename
@deffnx {Scheme Procedure} i/o-filename-error? obj
@deffnx {Scheme Procedure} i/o-error-filename condition
A subtype of @code{&i/o}; represents an error related to an operation on
a named file.
@end deffn

@deffn {Condition Type} &i/o-file-protection
@deffnx {Scheme Procedure} make-i/o-file-protection-error filename
@deffnx {Scheme Procedure} i/o-file-protection-error? obj
A subtype of @code{&i/o-filename}; represents an error resulting from an
attempt to access a named file for which the caller had insufficient 
permissions.
@end deffn

@deffn {Condition Type} &i/o-file-is-read-only
@deffnx {Scheme Procedure} make-i/o-file-is-read-only-error filename
@deffnx {Scheme Procedure} i/o-file-is-read-only-error? obj
A subtype of @code{&i/o-file-protection}; represents an error related to
an attempt to write to a read-only file.
@end deffn

@deffn {Condition Type} &i/o-file-already-exists
@deffnx {Scheme Procedure} make-i/o-file-already-exists-error filename
@deffnx {Scheme Procedure} i/o-file-already-exists-error? obj
A subtype of @code{&i/o-filename}; represents an error related to an
operation on an existing file that was assumed not to exist.
@end deffn

@deffn {Condition Type} &i/o-file-does-not-exist
@deffnx {Scheme Procedure} make-i/o-file-does-not-exist-error
@deffnx {Scheme Procedure} i/o-file-does-not-exist-error? obj
A subtype of @code{&i/o-filename}; represents an error related to an
operation on a non-existent file that was assumed to exist.
@end deffn

@deffn {Condition Type} &i/o-port
@deffnx {Scheme Procedure} make-i/o-port-error port
@deffnx {Scheme Procedure} i/o-port-error? obj
@deffnx {Scheme Procedure} i/o-error-port condition
A subtype of @code{&i/o}; represents an error related to an operation on
the port @var{port}.
@end deffn

@node R6RS Transcoders
@subsubsection Transcoders
@cindex codec
@cindex end-of-line style
@cindex transcoder
@cindex binary port
@cindex textual port

The transcoder facilities are exported by @code{(rnrs io ports)}.

Several different Unicode encoding schemes describe standard ways to
encode characters and strings as byte sequences and to decode those
sequences. Within this document, a @dfn{codec} is an immutable Scheme
object that represents a Unicode or similar encoding scheme.

An @dfn{end-of-line style} is a symbol that, if it is not @code{none},
describes how a textual port transcodes representations of line endings.

A @dfn{transcoder} is an immutable Scheme object that combines a codec
with an end-of-line style and a method for handling decoding errors.
Each transcoder represents some specific bidirectional (but not
necessarily lossless), possibly stateful translation between byte
sequences and Unicode characters and strings.  Every transcoder can
operate in the input direction (bytes to characters) or in the output
direction (characters to bytes).  A @var{transcoder} parameter name
means that the corresponding argument must be a transcoder.

A @dfn{binary port} is a port that supports binary I/O, does not have an
associated transcoder and does not support textual I/O.  A @dfn{textual
port} is a port that supports textual I/O, and does not support binary
I/O.  A textual port may or may not have an associated transcoder.

@deffn {Scheme Procedure} latin-1-codec
@deffnx {Scheme Procedure} utf-8-codec
@deffnx {Scheme Procedure} utf-16-codec

These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16
encoding schemes.

A call to any of these procedures returns a value that is equal in the
sense of @code{eqv?} to the result of any other call to the same
procedure.
@end deffn

@deffn {Scheme Syntax} eol-style @var{eol-style-symbol}

@var{eol-style-symbol} should be a symbol whose name is one of
@code{lf}, @code{cr}, @code{crlf}, @code{nel}, @code{crnel}, @code{ls},
and @code{none}.

The form evaluates to the corresponding symbol.  If the name of
@var{eol-style-symbol} is not one of these symbols, the effect and
result are implementation-dependent; in particular, the result may be an
eol-style symbol acceptable as an @var{eol-style} argument to
@code{make-transcoder}.  Otherwise, an exception is raised.

All eol-style symbols except @code{none} describe a specific
line-ending encoding:

@table @code
@item lf
linefeed
@item cr
carriage return
@item crlf
carriage return, linefeed
@item nel
next line
@item crnel
carriage return, next line
@item ls
line separator
@end table

For a textual port with a transcoder, and whose transcoder has an
eol-style symbol @code{none}, no conversion occurs.  For a textual input
port, any eol-style symbol other than @code{none} means that all of the
above line-ending encodings are recognized and are translated into a
single linefeed.  For a textual output port, @code{none} and @code{lf}
are equivalent.  Linefeed characters are encoded according to the
specified eol-style symbol, and all other characters that participate in
possible line endings are encoded as is.

@quotation Note
  Only the name of @var{eol-style-symbol} is significant.
@end quotation
@end deffn

@deffn {Scheme Procedure} native-eol-style
Returns the default end-of-line style of the underlying platform, e.g.,
@code{lf} on Unix and @code{crlf} on Windows.
@end deffn

@deffn {Condition Type} &i/o-decoding
@deffnx {Scheme Procedure} make-i/o-decoding-error  port
@deffnx {Scheme Procedure} i/o-decoding-error?  obj
This condition type could be defined by

@lisp
(define-condition-type &i/o-decoding &i/o-port
  make-i/o-decoding-error i/o-decoding-error?)
@end lisp

An exception with this type is raised when one of the operations for
textual input from a port encounters a sequence of bytes that cannot be
translated into a character or string by the input direction of the
port's transcoder.

When such an exception is raised, the port's position is past the
invalid encoding.
@end deffn

@deffn {Condition Type} &i/o-encoding
@deffnx {Scheme Procedure} make-i/o-encoding-error  port char
@deffnx {Scheme Procedure} i/o-encoding-error?  obj
@deffnx {Scheme Procedure} i/o-encoding-error-char  condition
This condition type could be defined by

@lisp
(define-condition-type &i/o-encoding &i/o-port
  make-i/o-encoding-error i/o-encoding-error?
  (char i/o-encoding-error-char))
@end lisp

An exception with this type is raised when one of the operations for
textual output to a port encounters a character that cannot be
translated into bytes by the output direction of the port's transcoder.
@var{char} is the character that could not be encoded.
@end deffn

@deffn {Scheme Syntax} error-handling-mode @var{error-handling-mode-symbol}
@var{error-handling-mode-symbol} should be a symbol whose name is one of
@code{ignore}, @code{raise}, and @code{replace}. The form evaluates to
the corresponding symbol.  If @var{error-handling-mode-symbol} is not
one of these identifiers, effect and result are
implementation-dependent: The result may be an error-handling-mode
symbol acceptable as a @var{handling-mode} argument to
@code{make-transcoder}.  If it is not acceptable as a
@var{handling-mode} argument to @code{make-transcoder}, an exception is
raised.

@quotation Note
  Only the name of @var{error-handling-mode-symbol} is significant.
@end quotation

The error-handling mode of a transcoder specifies the behavior
of textual I/O operations in the presence of encoding or decoding
errors.

If a textual input operation encounters an invalid or incomplete
character encoding, and the error-handling mode is @code{ignore}, an
appropriate number of bytes of the invalid encoding are ignored and
decoding continues with the following bytes.

If the error-handling mode is @code{replace}, the replacement
character U+FFFD is injected into the data stream, an appropriate
number of bytes are ignored, and decoding
continues with the following bytes.

If the error-handling mode is @code{raise}, an exception with condition
type @code{&i/o-decoding} is raised.

If a textual output operation encounters a character it cannot encode,
and the error-handling mode is @code{ignore}, the character is ignored
and encoding continues with the next character.  If the error-handling
mode is @code{replace}, a codec-specific replacement character is
emitted by the transcoder, and encoding continues with the next
character.  The replacement character is U+FFFD for transcoders whose
codec is one of the Unicode encodings, but is the @code{?}  character
for the Latin-1 encoding.  If the error-handling mode is @code{raise},
an exception with condition type @code{&i/o-encoding} is raised.
@end deffn

@deffn {Scheme Procedure} make-transcoder  codec
@deffnx {Scheme Procedure} make-transcoder codec eol-style
@deffnx {Scheme Procedure} make-transcoder codec eol-style handling-mode
@var{codec} must be a codec; @var{eol-style}, if present, an eol-style
symbol; and @var{handling-mode}, if present, an error-handling-mode
symbol.

@var{eol-style} may be omitted, in which case it defaults to the native
end-of-line style of the underlying platform.  @var{handling-mode} may
be omitted, in which case it defaults to @code{replace}.  The result is
a transcoder with the behavior specified by its arguments.
@end deffn

@deffn {Scheme procedure} native-transcoder
Returns an implementation-dependent transcoder that represents a
possibly locale-dependent ``native'' transcoding.
@end deffn

@deffn {Scheme Procedure} transcoder-codec  transcoder
@deffnx {Scheme Procedure} transcoder-eol-style  transcoder
@deffnx {Scheme Procedure} transcoder-error-handling-mode  transcoder
These are accessors for transcoder objects; when applied to a
transcoder returned by @code{make-transcoder}, they return the
@var{codec}, @var{eol-style}, and @var{handling-mode} arguments,
respectively.
@end deffn

@deffn {Scheme Procedure} bytevector->string  bytevector transcoder
Returns the string that results from transcoding the
@var{bytevector} according to the input direction of the transcoder.
@end deffn

@deffn {Scheme Procedure} string->bytevector  string transcoder
Returns the bytevector that results from transcoding the
@var{string} according to the output direction of the transcoder.
@end deffn

@node rnrs io ports
@subsubsection rnrs io ports

@cindex R6RS
@cindex R6RS ports
Guile's binary and textual port interface was heavily inspired by R6RS,
so many R6RS port interfaces are documented elsewhere.  Note that R6RS
ports are not disjoint from Guile's native ports, so Guile-specific
procedures will work on ports created using the R6RS API, and vice
versa.  Also note that in Guile, all ports are both textual and binary.
@xref{Input and Output}, for more on Guile's core port API.  The R6RS
ports module wraps Guile's I/O routines in a helper that will translate
native Guile exceptions to R6RS conditions; @xref{R6RS I/O Conditions},
for more.  @xref{R6RS File Ports}, for documentation on the R6RS file
port interface.

@c FIXME: Update description when implemented.
@emph{Note}: The implementation of this R6RS API is not complete yet.

@deffn {Scheme Procedure} eof-object? obj
@xref{Binary I/O}, for documentation.
@end deffn

@deffn {Scheme Procedure} eof-object
Return the end-of-file (EOF) object.

@lisp
(eof-object? (eof-object))
@result{} #t
@end lisp
@end deffn

@deffn {Scheme Procedure} port? obj
@deffnx {Scheme Procedure} input-port? obj
@deffnx {Scheme Procedure} output-port? obj
@xref{Ports}, for documentation.
@end deffn

@deffn {Scheme Procedure} port-transcoder port
Return a transcoder associated with the encoding of @var{port}.
@xref{Encoding}, and @xref{R6RS Transcoders}.
@end deffn

@deffn {Scheme Procedure} binary-port? port
Return @code{#t} if @var{port} appears to be a binary port, else return
@code{#f}.  Note that Guile does not currently distinguish between
binary and textual ports, so this predicate is not a reliable indicator
of whether the port was created as a binary port.  Currently, it returns
@code{#t} if and only if the port encoding is ``ISO-8859-1'', because
Guile uses this encoding when creating a binary port.  @xref{Encoding},
for more details.
@end deffn

@deffn {Scheme Procedure} textual-port? port
Return @code{#t} if @var{port} appears to be a textual port, else return
@code{#f}.  Note that Guile does not currently distinguish between
binary and textual ports, so this predicate is not a reliable indicator
of whether the port was created as a textual port.  Currently, it always
returns @code{#t}, because all ports can be used for textual I/O in
Guile.  @xref{Encoding}, for more details.
@end deffn

@deffn {Scheme Procedure} transcoded-port binary-port transcoder
The @code{transcoded-port} procedure
returns a new textual port with the specified @var{transcoder}.
Otherwise the new textual port's state is largely the same as
that of @var{binary-port}.
If @var{binary-port} is an input port, the new textual
port will be an input port and
will transcode the bytes that have not yet been read from
@var{binary-port}.
If @var{binary-port} is an output port, the new textual
port will be an output port and
will transcode output characters into bytes that are
written to the byte sink represented by @var{binary-port}.

As a side effect, however, @code{transcoded-port}
closes @var{binary-port} in
a special way that allows the new textual port to continue to
use the byte source or sink represented by @var{binary-port},
even though @var{binary-port} itself is closed and cannot
be used by the input and output operations described in this
chapter.
@end deffn

@deffn {Scheme Procedure} port-position port
Equivalent to @code{(seek @var{port} SEEK_CUR 0)}.  @xref{Random
Access}.
@end deffn

@deffn {Scheme Procedure} port-has-port-position? port
Return @code{#t} is @var{port} supports @code{port-position}.
@end deffn

@deffn {Scheme Procedure} set-port-position! port offset
Equivalent to @code{(seek @var{port} SEEK_SET @var{offset})}.
@xref{Random Access}.
@end deffn

@deffn {Scheme Procedure} port-has-set-port-position!? port
Return @code{#t} is @var{port} supports @code{set-port-position!}.
@end deffn

@deffn {Scheme Procedure} call-with-port port proc
Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
of @var{proc}.  Return the return values of @var{proc}.
@end deffn

@deffn {Scheme Procedure} port-eof? input-port
Equivalent to @code{(eof-object? (lookahead-u8 @var{input-port}))}.
@end deffn

@deffn {Scheme Procedure} standard-input-port
@deffnx {Scheme Procedure} standard-output-port
@deffnx {Scheme Procedure} standard-error-port
Returns a fresh binary input port connected to standard input, or a
binary output port connected to the standard output or standard error,
respectively.  Whether the port supports the @code{port-position} and
@code{set-port-position!}  operations is implementation-dependent.
@end deffn

@deffn {Scheme Procedure} current-input-port
@deffnx {Scheme Procedure} current-output-port
@deffnx {Scheme Procedure} current-error-port
@xref{Default Ports}.
@end deffn

@deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
@deffnx {Scheme Procedure} open-bytevector-output-port [transcoder]
@xref{Bytevector Ports}.
@end deffn

@deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
@deffnx {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
@deffnx {Scheme Procedure} make-custom-binary-input/output-port id read! write! get-position set-position! close
@xref{Custom Ports}.
@end deffn

@deffn {Scheme Procedure} get-u8 port
@deffnx {Scheme Procedure} lookahead-u8 port
@deffnx {Scheme Procedure} get-bytevector-n port count
@deffnx {Scheme Procedure} get-bytevector-n! port bv start count
@deffnx {Scheme Procedure} get-bytevector-some port
@deffnx {Scheme Procedure} get-bytevector-all port
@deffnx {Scheme Procedure} put-u8 port octet
@deffnx {Scheme Procedure} put-bytevector port bv [start [count]]
@xref{Binary I/O}.
@end deffn

@deffn {Scheme Procedure} get-char textual-input-port
@deffnx {Scheme Procedure} lookahead-char textual-input-port
@deffnx {Scheme Procedure} get-string-n textual-input-port count
@deffnx {Scheme Procedure} get-string-n! textual-input-port string start count
@deffnx {Scheme Procedure} get-string-all textual-input-port
@deffnx {Scheme Procedure} get-line textual-input-port
@deffnx {Scheme Procedure} put-char port char
@deffnx {Scheme Procedure} put-string port string [start [count]]
@xref{Textual I/O}.
@end deffn

@deffn {Scheme Procedure} get-datum textual-input-port count
Reads an external representation from @var{textual-input-port} and returns the
datum it represents.  The @code{get-datum} procedure returns the next
datum that can be parsed from the given @var{textual-input-port}, updating
@var{textual-input-port} to point exactly past the end of the external
representation of the object.

Any @emph{interlexeme space} (comment or whitespace, @pxref{Scheme
Syntax}) in the input is first skipped.  If an end of file occurs after
the interlexeme space, the end-of-file object is returned.

If a character inconsistent with an external representation is
encountered in the input, an exception with condition types
@code{&lexical} and @code{&i/o-read} is raised.  Also, if the end of
file is encountered after the beginning of an external representation,
but the external representation is incomplete and therefore cannot be
parsed, an exception with condition types @code{&lexical} and
@code{&i/o-read} is raised.
@end deffn

@deffn {Scheme Procedure} put-datum textual-output-port datum
@var{datum} should be a datum value.  The @code{put-datum} procedure
writes an external representation of @var{datum} to
@var{textual-output-port}.  The specific external representation is
implementation-dependent.  However, whenever possible, an implementation
should produce a representation for which @code{get-datum}, when reading
the representation, will return an object equal (in the sense of
@code{equal?}) to @var{datum}.

@quotation Note
  Not all datums may allow producing an external representation for which
  @code{get-datum} will produce an object that is equal to the
  original.  Specifically, NaNs contained in @var{datum} may make
  this impossible.
@end quotation

@quotation Note
  The @code{put-datum} procedure merely writes the external
  representation, but no trailing delimiter.  If @code{put-datum} is
  used to write several subsequent external representations to an
  output port, care should be taken to delimit them properly so they can
  be read back in by subsequent calls to @code{get-datum}.
@end quotation
@end deffn

@deffn {Scheme Procedure} flush-output-port port
@xref{Buffering}, for documentation on @code{force-output}.
@end deffn

@node R6RS File Ports
@subsubsection R6RS File Ports

The facilities described in this section are exported by the @code{(rnrs
io ports)} module.

@deffn {Scheme Syntax} buffer-mode @var{buffer-mode-symbol}
@var{buffer-mode-symbol} must be a symbol whose name is one of
@code{none}, @code{line}, and @code{block}. The result is the
corresponding symbol, and specifies the associated buffer mode.
@xref{Buffering}, for a discussion of these different buffer modes.  To
control the amount of buffering, use @code{setvbuf} instead.  Note that
only the name of @var{buffer-mode-symbol} is significant.

@xref{Buffering}, for a discussion of port buffering.
@end deffn

@deffn {Scheme Procedure} buffer-mode? obj
Returns @code{#t} if the argument is a valid buffer-mode symbol, and
returns @code{#f} otherwise.
@end deffn

When opening a file, the various procedures accept a @code{file-options}
object that encapsulates flags to specify how the file is to be
opened. A @code{file-options} object is an enum-set (@pxref{rnrs enums})
over the symbols constituting valid file options.

A @var{file-options} parameter name means that the corresponding
argument must be a file-options object.

@deffn {Scheme Syntax} file-options @var{file-options-symbol} ...

Each @var{file-options-symbol} must be a symbol.

The @code{file-options} syntax returns a file-options object that
encapsulates the specified options.

When supplied to an operation that opens a file for output, the
file-options object returned by @code{(file-options)} specifies that the
file is created if it does not exist and an exception with condition
type @code{&i/o-file-already-exists} is raised if it does exist.  The
following standard options can be included to modify the default
behavior.

@table @code
@item no-create
      If the file does not already exist, it is not created;
      instead, an exception with condition type @code{&i/o-file-does-not-exist}
      is raised.
      If the file already exists, the exception with condition type
      @code{&i/o-file-already-exists} is not raised
      and the file is truncated to zero length.
@item no-fail
      If the file already exists, the exception with condition type
      @code{&i/o-file-already-exists} is not raised,
      even if @code{no-create} is not included,
      and the file is truncated to zero length.
@item no-truncate
      If the file already exists and the exception with condition type
      @code{&i/o-file-already-exists} has been inhibited by inclusion of
      @code{no-create} or @code{no-fail}, the file is not truncated, but
      the port's current position is still set to the beginning of the
      file.
@end table

These options have no effect when a file is opened only for input.
Symbols other than those listed above may be used as
@var{file-options-symbol}s; they have implementation-specific meaning,
if any.

@quotation Note
  Only the name of @var{file-options-symbol} is significant.
@end quotation
@end deffn

@deffn {Scheme Procedure} open-file-input-port filename
@deffnx {Scheme Procedure} open-file-input-port filename file-options
@deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode
@deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode maybe-transcoder
@var{maybe-transcoder} must be either a transcoder or @code{#f}.

The @code{open-file-input-port} procedure returns an
input port for the named file. The @var{file-options} and
@var{maybe-transcoder} arguments are optional.

The @var{file-options} argument, which may determine various aspects of
the returned port, defaults to the value of @code{(file-options)}.

The @var{buffer-mode} argument, if supplied,
must be one of the symbols that name a buffer mode.
The @var{buffer-mode} argument defaults to @code{block}.

If @var{maybe-transcoder} is a transcoder, it becomes the transcoder associated
with the returned port.

If @var{maybe-transcoder} is @code{#f} or absent,
the port will be a binary port and will support the
@code{port-position} and @code{set-port-position!}  operations.
Otherwise the port will be a textual port, and whether it supports
the @code{port-position} and @code{set-port-position!} operations
is implementation-dependent (and possibly transcoder-dependent).
@end deffn

@deffn {Scheme Procedure} open-file-output-port filename
@deffnx {Scheme Procedure} open-file-output-port filename file-options
@deffnx {Scheme Procedure} open-file-output-port filename file-options buffer-mode
@deffnx {Scheme Procedure} open-file-output-port filename file-options buffer-mode maybe-transcoder
@var{maybe-transcoder} must be either a transcoder or @code{#f}.

The @code{open-file-output-port} procedure returns an output port for the named file.

The @var{file-options} argument, which may determine various aspects of
the returned port, defaults to the value of @code{(file-options)}.

The @var{buffer-mode} argument, if supplied,
must be one of the symbols that name a buffer mode.
The @var{buffer-mode} argument defaults to @code{block}.

If @var{maybe-transcoder} is a transcoder, it becomes the transcoder
associated with the port.

If @var{maybe-transcoder} is @code{#f} or absent,
the port will be a binary port and will support the
@code{port-position} and @code{set-port-position!}  operations.
Otherwise the port will be a textual port, and whether it supports
the @code{port-position} and @code{set-port-position!} operations
is implementation-dependent (and possibly transcoder-dependent).
@end deffn

@node rnrs io simple
@subsubsection rnrs io simple

The @code{(rnrs io simple (6))} library provides convenience functions
for performing textual I/O on ports.  This library also exports all of
the condition types and associated procedures described in (@pxref{R6RS
I/O Conditions}).  In the context of this section, when stating that a
procedure behaves ``identically'' to the corresponding procedure in
Guile's core library, this is modulo the behavior wrt. conditions: such
procedures raise the appropriate R6RS conditions in case of error, but
otherwise behave identically.

@c FIXME: remove the following note when proper condition behavior has
@c been verified.

@quotation Note
There are still known issues regarding condition-correctness; some
errors may still be thrown as native Guile exceptions instead of the
appropriate R6RS conditions.
@end quotation

@deffn {Scheme Procedure} eof-object
@deffnx {Scheme Procedure} eof-object? obj
These procedures are identical to the ones provided by the @code{(rnrs
io ports (6))} library.  @xref{rnrs io ports}, for documentation.
@end deffn

@deffn {Scheme Procedure} input-port? obj
@deffnx {Scheme Procedure} output-port? obj
These procedures are identical to the ones provided by Guile's core
library.  @xref{Ports}, for documentation.
@end deffn

@deffn {Scheme Procedure} call-with-input-file filename proc
@deffnx {Scheme Procedure} call-with-output-file filename proc
@deffnx {Scheme Procedure} open-input-file filename
@deffnx {Scheme Procedure} open-output-file filename
@deffnx {Scheme Procedure} with-input-from-file filename thunk
@deffnx {Scheme Procedure} with-output-to-file filename thunk
These procedures are identical to the ones provided by Guile's core
library.  @xref{File Ports}, for documentation.
@end deffn

@deffn {Scheme Procedure} close-input-port input-port
@deffnx {Scheme Procedure} close-output-port output-port
Closes the given @var{input-port} or @var{output-port}.  These are
legacy interfaces; just use @code{close-port}.
@end deffn

@deffn {Scheme Procedure} peek-char
@deffnx {Scheme Procedure} peek-char textual-input-port
@deffnx {Scheme Procedure} read-char
@deffnx {Scheme Procedure} read-char textual-input-port
These procedures are identical to the ones provided by Guile's core
library.  @xref{Venerable Port Interfaces}, for documentation.
@end deffn

@deffn {Scheme Procedure} read
@deffnx {Scheme Procedure} read textual-input-port
This procedure is identical to the one provided by Guile's core library.
@xref{Scheme Read}, for documentation.
@end deffn

@deffn {Scheme Procedure} display obj
@deffnx {Scheme Procedure} display obj textual-output-port
@deffnx {Scheme Procedure} newline
@deffnx {Scheme Procedure} newline textual-output-port
@deffnx {Scheme Procedure} write obj
@deffnx {Scheme Procedure} write obj textual-output-port
@deffnx {Scheme Procedure} write-char char
@deffnx {Scheme Procedure} write-char char textual-output-port
These procedures are identical to the ones provided by Guile's core
library.  @xref{Venerable Port Interfaces}, and @xref{Scheme Write}, for
documentation.
@end deffn

@node rnrs files
@subsubsection rnrs files

The @code{(rnrs files (6))} library provides the @code{file-exists?} and
@code{delete-file} procedures, which test for the existence of a file
and allow the deletion of files from the file system, respectively.

These procedures are identical to the ones provided by Guile's core 
library.  @xref{File System}, for documentation.

@node rnrs programs
@subsubsection rnrs programs

The @code{(rnrs programs (6))} library provides procedures for 
process management and introspection.

@deffn {Scheme Procedure} command-line
This procedure is identical to the one provided by Guile's core library.
@xref{Runtime Environment}, for documentation.
@end deffn

@deffn {Scheme Procedure} exit [status]
This procedure is identical to the one provided by Guile's core
library. @xref{Processes}, for documentation.
@end deffn

@node rnrs arithmetic fixnums
@subsubsection rnrs arithmetic fixnums

The @code{(rnrs arithmetic fixnums (6))} library provides procedures for
performing arithmetic operations on an implementation-dependent range of
exact integer values, which R6RS refers to as @dfn{fixnums}.  In Guile,
the size of a fixnum is determined by the size of the @code{SCM} type; a
single SCM struct is guaranteed to be able to hold an entire fixnum, 
making fixnum computations particularly 
efficient---(@pxref{The SCM Type}).  On 32-bit systems, the most 
negative and most positive fixnum values are, respectively, -536870912 
and 536870911.

Unless otherwise specified, all of the procedures below take fixnums as
arguments, and will raise an @code{&assertion} condition if passed a 
non-fixnum argument or an @code{&implementation-restriction} condition 
if their result is not itself a fixnum.

@deffn {Scheme Procedure} fixnum? obj
Returns @code{#t} if @var{obj} is a fixnum, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} fixnum-width
@deffnx {Scheme Procedure} least-fixnum
@deffnx {Scheme Procedure} greatest-fixnum
These procedures return, respectively, the maximum number of bits 
necessary to represent a fixnum value in Guile, the minimum fixnum
value, and the maximum fixnum value.
@end deffn

@deffn {Scheme Procedure} fx=? fx1 fx2 fx3 ...
@deffnx {Scheme Procedure} fx>? fx1 fx2 fx3 ...
@deffnx {Scheme Procedure} fx<? fx1 fx2 fx3 ...
@deffnx {Scheme Procedure} fx>=? fx1 fx2 fx3 ...
@deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
These procedures return @code{#t} if their fixnum arguments are
(respectively): equal, monotonically increasing, monotonically
decreasing, monotonically nondecreasing, or monotonically nonincreasing;
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} fxzero? fx
@deffnx {Scheme Procedure} fxpositive? fx
@deffnx {Scheme Procedure} fxnegative? fx
@deffnx {Scheme Procedure} fxodd? fx
@deffnx {Scheme Procedure} fxeven? fx
These numerical predicates return @code{#t} if @var{fx} is,
respectively, zero, greater than zero, less than zero, odd, or even;
@code{#f} otherwise. 
@end deffn

@deffn {Scheme Procedure} fxmax fx1 fx2 ...
@deffnx {Scheme Procedure} fxmin fx1 fx2 ...
These procedures return the maximum or minimum of their arguments.
@end deffn

@deffn {Scheme Procedure} fx+ fx1 fx2
@deffnx {Scheme Procedure} fx* fx1 fx2
These procedures return the sum or product of their arguments.
@end deffn

@deffn {Scheme Procedure} fx- fx1 fx2
@deffnx {Scheme Procedure} fx- fx
Returns the difference of @var{fx1} and @var{fx2}, or the negation of
@var{fx}, if called with a single argument.

An @code{&assertion} condition is raised if the result is not itself a
fixnum.
@end deffn

@deffn {Scheme Procedure} fxdiv-and-mod fx1 fx2
@deffnx {Scheme Procedure} fxdiv fx1 fx2
@deffnx {Scheme Procedure} fxmod fx1 fx2
@deffnx {Scheme Procedure} fxdiv0-and-mod0 fx1 fx2
@deffnx {Scheme Procedure} fxdiv0 fx1 fx2
@deffnx {Scheme Procedure} fxmod0 fx1 fx2
These procedures implement number-theoretic division on fixnums;
@xref{(rnrs base)}, for a description of their semantics.
@end deffn

@deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
Returns the two fixnum results of the following computation:
@lisp
(let* ((s (+ fx1 fx2 fx3))
       (s0 (mod0 s (expt 2 (fixnum-width))))
       (s1 (div0 s (expt 2 (fixnum-width)))))
  (values s0 s1))
@end lisp
@end deffn

@deffn {Scheme Procedure} fx-/carry fx1 fx2 fx3
Returns the two fixnum results of the following computation:
@lisp
(let* ((d (- fx1 fx2 fx3))
       (d0 (mod0 d (expt 2 (fixnum-width))))
       (d1 (div0 d (expt 2 (fixnum-width)))))
  (values d0 d1))
@end lisp
@end deffn

@deffn {Scheme Procedure} fx*/carry fx1 fx2 fx3
@lisp
Returns the two fixnum results of the following computation:
(let* ((s (+ (* fx1 fx2) fx3))
       (s0 (mod0 s (expt 2 (fixnum-width))))
       (s1 (div0 s (expt 2 (fixnum-width)))))
  (values s0 s1))
@end lisp
@end deffn

@deffn {Scheme Procedure} fxnot fx
@deffnx {Scheme Procedure} fxand fx1 ...
@deffnx {Scheme Procedure} fxior fx1 ...
@deffnx {Scheme Procedure} fxxor fx1 ...
These procedures are identical to the @code{lognot}, @code{logand},
@code{logior}, and @code{logxor} procedures provided by Guile's core
library.  @xref{Bitwise Operations}, for documentation.
@end deffn

@deffn {Scheme Procedure} fxif fx1 fx2 fx3
Returns the bitwise ``if'' of its fixnum arguments.  The bit at position
@code{i} in the return value will be the @code{i}th bit from @var{fx2}
if the @code{i}th bit of @var{fx1} is 1, the @code{i}th bit from 
@var{fx3}.
@end deffn

@deffn {Scheme Procedure} fxbit-count fx
Returns the number of 1 bits in the two's complement representation of
@var{fx}.
@end deffn

@deffn {Scheme Procedure} fxlength fx
Returns the number of bits necessary to represent @var{fx}.
@end deffn

@deffn {Scheme Procedure} fxfirst-bit-set fx
Returns the index of the least significant 1 bit in the two's complement
representation of @var{fx}.
@end deffn

@deffn {Scheme Procedure} fxbit-set? fx1 fx2
Returns @code{#t} if the @var{fx2}th bit in the two's complement
representation of @var{fx1} is 1, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} fxcopy-bit fx1 fx2 fx3
Returns the result of setting the @var{fx2}th bit of @var{fx1} to the
@var{fx2}th bit of @var{fx3}.
@end deffn 

@deffn {Scheme Procedure} fxbit-field fx1 fx2 fx3
Returns the integer representation of the contiguous sequence of bits in
@var{fx1} that starts at position @var{fx2} (inclusive) and ends at
position @var{fx3} (exclusive).
@end deffn

@deffn {Scheme Procedure} fxcopy-bit-field fx1 fx2 fx3 fx4
Returns the result of replacing the bit field in @var{fx1} with start
and end positions @var{fx2} and @var{fx3} with the corresponding bit
field from @var{fx4}.
@end deffn

@deffn {Scheme Procedure} fxarithmetic-shift fx1 fx2
@deffnx {Scheme Procedure} fxarithmetic-shift-left fx1 fx2
@deffnx {Scheme Procedure} fxarithmetic-shift-right fx1 fx2
Returns the result of shifting the bits of @var{fx1} right or left by
the @var{fx2} positions.  @code{fxarithmetic-shift} is identical
to @code{fxarithmetic-shift-left}.
@end deffn

@deffn {Scheme Procedure} fxrotate-bit-field fx1 fx2 fx3 fx4
Returns the result of cyclically permuting the bit field in @var{fx1}
with start and end positions @var{fx2} and @var{fx3} by @var{fx4} bits
in the direction of more significant bits.
@end deffn

@deffn {Scheme Procedure} fxreverse-bit-field fx1 fx2 fx3
Returns the result of reversing the order of the bits of @var{fx1} 
between position @var{fx2} (inclusive) and position @var{fx3} 
(exclusive).
@end deffn

@node rnrs arithmetic flonums
@subsubsection rnrs arithmetic flonums

The @code{(rnrs arithmetic flonums (6))} library provides procedures for
performing arithmetic operations on inexact representations of real
numbers, which R6RS refers to as @dfn{flonums}.

Unless otherwise specified, all of the procedures below take flonums as
arguments, and will raise an @code{&assertion} condition if passed a 
non-flonum argument.

@deffn {Scheme Procedure} flonum? obj
Returns @code{#t} if @var{obj} is a flonum, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} real->flonum x
Returns the flonum that is numerically closest to the real number 
@var{x}.
@end deffn

@deffn {Scheme Procedure} fl=? fl1 fl2 fl3 ...
@deffnx {Scheme Procedure} fl<? fl1 fl2 fl3 ...
@deffnx {Scheme Procedure} fl<=? fl1 fl2 fl3 ...
@deffnx {Scheme Procedure} fl>? fl1 fl2 fl3 ...
@deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
These procedures return @code{#t} if their flonum arguments are
(respectively): equal, monotonically increasing, monotonically
decreasing, monotonically nondecreasing, or monotonically nonincreasing;
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} flinteger? fl
@deffnx {Scheme Procedure} flzero? fl
@deffnx {Scheme Procedure} flpositive? fl
@deffnx {Scheme Procedure} flnegative? fl
@deffnx {Scheme Procedure} flodd? fl
@deffnx {Scheme Procedure} fleven? fl
These numerical predicates return @code{#t} if @var{fl} is,
respectively, an integer, zero, greater than zero, less than zero, odd,
even, @code{#f} otherwise.  In the case of @code{flodd?} and 
@code{fleven?}, @var{fl} must be an integer-valued flonum.
@end deffn

@deffn {Scheme Procedure} flfinite? fl
@deffnx {Scheme Procedure} flinfinite? fl
@deffnx {Scheme Procedure} flnan? fl
These numerical predicates return @code{#t} if @var{fl} is, 
respectively, not infinite, infinite, or a @code{NaN} value.
@end deffn

@deffn {Scheme Procedure} flmax fl1 fl2 ...
@deffnx {Scheme Procedure} flmin fl1 fl2 ...
These procedures return the maximum or minimum of their arguments.
@end deffn

@deffn {Scheme Procedure} fl+ fl1 ...
@deffnx {Scheme Procedure} fl* fl ...
These procedures return the sum or product of their arguments.
@end deffn

@deffn {Scheme Procedure} fl- fl1 fl2 ...
@deffnx {Scheme Procedure} fl- fl
@deffnx {Scheme Procedure} fl/ fl1 fl2 ...
@deffnx {Scheme Procedure} fl/ fl
These procedures return, respectively, the difference or quotient of
their arguments when called with two arguments; when called with a
single argument, they return the additive or multiplicative inverse of
@var{fl}.
@end deffn

@deffn {Scheme Procedure} flabs fl
Returns the absolute value of @var{fl}.
@end deffn

@deffn {Scheme Procedure} fldiv-and-mod fl1 fl2
@deffnx {Scheme Procedure} fldiv fl1 fl2
@deffnx {Scheme Procedure} fldmod fl1 fl2
@deffnx {Scheme Procedure} fldiv0-and-mod0 fl1 fl2
@deffnx {Scheme Procedure} fldiv0 fl1 fl2
@deffnx {Scheme Procedure} flmod0 fl1 fl2
These procedures implement number-theoretic division on flonums;
@xref{(rnrs base)}, for a description for their semantics.
@end deffn

@deffn {Scheme Procedure} flnumerator fl
@deffnx {Scheme Procedure} fldenominator fl
These procedures return the numerator or denominator of @var{fl} as a
flonum.
@end deffn

@deffn {Scheme Procedure} flfloor fl1
@deffnx {Scheme Procedure} flceiling fl
@deffnx {Scheme Procedure} fltruncate fl
@deffnx {Scheme Procedure} flround fl
These procedures are identical to the @code{floor}, @code{ceiling},
@code{truncate}, and @code{round} procedures provided by Guile's core
library.  @xref{Arithmetic}, for documentation.
@end deffn

@deffn {Scheme Procedure} flexp fl
@deffnx {Scheme Procedure} fllog fl
@deffnx {Scheme Procedure} fllog fl1 fl2 
@deffnx {Scheme Procedure} flsin fl
@deffnx {Scheme Procedure} flcos fl
@deffnx {Scheme Procedure} fltan fl
@deffnx {Scheme Procedure} flasin fl
@deffnx {Scheme Procedure} flacos fl
@deffnx {Scheme Procedure} flatan fl
@deffnx {Scheme Procedure} flatan fl1 fl2
These procedures, which compute the usual transcendental functions, are
the flonum variants of the procedures provided by the R6RS base library
(@pxref{(rnrs base)}).
@end deffn

@deffn {Scheme Procedure} flsqrt fl
Returns the square root of @var{fl}.  If @var{fl} is @code{-0.0}, 
@var{-0.0} is returned; for other negative values, a @code{NaN} value
is returned.
@end deffn

@deffn {Scheme Procedure} flexpt fl1 fl2
Returns the value of @var{fl1} raised to the power of @var{fl2}.
@end deffn

The following condition types are provided to allow Scheme 
implementations that do not support infinities or @code{NaN} values
to indicate that a computation resulted in such a value.  Guile supports
both of these, so these conditions will never be raised by Guile's 
standard libraries implementation.

@deffn {Condition Type} &no-infinities
@deffnx {Scheme Procedure} make-no-infinities-violation obj
@deffnx {Scheme Procedure} no-infinities-violation?
A condition type indicating that a computation resulted in an infinite
value on a Scheme implementation incapable of representing infinities.
@end deffn

@deffn {Condition Type} &no-nans
@deffnx {Scheme Procedure} make-no-nans-violation obj
@deffnx {Scheme Procedure} no-nans-violation? obj
A condition type indicating that a computation resulted in a @code{NaN}
value on a Scheme implementation incapable of representing @code{NaN}s.
@end deffn

@deffn {Scheme Procedure} fixnum->flonum fx
Returns the flonum that is numerically closest to the fixnum @var{fx}.
@end deffn

@node rnrs arithmetic bitwise
@subsubsection rnrs arithmetic bitwise

The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
performing bitwise arithmetic operations on the two's complement
representations of fixnums.  

This library and the procedures it exports share functionality with 
SRFI-60, which provides support for bitwise manipulation of integers 
(@pxref{SRFI-60}).

@deffn {Scheme Procedure} bitwise-not ei
@deffnx {Scheme Procedure} bitwise-and ei1 ...
@deffnx {Scheme Procedure} bitwise-ior ei1 ...
@deffnx {Scheme Procedure} bitwise-xor ei1 ...
These procedures are identical to the @code{lognot}, @code{logand},
@code{logior}, and @code{logxor} procedures provided by Guile's core
library.  @xref{Bitwise Operations}, for documentation.
@end deffn

@deffn {Scheme Procedure} bitwise-if ei1 ei2 ei3
Returns the bitwise ``if'' of its arguments.  The bit at position
@code{i} in the return value will be the @code{i}th bit from @var{ei2}
if the @code{i}th bit of @var{ei1} is 1, the @code{i}th bit from 
@var{ei3}.
@end deffn

@deffn {Scheme Procedure} bitwise-bit-count ei
Returns the number of 1 bits in the two's complement representation of
@var{ei}.
@end deffn

@deffn {Scheme Procedure} bitwise-length ei
Returns the number of bits necessary to represent @var{ei}.
@end deffn

@deffn {Scheme Procedure} bitwise-first-bit-set ei
Returns the index of the least significant 1 bit in the two's complement
representation of @var{ei}.
@end deffn

@deffn {Scheme Procedure} bitwise-bit-set? ei1 ei2
Returns @code{#t} if the @var{ei2}th bit in the two's complement
representation of @var{ei1} is 1, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} bitwise-copy-bit ei1 ei2 ei3
Returns the result of setting the @var{ei2}th bit of @var{ei1} to the
@var{ei2}th bit of @var{ei3}.
@end deffn

@deffn {Scheme Procedure} bitwise-bit-field ei1 ei2 ei3
Returns the integer representation of the contiguous sequence of bits in
@var{ei1} that starts at position @var{ei2} (inclusive) and ends at
position @var{ei3} (exclusive).
@end deffn

@deffn {Scheme Procedure} bitwise-copy-bit-field ei1 ei2 ei3 ei4
Returns the result of replacing the bit field in @var{ei1} with start
and end positions @var{ei2} and @var{ei3} with the corresponding bit
field from @var{ei4}.
@end deffn

@deffn {Scheme Procedure} bitwise-arithmetic-shift ei1 ei2
@deffnx {Scheme Procedure} bitwise-arithmetic-shift-left ei1 ei2
@deffnx {Scheme Procedure} bitwise-arithmetic-shift-right ei1 ei2
Returns the result of shifting the bits of @var{ei1} right or left by
the @var{ei2} positions.  @code{bitwise-arithmetic-shift} is identical
to @code{bitwise-arithmetic-shift-left}.
@end deffn

@deffn {Scheme Procedure} bitwise-rotate-bit-field ei1 ei2 ei3 ei4
Returns the result of cyclically permuting the bit field in @var{ei1}
with start and end positions @var{ei2} and @var{ei3} by @var{ei4} bits
in the direction of more significant bits.
@end deffn

@deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
Returns the result of reversing the order of the bits of @var{ei1}
between position @var{ei2} (inclusive) and position @var{ei3}
(exclusive).
@end deffn

@node rnrs syntax-case
@subsubsection rnrs syntax-case

The @code{(rnrs syntax-case (6))} library provides access to the 
@code{syntax-case} system for writing hygienic macros.  With one
exception, all of the forms and procedures exported by this library
are ``re-exports'' of Guile's native support for @code{syntax-case};
@xref{Syntax Case}, for documentation, examples, and rationale. 

@deffn {Scheme Procedure} make-variable-transformer proc
Creates a new variable transformer out of @var{proc}, a procedure that
takes a syntax object as input and returns a syntax object.  If an
identifier to which the result of this procedure is bound appears on the
left-hand side of a @code{set!} expression, @var{proc} will be called
with a syntax object representing the entire @code{set!} expression,
and its return value will replace that @code{set!} expression. 
@end deffn

@deffn {Scheme Syntax} syntax-case expression (literal ...) clause ...
The @code{syntax-case} pattern matching form.
@end deffn

@deffn {Scheme Syntax} syntax template
@deffnx {Scheme Syntax} quasisyntax template
@deffnx {Scheme Syntax} unsyntax template
@deffnx {Scheme Syntax} unsyntax-splicing template
These forms allow references to be made in the body of a syntax-case 
output expression subform to datum and non-datum values.  They are 
identical to the forms provided by Guile's core library;
@xref{Syntax Case}, for documentation.
@end deffn

@deffn {Scheme Procedure} identifier? obj
@deffnx {Scheme Procedure} bound-identifier=? id1 id2
@deffnx {Scheme Procedure} free-identifier=? id1 id2
These predicate procedures operate on syntax objects representing
Scheme identifiers.  @code{identifier?} returns @code{#t} if @var{obj}
represents an identifier, @code{#f} otherwise.  
@code{bound-identifier=?} returns @code{#t} if and only if a binding for
@var{id1} would capture a reference to @var{id2} in the transformer's 
output, or vice-versa.  @code{free-identifier=?} returns @code{#t} if
and only @var{id1} and @var{id2} would refer to the same binding in the
output of the transformer, independent of any bindings introduced by the
transformer.
@end deffn

@deffn {Scheme Procedure} generate-temporaries l
Returns a list, of the same length as @var{l}, which must be a list or
a syntax object representing a list, of globally unique symbols.
@end deffn

@deffn {Scheme Procedure} syntax->datum syntax-object
@deffnx {Scheme Procedure} datum->syntax template-id datum
These procedures convert wrapped syntax objects to and from Scheme datum
values.  The syntax object returned by @code{datum->syntax} shares
contextual information with the syntax object @var{template-id}.
@end deffn

@deffn {Scheme Procedure} syntax-violation whom message form
@deffnx {Scheme Procedure} syntax-violation whom message form subform
Constructs a new compound condition that includes the following
simple conditions:
@itemize @bullet
@item
If @var{whom} is not @code{#f}, a @code{&who} condition with the
@var{whom} as its field
@item
A @code{&message} condition with the specified @var{message}
@item
A @code{&syntax} condition with the specified @var{form} and optional
@var{subform} fields
@end itemize
@end deffn

@node rnrs hashtables
@subsubsection rnrs hashtables

The @code{(rnrs hashtables (6))} library provides structures and
procedures for creating and accessing hash tables.  The hash tables API
defined by R6RS is substantially similar to both Guile's native hash 
tables implementation as well as the one provided by SRFI-69; 
@xref{Hash Tables}, and @ref{SRFI-69}, respectively.  Note that you can
write portable R6RS library code that manipulates SRFI-69 hash tables 
(by importing the @code{(srfi :69)} library); however, hash tables 
created by one API cannot be used by another.

Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash 
tables associate hash and equality functions with a hash table at the 
time of its creation.  Additionally, R6RS allows for the creation
(via @code{hashtable-copy}; see below) of immutable hash tables.

@deffn {Scheme Procedure} make-eq-hashtable
@deffnx {Scheme Procedure} make-eq-hashtable k
Returns a new hash table that uses @code{eq?} to compare keys and 
Guile's @code{hashq} procedure as a hash function.  If @var{k} is given,
it specifies the initial capacity of the hash table.
@end deffn

@deffn {Scheme Procedure} make-eqv-hashtable
@deffnx {Scheme Procedure} make-eqv-hashtable k
Returns a new hash table that uses @code{eqv?} to compare keys and
Guile's @code{hashv} procedure as a hash function.  If @var{k} is given,
it specifies the initial capacity of the hash table.
@end deffn

@deffn {Scheme Procedure} make-hashtable hash-function equiv
@deffnx {Scheme Procedure} make-hashtable hash-function equiv k
Returns a new hash table that uses @var{equiv} to compare keys and
@var{hash-function} as a hash function.  @var{equiv} must be a procedure
that accepts two arguments and returns a true value if they are 
equivalent, @code{#f} otherwise; @var{hash-function} must be a procedure
that accepts one argument and returns a non-negative integer.

If @var{k} is given, it specifies the initial capacity of the hash 
table.
@end deffn

@deffn {Scheme Procedure} hashtable? obj
Returns @code{#t} if @var{obj} is an R6RS hash table, @code{#f} 
otherwise.
@end deffn

@deffn {Scheme Procedure} hashtable-size hashtable
Returns the number of keys currently in the hash table @var{hashtable}.
@end deffn

@deffn {Scheme Procedure} hashtable-ref hashtable key default
Returns the value associated with @var{key} in the hash table
@var{hashtable}, or @var{default} if none is found.
@end deffn

@deffn {Scheme Procedure} hashtable-set! hashtable key obj
Associates the key @var{key} with the value @var{obj} in the hash table
@var{hashtable}, and returns an unspecified value.  An @code{&assertion}
condition is raised if @var{hashtable} is immutable.
@end deffn

@deffn {Scheme Procedure} hashtable-delete! hashtable key
Removes any association found for the key @var{key} in the hash table
@var{hashtable}, and returns an unspecified value.  An @code{&assertion}
condition is raised if @var{hashtable} is immutable.
@end deffn

@deffn {Scheme Procedure} hashtable-contains? hashtable key
Returns @code{#t} if the hash table @var{hashtable} contains an
association for the key @var{key}, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} hashtable-update! hashtable key proc default
Associates with @var{key} in the hash table @var{hashtable} the result 
of calling @var{proc}, which must be a procedure that takes one 
argument, on the value currently associated @var{key} in 
@var{hashtable}---or on @var{default} if no such association exists.
An @code{&assertion} condition is raised if @var{hashtable} is
immutable.
@end deffn

@deffn {Scheme Procedure} hashtable-copy hashtable
@deffnx {Scheme Procedure} hashtable-copy hashtable mutable
Returns a copy of the hash table @var{hashtable}.  If the optional
argument @var{mutable} is provided and is a true value, the new hash
table will be mutable.
@end deffn

@deffn {Scheme Procedure} hashtable-clear! hashtable
@deffnx {Scheme Procedure} hashtable-clear! hashtable k
Removes all of the associations from the hash table @var{hashtable}.
The optional argument @var{k}, which specifies a new capacity for the
hash table, is accepted by Guile's @code{(rnrs hashtables)} 
implementation, but is ignored.
@end deffn

@deffn {Scheme Procedure} hashtable-keys hashtable
Returns a vector of the keys with associations in the hash table 
@var{hashtable}, in an unspecified order.
@end deffn

@deffn {Scheme Procedure} hashtable-entries hashtable
Return two values---a vector of the keys with associations in the hash
table @var{hashtable}, and a vector of the values to which these keys
are mapped, in corresponding but unspecified order.
@end deffn

@deffn {Scheme Procedure} hashtable-equivalence-function hashtable
Returns the equivalence predicated use by @var{hashtable}.  This
procedure returns @code{eq?} and @code{eqv?}, respectively, for hash
tables created by @code{make-eq-hashtable} and 
@code{make-eqv-hashtable}.
@end deffn

@deffn {Scheme Procedure} hashtable-hash-function hashtable
Returns the hash function used by @var{hashtable}.  For hash tables
created by @code{make-eq-hashtable} or @code{make-eqv-hashtable}, 
@code{#f} is returned.
@end deffn

@deffn {Scheme Procedure} hashtable-mutable? hashtable
Returns @code{#t} if @var{hashtable} is mutable, @code{#f} otherwise.
@end deffn

A number of hash functions are provided for convenience:

@deffn {Scheme Procedure} equal-hash obj
Returns an integer hash value for @var{obj}, based on its structure and 
current contents. This hash function is suitable for use with 
@code{equal?} as an equivalence function.
@end deffn

@deffn {Scheme Procedure} string-hash string
@deffnx {Scheme Procedure} symbol-hash symbol
These procedures are identical to the ones provided by Guile's core 
library.  @xref{Hash Table Reference}, for documentation.
@end deffn

@deffn {Scheme Procedure} string-ci-hash string
Returns an integer hash value for @var{string} based on its contents,
ignoring case.  This hash function is suitable for use with 
@code{string-ci=?} as an equivalence function.
@end deffn

@node rnrs enums
@subsubsection rnrs enums

The @code{(rnrs enums (6))} library provides structures and procedures
for working with enumerable sets of symbols.  Guile's implementation 
defines an @dfn{enum-set} record type that encapsulates a finite set of
distinct symbols, the @dfn{universe}, and a subset of these symbols, 
which define the enumeration set.

The SRFI-1 list library provides a number of procedures for performing
set operations on lists; Guile's @code{(rnrs enums)} implementation 
makes use of several of them.  @xref{SRFI-1 Set Operations}, for
more information.

@deffn {Scheme Procedure} make-enumeration symbol-list
Returns a new enum-set whose universe and enumeration set are both equal
to @var{symbol-list}, a list of symbols.
@end deffn

@deffn {Scheme Procedure} enum-set-universe enum-set
Returns an enum-set representing the universe of @var{enum-set},
an enum-set.
@end deffn

@deffn {Scheme Procedure} enum-set-indexer enum-set
Returns a procedure that takes a single argument and returns the
zero-indexed position of that argument in the universe of 
@var{enum-set}, or @code{#f} if its argument is not a member of that
universe.
@end deffn

@deffn {Scheme Procedure} enum-set-constructor enum-set
Returns a procedure that takes a single argument, a list of symbols
from the universe of @var{enum-set}, an enum-set, and returns a new
enum-set with the same universe that represents a subset containing the
specified symbols.
@end deffn

@deffn {Scheme Procedure} enum-set->list enum-set
Returns a list containing the symbols of the set represented by
@var{enum-set}, an enum-set, in the order that they appear in the 
universe of @var{enum-set}.
@end deffn

@deffn {Scheme Procedure} enum-set-member? symbol enum-set
@deffnx {Scheme Procedure} enum-set-subset? enum-set1 enum-set2
@deffnx {Scheme Procedure} enum-set=? enum-set1 enum-set2
These procedures test for membership of symbols and enum-sets in other
enum-sets.  @code{enum-set-member?} returns @code{#t} if and only if
@var{symbol} is a member of the subset specified by @var{enum-set}.
@code{enum-set-subset?} returns @code{#t} if and only if the universe of
@var{enum-set1} is a subset of the universe of @var{enum-set2} and
every symbol in @var{enum-set1} is present in @var{enum-set2}.
@code{enum-set=?} returns @code{#t} if and only if @var{enum-set1} is a
subset, as per @code{enum-set-subset?} of @var{enum-set2} and vice
versa.
@end deffn

@deffn {Scheme Procedure} enum-set-union enum-set1 enum-set2
@deffnx {Scheme Procedure} enum-set-intersection enum-set1 enum-set2
@deffnx {Scheme Procedure} enum-set-difference enum-set1 enum-set2
These procedures return, respectively, the union, intersection, and
difference of their enum-set arguments.
@end deffn

@deffn {Scheme Procedure} enum-set-complement enum-set
Returns @var{enum-set}'s complement (an enum-set), with regard to its
universe.
@end deffn

@deffn {Scheme Procedure} enum-set-projection enum-set1 enum-set2
Returns the projection of the enum-set @var{enum-set1} onto the universe
of the enum-set @var{enum-set2}.
@end deffn

@deffn {Scheme Syntax} define-enumeration type-name (symbol ...) constructor-syntax
Evaluates to two new definitions: A constructor bound to 
@var{constructor-syntax} that behaves similarly to constructors created
by @code{enum-set-constructor}, above, and creates new @var{enum-set}s
in the universe specified by @code{(symbol ...)}; and a ``predicate 
macro'' bound to @var{type-name}, which has the following form:

@lisp
(@var{type-name} sym)
@end lisp
 
If @var{sym} is a member of the universe specified by the @var{symbol}s
above, this form evaluates to @var{sym}.  Otherwise, a @code{&syntax} 
condition is raised.
@end deffn

@node rnrs
@subsubsection rnrs

The @code{(rnrs (6))} library is a composite of all of the other R6RS
standard libraries---it imports and re-exports all of their exported
procedures and syntactic forms---with the exception of the following
libraries:

@itemize @bullet
@item @code{(rnrs eval (6))}
@item @code{(rnrs mutable-pairs (6))}
@item @code{(rnrs mutable-strings (6))}
@item @code{(rnrs r5rs (6))}
@end itemize

@node rnrs eval
@subsubsection rnrs eval

The @code{(rnrs eval (6)} library provides procedures for performing 
``on-the-fly'' evaluation of expressions.

@deffn {Scheme Procedure} eval expression environment
Evaluates @var{expression}, which must be a datum representation of a
valid Scheme expression, in the environment specified by 
@var{environment}.  This procedure is identical to the one provided by
Guile's code library; @xref{Fly Evaluation}, for documentation.
@end deffn

@deffn {Scheme Procedure} environment import-spec ...
Constructs and returns a new environment based on the specified
@var{import-spec}s, which must be datum representations of the import
specifications used with the @code{import} form.  @xref{R6RS Libraries},
for documentation.
@end deffn

@node rnrs mutable-pairs
@subsubsection rnrs mutable-pairs

The @code{(rnrs mutable-pairs (6))} library provides the @code{set-car!}
and @code{set-cdr!} procedures, which allow the @code{car} and 
@code{cdr} fields of a pair to be modified.

These procedures are identical to the ones provide by Guile's core
library.  @xref{Pairs}, for documentation.  All pairs in Guile are
mutable; consequently, these procedures will never throw the
@code{&assertion} condition described in the R6RS libraries 
specification.

@node rnrs mutable-strings
@subsubsection rnrs mutable-strings

The @code{(rnrs mutable-strings (6))} library provides the 
@code{string-set!} and @code{string-fill!} procedures, which allow the
content of strings to be modified ``in-place.''

These procedures are identical to the ones provided by Guile's core
library.  @xref{String Modification}, for documentation.  All strings in
Guile are mutable; consequently, these procedures will never throw the 
@code{&assertion} condition described in the R6RS libraries 
specification.

@node rnrs r5rs
@subsubsection rnrs r5rs

The @code{(rnrs r5rs (6))} library exports bindings for some procedures
present in R5RS but omitted from the R6RS base library specification.

@deffn {Scheme Procedure} exact->inexact z
@deffnx {Scheme Procedure} inexact->exact z
These procedures are identical to the ones provided by Guile's core
library.  @xref{Exactness}, for documentation.
@end deffn

@deffn {Scheme Procedure} quotient n1 n2
@deffnx {Scheme Procedure} remainder n1 n2
@deffnx {Scheme Procedure} modulo n1 n2
These procedures are identical to the ones provided by Guile's core
library.  @xref{Integer Operations}, for documentation.
@end deffn

@deffn {Scheme Syntax} delay expr
@deffnx {Scheme Procedure} force promise
The @code{delay} form and the @code{force} procedure are identical to 
their counterparts in Guile's core library.  @xref{Delayed Evaluation},
for documentation.
@end deffn

@deffn {Scheme Procedure} null-environment n
@deffnx {Scheme Procedure} scheme-report-environment n
These procedures are identical to the ones provided by the 
@code{(ice-9 r5rs)} Guile module.  @xref{Environments}, for 
documentation.
@end deffn

@c r6rs.texi ends here

@c Local Variables:
@c TeX-master: "guile.texi"
@c End: