summaryrefslogtreecommitdiffstats
path: root/slib.texi
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:27 -0800
committerBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:27 -0800
commitfa3f23105ddcf07c5900de47f19af43d1db1b597 (patch)
treeb2c6cce6b97698098f50cbc78c23fdc0f8d401ab /slib.texi
parentf24b9140d6f74804d5599ec225717d38ca443813 (diff)
downloadslib-fa3f23105ddcf07c5900de47f19af43d1db1b597.tar.gz
slib-fa3f23105ddcf07c5900de47f19af43d1db1b597.zip
Import Upstream version 2c3upstream/2c3
Diffstat (limited to 'slib.texi')
-rw-r--r--slib.texi1265
1 files changed, 601 insertions, 664 deletions
diff --git a/slib.texi b/slib.texi
index 9251b9f..7aed0b5 100644
--- a/slib.texi
+++ b/slib.texi
@@ -10,6 +10,11 @@
@syncodeindex tp cp
@c %**end of header
+@dircategory The Algorithmic Language Scheme
+@direntry
+* SLIB: (slib). Scheme Library
+@end direntry
+
@iftex
@finalout
@c DL: lose the egregious vertical whitespace, esp. around examples
@@ -21,7 +26,7 @@
This file documents SLIB, the portable Scheme library.
Copyright (C) 1993 Todd R. Eigenschink@*
-Copyright (C) 1993, 1994, 1995, 1996, 1997 Aubrey Jaffer
+Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998 Aubrey Jaffer
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -48,13 +53,13 @@ by the author.
@titlepage
@title SLIB
@subtitle The Portable Scheme Library
-@subtitle Version 2c0
+@subtitle Version 2c3
@author by Aubrey Jaffer
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993 Todd R. Eigenschink@*
-Copyright @copyright{} 1993, 1994, 1995, 1996, 1997 Aubrey Jaffer
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998 Aubrey Jaffer
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -89,7 +94,7 @@ specific to a site, implementation, user, or directory.
@quotation
Aubrey Jaffer <jaffer@@ai.mit.edu>@*
@i{Hyperactive Software} -- The Maniac Inside!@*
-http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
+@url{http://swissnet.ai.mit.edu/~jaffer/SLIB.html}
@end quotation
@end ifinfo
@@ -125,13 +130,7 @@ specific to a site, implementation, user, or directory.
@quotation
Aubrey Jaffer <jaffer@@ai.mit.edu>@*
@i{Hyperactive Software} -- The Maniac Inside!@*
-@ifset html
-<A HREF="http://www-swiss.ai.mit.edu/~jaffer/SLIB.html">
-@end ifset
-http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
-@ifset html
-</A>
-@end ifset
+@url{http://swissnet.ai.mit.edu/~jaffer/SLIB.html}
@end quotation
@end iftex
@@ -316,12 +315,12 @@ Here is an example of a @file{usercat} catalog. A Program in this
directory can invoke the @samp{run} feature with @code{(require 'run)}.
@example
-;;; "usercat": SLIB catalog additions for SIMSYNCH. -*-scheme-*-
+;;; "usercat": SLIB catalog additions for SIMSYNCH. -*-scheme-*-
(
- (simsynch . "../synch/simsynch.scm")
- (run . "../synch/run.scm")
- (schlep . "schlep.scm")
+ (simsynch . "../synch/simsynch.scm")
+ (run . "../synch/run.scm")
+ (schlep . "schlep.scm")
)
@end example
@@ -492,9 +491,9 @@ unspecified value is returned. If @var{feature} is not found in
@code{*catalog*}, then an error is signaled.
@deffnx Procedure require pathname
-@var{pathname} is a string. If @var{pathname} has not already been given as
-an argument to @code{require}, @var{pathname} is loaded.
-An unspecified value is returned.
+@var{pathname} is a string. If @var{pathname} has not already been
+given as an argument to @code{require}, @var{pathname} is loaded. An
+unspecified value is returned.
@end deffn
@deffn Procedure provide feature
@@ -530,8 +529,8 @@ these procedures are file system dependent.
@noindent
These procedures are provided by all implementations.
-@defun make-vicinity filename
-Returns the vicinity of @var{filename} for use by @code{in-vicinity}.
+@defun make-vicinity path
+Returns the vicinity of @var{path} for use by @code{in-vicinity}.
@end defun
@defun program-vicinity
@@ -631,7 +630,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 "2c0" on scm "5b1" on unix
+(slib:report-version) @result{} slib "2c3" on scm "5b1" on unix
@end example
@end defun
@@ -649,7 +648,7 @@ Writes the report to file @file{filename}.
@example
(slib:report)
@result{}
-slib "2c0" on scm "5b1" on unix
+slib "2c3" on scm "5b1" on unix
(implementation-vicinity) is "/home/jaffer/scm/"
(library-vicinity) is "/home/jaffer/slib/"
(scheme-file-suffix) is ".scm"
@@ -802,7 +801,8 @@ If an implementation does not support compiled code then
@deffn Procedure slib:eval obj
@code{eval} returns the value of @var{obj} evaluated in the current top
-level environment.@refill
+level environment. @ref{Eval} provides a more general evaluation
+facility.
@end deffn
@deffn Procedure slib:eval-load filename eval
@@ -1916,7 +1916,7 @@ 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 default behavior (for an empty
+operation @var{opname}. The default behavior (for an empty
@var{default-body}) is to generate an error.@refill
@end deffn
@@ -2134,10 +2134,12 @@ value is unspecified.
* Precedence Parsing::
* Format:: Common-Lisp Format
* Standard Formatted I/O:: Posix printf and scanf
-* Program Arguments:: Commands and Options.
+* Programs and Arguments::
+* HTML HTTP and CGI:: Generate pages and serve WWW sites
* Printing Scheme:: Nicely
* Time and Date::
* Vector Graphics::
+* Schmooz:: Documentation markup for Scheme programs
@end menu
@@ -2535,8 +2537,8 @@ when @var{tk} is parsed:
The rules @var{rule1} @dots{} augment and, in case of conflict, override
rules currently in effect.
@item
-One expression is parsed with binding-power @var{lbp}. If instead a delimiter
-is encountered, a warning is issued.
+One expression is parsed with binding-power @var{lbp}. If instead a
+delimiter is encountered, a warning is issued.
@item
If @var{sop} is a procedure, it is applied to the list of @var{left} and
the parsed expression; the resulting value is incorporated into the
@@ -2606,7 +2608,7 @@ is parsed:
The rules @var{rule1} @dots{} augment and, in case of conflict, override
rules currently in effect.
@item
-Characters are read untile and end-of-file or a sequence of characters
+Characters are read until and end-of-file or a sequence of characters
is read which matches the @emph{string} @var{match}.
@item
If @var{stp} is a procedure, it is called with the string of all that
@@ -2678,440 +2680,9 @@ The ruleset in effect before @var{tk} was parsed is restored;
@code{(require 'format)}
@ftindex format
-@menu
-* Format Interface::
-* Format Specification::
-@end menu
-
-@node Format Interface, Format Specification, Format, Format
-@subsection Format Interface
-
-@defun format destination format-string . arguments
-An almost complete implementation of Common LISP format description
-according to the CL reference book @cite{Common LISP} from Guy L.
-Steele, Digital Press. Backward compatible to most of the available
-Scheme format implementations.
-
-Returns @code{#t}, @code{#f} or a string; has side effect of printing
-according to @var{format-string}. If @var{destination} is @code{#t},
-the output is to the current output port and @code{#t} is returned. If
-@var{destination} is @code{#f}, a formatted string is returned as the
-result of the call. NEW: If @var{destination} is a string,
-@var{destination} is regarded as the format string; @var{format-string} is
-then the first argument and the output is returned as a string. If
-@var{destination} is a number, the output is to the current error port
-if available by the implementation. Otherwise @var{destination} must be
-an output port and @code{#t} is returned.@refill
-
-@var{format-string} must be a string. In case of a formatting error
-format returns @code{#f} and prints a message on the current output or
-error port. Characters are output as if the string were output by the
-@code{display} function with the exception of those prefixed by a tilde
-(~). For a detailed description of the @var{format-string} syntax
-please consult a Common LISP format reference manual. For a test suite
-to verify this format implementation load @file{formatst.scm}. Please
-send bug reports to @code{lutzeb@@cs.tu-berlin.de}.
-
-Note: @code{format} is not reentrant, i.e. only one @code{format}-call
-may be executed at a time.
-
-@end defun
-
-@node Format Specification, , Format Interface, Format
-@subsection Format Specification (Format version 3.0)
-
-Please consult a Common LISP format reference manual for a detailed
-description of the format string syntax. For a demonstration of the
-implemented directives see @file{formatst.scm}.@refill
-
-This implementation supports directive parameters and modifiers
-(@code{:} and @code{@@} characters). Multiple parameters must be
-separated by a comma (@code{,}). Parameters can be numerical parameters
-(positive or negative), character parameters (prefixed by a quote
-character (@code{'}), variable parameters (@code{v}), number of rest
-arguments parameter (@code{#}), empty and default parameters. Directive
-characters are case independent. The general form of a directive
-is:@refill
-
-@noindent
-@var{directive} ::= ~@{@var{directive-parameter},@}[:][@@]@var{directive-character}
-
-@noindent
-@var{directive-parameter} ::= [ [-|+]@{0-9@}+ | '@var{character} | v | # ]
-
-
-@subsubsection Implemented CL Format Control Directives
+@include fmtdoc.txi
-Documentation syntax: Uppercase characters represent the corresponding
-control directive characters. Lowercase characters represent control
-directive parameter descriptions.
-
-@table @asis
-@item @code{~A}
-Any (print as @code{display} does).
-@table @asis
-@item @code{~@@A}
-left pad.
-@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}A}
-full padding.
-@end table
-@item @code{~S}
-S-expression (print as @code{write} does).
-@table @asis
-@item @code{~@@S}
-left pad.
-@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}S}
-full padding.
-@end table
-@item @code{~D}
-Decimal.
-@table @asis
-@item @code{~@@D}
-print number sign always.
-@item @code{~:D}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}D}
-padding.
-@end table
-@item @code{~X}
-Hexadecimal.
-@table @asis
-@item @code{~@@X}
-print number sign always.
-@item @code{~:X}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}X}
-padding.
-@end table
-@item @code{~O}
-Octal.
-@table @asis
-@item @code{~@@O}
-print number sign always.
-@item @code{~:O}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}O}
-padding.
-@end table
-@item @code{~B}
-Binary.
-@table @asis
-@item @code{~@@B}
-print number sign always.
-@item @code{~:B}
-print comma separated.
-@item @code{~@var{mincol},@var{padchar},@var{commachar}B}
-padding.
-@end table
-@item @code{~@var{n}R}
-Radix @var{n}.
-@table @asis
-@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar}R}
-padding.
-@end table
-@item @code{~@@R}
-print a number as a Roman numeral.
-@item @code{~:R}
-print a number as an ordinal English number.
-@item @code{~:@@R}
-print a number as a cardinal English number.
-@item @code{~P}
-Plural.
-@table @asis
-@item @code{~@@P}
-prints @code{y} and @code{ies}.
-@item @code{~:P}
-as @code{~P but jumps 1 argument backward.}
-@item @code{~:@@P}
-as @code{~@@P but jumps 1 argument backward.}
-@end table
-@item @code{~C}
-Character.
-@table @asis
-@item @code{~@@C}
-prints a character as the reader can understand it (i.e. @code{#\} prefixing).
-@item @code{~:C}
-prints a character as emacs does (eg. @code{^C} for ASCII 03).
-@end table
-@item @code{~F}
-Fixed-format floating-point (prints a flonum like @var{mmm.nnn}).
-@table @asis
-@item @code{~@var{width},@var{digits},@var{scale},@var{overflowchar},@var{padchar}F}
-@item @code{~@@F}
-If the number is positive a plus sign is printed.
-@end table
-@item @code{~E}
-Exponential floating-point (prints a flonum like @var{mmm.nnn}@code{E}@var{ee}).
-@table @asis
-@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E}
-@item @code{~@@E}
-If the number is positive a plus sign is printed.
-@end table
-@item @code{~G}
-General floating-point (prints a flonum either fixed or exponential).
-@table @asis
-@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G}
-@item @code{~@@G}
-If the number is positive a plus sign is printed.
-@end table
-@item @code{~$}
-Dollars floating-point (prints a flonum in fixed with signs separated).
-@table @asis
-@item @code{~@var{digits},@var{scale},@var{width},@var{padchar}$}
-@item @code{~@@$}
-If the number is positive a plus sign is printed.
-@item @code{~:@@$}
-A sign is always printed and appears before the padding.
-@item @code{~:$}
-The sign appears before the padding.
-@end table
-@item @code{~%}
-Newline.
-@table @asis
-@item @code{~@var{n}%}
-print @var{n} newlines.
-@end table
-@item @code{~&}
-print newline if not at the beginning of the output line.
-@table @asis
-@item @code{~@var{n}&}
-prints @code{~&} and then @var{n-1} newlines.
-@end table
-@item @code{~|}
-Page Separator.
-@table @asis
-@item @code{~@var{n}|}
-print @var{n} page separators.
-@end table
-@item @code{~~}
-Tilde.
-@table @asis
-@item @code{~@var{n}~}
-print @var{n} tildes.
-@end table
-@item @code{~}<newline>
-Continuation Line.
-@table @asis
-@item @code{~:}<newline>
-newline is ignored, white space left.
-@item @code{~@@}<newline>
-newline is left, white space ignored.
-@end table
-@item @code{~T}
-Tabulation.
-@table @asis
-@item @code{~@@T}
-relative tabulation.
-@item @code{~@var{colnum,colinc}T}
-full tabulation.
-@end table
-@item @code{~?}
-Indirection (expects indirect arguments as a list).
-@table @asis
-@item @code{~@@?}
-extracts indirect arguments from format arguments.
-@end table
-@item @code{~(@var{str}~)}
-Case conversion (converts by @code{string-downcase}).
-@table @asis
-@item @code{~:(@var{str}~)}
-converts by @code{string-capitalize}.
-@item @code{~@@(@var{str}~)}
-converts by @code{string-capitalize-first}.
-@item @code{~:@@(@var{str}~)}
-converts by @code{string-upcase}.
-@end table
-@item @code{~*}
-Argument Jumping (jumps 1 argument forward).
-@table @asis
-@item @code{~@var{n}*}
-jumps @var{n} arguments forward.
-@item @code{~:*}
-jumps 1 argument backward.
-@item @code{~@var{n}:*}
-jumps @var{n} arguments backward.
-@item @code{~@@*}
-jumps to the 0th argument.
-@item @code{~@var{n}@@*}
-jumps to the @var{n}th argument (beginning from 0)
-@end table
-@item @code{~[@var{str0}~;@var{str1}~;...~;@var{strn}~]}
-Conditional Expression (numerical clause conditional).
-@table @asis
-@item @code{~@var{n}[}
-take argument from @var{n}.
-@item @code{~@@[}
-true test conditional.
-@item @code{~:[}
-if-else-then conditional.
-@item @code{~;}
-clause separator.
-@item @code{~:;}
-default clause follows.
-@end table
-@item @code{~@{@var{str}~@}}
-Iteration (args come from the next argument (a list)).
-@table @asis
-@item @code{~@var{n}@{}
-at most @var{n} iterations.
-@item @code{~:@{}
-args from next arg (a list of lists).
-@item @code{~@@@{}
-args from the rest of arguments.
-@item @code{~:@@@{}
-args from the rest args (lists).
-@end table
-@item @code{~^}
-Up and out.
-@table @asis
-@item @code{~@var{n}^}
-aborts if @var{n} = 0
-@item @code{~@var{n},@var{m}^}
-aborts if @var{n} = @var{m}
-@item @code{~@var{n},@var{m},@var{k}^}
-aborts if @var{n} <= @var{m} <= @var{k}
-@end table
-@end table
-
-
-@subsubsection Not Implemented CL Format Control Directives
-
-@table @asis
-@item @code{~:A}
-print @code{#f} as an empty list (see below).
-@item @code{~:S}
-print @code{#f} as an empty list (see below).
-@item @code{~<~>}
-Justification.
-@item @code{~:^}
-(sorry I don't understand its semantics completely)
-@end table
-
-
-@subsubsection Extended, Replaced and Additional Control Directives
-
-@table @asis
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}D}
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}X}
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}O}
-@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}B}
-@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar},@var{commawidth}R}
-@var{commawidth} is the number of characters between two comma characters.
-@end table
-
-@table @asis
-@item @code{~I}
-print a R4RS complex number as @code{~F~@@Fi} with passed parameters for
-@code{~F}.
-@item @code{~Y}
-Pretty print formatting of an argument for scheme code lists.
-@item @code{~K}
-Same as @code{~?.}
-@item @code{~!}
-Flushes the output if format @var{destination} is a port.
-@item @code{~_}
-Print a @code{#\space} character
-@table @asis
-@item @code{~@var{n}_}
-print @var{n} @code{#\space} characters.
-@end table
-@item @code{~/}
-Print a @code{#\tab} character
-@table @asis
-@item @code{~@var{n}/}
-print @var{n} @code{#\tab} characters.
-@end table
-@item @code{~@var{n}C}
-Takes @var{n} as an integer representation for a character. No arguments
-are consumed. @var{n} is converted to a character by
-@code{integer->char}. @var{n} must be a positive decimal number.@refill
-@item @code{~:S}
-Print out readproof. Prints out internal objects represented as
-@code{#<...>} as strings @code{"#<...>"} so that the format output can always
-be processed by @code{read}.
-@refill
-@item @code{~:A}
-Print out readproof. Prints out internal objects represented as
-@code{#<...>} as strings @code{"#<...>"} so that the format output can always
-be processed by @code{read}.
-@item @code{~Q}
-Prints information and a copyright notice on the format implementation.
-@table @asis
-@item @code{~:Q}
-prints format version.
-@end table
-@refill
-@item @code{~F, ~E, ~G, ~$}
-may also print number strings, i.e. passing a number as a string and
-format it accordingly.
-@end table
-
-@subsubsection Configuration Variables
-
-Format has some configuration variables at the beginning of
-@file{format.scm} to suit the systems and users needs. There should be
-no modification necessary for the configuration that comes with SLIB.
-If modification is desired the variable should be set after the format
-code is loaded. Format detects automatically if the running scheme
-system implements floating point numbers and complex numbers.
-
-@table @asis
-
-@item @var{format:symbol-case-conv}
-Symbols are converted by @code{symbol->string} so the case type of the
-printed symbols is implementation dependent.
-@code{format:symbol-case-conv} is a one arg closure which is either
-@code{#f} (no conversion), @code{string-upcase}, @code{string-downcase}
-or @code{string-capitalize}. (default @code{#f})
-
-@item @var{format:iobj-case-conv}
-As @var{format:symbol-case-conv} but applies for the representation of
-implementation internal objects. (default @code{#f})
-
-@item @var{format:expch}
-The character prefixing the exponent value in @code{~E} printing. (default
-@code{#\E})
-
-@end table
-
-@subsubsection Compatibility With Other Format Implementations
-
-@table @asis
-@item SLIB format 2.x:
-See @file{format.doc}.
-
-@item SLIB format 1.4:
-Downward compatible except for padding support and @code{~A}, @code{~S},
-@code{~P}, @code{~X} uppercase printing. SLIB format 1.4 uses C-style
-@code{printf} padding support which is completely replaced by the CL
-@code{format} padding style.
-
-@item MIT C-Scheme 7.1:
-Downward compatible except for @code{~}, which is not documented
-(ignores all characters inside the format string up to a newline
-character). (7.1 implements @code{~a}, @code{~s},
-~@var{newline}, @code{~~}, @code{~%}, numerical and variable
-parameters and @code{:/@@} modifiers in the CL sense).@refill
-
-@item Elk 1.5/2.0:
-Downward compatible except for @code{~A} and @code{~S} which print in
-uppercase. (Elk implements @code{~a}, @code{~s}, @code{~~}, and
-@code{~%} (no directive parameters or modifiers)).@refill
-
-@item Scheme->C 01nov91:
-Downward compatible except for an optional destination parameter: S2C
-accepts a format call without a destination which returns a formatted
-string. This is equivalent to a #f destination in S2C. (S2C implements
-@code{~a}, @code{~s}, @code{~c}, @code{~%}, and @code{~~} (no directive
-parameters or modifiers)).@refill
-
-@end table
-
-This implementation of format is solely useful in the SLIB context
-because it requires other components provided by SLIB.@refill
-
-
-@node Standard Formatted I/O, Program Arguments, Format, Textual Conversion Packages
+@node Standard Formatted I/O, Programs and Arguments, Format, Textual Conversion Packages
@section Standard Formatted I/O
@menu
@@ -3147,6 +2718,8 @@ Defined to be @code{(current-error-port)}.
@deffn Procedure printf format arg1 @dots{}
@deffnx Procedure fprintf port format arg1 @dots{}
@deffnx Procedure sprintf str format arg1 @dots{}
+@deffnx Procedure sprintf #f format arg1 @dots{}
+@deffnx Procedure sprintf k format arg1 @dots{}
Each function converts, formats, and outputs its @var{arg1} @dots{}
arguments according to the control string @var{format} argument and
@@ -3157,10 +2730,11 @@ returns the number of characters output.
@code{string-set!}s locations of the non-constant string argument
@var{str} to the output characters.
-@quotation
-@emph{Note:} sprintf should be changed to a macro so a @code{substring}
-expression could be used for the @var{str} argument.
-@end quotation
+Two extensions of @code{sprintf} return new strings. If the first
+argument is @code{#f}, then the returned string's length is as many
+characters as specified by the @var{format} and data; if the first
+argument is a non-negative integer @var{k}, then the length of the
+returned string is also bounded by @var{k}.
The string @var{format} contains plain characters which are copied to
the output stream, and conversion specifications, each of which results
@@ -3300,7 +2874,6 @@ digits @samp{0123456789ABCDEF}.
@end table
@subsubsection Inexact Conversions
-@emph{Note:} Inexact conversions are not supported yet.
@table @asis
@item @samp{f}
@@ -3313,9 +2886,10 @@ between mantissa and exponont.
@item @samp{g}, @samp{G}
Print a floating-point number in either normal or exponential notation,
-whichever is more appropriate for its magnitude. @samp{%g} prints
-@samp{e} between mantissa and exponont. @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.
@end table
@subsubsection Other Conversions
@@ -3528,17 +3102,19 @@ left unread in the input stream.
@end defmac
-@node Program Arguments, Printing Scheme, Standard Formatted I/O, Textual Conversion Packages
-@section Program Arguments
+@node Programs and Arguments, HTML HTTP and CGI, Standard Formatted I/O, Textual Conversion Packages
+@section Program and Arguments
@menu
* Getopt:: Command Line option parsing
* Command Line:: A command line reader for Scheme shells
* Parameter lists:: 'parameters
+* Getopt Parameter lists:: 'getopt-parameters
+* Filenames:: 'glob or 'filename
* Batch:: 'batch
@end menu
-@node Getopt, Command Line, Program Arguments, Program Arguments
+@node Getopt, Command Line, Programs and Arguments, Programs and Arguments
@subsection Getopt
@code{(require 'getopt)}
@@ -3614,15 +3190,16 @@ options; @code{#f} is returned, and @code{"--"} is skipped.
RETURN VALUE
@code{getopt} returns the next option character specified on the command
-line. A colon @code{#\:} is returned if @code{getopt} detects a missing argument
-and the first character of @var{optstring} was a colon @code{#\:}.
+line. A colon @code{#\:} is returned if @code{getopt} detects a missing
+argument and the first character of @var{optstring} was a colon
+@code{#\:}.
-A question-mark @code{#\?} is returned if @code{getopt} encounters an option
-character not in @var{optstring} or detects a missing argument and the first
-character of @var{optstring} was not a colon @code{#\:}.
+A question-mark @code{#\?} is returned if @code{getopt} encounters an
+option character not in @var{optstring} or detects a missing argument
+and the first character of @var{optstring} was not a colon @code{#\:}.
-Otherwise, @code{getopt} returns @code{#f} when all command line options have been
-parsed.
+Otherwise, @code{getopt} returns @code{#f} when all command line options
+have been parsed.
Example:
@lisp
@@ -3693,7 +3270,7 @@ errors.
@end example
@end defun
-@node Command Line, Parameter lists, Getopt, Program Arguments
+@node Command Line, Parameter lists, Getopt, Programs and Arguments
@subsection Command Line
@code{(require 'read-command)}
@@ -3773,7 +3350,7 @@ can begin an object or comment, then an end of file object is returned.
-@node Parameter lists, Batch, Command Line, Program Arguments
+@node Parameter lists, Getopt Parameter lists, Command Line, Programs and Arguments
@subsection Parameter lists
@code{(require 'parameters)}
@@ -3873,6 +3450,12 @@ integers specify in which argument position the corresponding parameter
should appear.
@end deffn
+
+@node Getopt Parameter lists, Filenames, Parameter lists, Programs and Arguments
+@subsection Getopt Parameter lists
+
+@code{(require 'getopt-parameters)}
+
@deffn Function getopt->parameter-list argc argv optnames arities types aliases
Returns @var{argv} converted to a parameter-list. @var{optnames} are
the parameter-names. @var{aliases} is a list of lists of strings and
@@ -3936,8 +3519,56 @@ Usage: cmd [OPTION ARGUMENT ...] ...
ERROR: getopt->parameter-list "unrecognized option" "-?"
@end example
+@node Filenames, Batch, Getopt Parameter lists, Programs and Arguments
+@subsection Filenames
+
+@code{(require 'filename)} or @code{(require 'glob)}
+
+@defun filename:match?? pattern
+@defunx filename:match-ci?? pattern
+Returns a predicate which returns true if its string argument matches
+(the string) @var{pattern}, false otherwise. Filename matching is like
+@cindex glob
+@dfn{glob} expansion described the bash manpage, except that names
+beginning with @samp{.} are matched and @samp{/} characters are not
+treated specially.
+
+These functions interpret the following characters specially in
+@var{pattern} strings:
+@table @samp
+@item *
+Matches any string, including the null string.
+@item ?
+Matches any single character.
+@item [@dots{}]
+Matches any one of the enclosed characters. A pair of characters
+separated by a minus sign (-) denotes a range; any character lexically
+between those two characters, inclusive, is matched. If the first
+character following the @samp{[} is a @samp{!} or a @samp{^} then any
+character not enclosed is matched. A @samp{-} or @samp{]} may be
+matched by including it as the first or last character in the set.
+@end table
+
+@example
+@end example
+
+
+@end defun
+
+@defun replace-suffix str old new
+@var{str} can be a string or a list of strings. Returns a new string
+(or strings) similar to @code{str} but with the suffix string @var{old}
+removed and the suffix string @var{new} appended. If the end of
+@var{str} does not match @var{old}, an error is signaled.
+
+@example
+(replace-suffix "/usr/local/lib/slib/batch.scm" ".scm" ".c")
+@result{} "/usr/local/lib/slib/batch.c"
+@end example
+@end defun
+
-@node Batch, , Parameter lists, Program Arguments
+@node Batch, , Filenames, Programs and Arguments
@subsection Batch
@code{(require 'batch)}
@@ -4081,18 +3712,6 @@ can be used to derive a filename moved locally from elsewhere.
@end example
@end defun
-@defun replace-suffix str old new
-@var{str} can be a string or a list of strings. Returns a new string
-(or strings) similar to @code{str} but with the suffix string @var{old}
-removed and the suffix string @var{new} appended. If the end of
-@var{str} does not match @var{old}, an error is signaled.
-
-@example
-(replace-suffix "/usr/local/lib/slib/batch.scm" ".scm" ".c")
-@result{} "/usr/local/lib/slib/batch.c"
-@end example
-@end defun
-
@defun string-join joiner string1 @dots{}
Returns a new string consisting of all the strings @var{string1} @dots{}
in order appended together with the string @var{joiner} between each
@@ -4129,6 +3748,8 @@ Here is an example of the use of most of batch's procedures:
@ftindex parameters
(require 'batch)
@ftindex batch
+(require 'glob)
+@ftindex glob
(define batch (create-database #f 'alist-table))
(batch:initialize! batch)
@@ -4199,7 +3820,13 @@ hello world
@end example
-@node Printing Scheme, Time and Date, Program Arguments, Textual Conversion Packages
+@node HTML HTTP and CGI, Printing Scheme, Programs and Arguments, Textual Conversion Packages
+@section HTML Forms
+
+@include htmlform.txi
+
+
+@node Printing Scheme, Time and Date, HTML HTTP and CGI, Textual Conversion Packages
@section Printing Scheme
@menu
@@ -4264,11 +3891,7 @@ where
@code{(require 'object->string)}
@ftindex object->string
-@defun object->string obj
-Returns the textual representation of @var{obj} as a string.
-@end defun
-
-
+@include obj2str.txi
@node Pretty-Print, , Object-To-String, Printing Scheme
@@ -4484,7 +4107,7 @@ match the arguments to @code{encode-universal-time}.
@end defun
-@node Vector Graphics, , Time and Date, Textual Conversion Packages
+@node Vector Graphics, Schmooz, Time and Date, Textual Conversion Packages
@section Vector Graphics
@menu
@@ -4560,6 +4183,113 @@ be mixed with regular text and ANSI or other terminal control sequences.
@deffn Procedure tek41:encode-int number
@end deffn
+@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.
+
@node Mathematical Packages, Database Packages, Textual Conversion Packages, Top
@chapter Mathematical Packages
@@ -4588,7 +4318,10 @@ The bit-twiddling functions are made available through the use of the
@code{logical} package. @code{logical} is loaded by inserting
@code{(require 'logical)} before the code that uses these
@ftindex logical
-functions.@refill
+functions. These functions behave as though operating on integers
+in two's-complement representation.@refill
+
+@subheading Bitwise Operations
@defun logand n1 n1
Returns the integer which is the bit-wise AND of the two integer
@@ -4635,6 +4368,13 @@ Example:
@end lisp
@end defun
+@defun bitwise-if mask n0 n1
+Returns an integer composed of some bits from integer @var{n0} and some
+from integer @var{n1}. A bit of the result is taken from @var{n0} if the
+corresponding bit of integer @var{mask} is 1 and from @var{n1} if that bit
+of @var{mask} is 0.
+@end defun
+
@defun logtest j k
@example
(logtest j k) @equiv{} (not (zero? (logand j k)))
@@ -4644,6 +4384,26 @@ Example:
@end example
@end defun
+@defun logcount n
+Returns the number of bits in integer @var{n}. If integer is positive,
+the 1-bits in its binary representation are counted. If negative, the
+0-bits in its two's-complement binary representation are counted. If 0,
+0 is returned.
+
+Example:
+@lisp
+(logcount #b10101010)
+ @result{} 4
+(logcount 0)
+ @result{} 0
+(logcount -2)
+ @result{} 1
+@end lisp
+@end defun
+
+
+@subheading Bit Within Word
+
@defun logbit? index j
@example
(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
@@ -4656,6 +4416,53 @@ Example:
@end example
@end defun
+@defun copy-bit index from bit
+Returns an integer the same as @var{from} except in the @var{index}th bit,
+which is 1 if @var{bit} is @code{#t} and 0 if @var{bit} is @code{#f}.
+
+Example:
+@example
+(number->string (copy-bit 0 0 #t) 2) @result{} "1"
+(number->string (copy-bit 2 0 #t) 2) @result{} "100"
+(number->string (copy-bit 2 #b1111 #f) 2) @result{} "1011"
+@end example
+@end defun
+
+@subheading Fields of Bits
+
+@defun bit-field n start end
+@findex bit-extract
+Returns the integer composed of the @var{start} (inclusive) through
+@var{end} (exclusive) bits of @var{n}. The @var{start}th bit becomes
+the 0-th bit in the result.
+
+This function was called @code{bit-extract} in previous versions of SLIB.
+@refill
+
+Example:
+@lisp
+(number->string (bit-field #b1101101010 0 4) 2)
+ @result{} "1010"
+(number->string (bit-field #b1101101010 4 9) 2)
+ @result{} "10110"
+@end lisp
+@end defun
+
+@defun copy-bit-field to start end from
+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
+
+Example:
+@example
+(number->string (copy-bit-field #b1101101010 0 4 0) 2)
+ @result{} "1101100000"
+(number->string (copy-bit-field #b1101101010 0 4 -1) 2)
+ @result{} "1101101111"
+@end example
+@end defun
+
@defun ash int count
Returns an integer equivalent to
@code{(inexact->exact (floor (* @var{int} (expt 2 @var{count}))))}.@refill
@@ -4669,23 +4476,6 @@ Example:
@end lisp
@end defun
-@defun logcount n
-Returns the number of bits in integer @var{n}. If integer is positive,
-the 1-bits in its binary representation are counted. If negative, the
-0-bits in its two's-complement binary representation are counted. If 0,
-0 is returned.
-
-Example:
-@lisp
-(logcount #b10101010)
- @result{} 4
-(logcount 0)
- @result{} 0
-(logcount -2)
- @result{} 1
-@end lisp
-@end defun
-
@defun integer-length n
Returns the number of bits neccessary to represent @var{n}.
@@ -4712,21 +4502,6 @@ Example:
@end lisp
@end defun
-@defun bit-extract n start end
-Returns the integer composed of the @var{start} (inclusive) through
-@var{end} (exclusive) bits of @var{n}. The @var{start}th bit becomes
-the 0-th bit in the result.@refill
-
-Example:
-@lisp
-(number->string (bit-extract #b1101101010 0 4) 2)
- @result{} "1010"
-(number->string (bit-extract #b1101101010 4 9) 2)
- @result{} "10110"
-@end lisp
-@end defun
-
-
@node Modular Arithmetic, Prime Testing and Generation, Bit-Twiddling, Mathematical Packages
@section Modular Arithmetic
@@ -4992,6 +4767,22 @@ done to test a number for primality.
@code{(require 'random)}
@ftindex random
+@cindex RNG
+@cindex PRNG
+A pseudo-random number generator is only as good as the tests it passes.
+George Marsaglia of Florida State University developed a battery of
+tests named @dfn{DIEHARD} (@url{http://stat.fsu.edu/~geo/diehard.html}).
+@file{diehard.c} has a bug which the patch
+@url{ftp://swissnet.ai.mit.edu/pub/users/jaffer/diehard.c.pat} corrects.
+
+SLIB's new PRNG generates 8 bits at a time. With the degenerate seed
+@samp{0}, the numbers generated pass DIEHARD; but when bits are combined
+from sequential bytes, tests fail. With the seed
+@samp{http://swissnet.ai.mit.edu/~jaffer/SLIB.html}, all of those tests
+pass.
+
+It would be better if there were no bad seeds. For now, use seeds of at
+least 30 bytes.
@deffn Procedure random n
@deffnx Procedure random n state
@@ -5022,7 +4813,7 @@ variable @code{*random-state*} and as a second argument to
returned. Otherwise a copy of @code{*random-state*} is returned.@refill
@end deffn
-If inexact numbers are support by the Scheme implementation,
+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.@refill
@@ -5808,6 +5599,8 @@ from any @ref{Base Table} implementation.
* Catalog Representation::
* Unresolved Issues::
* Database Utilities:: 'database-utilities
+* Database Reports::
+* Database Browser:: 'database-browse
@end menu
@node Motivations, Creating and Opening Relational Databases, Relational Database, Relational Database
@@ -5837,7 +5630,7 @@ intermediate files with a text editor to using the interactive program
in order to do operations (such as global changes) not forseen by the
program's author.
-In order to address this need, the concientous software engineer may
+In order to address this need, the conscientious software engineer may
even provide a scripting language to allow users to make repetitive
database changes. Users will grumble that they need to read a large
manual and learn yet another programming language (even if it
@@ -6411,7 +6204,7 @@ part of transactions also non-reentrant? If so, perhaps suspending
transaction capture for the duration of locks would solve this problem.
@end table
-@node Database Utilities, , Unresolved Issues, Relational Database
+@node Database Utilities, Database Reports, Unresolved Issues, Relational Database
@subsection Database Utilities
@code{(require 'database-utilities)}
@@ -6654,9 +6447,8 @@ arguments from a @code{getopt} style argument list (@pxref{Getopt}).
(define (cmd . opts)
(fluid-let ((*optind* 1))
(printf "%-34s @result{} "
- (call-with-output-string (lambda (pt) (write (cons 'cmd opts) pt)))
- ;;(apply string-append (map (lambda (x) (string-append x " ")) opts))
- )
+ (call-with-output-string
+ (lambda (pt) (write (cons 'cmd opts) pt))))
(set! opts (cons "cmd" opts))
(force-output)
(dbutil:serve-command-line
@@ -6788,6 +6580,85 @@ key field table, a foriegn-key domain will be created for it.
@end deffn
+@noindent
+The following example shows a new database with the name of
+@file{foo.db} being created with tables describing processor families
+and processor/os/compiler combinations.
+
+@noindent
+The database command @code{define-tables} is defined to call
+@code{define-tables} with its arguments. The database is also
+configured to print @samp{Welcome} when the database is opened. The
+database is then closed and reopened.
+
+@example
+(require 'database-utilities)
+@ftindex database-utilities
+(define my-rdb (create-database "foo.db" 'alist-table))
+
+(define-tables my-rdb
+ '(*commands*
+ ((name symbol))
+ ((parameters parameter-list)
+ (procedure expression)
+ (documentation string))
+ ((define-tables
+ no-parameters
+ no-parameter-names
+ (lambda (rdb) (lambda specs (apply define-tables rdb specs)))
+ "Create or Augment tables from list of specs")
+ (*initialize*
+ no-parameters
+ no-parameter-names
+ (lambda (rdb) (display "Welcome") (newline) rdb)
+ "Print Welcome"))))
+
+((my-rdb 'define-tables)
+ '(processor-family
+ ((family atom))
+ ((also-ran processor-family))
+ ((m68000 #f)
+ (m68030 m68000)
+ (i386 8086)
+ (8086 #f)
+ (powerpc #f)))
+
+ '(platform
+ ((name symbol))
+ ((processor processor-family)
+ (os symbol)
+ (compiler symbol))
+ ((aix powerpc aix -)
+ (amiga-dice-c m68000 amiga dice-c)
+ (amiga-aztec m68000 amiga aztec)
+ (amiga-sas/c-5.10 m68000 amiga sas/c)
+ (atari-st-gcc m68000 atari gcc)
+ (atari-st-turbo-c m68000 atari turbo-c)
+ (borland-c-3.1 8086 ms-dos borland-c)
+ (djgpp i386 ms-dos gcc)
+ (linux i386 linux gcc)
+ (microsoft-c 8086 ms-dos microsoft-c)
+ (os/2-emx i386 os/2 gcc)
+ (turbo-c-2 8086 ms-dos turbo-c)
+ (watcom-9.0 i386 ms-dos watcom))))
+
+((my-rdb 'close-database))
+
+(set! my-rdb (open-database "foo.db" 'alist-table))
+@print{}
+Welcome
+@end example
+
+@node Database Reports, Database Browser, Database Utilities, Relational Database
+@subsection Database Reports
+
+@noindent
+Code for generating database reports is in @file{report.scm}. After
+writing it using @code{format}, I discovered that Common-Lisp
+@code{format} is not useable for this application because there is no
+mechanismm for truncating fields. @file{report.scm} needs to be
+rewritten using @code{printf}.
+
@deffn Procedure create-report rdb destination report-name table
@deffnx Procedure create-report rdb destination report-name
The symbol @var{report-name} must be primary key in the table named
@@ -6859,75 +6730,43 @@ This entire process repeats until all the rows are output.
@end itemize
@end deffn
-@noindent
-The following example shows a new database with the name of
-@file{foo.db} being created with tables describing processor families
-and processor/os/compiler combinations.
-@noindent
-The database command @code{define-tables} is defined to call
-@code{define-tables} with its arguments. The database is also
-configured to print @samp{Welcome} when the database is opened. The
-database is then closed and reopened.
+@node Database Browser, , Database Reports, Relational Database
+@subsection Database Browser
-@example
-(require 'database-utilities)
-@ftindex database-utilities
-(define my-rdb (create-database "foo.db" 'alist-table))
+(require 'database-browse)
-(define-tables my-rdb
- '(*commands*
- ((name symbol))
- ((parameters parameter-list)
- (procedure expression)
- (documentation string))
- ((define-tables
- no-parameters
- no-parameter-names
- (lambda (rdb) (lambda specs (apply define-tables rdb specs)))
- "Create or Augment tables from list of specs")
- (*initialize*
- no-parameters
- no-parameter-names
- (lambda (rdb) (display "Welcome") (newline) rdb)
- "Print Welcome"))))
+@deffn Procedure browse database
-((my-rdb 'define-tables)
- '(processor-family
- ((family atom))
- ((also-ran processor-family))
- ((m68000 #f)
- (m68030 m68000)
- (i386 8086)
- (8086 #f)
- (powerpc #f)))
+Prints the names of all the tables in @var{database} and sets browse's
+default to @var{database}.
- '(platform
- ((name symbol))
- ((processor processor-family)
- (os symbol)
- (compiler symbol))
- ((aix powerpc aix -)
- (amiga-dice-c m68000 amiga dice-c)
- (amiga-aztec m68000 amiga aztec)
- (amiga-sas/c-5.10 m68000 amiga sas/c)
- (atari-st-gcc m68000 atari gcc)
- (atari-st-turbo-c m68000 atari turbo-c)
- (borland-c-3.1 8086 ms-dos borland-c)
- (djgpp i386 ms-dos gcc)
- (linux i386 linux gcc)
- (microsoft-c 8086 ms-dos microsoft-c)
- (os/2-emx i386 os/2 gcc)
- (turbo-c-2 8086 ms-dos turbo-c)
- (watcom-9.0 i386 ms-dos watcom))))
+@deffnx Procedure browse
-((my-rdb 'close-database))
+Prints the names of all the tables in the default database.
-(set! my-rdb (open-database "foo.db" 'alist-table))
-@print{}
-Welcome
-@end example
+@deffnx Procedure browse table-name
+
+For each record of the table named by the symbol @var{table-name},
+prints a line composed of all the field values.
+
+@deffnx Procedure browse pathname
+Opens the database named by the string @var{pathname}, prints the names
+of all its tables, and sets browse's default to the database.
+
+@deffnx Procedure browse database table-name
+
+Sets browse's default to @var{database} and prints the records of the
+table named by the symbol @var{table-name}.
+
+@deffnx Procedure browse pathname table-name
+
+Opens the database named by the string @var{pathname} and sets browse's
+default to it; @code{browse} prints the records of the table named by
+the symbol @var{table-name}.
+
+@end deffn
@node Weight-Balanced Trees, , Relational Database, Database Packages
@section Weight-Balanced Trees
@@ -7003,14 +6842,13 @@ association is a member of the set. Typically a value such as
Many operations can be viewed as computing a result that, depending on
whether the tree arguments are thought of as sets or maps, is known by
-two different names.
-An example is @code{wt-tree/member?}, which, when
-regarding the tree argument as a set, computes the set membership operation, but,
-when regarding the tree as a discrete map, @code{wt-tree/member?} is the
-predicate testing if the map is defined at an element in its domain.
-Most names in this package have been chosen based on interpreting the
-trees as sets, hence the name @code{wt-tree/member?} rather than
-@code{wt-tree/defined-at?}.
+two different names. An example is @code{wt-tree/member?}, which, when
+regarding the tree argument as a set, computes the set membership
+operation, but, when regarding the tree as a discrete map,
+@code{wt-tree/member?} is the predicate testing if the map is defined at
+an element in its domain. Most names in this package have been chosen
+based on interpreting the trees as sets, hence the name
+@code{wt-tree/member?} rather than @code{wt-tree/defined-at?}.
@cindex run-time-loadable option
@@ -7041,13 +6879,13 @@ Binary trees require there to be a total order on the keys used to
arrange the elements in the tree. Weight balanced trees are organized
by @emph{types}, where the type is an object encapsulating the ordering
relation. Creating a tree is a two-stage process. First a tree type
-must be created from the predicate which gives the ordering. The tree type
-is then used for making trees, either empty or singleton trees or trees
-from other aggregate structures like association lists. Once created, a
-tree `knows' its type and the type is used to test compatibility between
-trees in operations taking two trees. Usually a small number of tree
-types are created at the beginning of a program and used many times
-throughout the program's execution.
+must be created from the predicate which gives the ordering. The tree
+type is then used for making trees, either empty or singleton trees or
+trees from other aggregate structures like association lists. Once
+created, a tree `knows' its type and the type is used to test
+compatibility between trees in operations taking two trees. Usually a
+small number of tree types are created at the beginning of a program and
+used many times throughout the program's execution.
@deffn {procedure+} make-wt-tree-type key<?
This procedure creates and returns a new tree type based on the ordering
@@ -7068,11 +6906,10 @@ Two key values are assumed to be equal if neither is less than the other
by @var{key<?}.
Each call to @code{make-wt-tree-type} returns a distinct value, and
-trees are only compatible if their tree types are @code{eq?}.
-A consequence is
-that trees that are intended to be used in binary tree operations must all be
-created with a tree type originating from the same call to
-@code{make-wt-tree-type}.
+trees are only compatible if their tree types are @code{eq?}. A
+consequence is that trees that are intended to be used in binary tree
+operations must all be created with a tree type originating from the
+same call to @code{make-wt-tree-type}.
@end deffn
@defvr {variable+} number-wt-type
@@ -7364,10 +7201,10 @@ sorted sequence under the tree's ordering relation on the keys.
@code{wt-tree/index} returns the @var{index}th key,
@code{wt-tree/index-datum} returns the datum associated with the
@var{index}th key and @code{wt-tree/index-pair} returns a new pair
-@code{(@var{key} . @var{datum})} which is the @code{cons} of the @var{index}th
-key and its datum. The average and worst-case times required by this
-operation are proportional to the logarithm of the number of
-associations in the tree.
+@code{(@var{key} . @var{datum})} which is the @code{cons} of the
+@var{index}th key and its datum. The average and worst-case times
+required by this operation are proportional to the logarithm of the
+number of associations in the tree.
These operations signal an error if the tree is empty, if
@var{index}@code{<0}, or if @var{index} is greater than or equal to the
@@ -7377,9 +7214,11 @@ Indexing can be used to find the median and maximum keys in the tree as
follows:
@example
-median: (wt-tree/index @var{wt-tree} (quotient (wt-tree/size @var{wt-tree}) 2))
+median: (wt-tree/index @var{wt-tree}
+ (quotient (wt-tree/size @var{wt-tree}) 2))
-maximum: (wt-tree/index @var{wt-tree} (-1+ (wt-tree/size @var{wt-tree})))
+maximum: (wt-tree/index @var{wt-tree}
+ (-1+ (wt-tree/size @var{wt-tree})))
@end example
@end deffn
@@ -7395,13 +7234,13 @@ the number of associations in the tree.
@deffn {procedure+} wt-tree/min wt-tree
@deffnx {procedure+} wt-tree/min-datum wt-tree
@deffnx {procedure+} wt-tree/min-pair wt-tree
-Returns the association of @var{wt-tree} that has the least key under the tree's ordering relation.
-@code{wt-tree/min} returns the least key,
-@code{wt-tree/min-datum} returns the datum associated with the
-least key and @code{wt-tree/min-pair} returns a new pair
-@code{(key . datum)} which is the @code{cons} of the minimum key and its datum.
-The average and worst-case times required by this operation are
-proportional to the logarithm of the number of associations in the tree.
+Returns the association of @var{wt-tree} that has the least key under
+the tree's ordering relation. @code{wt-tree/min} returns the least key,
+@code{wt-tree/min-datum} returns the datum associated with the least key
+and @code{wt-tree/min-pair} returns a new pair @code{(key . datum)}
+which is the @code{cons} of the minimum key and its datum. The average
+and worst-case times required by this operation are proportional to the
+logarithm of the number of associations in the tree.
These operations signal an error if the tree is empty.
They could be written
@@ -7553,13 +7392,13 @@ in @var{array}.@refill
@end deffn
@defun array-1d-ref array index
-@defunx array-2d-ref array index index
-@defunx array-3d-ref array index index 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 index index
-@deffnx Procedure array-3d-set! array new-value index index 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
@@ -7729,6 +7568,13 @@ byte-array are unspecified.
@end deffn
+@deffn Function bytes-length bytes
+
+@code{bytes-length} returns length of byte-array @var{bytes}.
+@findex bytes-length
+
+@end deffn
+
@deffn Function write-byte byte
@deffnx Function write-byte byte port
@@ -7866,7 +7712,8 @@ A generalization of the list-based @code{comlist:reduce-init}
(@xref{Lists as sequences}) to collections which will shadow the
list-based version if @code{(require 'collect)} follows
@ftindex collect
-@code{(require 'common-list-functions)} (@xref{Common List Functions}).@refill
+@code{(require 'common-list-functions)} (@xref{Common List
+Functions}).@refill
@ftindex common-list-functions
Examples:
@@ -9520,7 +9367,10 @@ The obvious string conversion routines. These are non-destructive.
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
@@ -9584,12 +9434,15 @@ character of the first substring of @var{string} that is equal to
@deffn Procedure find-string-from-port? str in-port max-no-chars
Looks for a string @var{str} within the first @var{max-no-chars} chars
of the input port @var{in-port}.
+
@deffnx Procedure find-string-from-port? str in-port
When called with two arguments, the search span is limited by the end of
the input stream.
+
@deffnx Procedure find-string-from-port? str in-port char
Searches up to the first occurrence of character @var{char} in
@var{str}.
+
@deffnx Procedure find-string-from-port? str in-port proc
Searches up to the first occurrence of the procedure @var{proc}
returning non-false when called with a character (from @var{in-port})
@@ -9606,6 +9459,11 @@ sequentially, and does not perform any buffering. So
open to a pipe or other communication channel.
@end deffn
+@defun string-subst txt old1 new1 @dots{}
+Returns a copy of string @var{txt} with all occurrences of string
+@var{old1} in @var{txt} replaced with @var{new1}, @var{old2} replaced
+with @var{new2} @dots{}.
+@end defun
@node Line I/O, Multi-Processing, String Search, Procedures
@subsection Line I/O
@@ -9693,6 +9551,7 @@ Kills the current process and runs the next process from
* Rationalize:: 'rationalize
* Promises:: 'promise
* Dynamic-Wind:: 'dynamic-wind
+* Eval:: 'eval
* Values:: 'values
@end menu
@@ -9913,7 +9772,7 @@ doesn't support them
-@node Dynamic-Wind, Values, Promises, Standards Support
+@node Dynamic-Wind, Eval, Promises, Standards Support
@subsection Dynamic-Wind
@code{(require 'dynamic-wind)}
@@ -9943,9 +9802,99 @@ the time of the error or interrupt.@refill
@end deffn
+@node Eval, Values, Dynamic-Wind, Standards Support
+@subsection Eval
+
+@code{(require 'eval)}
+
+@defun eval expression environment-specifier
+
+Evaluates @var{expression} in the specified environment and returns its
+value. @var{Expression} must be a valid Scheme expression represented
+as data, and @var{environment-specifier} must be a value returned by one
+of the three procedures described below. Implementations may extend
+@code{eval} to allow non-expression programs (definitions) as the first
+argument and to allow other values as environments, with the restriction
+that @code{eval} is not allowed to create new bindings in the
+environments associated with @code{null-environment} or
+@code{scheme-report-environment}.
+@lisp
+(eval '(* 7 3) (scheme-report-environment 5))
+ @result{} 21
+
+(let ((f (eval '(lambda (f x) (f x x))
+ (null-environment))))
+ (f + 10))
+ @result{} 20
+@end lisp
+@end defun
+
+@defun scheme-report-environment version
+@defunx null-environment version
+@defunx null-environment
+
+@var{Version} must be an exact non-negative integer @var{n}
+corresponding to a version of one of the Revised^@var{n} Reports on
+Scheme. @code{Scheme-report-environment} returns a specifier for an
+environment that contains the set of bindings specified in the
+corresponding report that the implementation supports.
+@code{Null-environment} returns a specifier for an environment that
+contains only the (syntactic) bindings for all the syntactic keywords
+defined in the given version of the report.
+
+Not all versions may be available in all implementations at all times.
+However, an implementation that conforms to version @var{n} of the
+Revised^@var{n} Reports on Scheme must accept version @var{n}. An error
+is signalled if the specified version is not available.
-@node Values, , Dynamic-Wind, Standards Support
+The effect of assigning (through the use of @code{eval}) a variable
+bound in a @code{scheme-report-environment} (for example @code{car}) is
+unspecified. Thus the environments specified by
+@code{scheme-report-environment} may be immutable.
+
+@end defun
+
+@defun interaction-environment
+
+This optional procedure returns a specifier for the environment that
+contains implementation-defined bindings, typically a superset of those
+listed in the report. The intent is that this procedure will return the
+environment in which the implementation would evaluate expressions
+dynamically typed by the user.
+@end defun
+
+@noindent
+Here are some more @code{eval} examples:
+
+@example
+(require 'eval)
+@result{} #<unspecified>
+(define car 'volvo)
+@result{} #<unspecified>
+car
+@result{} volvo
+(eval 'car (interaction-environment))
+@result{} volvo
+(eval 'car (scheme-report-environment 5))
+@result{} #<primitive-procedure car>
+(eval '(eval 'car (interaction-environment))
+ (scheme-report-environment 5))
+@result{} volvo
+(eval '(eval '(set! car 'buick) (interaction-environment))
+ (scheme-report-environment 5))
+@result{} #<unspecified>
+car
+@result{} buick
+(eval 'car (scheme-report-environment 5))
+@result{} #<primitive-procedure car>
+(eval '(eval 'car (interaction-environment))
+ (scheme-report-environment 5))
+@result{} buick
+@end example
+
+
+@node Values, , Eval, Standards Support
@subsection Values
@code{(require 'values)}
@@ -10116,6 +10065,7 @@ which it was called on a continuation stack.
@defun continue
Pops the topmost continuation off of the continuation stack and returns
an unspecified value to it.
+
@defunx continue arg1 @dots{}
Pops the topmost continuation off of the continuation stack and returns
@var{arg1} @dots{} to it.
@@ -10376,8 +10326,10 @@ compatability. Because of shared state they are not thread-safe.
@defun tzset
Returns the default time-zone.
+
@defunx tzset tz
Sets (and returns) the default time-zone to @var{tz}.
+
@defunx tzset TZ-string
Sets (and returns) the default time-zone to that specified by
@var{TZ-string}.
@@ -10436,7 +10388,7 @@ sites are:
@table @asis
@item SLIB-PSD is a portable debugger for Scheme (requires emacs editor).
@lisp
-ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
+swissnet.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
prep.ai.mit.edu:pub/gnu/jacal/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
@@ -10451,25 +10403,9 @@ 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
(Lisp Pointers VI(1):15-23, January-March 1993) is available as
-@ifset html
-<A HREF="http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html">
-@end ifset
-@lisp
-http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html
-@end lisp
-@ifset html
-</A>
-@end ifset
+@url{http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html}
@item SCHELOG is an embedding of Prolog in Scheme.
-@ifset html
-<A HREF="http://www.cs.rice.edu/CS/PLT/packages/schelog/">
-@end ifset
-@lisp
-http://www.cs.rice.edu/CS/PLT/packages/schelog/
-@end lisp
-@ifset html
-</A>
-@end ifset
+@url{http://www.cs.rice.edu/CS/PLT/packages/schelog/}
@end table
@@ -10536,9 +10472,10 @@ script with the name @code{slib48} which will invoke the saved image.
If there is no initialization file for your Scheme implementation, you
will have to create one. Your Scheme implementation must be largely
-compliant with @cite{IEEE Std 1178-1990} or @cite{Revised^4 Report on
-the Algorithmic Language Scheme} to support SLIB. @footnote{If you are
-porting a @cite{Revised^3 Report on the Algorithmic Language Scheme}
+compliant with @cite{IEEE Std 1178-1990}, @cite{Revised^4 Report on the
+Algorithmic Language Scheme}, or @cite{Revised^5 Report on the
+Algorithmic Language Scheme} in order to support SLIB. @footnote{If you
+are porting a @cite{Revised^3 Report on the Algorithmic Language Scheme}
implementation, then you will need to finish writing @file{sc4sc3.scm}
and @code{load} it from your initialization file.}