X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/08fc523b0eb477e137d1f6c64c38851f6cddb514..f4af36aca47f7d0653b997986e8be9894bbd87ff:/doc/ref/r6rs.texi

diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index a680f51c2..e5ffb78e4 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -1,7 +1,7 @@
 @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
@@ -36,6 +36,14 @@ 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
 A @code{set!} to a variable transformer may only expand to an 
 expression, not a definition---even if the original @code{set!} 
@@ -45,23 +53,8 @@ expression was in definition context.
 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
@@ -72,6 +65,20 @@ The same definitions at the toplevel do not:
    (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
@@ -80,10 +87,23 @@ 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.
 
-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
@@ -257,8 +277,8 @@ grouped below by the existing manual sections to which they correspond.
 @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
 
@@ -300,7 +320,7 @@ grouped below by the existing manual sections to which they correspond.
 @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 ...
@@ -345,7 +365,6 @@ grouped below by the existing manual sections to which they correspond.
 
 @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
@@ -369,6 +388,7 @@ grouped below by the existing manual sections to which they correspond.
 @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
 
@@ -387,7 +407,7 @@ grouped below by the existing manual sections to which they correspond.
 @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
 
@@ -397,7 +417,8 @@ grouped below by the existing manual sections to which they correspond.
 @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
@@ -424,15 +445,15 @@ grouped below by the existing manual sections to which they correspond.
 @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
 
@@ -454,26 +475,65 @@ grouped below by the existing manual sections to which they correspond.
 @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
@@ -487,11 +547,15 @@ loss of numerical precision.
 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 
@@ -520,7 +584,7 @@ These procedures implement the @code{map} and @code{for-each} contracts
 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
@@ -541,7 +605,7 @@ over vectors.
 @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
@@ -550,7 +614,7 @@ over vectors.
 @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
 
@@ -658,8 +722,8 @@ These procedures are identical to the ones provided by SRFI-1.
 @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.
@@ -766,11 +830,11 @@ This form is identical to the one provided by Guile's core library.
 @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
@@ -844,7 +908,7 @@ compatible with either.
 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
@@ -1071,7 +1135,7 @@ called on exceptions thrown by the corresponding @code{raise} procedure.
 
 @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 
@@ -1087,7 +1151,7 @@ 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{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.
 
@@ -1236,7 +1300,7 @@ condition in a compound condition.
 @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
@@ -1369,8 +1433,21 @@ functionality is documented in its own section of the manual;
 
 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
@@ -1432,7 +1509,7 @@ library.  @xref{Writing}, for documentation.
 
 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.
@@ -1448,9 +1525,9 @@ This procedure is identical to the one provided by Guile's core library.
 @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
@@ -1490,7 +1567,7 @@ value, and the maximum fixnum value.
 @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
 
@@ -1662,7 +1739,7 @@ Returns the flonum that is numerically closest to the real number
 @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
 
@@ -1861,8 +1938,8 @@ 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{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
 
@@ -2026,8 +2103,8 @@ immutable.
 @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