@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, 2011
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
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-37:: args-fold program argument processor
* SRFI-38:: External Representation for Data With Shared Structure
* SRFI-39:: Parameter objects
+* SRFI-41:: Streams.
* SRFI-42:: Eager comprehensions
* SRFI-45:: Primitives for expressing iterative lazy algorithms
* SRFI-55:: Requiring Features.
* SRFI-69:: Basic hash tables.
* SRFI-88:: Keyword objects.
* SRFI-98:: Accessing environment variables.
+* SRFI-105:: Curly-infix expressions.
@end menu
it is safe to use @code{use-modules} to load SRFI support modules. The
second reason is that some features defined in SRFIs had been
implemented in Guile before the developers started to add SRFI
-implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
+implementations as modules (for example SRFI-13 (@pxref{SRFI-13})). In
the future, it is possible that SRFIs in the core library might be
factored out into separate modules, requiring explicit module loading
when they are needed. So you should be prepared to have to use
-@code{use-modules} someday in the future to access SRFI-6 bindings. If
+@code{use-modules} someday in the future to access SRFI-13 bindings. If
you want, you can do that already. We have included the module
-@code{(srfi srfi-6)} in the distribution, which currently does nothing,
+@code{(srfi srfi-13)} in the distribution, which currently does nothing,
but ensures that you can write future-safe code.
Generally, support for a specific SRFI is made available by using
r5rs
srfi-0
srfi-4
-srfi-6
srfi-13
srfi-14
+srfi-23
+srfi-39
+srfi-55
+srfi-61
+srfi-105
@end example
Other SRFI feature symbols are defined once their code has been loaded
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
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
@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.
@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.
C}), but returns a pointer to the elements of a uniform numeric vector.
@end deftypefn
-Unless you really need to the limited generality of these functions, it is best
-to use the type-specific functions, or the generalized vector accessors.
+Unless you really need to the limited generality of these functions, it
+is best to use the type-specific functions, or the array accessors.
@node SRFI-4 and Bytevectors
@subsubsection SRFI-4 - Relation to bytevectors
@cindex SRFI-6
SRFI-6 defines the procedures @code{open-input-string},
-@code{open-output-string} and @code{get-output-string}. These
-procedures are included in the Guile core, so using this module does not
-make any difference at the moment. But it is possible that support for
-SRFI-6 will be factored out of the core library in the future, so using
-this module does not hurt, after all.
+@code{open-output-string} and @code{get-output-string}.
+
+Note that although versions of these procedures are included in the
+Guile core, the core versions are not fully conformant with SRFI-6:
+attempts to read or write characters that are not supported by the
+current @code{%default-port-encoding} will fail.
+
+We therefore recommend that you import this module, which supports all
+characters:
+
+@example
+(use-modules (srfi srfi-6))
+@end example
@node SRFI-8
@subsection SRFI-8 - receive
@node SRFI-9
@subsection SRFI-9 - define-record-type
-@cindex SRFI-9
-@cindex record
This SRFI is a syntax for defining new record types and creating
-predicate, constructor, and field getter and setter functions. In
-Guile this is simply an alternate interface to the core record
-functionality (@pxref{Records}). It can be used with,
-
-@example
-(use-modules (srfi srfi-9))
-@end example
-
-@deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{}
-@sp 1
-Create a new record type, and make various @code{define}s for using
-it. This syntax can only occur at the top-level, not nested within
-some other form.
-
-@var{type} is bound to the record type, which is as per the return
-from the core @code{make-record-type}. @var{type} also provides the
-name for the record, as per @code{record-type-name}.
-
-@var{constructor} is bound to a function to be called as
-@code{(@var{constructor} fieldval @dots{})} to create a new record of
-this type. The arguments are initial values for the fields, one
-argument for each field, in the order they appear in the
-@code{define-record-type} form.
-
-The @var{fieldname}s provide the names for the record fields, as per
-the core @code{record-type-fields} etc, and are referred to in the
-subsequent accessor/modifier forms.
-
-@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.
-
-Each @var{accessor} is bound to a function to be called
-@code{(@var{accessor} record)} to retrieve the respective field from a
-@var{record}. Similarly each @var{modifier} is bound to a function to
-be called @code{(@var{modifier} record val)} to set the respective
-field in a @var{record}.
-@end deffn
-
-@noindent
-An example will illustrate typical usage,
-
-@example
-(define-record-type employee-type
- (make-employee name age salary)
- employee?
- (name get-employee-name)
- (age get-employee-age set-employee-age)
- (salary get-employee-salary set-employee-salary))
-@end example
-
-This creates a new employee data type, with name, age and salary
-fields. Accessor functions are created for each field, but no
-modifier function for the name (the intention in this example being
-that it's established only when an employee object is created). These
-can all then be used as for example,
-
-@example
-employee-type @result{} #<record-type employee-type>
-
-(define fred (make-employee "Fred" 45 20000.00))
-
-(employee? fred) @result{} #t
-(get-employee-age fred) @result{} 45
-(set-employee-salary fred 25000.00) ;; pay rise
-@end example
-
-The functions created by @code{define-record-type} are ordinary
-top-level @code{define}s. They can be redefined or @code{set!} as
-desired, exported from a module, etc.
+predicate, constructor, and field getter and setter functions. It is
+documented in the ``Compound Data Types'' section of the manual
+(@pxref{SRFI-9 Records}).
-@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
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
(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
Note that all fields of @var{type} and its supertypes must be specified.
@end deffn
-@deffn {Scheme Procedure} make-compound-condition . conditions
-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?}).
+@deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{}
+Return a new compound condition composed of @var{condition1}
+@var{condition2} @enddots{}. The returned condition has the type of
+each condition of condition1 condition2 @dots{} (per
+@code{condition-has-type?}).
@end deffn
@deffn {Scheme Procedure} condition-has-type? c 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:
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
@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
+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}.
+
+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}).
+
+@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
+
+@node SRFI-41
+@subsection SRFI-41 - Streams
+@cindex SRFI-41
+
+This subsection is based on the
+@uref{http://srfi.schemers.org/srfi-41/srfi-41.html, specification of
+SRFI-41} by Philip L.@: Bewig.
+
+@c The copyright notice and license text of the SRFI-41 specification is
+@c reproduced below:
+
+@c Copyright (C) Philip L. Bewig (2007). 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.
+
+@noindent
+This SRFI implements streams, sometimes called lazy lists, a sequential
+data structure containing elements computed only on demand. A stream is
+either null or is a pair with a stream in its cdr. Since elements of a
+stream are computed only when accessed, streams can be infinite. Once
+computed, the value of a stream element is cached in case it is needed
+again. SRFI-41 can be made available with:
@example
-(use-modules (srfi srfi-39))
+(use-modules (srfi srfi-41))
@end example
-A parameter object is a procedure. Called with no arguments it
-returns its value, called with one argument it sets the value.
+@menu
+* SRFI-41 Stream Fundamentals::
+* SRFI-41 Stream Primitives::
+* SRFI-41 Stream Library::
+@end menu
+
+@node SRFI-41 Stream Fundamentals
+@subsubsection SRFI-41 Stream Fundamentals
+
+SRFI-41 Streams are based on two mutually-recursive abstract data types:
+An object of the @code{stream} abstract data type is a promise that,
+when forced, is either @code{stream-null} or is an object of type
+@code{stream-pair}. An object of the @code{stream-pair} abstract data
+type contains a @code{stream-car} and a @code{stream-cdr}, which must be
+a @code{stream}. The essential feature of streams is the systematic
+suspensions of the recursive promises between the two data types.
+
+The object stored in the @code{stream-car} of a @code{stream-pair} is a
+promise that is forced the first time the @code{stream-car} is accessed;
+its value is cached in case it is needed again. The object may have any
+type, and different stream elements may have different types. If the
+@code{stream-car} is never accessed, the object stored there is never
+evaluated. Likewise, the @code{stream-cdr} is a promise to return a
+stream, and is only forced on demand.
+
+@node SRFI-41 Stream Primitives
+@subsubsection SRFI-41 Stream Primitives
+
+This library provides eight operators: constructors for
+@code{stream-null} and @code{stream-pair}s, type predicates for streams
+and the two kinds of streams, accessors for both fields of a
+@code{stream-pair}, and a lambda that creates procedures that return
+streams.
+
+@defvr {Scheme Variable} stream-null
+A promise that, when forced, is a single object, distinguishable from
+all other objects, that represents the null stream. @code{stream-null}
+is immutable and unique.
+@end defvr
+
+@deffn {Scheme Syntax} stream-cons object-expr stream-expr
+Creates a newly-allocated stream containing a promise that, when forced,
+is a @code{stream-pair} with @var{object-expr} in its @code{stream-car}
+and @var{stream-expr} in its @code{stream-cdr}. Neither
+@var{object-expr} nor @var{stream-expr} is evaluated when
+@code{stream-cons} is called.
+
+Once created, a @code{stream-pair} is immutable; there is no
+@code{stream-set-car!} or @code{stream-set-cdr!} that modifies an
+existing stream-pair. There is no dotted-pair or improper stream as
+with lists.
+@end deffn
+
+@deffn {Scheme Procedure} stream? object
+Returns true if @var{object} is a stream, otherwise returns false. If
+@var{object} is a stream, its promise will not be forced. If
+@code{(stream? obj)} returns true, then one of @code{(stream-null? obj)}
+or @code{(stream-pair? obj)} will return true and the other will return
+false.
+@end deffn
+
+@deffn {Scheme Procedure} stream-null? object
+Returns true if @var{object} is the distinguished null stream, otherwise
+returns false. If @var{object} is a stream, its promise will be forced.
+@end deffn
+
+@deffn {Scheme Procedure} stream-pair? object
+Returns true if @var{object} is a @code{stream-pair} constructed by
+@code{stream-cons}, otherwise returns false. If @var{object} is a
+stream, its promise will be forced.
+@end deffn
+
+@deffn {Scheme Procedure} stream-car stream
+Returns the object stored in the @code{stream-car} of @var{stream}. An
+error is signalled if the argument is not a @code{stream-pair}. This
+causes the @var{object-expr} passed to @code{stream-cons} to be
+evaluated if it had not yet been; the value is cached in case it is
+needed again.
+@end deffn
+
+@deffn {Scheme Procedure} stream-cdr stream
+Returns the stream stored in the @code{stream-cdr} of @var{stream}. An
+error is signalled if the argument is not a @code{stream-pair}.
+@end deffn
+
+@deffn {Scheme Syntax} stream-lambda formals body @dots{}
+Creates a procedure that returns a promise to evaluate the @var{body} of
+the procedure. The last @var{body} expression to be evaluated must
+yield a stream. As with normal @code{lambda}, @var{formals} may be a
+single variable name, in which case all the formal arguments are
+collected into a single list, or a list of variable names, which may be
+null if there are no arguments, proper if there are an exact number of
+arguments, or dotted if a fixed number of arguments is to be followed by
+zero or more arguments collected into a list. @var{Body} must contain
+at least one expression, and may contain internal definitions preceding
+any expressions to be evaluated.
+@end deffn
@example
-(define my-param (make-parameter 123))
-(my-param) @result{} 123
-(my-param 456)
-(my-param) @result{} 456
+(define strm123
+ (stream-cons 1
+ (stream-cons 2
+ (stream-cons 3
+ stream-null))))
+
+(stream-car strm123) @result{} 1
+(stream-car (stream-cdr strm123) @result{} 2
+
+(stream-pair?
+ (stream-cdr
+ (stream-cons (/ 1 0) stream-null))) @result{} #f
+
+(stream? (list 1 2 3)) @result{} #f
+
+(define iter
+ (stream-lambda (f x)
+ (stream-cons x (iter f (f x)))))
+
+(define nats (iter (lambda (x) (+ x 1)) 0))
+
+(stream-car (stream-cdr nats)) @result{} 1
+
+(define stream-add
+ (stream-lambda (s1 s2)
+ (stream-cons
+ (+ (stream-car s1) (stream-car s2))
+ (stream-add (stream-cdr s1)
+ (stream-cdr s2)))))
+
+(define evens (stream-add nats nats))
+
+(stream-car evens) @result{} 0
+(stream-car (stream-cdr evens)) @result{} 2
+(stream-car (stream-cdr (stream-cdr evens))) @result{} 4
@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.
+@node SRFI-41 Stream Library
+@subsubsection SRFI-41 Stream Library
+
+@deffn {Scheme Syntax} define-stream (name args @dots{}) body @dots{}
+Creates a procedure that returns a stream, and may appear anywhere a
+normal @code{define} may appear, including as an internal definition.
+It may contain internal definitions of its own. The defined procedure
+takes arguments in the same way as @code{stream-lambda}.
+@code{define-stream} is syntactic sugar on @code{stream-lambda}; see
+also @code{stream-let}, which is also a sugaring of
+@code{stream-lambda}.
+
+A simple version of @code{stream-map} that takes only a single input
+stream calls itself recursively:
@example
-(parameterize ((my-param 789))
- (my-param) @result{} 789
- )
-(my-param) @result{} 456
+(define-stream (stream-map proc strm)
+ (if (stream-null? strm)
+ stream-null
+ (stream-cons
+ (proc (stream-car strm))
+ (stream-map proc (stream-cdr strm))))))
@end example
+@end deffn
-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.
+@deffn {Scheme Procedure} list->stream list
+Returns a newly-allocated stream containing the elements from
+@var{list}.
+@end deffn
-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.
+@deffn {Scheme Procedure} port->stream [port]
+Returns a newly-allocated stream containing in its elements the
+characters on the port. If @var{port} is not given it defaults to the
+current input port. The returned stream has finite length and is
+terminated by @code{stream-null}.
-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.
+It looks like one use of @code{port->stream} would be this:
+@example
+(define s ;wrong!
+ (with-input-from-file filename
+ (lambda () (port->stream))))
+@end example
-@sp 1
-@defun make-parameter init [converter]
-Return a new parameter object, with initial value @var{init}.
+But that fails, because @code{with-input-from-file} is eager, and closes
+the input port prematurely, before the first character is read. To read
+a file into a stream, say:
-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,
+@example
+(define-stream (file->stream filename)
+ (let ((p (open-input-file filename)))
+ (stream-let loop ((c (read-char p)))
+ (if (eof-object? c)
+ (begin (close-input-port p)
+ stream-null)
+ (stream-cons c
+ (loop (read-char p)))))))
+@end example
+@end deffn
+
+@deffn {Scheme Syntax} stream object-expr @dots{}
+Creates a newly-allocated stream containing in its elements the objects,
+in order. The @var{object-expr}s are evaluated when they are accessed,
+not when the stream is created. If no objects are given, as in
+(stream), the null stream is returned. See also @code{list->stream}.
@example
-(define my-param (make-parameter 123))
-(my-param) @result{} 123
+(define strm123 (stream 1 2 3))
-(my-param 456)
-(my-param) @result{} 456
+; (/ 1 0) not evaluated when stream is created
+(define s (stream 1 (/ 1 0) -1))
@end example
+@end deffn
-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.
+@deffn {Scheme Procedure} stream->list [n] stream
+Returns a newly-allocated list containing in its elements the first
+@var{n} items in @var{stream}. If @var{stream} has less than @var{n}
+items, all the items in the stream will be included in the returned
+list. If @var{n} is not given it defaults to infinity, which means that
+unless @var{stream} is finite @code{stream->list} will never return.
-A @var{converter} allows values to be validated, or put into a
-canonical form. For example,
+@example
+(stream->list 10
+ (stream-map (lambda (x) (* x x))
+ (stream-from 0)))
+ @result{} (0 1 4 9 16 25 36 49 64 81)
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} stream-append stream @dots{}
+Returns a newly-allocated stream containing in its elements those
+elements contained in its input @var{stream}s, in order of input. If
+any of the input streams is infinite, no elements of any of the
+succeeding input streams will appear in the output stream. See also
+@code{stream-concat}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-concat stream
+Takes a @var{stream} consisting of one or more streams and returns a
+newly-allocated stream containing all the elements of the input streams.
+If any of the streams in the input @var{stream} is infinite, any
+remaining streams in the input stream will never appear in the output
+stream. See also @code{stream-append}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-constant object @dots{}
+Returns a newly-allocated stream containing in its elements the
+@var{object}s, repeating in succession forever.
@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
+(stream-constant 1) @result{} 1 1 1 @dots{}
+(stream-constant #t #f) @result{} #t #f #t #f #t #f @dots{}
@end example
-@end defun
+@end deffn
-@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}.
+@deffn {Scheme Procedure} stream-drop n stream
+Returns the suffix of the input @var{stream} that starts at the next
+element after the first @var{n} elements. The output stream shares
+structure with the input @var{stream}; thus, promises forced in one
+instance of the stream are also forced in the other instance of the
+stream. If the input @var{stream} has less than @var{n} elements,
+@code{stream-drop} returns the null stream. See also
+@code{stream-take}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-drop-while pred stream
+Returns the suffix of the input @var{stream} that starts at the first
+element @var{x} for which @code{(pred x)} returns false. The output
+stream shares structure with the input @var{stream}. See also
+@code{stream-take-while}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-filter pred stream
+Returns a newly-allocated stream that contains only those elements
+@var{x} of the input @var{stream} which satisfy the predicate
+@code{pred}.
+
+@example
+(stream-filter odd? (stream-from 0))
+ @result{} 1 3 5 7 9 @dots{}
+@end example
+@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 Procedure} stream-fold proc base stream
+Applies a binary procedure @var{proc} to @var{base} and the first
+element of @var{stream} to compute a new @var{base}, then applies the
+procedure to the new @var{base} and the next element of @var{stream} to
+compute a succeeding @var{base}, and so on, accumulating a value that is
+finally returned as the value of @code{stream-fold} when the end of the
+stream is reached. @var{stream} must be finite, or @code{stream-fold}
+will enter an infinite loop. See also @code{stream-scan}, which is
+similar to @code{stream-fold}, but useful for infinite streams. For
+readers familiar with other functional languages, this is a left-fold;
+there is no corresponding right-fold, since right-fold relies on finite
+streams that are fully-evaluated, in which case they may as well be
+converted to a list.
+@end deffn
+
+@deffn {Scheme Procedure} stream-for-each proc stream @dots{}
+Applies @var{proc} element-wise to corresponding elements of the input
+@var{stream}s for side-effects; it returns nothing.
+@code{stream-for-each} stops as soon as any of its input streams is
+exhausted.
+@end deffn
+
+@deffn {Scheme Procedure} stream-from first [step]
+Creates a newly-allocated stream that contains @var{first} as its first
+element and increments each succeeding element by @var{step}. If
+@var{step} is not given it defaults to 1. @var{first} and @var{step}
+may be of any numeric type. @code{stream-from} is frequently useful as
+a generator in @code{stream-of} expressions. See also
+@code{stream-range} for a similar procedure that creates finite streams.
+@end deffn
+
+@deffn {Scheme Procedure} stream-iterate proc base
+Creates a newly-allocated stream containing @var{base} in its first
+element and applies @var{proc} to each element in turn to determine the
+succeeding element. See also @code{stream-unfold} and
+@code{stream-unfolds}.
+@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} stream-length stream
+Returns the number of elements in the @var{stream}; it does not evaluate
+its elements. @code{stream-length} may only be used on finite streams;
+it enters an infinite loop with infinite streams.
+@end deffn
-For example,
+@deffn {Scheme Syntax} stream-let tag ((var expr) @dots{}) body @dots{}
+Creates a local scope that binds each variable to the value of its
+corresponding expression. It additionally binds @var{tag} to a
+procedure which takes the bound variables as arguments and @var{body} as
+its defining expressions, binding the @var{tag} with
+@code{stream-lambda}. @var{tag} is in scope within body, and may be
+called recursively. When the expanded expression defined by the
+@code{stream-let} is evaluated, @code{stream-let} evaluates the
+expressions in its @var{body} in an environment containing the
+newly-bound variables, returning the value of the last expression
+evaluated, which must yield a stream.
+
+@code{stream-let} provides syntactic sugar on @code{stream-lambda}, in
+the same manner as normal @code{let} provides syntactic sugar on normal
+@code{lambda}. However, unlike normal @code{let}, the @var{tag} is
+required, not optional, because unnamed @code{stream-let} is
+meaningless.
+
+For example, @code{stream-member} returns the first @code{stream-pair}
+of the input @var{strm} with a @code{stream-car} @var{x} that satisfies
+@code{(eql? obj x)}, or the null stream if @var{x} is not present in
+@var{strm}.
@example
-(define prompt (make-parameter "Type something: "))
-(define (get-input)
- (display (prompt))
- ...)
-
-(parameterize ((prompt "Type a number: "))
- (get-input)
- ...)
+(define-stream (stream-member eql? obj strm)
+ (stream-let loop ((strm strm))
+ (cond ((stream-null? strm) strm)
+ ((eql? obj (stream-car strm)) strm)
+ (else (loop (stream-cdr strm))))))
@end example
@end deffn
-@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}.)
+@deffn {Scheme Procedure} stream-map proc stream @dots{}
+Applies @var{proc} element-wise to corresponding elements of the input
+@var{stream}s, returning a newly-allocated stream containing elements
+that are the results of those procedure applications. The output stream
+has as many elements as the minimum-length input stream, and may be
+infinite.
+@end deffn
+
+@deffn {Scheme Syntax} stream-match stream clause @dots{}
+Provides pattern-matching for streams. The input @var{stream} is an
+expression that evaluates to a stream. Clauses are of the form
+@code{(pattern [fender] expression)}, consisting of a @var{pattern} that
+matches a stream of a particular shape, an optional @var{fender} that
+must succeed if the pattern is to match, and an @var{expression} that is
+evaluated if the pattern matches. There are four types of patterns:
+
+@itemize @bullet
+@item
+() matches the null stream.
+
+@item
+(@var{pat0} @var{pat1} @dots{}) matches a finite stream with length
+exactly equal to the number of pattern elements.
+
+@item
+(@var{pat0} @var{pat1} @dots{} @code{.} @var{pat-rest}) matches an
+infinite stream, or a finite stream with length at least as great as the
+number of pattern elements before the literal dot.
+
+@item
+@var{pat} matches an entire stream. Should always appear last in the
+list of clauses; it's not an error to appear elsewhere, but subsequent
+clauses could never match.
+@end itemize
+
+Each pattern element may be either:
+
+@itemize @bullet
+@item
+An identifier, which matches any stream element. Additionally, the
+value of the stream element is bound to the variable named by the
+identifier, which is in scope in the @var{fender} and @var{expression}
+of the corresponding @var{clause}. Each identifier in a single pattern
+must be unique.
-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}.
+@item
+A literal underscore (@code{_}), which matches any stream element but
+creates no bindings.
+@end itemize
+
+The @var{pattern}s are tested in order, left-to-right, until a matching
+pattern is found; if @var{fender} is present, it must evaluate to a true
+value for the match to be successful. Pattern variables are bound in
+the corresponding @var{fender} and @var{expression}. Once the matching
+@var{pattern} is found, the corresponding @var{expression} is evaluated
+and returned as the result of the match. An error is signaled if no
+pattern matches the input @var{stream}.
+
+@code{stream-match} is often used to distinguish null streams from
+non-null streams, binding @var{head} and @var{tail}:
+
+@example
+(define (len strm)
+ (stream-match strm
+ (() 0)
+ ((head . tail) (+ 1 (len tail)))))
+@end example
+
+Fenders can test the common case where two stream elements must be
+identical; the @code{else} pattern is an identifier bound to the entire
+stream, not a keyword as in @code{cond}.
+
+@example
+(stream-match strm
+ ((x y . _) (equal? x y) 'ok)
+ (else 'error))
+@end example
+
+A more complex example uses two nested matchers to match two different
+stream arguments; @code{(stream-merge lt? . strms)} stably merges two or
+more streams ordered by the @code{lt?} predicate:
+
+@example
+(define-stream (stream-merge lt? . strms)
+ (define-stream (merge xx yy)
+ (stream-match xx (() yy) ((x . xs)
+ (stream-match yy (() xx) ((y . ys)
+ (if (lt? y x)
+ (stream-cons y (merge xx ys))
+ (stream-cons x (merge xs yy))))))))
+ (stream-let loop ((strms strms))
+ (cond ((null? strms) stream-null)
+ ((null? (cdr strms)) (car strms))
+ (else (merge (car strms)
+ (apply stream-merge lt?
+ (cdr strms)))))))
+@end example
@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*}.
+@deffn {Scheme Syntax} stream-of expr clause @dots{}
+Provides the syntax of stream comprehensions, which generate streams by
+means of looping expressions. The result is a stream of objects of the
+type returned by @var{expr}. There are four types of clauses:
-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
+@itemize @bullet
+@item
+(@var{var} @code{in} @var{stream-expr}) loops over the elements of
+@var{stream-expr}, in order from the start of the stream, binding each
+element of the stream in turn to @var{var}. @code{stream-from} and
+@code{stream-range} are frequently useful as generators for
+@var{stream-expr}.
+@item
+(@var{var} @code{is} @var{expr}) binds @var{var} to the value obtained
+by evaluating @var{expr}.
-@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.
-
-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.
-
-SRFI-39 doesn't specify the interaction between parameter objects and
-threads, so the threading behaviour described here should be regarded
-as Guile-specific.
+@item
+(@var{pred} @var{expr}) includes in the output stream only those
+elements @var{x} which satisfy the predicate @var{pred}.
+@end itemize
+
+The scope of variables bound in the stream comprehension is the clauses
+to the right of the binding clause (but not the binding clause itself)
+plus the result expression.
+
+When two or more generators are present, the loops are processed as if
+they are nested from left to right; that is, the rightmost generator
+varies fastest. A consequence of this is that only the first generator
+may be infinite and all subsequent generators must be finite. If no
+generators are present, the result of a stream comprehension is a stream
+containing the result expression; thus, @samp{(stream-of 1)} produces a
+finite stream containing only the element 1.
+
+@example
+(stream-of (* x x)
+ (x in (stream-range 0 10))
+ (even? x))
+ @result{} 0 4 16 36 64
+
+(stream-of (list a b)
+ (a in (stream-range 1 4))
+ (b in (stream-range 1 3)))
+ @result{} (1 1) (1 2) (2 1) (2 2) (3 1) (3 2)
+
+(stream-of (list i j)
+ (i in (stream-range 1 5))
+ (j in (stream-range (+ i 1) 5)))
+ @result{} (1 2) (1 3) (1 4) (2 3) (2 4) (3 4)
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} stream-range first past [step]
+Creates a newly-allocated stream that contains @var{first} as its first
+element and increments each succeeding element by @var{step}. The
+stream is finite and ends before @var{past}, which is not an element of
+the stream. If @var{step} is not given it defaults to 1 if @var{first}
+is less than past and -1 otherwise. @var{first}, @var{past} and
+@var{step} may be of any real numeric type. @code{stream-range} is
+frequently useful as a generator in @code{stream-of} expressions. See
+also @code{stream-from} for a similar procedure that creates infinite
+streams.
+
+@example
+(stream-range 0 10) @result{} 0 1 2 3 4 5 6 7 8 9
+(stream-range 0 10 2) @result{} 0 2 4 6 8
+@end example
+
+Successive elements of the stream are calculated by adding @var{step} to
+@var{first}, so if any of @var{first}, @var{past} or @var{step} are
+inexact, the length of the output stream may differ from
+@code{(ceiling (- (/ (- past first) step) 1)}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-ref stream n
+Returns the @var{n}th element of stream, counting from zero. An error
+is signaled if @var{n} is greater than or equal to the length of stream.
+
+@example
+(define (fact n)
+ (stream-ref
+ (stream-scan * 1 (stream-from 1))
+ n))
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} stream-reverse stream
+Returns a newly-allocated stream containing the elements of the input
+@var{stream} but in reverse order. @code{stream-reverse} may only be
+used with finite streams; it enters an infinite loop with infinite
+streams. @code{stream-reverse} does not force evaluation of the
+elements of the stream.
+@end deffn
+
+@deffn {Scheme Procedure} stream-scan proc base stream
+Accumulates the partial folds of an input @var{stream} into a
+newly-allocated output stream. The output stream is the @var{base}
+followed by @code{(stream-fold proc base (stream-take i stream))} for
+each of the first @var{i} elements of @var{stream}.
+
+@example
+(stream-scan + 0 (stream-from 1))
+ @result{} (stream 0 1 3 6 10 15 @dots{})
+
+(stream-scan * 1 (stream-from 1))
+ @result{} (stream 1 1 2 6 24 120 @dots{})
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} stream-take n stream
+Returns a newly-allocated stream containing the first @var{n} elements
+of the input @var{stream}. If the input @var{stream} has less than
+@var{n} elements, so does the output stream. See also
+@code{stream-drop}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-take-while pred stream
+Takes a predicate and a @code{stream} and returns a newly-allocated
+stream containing those elements @code{x} that form the maximal prefix
+of the input stream which satisfy @var{pred}. See also
+@code{stream-drop-while}.
+@end deffn
+
+@deffn {Scheme Procedure} stream-unfold map pred gen base
+The fundamental recursive stream constructor. It constructs a stream by
+repeatedly applying @var{gen} to successive values of @var{base}, in the
+manner of @code{stream-iterate}, then applying @var{map} to each of the
+values so generated, appending each of the mapped values to the output
+stream as long as @code{(pred? base)} returns a true value. See also
+@code{stream-iterate} and @code{stream-unfolds}.
+
+The expression below creates the finite stream @samp{0 1 4 9 16 25 36 49
+64 81}. Initially the @var{base} is 0, which is less than 10, so
+@var{map} squares the @var{base} and the mapped value becomes the first
+element of the output stream. Then @var{gen} increments the @var{base}
+by 1, so it becomes 1; this is less than 10, so @var{map} squares the
+new @var{base} and 1 becomes the second element of the output stream.
+And so on, until the base becomes 10, when @var{pred} stops the
+recursion and stream-null ends the output stream.
+
+@example
+(stream-unfold
+ (lambda (x) (expt x 2)) ; map
+ (lambda (x) (< x 10)) ; pred?
+ (lambda (x) (+ x 1)) ; gen
+ 0) ; base
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} stream-unfolds proc seed
+Returns @var{n} newly-allocated streams containing those elements
+produced by successive calls to the generator @var{proc}, which takes
+the current @var{seed} as its argument and returns @var{n}+1 values
+
+(@var{proc} @var{seed}) @result{} @var{seed} @var{result_0} @dots{} @var{result_n-1}
+
+where the returned @var{seed} is the input @var{seed} to the next call
+to the generator and @var{result_i} indicates how to produce the next
+element of the @var{i}th result stream:
+
+@itemize @bullet
+@item
+(@var{value}): @var{value} is the next car of the result stream.
+
+@item
+@code{#f}: no value produced by this iteration of the generator
+@var{proc} for the result stream.
+
+@item
+(): the end of the result stream.
+@end itemize
+
+It may require multiple calls of @var{proc} to produce the next element
+of any particular result stream. See also @code{stream-iterate} and
+@code{stream-unfold}.
+
+@example
+(define (stream-partition pred? strm)
+ (stream-unfolds
+ (lambda (s)
+ (if (stream-null? s)
+ (values s '() '())
+ (let ((a (stream-car s))
+ (d (stream-cdr s)))
+ (if (pred? a)
+ (values d (list a) #f)
+ (values d #f (list a))))))
+ strm))
+
+(call-with-values
+ (lambda ()
+ (stream-partition odd?
+ (stream-range 1 6)))
+ (lambda (odds evens)
+ (list (stream->list odds)
+ (stream->list evens))))
+ @result{} ((1 3 5) (2 4))
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} stream-zip stream @dots{}
+Returns a newly-allocated stream in which each element is a list (not a
+stream) of the corresponding elements of the input @var{stream}s. The
+output stream is as long as the shortest input @var{stream}, if any of
+the input @var{stream}s is finite, or is infinite if all the input
+@var{stream}s are infinite.
+@end deffn
@node SRFI-42
@subsection SRFI-42 - Eager Comprehensions
break if those definition are replaced by the SRFI-45 definitions of
delay and force.
+Guile also adds @code{promise?} to the list of exports, which is not
+part of the official SRFI-45.
+
+@deffn {Scheme Procedure} promise? obj
+Return true if @var{obj} is an SRFI-45 promise, otherwise return false.
+@end deffn
+
@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
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
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