@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2010, 2011, 2012, 2013,
+@c 2014 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node R6RS Support
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
A @code{set!} to a variable transformer may only expand to an
expression, not a definition---even if the original @code{set!}
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 recursive
-nested definitions does do the correct thing:
-
-@example
-(let ()
- (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 at the toplevel do not:
+For example, while the expansion of the following set of toplevel
+definitions does the correct thing:
@example
(begin
(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
reference to @code{odd?} is not yet marked as a syntax transformer, so
it is assumed to be a function.
-While it is likely that we can fix the case of toplevel forms nested in
-a @code{begin} or a @code{library} form, a fix for toplevel programs
-seems trickier to implement in a backward-compatible way. Suggestions
-and/or patches would be appreciated.
+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.
+More generally, it does not make a sharp distinction between binary and
+textual ports (@pxref{R6RS Port Manipulation, binary-port?}).
+
+@item
+Guile's implementation of @code{equal?} may fail to terminate when
+applied to arguments containing cycles.
@end itemize
@node R6RS Standard Libraries
@end deffn
@deffn {Scheme Syntax} define-syntax keyword expression
-@deffnx {Scheme Syntax} let-syntax ((keyword transformer) ...) exp ...
-@deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) ...) exp ...
+@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} if test consequence [alternate]
@deffnx {Scheme Syntax} cond clause1 clause2 ...
@deffnx {Scheme Syntax} case key clause1 clause2 ...
-@xref{if cond case}, for documentation.
+@xref{Conditionals}, for documentation.
@end deffn
@deffn {Scheme Syntax} and expr ...
@deffn {Scheme Procedure} real? x
@deffnx {Scheme Procedure} rational? x
-@deffnx {Scheme Procedure} nan? x
@deffnx {Scheme Procedure} numerator x
@deffnx {Scheme Procedure} denominator x
@deffnx {Scheme Procedure} rationalize x eps
@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
@xref{SRFI-1 Fold and Map}, for documentation.
@end deffn
-@deffn {Scheme Procedure} list elem1 ... elemN
+@deffn {Scheme Procedure} list elem @dots{}
@xref{List Constructors}, for documentation.
@end deffn
@xref{List Selection}, for documentation.
@end deffn
-@deffn {Scheme Procedure} append lst1 ... lstN
+@deffn {Scheme Procedure} append lst @dots{} obj
+@deffnx {Scheme Procedure} append
@deffnx {Scheme Procedure} reverse lst
@xref{Append/Reverse}, for documentation.
@end deffn
@xref{String Selection}, for documentation.
@end deffn
-@deffn {Scheme Procedure} string=? [s1 [s2 . rest]]
-@deffnx {Scheme Procedure} string<? [s1 [s2 . rest]]
-@deffnx {Scheme Procedure} string>? [s1 [s2 . rest]]
-@deffnx {Scheme Procedure} string<=? [s1 [s2 . rest]]
-@deffnx {Scheme Procedure} string>=? [s1 [s2 . rest]]
+@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 . args
+@deffn {Scheme Procedure} string-append arg @dots{}
@xref{Reversing and Appending Strings}, for documentation.
@end deffn
@xref{Arithmetic}, for documentation.
@end deffn
-@deffn {Scheme Procedure} div x1 x2
-@deffnx {Scheme Procedure} mod x1 x2
-@deffnx {Scheme Procedure} div-and-mod x1 x2
-These procedures implement number-theoretic division.
+@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})}.
-@code{div-and-mod} returns two values, the respective results of
-@code{(div x1 x2)} and @code{(mod x1 x2)}.
+@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
-@deffn {Scheme Procedure} div0 x1 x2
-@deffnx {Scheme Procedure} mod0 x1 x2
-@deffnx {Scheme Procedure} div0-and-mod0 x1 x2
-These procedures are similar to @code{div}, @code{mod}, and
-@code{div-and-mod}, except that @code{mod0} returns values that lie
-within a half-open interval centered on zero.
-@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)}.
-@deffn {Scheme Procedure} exact-integer-sqrt k
-This procedure returns two nonnegative integer objects @code{s} and
-@code{r} such that k = s^2 + r and k < (s + 1)^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
imaginary parts are zero.
@end deffn
-@deffn {Scheme Procedure} finite? x
+@deffn {Scheme Procedure} nan? x
@deffnx {Scheme Procedure} infinite? x
-@code{infinite?} returns @code{#t} if @var{x} is an infinite value,
-@code{#f} otherwise. @code{finite?} returns the negation of
-@code{infinite?}.
+@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
over vectors.
@end deffn
-@deffn {Scheme Procedure} vector . l
+@deffn {Scheme Procedure} vector arg @dots{}
@deffnx {Scheme Procedure} vector? obj
@deffnx {Scheme Procedure} make-vector len
@deffnx {Scheme Procedure} make-vector len fill
@xref{Continuations}, for documentation.
@end deffn
-@deffn {Scheme Procedure} values arg1 ... argN
+@deffn {Scheme Procedure} values arg @dots{}
@deffnx {Scheme Procedure} call-with-values producer consumer
@xref{Multiple Values}, for documentation.
@end deffn
@xref{Dynamic Wind}, for documentation.
@end deffn
-@deffn {Scheme Procedure} apply proc arg1 ... argN arglst
+@deffn {Scheme Procedure} apply proc arg @dots{} arglst
@xref{Fly Evaluation}, for documentation.
@end deffn
@xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
@end deffn
-@deffn {Scheme Procedure} fold-left combine nil list1 list2 ... listn
-@deffnx {Scheme Procedure} fold-right combine nil list1 list2 ... listn
+@deffn {Scheme Procedure} fold-left combine nil list1 list2 @dots{}
+@deffnx {Scheme Procedure} fold-right combine nil list1 list2 @dots{}
These procedures are identical to the @code{fold} and @code{fold-right}
procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for
documentation.
@node R6RS Records
@subsubsection R6RS Records
-The manual sections below describe Guile's implementation of R6RS
+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}, for a description of those
+@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
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*
+@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
@deffn {Scheme Procedure} with-exception-handler handler thunk
Installs @var{handler}, which must be a procedure taking one argument,
-as the current exception handler during the invokation of @var{thunk}, a
+as the current exception handler during the invocation of @var{thunk}, a
procedure taking zero arguments. The handler in place at the time
@code{with-exception-handler} is called is made current again once
either @var{thunk} returns or @var{handler} is invoked after an
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{if cond case}). If none of the clause's test expressions
+(@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.
@deffn {Condition Type} &who
@deffnx {Scheme Procedure} make-who-condition who
@deffnx {Scheme Procedure} who-condition? obj
-@deffnx {Scheme Procedure} condiction-who condition
+@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
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{I/O Conditions}).
+the condition types and associated procedures described in (@pxref{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
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 filesystem, respectively.
+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.
@xref{Runtime Environment}, for documentation.
@end deffn
-@deffn {Scheme Procedure} exit
-@deffnx {Scheme Procedure} exit obj
-This procedure is identical to the one provided by Guile's core library.
+@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
@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 nonincrasing;
+decreasing, monotonically nondecreasing, or monotonically nonincreasing;
@code{#f} otherwise.
@end deffn
@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 nonincrasing;
+decreasing, monotonically nondecreasing, or monotonically nonincreasing;
@code{#f} otherwise.
@end deffn
@end deffn
@deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
-Returns the result of reversing the order of the bits of @var{e1}
-between position @var{ei2} (inclusive) and position @var{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
@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 a true value, the new hash table will be
-immutable.
+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