diff options
Diffstat (limited to 'slib.texi')
| -rw-r--r-- | slib.texi | 1275 |
1 files changed, 605 insertions, 670 deletions
@@ -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 @@ -10491,10 +10427,9 @@ you. @node Installation, Porting, About SLIB, About SLIB @section Installation -Check the manifest in @file{/usr/doc/slib/README.gz} to find a -configuration file for your Scheme implementation. Initialization files -for most IEEE P1178 compliant Scheme Implementations are included with -this distribution. +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. If the Scheme implementation supports @code{getenv}, then the value of the shell environment variable @var{SCHEME_LIBRARY_PATH} will be used @@ -10514,8 +10449,7 @@ 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. The startup files are located in -@file{/usr/lib/slib/init/}. +installed. Multiple implementations of Scheme can all use the same SLIB directory. Simply configure each implementation's initialization file as outlined @@ -10538,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.} |