@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
@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
+much---if a correct R6RS program would not hit that error, we don't
bother checking for it.
@item
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!}
+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.
+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
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 --- for example, via a
-@code{use-modules} form. For example, the R6RS ``composite'' library
-can be imported by:
+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 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} 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} 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{Comparison}, for documentation.
@end deffn
-@deffn {Scheme Procedure} fold f lst1 lst2 ...
-@deffnx {Scheme Procedure} for-each f lst1 lst2 ...
+@deffn {Scheme Procedure} for-each f lst1 lst2 ...
@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
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; see (@pxref{Characters}) for documentation.
+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
+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
@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};
-(@pxref{SRFI-1 Filtering and Partitioning}) for @code{partition}.
+@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.
@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}) for their
-documentation. @code{remp} is identical to the alternate @code{remove}
-procedure provided by SRFI-1; @xref{SRFI-1 Deleting}.
+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} 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; (@pxref{List Searching})
-for their documentation. @code{memp} uses the specified predicate
-function @code{proc} to test elements of the list @var{list} --- it
+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
@deffnx {Scheme Procedure} assq obj alist
@code{assoc}, @code{assv}, and @code{assq} are identical to the
procedures provided by Guile's core library;
-(@pxref{Alist Key Equality}) for their documentation. @code{assp} uses
+@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
@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;
-(@pxref{Records}) and (@pxref{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
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.
+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
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
The @code{(rnrs exceptions (6))} library provides functionality related
to signaling and handling exceptional situations. This functionality is
similar to the exception handling systems provided by Guile's core
-library (@pxref{Exceptions}) and by the SRFI-18 and SRFI-34
-modules --- (@pxref{SRFI-18 Exceptions}) and (@pxref{SRFI-34}),
-respectively --- but there are some key differences in concepts and
+library @xref{Exceptions}, and by the SRFI-18 and SRFI-34
+modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34},
+respectively---but there are some key differences in concepts and
behavior.
A raised exception may be @dfn{continuable} or @dfn{non-continuable}.
@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
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 (@pxref{if cond case}), with the value of the
-first matching clause becoming the value of the @code{guard} expression.
-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.
+@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
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
+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
return the requisite fields from the first component simple condition
found to be of the appropriate type.
-@deffn &condition
-@deffnx condition? obj
+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 not currently compatible,
+however; the @code{condition?} predicate from one API will return
+@code{#f} when applied to a condition object created in the other.
+
+@deffn {Condition Type} &condition
+@deffnx {Scheme Procedure} condition? obj
The base record type for conditions.
@end deffn
the name for a binding to an accessor procedure created for this field.
@end deffn
-@deffn &message
+@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 &warning
+@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 &serious
+@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.
@end deffn
-@deffn &error
+@deffn {Condition Type} &error
@deffnx {Scheme Procedure} make-error
@deffnx {Scheme Procedure} error? obj
A base type for conditions representing errors.
@end deffn
-@deffn &violation
+@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.
@end deffn
-@deffn &assertion
+@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.
@end deffn
-@deffn &irritants
+@deffn {Condition Type} &irritants
@deffnx {Scheme Procedure} make-irritants-condition irritants
@deffnx {Scheme Procedure} irritants-condition? obj
@deffnx {Scheme Procedure} condition-irritants condition
condition in a compound condition.
@end deffn
-@deffn &who
+@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
-@deffn &non-continuable
+@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 &implementation-restriction
+@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 &lexical
+@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 &syntax
+@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
indicate the syntactic form responsible for the condition.
@end deffn
-@deffn &undefined
+@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
These condition types are exported by both the
@code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.
-@deffn &i/o
+@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 &i/o-read
+@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 &i/o-write
+@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 &i/o-invalid-position
+@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
set the file position to an invalid position.
@end deffn
-@deffn &i/o-filename
+@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 named file.
@end deffn
-@deffn &i/o-file-protection
+@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
permissions.
@end deffn
-@deffn &i/o-file-is-read-only
+@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 &i/o-file-already-exists
+@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 &i/o-file-does-not-exist
+@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 &i/o-port
+@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
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
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.
+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
@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} fxdiv0 fx1 fx2
@deffnx {Scheme Procedure} fxmod0 fx1 fx2
These procedures implement number-theoretic division on fixnums;
-(@pxref{(rnrs base)}) for a description for their semantics.
+@xref{(rnrs base)}, for a description of their semantics.
@end deffn
@deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
@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
@deffnx {Scheme Procedure} fldiv0 fl1 fl2
@deffnx {Scheme Procedure} flmod0 fl1 fl2
These procedures implement number-theoretic division on flonums;
-(@pxref{(rnrs base)}) for a description for their semantics.
+@xref{(rnrs base)}, for a description for their semantics.
@end deffn
@deffn {Scheme Procedure} flnumerator fl
both of these, so these conditions will never be raised by Guile's
standard libraries implementation.
-@deffn &no-infinities
+@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 &no-nans
+@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}
The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
performing bitwise arithmetic operations on the two's complement
-representations of fixnums.
+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 ...
@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
@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};
-(@pxref{Syntax Case}) for documentation, examples, and rationale.
+@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
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;
-(@pxref{Syntax Case}) for documentation.
+@xref{Syntax Case}, for documentation.
@end deffn
@deffn {Scheme Procedure} identifier? obj
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 (@pxref{Hash Tables}) as well as the one
-provided by SRFI-69 (@pxref{SRFI-69}). 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
+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
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.
+@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 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
@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.
+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
@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
+standard libraries---it imports and re-exports all of their exported
+procedures and syntactic forms---with the exception of the following
libraries:
@itemize @bullet
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; (@pxref{Fly Evaluation}) for documentation.
+Guile's code library; @xref{Fly Evaluation}, for documentation.
@end deffn
@deffn {Scheme Procedure} environment import-spec ...
HCoop / bpt / guile.git / blobdiff