@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node SRFI Support
@section SRFI Support Modules
@cindex SRFI
over the available SRFIs and some usage hints. For complete
documentation, design rationales and further examples, we advise you to
get the relevant SRFI documents from the SRFI home page
-@url{http://srfi.schemers.org}.
+@url{http://srfi.schemers.org/}.
@menu
* About SRFI Usage:: What to know about Guile's SRFI support.
* SRFI-17:: Generalized set!
* SRFI-18:: Multithreading support
* SRFI-19:: Time/Date library.
+* SRFI-23:: Error reporting
* SRFI-26:: Specializing parameters
+* SRFI-27:: Sources of Random Bits
* SRFI-30:: Nested multi-line block comments
* SRFI-31:: A special form `rec' for recursive evaluation
* SRFI-34:: Exception handling.
* SRFI-35:: Conditions.
* SRFI-37:: args-fold program argument processor
+* SRFI-38:: External Representation for Data With Shared Structure
* SRFI-39:: Parameter objects
+* SRFI-42:: Eager comprehensions
+* SRFI-45:: Primitives for expressing iterative lazy algorithms
* SRFI-55:: Requiring Features.
* SRFI-60:: Integers as bits.
* SRFI-61:: A more general `cond' clause
+* SRFI-67:: Compare procedures
* SRFI-69:: Basic hash tables.
* SRFI-88:: Keyword objects.
* SRFI-98:: Accessing environment variables.
+* SRFI-105:: Curly-infix expressions.
@end menu
@end deffn
@deffn {Scheme Procedure} take-right lst i
-Return the a list containing the @var{i} last elements of @var{lst}.
+Return a list containing the @var{i} last elements of @var{lst}.
The return shares a common tail with @var{lst}.
@end deffn
@deffn {Scheme Procedure} drop-right lst i
@deffnx {Scheme Procedure} drop-right! lst i
-Return the a list containing all but the @var{i} last elements of
+Return a list containing all but the @var{i} last elements of
@var{lst}.
@code{drop-right} always returns a new list, even when @var{i} is
containing the second elements of each lists, and so on.
@end deffn
-@deffn {Scheme Procedure} count pred lst1 @dots{} lstN
+@deffn {Scheme Procedure} count pred lst1 lst2 @dots{}
Return a count of the number of times @var{pred} returns true when
called on elements from the given lists.
@var{pred} is called with @var{N} parameters @code{(@var{pred}
-@var{elem1} @dots{} @var{elemN})}, each element being from the
-corresponding @var{lst1} @dots{} @var{lstN}. The first call is with
-the first element of each list, the second with the second element
-from each, and so on.
+@var{elem1} @dots{} @var{elemN} )}, each element being from the
+corresponding list. The first call is with the first element of each
+list, the second with the second element from each, and so on.
Counting stops when the end of the shortest list is reached. At least
one list must be non-circular.
@c FIXME::martin: Review me!
-@deffn {Scheme Procedure} fold proc init lst1 @dots{} lstN
-@deffnx {Scheme Procedure} fold-right proc init lst1 @dots{} lstN
-Apply @var{proc} to the elements of @var{lst1} @dots{} @var{lstN} to
+@deffn {Scheme Procedure} fold proc init lst1 lst2 @dots{}
+@deffnx {Scheme Procedure} fold-right proc init lst1 lst2 @dots{}
+Apply @var{proc} to the elements of @var{lst1} @var{lst2} @dots{} to
build a result, and return that result.
-Each @var{proc} call is @code{(@var{proc} @var{elem1} @dots{}
-@var{elemN} @var{previous})}, where @var{elem1} is from @var{lst1},
-through @var{elemN} from @var{lstN}. @var{previous} is the return
+Each @var{proc} call is @code{(@var{proc} @var{elem1} @var{elem2}
+@dots{} @var{previous})}, where @var{elem1} is from @var{lst1},
+@var{elem2} is from @var{lst2}, and so on. @var{previous} is the return
from the previous call to @var{proc}, or the given @var{init} for the
first call. If any list is empty, just @var{init} is returned.
@result{} "xyz"
@end example
-If @var{lst1} through @var{lstN} have different lengths, @code{fold}
+If @var{lst1} @var{lst2} @dots{} have different lengths, @code{fold}
stops when the end of the shortest is reached; @code{fold-right}
-commences at the last element of the shortest. Ie.@: elements past
-the length of the shortest are ignored in the other @var{lst}s. At
-least one @var{lst} must be non-circular.
+commences at the last element of the shortest. Ie.@: elements past the
+length of the shortest are ignored in the other @var{lst}s. At least
+one @var{lst} must be non-circular.
@code{fold} should be preferred over @code{fold-right} if the order of
processing doesn't matter, or can be arranged either way, since
@code{for-each} would have to be written out each time.
@end deffn
-@deffn {Scheme Procedure} pair-fold proc init lst1 @dots{} lstN
-@deffnx {Scheme Procedure} pair-fold-right proc init lst1 @dots{} lstN
+@deffn {Scheme Procedure} pair-fold proc init lst1 lst2 @dots{}
+@deffnx {Scheme Procedure} pair-fold-right proc init lst1 lst2 @dots{}
The same as @code{fold} and @code{fold-right}, but apply @var{proc} to
the pairs of the lists instead of the list elements.
@end deffn
Maps each seed value to the corresponding list element.
@item g
-Maps each seed value to next seed valu.
+Maps each seed value to next seed value.
@item seed
The state value for the unfold.
Maps each seed value to the corresponding list element.
@item g
-Maps each seed value to next seed valu.
+Maps each seed value to next seed value.
@item seed
The state value for the unfold.
to make a new define under a different name.
@end deffn
-@deffn {Scheme Procedure} any pred lst1 lst2 @dots{} lstN
-Test whether any set of elements from @var{lst1} @dots{} lstN
-satisfies @var{pred}. If so the return value is the return from the
-successful @var{pred} call, or if not the return is @code{#f}.
+@deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
+Test whether any set of elements from @var{lst1} @var{lst2} @dots{}
+satisfies @var{pred}. If so, the return value is the return value from
+the successful @var{pred} call, or if not, the return value is
+@code{#f}.
-Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{}
-@var{elemN})} taking an element from each @var{lst}. The calls are
-made successively for the first, second, etc elements of the lists,
-stopping when @var{pred} returns non-@code{#f}, or when the end of the
-shortest list is reached.
+If there are n list arguments, then @var{pred} must be a predicate
+taking n arguments. Each @var{pred} call is @code{(@var{pred}
+@var{elem1} @var{elem2} @dots{} )} taking an element from each
+@var{lst}. The calls are made successively for the first, second, etc.
+elements of the lists, stopping when @var{pred} returns non-@code{#f},
+or when the end of the shortest list is reached.
-The @var{pred} call on the last set of elements (ie.@: when the end of
+The @var{pred} call on the last set of elements (i.e., when the end of
the shortest list has been reached), if that point is reached, is a
tail call.
@end deffn
-@deffn {Scheme Procedure} every pred lst1 lst2 @dots{} lstN
-Test whether every set of elements from @var{lst1} @dots{} lstN
-satisfies @var{pred}. If so the return value is the return from the
-final @var{pred} call, or if not the return is @code{#f}.
+@deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
+Test whether every set of elements from @var{lst1} @var{lst2} @dots{}
+satisfies @var{pred}. If so, the return value is the return from the
+final @var{pred} call, or if not, the return value is @code{#f}.
-Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{}
-@var{elemN})} taking an element from each @var{lst}. The calls are
-made successively for the first, second, etc elements of the lists,
-stopping if @var{pred} returns @code{#f}, or when the end of any of
-the lists is reached.
+If there are n list arguments, then @var{pred} must be a predicate
+taking n arguments. Each @var{pred} call is @code{(@var{pred}
+@var{elem1} @var{elem2 @dots{}})} taking an element from each
+@var{lst}. The calls are made successively for the first, second, etc.
+elements of the lists, stopping if @var{pred} returns @code{#f}, or when
+the end of any of the lists is reached.
-The @var{pred} call on the last set of elements (ie.@: when the end of
+The @var{pred} call on the last set of elements (i.e., when the end of
the shortest list has been reached) is a tail call.
-If one of @var{lst1} @dots{} @var{lstN} is empty then no calls to
-@var{pred} are made, and the return is @code{#t}.
+If one of @var{lst1} @var{lst2} @dots{}is empty then no calls to
+@var{pred} are made, and the return value is @code{#t}.
@end deffn
-@deffn {Scheme Procedure} list-index pred lst1 @dots{} lstN
+@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
Return the index of the first set of elements, one from each of
-@var{lst1}@dots{}@var{lstN}, which satisfies @var{pred}.
+@var{lst1} @var{lst2} @dots{}, which satisfies @var{pred}.
-@var{pred} is called as @code{(@var{pred} elem1 @dots{} elemN)}.
+@var{pred} is called as @code{(@var{elem1} @var{elem2 @dots{}})}.
Searching stops when the end of the shortest @var{lst} is reached.
The return index starts from 0 for the first set of elements. If no
-set of elements pass then the return is @code{#f}.
+set of elements pass, then the return value is @code{#f}.
@example
(list-index odd? '(2 4 6 9)) @result{} 3
taking an optional @var{=} comparison procedure.
The default comparison is @code{equal?}. If an @var{=} parameter is
-given it's called @code{(@var{=} @var{key} @var{alistcar})}, ie. the
+given it's called @code{(@var{=} @var{key} @var{alistcar})}, i.e.@: the
given target @var{key} is the first argument, and a @code{car} from
@var{alist} is second.
Equality is determined by the @var{=} predicate, or @code{equal?} if
not given. The order in which elements are tested is unspecified, but
-each equality call is made @code{(= key alistkey)}, ie. the given
+each equality call is made @code{(= key alistkey)}, i.e.@: the given
@var{key} parameter is first and the key from @var{alist} second.
This means for instance all associations with a key greater than 5 can
be removed with @code{(alist-delete 5 alist <)}.
@code{eq?} then they must also be equal under the predicate. This
simply means a given object must be equal to itself.
-@deffn {Scheme Procedure} lset<= = list1 list2 @dots{}
+@deffn {Scheme Procedure} lset<= = list @dots{}
Return @code{#t} if each list is a subset of the one following it.
-Ie.@: @var{list1} a subset of @var{list2}, @var{list2} a subset of
-@var{list3}, etc, for as many lists as given. If only one list or no
-lists are given then the return is @code{#t}.
+I.e., @var{list1} is a subset of @var{list2}, @var{list2} is a subset of
+@var{list3}, etc., for as many lists as given. If only one list or no
+lists are given, the return value is @code{#t}.
A list @var{x} is a subset of @var{y} if each element of @var{x} is
equal to some element in @var{y}. Elements are compared using the
@end example
@end deffn
-@deffn {Scheme Procedure} lset= = list1 list2 @dots{}
+@deffn {Scheme Procedure} lset= = list @dots{}
Return @code{#t} if all argument lists are set-equal. @var{list1} is
-compared to @var{list2}, @var{list2} to @var{list3}, etc, for as many
-lists as given. If only one list or no lists are given then the
-return is @code{#t}.
+compared to @var{list2}, @var{list2} to @var{list3}, etc., for as many
+lists as given. If only one list or no lists are given, the return
+value is @code{#t}.
Two lists @var{x} and @var{y} are set-equal if each element of @var{x}
is equal to some element of @var{y} and conversely each element of
@end example
@end deffn
-@deffn {Scheme Procedure} lset-adjoin = list elem1 @dots{}
-Add to @var{list} any of the given @var{elem}s not already in the
-list. @var{elem}s are @code{cons}ed onto the start of @var{list} (so
-the return shares a common tail with @var{list}), but the order
-they're added is unspecified.
+@deffn {Scheme Procedure} lset-adjoin = list elem @dots{}
+Add to @var{list} any of the given @var{elem}s not already in the list.
+@var{elem}s are @code{cons}ed onto the start of @var{list} (so the
+return value shares a common tail with @var{list}), but the order that
+the @var{elem}s are added is unspecified.
The given @var{=} procedure is used for comparing elements, called as
-@code{(@var{=} listelem elem)}, ie.@: the second argument is one of
+@code{(@var{=} listelem elem)}, i.e., the second argument is one of
the given @var{elem} parameters.
@example
@end example
@end deffn
-@deffn {Scheme Procedure} lset-union = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-union! = list1 list2 @dots{}
+@deffn {Scheme Procedure} lset-union = list @dots{}
+@deffnx {Scheme Procedure} lset-union! = list @dots{}
Return the union of the argument list sets. The result is built by
taking the union of @var{list1} and @var{list2}, then the union of
-that with @var{list3}, etc, for as many lists as given. For one list
+that with @var{list3}, etc., for as many lists as given. For one list
argument that list itself is the result, for no list arguments the
result is the empty list.
@var{list1} to form its results.
@end deffn
-@deffn {Scheme Procedure} lset-xor = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-xor! = list1 list2 @dots{}
+@deffn {Scheme Procedure} lset-xor = list @dots{}
+@deffnx {Scheme Procedure} lset-xor! = list @dots{}
Return an XOR of the argument lists. For two lists this means those
elements which are in exactly one of the lists. For more than two
lists it means those elements which appear in an odd number of the
(use-modules (srfi srfi-2))
@end lisp
+or alternatively
+
+@lisp
+(use-modules (ice-9 and-let-star))
+@end lisp
+
@deffn {library syntax} and-let* (clause @dots{}) body @dots{}
A combination of @code{and} and @code{let*}.
@deffnx {Scheme Procedure} make-f64vector n [value]
@deffnx {Scheme Procedure} make-c32vector n [value]
@deffnx {Scheme Procedure} make-c64vector n [value]
-@deffnx {C Function} scm_make_u8vector n [value]
-@deffnx {C Function} scm_make_s8vector n [value]
-@deffnx {C Function} scm_make_u16vector n [value]
-@deffnx {C Function} scm_make_s16vector n [value]
-@deffnx {C Function} scm_make_u32vector n [value]
-@deffnx {C Function} scm_make_s32vector n [value]
-@deffnx {C Function} scm_make_u64vector n [value]
-@deffnx {C Function} scm_make_s64vector n [value]
-@deffnx {C Function} scm_make_f32vector n [value]
-@deffnx {C Function} scm_make_f64vector n [value]
-@deffnx {C Function} scm_make_c32vector n [value]
-@deffnx {C Function} scm_make_c64vector n [value]
+@deffnx {C Function} scm_make_u8vector (n, value)
+@deffnx {C Function} scm_make_s8vector (n, value)
+@deffnx {C Function} scm_make_u16vector (n, value)
+@deffnx {C Function} scm_make_s16vector (n, value)
+@deffnx {C Function} scm_make_u32vector (n, value)
+@deffnx {C Function} scm_make_s32vector (n, value)
+@deffnx {C Function} scm_make_u64vector (n, value)
+@deffnx {C Function} scm_make_s64vector (n, value)
+@deffnx {C Function} scm_make_f32vector (n, value)
+@deffnx {C Function} scm_make_f64vector (n, value)
+@deffnx {C Function} scm_make_c32vector (n, value)
+@deffnx {C Function} scm_make_c64vector (n, value)
Return a newly allocated homogeneous numeric vector holding @var{n}
elements of the indicated type. If @var{value} is given, the vector
is initialized with that value, otherwise the contents are
@deffnx {Scheme Procedure} f64vector-ref vec i
@deffnx {Scheme Procedure} c32vector-ref vec i
@deffnx {Scheme Procedure} c64vector-ref vec i
-@deffnx {C Function} scm_u8vector_ref (vec i)
-@deffnx {C Function} scm_s8vector_ref (vec i)
-@deffnx {C Function} scm_u16vector_ref (vec i)
-@deffnx {C Function} scm_s16vector_ref (vec i)
-@deffnx {C Function} scm_u32vector_ref (vec i)
-@deffnx {C Function} scm_s32vector_ref (vec i)
-@deffnx {C Function} scm_u64vector_ref (vec i)
-@deffnx {C Function} scm_s64vector_ref (vec i)
-@deffnx {C Function} scm_f32vector_ref (vec i)
-@deffnx {C Function} scm_f64vector_ref (vec i)
-@deffnx {C Function} scm_c32vector_ref (vec i)
-@deffnx {C Function} scm_c64vector_ref (vec i)
+@deffnx {C Function} scm_u8vector_ref (vec, i)
+@deffnx {C Function} scm_s8vector_ref (vec, i)
+@deffnx {C Function} scm_u16vector_ref (vec, i)
+@deffnx {C Function} scm_s16vector_ref (vec, i)
+@deffnx {C Function} scm_u32vector_ref (vec, i)
+@deffnx {C Function} scm_s32vector_ref (vec, i)
+@deffnx {C Function} scm_u64vector_ref (vec, i)
+@deffnx {C Function} scm_s64vector_ref (vec, i)
+@deffnx {C Function} scm_f32vector_ref (vec, i)
+@deffnx {C Function} scm_f64vector_ref (vec, i)
+@deffnx {C Function} scm_c32vector_ref (vec, i)
+@deffnx {C Function} scm_c64vector_ref (vec, i)
Return the element at index @var{i} in @var{vec}. The first element
in @var{vec} is index 0.
@end deffn
@deffnx {Scheme Procedure} f64vector-set! vec i value
@deffnx {Scheme Procedure} c32vector-set! vec i value
@deffnx {Scheme Procedure} c64vector-set! vec i value
-@deffnx {C Function} scm_u8vector_set_x (vec i value)
-@deffnx {C Function} scm_s8vector_set_x (vec i value)
-@deffnx {C Function} scm_u16vector_set_x (vec i value)
-@deffnx {C Function} scm_s16vector_set_x (vec i value)
-@deffnx {C Function} scm_u32vector_set_x (vec i value)
-@deffnx {C Function} scm_s32vector_set_x (vec i value)
-@deffnx {C Function} scm_u64vector_set_x (vec i value)
-@deffnx {C Function} scm_s64vector_set_x (vec i value)
-@deffnx {C Function} scm_f32vector_set_x (vec i value)
-@deffnx {C Function} scm_f64vector_set_x (vec i value)
-@deffnx {C Function} scm_c32vector_set_x (vec i value)
-@deffnx {C Function} scm_c64vector_set_x (vec i value)
+@deffnx {C Function} scm_u8vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s8vector_set_x (vec, i, value)
+@deffnx {C Function} scm_u16vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s16vector_set_x (vec, i, value)
+@deffnx {C Function} scm_u32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_u64vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s64vector_set_x (vec, i, value)
+@deffnx {C Function} scm_f32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_f64vector_set_x (vec, i, value)
+@deffnx {C Function} scm_c32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_c64vector_set_x (vec, i, value)
Set the element at index @var{i} in @var{vec} to @var{value}. The
first element in @var{vec} is index 0. The return value is
unspecified.
@deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
-@deftypefnx {C Function} {const float *} scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
+@deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
-@deftypefnx {C Function} {float *} scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
+@deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@end deffn
@deffn {Scheme Procedure} uniform-vector-ref vec i
-@deffnx {C Function} scm_uniform_vector_ref (vec i)
+@deffnx {C Function} scm_uniform_vector_ref (vec, i)
Return the element at index @var{i} in @var{vec}. The first element
in @var{vec} is index 0.
@end deffn
@deffn {Scheme Procedure} uniform-vector-set! vec i value
-@deffnx {C Function} scm_uniform_vector_set_x (vec i value)
+@deffnx {C Function} scm_uniform_vector_set_x (vec, i, value)
Set the element at index @var{i} in @var{vec} to @var{value}. The
first element in @var{vec} is index 0. The return value is
unspecified.
the core @code{record-type-fields} etc, and are referred to in the
subsequent accessor/modifier forms.
-@var{predictate} is bound to a function to be called as
+@var{predicate} is bound to a function to be called as
@code{(@var{predicate} obj)}. It returns @code{#t} or @code{#f}
according to whether @var{obj} is a record of this type.
top-level @code{define}s. They can be redefined or @code{set!} as
desired, exported from a module, etc.
+@unnumberedsubsubsec Non-toplevel Record Definitions
+
+The SRFI-9 specification explicitly disallows record definitions in a
+non-toplevel context, such as inside @code{lambda} body or inside a
+@var{let} block. However, Guile's implementation does not enforce that
+restriction.
+
+@unnumberedsubsubsec Custom Printers
+
+You may use @code{set-record-type-printer!} to customize the default printing
+behavior of records. This is a Guile extension and is not part of SRFI-9. It
+is located in the @nicode{(srfi srfi-9 gnu)} module.
+
+@deffn {Scheme Syntax} set-record-type-printer! name thunk
+Where @var{type} corresponds to the first argument of @code{define-record-type},
+and @var{thunk} is a procedure accepting two arguments, the record to print, and
+an output port.
+@end deffn
+
+@noindent
+This example prints the employee's name in brackets, for instance @code{[Fred]}.
+
+@example
+(set-record-type-printer! employee-type
+ (lambda (record port)
+ (write-char #\[ port)
+ (display (get-employee-name record) port)
+ (write-char #\] port)))
+@end example
@node SRFI-10
@subsection SRFI-10 - Hash-Comma Reader Extension
@deffn {Scheme Procedure} define-reader-ctor tag proc
Register @var{proc} as the constructor for a hash-comma read syntax
-starting with symbol @var{tag}, ie. @nicode{#,(@var{tag} arg@dots{})}.
+starting with symbol @var{tag}, i.e.@: @nicode{#,(@var{tag} arg@dots{})}.
@var{proc} is called with the given arguments @code{(@var{proc}
arg@dots{})} and the object it returns is the result of the read.
@end deffn
Wait for @var{thread} to terminate and return its exit value. When a
time value @var{timeout} is given, it specifies a point in time where
the waiting should be aborted. When the waiting is aborted,
-@var{timeoutval} is returned if it is specified; otherwise, a
+@var{timeout-val} is returned if it is specified; otherwise, a
@code{join-timeout-exception} exception is raised
(@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the
thread was terminated by a call to @code{thread-terminate!}
@end defun
@defun condition-variable-name condition-variable
-Returns the name assigned to @var{thread} at the time of its creation,
-or @code{#f} if it was not given a name.
+Returns the name assigned to @var{condition-variable} at the time of its
+creation, or @code{#f} if it was not given a name.
@end defun
@defun condition-variable-specific condition-variable
@item @nicode{~z} @tab time zone, RFC-822 style
@item @nicode{~Z} @tab time zone symbol (not currently implemented)
@item @nicode{~1} @tab ISO-8601 date, @samp{~Y-~m-~d}
-@item @nicode{~2} @tab ISO-8601 time+zone, @samp{~k:~M:~S~z}
-@item @nicode{~3} @tab ISO-8601 time, @samp{~k:~M:~S}
-@item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~k:~M:~S~z}
-@item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~k:~M:~S}
+@item @nicode{~2} @tab ISO-8601 time+zone, @samp{~H:~M:~S~z}
+@item @nicode{~3} @tab ISO-8601 time, @samp{~H:~M:~S}
+@item @nicode{~4} @tab ISO-8601 date/time+zone, @samp{~Y-~m-~dT~H:~M:~S~z}
+@item @nicode{~5} @tab ISO-8601 date/time, @samp{~Y-~m-~dT~H:~M:~S}
@end multitable
@end defun
@cindex date, from string
@c FIXME: Can we say what happens when an incomplete date is
-@c converted? Ie. fields left as 0, or what? The spec seems to be
+@c converted? I.e. fields left as 0, or what? The spec seems to be
@c silent on this.
@defun string->date input template
locale.
@end defun
+@node SRFI-23
+@subsection SRFI-23 - Error Reporting
+@cindex SRFI-23
+
+The SRFI-23 @code{error} procedure is always available.
@node SRFI-26
@subsection SRFI-26 - specializing parameters
(use-modules (srfi srfi-26))
@end example
-@deffn {library syntax} cut slot @dots{}
-@deffnx {library syntax} cute slot @dots{}
-Return a new procedure which will make a call (@var{slot} @dots{}) but
-with selected parameters specialized to given expressions.
+@deffn {library syntax} cut slot1 slot2 @dots{}
+@deffnx {library syntax} cute slot1 slot2 @dots{}
+Return a new procedure which will make a call (@var{slot1} @var{slot2}
+@dots{}) but with selected parameters specialized to given expressions.
An example will illustrate the idea. The following is a
specialization of @code{write}, sending output to
@end example
@end deffn
+@node SRFI-27
+@subsection SRFI-27 - Sources of Random Bits
+@cindex SRFI-27
+
+This subsection is based on the
+@uref{http://srfi.schemers.org/srfi-27/srfi-27.html, specification of
+SRFI-27} written by Sebastian Egner.
+
+@c The copyright notice and license text of the SRFI-27 specification is
+@c reproduced below:
+
+@c Copyright (C) Sebastian Egner (2002). All Rights Reserved.
+
+@c Permission is hereby granted, free of charge, to any person obtaining a
+@c copy of this software and associated documentation files (the
+@c "Software"), to deal in the Software without restriction, including
+@c without limitation the rights to use, copy, modify, merge, publish,
+@c distribute, sublicense, and/or sell copies of the Software, and to
+@c permit persons to whom the Software is furnished to do so, subject to
+@c the following conditions:
+
+@c The above copyright notice and this permission notice shall be included
+@c in all copies or substantial portions of the Software.
+
+@c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+@c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+@c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+@c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+@c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+@c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+@c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+This SRFI provides access to a (pseudo) random number generator; for
+Guile's built-in random number facilities, which SRFI-27 is implemented
+upon, @xref{Random}. With SRFI-27, random numbers are obtained from a
+@emph{random source}, which encapsulates a random number generation
+algorithm and its state.
+
+@menu
+* SRFI-27 Default Random Source:: Obtaining random numbers
+* SRFI-27 Random Sources:: Creating and manipulating random sources
+* SRFI-27 Random Number Generators:: Obtaining random number generators
+@end menu
+
+@node SRFI-27 Default Random Source
+@subsubsection The Default Random Source
+@cindex SRFI-27
+
+@defun random-integer n
+Return a random number between zero (inclusive) and @var{n} (exclusive),
+using the default random source. The numbers returned have a uniform
+distribution.
+@end defun
+
+@defun random-real
+Return a random number in (0,1), using the default random source. The
+numbers returned have a uniform distribution.
+@end defun
+
+@defun default-random-source
+A random source from which @code{random-integer} and @code{random-real}
+have been derived using @code{random-source-make-integers} and
+@code{random-source-make-reals} (@pxref{SRFI-27 Random Number Generators}
+for those procedures). Note that an assignment to
+@code{default-random-source} does not change @code{random-integer} or
+@code{random-real}; it is also strongly recommended not to assign a new
+value.
+@end defun
+
+@node SRFI-27 Random Sources
+@subsubsection Random Sources
+@cindex SRFI-27
+
+@defun make-random-source
+Create a new random source. The stream of random numbers obtained from
+each random source created by this procedure will be identical, unless
+its state is changed by one of the procedures below.
+@end defun
+
+@defun random-source? object
+Tests whether @var{object} is a random source. Random sources are a
+disjoint type.
+@end defun
+
+@defun random-source-randomize! source
+Attempt to set the state of the random source to a truly random value.
+The current implementation uses a seed based on the current system time.
+@end defun
+
+@defun random-source-pseudo-randomize! source i j
+Changes the state of the random source s into the initial state of the
+(@var{i}, @var{j})-th independent random source, where @var{i} and
+@var{j} are non-negative integers. This procedure provides a mechanism
+to obtain a large number of independent random sources (usually all
+derived from the same backbone generator), indexed by two integers. In
+contrast to @code{random-source-randomize!}, this procedure is entirely
+deterministic.
+@end defun
+
+The state associated with a random state can be obtained an reinstated
+with the following procedures:
+
+@defun random-source-state-ref source
+@defunx random-source-state-set! source state
+Get and set the state of a random source. No assumptions should be made
+about the nature of the state object, besides it having an external
+representation (i.e.@: it can be passed to @code{write} and subsequently
+@code{read} back).
+@end defun
+
+@node SRFI-27 Random Number Generators
+@subsubsection Obtaining random number generator procedures
+@cindex SRFI-27
+
+@defun random-source-make-integers source
+Obtains a procedure to generate random integers using the random source
+@var{source}. The returned procedure takes a single argument @var{n},
+which must be a positive integer, and returns the next uniformly
+distributed random integer from the interval @{0, ..., @var{n}-1@} by
+advancing the state of @var{source}.
+
+If an application obtains and uses several generators for the same
+random source @var{source}, a call to any of these generators advances
+the state of @var{source}. Hence, the generators do not produce the
+same sequence of random integers each but rather share a state. This
+also holds for all other types of generators derived from a fixed random
+sources.
+
+While the SRFI text specifies that ``Implementations that support
+concurrency make sure that the state of a generator is properly
+advanced'', this is currently not the case in Guile's implementation of
+SRFI-27, as it would cause a severe performance penalty. So in
+multi-threaded programs, you either must perform locking on random
+sources shared between threads yourself, or use different random sources
+for multiple threads.
+@end defun
+
+@defun random-source-make-reals source
+@defunx random-source-make-reals source unit
+Obtains a procedure to generate random real numbers @math{0 < x < 1}
+using the random source @var{source}. The procedure rand is called
+without arguments.
+
+The optional parameter @var{unit} determines the type of numbers being
+produced by the returned procedure and the quantization of the output.
+@var{unit} must be a number such that @math{0 < @var{unit} < 1}. The
+numbers created by the returned procedure are of the same numerical type
+as @var{unit} and the potential output values are spaced by at most
+@var{unit}. One can imagine rand to create numbers as @var{x} *
+@var{unit} where @var{x} is a random integer in @{1, ...,
+floor(1/unit)-1@}. Note, however, that this need not be the way the
+values are actually created and that the actual resolution of rand can
+be much higher than unit. In case @var{unit} is absent it defaults to a
+reasonably small value (related to the width of the mantissa of an
+efficient number format).
+@end defun
+
@node SRFI-30
@subsection SRFI-30 - Nested Multi-line Comments
@cindex SRFI-30
Note that all fields of @var{type} and its supertypes must be specified.
@end deffn
-@deffn {Scheme Procedure} make-compound-condition . conditions
+@deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{}
Return a new compound condition composed of @var{conditions}. The
returned condition has the type of each condition of @var{conditions}
(per @code{condition-has-type?}).
If @var{c} is a compound condition and several underlying condition
types contain a field named @var{field-name}, then the value of the
first such field is returned, using the order in which conditions were
-passed to @var{make-compound-condition}.
+passed to @code{make-compound-condition}.
@end deffn
@deffn {Scheme Procedure} extract-condition c type
@end lisp
@end deffn
-@deffn {library syntax} condition type-field-bindings...
-Return a new condition, or compound condition, initialized according to
-@var{type-field-bindings}. Each @var{type-field-binding} must have the
-form @code{(type field-specs...)}, where @var{type} is the name of a
-variable bound to condition type; each @var{field-spec} must have the
-form @code{(field-name value)} where @var{field-name} is a symbol
-denoting the field being initialized to @var{value}. As for
+@deffn {library syntax} condition type-field-binding1 type-field-binding2 @dots{}
+Return a new condition or compound condition, initialized according to
+@var{type-field-binding1} @var{type-field-binding2} @enddots{}. Each
+@var{type-field-binding} must have the form @code{(type
+field-specs...)}, where @var{type} is the name of a variable bound to a
+condition type; each @var{field-spec} must have the form
+@code{(field-name value)} where @var{field-name} is a symbol denoting
+the field being initialized to @var{value}. As for
@code{make-condition}, all fields must be specified.
The following example returns a simple condition:
Return true if @var{c} is of type @code{&error} or one of its subtypes.
@end deffn
-
@node SRFI-37
@subsection SRFI-37 - args-fold
@cindex SRFI-37
described above for @code{option}.
@end deffn
-@deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seeds @dots{}
-Process @var{args}, a list of program arguments such as that returned
-by @code{(cdr (program-arguments))}, in order against @var{options}, a
-list of option objects as described above. All functions called take
-the ``seeds'', or the last multiple-values as multiple arguments,
-starting with @var{seeds}, and must return the new seeds. Return the
+@deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seed @dots{}
+Process @var{args}, a list of program arguments such as that returned by
+@code{(cdr (program-arguments))}, in order against @var{options}, a list
+of option objects as described above. All functions called take the
+``seeds'', or the last multiple-values as multiple arguments, starting
+with @var{seed} @dots{}, and must return the new seeds. Return the
final seeds.
Call @code{unrecognized-option-proc}, which is like an option object's
called with the argument in question, as well as the seeds.
@end deffn
-
-@node SRFI-39
-@subsection SRFI-39 - Parameters
-@cindex SRFI-39
-@cindex parameter object
-@tindex Parameter
-
-This SRFI provides parameter objects, which implement dynamically
-bound locations for values. The functions below are available from
+@node SRFI-38
+@subsection SRFI-38 - External Representation for Data With Shared Structure
+@cindex SRFI-38
+
+This subsection is based on
+@uref{http://srfi.schemers.org/srfi-38/srfi-38.html, the specification
+of SRFI-38} written by Ray Dillinger.
+
+@c Copyright (C) Ray Dillinger 2003. All Rights Reserved.
+
+@c Permission is hereby granted, free of charge, to any person obtaining a
+@c copy of this software and associated documentation files (the
+@c "Software"), to deal in the Software without restriction, including
+@c without limitation the rights to use, copy, modify, merge, publish,
+@c distribute, sublicense, and/or sell copies of the Software, and to
+@c permit persons to whom the Software is furnished to do so, subject to
+@c the following conditions:
+
+@c The above copyright notice and this permission notice shall be included
+@c in all copies or substantial portions of the Software.
+
+@c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+@c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+@c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+@c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+@c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+@c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+@c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+This SRFI creates an alternative external representation for data
+written and read using @code{write-with-shared-structure} and
+@code{read-with-shared-structure}. It is identical to the grammar for
+external representation for data written and read with @code{write} and
+@code{read} given in section 7 of R5RS, except that the single
+production
@example
-(use-modules (srfi srfi-39))
+<datum> --> <simple datum> | <compound datum>
@end example
-A parameter object is a procedure. Called with no arguments it
-returns its value, called with one argument it sets the value.
+is replaced by the following five productions:
@example
-(define my-param (make-parameter 123))
-(my-param) @result{} 123
-(my-param 456)
-(my-param) @result{} 456
+<datum> --> <defining datum> | <nondefining datum> | <defined datum>
+<defining datum> --> #<indexnum>=<nondefining datum>
+<defined datum> --> #<indexnum>#
+<nondefining datum> --> <simple datum> | <compound datum>
+<indexnum> --> <digit 10>+
@end example
-The @code{parameterize} special form establishes new locations for
-parameters, those new locations having effect within the dynamic scope
-of the @code{parameterize} body. Leaving restores the previous
-locations, or re-entering through a saved continuation will again use
-the new locations.
+@deffn {Scheme procedure} write-with-shared-structure obj
+@deffnx {Scheme procedure} write-with-shared-structure obj port
+@deffnx {Scheme procedure} write-with-shared-structure obj port optarg
+
+Writes an external representation of @var{obj} to the given port.
+Strings that appear in the written representation are enclosed in
+doublequotes, and within those strings backslash and doublequote
+characters are escaped by backslashes. Character objects are written
+using the @code{#\} notation.
+
+Objects which denote locations rather than values (cons cells, vectors,
+and non-zero-length strings in R5RS scheme; also Guile's structs,
+bytevectors and ports and hash-tables), if they appear at more than one
+point in the data being written, are preceded by @samp{#@var{N}=} the
+first time they are written and replaced by @samp{#@var{N}#} all
+subsequent times they are written, where @var{N} is a natural number
+used to identify that particular object. If objects which denote
+locations occur only once in the structure, then
+@code{write-with-shared-structure} must produce the same external
+representation for those objects as @code{write}.
+
+@code{write-with-shared-structure} terminates in finite time and
+produces a finite representation when writing finite data.
+
+@code{write-with-shared-structure} returns an unspecified value. The
+@var{port} argument may be omitted, in which case it defaults to the
+value returned by @code{(current-output-port)}. The @var{optarg}
+argument may also be omitted. If present, its effects on the output and
+return value are unspecified but @code{write-with-shared-structure} must
+still write a representation that can be read by
+@code{read-with-shared-structure}. Some implementations may wish to use
+@var{optarg} to specify formatting conventions, numeric radixes, or
+return values. Guile's implementation ignores @var{optarg}.
+
+For example, the code
-@example
-(parameterize ((my-param 789))
- (my-param) @result{} 789
- )
-(my-param) @result{} 456
-@end example
+@lisp
+(begin (define a (cons 'val1 'val2))
+ (set-cdr! a a)
+ (write-with-shared-structure a))
+@end lisp
-Parameters are like dynamically bound variables in other Lisp dialects.
-They allow an application to establish parameter settings (as the name
-suggests) just for the execution of a particular bit of code,
-restoring when done. Examples of such parameters might be
-case-sensitivity for a search, or a prompt for user input.
+should produce the output @code{#1=(val1 . #1#)}. This shows a cons
+cell whose @code{cdr} contains itself.
-Global variables are not as good as parameter objects for this sort of
-thing. Changes to them are visible to all threads, but in Guile
-parameter object locations are per-thread, thereby truly limiting the
-effect of @code{parameterize} to just its dynamic execution.
+@end deffn
-Passing arguments to functions is thread-safe, but that soon becomes
-tedious when there's more than a few or when they need to pass down
-through several layers of calls before reaching the point they should
-affect. And introducing a new setting to existing code is often
-easier with a parameter object than adding arguments.
+@deffn {Scheme procedure} read-with-shared-structure
+@deffnx {Scheme procedure} read-with-shared-structure port
+@code{read-with-shared-structure} converts the external representations
+of Scheme objects produced by @code{write-with-shared-structure} into
+Scheme objects. That is, it is a parser for the nonterminal
+@samp{<datum>} in the augmented external representation grammar defined
+above. @code{read-with-shared-structure} returns the next object
+parsable from the given input port, updating @var{port} to point to the
+first character past the end of the external representation of the
+object.
-@sp 1
-@defun make-parameter init [converter]
-Return a new parameter object, with initial value @var{init}.
+If an end-of-file is encountered in the input before any characters are
+found that can begin an object, then an end-of-file object is returned.
+The port remains open, and further attempts to read it (by
+@code{read-with-shared-structure} or @code{read} will also return an
+end-of-file object. If an end of file is encountered after the
+beginning of an object's external representation, but the external
+representation is incomplete and therefore not parsable, an error is
+signalled.
-A parameter object is a procedure. When called @code{(param)} it
-returns its value, or a call @code{(param val)} sets its value. For
-example,
+The @var{port} argument may be omitted, in which case it defaults to the
+value returned by @code{(current-input-port)}. It is an error to read
+from a closed port.
-@example
-(define my-param (make-parameter 123))
-(my-param) @result{} 123
+@end deffn
-(my-param 456)
-(my-param) @result{} 456
-@end example
+@node SRFI-39
+@subsection SRFI-39 - Parameters
+@cindex SRFI-39
-If a @var{converter} is given, then a call @code{(@var{converter}
-val)} is made for each value set, its return is the value stored.
-Such a call is made for the @var{init} initial value too.
+This SRFI adds support for dynamically-scoped parameters. SRFI 39 is
+implemented in the Guile core; there's no module needed to get SRFI-39
+itself. Parameters are documented in @ref{Parameters}.
-A @var{converter} allows values to be validated, or put into a
-canonical form. For example,
+This module does export one extra function: @code{with-parameters*}.
+This is a Guile-specific addition to the SRFI, similar to the core
+@code{with-fluids*} (@pxref{Fluids and Dynamic States}).
-@example
-(define my-param (make-parameter 123
- (lambda (val)
- (if (not (number? val))
- (error "must be a number"))
- (inexact->exact val))))
-(my-param 0.75)
-(my-param) @result{} 3/4
-@end example
+@defun with-parameters* param-list value-list thunk
+Establish a new dynamic scope, as per @code{parameterize} above,
+taking parameters from @var{param-list} and corresponding values from
+@var{value-list}. A call @code{(@var{thunk})} is made in the new
+scope and the result from that @var{thunk} is the return from
+@code{with-parameters*}.
@end defun
-@deffn {library syntax} parameterize ((param value) @dots{}) body @dots{}
-Establish a new dynamic scope with the given @var{param}s bound to new
-locations and set to the given @var{value}s. @var{body} is evaluated
-in that environment, the result is the return from the last form in
-@var{body}.
+@node SRFI-42
+@subsection SRFI-42 - Eager Comprehensions
+@cindex SRFI-42
+
+See @uref{http://srfi.schemers.org/srfi-42/srfi-42.html, the
+specification of SRFI-42}.
+
+@node SRFI-45
+@subsection SRFI-45 - Primitives for Expressing Iterative Lazy Algorithms
+@cindex SRFI-45
+
+This subsection is based on @uref{http://srfi.schemers.org/srfi-45/srfi-45.html, the
+specification of SRFI-45} written by Andr@'e van Tonder.
+
+@c Copyright (C) André van Tonder (2003). All Rights Reserved.
+
+@c Permission is hereby granted, free of charge, to any person obtaining a
+@c copy of this software and associated documentation files (the
+@c "Software"), to deal in the Software without restriction, including
+@c without limitation the rights to use, copy, modify, merge, publish,
+@c distribute, sublicense, and/or sell copies of the Software, and to
+@c permit persons to whom the Software is furnished to do so, subject to
+@c the following conditions:
+
+@c The above copyright notice and this permission notice shall be included
+@c in all copies or substantial portions of the Software.
+
+@c THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+@c OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+@c MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+@c NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+@c LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+@c OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+@c WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Lazy evaluation is traditionally simulated in Scheme using @code{delay}
+and @code{force}. However, these primitives are not powerful enough to
+express a large class of lazy algorithms that are iterative. Indeed, it
+is folklore in the Scheme community that typical iterative lazy
+algorithms written using delay and force will often require unbounded
+memory.
+
+This SRFI provides set of three operations: @{@code{lazy}, @code{delay},
+@code{force}@}, which allow the programmer to succinctly express lazy
+algorithms while retaining bounded space behavior in cases that are
+properly tail-recursive. A general recipe for using these primitives is
+provided. An additional procedure @code{eager} is provided for the
+construction of eager promises in cases where efficiency is a concern.
+
+Although this SRFI redefines @code{delay} and @code{force}, the
+extension is conservative in the sense that the semantics of the subset
+@{@code{delay}, @code{force}@} in isolation (i.e., as long as the
+program does not use @code{lazy}) agrees with that in R5RS. In other
+words, no program that uses the R5RS definitions of delay and force will
+break if those definition are replaced by the SRFI-45 definitions of
+delay and force.
+
+@deffn {Scheme Syntax} delay expression
+Takes an expression of arbitrary type @var{a} and returns a promise of
+type @code{(Promise @var{a})} which at some point in the future may be
+asked (by the @code{force} procedure) to evaluate the expression and
+deliver the resulting value.
+@end deffn
-Each @var{param} is an expression which is evaluated to get the
-parameter object. Often this will just be the name of a variable
-holding the object, but it can be anything that evaluates to a
-parameter.
+@deffn {Scheme Syntax} lazy expression
+Takes an expression of type @code{(Promise @var{a})} and returns a
+promise of type @code{(Promise @var{a})} which at some point in the
+future may be asked (by the @code{force} procedure) to evaluate the
+expression and deliver the resulting promise.
+@end deffn
-The @var{param} expressions and @var{value} expressions are all
-evaluated before establishing the new dynamic bindings, and they're
-evaluated in an unspecified order.
+@deffn {Scheme Procedure} force expression
+Takes an argument of type @code{(Promise @var{a})} and returns a value
+of type @var{a} as follows: If a value of type @var{a} has been computed
+for the promise, this value is returned. Otherwise, the promise is
+first evaluated, then overwritten by the obtained promise or value, and
+then force is again applied (iteratively) to the promise.
+@end deffn
-For example,
+@deffn {Scheme Procedure} eager expression
+Takes an argument of type @var{a} and returns a value of type
+@code{(Promise @var{a})}. As opposed to @code{delay}, the argument is
+evaluated eagerly. Semantically, writing @code{(eager expression)} is
+equivalent to writing
-@example
-(define prompt (make-parameter "Type something: "))
-(define (get-input)
- (display (prompt))
- ...)
-
-(parameterize ((prompt "Type a number: "))
- (get-input)
- ...)
-@end example
-@end deffn
+@lisp
+(let ((value expression)) (delay value)).
+@end lisp
+
+However, the former is more efficient since it does not require
+unnecessary creation and evaluation of thunks. We also have the
+equivalence
-@deffn {Parameter object} current-input-port [new-port]
-@deffnx {Parameter object} current-output-port [new-port]
-@deffnx {Parameter object} current-error-port [new-port]
-This SRFI extends the core @code{current-input-port} and
-@code{current-output-port}, making them parameter objects. The
-Guile-specific @code{current-error-port} is extended too, for
-consistency. (@pxref{Default Ports}.)
-
-This is an upwardly compatible extension, a plain call like
-@code{(current-input-port)} still returns the current input port, and
-@code{set-current-input-port} can still be used. But the port can now
-also be set with @code{(current-input-port my-port)} and bound
-dynamically with @code{parameterize}.
+@lisp
+(delay expression) = (lazy (eager expression))
+@end lisp
@end deffn
-@defun with-parameters* param-list value-list thunk
-Establish a new dynamic scope, as per @code{parameterize} above,
-taking parameters from @var{param-list} and corresponding values from
-@var{values-list}. A call @code{(@var{thunk})} is made in the new
-scope and the result from that @var{thunk} is the return from
-@code{with-parameters*}.
+The following reduction rules may be helpful for reasoning about these
+primitives. However, they do not express the memoization and memory
+usage semantics specified above:
-This function is a Guile-specific addition to the SRFI, it's similar
-to the core @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
-@end defun
+@lisp
+(force (delay expression)) -> expression
+(force (lazy expression)) -> (force expression)
+(force (eager value)) -> value
+@end lisp
+@subsubheading Correct usage
-@sp 1
-Parameter objects are implemented using fluids (@pxref{Fluids and
-Dynamic States}), so each dynamic state has it's own parameter
-locations. That includes the separate locations when outside any
-@code{parameterize} form. When a parameter is created it gets a
-separate initial location in each dynamic state, all initialized to
-the given @var{init} value.
+We now provide a general recipe for using the primitives @{@code{lazy},
+@code{delay}, @code{force}@} to express lazy algorithms in Scheme. The
+transformation is best described by way of an example: Consider the
+stream-filter algorithm, expressed in a hypothetical lazy language as
-As alluded to above, because each thread usually has a separate
-dynamic state, each thread has it's own locations behind parameter
-objects, and changes in one thread are not visible to any other. When
-a new dynamic state or thread is created, the values of parameters in
-the originating context are copied, into new locations.
+@lisp
+(define (stream-filter p? s)
+ (if (null? s) '()
+ (let ((h (car s))
+ (t (cdr s)))
+ (if (p? h)
+ (cons h (stream-filter p? t))
+ (stream-filter p? t)))))
+@end lisp
-SRFI-39 doesn't specify the interaction between parameter objects and
-threads, so the threading behaviour described here should be regarded
-as Guile-specific.
+This algorithm can be expressed as follows in Scheme:
+@lisp
+(define (stream-filter p? s)
+ (lazy
+ (if (null? (force s)) (delay '())
+ (let ((h (car (force s)))
+ (t (cdr (force s))))
+ (if (p? h)
+ (delay (cons h (stream-filter p? t)))
+ (stream-filter p? t))))))
+@end lisp
+
+In other words, we
+
+@itemize @bullet
+@item
+wrap all constructors (e.g., @code{'()}, @code{cons}) with @code{delay},
+@item
+apply @code{force} to arguments of deconstructors (e.g., @code{car},
+@code{cdr} and @code{null?}),
+@item
+wrap procedure bodies with @code{(lazy ...)}.
+@end itemize
@node SRFI-55
@subsection SRFI-55 - Requiring Features
mechanism to load selected SRFI modules. This is implemented in the
Guile core, there's no module needed to get SRFI-55 itself.
-@deffn {library syntax} require-extension clause@dots{}
-Require each of the given @var{clause} features, throwing an error if
-any are unavailable.
+@deffn {library syntax} require-extension clause1 clause2 @dots{}
+Require the features of @var{clause1} @var{clause2} @dots{} , throwing
+an error if any are unavailable.
A @var{clause} is of the form @code{(@var{identifier} arg...)}. The
only @var{identifier} currently supported is @code{srfi} and the
return multiple values, as well as arbitrary definitions of test
success. SRFI 61 is implemented in the Guile core; there's no module
needed to get SRFI-61 itself. Extended @code{cond} is documented in
-@ref{if cond case,, Simple Conditional Evaluation}.
+@ref{Conditionals,, Simple Conditional Evaluation}.
+@node SRFI-67
+@subsection SRFI-67 - Compare procedures
+@cindex SRFI-67
+
+See @uref{http://srfi.schemers.org/srfi-67/srfi-67.html, the
+specification of SRFI-67}.
@node SRFI-69
@subsection SRFI-69 - Basic hash tables
@dfn{keyword objects}, which are equivalent to Guile's keywords
(@pxref{Keywords}). SRFI-88 keywords can be entered using the
@dfn{postfix keyword syntax}, which consists of an identifier followed
-by @code{:} (@pxref{Reader options, @code{postfix} keyword syntax}).
+by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}).
SRFI-88 can be made available with:
@example
association list in which both the keys and the values are strings.
@end deffn
+@node SRFI-105
+@subsection SRFI-105 Curly-infix expressions.
+@cindex SRFI-105
+@cindex curly-infix
+@cindex curly-infix-and-bracket-lists
+
+Guile's built-in reader includes support for SRFI-105 curly-infix
+expressions. See @uref{http://srfi.schemers.org/srfi-105/srfi-105.html,
+the specification of SRFI-105}. Some examples:
+
+@example
+@{n <= 5@} @result{} (<= n 5)
+@{a + b + c@} @result{} (+ a b c)
+@{a * @{b + c@}@} @result{} (* a (+ b c))
+@{(- a) / b@} @result{} (/ (- a) b)
+@{-(a) / b@} @result{} (/ (- a) b) as well
+@{(f a b) + (g h)@} @result{} (+ (f a b) (g h))
+@{f(a b) + g(h)@} @result{} (+ (f a b) (g h)) as well
+@{f[a b] + g(h)@} @result{} (+ ($bracket-apply$ f a b) (g h))
+'@{a + f(b) + x@} @result{} '(+ a (f b) x)
+@{length(x) >= 6@} @result{} (>= (length x) 6)
+@{n-1 + n-2@} @result{} (+ n-1 n-2)
+@{n * factorial@{n - 1@}@} @result{} (* n (factorial (- n 1)))
+@{@{a > 0@} and @{b >= 1@}@} @result{} (and (> a 0) (>= b 1))
+@{f@{n - 1@}(x)@} @result{} ((f (- n 1)) x)
+@{a . z@} @result{} ($nfx$ a . z)
+@{a + b - c@} @result{} ($nfx$ a + b - c)
+@end example
+
+To enable curly-infix expressions within a file, place the reader
+directive @code{#!curly-infix} before the first use of curly-infix
+notation. To globally enable curly-infix expressions in Guile's reader,
+set the @code{curly-infix} read option.
+
+Guile also implements the following non-standard extension to SRFI-105:
+if @code{curly-infix} is enabled and there is no other meaning assigned
+to square brackets (i.e. the @code{square-brackets} read option is
+turned off), then lists within square brackets are read as normal lists
+but with the special symbol @code{$bracket-list$} added to the front.
+To enable this combination of read options within a file, use the reader
+directive @code{#!curly-infix-and-bracket-lists}. For example:
+
+@example
+[a b] @result{} ($bracket-list$ a b)
+[a . b] @result{} ($bracket-list$ a . b)
+@end example
+
+
+For more information on reader options, @xref{Scheme Read}.
+
@c srfi-modules.texi ends here
@c Local Variables:
HCoop / bpt / guile.git / blobdiff