diff options
Diffstat (limited to 'slib.texi')
| -rw-r--r-- | slib.texi | 794 |
1 files changed, 513 insertions, 281 deletions
@@ -76,15 +76,14 @@ you! SLIB @value{SLIBVERSION}, released @value{SLIBDATE}.@* Aubrey Jaffer <agj @@ alum.mit.edu>@* @ifset html -<A HREF="http://swissnet.ai.mit.edu/~jaffer/SLIB.html"> +<A HREF="http://swiss.csail.mit.edu/~jaffer/SLIB.html"> @end ifset -@url{http://swissnet.ai.mit.edu/~jaffer/SLIB.html} +@url{http://swiss.csail.mit.edu/~jaffer/SLIB.html} @ifset html </A> @end ifset @end quotation -@ifclear html @vskip 0pt plus 1filll Copyright @copyright{} 1993 Todd R. Eigenschink@* Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Aubrey Jaffer @@ -102,10 +101,9 @@ Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author. -@end ifclear @end titlepage -@ifinfo +@ifnottex @noindent @dfn{SLIB} is a portable library for the programming language @dfn{Scheme}. It provides a platform independent framework for using @@ -113,7 +111,7 @@ by the author. contains useful packages for all Scheme implementations. Its catalog can be transparently extended to accomodate packages specific to a site, implementation, user, or directory. -@end ifinfo +@end ifnottex @menu * The Library System:: How to use and customize. @@ -179,8 +177,14 @@ procedures or syntax (macros). Returns @code{#t} if @var{feature} is present in the current Scheme session; otherwise @code{#f}. More specifically, @code{provided?} returns @code{#t} if the symbol @var{feature} is the -@code{software-type} or if @var{feature} has been provided by a module -already loaded; and @code{#f} otherwise. +@code{software-type}, the @code{scheme-implementation-type} +@footnote{scheme-implementation-type is the name symbol of the running +Scheme implementation (RScheme, |STk|, Bigloo, chez, Elk, gambit, +guile, JScheme, MacScheme, MITScheme, Pocket-Scheme, Scheme48, +Scheme->C, Scheme48, Scsh, T, umb-scheme, or Vscm). Dependence on +scheme-implementation-type is almost always the wrong way to do +things.}, or if @var{feature} has been provided by a module already +loaded; and @code{#f} otherwise. In some implementations @code{provided?} tests whether a module has been @code{require}d by any module or in any thread; other @@ -302,16 +306,6 @@ large precision exact integers. @end example @noindent -The @code{commutative-ring} module uses @code{require-if} to ensure -that it has an exponentiation routine, regardless of whether the -implementation supports inexact numbers: - -@example -(require-if '(not inexact) 'logical) ;for integer-expt -(define number^ (if (provided? 'inexact) expt integer-expt)) -@end example - -@noindent The catalog can also be queried using @code{slib:in-catalog?}. @defun slib:in-catalog? feature @@ -346,7 +340,7 @@ Loads file @i{<path>}. @code{slib:load-compiled}s the files @i{<path>} @dots{}. @item (@var{feature} aggregate @i{<symbol>} @dots{}) @cindex aggregate -@code{slib:require}s the features @i{<symbol>} @dots{}. +@code{require}s the features @i{<symbol>} @dots{}. @end table @noindent @@ -603,7 +597,7 @@ immediately preceding the definition (@code{define}, @example ;@@ -(define (make-vicinity <pathname>) <pathname>) +(define (identity <obj>) <obj>) @end example @item @@ -709,11 +703,14 @@ version. Vicinities express only the concept of a file environment where a file name can be resolved to a file in a system independent manner. Vicinities can even be used on @dfn{flat} file systems (which have no directory structure) by having the vicinity express constraints -on the file name. On most systems a vicinity would be a string. All of -these procedures are file system dependent. +on the file name. + +All of these procedures are file-system dependent. Use of these +vicinity procedures can make programs file-system @emph{in}dependent. @noindent These procedures are provided by all implementations. +On most systems a vicinity is a string. @defun make-vicinity dirpath Returns @var{dirpath} as a vicinity for use as first argument to @@ -731,11 +728,11 @@ Returns the vicinity containing @var{path}. @defun program-vicinity Returns the vicinity of the currently loading Scheme code. For an interpreter this would be the directory containing source code. For a -compiled system (with multiple files) this would be the directory where -the object or executable files are. If no file is currently loading it -the result is undefined. @strong{Warning:} @code{program-vicinity} can -return incorrect values if your program escapes back into a -@code{load}. +compiled system (with multiple files) this would be the directory +where the object or executable files are. If no file is currently +loading, then the result is undefined. @strong{Warning:} +@code{program-vicinity} can return incorrect values if your program +escapes back into a @code{load} continuation. @end defun @defun library-vicinity @@ -793,6 +790,14 @@ return a pathname of the subdirectory @var{name} of @var{vicinity}. @end defun +@defun with-load-pathname path thunk +@var{path} should be a string naming a file being read or loaded. +@code{with-load-pathname} evaluates @var{thunk} in a dynamic scope +where an internal variable is bound to @var{path}; the internal +variable is used for messages and @code{program-vicinity}. +@code{with-load-pathname} returns the value returned by @var{thunk}. +@end defun + @node Configuration, Input/Output, Vicinity, Universal SLIB Procedures @@ -1084,6 +1089,19 @@ Example: @end lisp @end defun +@defun expt n k +Returns @var{n} raised to the non-negative integer exponent @var{k}. + +Example: +@lisp +(expt 2 5) + @result{} 32 +(expt -3 3) + @result{} -27 +@end lisp +@end defun + + @subsection Mutual Exclusion @noindent @@ -1164,6 +1182,7 @@ Returns the last pair in the list @var{l}. Example: Syntax extensions (macros) included with SLIB. +* Define-Structure:: 'structure * Fluid-Let:: 'fluid-let * Yasos:: 'yasos, 'oop, 'collect @end menu @@ -1991,7 +2010,7 @@ Bawden. -@node Syntax-Case Macros, Fluid-Let, Syntactic Closures, Scheme Syntax Extension Packages +@node Syntax-Case Macros, Define-Structure, Syntactic Closures, Scheme Syntax Extension Packages @section Syntax-Case Macros @code{(require 'syntax-case)} @@ -2111,18 +2130,73 @@ know if there is some incompatibility that is not flagged as such. Send bug reports, comments, suggestions, and questions to Kent Dybvig (dyb @@ iuvax.cs.indiana.edu). -@subsection Note from SLIB maintainer + + +@node Define-Structure, Fluid-Let, Syntax-Case Macros, Scheme Syntax Extension Packages +@section Define-Structure @code{(require 'structure)} -@findex define-structure +@noindent Included with the @code{syntax-case} files was @file{structure.scm} -which defines a macro @code{define-structure}. I have no -documentation for this macro; it is not used by any other code in -SLIB. +which defines a macro @code{define-structure}. Here is its +documentation from Gambit 4.0: + +@deffn {special form} define-structure @var{name} @var{field}@dots{} +Record data types similar to Pascal records and C @code{struct} +types can be defined using the @code{define-structure} special form. +The identifier @var{name} specifies the name of the new data type. The +structure name is followed by @var{k} identifiers naming each field of +the record. The @code{define-structure} expands into a set of definitions +of the following procedures: + +@itemize @bullet{} + +@item +`@t{make-}@var{name}' -- A @var{k} argument procedure which constructs +a new record from the value of its @var{k} fields. + +@item +`@var{name}@t{?}' -- A procedure which tests if its single argument +is of the given record type. + +@item +`@var{name}@t{-}@var{field}' -- For each field, a procedure taking +as its single argument a value of the given record type and returning +the content of the corresponding field of the record. + +@item +`@var{name}@t{-}@var{field}@t{-set!}' -- For each field, a two +argument procedure taking as its first argument a value of the given +record type. The second argument gets assigned to the corresponding +field of the record and the void object is returned. + +@end itemize + +Gambit record data types have a printed representation that includes +the name of the type and the name and value of each field. + +For example: + +@smallexample +> @b{(define-structure point x y color)} +> @b{(define p (make-point 3 5 'red))} +> @b{p} +#<point #3 x: 3 y: 5 color: red> +> @b{(point-x p)} +3 +> @b{(point-color p)} +red +> @b{(point-color-set! p 'black)} +> @b{p} +#<point #3 x: 3 y: 5 color: black> +@end smallexample + +@end deffn -@node Fluid-Let, Yasos, Syntax-Case Macros, Scheme Syntax Extension Packages + +@node Fluid-Let, Yasos, Define-Structure, Scheme Syntax Extension Packages @section Fluid-Let @code{(require 'fluid-let)} @@ -2538,7 +2612,7 @@ call graph of grammar rules effectively instantiate the sytnax tree. @noindent The JACAL symbolic math system -(@url{http://swissnet.ai.mit.edu/~jaffer/JACAL.html}) uses +(@url{http://swiss.csail.mit.edu/~jaffer/JACAL.html}) uses @t{precedence-parse}. Its grammar definitions in the file @file{jacal/English.scm} can serve as examples of use. @@ -3034,18 +3108,20 @@ The ruleset in effect before @var{tk} was parsed is restored; @node Format, Standard Formatted I/O, Precedence Parsing, Textual Conversion Packages -@section Format (version 3.0) +@section Format (version 3.1) @ifset html <A NAME="format"></A> @end ifset -@c @code{(require 'format)} +@code{(require 'format)} @ftindex format -@c @include fmtdoc.txi -The @file{format.scm} package was removed because it was not -reentrant. @url{http://swissnet.ai.mit.edu/~jaffer/SLIB.FAQ} explains -more about FORMAT's woes. +@c The @file{format.scm} package was removed because it was not +@c reentrant. @url{http://swiss.csail.mit.edu/~jaffer/SLIB.FAQ} explains +@c more about FORMAT's woes. + +@include format.texi + @node Standard Formatted I/O, Programs and Arguments, Format, Textual Conversion Packages @@ -3267,9 +3343,9 @@ stripped off. @samp{%g} prints @samp{e} between mantissa and exponont. @samp{%G} prints @samp{E} between mantissa and exponent. @item @samp{k}, @samp{K} -Print a number like @samp{%g}, except that an SI prefix is output after -the number, which is scaled accordingly. @samp{%K} outputs a space -between number and prefix, @samp{%k} does not. +Print a number like @samp{%g}, except that an SI prefix is output +after the number, which is scaled accordingly. @samp{%K} outputs a +dot between number and prefix, @samp{%k} does not. @end table @@ -4275,6 +4351,7 @@ thus can reduce loading time. The following will write into * Time Zone:: * Posix Time:: 'posix-time * Common-Lisp Time:: 'common-lisp-time +* Time Infrastructure:: @end menu @noindent @@ -4303,6 +4380,7 @@ Returns the calendar time of @var{caltime} offset by @var{offset} number of seconds @code{(+ caltime offset)}. @end defun + @node Time Zone, Posix Time, Time and Date, Time and Date @subsection Time Zone @@ -4525,7 +4603,7 @@ Equivalent to @code{(asctime (gmtime @var{caltime}))}, @end defun -@node Common-Lisp Time, , Posix Time, Time and Date +@node Common-Lisp Time, Time Infrastructure, Posix Time, Time and Date @subsection Common-Lisp Time @defun get-decoded-time @@ -4576,6 +4654,21 @@ Notice that the values returned by @code{decode-universal-time} do not match the arguments to @code{encode-universal-time}. @end defun +@node Time Infrastructure, , Common-Lisp Time, Time and Date +@subsection Time Infrastructure + +@code{(require 'time-core)} + +@defun time:gmtime tm +@defunx time:invert decoder target +@defunx time:split t tm_isdst tm_gmtoff tm_zone +@end defun + +@code{(require 'tzfile)} + +@defun tzfile:read path +@end defun + @node NCBI-DNA, Schmooz, Time and Date, Textual Conversion Packages @section NCBI-DNA @@ -4619,15 +4712,16 @@ match the arguments to @code{encode-universal-time}. @noindent 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. These functions behave as though operating on integers -in two's-complement representation. +@code{(require 'logical)} before the code that uses these functions. +These functions behave as though operating on integers in +two's-complement representation. @subsection Bitwise Operations -@defun logand n1 n1 -Returns the integer which is the bit-wise AND of the two integer +@defun logand n1 @dots{} +@defunx bitwise-and n1 @dots{} +Returns the integer which is the bit-wise AND of the integer arguments. Example: @@ -4637,9 +4731,9 @@ Example: @end lisp @end defun -@defun logior n1 n2 -Returns the integer which is the bit-wise OR of the two integer -arguments. +@defun logior n1 @dots{} +@defunx bitwise-ior n1 @dots{} +Returns the integer which is the bit-wise OR of the integer arguments. Example: @lisp @@ -4648,8 +4742,9 @@ Example: @end lisp @end defun -@defun logxor n1 n2 -Returns the integer which is the bit-wise XOR of the two integer +@defun logxor n1 @dots{} +@defunx bitwise-xor n1 @dots{} +Returns the integer which is the bit-wise XOR of the integer arguments. Example: @@ -4660,7 +4755,9 @@ Example: @end defun @defun lognot n -Returns the integer which is the 2s-complement of the integer argument. +@defunx bitwise-not n +Returns the integer which is the one's-complement of the integer +argument. Example: @lisp @@ -4672,6 +4769,7 @@ Example: @end defun @defun bitwise-if mask n0 n1 +@defunx bitwise-merge 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 @@ -4679,6 +4777,7 @@ of @var{mask} is 0. @end defun @defun logtest j k +@defunx any-bits-set? j k @example (logtest j k) @equiv{} (not (zero? (logand j k))) @@ -4687,7 +4786,11 @@ of @var{mask} is 0. @end example @end defun + +@subsection Integer Properties + @defun logcount n +@defunx bit-count 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, @@ -4704,12 +4807,62 @@ Example: @end lisp @end defun +@defun integer-length n +Returns the number of bits neccessary to represent @var{n}. + +Example: +@lisp +(integer-length #b10101010) + @result{} 8 +(integer-length 0) + @result{} 0 +(integer-length #b1111) + @result{} 4 +@end lisp +@end defun + +@defun log2-binary-factors n +@defunx first-set-bit n +Returns the number of factors of two of integer @var{n}. This value +is also the bit-index of the least-significant @samp{1} bit in +@var{n}. + +@lisp +(require 'printf) +(do ((idx 0 (+ 1 idx))) + ((> idx 16)) + (printf "%s(%3d) ==> %-5d %s(%2d) ==> %-5d\n" + 'log2-binary-factors + (- idx) (log2-binary-factors (- idx)) + 'log2-binary-factors + idx (log2-binary-factors idx))) +@print{} +log2-binary-factors( 0) ==> -1 log2-binary-factors( 0) ==> -1 +log2-binary-factors( -1) ==> 0 log2-binary-factors( 1) ==> 0 +log2-binary-factors( -2) ==> 1 log2-binary-factors( 2) ==> 1 +log2-binary-factors( -3) ==> 0 log2-binary-factors( 3) ==> 0 +log2-binary-factors( -4) ==> 2 log2-binary-factors( 4) ==> 2 +log2-binary-factors( -5) ==> 0 log2-binary-factors( 5) ==> 0 +log2-binary-factors( -6) ==> 1 log2-binary-factors( 6) ==> 1 +log2-binary-factors( -7) ==> 0 log2-binary-factors( 7) ==> 0 +log2-binary-factors( -8) ==> 3 log2-binary-factors( 8) ==> 3 +log2-binary-factors( -9) ==> 0 log2-binary-factors( 9) ==> 0 +log2-binary-factors(-10) ==> 1 log2-binary-factors(10) ==> 1 +log2-binary-factors(-11) ==> 0 log2-binary-factors(11) ==> 0 +log2-binary-factors(-12) ==> 2 log2-binary-factors(12) ==> 2 +log2-binary-factors(-13) ==> 0 log2-binary-factors(13) ==> 0 +log2-binary-factors(-14) ==> 1 log2-binary-factors(14) ==> 1 +log2-binary-factors(-15) ==> 0 log2-binary-factors(15) ==> 0 +log2-binary-factors(-16) ==> 4 log2-binary-factors(16) ==> 4 +@end lisp +@end defun @subsection Bit Within Word -@defun logbit? index j +@defun logbit? index n +@defunx bit-set? index n @example -(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j) +(logbit? index n) @equiv{} (logtest (expt 2 index) n) (logbit? 0 #b1101) @result{} #t (logbit? 1 #b1101) @result{} #f @@ -4731,11 +4884,8 @@ Example: @end example @end defun -@subsection Fields of Bits -@defun logical:ones n -Returns the smallest non-negative integer having @var{n} binary ones. -@end defun +@subsection Field of Bits @defun bit-field n start end Returns the integer composed of the @var{start} (inclusive) through @@ -4751,7 +4901,7 @@ Example: @end lisp @end defun -@defun copy-bit-field to start end from +@defun copy-bit-field to from start end 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 @@ -4759,14 +4909,17 @@ the same as those of @var{from}. The 0-th bit of @var{from} becomes the Example: @example -(number->string (copy-bit-field #b1101101010 0 4 0) 2) +(number->string (copy-bit-field #b1101101010 0 0 4) 2) @result{} "1101100000" -(number->string (copy-bit-field #b1101101010 0 4 -1) 2) +(number->string (copy-bit-field #b1101101010 -1 0 4) 2) @result{} "1101101111" +(number->string (copy-bit-field #b110100100010000 -1 5 9) 2) + @result{} "110100111110000" @end example @end defun @defun ash n count +@defunx arithmetic-shift n count Returns an integer equivalent to @code{(inexact->exact (floor (* @var{n} (expt 2 @var{count}))))}. @@ -4779,58 +4932,37 @@ Example: @end lisp @end defun -@defun integer-length n -Returns the number of bits neccessary to represent @var{n}. -Example: -@lisp -(integer-length #b10101010) - @result{} 8 -(integer-length 0) - @result{} 0 -(integer-length #b1111) - @result{} 4 -@end lisp -@end defun - -@defun integer-expt n k -Returns @var{n} raised to the non-negative integer exponent @var{k}. +@defun rotate-bit-field n count start end +Returns @var{n} with the bit-field from @var{start} to @var{end} +cyclically permuted by @var{count} bits towards high-order. Example: @lisp -(integer-expt 2 5) - @result{} 32 -(integer-expt -3 3) - @result{} -27 +(number->string (rotate-bit-field #b0100 3 0 4) 2) + @result{} "10" +(number->string (rotate-bit-field #b0100 -1 0 4) 2) + @result{} "10" +(number->string (rotate-bit-field #b110100100010000 -1 5 9) 2) + @result{} "110100010010000" +(number->string (rotate-bit-field #b110100100010000 1 5 9) 2) + @result{} "110100000110000" @end lisp @end defun -@subsection Bit order and Lamination - -@defun logical:rotate k count len -Returns the low-order @var{len} bits of @var{k} cyclically permuted -@var{count} bits towards high-order. - -Example: -@lisp -(number->string (logical:rotate #b0100 3 4) 2) -@result{} "10" -(number->string (logical:rotate #b0100 -1 4) 2) -@result{} "10" -@end lisp -@end defun - -@defun bit-reverse k n -Returns the low-order @var{k} bits of @var{n} with the bit order -reversed. The low-order bit of @var{n} is the high order bit of the -returned value. +@defun reverse-bit-field n start end +Returns @var{n} with the order of bits @var{start} to @var{end} +reversed. @example -(number->string (bit-reverse 8 #xa7) 16) +(number->string (reverse-bit-field #xa7 0 8) 16) @result{} "e5" @end example @end defun + +@subsection Bits as Booleans + @defun integer->list k len @defunx integer->list k @code{integer->list} returns a list of @var{len} booleans corresponding @@ -4850,67 +4982,6 @@ each #t; a 0 bit for #f. Returns the integer coded by the @var{bool1} @dots{} arguments. @end defun -@defun bitwise:laminate k1 @dots{} -Returns an integer composed of the bits of @var{k1} @dots{} interlaced -in argument order. Given @var{k1}, @dots{} @var{kn}, the n low-order -bits of the returned value will be the lowest-order bit of each -argument. - -@defunx bitwise:delaminate count k -Returns a list of @var{count} integers comprised of every @var{count}h -bit of the integer @var{k}. - -For any non-negative integers @var{k} and @var{count}: -@example -(eqv? k (bitwise:laminate (bitwise:delaminate count k))) -@end example -@end defun - - -@subsection Gray code - -@cindex Gray code -@noindent -A @dfn{Gray code} is an ordering of non-negative integers in which -exactly one bit differs between each pair of successive elements. There -are multiple Gray codings. An n-bit Gray code corresponds to a -Hamiltonian cycle on an n-dimensional hypercube. - -@noindent -Gray codes find use communicating incrementally changing values between -asynchronous agents. De-laminated Gray codes comprise the coordinates -of Peano-Hilbert space-filling curves. - - -@defun integer->gray-code k -Converts @var{k} to a Gray code of the same @code{integer-length} as -@var{k}. - -@defunx gray-code->integer k -Converts the Gray code @var{k} to an integer of the same -@code{integer-length} as @var{k}. - -For any non-negative integer @var{k}, -@example -(eqv? k (gray-code->integer (integer->gray-code k))) -@end example -@end defun - -@defun = k1 k2 -@defunx gray-code<? k1 k2 -@defunx gray-code>? k1 k2 -@defunx gray-code<=? k1 k2 -@defunx gray-code>=? k1 k2 -These procedures return #t if their Gray code arguments are -(respectively): equal, monotonically increasing, monotonically -decreasing, monotonically nondecreasing, or monotonically nonincreasing. - -For any non-negative integers @var{k1} and @var{k2}, the Gray code -predicate of @code{(integer->gray-code k1)} and -@code{(integer->gray-code k2)} will return the same value as the -corresponding predicate of @var{k1} and @var{k2}. -@end defun - @@ -4939,7 +5010,7 @@ 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{http://swissnet.ai.mit.edu/ftpdir/users/jaffer/diehard.c.pat} corrects. +@url{http://swiss.csail.mit.edu/ftpdir/users/jaffer/diehard.c.pat} corrects. SLIB's PRNG generates 8 bits at a time. With the degenerate seed @samp{0}, the numbers generated pass DIEHARD; but when bits are @@ -5004,6 +5075,27 @@ or non-inverted) to the data stream. @end itemize @noindent +The performance of a particular CRC polynomial over packets of given +sizes varies widely. In terms of the probability of undetected +errors, some uses of extant CRC polynomials are suboptimal by several +orders of magnitude. + +@noindent +If you are considering CRC for a new application, consult the +following article to find the optimum CRC polynomial for your range of +data lengths: + +@itemize @bullet +@item +Philip Koopman and Tridib Chakravarty,@* +``Cyclic Redundancy Code (CRC) Polynomial Selection For Embedded Networks'',@* +The International Conference on Dependable Systems and Networks, DSN-2004.@* +@end itemize + +@exdent +@url{http://www.ece.cmu.edu/~koopman/roses/dsn04/koopman04_crc_poly_embedded.pdf} + +@noindent There is even some controversy over the polynomials themselves. @defvr Constant crc-32-polynomial @@ -5062,7 +5154,8 @@ CRC-12: x^12+x^11+x^3+x^2+x+1. These differ in bit 1 and calculations using them return different values. With citations near evenly split, it is hard to know which is -correct. +correct. Thanks to Philip Koopman for breaking the tie in favor of +the latter (#xC07). @end defvr @defvr Constant crc-10-polynomial @@ -5345,7 +5438,7 @@ vector or list @var{data} <A NAME="Color"></A> @end ifset -@uref{http://swissnet.ai.mit.edu/~jaffer/Color} +@uref{http://swiss.csail.mit.edu/~jaffer/Color} @noindent The goals of this package are to provide methods to specify, compute, @@ -5398,6 +5491,20 @@ L*C*h @defun make-color space arg @dots{} Returns a color of type @var{space}. + +@itemize @bullet +@item +For @var{space} arguments @code{CIEXYZ}, @code{RGB709}, and +@code{sRGB}, the sole @var{arg} is a list of three numbers. +@item +For @var{space} arguments @code{L*a*b*}, @code{L*u*v*}, and +@code{L*C*h}, @var{arg} is a list of three numbers optionally followed +by a whitepoint. +@item +For @code{xRGB}, @var{arg} is an integer. +@item +For @code{e-sRGB}, the arguments are as for @code{e-sRGB->color}. +@end itemize @end defun @defun color-space color @@ -5589,6 +5696,57 @@ Requires Spectral Tristimulus Values, defaulting to cie1931. conversion procedures. The spectrum conversion procedures @code{(require 'ciexyz)} to assure that a set is loaded. +@defun read-cie-illuminant path +@var{path} must be a string naming a file consisting of 107 numbers +for 5.nm intervals from 300.nm to 830.nm. @code{read-cie-illuminant} +reads (using Scheme @code{read}) these numbers and returns a length +107 vector filled with them. +@end defun + +@example +(define CIE:SI-D65 + (read-CIE-illuminant (in-vicinity (library-vicinity) "ciesid65.dat"))) +(spectrum->XYZ CIE:SI-D65 300e-9 830e-9) +@result{} (25.108569422374994 26.418013465625001 28.764075683374993) +@end example + + +@defun read-normalized-illuminant path +@var{path} must be a string naming a file consisting of 107 numbers +for 5.nm intervals from 300.nm to 830.nm. +@code{read-normalized-illuminant} reads (using Scheme @code{read}) +these numbers and returns a length 107 vector filled with them, +normalized so that @code{spectrum->XYZ} of the illuminant returns its +whitepoint. +@end defun + +CIE Standard Illuminants A and D65 are included with SLIB: + +@example +(define CIE:SI-A + (read-normalized-illuminant (in-vicinity (library-vicinity) "ciesia.dat"))) +(define CIE:SI-D65 + (read-normalized-illuminant (in-vicinity (library-vicinity) "ciesid65.dat"))) +(spectrum->XYZ CIE:SI-A 300e-9 830e-9) +@result{} (1.098499460820401 999.9999999999998e-3 355.8173930654951e-3) +(CIEXYZ->sRGB (spectrum->XYZ CIE:SI-A 300e-9 830e-9)) +@result{} (255 234 133) +(spectrum->XYZ CIE:SI-D65 300e-9 830e-9) +@result{} (950.4336673552745e-3 1.0000000000000002 1.0888053986649182) +(CIEXYZ->sRGB (spectrum->XYZ CIE:SI-D65 300e-9 830e-9)) +@result{} (255 255 255) +@end example + +@defun illuminant-map proc siv +@var{siv} must be a one-dimensional array or vector of 107 numbers. +@code{illuminant-map} returns a vector of length 107 containing the +result of applying @var{proc} to each element of @var{siv}. +@end defun + +@defun illuminant-map->XYZ proc siv +@code{(spectrum->XYZ (illuminant-map @var{proc} @var{siv}) 300e-9 830e-9)} +@end defun + @defun spectrum->XYZ proc @var{proc} must be a function of one argument. @code{spectrum->XYZ} computes the CIEXYZ(1931) values for the spectrum returned by @var{proc} @@ -5616,11 +5774,6 @@ Compute the colors of 6500.K and 5000.K blackbody radiation: (map (lambda (x) (/ x y_n)) xyz) @result{} (0.2933441826889158 0.2988931825387761 0.25783646831201573) @end example - -@defunx spectrum->CIEXYZ proc -@defunx spectrum->CIEXYZ spectrum x1 x2 -@code{spectrum->CIEXYZ} computes the CIEXYZ(1931) values for the -spectrum, scaled so their sum is 1. @end defun @defun spectrum->chromaticity proc @@ -5629,16 +5782,15 @@ Computes the chromaticity for the given spectrum. @end defun @defun wavelength->XYZ w -@defunx wavelength->chromaticity w -@defunx wavelength->CIEXYZ w @var{w} must be a number between 380e-9 to 780e-9. @code{wavelength->XYZ} returns (unnormalized) XYZ values for a monochromatic light source with wavelength @var{w}. +@end defun + +@defun wavelength->chromaticity w +@var{w} must be a number between 380e-9 to 780e-9. @code{wavelength->chromaticity} returns the chromaticity for a monochromatic light source with wavelength @var{w}. -@code{wavelength->CIEXYZ} returns XYZ values for the saturated color -having chromaticity of a monochromatic light source with wavelength -@var{w}. @end defun @defun blackbody-spectrum temp @@ -5654,8 +5806,8 @@ procedure correspond to the power of the photons with wavelengths @defun temperature->XYZ x The positive number @var{x} is a temperature in degrees kelvin. -@code{temperature->XYZ} computes the CIEXYZ(1931) values for the -spectrum of a black body at temperature @var{x}. +@code{temperature->XYZ} computes the unnormalized CIEXYZ(1931) values +for the spectrum of a black body at temperature @var{x}. Compute the chromaticities of 6500.K and 5000.K blackbody radiation: @@ -5669,26 +5821,21 @@ Compute the chromaticities of 6500.K and 5000.K blackbody radiation: @end example @end defun -@defun temperature->CIEXYZ x +@defun temperature->chromaticity x The positive number @var{x} is a temperature in degrees kelvin. -@code{temperature->CIEXYZ} computes the CIEXYZ(1931) values for the -spectrum of a black body at temperature @var{x}, scaled to be just -inside the RGB709 gamut. -@end defun +@code{temperature->cromaticity} computes the chromaticity for the +spectrum of a black body at temperature @var{x}. -@defun temperature->chromaticity x -@end defun +Compute the chromaticities of 6500.K and 5000.K blackbody radiation: -@defun XYZ:normalize xyz -@var{xyz} is a list of three non-negative real numbers. -@code{XYZ:normalize} returns a list of numbers proportional to -@var{xyz}; scaled so their sum is 1. -@end defun +@example +(require 'color-space) +(temperature->chromaticity 6500) + @result{} (0.3135191660557008 0.3236456786200268) -@defun XYZ:normalize-colors colors @dots{} -@var{colors} is a list of XYZ triples. @code{XYZ:normalize-colors} -scales all the triples by a common factor such that the maximum sum of -numbers in a scaled triple is 1. +(temperature->chromaticity 5000) + @result{} (0.34508082841161052 0.3516084965163377) +@end example @end defun @defun XYZ->chromaticity xyz @@ -5958,7 +6105,7 @@ Looks for @var{name} among the 19 saturated colors from @item red purple @tab purplish red @tab red @end multitable -(@url{http://swissnet.ai.mit.edu/~jaffer/Color/saturate.pdf}). If +(@url{http://swiss.csail.mit.edu/~jaffer/Color/saturate.pdf}). If @var{name} is found, the corresponding color is returned. Otherwise #f is returned. Use saturate only for light source colors. @end defun @@ -5974,7 +6121,7 @@ operated paint manufacturing company, has generously made their @defun resene name Looks for @var{name} among the 1300 entries in the Resene color-name -dictionary (@url{http://swissnet.ai.mit.edu/~jaffer/Color/resene.pdf}). +dictionary (@url{http://swiss.csail.mit.edu/~jaffer/Color/resene.pdf}). If @var{name} is found, the corresponding color is returned. Otherwise #f is returned. The @cite{Resene RGB Values List} is an excellent source for surface colors. @@ -6043,7 +6190,7 @@ its argument) @var{df/dx}, and initial integer value @var{x0} for which @var{f}(@var{x}) is closer to zero than either of the integers adjacent to @var{x}; or returns @code{#f} if such an integer can't be found. -To find the closest integer to a given integers square root: +To find the closest integer to a given integer's square root: @example (define (integer-sqrt y) @@ -6485,7 +6632,7 @@ Data Banks}). An SLIB relational database implementation can be created from any @ref{Base Table} implementation. Why relational database? For motivations and design issues see@* -@uref{http://swissnet.ai.mit.edu/~jaffer/DBManifesto.html}. +@uref{http://swiss.csail.mit.edu/~jaffer/DBManifesto.html}. @menu * Using Databases:: 'databases @@ -6788,7 +6935,7 @@ returns the key-list identifying the highest record less than @var{key1} @var{key2} @dots{} which is stored in the relational-table; or false if no lower record is present. -@defopx {Operation} {relational-table} isam-prev index +@defopx {Operation} {relational-table} isam-prev column-name The symbol @var{column-name} names a key field. In the list returned by @code{isam-next}, that field, or a field to its left, will be changed. This allows one to skip over less significant key fields. @@ -7329,15 +7476,20 @@ etags -lscheme -r'/ *(define-\(command\|table\) (\([^; \t]+\)/\2/' \ @end example @menu +* Within-database:: * Within-database Example:: @end menu +@node Within-database, Within-database Example, Database Macros, Database Macros +@subsubsection Within-database + @defun within-database database statement-1 @dots{} @code{within-database} creates a lexical scope in which the commands @code{define-table} and @code{define-command} create tables and @code{*commands*}-table entries respectively in open relational -database @var{database}. +database @var{database}. The expressions in `within-database' form +are executed in order. @code{within-database} Returns @var{database}. @end defun @@ -7385,8 +7537,38 @@ key field table, a foreign-key domain will be created for it. @end deffn +@defun add-macro-support database +The relational database @var{database} must be mutable. +@code{add-macro-support} adds a @code{*macros*} table and +@code{define-macro} macro to @var{database}; then @var{database} is +returned. +@end defun + +@deffn Syntax define-macro (@r{<name>} @r{arg1} @dots{}) @r{"comment"} @r{<expression1>} @r{<expression2>} @dots{} +@deffnx Syntax define-macro (@r{<name>} @r{arg1} @dots{}) @r{<expression1>} @r{<expression2>} @dots{} +Adds a macro @r{<name>} to the @code{*macros*}. + +@emph{Note:} @code{within-database} creates lexical scope where not +only @code{define-command} and @code{define-table}, but every command +and macro are defined, ie.: -@node Within-database Example, , Database Macros, Database Macros +@example +(within-database my-rdb + (define-command (message rdb) + (lambda (msg) + (display "message: ") + (display msg) + (newline))) + (message "Defining FOO...") + ;; ... defining FOO ... + (message "Defining BAR...") + ;; ... defining BAR ... + ) +@end example +@end deffn + + +@node Within-database Example, , Within-database, Database Macros @subsubsection Within-database Example @noindent @@ -9656,7 +9838,7 @@ Example: @noindent @code{last} and @code{butlast} split a list into two parts when given -identical arugments. +identical arguments. @example (last '(a b c d e) 2) @result{} (d e) @@ -9693,7 +9875,7 @@ Example: @noindent @code{nthcdr} and @code{butnthcdr} split a list into two parts when -given identical arugments. +given identical arguments. @example (nthcdr 2 '(a b c d e)) @result{} (c d e) @@ -10090,17 +10272,24 @@ items have the same @code{hashv} implies the items have the same @subsection Space-Filling Curves @menu -* Peano-Hilbert Space-Filling Curve:: +* Hilbert Space-Filling Curve:: Non-negative coordinates +* Peano Space-Filling Curve:: Integer coordinates * Sierpinski Curve:: @end menu -@node Peano-Hilbert Space-Filling Curve, Sierpinski Curve, Space-Filling Curves, Space-Filling Curves -@subsubsection Peano-Hilbert Space-Filling Curve +@node Hilbert Space-Filling Curve, Peano Space-Filling Curve, Space-Filling Curves, Space-Filling Curves +@subsubsection Hilbert Space-Filling Curve @include phil-spc.txi -@node Sierpinski Curve, , Peano-Hilbert Space-Filling Curve, Space-Filling Curves +@node Peano Space-Filling Curve, Sierpinski Curve, Hilbert Space-Filling Curve, Space-Filling Curves +@subsubsection Peano Space-Filling Curve + +@include peanosfc.txi + + +@node Sierpinski Curve, , Peano Space-Filling Curve, Space-Filling Curves @subsubsection Sierpinski Curve @code{(require 'sierpinski)} @@ -10444,7 +10633,7 @@ Kills the current process and runs the next process from @code{(require 'metric-units)} @ftindex metric-units -@url{http://swissnet.ai.mit.edu/~jaffer/MIXF.html} +@url{http://swiss.csail.mit.edu/~jaffer/MIXF} @dfn{Metric Interchange Format} is a character string encoding for numerical values and units which: @@ -10810,24 +10999,12 @@ For the specification of these optional procedures, @defun list-tail l p @end defun -@defun string->list s -@end defun - -@defun list->string l -@end defun - @defun string-copy @end defun @deffn {Procedure} string-fill! s obj @end deffn -@defun list->vector l -@end defun - -@defun vector->list s -@end defun - @deffn {Procedure} vector-fill! s obj @end deffn @@ -11062,6 +11239,8 @@ unspecified. * SRFI-9:: Defining Record Types @end menu +SRFI-47 is the same as @ref{Arrays}. + @node SRFI-1, SRFI-2, SRFI, SRFI @subsubsection SRFI-1 @@ -11102,6 +11281,14 @@ Where @node Session Support, System Interface, Standards Support, Other Packages @section Session Support +@noindent +If @code{(provided? 'abort)}: + +@defun abort +Resumes the top level Read-Eval-Print loop. If provided, @code{abort} +is used by the @code{break} and @code{debug} packages. +@end defun + @menu * Repl:: Macros at top-level * Quick Print:: Loop-safe Output @@ -11508,17 +11695,18 @@ sites are: @table @asis @item SLIB-PSD +@cindex PSD is a portable debugger for Scheme (requires emacs editor). @ifset html -<A HREF="http://swissnet.ai.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz"> +<A HREF="http://swiss.csail.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz"> @end ifset -http://swissnet.ai.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz +http://swiss.csail.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz @ifset html </A> @end ifset -swissnet.ai.mit.edu:/pub/scm/slib-psd1-3.tar.gz +swiss.csail.mit.edu:/pub/scm/slib-psd1-3.tar.gz ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz @@ -11544,6 +11732,8 @@ http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html @sp 1 @item SCHELOG +@cindex SCHELOG +@cindex Prolog is an embedding of Prolog in Scheme.@* @ifset html <A HREF="http://www.ccs.neu.edu/~dorai/schelog/schelog.html"> @@ -11555,6 +11745,10 @@ http://www.ccs.neu.edu/~dorai/schelog/schelog.html @sp 1 @item JFILTER +@cindex JFILTER +@cindex Japanese +@cindex JIS +@cindex EUC is a Scheme program which converts text among the JIS, EUC, and Shift-JIS Japanese character sets.@* @ifset html @@ -11570,7 +11764,7 @@ http://www.sci.toyama-u.ac.jp/~iwao/Scheme/Jfilter/index.html @node About SLIB, Index, Other Packages, Top @chapter About SLIB -@ifinfo +@ifnottex @noindent More people than I can name have contributed to SLIB. Thanks to all of you! @@ -11579,12 +11773,13 @@ you! SLIB @value{SLIBVERSION}, released @value{SLIBDATE}.@* Aubrey Jaffer <agj @@ alum.mit.edu>@* @i{Hyperactive Software} -- The Maniac Inside!@* -@url{http://swissnet.ai.mit.edu/~jaffer/SLIB.html} +@url{http://swiss.csail.mit.edu/~jaffer/SLIB.html} @end quotation -@end ifinfo +@end ifnottex @menu * Installation:: How to install SLIB on your system. +* The SLIB script:: Run interactive SLIB sessions. * Porting:: SLIB to new platforms. * Coding Guidelines:: How to write modules for SLIB. * Copyrights:: Intellectual propery issues. @@ -11592,7 +11787,7 @@ Aubrey Jaffer <agj @@ alum.mit.edu>@* @end menu -@node Installation, Porting, About SLIB, About SLIB +@node Installation, The SLIB script, About SLIB, About SLIB @section Installation @ifset html @@ -11604,12 +11799,14 @@ Aubrey Jaffer <agj @@ alum.mit.edu>@* @cindex install @cindex installation -There are four parts to installation: +There are five parts to installation: @itemize @bullet @item Unpack the SLIB distribution. @item +Install documentation and @code{slib} script. +@item Configure the Scheme implementation(s) to locate the SLIB directory. @item Arrange for Scheme implementation to load its SLIB initialization file. @@ -11630,6 +11827,15 @@ this might be @file{/usr/share/slib}, @file{/usr/local/lib/slib}, or @file{/usr/lib/slib}. If you know where SLIB should go on other platforms, please inform agj @@ alum.mit.edu. +@subsection Install documentation and slib script + +@cindex slib +@cindex script +@example +make infoz +make install +@end example + @subsection Configure Scheme Implementation to Locate SLIB If the Scheme implementation supports @code{getenv}, then the value of @@ -11696,6 +11902,66 @@ support is already built into SCM. See the documentation with SCM for installation instructions. @end deftp +@deftp Implementation {PLT Scheme} +@deftpx Implementation {DrScheme} +@deftpx Implementation {MzScheme} + +The @file{init.ss} file in the _slibinit_ collection is an SLIB +initialization file. + +To use SLIB in MzScheme, set the @var{SCHEME_LIBRARY_PATH} environment +variable to the installed SLIB location; then invoke MzScheme thus: + +@code{mzscheme -f $@{SCHEME_LIBRARY_PATH@}DrScheme.init} +@end deftp + +@deftp Implementation {MIT Scheme} +@code{scheme -load $@{SCHEME_LIBRARY_PATH@}mitscheme.init} +@end deftp + +@deftp Implementation Gambit-C 3.0 + +@code{$command -:s $@{SCHEME_LIBRARY_PATH@}gambit.init -} +@end deftp + +@deftp Implementation {Guile} +Guile versions 1.6 and earlier link to an archaic SLIB version. In +RedHat or Fedora installations: + +@example +rm /usr/share/guile/slib +ln -s $@{SCHEME_LIBRARY_PATH@} /usr/share/guile/slib +@end example + +In Debian installations: + +@example +rm /usr/share/guile/1.6/slib +ln -s $@{SCHEME_LIBRARY_PATH@} /usr/share/guile/1.6/slib +@end example + +@code{$@{SCHEME_LIBRARY_PATH@}} is where SLIB gets installed. + +Guile with SLIB can then be started thus: + +@code{guile -l $@{SCHEME_LIBRARY_PATH@}guile.init} +@end deftp + +@deftp Implementation Scheme48 +To make a Scheme48 image for an installation under @code{<prefix>}, + +@enumerate +@item +@code{cd} to the SLIB directory +@item +type @code{make prefix=<prefix> slib48}. +@item +To install the image, type @code{make prefix=<prefix> install48}. This +will also create a shell script with the name @code{slib48} which will +invoke the saved image. +@end enumerate +@end deftp + @deftp Implementation VSCM @format From: Matthias Blume <blume @@ cs.Princeton.EDU> @@ -11726,45 +11992,27 @@ e.g. mv dumpfile /usr/local/vscm/lib/scheme-boot @end deftp -@deftp Implementation Scheme48 -To make a Scheme48 image for an installation under @code{<prefix>}, - -@enumerate -@item -@code{cd} to the SLIB directory -@item -type @code{make prefix=<prefix> slib48}. -@item -To install the image, type @code{make prefix=<prefix> install48}. This -will also create a shell script with the name @code{slib48} which will -invoke the saved image. -@end enumerate -@end deftp - -@deftp Implementation {PLT Scheme} -@deftpx Implementation {DrScheme} -@deftpx Implementation {MzScheme} -The @file{init.ss} file in the _slibinit_ collection is an SLIB -initialization file. +@node The SLIB script, Porting, Installation, About SLIB +@section The SLIB script -To use SLIB in MzScheme, set the @var{SCHEME_LIBRARY_PATH} environment -variable to the installed SLIB location; then invoke MzScheme thus: +SLIB comes with shell script for Unix platforms. -@code{mzscheme -f $@{SCHEME_LIBRARY_PATH@}DrScheme.init} -@end deftp +@example +@exdent @b{ slib } [ scm | gsi | mzscheme | guile | slib48 | scheme48 | scmlit ] +@end example -@deftp Implementation {MIT Scheme} -@code{scheme -load $@{SCHEME_LIBRARY_PATH@}mitscheme.init} -@end deftp +@noindent +Starts an interactive Scheme-with-SLIB session. -@deftp Implementation {Guile} -@code{guile -l $@{SCHEME_LIBRARY_PATH@}guile.init} -@end deftp +@noindent +The optional argument to the @code{slib} script is the Scheme +implementation to run. Absent the argument, it searches for +implementations in the above order. -@node Porting, Coding Guidelines, Installation, About SLIB +@node Porting, Coding Guidelines, The SLIB script, About SLIB @section Porting If there is no initialization file for your Scheme implementation, you @@ -11973,26 +12221,10 @@ At the beginning of each section, there is a line that looks like using the package. @end itemize - +@ifinfo @node Index, , About SLIB, Top -@c @node Procedure and Macro Index, Operator Index, About SLIB, Top -@unnumbered Procedure and Macro Index - -This is an alphabetical list of all the procedures and macros in SLIB. - -@printindex fn - -@c @node Variable Index, Concept Index, Operator Index, Top -@unnumbered Variable Index - -This is an alphabetical list of all the global variables in SLIB. - -@printindex vr - -@c @node Concept Index, , Variable Index, Top -@unnumbered Concept and Feature Index - -@printindex cp +@unnumbered Index +@end ifinfo -@contents +@include indexes.texi @bye |