* Add macros for R7RS.
* Tweak parameter sections.
* Add make-unsettable-parameter and make-settable-parameter.
Tables}).
In addition to the hash table interface described in the following,
-MIT Scheme implements SRFI 69: ``Basic hash tables''. The reason for
-supporting two interfaces is partly historical---MIT Scheme supported
-hash tables prior to the existence of SRFI 69---and partly
+MIT Scheme implements @usrfi{69}: ``Basic hash tables''. The reason
+for supporting two interfaces is partly historical---MIT Scheme
+supported hash tables prior to the existence of @asrfi{69}---and partly
technical---SFRI 69 fails to specify certain optimization-enabling
exceptions to its semantics, forcing a correct implementation to pay
the non-negligible performance cost of completely safe behavior.
-@footnote{SRFI 69 does not give hash functions the flexibility to
+@footnote{@asrfi{69} does not give hash functions the flexibility to
return new hash values after a garbage collection, which prevents a
system whose garbage collector may relocate objects from hashing based
-on the addresses of objects in memory (@pxref{Address Hashing}). SRFI
-69 also does not specify circumstances when procedures passed as
-arguments to hash table operations may not themselves modify the hash
-table, which requires defensive copying and defensive repetitions of
-lookups.} The MIT Scheme native hash table interface, in contrast,
+on the addresses of objects in memory (@pxref{Address Hashing}).
+@asrfi{69} also does not specify circumstances when procedures passed
+as arguments to hash table operations may not themselves modify the
+hash table, which requires defensive copying and defensive repetitions
+of lookups.} The MIT Scheme native hash table interface, in contrast,
specifies the minor exceptions it needs, and is therefore implemented
-more efficiently. We do not describe the SRFI-69-compliant interface
+more efficiently. We do not describe the @asrfi{69}-compliant interface
here, as that would be redundant with the SRFI document.
(Previously, the hash-table implementation was a run-time-loadable
@end deffn
@deffn procedure xcons obj1 obj2
-(@acronym{SRFI} 1) Returns a newly allocated pair whose car is
+(@asrfi{1}) Returns a newly allocated pair whose car is
@var{obj2} and whose cdr is @var{obj1}.
@example
@end deffn
@deffn procedure car+cdr pair
-(@acronym{SRFI} 1) The fundamental pair deconstructor:
+(@asrfi{1}) The fundamental pair deconstructor:
@example
(lambda (p) (values (car p) (cdr p)))
@deffn procedure tree-copy tree
@cindex copying, of tree
@cindex tree, copying
-(@acronym{SRFI} 1) This copies an arbitrary @var{tree} constructed
+(@asrfi{1}) This copies an arbitrary @var{tree} constructed
from pairs, copying both the car and cdr elements of every pair. This
could have been defined by
@end deffn
@deffn procedure make-list k [element]
-(@acronym{SRFI} 1) This procedure returns a newly allocated list of
+(@asrfi{1}) This procedure returns a newly allocated list of
length @var{k}, whose elements are all @var{element}. If
@var{element} is not supplied, it defaults to the empty list.
@deffn procedure cons* object object @dots{}
@findex list
-(@acronym{SRFI} 1) @code{cons*} is similar to @code{list}, except that
+(@asrfi{1}) @code{cons*} is similar to @code{list}, except that
@code{cons*} conses together the last two arguments rather than
consing the last argument with the empty list. If the last argument
is not a list the result is an improper list. If the last argument is
(list-tabulate 4 values) => (0 1 2 3)
@end example
-@code{list-tabulate} is defined by @acronym{SRFI} 1.
+@code{list-tabulate} is defined by @usrfi{1}.
@end deffn
@deffn procedure list-copy list
-(@acronym{SRFI} 1) Returns a newly allocated copy of @var{list}. This
+(@asrfi{1}) Returns a newly allocated copy of @var{list}. This
copies each of the pairs comprising @var{list}. This could have been
defined by
@end deffn
@deffn procedure iota count [start [step]]
-(@acronym{SRFI} 1) Returns a list containing the elements
+(@asrfi{1}) Returns a list containing the elements
@example
(@var{start} @var{start}+@var{step} @dots{} @var{start}+(@var{count}-1)*@var{step})
@end deffn
@deffn procedure circular-list? object
-(@acronym{SRFI} 1) Returns @code{#t} if @var{object} is a circular
+(@asrfi{1}) Returns @code{#t} if @var{object} is a circular
list, otherwise returns @code{#f}.
@example
@end deffn
@deffn procedure dotted-list? object
-(@acronym{SRFI} 1) Returns @code{#t} if @var{object} is an improper
+(@asrfi{1}) Returns @code{#t} if @var{object} is an improper
list, otherwise returns @code{#f}.
@example
@end deffn
@deffn procedure length+ clist
-(@acronym{SRFI} 1) Returns the length of @var{clist}, if it is a proper
+(@asrfi{1}) Returns the length of @var{clist}, if it is a proper
list. Returns @code{#f} if @var{clist} is a circular list. Otherwise
signals an error.
@cindex deletion, of list element
@deffn procedure filter predicate list
-(@acronym{SRFI} 1) Returns a newly allocated copy of @var{list}
+(@asrfi{1}) Returns a newly allocated copy of @var{list}
containing only the elements satisfying @var{predicate}.
@var{Predicate} must be a procedure of one argument.
@end deffn
@deffn procedure remove predicate list
-(@acronym{SRFI} 1) Like @code{filter}, except that the returned list
+(@asrfi{1}) Like @code{filter}, except that the returned list
contains only those elements @emph{not} satisfying @var{predicate}.
@example
@end deffn
@deffn procedure partition predicate list
-(@acronym{SRFI} 1) Partitions the elements of @var{list} with
+(@asrfi{1}) Partitions the elements of @var{list} with
@var{predicate}, and returns two values: the list of in-elements and
the list of out-elements. The @var{list} is not disordered---elements
occur in the result lists in the same order as they occur in the
@deffn procedure filter! predicate list
@deffnx procedure remove! predicate list
@deffnx procedure partition! predicate list
-(@acronym{SRFI} 1) Linear-update variants of @code{filter},
+(@asrfi{1}) Linear-update variants of @code{filter},
@code{remove} and @code{partition}. These procedures are allowed, but
not required, to alter the cons cells in the argument @code{list} to
construct the result lists.
@cindex searching, of list
@deffn procedure find predicate list
-(@acronym{SRFI} 1) Returns the first element in @var{list} for which
+(@asrfi{1}) Returns the first element in @var{list} for which
@var{predicate} is true; returns @code{#f} if it doesn't find such an
element. @var{Predicate} must be a procedure of one argument.
@end deffn
@deffn procedure find-tail predicate list
-(@acronym{SRFI} 1) Returns the first pair of @var{list} whose car
+(@asrfi{1}) Returns the first pair of @var{list} whose car
satisfies @var{predicate}; returns @code{#f} if there's no such pair.
@code{find-tail} can be viewed as a general-predicate variant of
@var{memv}.
@end deffn
@deffn procedure any predicate list list @dots{}
-(@acronym{SRFI} 1) Applies @var{predicate} across the @var{list}s,
+(@asrfi{1}) Applies @var{predicate} across the @var{list}s,
returning true if @var{predicate} returns true on any application.
If there are @math{n} list arguments @var{list1} @dots{} @var{listn},
@end deffn
@deffn procedure every predicate list list @dots{}
-(@acronym{SRFI} 1) Applies @var{predicate} across the @var{list}s,
+(@asrfi{1}) Applies @var{predicate} across the @var{list}s,
returning true if @var{predicate} returns true on every application.
If there are @math{n} list arguments @var{list1} @dots{} @var{listn},
@end group
@end example
-@code{circular-list} is compatible with @acronym{SRFI} 1, but extended
+@code{circular-list} is compatible with @usrfi{1}, but extended
so that it can be called with no arguments.
@end deffn
duration of a dynamic extent. @xref{Dynamic Binding}.
@deffn procedure make-parameter init [converter]
+@deffnx procedure make-unsettable-parameter init [converter]
Returns a newly allocated parameter object, which is a procedure that
accepts zero arguments and returns the value associated with the
parameter object. Initially this value is the value of
@var{converter} is not specified. The associated value can be
temporarily changed using the @code{parameterize} special form
(@pxref{parameterize}).
+
+The @code{make-parameter} procedure is standardized by @usrfi{39} and
+by @urseven{}, while @code{make-unsettable-parameter} is an MIT/GNU
+Scheme extension.
+@end deffn
+
+@deffn procedure make-settable-parameter init [converter]
+This procedure is like @code{make-parameter}, except that the returned
+parameter object may also be assigned by passing it an argument. Note
+that an assignment to a settable parameter affects only the extent of
+its current binding.
@end deffn
@deffn procedure parameterize* bindings thunk
@var{Bindings} should be an alist associating parameter objects with
new values. Returns the value of @var{thunk} while the parameters are
dynamically bound to the values.
+
+Note that the @code{parameterize} special form expands into a call to
+this procedure.
@end deffn
@anchor{Cells}
@var{Template} consists of the variable's name.
@cindex variable, entry category
+@item Parameter
+@var{Template} consists of the parameter's name. See @ref{Dynamic
+Binding} and @ref{Parameters} for more information.
+@cindex parameter, entry category
+
@item Special Form
@var{Template} starts with the syntactic keyword of the special form,
followed by a description of the special form's syntax. The description
@comment %**start of header
@setfilename mit-scheme-ref
@set EDITION 1.105
-@set VERSION 9.2.1
-@set UPDATED 2015-11-25
+@set VERSION 9.2.50
+@set UPDATED 2016-02-28
@settitle MIT/GNU Scheme @value{VERSION}
@comment %**end of header
@setchapternewpage odd
@insertcopying
@end ifnottex
+@macro asrfi {n}
+@acronym{SRFI} \n\
+@end macro
+
+@macro usrfi {n}
+@uref{http://srfi.schemers.org/srfi-\n\/srfi-\n\.html,@asrfi{\n\}}
+@end macro
+
+@macro rseven {}
+@acronym{R7RS}
+@end macro
+
+@macro urseven {}
+@uref{http://r7rs.org/,@rseven{}}
+@end macro
+
@menu
* Acknowledgements::
* Overview::
without passing it to the conversion procedure.
The value of the parameterize expression is the value of the last
body @var{expression}.
+
+The @code{parameterize} special form is standardized by @usrfi{39} and
+by @urseven{}.
@end deffn
Parameter objects can be used to specify configurable settings for a
@cindex binding expression, dynamic
@cindex dynamic binding
+@cindex dynamic environment
+@cindex dynamic extent
A @dfn{dynamic binding} changes the value of a parameter
(@pxref{Parameters}) object temporarily, for a @dfn{dynamic extent}.
The set of all dynamic bindings at a given time is called the
@cindex SRFI syntax
Several special forms have been introduced to support some of the
@uref{http://srfi.schemers.org/,Scheme Requests for Implementation}
-(@acronym{SRFI}). Note that MIT/GNU Scheme has for some time supported
-@uref{http://srfi.schemers.org/srfi-23/srfi-23.html,@acronym{SRFI} 23}
-(error-reporting mechanism) and
-@uref{http://srfi.schemers.org/srfi-30/srfi-30.html,@acronym{SRFI} 30}
-(nested multi-line comments), since these @acronym{SRFI}s reflect
-existing practice rather than introducing new functionality.
+(@acronym{SRFI}). Note that MIT/GNU Scheme has for some time
+supported @usrfi{23} (error-reporting mechanism) and @usrfi{30} (nested
+multi-line comments), since these @acronym{SRFI}s reflect existing
+practice rather than introducing new functionality.
@menu
* cond-expand (SRFI 0)::
@subsection cond-expand (SRFI 0)
@cindex SRFI 0
-@uref{http://srfi.schemers.org/srfi-0/srfi-0.html,@acronym{SRFI} 0}
-is a mechanism for portably determining the availability of
-@uref{http://srfi.schemers.org/,@acronym{SRFI}} @dfn{features}.
-The @code{cond-expand} special form conditionally expands according to
-the features available.
+@usrfi{0} is a mechanism for portably determining the availability of
+@uref{http://srfi.schemers.org/,@acronym{SRFI}} @dfn{features}. The
+@code{cond-expand} special form conditionally expands according to the
+features available.
@deffn {special form} cond-expand clause clause dots{}
Each @var{clause} has the form
Note that MIT/GNU Scheme allows @code{cond-expand} in any context where a
special form is allowed. This is an extension of the semantics defined
-by @acronym{SRFI 0}, which only allows @code{cond-expand} at top level.
+by @asrfi{0}, which only allows @code{cond-expand} at top level.
@end deffn
@node receive (SRFI 8), and-let* (SRFI 2), cond-expand (SRFI 0), SRFI syntax
@subsection receive (SRFI 8)
@cindex SRFI 8
-@uref{http://srfi.schemers.org/srfi-8/srfi-8.html,@acronym{SRFI} 8}
-defines a convenient syntax to bind an identifier to each of the values
-of a multiple-valued expression and then evaluate an expression in the
-scope of the bindings. As an instance of this pattern, consider the
-following excerpt from a @samp{quicksort} procedure:
+@usrfi{8} defines a convenient syntax to bind an identifier to each of
+the values of a multiple-valued expression and then evaluate an
+expression in the scope of the bindings. As an instance of this
+pattern, consider the following excerpt from a @samp{quicksort}
+procedure:
@example
@group
@subsection and-let* (SRFI 2)
@cindex SRFI 2
-@uref{http://srfi.schemers.org/srfi-2/srfi-2.html,@acronym{SRFI} 2}
-provides a form that combines @samp{and} and @samp{let*} for a
-logically short-circuiting sequential binding operator.
+@usrfi{2} provides a form that combines @samp{and} and @samp{let*} for
+a logically short-circuiting sequential binding operator.
@deffn {special form} and-let* (clause @dots{}) body
Runs through each of the clauses left-to-right, short-circuiting like
@subsection define-record-type (SRFI 9)
@cindex SRFI 9
-The @samp{define-record-type} syntax described in
-@uref{http://srfi.schemers.org/srfi-9/srfi-9.html,@acronym{SRFI} 9} is a
-slight simplification of one written for Scheme 48 by Jonathan Rees.
-Unlike many record-defining special forms, it does not create any new
+The @samp{define-record-type} syntax described in @usrfi{9} is a slight
+simplification of one written for Scheme 48 by Jonathan Rees. Unlike
+many record-defining special forms, it does not create any new
identifiers. Instead, the names of the record type, predicate,
constructor, and so on are all listed explicitly in the source. This
has the following advantages:
projects / mit-scheme.git / commitdiff