From 3bd95d398576765c62c3ace0e11716a7ae7cfae7 Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Sun, 28 Feb 2016 17:01:15 -0800 Subject: [PATCH] Refactor handling of SRFI references using macros. * Add macros for R7RS. * Tweak parameter sections. * Add make-unsettable-parameter and make-settable-parameter. --- doc/ref-manual/associations.texi | 20 ++++++------- doc/ref-manual/lists.texi | 40 ++++++++++++------------- doc/ref-manual/misc-datatypes.texi | 15 ++++++++++ doc/ref-manual/overview.texi | 5 ++++ doc/ref-manual/scheme.texinfo | 20 +++++++++++-- doc/ref-manual/special-forms.texi | 48 +++++++++++++++--------------- 6 files changed, 92 insertions(+), 56 deletions(-) diff --git a/doc/ref-manual/associations.texi b/doc/ref-manual/associations.texi index 845bb27fe..e2ca01ea5 100644 --- a/doc/ref-manual/associations.texi +++ b/doc/ref-manual/associations.texi @@ -382,22 +382,22 @@ constant of proportionality is described below (@pxref{Resizing of Hash 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 diff --git a/doc/ref-manual/lists.texi b/doc/ref-manual/lists.texi index a4f77a662..25021b438 100644 --- a/doc/ref-manual/lists.texi +++ b/doc/ref-manual/lists.texi @@ -183,7 +183,7 @@ Returns a newly allocated pair whose car is @var{obj1} and whose cdr is @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 @@ -221,7 +221,7 @@ error to take the @code{cdr} of the empty list. @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))) @@ -333,7 +333,7 @@ Here is a partial table of path/operation equivalents: @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 @@ -373,7 +373,7 @@ These expressions are equivalent: @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. @@ -384,7 +384,7 @@ length @var{k}, whose elements are all @var{element}. If @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 @@ -421,11 +421,11 @@ applied to these indices. (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 @@ -441,7 +441,7 @@ 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}) @@ -522,7 +522,7 @@ of @code{pair?} or @code{null?}. @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 @@ -535,7 +535,7 @@ list, otherwise returns @code{#f}. @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 @@ -562,7 +562,7 @@ a proper list. @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. @@ -746,7 +746,7 @@ procedure. @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. @@ -762,7 +762,7 @@ are reversed. @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 @@ -777,7 +777,7 @@ are reversed. @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 @@ -798,7 +798,7 @@ the returned lists may share a common tail with the argument @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. @@ -908,7 +908,7 @@ with the appropriate elements removed. The procedure returned by @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. @@ -945,7 +945,7 @@ reversed. @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}. @@ -1182,7 +1182,7 @@ is iterative in nature, combining the elements as the list is traversed. @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}, @@ -1221,7 +1221,7 @@ that it takes a single list and a predicate argument, in that order. @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}, @@ -1270,7 +1270,7 @@ respectively, except that the returned lists are circular. @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 diff --git a/doc/ref-manual/misc-datatypes.texi b/doc/ref-manual/misc-datatypes.texi index 11a8b54eb..61e6212be 100644 --- a/doc/ref-manual/misc-datatypes.texi +++ b/doc/ref-manual/misc-datatypes.texi @@ -413,6 +413,7 @@ This procedure computes a total order on symbols. It is equivalent to 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 @@ -420,12 +421,26 @@ 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} diff --git a/doc/ref-manual/overview.texi b/doc/ref-manual/overview.texi index a3adda952..54ffc7577 100644 --- a/doc/ref-manual/overview.texi +++ b/doc/ref-manual/overview.texi @@ -212,6 +212,11 @@ interpreted depending on @var{category}. @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 diff --git a/doc/ref-manual/scheme.texinfo b/doc/ref-manual/scheme.texinfo index 001da7a22..5c99312df 100644 --- a/doc/ref-manual/scheme.texinfo +++ b/doc/ref-manual/scheme.texinfo @@ -2,8 +2,8 @@ @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 @@ -68,6 +68,22 @@ Documentation License.'' @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:: diff --git a/doc/ref-manual/special-forms.texi b/doc/ref-manual/special-forms.texi index 2aa3e2825..385c43f4f 100644 --- a/doc/ref-manual/special-forms.texi +++ b/doc/ref-manual/special-forms.texi @@ -351,6 +351,9 @@ Then the previous value of @var{parameter} is restored 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 @@ -383,6 +386,8 @@ the call chain explicitly. @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 @@ -2790,12 +2795,10 @@ must be written using the @code{er-macro-transformer} syntax: @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):: @@ -2808,11 +2811,10 @@ existing practice rather than introducing new functionality. @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 @@ -2874,18 +2876,18 @@ present. 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 @@ -2973,9 +2975,8 @@ body are the values of the @samp{receive} expression. @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 @@ -3023,10 +3024,9 @@ Example: @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: -- 2.25.1