diff options
Diffstat (limited to 'slib.texi')
| -rw-r--r-- | slib.texi | 1926 |
1 files changed, 1198 insertions, 728 deletions
@@ -27,7 +27,7 @@ This file documents SLIB, the portable Scheme library. Copyright (C) 1993 Todd R. Eigenschink@* -Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999 Aubrey Jaffer +Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Aubrey Jaffer Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -74,7 +74,7 @@ you! @sp 1 @quotation SLIB @value{SLIBVERSION}, released @value{SLIBDATE}.@* -Aubrey Jaffer <jaffer @@ ai.mit.edu>@* +Aubrey Jaffer <agj @@ alum.mit.edu>@* @ifset html <A HREF="http://swissnet.ai.mit.edu/~jaffer/SLIB.html"> @end ifset @@ -87,7 +87,7 @@ Aubrey Jaffer <jaffer @@ ai.mit.edu>@* @ifclear html @vskip 0pt plus 1filll Copyright @copyright{} 1993 Todd R. Eigenschink@* -Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999 Aubrey Jaffer +Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Aubrey Jaffer Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -346,6 +346,7 @@ can automatically trigger catalog compilation by deleting @file{slibcat} or by invoking a special form of @code{require}: @deffn Procedure require @r{'new-catalog} +@cindex new-catalog This will load @file{mklibcat}, which compiles and writes a new @file{slibcat}. @end deffn @@ -469,12 +470,12 @@ should be either a string or a list. @noindent In the following functions if the argument @var{feature} is not a symbol -it is assumed to be a pathname.@refill +it is assumed to be a pathname. @defun provided? feature Returns @code{#t} if @var{feature} is a member of @code{*features*} or @code{*modules*} or if @var{feature} is supported by a file already -loaded and @code{#f} otherwise.@refill +loaded and @code{#f} otherwise. @end defun @deffn Procedure require feature @@ -493,7 +494,7 @@ unspecified value is returned. @deffn Procedure provide feature Assures that @var{feature} is contained in @code{*features*} if -@var{feature} is a symbol and @code{*modules*} otherwise.@refill +@var{feature} is a symbol and @code{*modules*} otherwise. @end deffn @defun require:feature->path feature @@ -535,7 +536,7 @@ compiled system (with multiple files) this would be the directory where the object or executable files are. If no file is currently loading it the result is undefined. @strong{Warning:} @code{program-vicinity} can return incorrect values if your program escapes back into a -@code{load}.@refill +@code{load}. @end defun @defun library-vicinity @@ -563,7 +564,7 @@ returns @code{#f}. @c @defun scheme-file-suffix @c Returns the default filename suffix for scheme source files. On most -@c systems this is @samp{.scm}.@refill +@c systems this is @samp{.scm}. @c @end defun @defun in-vicinity vicinity filename @@ -576,7 +577,7 @@ an absolute pathname and @var{vicinity} is equal to the value of @code{(user-vicinity)}. The behavior of @code{in-vicinity} when @var{filename} is absolute and @var{vicinity} is not equal to the value of @code{(user-vicinity)} is unspecified. For most systems -@code{in-vicinity} can be @code{string-append}.@refill +@code{in-vicinity} can be @code{string-append}. @end defun @defun sub-vicinity vicinity name @@ -584,7 +585,7 @@ Returns the vicinity of @var{vicinity} restricted to @var{name}. This is used for large systems where names of files in subsystems could conflict. On systems with directory structure @code{sub-vicinity} will return a pathname of the subdirectory @var{name} of -@var{vicinity}.@refill +@var{vicinity}. @end defun @@ -599,7 +600,7 @@ implementations. @defvr Constant char-code-limit An integer 1 larger that the largest value which can be returned by -@code{char->integer}.@refill +@code{char->integer}. @end defvr @defvr Constant most-positive-fixnum @@ -632,7 +633,7 @@ Displays the versions of SLIB and the underlying Scheme implementation and the name of the operating system. An unspecified value is returned. @example -(slib:report-version) @result{} slib "@value{SLIBVERSION}" on scm "5b1" on unix +(slib:report-version) @result{} slib "@value{SLIBVERSION}" on scm "5b1" on unix @end example @end defun @@ -650,15 +651,15 @@ Writes the report to file @file{filename}. @example (slib:report) @result{} -slib "@value{SLIBVERSION}" on scm "5b1" on unix -(implementation-vicinity) is "/home/jaffer/scm/" -(library-vicinity) is "/home/jaffer/slib/" -(scheme-file-suffix) is ".scm" -loaded *features* : +slib "@value{SLIBVERSION}" on scm "5b1" on unix +(implementation-vicinity) is "/home/jaffer/scm/" +(library-vicinity) is "/home/jaffer/slib/" +(scheme-file-suffix) is ".scm" +loaded *features* : trace alist qp sort common-list-functions macro values getopt compiled -implementation *features* : +implementation *features* : bignum complex real rational inexact vicinity ed getenv tmpnam abort transcript with-file @@ -669,9 +670,9 @@ implementation *features* : rev3-procedures rev2-procedures sun-dl string-case array dump char-ready? full-continuation system -implementation *catalog* : - (i/o-extensions compiled "/home/jaffer/scm/ioext.so") - ... +implementation *catalog* : + (i/o-extensions compiled "/home/jaffer/scm/ioext.so") + ... @end example @end defun @@ -690,13 +691,13 @@ feature then @code{#f} is always returned. @deffn Procedure delete-file filename Deletes the file specified by @var{filename}. If @var{filename} can not be deleted, @code{#f} is returned. Otherwise, @code{#t} is -returned.@refill +returned. @end deffn @deffn Procedure tmpnam Returns a pathname for a file which will likely not be used by any other process. Successive calls to @code{(tmpnam)} will return different -pathnames.@refill +pathnames. @end deffn @deffn Procedure current-error-port @@ -709,7 +710,7 @@ directed. Forces any pending output on @var{port} to be delivered to the output device and returns an unspecified value. The @var{port} argument may be omitted, in which case it defaults to the value returned by -@code{(current-output-port)}.@refill +@code{(current-output-port)}. @end deffn @deffn Procedure output-port-width @@ -717,7 +718,7 @@ omitted, in which case it defaults to the value returned by Returns the width of @var{port}, which defaults to @code{(current-output-port)} if absent. If the width cannot be -determined 79 is returned.@refill +determined 79 is returned. @end deffn @deffn Procedure output-port-height @@ -725,7 +726,7 @@ determined 79 is returned.@refill Returns the height of @var{port}, which defaults to @code{(current-output-port)} if absent. If the height cannot be -determined 24 is returned.@refill +determined 24 is returned. @end deffn @node Legacy, System, Input/Output, Built-in Support @@ -812,7 +813,7 @@ facility. the Scheme source code expressions and definitions are read from the file and @var{eval} called with them sequentially. The @code{slib:eval-load} procedure does not affect the values returned by -@code{current-input-port} and @code{current-output-port}.@refill +@code{current-input-port} and @code{current-output-port}. @end deffn @deffn Procedure slib:warn arg1 arg2 @dots{} @@ -823,7 +824,7 @@ Outputs a warning message containing the arguments. Outputs an error message containing the arguments, aborts evaluation of the current form and responds in a system dependent way to the error. Typical responses are to abort the program or to enter a read-eval-print -loop.@refill +loop. @end deffn @deffn Procedure slib:exit n @@ -870,7 +871,7 @@ using the package. * Syntactic Closures:: 'syntactic-closures * Syntax-Case Macros:: 'syntax-case -Syntax extensions (macros) included with SLIB. Also @xref{Structures}. +Syntax extensions (macros) included with SLIB. * Fluid-Let:: 'fluid-let * Yasos:: 'yasos, 'oop, 'collect @@ -904,7 +905,7 @@ and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain defmacro definitions. The @code{macro:load} procedure does not affect the values returned by @code{current-input-port} and -@code{current-output-port}.@refill +@code{current-output-port}. @end defun @defun defmacro? sym @@ -917,7 +918,7 @@ Returns @code{#t} if @var{sym} has been defined by @code{defmacro}, If @var{form} is a macro call, @code{macroexpand-1} will expand the macro call once and return it. A @var{form} is considered to be a macro call only if it is a cons whose @code{car} is a symbol for which a -@code{defmacr} has been defined. +@code{defmacro} has been defined. @code{macroexpand} is similar to @code{macroexpand-1}, but repeatedly expands @var{form} until it is no longer a macro call. @@ -967,7 +968,7 @@ the @code{macro:load} procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The @code{macro:load} procedure does not affect the values returned by -@code{current-input-port} and @code{current-output-port}.@refill +@code{current-input-port} and @code{current-output-port}. @end deffn @node Macro by Example, Macros That Work, R4RS Macros, Scheme Syntax Extension Packages @@ -977,7 +978,7 @@ code expressions and definitions may contain macro definitions. The @ftindex macro-by-example A vanilla implementation of @cite{Macro by Example} (Eugene Kohlbecker, -R4RS) by Dorai Sitaram, (dorai@@cs.rice.edu) using @code{defmacro}. +R4RS) by Dorai Sitaram, (dorai @@ cs.rice.edu) using @code{defmacro}. @itemize @bullet @@ -1072,7 +1073,7 @@ the macro expansion. @code{macro:eval} returns the value of @var{expression} in the current top level environment. @var{expression} can contain macro definitions. Side effects of @var{expression} will affect the top level -environment.@refill +environment. @end defun @deffn Procedure macro:load filename @@ -1082,7 +1083,7 @@ the @code{macro:load} procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The @code{macro:load} procedure does not affect the values returned by -@code{current-input-port} and @code{current-output-port}.@refill +@code{current-input-port} and @code{current-output-port}. @end deffn References: @@ -1090,7 +1091,7 @@ References: The @cite{Revised^4 Report on the Algorithmic Language Scheme} Clinger and Rees [editors]. To appear in LISP Pointers. Also available as a technical report from the University of Oregon, MIT AI Lab, and -Cornell.@refill +Cornell. @center Macros That Work. Clinger and Rees. POPL '91. @@ -1254,7 +1255,7 @@ unnecessarily. That shouldn't matter very often. @defun macro:expand expression @defunx synclo:expand expression Returns scheme code with the macros and derived expression types of -@var{expression} expanded to primitive expression types.@refill +@var{expression} expanded to primitive expression types. @end defun @defun macro:eval expression @@ -1262,7 +1263,7 @@ Returns scheme code with the macros and derived expression types of @code{macro:eval} returns the value of @var{expression} in the current top level environment. @var{expression} can contain macro definitions. Side effects of @var{expression} will affect the top level -environment.@refill +environment. @end defun @deffn Procedure macro:load filename @@ -1272,7 +1273,7 @@ the @code{macro:load} procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The @code{macro:load} procedure does not affect the values returned by -@code{current-input-port} and @code{current-output-port}.@refill +@code{current-input-port} and @code{current-output-port}. @end deffn @subsection Syntactic Closure Macro Facility @@ -1306,7 +1307,7 @@ The description of the facility is divided into three parts. The first part defines basic terminology. The second part describes how macro transformers are defined. The third part describes the use of @dfn{identifiers}, which extend the syntactic closure mechanism to be -compatible with @code{syntax-rules}.@refill +compatible with @code{syntax-rules}. @subsubsection Terminology @@ -1335,7 +1336,7 @@ define appear anywhere in a form that the symbol could be used, and when quoted it is replaced by the symbol; however, it does not satisfy the predicate @code{symbol?}. Macro transformers rarely distinguish symbols from -aliases, referring to both as identifiers.@refill +aliases, referring to both as identifiers. @item A @dfn{syntactic} environment maps identifiers to their meanings. More precisely, it determines whether an identifier is a @@ -1344,7 +1345,7 @@ interpretation for the form in which that keyword appears. If it is a variable, the meaning identifies which binding of that variable is referenced. In short, syntactic environments contain all of the contextual information necessary for interpreting the meaning of a -particular form.@refill +particular form. @item A @dfn{syntactic closure} consists of a form, a syntactic environment, and a list of identifiers. All identifiers in the form @@ -1355,7 +1356,7 @@ which its form could have been used. Since a syntactic closure is also a form, it may not be used in contexts where a form would be illegal. For example, a form may not appear as a clause in the cond special form. A syntactic closure appearing in a quoted structure is replaced by its -form.@refill +form. @end itemize @@ -1363,18 +1364,18 @@ form.@refill This section describes the @code{transformer} special form and the procedures @code{make-syntactic-closure} and -@code{capture-syntactic-environment}.@refill +@code{capture-syntactic-environment}. @deffn Syntax transformer expression Syntax: It is an error if this syntax occurs except as a -@var{transformer spec}.@refill +@var{transformer spec}. Semantics: The @var{expression} is evaluated in the standard transformer environment to yield a macro transformer as described below. This macro transformer is bound to a macro keyword by the special form in which the @code{transformer} expression appears (for example, -@code{let-syntax}).@refill +@code{let-syntax}). A @dfn{macro transformer} is a procedure that takes two arguments, a form and a syntactic environment, and returns a new form. The first @@ -1383,7 +1384,7 @@ occurred. The second argument, the @dfn{usage environment}, is the syntactic environment in which the input form occurred. The result of the transformer, the @dfn{output form}, is automatically closed in the @dfn{transformer environment}, which is the syntactic environment in -which the @code{transformer} expression occurred.@refill +which the @code{transformer} expression occurred. For example, here is a definition of a push macro using @code{syntax-rules}:@refill @@ -1409,7 +1410,7 @@ Here is an equivalent definition using @code{transformer}: In this example, the identifiers @code{set!} and @code{cons} are closed in the transformer environment, and thus will not be affected by the meanings of those identifiers in the usage environment -@code{env}.@refill +@code{env}. Some macros may be non-hygienic by design. For example, the following defines a loop macro that implicitly binds @code{exit} to an escape @@ -1433,7 +1434,7 @@ be left free when the body is closed:@refill To assign meanings to the identifiers in a form, use @code{make-syntactic-closure} to close the form in a syntactic -environment.@refill +environment. @end deffn @defun make-syntactic-closure environment free-names form @@ -1444,13 +1445,13 @@ be a list of identifiers, and @var{form} must be a form. of @var{form} in @var{environment}, which can be used anywhere that @var{form} could have been used. All the identifiers used in @var{form}, except those explicitly excepted by @var{free-names}, obtain -their meanings from @var{environment}.@refill +their meanings from @var{environment}. Here is an example where @var{free-names} is something other than the empty list. It is instructive to compare the use of @var{free-names} in this example with its use in the @code{loop} example above: the examples are similar except for the source of the identifier being left -free.@refill +free. @lisp (define-syntax let1 (transformer @@ -1468,10 +1469,10 @@ single identifier, and whose body consists of a single expression. When the body expression is syntactically closed in its original syntactic environment, the identifier that is to be bound by @code{let1} must be left free, so that it can be properly captured by the @code{lambda} in -the output form.@refill +the output form. To obtain a syntactic environment other than the usage environment, use -@code{capture-syntactic-environment}.@refill +@code{capture-syntactic-environment}. @end defun @defun capture-syntactic-environment procedure @@ -1479,7 +1480,7 @@ To obtain a syntactic environment other than the usage environment, use @code{capture-syntactic-environment} returns a form that will, when transformed, call @var{procedure} on the current syntactic environment. @var{procedure} should compute and return a new form to be transformed, -in that same syntactic environment, in place of the form.@refill +in that same syntactic environment, in place of the form. An example will make this clear. Suppose we wanted to define a simple @code{loop-until} keyword equivalent to@refill @@ -1522,7 +1523,7 @@ that it will be captured by the binding introduced by the @code{lambda} expression. Unfortunately it uses the identifiers @code{if} and @code{loop} within that @code{lambda} expression, so if the user of @code{loop-until} just happens to use, say, @code{if} for the -identifier, it will be inadvertently captured.@refill +identifier, it will be inadvertently captured. The syntactic environment that @code{if} and @code{loop} want to be exposed to is the one just outside the @code{lambda} expression: before @@ -1558,7 +1559,7 @@ as follows:@refill In this case, having captured the desired syntactic environment, it is convenient to construct syntactic closures of the identifiers @code{if} and the @code{loop} and use them in the body of the -@code{lambda}.@refill +@code{lambda}. A common use of @code{capture-syntactic-environment} is to get the transformer environment of a macro transformer:@refill @@ -1577,7 +1578,7 @@ This section describes the procedures that create and manipulate identifiers. Previous syntactic closure proposals did not have an identifier data type -- they just used symbols. The identifier data type extends the syntactic closures facility to be compatible with the -high-level @code{syntax-rules} facility.@refill +high-level @code{syntax-rules} facility. As discussed earlier, an identifier is either a symbol or an @dfn{alias}. An alias is implemented as a syntactic closure whose @@ -1592,7 +1593,7 @@ like syntactic closures most of the time. The difference is that an alias may be bound to a new value (for example by @code{lambda} or @code{let-syntax}); other syntactic closures may not be used this way. If an alias is bound, then within the scope of that binding it is looked -up in the syntactic environment just like any other identifier.@refill +up in the syntactic environment just like any other identifier. Aliases are used in the implementation of the high-level facility @code{syntax-rules}. A macro transformer created by @code{syntax-rules} @@ -1637,7 +1638,7 @@ the final clause in the conditional. A macro transformer for replaced the symbol @code{else} with an alias. Instead the transformer must look for an identifier that ``means the same thing'' in the usage environment as the symbol @code{else} means in the transformer -environment.@refill +environment. @end defun @defun identifier=? environment1 identifier1 environment2 identifier2 @@ -1684,7 +1685,7 @@ The syntactic closures facility was invented by Alan Bawden and Jonathan Rees. The use of aliases to implement @code{syntax-rules} was invented by Alan Bawden (who prefers to call them @dfn{synthetic names}). Much of this proposal is derived from an earlier proposal by Alan -Bawden.@refill +Bawden. @@ -1699,7 +1700,7 @@ Bawden.@refill @defun macro:expand expression @defunx syncase:expand expression Returns scheme code with the macros and derived expression types of -@var{expression} expanded to primitive expression types.@refill +@var{expression} expanded to primitive expression types. @end defun @defun macro:eval expression @@ -1707,7 +1708,7 @@ Returns scheme code with the macros and derived expression types of @code{macro:eval} returns the value of @var{expression} in the current top level environment. @var{expression} can contain macro definitions. Side effects of @var{expression} will affect the top level -environment.@refill +environment. @end defun @deffn Procedure macro:load filename @@ -1717,14 +1718,14 @@ the @code{macro:load} procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The @code{macro:load} procedure does not affect the values returned by -@code{current-input-port} and @code{current-output-port}.@refill +@code{current-input-port} and @code{current-output-port}. @end deffn This is version 2.1 of @code{syntax-case}, the low-level macro facility proposed and implemented by Robert Hieb and R. Kent Dybvig. This version is further adapted by Harald Hanche-Olsen -<hanche@@imf.unit.no> to make it compatible with, and easily usable +<hanche @@ imf.unit.no> to make it compatible with, and easily usable with, SLIB. Mainly, these adaptations consisted of: @itemize @bullet @@ -1755,7 +1756,7 @@ distribution with them. If you do intend to use @code{syntax-case}, however, you should get these files and print them out on a PostScript printer. They are available with the original @code{syntax-case} distribution by anonymous FTP in -@file{cs.indiana.edu:/pub/scheme/syntax-case}.@refill +@file{cs.indiana.edu:/pub/scheme/syntax-case}. In order to use syntax-case from an interactive top level, execute: @lisp @@ -1783,14 +1784,14 @@ Gambit). All R4RS syntactic forms are defined, including @code{delay}. Along with @code{delay} are simple definitions for @code{make-promise} (into -which @code{delay} expressions expand) and @code{force}.@refill +which @code{delay} expressions expand) and @code{force}. @code{syntax-rules} and @code{with-syntax} (described in @cite{TR356}) -are defined.@refill +are defined. @code{syntax-case} is actually defined as a macro that expands into calls to the procedure @code{syntax-dispatch} and the core form -@code{syntax-lambda}; do not redefine these names.@refill +@code{syntax-lambda}; do not redefine these names. Several other top-level bindings not documented in TR356 are created: @itemize @bullet @@ -1800,14 +1801,14 @@ Several other top-level bindings not documented in TR356 are created: @end itemize The syntax of define has been extended to allow @code{(define @var{id})}, -which assigns @var{id} to some unspecified value.@refill +which assigns @var{id} to some unspecified value. We have attempted to maintain R4RS compatibility where possible. The incompatibilities should be confined to @file{hooks.ss}. Please let us -know if there is some incompatibility that is not flagged as such.@refill +know if there is some incompatibility that is not flagged as such. Send bug reports, comments, suggestions, and questions to Kent Dybvig -(dyb@@iuvax.cs.indiana.edu). +(dyb @@ iuvax.cs.indiana.edu). @subsection Note from maintainer @@ -1833,14 +1834,14 @@ unspecified order), the current values of the @var{variable}s are saved, the results are assigned to the @var{variable}s, the @var{expression}s are evaluated sequentially in the current environment, the @var{variable}s are restored to their original values, and the value of -the last @var{expression} is returned.@refill +the last @var{expression} is returned. The syntax of this special form is similar to that of @code{let}, but @code{fluid-let} temporarily rebinds existing @var{variable}s. Unlike @code{let}, @code{fluid-let} creates no new bindings; instead it @emph{assigns} the values of each @var{init} to the binding (determined by the rules of lexical scoping) of its corresponding -@var{variable}.@refill +@var{variable}. @node Yasos, , Fluid-Let, Scheme Syntax Extension Packages @@ -1857,7 +1858,7 @@ by the rules of lexical scoping) of its corresponding `Yet Another Scheme Object System' is a simple object system for Scheme based on the paper by Norman Adams and Jonathan Rees: @cite{Object Oriented Programming in Scheme}, Proceedings of the 1988 ACM Conference -on LISP and Functional Programming, July 1988 [ACM #552880].@refill +on LISP and Functional Programming, July 1988 [ACM #552880]. Another reference is: @@ -1901,12 +1902,12 @@ first ancestor which contains it (in the ancestor @code{let}). An operation may be applied to any Scheme data object---not just instances. As code which creates instances is just code, there are no @dfn{classes} and no meta-@var{anything}. Method dispatch is by a procedure call a la -CLOS rather than by @code{send} syntax a la Smalltalk.@refill +CLOS rather than by @code{send} syntax a la Smalltalk. @item Disclaimer: There are a number of optimizations which can be made. This implementation is expository (although performance should be quite -reasonable). See the L&FP paper for some suggestions.@refill +reasonable). See the L&FP paper for some suggestions. @end table @@ -1919,21 +1920,21 @@ reasonable). See the L&FP paper for some suggestions.@refill @deffn Syntax define-operation @code{(}opname self arg @dots{}@code{)} @var{default-body} Defines a default behavior for data objects which don't handle the operation @var{opname}. The default behavior (for an empty -@var{default-body}) is to generate an error.@refill +@var{default-body}) is to generate an error. @end deffn @deffn Syntax define-predicate opname? Defines a predicate @var{opname?}, usually used for determining the @dfn{type} of an object, such that @code{(@var{opname?} @var{object})} returns @code{#t} if @var{object} has an operation @var{opname?} and -@code{#f} otherwise.@refill +@code{#f} otherwise. @end deffn @deffn Syntax object @code{((@var{name} @var{self} @var{arg} @dots{}) @var{body})} @dots{} Returns an object (an instance of the object system) with operations. Invoking @code{(@var{name} @var{object} @var{arg} @dots{}} executes the @var{body} of the @var{object} with @var{self} bound to @var{object} and -with argument(s) @var{arg}@dots{}.@refill +with argument(s) @var{arg}@dots{}. @end deffn @deffn Syntax object-with-ancestors @code{((}ancestor1 init1@code{)} @dots{}@code{)} operation @dots{} @@ -1948,7 +1949,7 @@ ancestor in the ancestor list. @deffn Syntax operate-as component operation self arg @dots{} Used in an operation definition (of @var{self}) to invoke the @var{operation} in an ancestor @var{component} but maintain the object's -identity. Also known as ``send-to-super''.@refill +identity. Also known as ``send-to-super''. @end deffn @deffn Procedure print obj port @@ -1961,7 +1962,7 @@ A default @code{print} operation is provided which is just @code{(format The default method returns the number of elements in @var{obj} if it is a vector, string or list, @code{2} for a pair, @code{1} for a character and by default id an error otherwise. Objects such as collections -(@pxref{Collections}) may override the default in an obvious way.@refill +(@pxref{Collections}) may override the default in an obvious way. @end defun @@ -2143,7 +2144,10 @@ value is unspecified. * Format:: Common-Lisp Format * Standard Formatted I/O:: Posix printf and scanf * Programs and Arguments:: -* HTML HTTP and CGI:: Generate pages and serve WWW sites +* HTML:: +* HTML Tables:: Databases meet HTML +* HTTP and CGI:: Serve WWW sites +* URI:: Uniform Resource Identifier * Printing Scheme:: Nicely * Time and Date:: * Vector Graphics:: @@ -2762,7 +2766,7 @@ An output conversion specifications consist of an initial @samp{%} character followed in sequence by: @itemize @bullet -@item +@item Zero or more @dfn{flag characters} that modify the normal behavior of the conversion specification. @@ -2804,7 +2808,7 @@ flag is also specified, or if a precision is specified for an exact converson. @end table -@item +@item An optional decimal integer specifying the @dfn{minimum field width}. If the normal conversion produces fewer characters than this, the field is padded (with spaces or zeros per the @samp{0} flag) to the specified @@ -2818,7 +2822,7 @@ field width. The width value must be an integer. If the value is negative it is as though the @samp{-} flag is set (see above) and the absolute value is used as the field width. -@item +@item An optional @dfn{precision} to specify the number of digits to be written for numeric conversions and the maximum field width for string conversions. The precision is specified by a period (@samp{.}) followed @@ -2864,6 +2868,12 @@ A character that specifies the conversion to be applied. @subsubsection Exact Conversions @table @asis +@item @samp{b}, @samp{B} +Print an integer as an unsigned binary number. + +@emph{Note:} @samp{%b} and @samp{%B} are SLIB extensions. + + @item @samp{d}, @samp{i} Print an integer as a signed decimal number. @samp{%d} and @samp{%i} are synonymous for output, but are different when used with @code{scanf} @@ -2894,10 +2904,16 @@ between mantissa and exponont. @item @samp{g}, @samp{G} Print a floating-point number in either fixed or exponential notation, -whichever is more appropriate for its magnitude. Unless an @samp{#} flag -has been supplied trailing zeros after a decimal point will be stripped -off. @samp{%g} prints @samp{e} between mantissa and exponont. +whichever is more appropriate for its magnitude. Unless an @samp{#} +flag has been supplied, trailing zeros after a decimal point will be +stripped off. @samp{%g} prints @samp{e} between mantissa and exponont. @samp{%G} prints @samp{E} between mantissa and exponent. + +@item @samp{k}, @samp{K} +Print a number like @samp{%g}, except that an SI prefix is output after +the number, which is scaled accordingly. @samp{%K} outputs a space +between number and prefix, @samp{%k} does not. + @end table @subsubsection Other Conversions @@ -2935,7 +2951,7 @@ are output. @item @samp{%} Print a literal @samp{%} character. No argument is consumed. It is an -error to specifiy flags, field width, precision, or type modifiers with +error to specify flags, field width, precision, or type modifiers with @samp{%%}. @end table @end deffn @@ -3110,7 +3126,7 @@ left unread in the input stream. @end defmac -@node Programs and Arguments, HTML HTTP and CGI, Standard Formatted I/O, Textual Conversion Packages +@node Programs and Arguments, HTML, Standard Formatted I/O, Textual Conversion Packages @section Program and Arguments @menu @@ -3242,7 +3258,7 @@ Example: @defun getopt-- argc argv optstring The procedure @code{getopt--} is an extended version of @code{getopt} which parses @dfn{long option names} of the form -@samp{--hold-the-onions} and @samp{--verbosity-level=extreme}. +@samp{--hold-the-onions} and @samp{--verbosity-level=extreme}. @w{@code{Getopt--}} behaves as @code{getopt} except for non-empty options beginning with @samp{--}. @@ -3270,11 +3286,11 @@ errors. (define opt (getopt-- argc argv opts)) (print *optind* opt *optarg*))) @print{} -2 #\b "9" -3 "f1" #f -4 "2" "" -5 "g3" "35234.342" -5 #f "35234.342" +2 #\b "9" +3 "f1" #f +4 "2" "" +5 "g3" "35234.342" +5 #f "35234.342" @end example @end defun @@ -3393,6 +3409,15 @@ Returns an empty parameter-list with slots for @var{parameter-names}. @var{parameter-name} of @var{parameter-list}. @end deffn +@deffn Function remove-parameter parameter-name parameter-list +Removes the parameter @var{parameter-name} from @var{parameter-list}. +@code{remove-parameter} does not alter the argument +@var{parameter-list}. + +If there are more than one @var{parameter-name} parameters, an error is +signaled. +@end deffn + @deffn Procedure adjoin-parameters! parameter-list parameter1 @dots{} Returns @var{parameter-list} with @var{parameter1} @dots{} merged in. @end deffn @@ -3425,7 +3450,7 @@ which created @var{parameter-list}. @code{check-parameters} returns @var{parameter-list} if each @var{check} of the corresponding @var{parameter-list} returns non-false. If some -@var{check} returns @code{#f} an error is signaled. +@var{check} returns @code{#f} a warning is signaled. @end deffn @noindent @@ -3445,11 +3470,11 @@ Any number of parameters are acceptable. One or more of parameters are acceptable. @end table -@deffn Function parameter-list->arglist positions arities types parameter-list +@deffn Function parameter-list->arglist positions arities parameter-list Returns @var{parameter-list} converted to an argument list. Parameters of @var{arity} type @code{single} and @code{boolean} are converted to the single value associated with them. The other @var{arity} types are -converted to lists of the value(s) of type @var{types}. +converted to lists of the value(s). @var{positions} is a list of positive integers whose order matches the order of the @var{parameter-name}s in the call to @@ -3464,19 +3489,38 @@ should appear. @code{(require 'getopt-parameters)} -@deffn Function getopt->parameter-list argc argv optnames arities types aliases +@deffn Function getopt->parameter-list argc argv optnames arities types aliases desc @dots{} Returns @var{argv} converted to a parameter-list. @var{optnames} are -the parameter-names. @var{aliases} is a list of lists of strings and -elements of @var{optnames}. Each of these strings which have length of -1 will be treated as a single @key{-} option by @code{getopt}. Longer -strings will be treated as long-named options (@pxref{Getopt, getopt--}). +the parameter-names. @var{arities} and @var{types} are lists of symbols +corresponding to @var{optnames}. + +@var{aliases} is a list of lists of strings or integers paired with +elements of @var{optnames}. Each one-character string will be treated +as a single @samp{-} option by @code{getopt}. Longer strings will be +treated as long-named options (@pxref{Getopt, getopt--}). + +If the @var{aliases} association list has only strings as its +@code{car}s, then all the option-arguments after an option (and before +the next option) are adjoined to that option. + +If the @var{aliases} association list has integers, then each (string) +option will take at most one option-argument. Unoptioned arguments are +collected in a list. A @samp{-1} alias will take the last argument in +this list; @samp{+1} will take the first argument in the list. The +aliases -2 then +2; -3 then +3; @dots{} are tried so long as a positive +or negative consecutive alias is found and arguments remain in the list. +Finally a @samp{0} alias, if found, absorbs any remaining arguments. + +In all cases, if unclaimed arguments remain after processing, a warning +is signaled and #f is returned. @end deffn -@deffn Function getopt->arglist argc argv optnames positions arities types defaulters checks aliases +@deffn Function getopt->arglist argc argv optnames positions arities types defaulters checks aliases desc @dots{} Like @code{getopt->parameter-list}, but converts @var{argv} to an argument-list as specified by @var{optnames}, @var{positions}, @var{arities}, @var{types}, @var{defaulters}, @var{checks}, and -@var{aliases}. +@var{aliases}. If the options supplied violate the @var{arities} or +@var{checks} constraints, then a warning is signaled and #f is returned. @end deffn @noindent @@ -3486,7 +3530,8 @@ make-command-server}. @noindent If errors are encountered while processing options, directions for using -the options are printed to @code{current-error-port}. +the options (and argument strings @var{desc} @dots{}) are printed to +@code{current-error-port}. @example (begin @@ -3514,19 +3559,20 @@ the options are printed to @code{current-error-port}. @print{} Usage: cmd [OPTION ARGUMENT ...] ... - -f, --flag - -o, --optional=<number> + -f, --flag + -o, --optional=<number> -n, --nary=<symbols> ... -N, --nary1=<symbols> ... - -s, --single=<string> - --Flag - -B + -s, --single=<string> + --Flag + -B -a <num2> ... --Abs=<num3> ... ERROR: getopt->parameter-list "unrecognized option" "-?" @end example + @node Filenames, Batch, Getopt Parameter lists, Programs and Arguments @subsection Filenames @@ -3867,13 +3913,32 @@ hello world @end example -@node HTML HTTP and CGI, Printing Scheme, Programs and Arguments, Textual Conversion Packages -@section HTML Forms +@node HTML, HTML Tables, Programs and Arguments, Textual Conversion Packages +@section HTML @include htmlform.txi -@node Printing Scheme, Time and Date, HTML HTTP and CGI, Textual Conversion Packages +@node HTML Tables, HTTP and CGI, HTML, Textual Conversion Packages +@section HTML Tables + +@include db2html.txi + + +@node HTTP and CGI, URI, HTML Tables, Textual Conversion Packages +@section HTTP and CGI + +@include http-cgi.txi + + +@node URI, Printing Scheme, HTTP and CGI, Textual Conversion Packages +@section URI + +@include uri.txi + + + +@node Printing Scheme, Time and Date, URI, Textual Conversion Packages @section Printing Scheme @menu @@ -3893,7 +3958,7 @@ hello world (or Scheme program expression) into its textual representation and prints it. The interface to the procedure is sufficiently general to easily implement other useful formatting procedures such as pretty -printing, output to a string and truncated output.@refill +printing, output to a string and truncated output. @deffn Procedure generic-write obj display? width output @table @var @@ -3967,6 +4032,53 @@ Example: @end example @end deffn +@deffn Procedure pretty-print->string obj +@deffnx Procedure pretty-print->string obj width + +Returns the string of @var{obj} @code{pretty-print}ed in @var{width} +columns. If @var{width} is not specified, @code{(output-port-width)} is +used. + +Example: +@example +@group +(pretty-print->string '((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) + (16 17 18 19 20) (21 22 23 24 25))) +@result{} +"((1 2 3 4 5) + (6 7 8 9 10) + (11 12 13 14 15) + (16 17 18 19 20) + (21 22 23 24 25)) +" +@end group +@group +(pretty-print->string '((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) + (16 17 18 19 20) (21 22 23 24 25)) + 16) +@result{} +"((1 2 3 4 5) + (6 7 8 9 10) + (11 + 12 + 13 + 14 + 15) + (16 + 17 + 18 + 19 + 20) + (21 + 22 + 23 + 24 + 25)) +" +@end group +@end example +@end deffn + @code{(require 'pprint-file)} @ftindex pprint-file @@ -3975,7 +4087,7 @@ Example: @deffnx Procedure pprint-file infile outfile Pretty-prints all the code in @var{infile}. If @var{outfile} is specified, the output goes to @var{outfile}, otherwise it goes to -@code{(current-output-port)}.@refill +@code{(current-output-port)}. @end deffn @defun pprint-filter-file infile proc outfile @@ -3991,7 +4103,7 @@ are then @code{pretty-print}ed to this port. Whitepsace and comments (introduced by @code{;}) which are not part of scheme expressions are reproduced in the output. This procedure does not affect the values returned by @code{current-input-port} and -@code{current-output-port}.@refill +@code{current-output-port}. @end defun @code{pprint-filter-file} can be used to pre-compile macro-expansion and @@ -4116,7 +4228,7 @@ Creates and returns a time-zone object specified by the string @var{tz} is a time-zone object. @code{tz:params} returns a list of three items: @enumerate 0 -@item +@item An integer. 0 if standard time is in effect for timezone @var{tz} at @var{caltime}; 1 if daylight savings time is in effect for timezone @var{tz} at @var{caltime}. @@ -4389,110 +4501,7 @@ be mixed with regular text and ANSI or other terminal control sequences. @node Schmooz, , Vector Graphics, Textual Conversion Packages @section Schmooz -@cindex schmooz -@dfn{Schmooz} is a simple, lightweight markup language for interspersing -Texinfo documentation with Scheme source code. Schmooz does not create -the top level Texinfo file; it creates @samp{txi} files which can be -imported into the documentation using the Texinfo command -@samp{@@include}. - -@ftindex schmooz -@code{(require 'schmooz)} defines the function @code{schmooz}, which is -used to process files. Files containing schmooz documentation should -not contain @code{(require 'schmooz)}. - -@deffn Procedure schmooz filename@r{scm} @dots{} -@var{Filename}scm should be a string ending with @samp{scm} naming an -existing file containing Scheme source code. @code{schmooz} extracts -top-level comments containing schmooz commands from @var{filename}scm -and writes the converted Texinfo source to a file named -@var{filename}txi. - -@deffnx Procedure schmooz filename@r{texi} @dots{} -@deffnx Procedure schmooz filename@r{tex} @dots{} -@deffnx Procedure schmooz filename@r{txi} @dots{} -@var{Filename} should be a string naming an existing file containing -Texinfo source code. For every occurrence of the string @samp{@@include -@var{filename}txi} within that file, @code{schmooz} calls itself with -the argument @samp{@var{filename}scm}. -@end deffn - -Schmooz comments are distinguished (from non-schmooz comments) by their -first line, which must start with an at-sign (@@) preceded by one or -more semicolons (@t{;}). A schmooz comment ends at the first subsequent -line which does @emph{not} start with a semicolon. Currently schmooz -comments are recognized only at top level. - -Schmooz comments are copied to the Texinfo output file with the leading -contiguous semicolons removed. Certain character sequences starting -with at-sign are treated specially. Others are copied unchanged. - -A schmooz comment starting with @samp{@@body} must be followed by a -Scheme definition. All comments between the @samp{@@body} line and -the definition will be included in a Texinfo definition, either -a @samp{@@defun} or a @samp{@@defvar}, depending on whether a procedure -or a variable is being defined. - -Within the text of that schmooz comment, at-sign -followed by @samp{0} will be replaced by @code{@@code@{procedure-name@}} -if the following definition is of a procedure; or -@code{@@var@{variable@}} if defining a variable. - -An at-sign followed by a non-zero digit will expand to the variable -citation of that numbered argument: @samp{@@var@{argument-name@}}. - -If more than one definition follows a @samp{@@body} comment line -without an intervening blank or comment line, then those definitions -will be included in the same Texinfo definition using @samp{@@defvarx} -or @samp{@@defunx}, depending on whether the first definition is of -a variable or of a procedure. - -Schmooz can figure out whether a definition is of a procedure if -it is of the form: - -@samp{(define (<identifier> <arg> ...) <expression>)} - -@noindent -or if the left hand side of the definition is some form ending in -a lambda expression. Obviously, it can be fooled. In order to -force recognition of a procedure definition, start the documentation -with @samp{@@args} instead of @samp{@@body}. @samp{@@args} should -be followed by the argument list of the function being defined, -which may be enclosed in parentheses and delimited by whitespace, -(as in Scheme), enclosed in braces and separated by commas, (as -in Texinfo), or consist of the remainder of the line, separated -by whitespace. - -For example: - -@example -;;@@args arg1 args ... -;;@@0 takes argument @@1 and any number of @@2 -(define myfun (some-function-returning-magic)) -@end example - -Will result in: - -@example -@@defun myfun arg1 args @@dots@{@} - -@@code@{myfun@} takes argument @@var@{arg1@} and any number of @@var@{args@} -@@end defun -@end example - -@samp{@@args} may also be useful for indicating optional arguments -by name. If @samp{@@args} occurs inside a schmooz comment section, -rather than at the beginning, then it will generate a @samp{@@defunx} -line with the arguments supplied. - - -If the first at-sign in a schmooz comment is immediately followed by -whitespace, then the comment will be expanded to whatever follows that -whitespace. If the at-sign is followed by a non-whitespace character -then the at-sign will be included as the first character of the expansion. -This feature is intended to make it easy to include Texinfo directives -in schmooz comments. - +@include schmooz.texi @node Mathematical Packages, Database Packages, Textual Conversion Packages, Top @chapter Mathematical Packages @@ -4506,6 +4515,7 @@ in schmooz comments. * Cyclic Checksum:: 'make-crc * Plotting:: 'charplot * Root Finding:: 'root +* Minimizing:: 'minimize * Commutative Rings:: 'commutative-ring * Determinant:: 'determinant @end menu @@ -4522,7 +4532,7 @@ The bit-twiddling functions are made available through the use of the @code{(require 'logical)} before the code that uses these @ftindex logical functions. These functions behave as though operating on integers -in two's-complement representation.@refill +in two's-complement representation. @subheading Bitwise Operations @@ -4655,7 +4665,7 @@ Example: Returns an integer the same as @var{to} except possibly in the @var{start} (inclusive) through @var{end} (exclusive) bits, which are the same as those of @var{from}. The 0-th bit of @var{from} becomes the -@var{start}th bit of the result.@refill +@var{start}th bit of the result. Example: @example @@ -4668,7 +4678,7 @@ Example: @defun ash int count Returns an integer equivalent to -@code{(inexact->exact (floor (* @var{int} (expt 2 @var{count}))))}.@refill +@code{(inexact->exact (floor (* @var{int} (expt 2 @var{count}))))}. Example: @lisp @@ -4713,7 +4723,7 @@ Example: @defun extended-euclid n1 n2 Returns a list of 3 integers @code{(d x y)} such that d = gcd(@var{n1}, -@var{n2}) = @var{n1} * x + @var{n2} * y.@refill +@var{n2}) = @var{n1} * x + @var{n2} * y. @end defun @defun symmetric:modulus n @@ -4795,7 +4805,7 @@ Returns (@var{k2} ^ @var{k3}) mod @var{modulus}. @ftindex factor @ftindex primes -@c @include factor.txi +@include factor.txi @node Random Numbers, Fast Fourier Transform, Prime Numbers, Mathematical Packages @@ -4818,14 +4828,14 @@ from sequential bytes, tests fail. With the seed @samp{http://swissnet.ai.mit.edu/~jaffer/SLIB.html}, all of those tests pass. -@c @include random.txi +@include random.txi If inexact numbers are supported by the Scheme implementation, @file{randinex.scm} will be loaded as well. @file{randinex.scm} contains procedures for generating inexact distributions. -@c @include randinex.txi +@include randinex.txi @node Fast Fourier Transform, Cyclic Checksum, Random Numbers, Mathematical Packages @@ -4868,7 +4878,6 @@ Discrete Fourier Transform of @var{array}. @defun make-port-crc @defunx make-port-crc degree -@defunx make-port-crc degree generator Returns an expression for a procedure of one argument, a port. This procedure reads characters from the port until the end of file and returns the integer checksum of the bytes read. @@ -4877,6 +4886,14 @@ The integer @var{degree}, if given, specifies the degree of the polynomial being computed -- which is also the number of bits computed in the checksums. The default value is 32. +@defunx make-port-crc generator + +The integer @var{generator} specifies the polynomial being computed. +The power of 2 generating each 1 bit is the exponent of a term of the +polynomial. The value of @var{generator} must be larger than 127. + +@defunx make-port-crc degree generator + The integer @var{generator} specifies the polynomial being computed. The power of 2 generating each 1 bit is the exponent of a term of the polynomial. The bit at position @var{degree} is implicit and should not @@ -4907,7 +4924,7 @@ checksum from the polynomial: (define (file-check-sum file) (call-with-input-file file crc32)) (file-check-sum (in-vicinity (library-vicinity) "ratize.scm")) -@result{} 3553047446 +@result{} 157103930 @end example @node Plotting, Root Finding, Cyclic Checksum, Mathematical Packages @@ -4918,9 +4935,8 @@ checksum from the polynomial: The plotting procedure is made available through the use of the @code{charplot} package. @code{charplot} is loaded by inserting -@code{(require 'charplot)} before the code that uses this +@code{(require 'charplot)} before the code that uses this procedure. @ftindex charplot -procedure.@refill @defvar charplot:height The number of rows to make the plot vertically. @@ -4933,7 +4949,7 @@ The number of columns to make the plot horizontally. @deffn Procedure plot! coords x-label y-label @var{coords} is a list of pairs of x and y coordinates. @var{x-label} and @var{y-label} are strings with which to label the x and y -axes.@refill +axes. Example: @example @@ -4955,29 +4971,36 @@ Example: | | 1|- **** | | ** ** | - 750.0e-3|- * * | + 0.75|- * * | | * * | - 500.0e-3|- * * | + 0.5|- * * | | * | - 250.0e-3|- * | + 0.25|- * | | * * | 0|-------------------*--------------------------| | * | - -250.0e-3|- * * | + -0.25|- * * | | * * | - -500.0e-3|- * | + -0.5|- * | | * * | - -750.0e-3|- * * | + -0.75|- * * | | ** ** | -1|- **** | |____________:_____._____:_____._____:_________| - x 2 4 + x 2 4 6 @end group @end example @end deffn +@deffn Procedure plot-function! func x1 x2 +@deffnx Procedure plot-function! func x1 x2 npts +Plots the function of one argument @var{func} over the range @var{x1} to +@var{x2}. If the optional integer argument @var{npts} is supplied, it +specifies the number of points to evaluate @var{func} at. +@end deffn + -@node Root Finding, Commutative Rings, Plotting, Mathematical Packages +@node Root Finding, Minimizing, Plotting, Mathematical Packages @section Root Finding @code{(require 'root)} @@ -5065,7 +5088,7 @@ points @var{x0} and @var{x1}, returns a real @var{x} for which If @var{x0} and @var{x1} are chosen such that they bracket a root, that is @example -(or (< (f x0) 0 (f x1)) +(or (< (f x0) 0 (f x1)) (< (f x1) 0 (f x0))) @end example then the root returned will be between @var{x0} and @var{x1}, and @@ -5087,7 +5110,16 @@ iterations performed so far. @var{prec} should return non-false if the iteration should be stopped. @end defun -@node Commutative Rings, Determinant, Root Finding, Mathematical Packages +@node Minimizing, Commutative Rings, Root Finding, Mathematical Packages +@section Minimizing + +@code{(require 'minimize)} +@ftindex minimize +@cindex minimize + +@include minimize.txi + +@node Commutative Rings, Determinant, Minimizing, Mathematical Packages @section Commutative Rings Scheme provides a consistent and capable set of numeric functions. @@ -5106,6 +5138,7 @@ that any non-numeric arguments they do not reduce appear in the expression output. In order to see what working with this package is like, self-set all the single letter identifiers (to their corresponding symbols). +@cindex self-set @example (define a 'a) @@ -5114,16 +5147,17 @@ symbols). @end example Or just @code{(require 'self-set)}. Now try some sample expressions: +@ftindex self-set @example -(+ (+ a b) (- a b)) @result{} (* a 2) -(* (+ a b) (+ a b)) @result{} (^ (+ a b) 2) -(* (+ a b) (- a b)) @result{} (* (+ a b) (- a b)) -(* (- a b) (- a b)) @result{} (^ (- a b) 2) -(* (- a b) (+ a b)) @result{} (* (+ a b) (- a b)) -(/ (+ a b) (+ c d)) @result{} (/ (+ a b) (+ c d)) -(^ (+ a b) 3) @result{} (^ (+ a b) 3) -(^ (+ a 2) 3) @result{} (^ (+ 2 a) 3) +(+ (+ a b) (- a b)) @result{} (* a 2) +(* (+ a b) (+ a b)) @result{} (^ (+ a b) 2) +(* (+ a b) (- a b)) @result{} (* (+ a b) (- a b)) +(* (- a b) (- a b)) @result{} (^ (- a b) 2) +(* (- a b) (+ a b)) @result{} (* (+ a b) (- a b)) +(/ (+ a b) (+ c d)) @result{} (/ (+ a b) (+ c d)) +(^ (+ a b) 3) @result{} (^ (+ a b) 3) +(^ (+ a 2) 3) @result{} (^ (+ 2 a) 3) @end example Associative rules have been applied and repeated addition and @@ -5134,16 +5168,16 @@ form: @example (set! *ruleset* (combined-rulesets distribute* distribute/)) -(* (+ a b) (+ a b)) @result{} (+ (* 2 a b) (^ a 2) (^ b 2)) -(* (+ a b) (- a b)) @result{} (- (^ a 2) (^ b 2)) -(* (- a b) (- a b)) @result{} (- (+ (^ a 2) (^ b 2)) (* 2 a b)) -(* (- a b) (+ a b)) @result{} (- (^ a 2) (^ b 2)) -(/ (+ a b) (+ c d)) @result{} (+ (/ a (+ c d)) (/ b (+ c d))) -(/ (+ a b) (- c d)) @result{} (+ (/ a (- c d)) (/ b (- c d))) -(/ (- a b) (- c d)) @result{} (- (/ a (- c d)) (/ b (- c d))) -(/ (- a b) (+ c d)) @result{} (- (/ a (+ c d)) (/ b (+ c d))) -(^ (+ a b) 3) @result{} (+ (* 3 a (^ b 2)) (* 3 b (^ a 2)) (^ a 3) (^ b 3)) -(^ (+ a 2) 3) @result{} (+ 8 (* a 12) (* (^ a 2) 6) (^ a 3)) +(* (+ a b) (+ a b)) @result{} (+ (* 2 a b) (^ a 2) (^ b 2)) +(* (+ a b) (- a b)) @result{} (- (^ a 2) (^ b 2)) +(* (- a b) (- a b)) @result{} (- (+ (^ a 2) (^ b 2)) (* 2 a b)) +(* (- a b) (+ a b)) @result{} (- (^ a 2) (^ b 2)) +(/ (+ a b) (+ c d)) @result{} (+ (/ a (+ c d)) (/ b (+ c d))) +(/ (+ a b) (- c d)) @result{} (+ (/ a (- c d)) (/ b (- c d))) +(/ (- a b) (- c d)) @result{} (- (/ a (- c d)) (/ b (- c d))) +(/ (- a b) (+ c d)) @result{} (- (/ a (+ c d)) (/ b (+ c d))) +(^ (+ a b) 3) @result{} (+ (* 3 a (^ b 2)) (* 3 b (^ a 2)) (^ a 3) (^ b 3)) +(^ (+ a 2) 3) @result{} (+ 8 (* a 12) (* (^ a 2) 6) (^ a 3)) @end example Use of this package is not restricted to simple arithmetic expressions: @@ -5394,12 +5428,16 @@ Now we are ready to compute! @node Determinant, , Commutative Rings, Mathematical Packages @section Determinant +@defun determinant square-matrix +Returns the determinant of @var{square-matrix}. + @example (require 'determinant) (determinant '((1 2) (3 4))) @result{} -2 (determinant '((1 2 3) (4 5 6) (7 8 9))) @result{} 0 (determinant '((1 2 3 4) (5 6 7 8) (9 10 11 12))) @result{} 0 @end example +@end defun @node Database Packages, Other Packages, Mathematical Packages, Top @@ -5576,14 +5614,14 @@ In the following functions, the @var{key} argument can always be assumed to be the value returned by a call to a @emph{keyify} routine. @noindent -@cindex match-key +@cindex match-keys @cindex match @cindex wild-card -In contrast, a @var{match-key} argument is a list of length equal to the -number of primary keys. The @var{match-key} restricts the actions of -the table command to those records whose primary keys all satisfy the -corresponding element of the @var{match-key} list. -The elements and their actions are: +In contrast, a @var{match-keys} argument is a list of length equal to +the number of primary keys. The @var{match-keys} restrict the actions +of the table command to those records whose primary keys all satisfy the +corresponding element of the @var{match-keys} list. The elements and +their actions are: @quotation @table @asis @@ -5598,27 +5636,31 @@ Any other value matches only those keys @code{equal?} to it. @end table @end quotation -@defun for-each-key handle procedure match-key +@noindent +The @var{key-dimension} and @var{column-types} arguments are needed to +decode the combined-keys for matching with @var{match-keys}. + +@defun for-each-key handle procedure key-dimension column-types match-keys Calls @var{procedure} once with each @var{key} in the table opened in -@var{handle} which satisfies @var{match-key} in an unspecified order. +@var{handle} which satisfy @var{match-keys} in an unspecified order. An unspecified value is returned. @end defun -@defun map-key handle procedure match-key +@defun map-key handle procedure key-dimension column-types match-keys Returns a list of the values returned by calling @var{procedure} once -with each @var{key} in the table opened in @var{handle} which satisfies -@var{match-key} in an unspecified order. +with each @var{key} in the table opened in @var{handle} which satisfy +@var{match-keys} in an unspecified order. @end defun -@defun ordered-for-each-key handle procedure match-key +@defun ordered-for-each-key handle procedure key-dimension column-types match-keys Calls @var{procedure} once with each @var{key} in the table opened in -@var{handle} which satisfies @var{match-key} in the natural order for +@var{handle} which satisfy @var{match-keys} in the natural order for the types of the primary key fields of that table. An unspecified value is returned. @end defun -@defun delete* handle match-key -Removes all rows which satisfy @var{match-key} from the table opened in +@defun delete* handle key-dimension column-types match-keys +Removes all rows which satisfy @var{match-keys} from the table opened in @var{handle}. An unspecified value is returned. @end defun @@ -5889,6 +5931,12 @@ completed successfully, @code{#t} is returned. Otherwise, @code{#f} is returned. @end defun +@defun sync-database +Causes any pending updates to the database file to be written out. If +the operations completed successfully, @code{#t} is returned. +Otherwise, @code{#f} is returned. +@end defun + @defun table-exists? table-name Returns @code{#t} if @var{table-name} exists in the system catalog, otherwise returns @code{#f}. @@ -6531,7 +6579,7 @@ arguments from a @code{getopt} style argument list (@pxref{Getopt}). ((make-command-server rdb command-table) command (lambda (comname comval options positions - arities types defaulters dirs aliases) + arities types defaulters dirs aliases) (apply comval (getopt->arglist argc argv options positions arities types defaulters dirs aliases))))) @@ -6546,38 +6594,38 @@ arguments from a @code{getopt} style argument list (@pxref{Getopt}). (dbutil:serve-command-line my-rdb 'my-commands 'foo (length opts) opts))) -(cmd) @result{} ("str" () (symb) () #f) -(cmd "-f") @result{} ("str" () (symb) () #t) -(cmd "--flag") @result{} ("str" () (symb) () #t) -(cmd "-o177") @result{} ("str" () (symb) (177) #f) -(cmd "-o" "177") @result{} ("str" () (symb) (177) #f) -(cmd "--optional" "621") @result{} ("str" () (symb) (621) #f) -(cmd "--optional=621") @result{} ("str" () (symb) (621) #f) -(cmd "-s" "speciality") @result{} ("speciality" () (symb) () #f) -(cmd "-sspeciality") @result{} ("speciality" () (symb) () #f) -(cmd "--single" "serendipity") @result{} ("serendipity" () (symb) () #f) -(cmd "--single=serendipity") @result{} ("serendipity" () (symb) () #f) -(cmd "-n" "gravity" "piety") @result{} ("str" () (piety gravity) () #f) -(cmd "-ngravity" "piety") @result{} ("str" () (piety gravity) () #f) -(cmd "--nary" "chastity") @result{} ("str" () (chastity) () #f) -(cmd "--nary=chastity" "") @result{} ("str" () ( chastity) () #f) -(cmd "-N" "calamity") @result{} ("str" () (calamity) () #f) -(cmd "-Ncalamity") @result{} ("str" () (calamity) () #f) -(cmd "--nary1" "surety") @result{} ("str" () (surety) () #f) -(cmd "--nary1=surety") @result{} ("str" () (surety) () #f) -(cmd "-N" "levity" "fealty") @result{} ("str" () (fealty levity) () #f) -(cmd "-Nlevity" "fealty") @result{} ("str" () (fealty levity) () #f) -(cmd "--nary1" "surety" "brevity") @result{} ("str" () (brevity surety) () #f) -(cmd "--nary1=surety" "brevity") @result{} ("str" () (brevity surety) () #f) +(cmd) @result{} ("str" () (symb) () #f) +(cmd "-f") @result{} ("str" () (symb) () #t) +(cmd "--flag") @result{} ("str" () (symb) () #t) +(cmd "-o177") @result{} ("str" () (symb) (177) #f) +(cmd "-o" "177") @result{} ("str" () (symb) (177) #f) +(cmd "--optional" "621") @result{} ("str" () (symb) (621) #f) +(cmd "--optional=621") @result{} ("str" () (symb) (621) #f) +(cmd "-s" "speciality") @result{} ("speciality" () (symb) () #f) +(cmd "-sspeciality") @result{} ("speciality" () (symb) () #f) +(cmd "--single" "serendipity") @result{} ("serendipity" () (symb) () #f) +(cmd "--single=serendipity") @result{} ("serendipity" () (symb) () #f) +(cmd "-n" "gravity" "piety") @result{} ("str" () (piety gravity) () #f) +(cmd "-ngravity" "piety") @result{} ("str" () (piety gravity) () #f) +(cmd "--nary" "chastity") @result{} ("str" () (chastity) () #f) +(cmd "--nary=chastity" "") @result{} ("str" () ( chastity) () #f) +(cmd "-N" "calamity") @result{} ("str" () (calamity) () #f) +(cmd "-Ncalamity") @result{} ("str" () (calamity) () #f) +(cmd "--nary1" "surety") @result{} ("str" () (surety) () #f) +(cmd "--nary1=surety") @result{} ("str" () (surety) () #f) +(cmd "-N" "levity" "fealty") @result{} ("str" () (fealty levity) () #f) +(cmd "-Nlevity" "fealty") @result{} ("str" () (fealty levity) () #f) +(cmd "--nary1" "surety" "brevity") @result{} ("str" () (brevity surety) () #f) +(cmd "--nary1=surety" "brevity") @result{} ("str" () (brevity surety) () #f) (cmd "-?") -@print{} +@print{} Usage: cmd [OPTION ARGUMENT ...] ... - -f, --flag - -o, --optional[=]<number> + -f, --flag + -o, --optional[=]<number> -n, --nary[=]<symbols> ... -N, --nary1[=]<symbols> ... - -s, --single[=]<string> + -s, --single[=]<string> ERROR: getopt->parameter-list "unrecognized option" "-?" @end example @@ -6741,6 +6789,19 @@ database is then closed and reopened. Welcome @end example +@subsubheading Listing Tables + +@deffn Procedure list-table-definition rdb table-name +If symbol @var{table-name} exists in the open relational-database +@var{rdb}, then returns a list of the table-name, its primary key names +and domains, its other key names and domains, and the table's records +(as lists). Otherwise, returns #f. + +The list returned by @code{list-table-definition}, when passed as an +argument to @code{define-tables}, will recreate the table. +@end deffn + + @node Database Reports, Database Browser, Database Utilities, Relational Database @subsection Database Reports @@ -7376,6 +7437,7 @@ operation is equivalent to @menu * Data Structures:: Various data structures. +* Sorting and Searching:: * Procedures:: Miscellaneous utility procedures. * Standards Support:: Support for Scheme Standards. * Session Support:: REPL and Debugging. @@ -7383,7 +7445,7 @@ operation is equivalent to @end menu -@node Data Structures, Procedures, Other Packages, Other Packages +@node Data Structures, Sorting and Searching, Other Packages, Other Packages @section Data Structures @@ -7393,6 +7455,7 @@ operation is equivalent to * Array Mapping:: 'array-for-each * Association Lists:: 'alist * Byte:: 'byte +* Portable Image Files:: 'pnm * Collections:: 'collect * Dynamic Data Type:: 'dynamic * Hash Tables:: 'hash-table @@ -7401,7 +7464,6 @@ operation is equivalent to * Priority Queues:: 'priority-queue * Queues:: 'queue * Records:: 'record -* Structures:: 'struct, 'structure @end menu @@ -7410,100 +7472,7 @@ operation is equivalent to @node Arrays, Array Mapping, Data Structures, Data Structures @subsection Arrays -@code{(require 'array)} -@ftindex array - -@defun array? obj -Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not. -@end defun - -@defun make-array initial-value bound1 bound2 @dots{} -Creates and returns an array that has as many dimensins as there are -@var{bound}s and fills it with @var{initial-value}.@refill -@end defun - -When constructing an array, @var{bound} is either an inclusive range of -indices expressed as a two element list, or an upper bound expressed as -a single integer. So@refill -@lisp -(make-array 'foo 3 3) @equiv{} (make-array 'foo '(0 2) '(0 2)) -@end lisp - -@defun make-shared-array array mapper bound1 bound2 @dots{} -@code{make-shared-array} can be used to create shared subarrays of other -arrays. The @var{mapper} is a function that translates coordinates in -the new array into coordinates in the old array. A @var{mapper} must be -linear, and its range must stay within the bounds of the old array, but -it can be otherwise arbitrary. A simple example:@refill -@lisp -(define fred (make-array #f 8 8)) -(define freds-diagonal - (make-shared-array fred (lambda (i) (list i i)) 8)) -(array-set! freds-diagonal 'foo 3) -(array-ref fred 3 3) - @result{} FOO -(define freds-center - (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) - 2 2)) -(array-ref freds-center 0 0) - @result{} FOO -@end lisp -@end defun - -@defun array-rank obj -Returns the number of dimensions of @var{obj}. If @var{obj} is not an -array, 0 is returned. -@end defun - -@defun array-shape array -@code{array-shape} returns a list of inclusive bounds. So: -@lisp -(array-shape (make-array 'foo 3 5)) - @result{} ((0 2) (0 4)) -@end lisp -@end defun - -@defun array-dimensions array -@code{array-dimensions} is similar to @code{array-shape} but replaces -elements with a 0 minimum with one greater than the maximum. So: -@lisp -(array-dimensions (make-array 'foo 3 5)) - @result{} (3 5) -@end lisp -@end defun - -@deffn Procedure array-in-bounds? array index1 index2 @dots{} -Returns @code{#t} if its arguments would be acceptable to -@code{array-ref}. -@end deffn - -@defun array-ref array index1 index2 @dots{} -Returns the element at the @code{(@var{index1}, @var{index2})} element -in @var{array}.@refill -@end defun - -@deffn Procedure array-set! array new-value index1 index2 @dots{} -@end deffn - -@defun array-1d-ref array index -@defunx array-2d-ref array index1 index2 -@defunx array-3d-ref array index1 index2 index3 -@end defun - -@deffn Procedure array-1d-set! array new-value index -@deffnx Procedure array-2d-set! array new-value index1 index2 -@deffnx Procedure array-3d-set! array new-value index1 index2 index3 -@end deffn - -The functions are just fast versions of @code{array-ref} and -@code{array-set!} that take a fixed number of arguments, and perform no -bounds checking.@refill - -If you comment out the bounds checking code, this is about as efficient -as you could ask for without help from the compiler. - -An exercise left to the reader: implement the rest of APL. - +@include array.txi @node Array Mapping, Association Lists, Arrays, Data Structures @@ -7570,7 +7539,7 @@ dimension. The order of copying is unspecified. Alist functions provide utilities for treating a list of key-value pairs as an associative database. These functions take an equality predicate, @var{pred}, as an argument. This predicate should be repeatable, -symmetric, and transitive.@refill +symmetric, and transitive. Alist functions can be used with a secondary index method such as hash tables for improved performance. @@ -7580,13 +7549,13 @@ Returns an @dfn{association function} (like @code{assq}, @code{assv}, or @code{assoc}) corresponding to @var{pred}. The returned function returns a key-value pair whose key is @code{pred}-equal to its first argument or @code{#f} if no key in the alist is @var{pred}-equal to the -first argument.@refill +first argument. @end defun @defun alist-inquirer pred Returns a procedure of 2 arguments, @var{alist} and @var{key}, which returns the value associated with @var{key} in @var{alist} or @code{#f} if -@var{key} does not appear in @var{alist}.@refill +@var{key} does not appear in @var{alist}. @end defun @defun alist-associator pred @@ -7625,7 +7594,7 @@ Applies @var{proc} to each pair of keys and values of @var{alist}. unspecified. @end defun -@node Byte, Collections, Association Lists, Data Structures +@node Byte, Portable Image Files, Association Lists, Data Structures @subsection Byte @code{(require 'byte)} @@ -7680,7 +7649,7 @@ returned by @code{current-output-port}. @end deffn -@deffn Function read-byte +@deffn Function read-byte @deffnx Function read-byte port Returns the next byte available from the input @var{port}, updating @@ -7714,8 +7683,66 @@ inverses so far as @code{equal?} is concerned. @end deffn +@node Portable Image Files, Collections, Byte, Data Structures +@subsection Portable Image Files + +@code{(require 'pnm)} + +@deffn Function pnm:type-dimensions path +The string @var{path} must name a @dfn{portable bitmap graphics} file. +@code{pnm:type-dimensions} returns a list of 4 items: +@enumerate +@item +A symbol describing the type of the file named by @var{path}. +@item +The image width in pixels. +@item +The image height in pixels. +@item +The maximum value of pixels assume in the file. +@end enumerate + +The current set of file-type symbols is: +@table @asis +@item pbm +@itemx pbm-raw +Black-and-White image; pixel values are 0 or 1. +@item pgm +@itemx pgm-raw +Gray (monochrome) image; pixel values are from 0 to @var{maxval} +specified in file header. +@item ppm +@itemx ppm-raw +RGB (full color) image; red, green, and blue interleaved pixel values +are from 0 to @var{maxval} +@end table + +@end deffn + +@deffn Function pnm:image-file->array path array + +Reads the @dfn{portable bitmap graphics} file named by @var{path} into +@var{array}. @var{array} must be the correct size and type for +@var{path}. @var{array} is returned. + +@deffnx Function pnm:image-file->array path + +@code{pnm:image-file->array} creates and returns an array with the +@dfn{portable bitmap graphics} file named by @var{path} read into it. -@node Collections, Dynamic Data Type, Byte, Data Structures +@end deffn + +@deffn Procedure pnm:array-write type array maxval path + +Writes the contents of @var{array} to a @var{type} image file named +@var{path}. The file will have pixel values between 0 and @var{maxval}, +which must be compatible with @var{type}. For @samp{pbm} files, +@var{maxval} must be @samp{1}. + +@end deffn + + +@node Collections, Dynamic Data Type, Portable Image Files, Data Structures @subsection Collections @c Much of the documentation in this section was written by Dave Love @@ -7729,7 +7756,7 @@ Routines for managing collections. Collections are aggregate data structures supporting iteration over their elements, similar to the Dylan(TM) language, but with a different interface. They have @dfn{elements} indexed by corresponding @dfn{keys}, although the keys -may be implicit (as with lists).@refill +may be implicit (as with lists). New types of collections may be defined as YASOS objects (@pxref{Yasos}). They must support the following operations: @@ -7756,15 +7783,15 @@ collection's keys in order. @end itemize They might support specialized @code{for-each-key} and -@code{for-each-elt} operations.@refill +@code{for-each-elt} operations. @defun collection? obj A predicate, true initially of lists, vectors and strings. New sorts of -collections must answer @code{#t} to @code{collection?}.@refill +collections must answer @code{#t} to @code{collection?}. @end defun -@deffn Procedure map-elts proc . collections -@deffnx Procedure do-elts proc . collections +@deffn Procedure map-elts proc collection1 @dots{} +@deffnx Procedure do-elts proc collection1 @dots{} @var{proc} is a procedure taking as many arguments as there are @var{collections} (at least one). The @var{collections} are iterated over in their natural order and @var{proc} is applied to the elements @@ -7773,7 +7800,7 @@ supplied corresponds to te order in which the @var{collections} appear. @code{do-elts} is used when only side-effects of @var{proc} are of interest and its return value is unspecified. @code{map-elts} returns a collection (actually a vector) of the results of the applications of -@var{proc}.@refill +@var{proc}. Example: @lisp @@ -7782,11 +7809,11 @@ Example: @end lisp @end deffn -@deffn Procedure map-keys proc . collections -@deffnx Procedure do-keys proc . collections +@deffn Procedure map-keys proc collection1 @dots{} +@deffnx Procedure do-keys proc collection1 @dots{} These are analogous to @code{map-elts} and @code{do-elts}, but each iteration is over the @var{collections}' @emph{keys} rather than their -elements.@refill +elements. Example: @lisp @@ -7801,13 +7828,13 @@ These are like @code{do-keys} and @code{do-elts} but only for a single collection; they are potentially more efficient. @end deffn -@defun reduce proc seed . collections +@defun reduce proc seed collection1 @dots{} A generalization of the list-based @code{comlist:reduce-init} (@pxref{Lists as sequences}) to collections which will shadow the list-based version if @code{(require 'collect)} follows @ftindex collect @code{(require 'common-list-functions)} (@pxref{Common List -Functions}).@refill +Functions}). @ftindex common-list-functions Examples: @@ -7819,9 +7846,9 @@ Examples: @end lisp @end defun -@defun any? pred . collections +@defun any? pred collection1 @dots{} A generalization of the list-based @code{some} (@pxref{Lists as -sequences}) to collections.@refill +sequences}) to collections. Example: @lisp @@ -7830,9 +7857,9 @@ Example: @end lisp @end defun -@defun every? pred . collections +@defun every? pred collection1 @dots{} A generalization of the list-based @code{every} (@pxref{Lists as -sequences}) to collections.@refill +sequences}) to collections. Example: @lisp @@ -7854,11 +7881,11 @@ Returns the number of elements in @var{collection}. @defun Setter list-ref See @ref{Setters} for a definition of @dfn{setter}. N.B. @code{(setter list-ref)} doesn't work properly for element 0 of a -list.@refill +list. @end defun Here is a sample collection: @code{simple-table} which is also a -@code{table}.@refill +@code{table}. @lisp (define-predicate TABLE?) (define-operation (LOOKUP table key failure-object)) @@ -7937,7 +7964,7 @@ Create and returns a new @dfn{dynamic} whose global value is @var{obj}. @defun dynamic? obj Returns true if and only if @var{obj} is a dynamic. No object satisfying @code{dynamic?} satisfies any of the other standard type -predicates.@refill +predicates. @end defun @defun dynamic-ref dyn @@ -7947,7 +7974,7 @@ environment. @deffn Procedure dynamic-set! dyn obj Change the value of the given dynamic to @var{obj} in the current -dynamic environment. The returned value is unspecified.@refill +dynamic environment. The returned value is unspecified. @end deffn @defun call-with-dynamic-binding dyn obj thunk @@ -7956,7 +7983,7 @@ environment in which the given dynamic has been bound to a new location whose initial contents are the value @var{obj}. This dynamic environment has precisely the same extent as the invocation of the thunk and is thus captured by continuations created within that invocation and -re-established by those continuations when they are invoked.@refill +re-established by those continuations when they are invoked. @end defun The @code{dynamic-bind} macro is not implemented. @@ -7975,7 +8002,7 @@ Returns a hash function (like @code{hashq}, @code{hashv}, or @code{hash}) corresponding to the equality predicate @var{pred}. @var{pred} should be @code{eq?}, @code{eqv?}, @code{equal?}, @code{=}, @code{char=?}, @code{char-ci=?}, @code{string=?}, or -@code{string-ci=?}.@refill +@code{string-ci=?}. @end defun A hash table is a vector of association lists. @@ -7988,33 +8015,33 @@ Hash table functions provide utilities for an associative database. These functions take an equality predicate, @var{pred}, as an argument. @var{pred} should be @code{eq?}, @code{eqv?}, @code{equal?}, @code{=}, @code{char=?}, @code{char-ci=?}, @code{string=?}, or -@code{string-ci=?}.@refill +@code{string-ci=?}. @defun predicate->hash-asso pred Returns a hash association function of 2 arguments, @var{key} and @var{hashtab}, corresponding to @var{pred}. The returned function returns a key-value pair whose key is @var{pred}-equal to its first argument or @code{#f} if no key in @var{hashtab} is @var{pred}-equal to -the first argument.@refill +the first argument. @end defun @defun hash-inquirer pred -Returns a procedure of 3 arguments, @code{hashtab} and @code{key}, which -returns the value associated with @code{key} in @code{hashtab} or -@code{#f} if key does not appear in @code{hashtab}.@refill +Returns a procedure of 2 arguments, @var{hashtab} and @var{key}, which +returns the value associated with @var{key} in @var{hashtab} or +@code{#f} if @var{key} does not appear in @var{hashtab}. @end defun @defun hash-associator pred Returns a procedure of 3 arguments, @var{hashtab}, @var{key}, and @var{value}, which modifies @var{hashtab} so that @var{key} and @var{value} associated. Any previous value associated with @var{key} -will be lost.@refill +will be lost. @end defun @defun hash-remover pred Returns a procedure of 2 arguments, @var{hashtab} and @var{key}, which modifies @var{hashtab} so that the association whose key is @var{key} is -removed.@refill +removed. @end defun @defun hash-map proc hash-table @@ -8048,21 +8075,21 @@ Hash tables use these functions. Returns an exact non-negative integer less than @var{k}. For each non-negative integer less than @var{k} there are arguments @var{obj} for which the hashing functions applied to @var{obj} and @var{k} returns -that integer.@refill +that integer. For @code{hashq}, @code{(eq? obj1 obj2)} implies @code{(= (hashq obj1 k) -(hashq obj2))}.@refill +(hashq obj2))}. For @code{hashv}, @code{(eqv? obj1 obj2)} implies @code{(= (hashv obj1 k) -(hashv obj2))}.@refill +(hashv obj2))}. For @code{hash}, @code{(equal? obj1 obj2)} implies @code{(= (hash obj1 k) -(hash obj2))}.@refill +(hash obj2))}. @code{hash}, @code{hashv}, and @code{hashq} return in time bounded by a constant. Notice that items having the same @code{hash} implies the items have the same @code{hashv} implies the items have the same -@code{hashq}.@refill +@code{hashq}. @end defun @@ -8134,7 +8161,7 @@ English pronunciation tend to map to the same key. Soundex was a classic algorithm used for manual filing of personal records before the advent of computers. It performs adequately for -English names but has trouble with other nationalities. +English names but has trouble with other languages. See Knuth, Vol. 3 @cite{Sorting and searching}, pp 391--2 @@ -8187,18 +8214,18 @@ operations. @end defun @defun heap-length heap -Returns the number of elements in @var{heap}.@refill +Returns the number of elements in @var{heap}. @end defun @deffn Procedure heap-insert! heap item Inserts @var{item} into @var{heap}. @var{item} can be inserted multiple -times. The value returned is unspecified.@refill +times. The value returned is unspecified. @end deffn @defun heap-extract-max! heap Returns the item which is larger than all others according to the @var{pred<?} argument to @code{make-heap}. If there are no items in -@var{heap}, an error is signaled.@refill +@var{heap}, an error is signaled. @end defun The algorithm for priority queues was taken from @cite{Introduction to @@ -8214,7 +8241,7 @@ Algorithms} by T. Cormen, C. Leiserson, R. Rivest. 1989 MIT Press. A @dfn{queue} is a list where elements can be added to both the front and rear, and removed from the front (i.e., they are what are often -called @dfn{dequeues}). A queue may also be used like a stack.@refill +called @dfn{dequeues}). A queue may also be used like a stack. @defun make-queue Returns a new, empty queue. @@ -8237,7 +8264,7 @@ Adds @var{datum} to the rear of queue @var{q}. @end deffn All of the following functions raise an error if the queue @var{q} is -empty.@refill +empty. @defun queue-front q Returns the datum at the front of the queue @var{q}. @@ -8251,14 +8278,14 @@ Returns the datum at the rear of the queue @var{q}. @deffnx Procedure dequeue! q Both of these procedures remove and return the datum at the front of the queue. @code{queue-pop!} is used to suggest that the queue is being -used like a stack.@refill +used like a stack. @end deffn -@node Records, Structures, Queues, Data Structures +@node Records, , Queues, Data Structures @subsection Records @code{(require 'record)} @@ -8274,7 +8301,7 @@ string, but is only used for debugging purposes (such as the printed representation of a record of the new type). The @var{field-names} argument is a list of symbols naming the @dfn{fields} of a record of the new type. It is an error if the list contains any duplicates. It is -unspecified how record-type descriptors are represented.@refill +unspecified how record-type descriptors are represented. @end defun @c @defun make-record-sub-type type-name field-names rtd @@ -8283,11 +8310,11 @@ unspecified how record-type descriptors are represented.@refill @c string. The @var{field-names} argument is a list of symbols naming the @c additional @dfn{fields} to be appended to @var{field-names} of @c @var{rtd}. It is an error if the combinded list contains any -@c duplicates.@refill +@c duplicates. @c @c Record-modifiers and record-accessors for @var{rtd} work for the new @c record-sub-type as well. But record-modifiers and record-accessors for -@c the new record-sub-type will not neccessarily work for @var{rtd}.@refill +@c the new record-sub-type will not neccessarily work for @var{rtd}. @c @end defun @defun record-constructor rtd [field-names] @@ -8300,14 +8327,14 @@ fields not named in that list are unspecified. The @var{field-names} argument defaults to the list of field names in the call to @code{make-record-type} that created the type represented by @var{rtd}; if the @var{field-names} argument is provided, it is an error if it -contains any duplicates or any symbols not in the default list.@refill +contains any duplicates or any symbols not in the default list. @end defun @defun record-predicate rtd Returns a procedure for testing membership in the type represented by @var{rtd}. The returned procedure accepts exactly one argument and returns a true value if the argument is a member of the indicated record -type; it returns a false value otherwise.@refill +type; it returns a false value otherwise. @end defun @c @defun record-sub-predicate rtd @@ -8315,7 +8342,7 @@ type; it returns a false value otherwise.@refill @c @var{rtd} or its parents. The returned procedure accepts exactly one @c argument and returns a true value if the argument is a member of the @c indicated record type or its parents; it returns a false value -@c otherwise.@refill +@c otherwise. @c @end defun @defun record-accessor rtd field-name @@ -8325,7 +8352,7 @@ accepts exactly one argument which must be a record of the appropriate type; it returns the current value of the field named by the symbol @var{field-name} in that record. The symbol @var{field-name} must be a member of the list of field-names in the call to @code{make-record-type} -that created the type represented by @var{rtd}.@refill +that created the type represented by @var{rtd}. @end defun @@ -8338,7 +8365,7 @@ the symbol @var{field-name} in that record to contain the given value. The returned value of the modifier procedure is unspecified. The symbol @var{field-name} must be a member of the list of field-names in the call to @code{make-record-type} that created the type represented by -@var{rtd}.@refill +@var{rtd}. @end defun In May of 1996, as a product of discussion on the @code{rrrs-authors} @@ -8360,7 +8387,7 @@ Returns a true value if @var{obj} is a record of any type and a false value otherwise. Note that @code{record?} may be true of any Scheme value; of course, if it returns true for some particular value, then @code{record-type-descriptor} is applicable to that value and returns an -appropriate descriptor.@refill +appropriate descriptor. @end defun @defun record-type-descriptor record @@ -8370,88 +8397,28 @@ record. That is, for example, if the returned descriptor were passed to value when passed the given record. Note that it is not necessarily the case that the returned descriptor is the one that was passed to @code{record-constructor} in the call that created the constructor -procedure that created the given record.@refill +procedure that created the given record. @end defun @defun record-type-name rtd Returns the type-name associated with the type represented by rtd. The returned value is @code{eqv?} to the @var{type-name} argument given in the call to @code{make-record-type} that created the type represented by -@var{rtd}.@refill +@var{rtd}. @end defun @defun record-type-field-names rtd Returns a list of the symbols naming the fields in members of the type represented by @var{rtd}. The returned value is @code{equal?} to the field-names argument given in the call to @code{make-record-type} that -created the type represented by @var{rtd}.@refill +created the type represented by @var{rtd}. @end defun @end ignore -@node Structures, , Records, Data Structures -@subsection Structures - -@code{(require 'struct)} (uses defmacros) -@ftindex struct - -@code{defmacro}s which implement @dfn{records} from the book -@cite{Essentials of Programming Languages} by Daniel P. Friedman, M. -Wand and C.T. Haynes. Copyright 1992 Jeff Alexander, Shinnder Lee, and -Lewis Patterson@refill - -Matthew McDonald <mafm@@cs.uwa.edu.au> added field setters. - -@defmac define-record tag (var1 var2 @dots{}) -Defines several functions pertaining to record-name @var{tag}: - -@defun make-@var{tag} var1 var2 @dots{} -@end defun -@defun @var{tag}? obj -@end defun -@defun @var{tag}->var1 obj -@end defun -@defun @var{tag}->var2 obj -@end defun -@dots{} -@defun set-@var{tag}-var1! obj val -@end defun -@defun set-@var{tag}-var2! obj val -@end defun -@dots{} - -Here is an example of its use. - -@example -(define-record term (operator left right)) -@result{} #<unspecified> -(define foo (make-term 'plus 1 2)) -@result{} foo -(term->left foo) -@result{} 1 -(set-term-left! foo 2345) -@result{} #<unspecified> -(term->left foo) -@result{} 2345 -@end example -@end defmac -@defmac variant-case exp (tag (var1 var2 @dots{}) body) @dots{} -executes the following for the matching clause: - -@example -((lambda (@var{var1} @var{var} @dots{}) @var{body}) - (@var{tag->var1} @var{exp}) - (@var{tag->var2} @var{exp}) @dots{}) -@end example -@end defmac - - -@node Procedures, Standards Support, Data Structures, Other Packages -@section Procedures - -Anything that doesn't fall neatly into any of the other categories winds -up here. +@node Sorting and Searching, Procedures, Data Structures, Other Packages +@section Sorting and Searching @menu * Common List Functions:: 'common-list-functions @@ -8459,15 +8426,13 @@ up here. * Chapter Ordering:: 'chapter-order * Sorting:: 'sort * Topological Sort:: Keep your socks on. -* String-Case:: 'string-case -* String Ports:: 'string-port * String Search:: Also Search from a Port. -* Line I/O:: 'line-i/o -* Multi-Processing:: 'process +* Sequence Comparison:: 'diff and longest-common-subsequence @end menu -@node Common List Functions, Tree Operations, Procedures, Procedures + +@node Common List Functions, Tree Operations, Sorting and Searching, Sorting and Searching @subsection Common List Functions @code{(require 'common-list-functions)} @@ -8488,10 +8453,11 @@ optional arguments in some cases. @node List construction, Lists as sets, Common List Functions, Common List Functions @subsubsection List construction -@defun make-list k . init +@defun make-list k +@defunx make-list k init @code{make-list} creates and returns a list of @var{k} elements. If @var{init} is included, all elements in the list are initialized to -@var{init}.@refill +@var{init}. Example: @lisp @@ -8503,7 +8469,7 @@ Example: @end defun -@defun list* x . y +@defun list* obj1 obj2 @dots{} Works like @code{list} except that the cdr of the last pair is the last argument unless there is only one argument, when the result is just that argument. Sometimes called @code{cons*}. E.g.:@refill @@ -8524,7 +8490,7 @@ argument. Sometimes called @code{cons*}. E.g.:@refill it. Only the top level of the list is copied, i.e., pairs forming elements of the copied list remain @code{eq?} to the corresponding elements of the original; the copy is, however, not @code{eq?} to the -original, but is @code{equal?} to it.@refill +original, but is @code{equal?} to it. Example: @lisp @@ -8559,7 +8525,7 @@ lists as sets. @defun adjoin e l @code{adjoin} returns the adjoint of the element @var{e} and the list @var{l}. That is, if @var{e} is in @var{l}, @code{adjoin} returns -@var{l}, otherwise, it returns @code{(cons @var{e} @var{l})}.@refill +@var{l}, otherwise, it returns @code{(cons @var{e} @var{l})}. Example: @lisp @@ -8573,20 +8539,20 @@ Example: @defun union l1 l2 @code{union} returns the combination of @var{l1} and @var{l2}. Duplicates between @var{l1} and @var{l2} are culled. Duplicates within -@var{l1} or within @var{l2} may or may not be removed.@refill +@var{l1} or within @var{l2} may or may not be removed. Example: @lisp (union '(1 2 3 4) '(5 6 7 8)) - @result{} (4 3 2 1 5 6 7 8) + @result{} (8 7 6 5 1 2 3 4) (union '(1 2 3 4) '(3 4 5 6)) - @result{} (2 1 3 4 5 6) + @result{} (6 5 1 2 3 4) @end lisp @end defun @defun intersection l1 l2 @code{intersection} returns all elements that are in both @var{l1} and -@var{l2}.@refill +@var{l2}. Example: @lisp @@ -8598,8 +8564,8 @@ Example: @end defun @defun set-difference l1 l2 -@code{set-difference} returns the union of all elements that are in -@var{l1} but not in @var{l2}.@refill +@code{set-difference} returns all elements that are in @var{l1} but not +in @var{l2}. Example: @lisp @@ -8613,7 +8579,7 @@ Example: @defun member-if pred lst @code{member-if} returns @var{lst} if @code{(@var{pred} @var{element})} is @code{#t} for any @var{element} in @var{lst}. Returns @code{#f} if -@var{pred} does not apply to any @var{element} in @var{lst}.@refill +@var{pred} does not apply to any @var{element} in @var{lst}. Example: @lisp @@ -8624,13 +8590,13 @@ Example: @end lisp @end defun -@defun some pred lst . more-lsts +@defun some pred lst1 lst2 @dots{} @var{pred} is a boolean function of as many arguments as there are list arguments to @code{some} i.e., @var{lst} plus any optional arguments. @var{pred} is applied to successive elements of the list arguments in order. @code{some} returns @code{#t} as soon as one of these applications returns @code{#t}, and is @code{#f} if none returns -@code{#t}. All the lists should have the same length.@refill +@code{#t}. All the lists should have the same length. Example: @@ -8646,10 +8612,10 @@ Example: @end lisp @end defun -@defun every pred lst . more-lsts +@defun every pred lst1 lst2 @dots{} @code{every} is analogous to @code{some} except it returns @code{#t} if every application of @var{pred} is @code{#t} and @code{#f} -otherwise.@refill +otherwise. Example: @lisp @@ -8664,16 +8630,16 @@ Example: @end lisp @end defun -@defun notany pred . lst +@defun notany pred lst1 @dots{} @code{notany} is analogous to @code{some} but returns @code{#t} if no application of @var{pred} returns @code{#t} or @code{#f} as soon as any -one does.@refill +one does. @end defun -@defun notevery pred . lst +@defun notevery pred lst1 @dots{} @code{notevery} is analogous to @code{some} but returns @code{#t} as soon as an application of @var{pred} returns @code{#f}, and @code{#f} -otherwise.@refill +otherwise. Example: @lisp @@ -8685,11 +8651,33 @@ Example: @end lisp @end defun + +@defun list-of?? predicate +Returns a predicate which returns true if its argument is a list every +element of which satisfies @var{predicate}. + +@defunx list-of?? predicate low-bound high-bound +@var{low-bound} and @var{high-bound} are non-negative integers. +@code{list-of??} returns a predicate which returns true if its argument +is a list of length between @var{low-bound} and @var{high-bound} +(inclusive); every element of which satisfies @var{predicate}. + +@defunx list-of?? predicate bound +@var{bound} is an integer. If @var{bound} is negative, @code{list-of??} +returns a predicate which returns true if its argument is a list of +length greater than @code{(- @var{bound})}; every element of which +satisfies @var{predicate}. Otherwise, @code{list-of??} returns a +predicate which returns true if its argument is a list of length less +than or equal to @var{bound}; every element of which satisfies +@var{predicate}. +@end defun + + @defun find-if pred lst @code{find-if} searches for the first @var{element} in @var{lst} such that @code{(@var{pred} @var{element})} returns @code{#t}. If it finds any such @var{element} in @var{lst}, @var{element} is returned. -Otherwise, @code{#f} is returned.@refill +Otherwise, @code{#f} is returned. Example: @lisp @@ -8708,7 +8696,7 @@ Example: @code{remove} removes all occurrences of @var{elt} from @var{lst} using @code{eqv?} to test for equality and returns everything that's left. N.B.: other implementations (Chez, Scheme->C and T, at least) use -@code{equal?} as the equality test.@refill +@code{equal?} as the equality test. Example: @lisp @@ -8723,7 +8711,7 @@ Example: @defun remove-if pred lst @code{remove-if} removes all @var{element}s from @var{lst} where @code{(@var{pred} @var{element})} is @code{#t} and returns everything -that's left.@refill +that's left. Example: @lisp @@ -8738,7 +8726,7 @@ Example: @defun remove-if-not pred lst @code{remove-if-not} removes all @var{element}s from @var{lst} for which @code{(@var{pred} @var{element})} is @code{#f} and returns everything that's -left.@refill +left. Example: @lisp @@ -8773,10 +8761,10 @@ Elements are considered duplicate if they are @code{equal?}. Example: @lisp (remove-duplicates '(1 2 3 4)) - @result{} (4 3 2 1) + @result{} (1 2 3 4) (remove-duplicates '(2 4 3 4)) - @result{} (3 4 2) + @result{} (2 4 3) @end lisp @end defun @@ -8786,7 +8774,7 @@ Example: @defun position obj lst @code{position} returns the 0-based position of @var{obj} in @var{lst}, -or @code{#f} if @var{obj} does not occur in @var{lst}.@refill +or @code{#f} if @var{obj} does not occur in @var{lst}. Example: @lisp @@ -8806,7 +8794,7 @@ operation (the combination is left-associative). For example, using apply a function which accepts only two arguments to more than 2 objects. Functional programmers usually refer to this as @dfn{foldl}. @code{collect:reduce} (@pxref{Collections}) provides a version of -@code{collect} generalized to collections.@refill +@code{collect} generalized to collections. Example: @lisp @@ -8831,10 +8819,10 @@ Example: What follows is a rather non-standard implementation of @code{reverse} in terms of @code{reduce} and a combinator elsewhere called -@dfn{C}.@refill +@dfn{C}. @lisp -;;; Contributed by Jussi Piitulainen (jpiitula@@ling.helsinki.fi) +;;; Contributed by Jussi Piitulainen (jpiitula @@ ling.helsinki.fi) (define commute (lambda (f) @@ -8853,7 +8841,7 @@ inserts @var{init} at the start of the list. @code{reduce-init} is preferred if you want to handle the null list, the one-element, and lists with two or more elements consistently. It is common to use the operator's idempotent as the initializer. Functional programmers -usually call this @dfn{foldl}.@refill +usually call this @dfn{foldl}. Example: @lisp @@ -8919,7 +8907,7 @@ Example: @defun butlast lst n @code{butlast} returns all but the last @var{n} elements of -@var{lst}.@refill +@var{lst}. Example: @lisp @@ -8956,14 +8944,14 @@ Example: @defun butnthcdr n lst @code{butnthcdr} returns all but the nthcdr @var{n} elements of -@var{lst}.@refill +@var{lst}. Example: @lisp (butnthcdr 3 '(a b c d)) @result{} (a b c) (butnthcdr 4 '(a b c d)) - @result{} () + @result{} (a b c d) @end lisp @end defun @@ -8988,7 +8976,7 @@ mutation is undefined. @deffn Procedure nconc args @code{nconc} destructively concatenates its arguments. (Compare this with @code{append}, which copies arguments rather than destroying them.) -Sometimes called @code{append!} (@pxref{Rev2 Procedures}).@refill +Sometimes called @code{append!} (@pxref{Rev2 Procedures}). Example: You want to find the subsets of a set. Here's the obvious way: @@ -9002,7 +8990,7 @@ Example: You want to find the subsets of a set. Here's the obvious way: @end lisp But that does way more consing than you need. Instead, you could replace the @code{append} with @code{nconc}, since you don't have any -need for all the intermediate results.@refill +need for all the intermediate results. Example: @lisp @@ -9019,7 +9007,7 @@ x @deffn Procedure nreverse lst @code{nreverse} reverses the order of elements in @var{lst} by mutating -@code{cdr}s of the list. Sometimes called @code{reverse!}.@refill +@code{cdr}s of the list. Sometimes called @code{reverse!}. Example: @lisp @@ -9048,7 +9036,7 @@ The example should suffice to show why this is the case. @deffnx Procedure delete-if pred lst @deffnx Procedure delete-if-not pred lst Destructive versions of @code{remove} @code{remove-if}, and -@code{remove-if-not}.@refill +@code{remove-if-not}. Example: @lisp @@ -9084,7 +9072,7 @@ The examples should suffice to show why this is the case. @node Non-List functions, , Destructive list operations, Common List Functions @subsubsection Non-List functions -@defun and? . args +@defun and? arg1 @dots{} @code{and?} checks to see if all its arguments are true. If they are, @code{and?} returns @code{#t}, otherwise, @code{#f}. (In contrast to @code{and}, this is a function, so all arguments are always evaluated @@ -9099,7 +9087,7 @@ Example: @end lisp @end defun -@defun or? . args +@defun or? arg1 @dots{} @code{or?} checks to see if any of its arguments are true. If any is true, @code{or?} returns @code{#t}, and @code{#f} otherwise. (To @code{or} as @code{and?} is to @code{and}.)@refill @@ -9126,18 +9114,8 @@ pair. (Called @code{atom} in Common LISP.) @end lisp @end defun -@defun type-of object -Returns a symbol name for the type of @var{object}. -@end defun - -@defun coerce object result-type -Converts and returns @var{object} of type @code{char}, @code{number}, -@code{string}, @code{symbol}, @code{list}, or @code{vector} to -@var{result-type} (which must be one of these symbols). -@end defun - -@node Tree Operations, Chapter Ordering, Common List Functions, Procedures +@node Tree Operations, Chapter Ordering, Common List Functions, Sorting and Searching @subsection Tree operations @code{(require 'tree)} @@ -9146,15 +9124,17 @@ Converts and returns @var{object} of type @code{char}, @code{number}, These are operations that treat lists a representations of trees. @defun subst new old tree +@defunx subst new old tree equ? @defunx substq new old tree @defunx substv new old tree @code{subst} makes a copy of @var{tree}, substituting @var{new} for every subtree or leaf of @var{tree} which is @code{equal?} to @var{old} and returns a modified tree. The original @var{tree} is unchanged, but -may share parts with the result.@refill +may share parts with the result. @code{substq} and @code{substv} are similar, but test against @var{old} -using @code{eq?} and @code{eqv?} respectively.@refill +using @code{eq?} and @code{eqv?} respectively. If @code{subst} is +called with a fourth argument, @var{equ?} is the equality predicate. Examples: @lisp @@ -9171,7 +9151,7 @@ Examples: @defun copy-tree tree Makes a copy of the nested list structure @var{tree} using new pairs and returns it. All levels are copied, so that none of the pairs in the -tree are @code{eq?} to the original ones -- only the leaves are.@refill +tree are @code{eq?} to the original ones -- only the leaves are. Example: @lisp @@ -9184,7 +9164,7 @@ Example: @end defun -@node Chapter Ordering, Sorting, Tree Operations, Procedures +@node Chapter Ordering, Sorting, Tree Operations, Sorting and Searching @subsection Chapter Ordering @code{(require 'chapter-order)} @@ -9230,7 +9210,7 @@ chap:next-string will always be @code{chap:string<?} than the result. @end defun -@node Sorting, Topological Sort, Chapter Ordering, Procedures +@node Sorting, Topological Sort, Chapter Ordering, Sorting and Searching @subsection Sorting @code{(require 'sort)} @@ -9329,12 +9309,12 @@ The standard functions @code{<}, @code{>}, @code{char<?}, @code{char>?}, @code{char-ci<?}, @code{char-ci>?}, @code{string<?}, @code{string>?}, @code{string-ci<?}, and @code{string-ci>?} are suitable for use as comparison functions. Think of @code{(less? x y)} as saying when -@code{x} must @emph{not} precede @code{y}.@refill +@code{x} must @emph{not} precede @code{y}. @defun sorted? sequence less? Returns @code{#t} when the sequence argument is in non-decreasing order according to @var{less?} (that is, there is no adjacent pair @code{@dots{} x -y @dots{}} for which @code{(less? y x)}).@refill +y @dots{}} for which @code{(less? y x)}). Returns @code{#f} when the sequence contains at least one out-of-order pair. It is an error if the sequence is neither a list nor a vector. @@ -9368,7 +9348,7 @@ Accepts either a list or a vector, and returns a new sequence which is sorted. The new sequence is the same type as the input. Always @code{(sorted? (sort sequence less?) less?)}. The original sequence is not altered in any way. The new sequence shares its @emph{elements} -with the old one; no elements are copied.@refill +with the old one; no elements are copied. @end defun @deffn Procedure sort! sequence less? @@ -9409,7 +9389,7 @@ in Common LISP, just write @noindent in Scheme. -@node Topological Sort, String-Case, Sorting, Procedures +@node Topological Sort, String Search, Sorting, Sorting and Searching @subsection Topological Sort @code{(require 'topological-sort)} or @code{(require 'tsort)} @@ -9465,55 +9445,7 @@ tie or his belt.) `tsort' gives the correct order of dressing: @end defun - -@node String-Case, String Ports, Topological Sort, Procedures -@subsection String-Case - -@code{(require 'string-case)} -@ftindex string-case - -@deffn Procedure string-upcase str -@deffnx Procedure string-downcase str -@deffnx Procedure string-capitalize str -The obvious string conversion routines. These are non-destructive. -@end deffn - -@defun string-upcase! str -@defunx string-downcase! str -@defunx string-captialize! str -The destructive versions of the functions above. -@end defun - -@defun string-ci->symbol str -Converts string @var{str} to a symbol having the same case as if the -symbol had been @code{read}. -@end defun - - - -@node String Ports, String Search, String-Case, Procedures -@subsection String Ports - -@code{(require 'string-port)} -@ftindex string-port - -@deffn Procedure call-with-output-string proc -@var{proc} must be a procedure of one argument. This procedure calls -@var{proc} with one argument: a (newly created) output port. When the -function returns, the string composed of the characters written into the -port is returned.@refill -@end deffn - -@deffn Procedure call-with-input-string string proc -@var{proc} must be a procedure of one argument. This procedure calls -@var{proc} with one argument: an (newly created) input port from which -@var{string}'s contents may be read. When @var{proc} returns, the port -is closed and the value yielded by the procedure @var{proc} is -returned.@refill -@end deffn - - -@node String Search, Line I/O, String Ports, Procedures +@node String Search, Sequence Comparison, Topological Sort, Sorting and Searching @subsection String Search @code{(require 'string-search)} @@ -9582,16 +9514,105 @@ Returns a copy of string @var{txt} with all occurrences of string with @var{new2} @dots{}. @end defun -@node Line I/O, Multi-Processing, String Search, Procedures + +@node Sequence Comparison, , String Search, Sorting and Searching +@subsection Sequence Comparison + +@code{(require 'diff)} +@ftindex diff +@cindex Sequence Comparison + +@include differ.txi + + +@node Procedures, Standards Support, Sorting and Searching, Other Packages +@section Procedures + +Anything that doesn't fall neatly into any of the other categories winds +up here. + +@menu +* Type Coercion:: 'coerce +* String-Case:: 'string-case +* String Ports:: 'string-port +* Line I/O:: 'line-i/o +* Multi-Processing:: 'process +* Metric Units:: Portable manifest types for numeric values. +@end menu + + +@node Type Coercion, String-Case, Procedures, Procedures +@subsection Type Coercion +@code{(require 'coerce)} +@ftindex coerce + +@include coerce.txi + + +@node String-Case, String Ports, Type Coercion, Procedures +@subsection String-Case + +@code{(require 'string-case)} +@ftindex string-case + +@deffn Procedure string-upcase str +@deffnx Procedure string-downcase str +@deffnx Procedure string-capitalize str +The obvious string conversion routines. These are non-destructive. +@end deffn + +@defun string-upcase! str +@defunx string-downcase! str +@defunx string-captialize! str +The destructive versions of the functions above. +@end defun + +@defun string-ci->symbol str +Converts string @var{str} to a symbol having the same case as if the +symbol had been @code{read}. +@end defun + +@defun symbol-append obj1 @dots{} +Converts @var{obj1} @dots{} to strings, appends them, and converts to a +symbol which is returned. Strings and numbers are converted to read's +symbol case; the case of symbol characters is not changed. #f is +converted to the empty string (symbol). +@end defun + + + +@node String Ports, Line I/O, String-Case, Procedures +@subsection String Ports + +@code{(require 'string-port)} +@ftindex string-port + +@deffn Procedure call-with-output-string proc +@var{proc} must be a procedure of one argument. This procedure calls +@var{proc} with one argument: a (newly created) output port. When the +function returns, the string composed of the characters written into the +port is returned. +@end deffn + +@deffn Procedure call-with-input-string string proc +@var{proc} must be a procedure of one argument. This procedure calls +@var{proc} with one argument: an (newly created) input port from which +@var{string}'s contents may be read. When @var{proc} returns, the port +is closed and the value yielded by the procedure @var{proc} is +returned. +@end deffn + + +@node Line I/O, Multi-Processing, String Ports, Procedures @subsection Line I/O @code{(require 'line-i/o)} @ftindex line-i -@c @include lineio.txi +@include lineio.txi -@node Multi-Processing, , Line I/O, Procedures +@node Multi-Processing, Metric Units, Line I/O, Procedures @subsection Multi-Processing @code{(require 'process)} @@ -9609,13 +9630,13 @@ of writing schedulers in Scheme. Adds proc, which must be a procedure (or continuation) capable of accepting accepting one argument, to the @code{process:queue}. The value returned is unspecified. The argument to @var{proc} should be -ignored. If @var{proc} returns, the process is killed.@refill +ignored. If @var{proc} returns, the process is killed. @end deffn @deffn Procedure process:schedule! Saves the current process on @code{process:queue} and runs the next process from @code{process:queue}. The value returned is -unspecified.@refill +unspecified. @end deffn @deffn Procedure kill-process! @@ -9625,6 +9646,214 @@ Kills the current process and runs the next process from @end deffn +@node Metric Units, , Multi-Processing, Procedures +@subsection Metric Units + +@code{(require 'metric-units)} +@ftindex metric-units + +@url{http://swissnet.ai.mit.edu/~jaffer/MIXF.html} + +@dfn{Metric Interchange Format} is a character string encoding for +numerical values and units which: + +@itemize @bullet +@item +is unambiguous in all locales; + +@item +uses only [TOG] "Portable Character Set" characters matching "Basic +Latin" characters in Plane 0 of the Universal Character Set [UCS]; + +@item +is transparent to [UTF-7] and [UTF-8] UCS transformation formats; + +@item +is human readable and writable; + +@item +is machine readable and writable; + +@item +incorporates SI prefixes and units; + +@item +incorporates [ISO 6093] numbers; and + +@item +incorporates [IEC 60027-2] binary prefixes. +@end itemize + +In the expression for the value of a quantity, the unit symbol is placed +after the numerical value. A dot (PERIOD, @samp{.}) is placed between +the numerical value and the unit symbol. + +Within a compound unit, each of the base and derived symbols can +optionally have an attached SI prefix. + +Unit symbols formed from other unit symbols by multiplication are +indicated by means of a dot (PERIOD, @samp{.}) placed between them. + +Unit symbols formed from other unit symbols by division are indicated by +means of a SOLIDUS (@samp{/}) or negative exponents. The SOLIDUS must +not be repeated in the same compound unit unless contained within a +parenthesized subexpression. + +The grouping formed by a prefix symbol attached to a unit symbol +constitutes a new inseparable symbol (forming a multiple or submultiple +of the unit concerned) which can be raised to a positive or negative +power and which can be combined with other unit symbols to form compound +unit symbols. + +The grouping formed by surrounding compound unit symbols with +parentheses (@samp{(} and @samp{)}) constitutes a new inseparable symbol +which can be raised to a positive or negative power and which can be +combined with other unit symbols to form compound unit symbols. + +Compound prefix symbols, that is, prefix symbols formed by the +juxtaposition of two or more prefix symbols, are not permitted. + +Prefix symbols are not used with the time-related unit symbols min +(minute), h (hour), d (day). No prefix symbol may be used with dB +(decibel). Only submultiple prefix symbols may be used with the unit +symbols L (liter), Np (neper), o (degree), oC (degree Celsius), rad +(radian), and sr (steradian). Submultiple prefix symbols may not be +used with the unit symbols t (metric ton), r (revolution), or Bd (baud). + +A unit exponent follows the unit, separated by a CIRCUMFLEX (@samp{^}). +Exponents may be positive or negative. Fractional exponents must be +parenthesized. + +@subsubheading SI Prefixes +@example + Factor Name Symbol | Factor Name Symbol + ====== ==== ====== | ====== ==== ====== + 1e24 yotta Y | 1e-1 deci d + 1e21 zetta Z | 1e-2 centi c + 1e18 exa E | 1e-3 milli m + 1e15 peta P | 1e-6 micro u + 1e12 tera T | 1e-9 nano n + 1e9 giga G | 1e-12 pico p + 1e6 mega M | 1e-15 femto f + 1e3 kilo k | 1e-18 atto a + 1e2 hecto h | 1e-21 zepto z + 1e1 deka da | 1e-24 yocto y +@end example + +@subsubheading Binary Prefixes + +These binary prefixes are valid only with the units B (byte) and bit. +However, decimal prefixes can also be used with bit; and decimal +multiple (not submultiple) prefixes can also be used with B (byte). + +@example + Factor (power-of-2) Name Symbol + ====== ============ ==== ====== + 1.152921504606846976e18 (2^60) exbi Ei + 1.125899906842624e15 (2^50) pebi Pi + 1.099511627776e12 (2^40) tebi Ti + 1.073741824e9 (2^30) gibi Gi + 1.048576e6 (2^20) mebi Mi + 1.024e3 (2^10) kibi Ki +@end example + +@subsubheading Unit Symbols + +@example + Type of Quantity Name Symbol Equivalent + ================ ==== ====== ========== +time second s +time minute min = 60.s +time hour h = 60.min +time day d = 24.h +frequency hertz Hz s^-1 +signaling rate baud Bd s^-1 +length meter m +volume liter L dm^3 +plane angle radian rad +solid angle steradian sr rad^2 +plane angle revolution * r = 6.283185307179586.rad +plane angle degree * o = 2.777777777777778e-3.r +information capacity bit bit +information capacity byte, octet B = 8.bit +mass gram g +mass ton t Mg +mass unified atomic mass unit u = 1.66053873e-27.kg +amount of substance mole mol +catalytic activity katal kat mol/s +thermodynamic temperature kelvin K +centigrade temperature degree Celsius oC +luminous intensity candela cd +luminous flux lumen lm cd.sr +illuminance lux lx lm/m^2 +force newton N m.kg.s^-2 +pressure, stress pascal Pa N/m^2 +energy, work, heat joule J N.m +energy electronvolt eV = 1.602176462e-19.J +power, radiant flux watt W J/s +logarithm of power ratio neper Np +logarithm of power ratio decibel * dB = 0.1151293.Np +electric current ampere A +electric charge coulomb C s.A +electric potential, EMF volt V W/A +capacitance farad F C/V +electric resistance ohm Ohm V/A +electric conductance siemens S A/V +magnetic flux weber Wb V.s +magnetic flux density tesla T Wb/m^2 +inductance henry H Wb/A +radionuclide activity becquerel Bq s^-1 +absorbed dose energy gray Gy m^2.s^-2 +dose equivalent sievert Sv m^2.s^-2 +@end example + +* The formulas are: + +@itemize @bullet +@item +r/rad = 8 * atan(1) +@item +o/r = 1 / 360 +@item +db/Np = ln(10) / 20 +@end itemize + +@defun si:conversion-factor to-unit from-unit +If the strings @var{from-unit} and @var{to-unit} express valid unit +expressions for quantities of the same unit-dimensions, then the value +returned by @code{si:conversion-factor} will be such that multiplying a +numerical value expressed in @var{from-unit}s by the returned conversion +factor yields the numerical value expressed in @var{to-unit}s. + +Otherwise, @code{si:conversion-factor} returns: + +@table @asis +@item -3 +if neither @var{from-unit} nor @var{to-unit} is a syntactically valid +unit. +@item -2 +if @var{from-unit} is not a syntactically valid unit. +@item -1 +if @var{to-unit} is not a syntactically valid unit. +@item 0 +if linear conversion (by a factor) is not possible. +@end table + +@end defun + +@example +(si:conversion-factor "km/s" "m/s" ) @result{} 0.001 +(si:conversion-factor "N" "m/s" ) @result{} 0 +(si:conversion-factor "moC" "oC" ) @result{} 1000 +(si:conversion-factor "mK" "oC" ) @result{} 0 +(si:conversion-factor "rad" "o" ) @result{} 0.0174533 +(si:conversion-factor "K" "o" ) @result{} 0 +(si:conversion-factor "K" "K" ) @result{} 1 +(si:conversion-factor "oK" "oK" ) @result{} -3 +(si:conversion-factor "" "s/s" ) @result{} 1 +(si:conversion-factor "km/h" "mph" ) @result{} -2 +@end example + @node Standards Support, Session Support, Procedures, Other Packages @section Standards Support @@ -9643,6 +9872,7 @@ Kills the current process and runs the next process from * Dynamic-Wind:: 'dynamic-wind * Eval:: 'eval * Values:: 'values +* SRFI:: 'http://srfi.schemers.org/srfi-0/srfi-0.html @end menu @node With-File, Transcripts, Standards Support, Standards Support @@ -9665,7 +9895,7 @@ Description found in R4RS. @defun transcript-on filename @defunx transcript-off filename Redefines @code{read-char}, @code{read}, @code{write-char}, -@code{write}, @code{display}, and @code{newline}.@refill +@code{write}, @code{display}, and @code{newline}. @end defun @@ -9681,7 +9911,7 @@ Redefines @code{read-char}, @code{read}, @code{write-char}, The procedures below were specified in the @cite{Revised^2 Report on Scheme}. @strong{N.B.}: The symbols @code{1+} and @code{-1+} are not @cite{R4RS} syntax. Scheme->C, for instance, barfs on this -module.@refill +module. @deffn Procedure substring-move-left! string1 start1 end1 string2 start2 @deffnx Procedure substring-move-right! string1 start1 end1 string2 start2 @@ -9696,23 +9926,23 @@ module.@refill @code{substring-move-left!} and @code{substring-move-right!} store characters of @var{string1} beginning with index @var{start1} (inclusive) and ending with index @var{end1} (exclusive) into -@var{string2} beginning with index @var{start2} (inclusive).@refill +@var{string2} beginning with index @var{start2} (inclusive). @code{substring-move-left!} stores characters in time order of increasing indices. @code{substring-move-right!} stores characters in -time order of increasing indeces.@refill +time order of increasing indeces. @end deffn @deffn Procedure substring-fill! string start end char Fills the elements @var{start}--@var{end} of @var{string} with the -character @var{char}.@refill +character @var{char}. @end deffn @defun string-null? str @equiv{} @code{(= 0 (string-length @var{str}))} @end defun -@deffn Procedure append! . pairs +@deffn Procedure append! pair1 @dots{} Destructively appends its arguments. Equivalent to @code{nconc}. @end deffn @@ -9781,20 +10011,20 @@ For the specification of these optional procedures, For the specification of these optional forms, @xref{Numerical operations, , ,r4rs, Revised(4) Scheme}. The @code{two-arg:}* forms are only defined if the implementation does not support the many-argument -forms.@refill +forms. @defun two-arg:/ n1 n2 The original two-argument version of @code{/}. @end defun -@defun / divident . divisors +@defun / dividend divisor1 @dots{} @end defun @defun two-arg:- n1 n2 The original two-argument version of @code{-}. @end defun -@defun - minuend . subtrahends +@defun - minuend subtrahend1 @dots{} @end defun @@ -9816,7 +10046,7 @@ The implementation's native @code{apply}. Only defined for implementations which don't support the many-argument version. @end defun -@defun apply proc . args +@defun apply proc arg1 @dots{} @end defun @@ -9829,19 +10059,43 @@ implementations which don't support the many-argument version. @code{(require 'rationalize)} @ftindex rationalize -The procedure rationalize is interesting because most programming -languages do not provide anything analogous to it. For simplicity, we -present an algorithm which computes the correct result for exact -arguments (provided the implementation supports exact rational numbers -of unlimited precision), and produces a reasonable answer for inexact -arguments when inexact arithmetic is implemented using floating-point. -We thank Alan Bawden for contributing this algorithm. +The procedure @dfn{rationalize} is interesting because most programming +languages do not provide anything analogous to it. Thanks to Alan +Bawden for contributing this algorithm. -@defun rationalize x e +@defun rationalize x y +Computes the correct result for exact arguments (provided the +implementation supports exact rational numbers of unlimited precision); +and produces a reasonable answer for inexact arguments when inexact +arithmetic is implemented using floating-point. @end defun +@code{Rationalize} has limited use in implementations lacking exact +(non-integer) rational numbers. The following procedures return a list +of the numerator and denominator. + +@defun find-ratio x y +@code{find-ratio} returns the list of the @emph{simplest} +numerator and denominator whose quotient differs from @var{x} by no more +than @var{y}. + +@format +@t{(find-ratio 3/97 .0001) @result{} (3 97) +(find-ratio 3/97 .001) @result{} (1 32) +} +@end format +@end defun +@defun find-ratio-between x y +@code{find-ratio-between} returns the list of the @emph{simplest} +numerator and denominator between @var{x} and @var{y}. +@format +@t{(find-ratio-between 2/7 3/5) @result{} (1 2) +(find-ratio-between -3/5 -2/7) @result{} (-1 2) +} +@end format +@end defun @node Promises, Dynamic-Wind, Rationalize, Standards Support @@ -9870,11 +10124,11 @@ doesn't support them This facility is a generalization of Common LISP @code{unwind-protect}, designed to take into account the fact that continuations produced by -@code{call-with-current-continuation} may be reentered.@refill +@code{call-with-current-continuation} may be reentered. @deffn Procedure dynamic-wind thunk1 thunk2 thunk3 The arguments @var{thunk1}, @var{thunk2}, and @var{thunk3} must all be -procedures of no arguments (thunks).@refill +procedures of no arguments (thunks). @code{dynamic-wind} calls @var{thunk1}, @var{thunk2}, and then @var{thunk3}. The value returned by @var{thunk2} is returned as the @@ -9888,7 +10142,7 @@ context of @var{thunk2} if @var{thunk2} is on the current return stack). @strong{Warning:} There is no provision for dealing with errors or interrupts. If an error or interrupt occurs while using @code{dynamic-wind}, the dynamic environment will be that in effect at -the time of the error or interrupt.@refill +the time of the error or interrupt. @end deffn @@ -9984,7 +10238,7 @@ car @end example -@node Values, , Eval, Standards Support +@node Values, SRFI, Eval, Standards Support @subsection Values @code{(require 'values)} @@ -9992,7 +10246,7 @@ car @defun values obj @dots{} @code{values} takes any number of arguments, and passes (returns) them -to its continuation.@refill +to its continuation. @end defun @@ -10000,15 +10254,29 @@ to its continuation.@refill @var{thunk} must be a procedure of no arguments, and @var{proc} must be a procedure. @code{call-with-values} calls @var{thunk} with a continuation that, when passed some values, calls @var{proc} with those -values as arguments.@refill +values as arguments. Except for continuations created by the @code{call-with-values} procedure, all continuations take exactly one value, as now; the effect of passing no value or more than one value to continuations that were not created by the @code{call-with-values} procedure is -unspecified.@refill +unspecified. @end defun +@node SRFI, , Values, Standards Support +@subsection SRFI + +@include srfi.txi + +@menu +* SRFI-1:: list-processing +@end menu + +@node SRFI-1, , SRFI, SRFI +@subsubsection SRFI-1 + +@include srfi-1.txi + @node Session Support, Extra-SLIB Packages, Standards Support, Other Packages @section Session Support @@ -10036,7 +10304,7 @@ Here is a read-eval-print-loop which, given an eval, evaluates forms. @code{(current-input-port)} to @code{(current-output-port)} until an end-of-file is encountered. @code{load}, @code{slib:eval}, @code{slib:error}, and @code{repl:quit} dynamically bound during -@code{repl:top-level}.@refill +@code{repl:top-level}. @end deffn @deffn Procedure repl:quit @@ -10051,7 +10319,7 @@ and interrupts. If your implementation supports this you are all set. Otherwise, if there is some way your implementation can catch error conditions and interrupts, then have them call @code{slib:error}. It will display its arguments and reenter @code{repl:top-level}. -@code{slib:error} dynamically bound by @code{repl:top-level}.@refill +@code{slib:error} dynamically bound by @code{repl:top-level}. To have your top level loop always use macros, add any interrupt catching lines and the following lines to your Scheme init file: @@ -10090,12 +10358,12 @@ bit-vectors are @emph{not} limited. substituting @samp{...} for substructure it does not have sufficient room to print. @code{qpn} is like @code{qp} but outputs a newline before returning. @code{qpr} is like @code{qpn} except that it returns -its last argument.@refill +its last argument. @end deffn @defvar *qp-width* @code{*qp-width*} is the largest number of characters that @code{qp} -should use.@refill +should use. @end defvar @node Debug, Breakpoints, Quick Print, Session Support @@ -10119,14 +10387,20 @@ printer for @code{qp}. This example shows how to do this: @ftindex debug @end example -@deffn Procedure trace-all file +@deffn Procedure trace-all file @dots{} Traces (@pxref{Trace}) all procedures @code{define}d at top-level in -file @file{file}. +@file{file} @dots{}. +@deffnx Procedure track-all file @dots{} +Tracks (@pxref{Trace}) all procedures @code{define}d at top-level in +@file{file} @dots{}. +@deffnx Procedure stack-all file @dots{} +Stacks (@pxref{Trace}) all procedures @code{define}d at top-level in +@file{file} @dots{}. @end deffn -@deffn Procedure break-all file +@deffn Procedure break-all file @dots{} Breakpoints (@pxref{Breakpoints}) all procedures @code{define}d at -top-level in file @file{file}. +top-level in @file{file} @dots{}. @end deffn @node Breakpoints, Trace, Debug, Session Support @@ -10176,15 +10450,11 @@ With no arguments, unbreaks all currently broken identifiers and returns a list of these formerly broken identifiers. @end defmac -The following routines are the procedures which actually do the tracing -when this module is supplied by SLIB, rather than natively. If -defmacros are not natively supported by your implementation, these might -be more convenient to use. +These are @emph{procedures} for breaking. If defmacros are not natively +supported by your implementation, these might be more convenient to use. @defun breakf proc @defunx breakf proc name -@defunx debug:breakf proc -@defunx debug:breakf proc name To break, type @lisp (set! @var{symbol} (breakf @var{symbol})) @@ -10207,7 +10477,6 @@ or @end defun @defun unbreakf proc -@defunx debug:unbreakf proc To unbreak, type @lisp (set! @var{symbol} (unbreakf @var{symbol})) @@ -10220,6 +10489,34 @@ To unbreak, type @code{(require 'trace)} @ftindex trace +@noindent +This feature provides three ways to monitor procedure invocations: + +@table @asis +@item stack +Pushes the procedure-name when the procedure is called; pops when it +returns. +@item track +Pushes the procedure-name and arguments when the procedure is called; +pops when it returns. +@item trace +Pushes the procedure-name and prints @samp{CALL @var{procedure-name} +@var{arg1} @dots{}} when the procdure is called; pops and prints +@samp{RETN @var{procedure-name} @var{value}} when the procedure returns. +@end table + +@defvar debug:max-count +If a traced procedure calls itself or untraced procedures which call it, +stack, track, and trace will limit the number of stack pushes to +@var{debug:max-count}. +@end defvar + +@defun print-call-stack +@defunx print-call-stack port +Prints the call-stack to @var{port} or the current-error-port. +@end defun + + @defmac trace proc1 @dots{} Traces the top-level named procedures given as arguments. @defmacx trace @@ -10228,22 +10525,48 @@ are traced (even if those identifiers have been redefined) and returns a list of the traced identifiers. @end defmac +@defmac track proc1 @dots{} +Traces the top-level named procedures given as arguments. +@defmacx track +With no arguments, makes sure that all the currently tracked identifiers +are tracked (even if those identifiers have been redefined) and returns +a list of the tracked identifiers. +@end defmac + +@defmac stack proc1 @dots{} +Traces the top-level named procedures given as arguments. +@defmacx stack +With no arguments, makes sure that all the currently stacked identifiers +are stacked (even if those identifiers have been redefined) and returns +a list of the stacked identifiers. +@end defmac + @defmac untrace proc1 @dots{} -Turns tracing off for its arguments. +Turns tracing, tracking, and off for its arguments. @defmacx untrace With no arguments, untraces all currently traced identifiers and returns a list of these formerly traced identifiers. @end defmac -The following routines are the procedures which actually do the tracing -when this module is supplied by SLIB, rather than natively. If -defmacros are not natively supported by your implementation, these might -be more convenient to use. +@defmac untrack proc1 @dots{} +Turns tracing, tracking, and off for its arguments. +@defmacx untrack +With no arguments, untracks all currently tracked identifiers and returns +a list of these formerly tracked identifiers. +@end defmac + +@defmac unstack proc1 @dots{} +Turns tracing, stacking, and off for its arguments. +@defmacx unstack +With no arguments, unstacks all currently stacked identifiers and returns +a list of these formerly stacked identifiers. +@end defmac + +These are @emph{procedures} for tracing. If defmacros are not natively +supported by your implementation, these might be more convenient to use. @defun tracef proc @defunx tracef proc name -@defunx debug:tracef proc -@defunx debug:tracef proc name To trace, type @lisp (set! @var{symbol} (tracef @var{symbol})) @@ -10266,7 +10589,7 @@ or @end defun @defun untracef proc -@defunx debug:untracef proc +Removes tracing, tracking, or stacking for @var{proc}. To untrace, type @lisp (set! @var{symbol} (untracef @var{symbol})) @@ -10301,7 +10624,7 @@ programs like FTP, mail, and Netscape. @code{(require 'net-clients)} @ftindex net-clients -@c @include nclients.txi +@include nclients.txi @node Extra-SLIB Packages, , Session Support, Other Packages @@ -10330,13 +10653,23 @@ and used as easily as any other SLIB package. Some optional packages sites are: @table @asis -@item SLIB-PSD is a portable debugger for Scheme (requires emacs editor). -@lisp +@item SLIB-PSD +is a portable debugger for Scheme (requires emacs editor). + +@ifset html +<A HREF="http://swissnet.ai.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz"> +@end ifset http://swissnet.ai.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz -ftp.gnu.org:pub/gnu/jacal/slib-psd1-3.tar.gz +@ifset html +</A> +@end ifset + +swissnet.ai.mit.edu:/pub/scm/slib-psd1-3.tar.gz + ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz + ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz -@end lisp +@sp 1 With PSD, you can run a Scheme program in an Emacs buffer, set breakpoints, single step evaluation and access and modify the program's @@ -10345,11 +10678,37 @@ should run with any R4RS compliant Scheme. It has been tested with SCM, Elk 1.5, and the sci interpreter in the Scheme->C system, but should work with other Schemes with a minimal amount of porting, if at all. Includes documentation and user's manual. Written by Pertti -Kellom\"aki, pk@@cs.tut.fi. The Lisp Pointers article describing PSD +Kellom\"aki, pk @@ cs.tut.fi. The Lisp Pointers article describing PSD (Lisp Pointers VI(1):15-23, January-March 1993) is available as -@url{http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html} -@item SCHELOG is an embedding of Prolog in Scheme. -@url{http://www.cs.rice.edu/CS/PLT/packages/schelog/} +@ifset html +<A HREF="http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html"> +@end ifset +http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html +@ifset html +</A> +@end ifset +@sp 1 + +@item SCHELOG +is an embedding of Prolog in Scheme. +@ifset html +<A HREF="http://www.cs.rice.edu/CS/PLT/packages/schelog/"> +@end ifset +http://www.cs.rice.edu/CS/PLT/packages/schelog/ +@ifset html +</A> +@end ifset +@sp 1 + +@item JFILTER +is a Scheme program which converts text among the JIS, EUC, and Shift-JIS Japanese character sets. +@ifset html +<A HREF="http://www.sci.toyama-u.ac.jp/~iwao/Scheme/Jfilter/index.html"> +@end ifset +http://www.sci.toyama-u.ac.jp/~iwao/Scheme/Jfilter/index.html +@ifset html +</A> +@end ifset @end table @@ -10363,7 +10722,7 @@ you! @quotation SLIB @value{SLIBVERSION}, released @value{SLIBDATE}.@* -Aubrey Jaffer <jaffer @@ ai.mit.edu>@* +Aubrey Jaffer <agj @@ alum.mit.edu>@* @i{Hyperactive Software} -- The Maniac Inside!@* @url{http://swissnet.ai.mit.edu/~jaffer/SLIB.html} @end quotation @@ -10372,7 +10731,7 @@ Aubrey Jaffer <jaffer @@ ai.mit.edu>@* @menu * Installation:: How to install SLIB on your system. * Porting:: SLIB to new platforms. -* Coding Standards:: How to write modules for SLIB. +* Coding Guidelines:: How to write modules for SLIB. * Copyrights:: Intellectual propery issues. @end menu @@ -10388,9 +10747,33 @@ Aubrey Jaffer <jaffer @@ ai.mit.edu>@* </A> @end ifset -Check the manifest in @file{README} to find a configuration file for -your Scheme implementation. Initialization files for most IEEE P1178 -compliant Scheme Implementations are included with this distribution. +There are four parts to installation: + +@itemize @bullet +@item +Unpack the SLIB distribution. +@item +Configure the Scheme implementation(s) to locate the SLIB directory. +@item +Arrange for Scheme implementation to load its SLIB initialization file. +@item +Build the SLIB catalog for the Scheme implementation. +@end itemize + +@subsection Unpacking the SLIB Distribution + +If the SLIB distribution is a Linux RPM, it will create the SLIB +directory @file{/usr/share/slib}. + +If the SLIB distribution is a ZIP file, unzip the distribution to create +the SLIB directory. Locate this @file{slib} directory either in your +home directory (if only you will use this SLIB installation); or put it +in a location where libraries reside on your system. On unix systems +this might be @file{/usr/share/slib}, @file{/usr/local/lib/slib}, or +@file{/usr/lib/slib}. If you know where SLIB should go on other +platforms, please inform agj @@ alum.mit.edu. + +@subsection Configure Scheme Implementation to Locate SLIB If the Scheme implementation supports @code{getenv}, then the value of the shell environment variable @var{SCHEME_LIBRARY_PATH} will be used @@ -10399,6 +10782,15 @@ MITScheme, scheme->c, VSCM, and SCM support @code{getenv}. Scheme48 supports @code{getenv} but does not use it for determining @code{library-vicinity}. (That is done from the Makefile.) +The @code{(library-vicinity)} can also be specified from the SLIB +initialization file or by implementation-specific means. + +@subsection Loading SLIB Initialization File + +Check the manifest in @file{README} to find a configuration file for +your Scheme implementation. Initialization files for most IEEE P1178 +compliant Scheme Implementations are included with this distribution. + You should check the definitions of @code{software-type}, @code{scheme-implementation-version}, @iftex @@ -10408,27 +10800,105 @@ You should check the definitions of @code{software-type}, and @code{library-vicinity} in the initialization file. There are comments in the file for how to configure it. -Once this is done you can modify the startup file for your Scheme -implementation to @code{load} this initialization file. SLIB is then -installed. +Once this is done, modify the startup file for your Scheme +implementation to @code{load} this initialization file. + +@subsection Build New SLIB Catalog for Implementation + +When SLIB is first used from an implementation, a file named +@file{slibcat} is written to the @code{implementation-vicinity} for that +implementation. Because users may lack permission to write in +@code{implementation-vicinity}, it is good practice to build the new +catalog when installing SLIB. + +To build (or rebuild) the catalog, start the Scheme implementation (with +SLIB), then: + +@example +(require 'new-catalog) +@end example + +@subsection Implementation-specific Instructions Multiple implementations of Scheme can all use the same SLIB directory. Simply configure each implementation's initialization file as outlined above. +@deftp Implementation SCM The SCM implementation does not require any initialization file as SLIB -support is already built in to SCM. See the documentation with SCM for +support is already built into SCM. See the documentation with SCM for installation instructions. +@end deftp + +@deftp Implementation VSCM +@format +From: Matthias Blume <blume @@ cs.Princeton.EDU> +Date: Tue, 1 Mar 1994 11:42:31 -0500 +@end format + +Disclaimer: The code below is only a quick hack. If I find some time to +spare I might get around to make some more things work. + +You have to provide @file{vscm.init} as an explicit command line +argument. Since this is not very nice I would recommend the following +installation procedure: + +@enumerate +@item +run scheme +@item +@code{(load "vscm.init")} +@item +@code{(slib:dump "dumpfile")} +@item +mv dumpfile place-where-vscm-standard-bootfile-resides +e.g. mv dumpfile /usr/local/vscm/lib/scheme-boot +(In this case vscm should have been compiled with flag +-DDEFAULT_BOOTFILE='"/usr/local/vscm/lib/scheme-boot"'. See Makefile +(definition of DDP) for details.) +@end enumerate + +@end deftp + +@deftp Implementation Scheme48 +To make a Scheme48 image for an installation under @code{<prefix>}, + +@enumerate +@item +@code{cd} to the SLIB directory +@item +type @code{make prefix=<prefix> slib48}. +@item +To install the image, type @code{make prefix=<prefix> install48}. This +will also create a shell script with the name @code{slib48} which will +invoke the saved image. +@end enumerate +@end deftp + +@deftp Implementation {PLT Scheme} +@deftpx Implementation {DrScheme} +@deftpx Implementation {MzScheme} + +The @file{init.ss} file in the _slibinit_ collection is an SLIB +initialization file. + +To use SLIB in MzScheme, set the @var{SCHEME_LIBRARY_PATH} environment +variable to the installed SLIB location; then invoke MzScheme thus: + +@code{mzscheme -L init.ss slibinit} +@end deftp + +@deftp Implementation {MIT Scheme} +@code{scheme -load $@{SCHEME_LIBRARY_PATH@}mitscheme.init} +@end deftp + +@deftp Implementation {Guile} +@code{guile -l $@{SCHEME_LIBRARY_PATH@}guile.init} +@end deftp + -SLIB includes methods to create heap images for the VSCM and Scheme48 -implementations. The instructions for creating a VSCM image are in -comments in @file{vscm.init}. To make a Scheme48 image for an -installation under @code{<prefix>}, @code{cd} to the SLIB directory and -type @code{make prefix=<prefix> slib48}. To install the image, type -@code{make prefix=<prefix> install48}. This will also create a shell -script with the name @code{slib48} which will invoke the saved image. -@node Porting, Coding Standards, Installation, About SLIB +@node Porting, Coding Guidelines, Installation, About SLIB @section Porting If there is no initialization file for your Scheme implementation, you @@ -10453,31 +10923,31 @@ the library; this will allow the use of @code{provide}, @code{provided?}, and @code{require} along with the @dfn{vicinity} functions (these functions are documented in the section @ref{Require}). The rest of the library will then be accessible in a system independent -fashion.@refill +fashion. -Please mail new working configuration files to @code{jaffer @@ ai.mit.edu} -so that they can be included in the SLIB distribution.@refill +Please mail new working configuration files to @code{agj @@ alum.mit.edu} +so that they can be included in the SLIB distribution. -@node Coding Standards, Copyrights, Porting, About SLIB -@section Coding Standards +@node Coding Guidelines, Copyrights, Porting, About SLIB +@section Coding Guidelines All library packages are written in IEEE P1178 Scheme and assume that a configuration file and @file{require.scm} package have already been loaded. Other versions of Scheme can be supported in library packages as well by using, for example, @code{(provided? 'rev3-report)} or -@code{(require 'rev3-report)} (@pxref{Require}).@refill +@code{(require 'rev3-report)} (@pxref{Require}). @ftindex rev3-report The module name and @samp{:} should prefix each symbol defined in the package. Definitions for external use should then be exported by having -@code{(define foo module-name:foo)}.@refill +@code{(define foo module-name:foo)}. Code submitted for inclusion in SLIB should not duplicate routines already in SLIB files. Use @code{require} to force those library routines to be used by your package. Care should be taken that there are no circularities in the @code{require}s and @code{load}s between the -library packages.@refill +library packages. Documentation should be provided in Emacs Texinfo format if possible, But documentation must be provided. @@ -10505,7 +10975,7 @@ Please @emph{do not} reformat the source code with your favorite beautifier, make 10 fixes, and send me the resulting source code. I do not have the time to fish through 10000 diffs to find your 10 real fixes. -@node Copyrights, , Coding Standards, About SLIB +@node Copyrights, , Coding Guidelines, About SLIB @section Copyrights @ifset html @@ -10529,7 +10999,7 @@ need to add your copyright or send a disclaimer. In order to put code in the public domain you should sign a copyright disclaimer and send it to the SLIB maintainer. Contact -jaffer @@ ai.mit.edu for the address to mail the disclaimer to. +agj @@ alum.mit.edu for the address to mail the disclaimer to. @quotation I, @var{name}, hereby affirm that I have placed the software package @@ -10554,7 +11024,7 @@ revisions of that module. Make sure no employer has any claim to the copyright on the work you are submitting. If there is any doubt, create a copyright disclaimer and have your employer sign it. Mail the signed disclaimer to the SLIB -maintainer. Contact jaffer @@ ai.mit.edu for the address to mail the +maintainer. Contact agj @@ alum.mit.edu for the address to mail the disclaimer to. An example disclaimer follows. @subheading Explicit copying terms @@ -10574,7 +11044,7 @@ from those already in the file. Make sure no employer has any claim to the copyright on the work you are submitting. If there is any doubt, create a copyright disclaimer and have your employer sign it. Mail the signed disclaim to the SLIB -maintainer. Contact jaffer @@ ai.mit.edu for the address to mail the +maintainer. Contact agj @@ alum.mit.edu for the address to mail the disclaimer to. @end itemize |