diff options
Diffstat (limited to 'slib.info')
| -rw-r--r-- | slib.info | 10520 |
1 files changed, 7234 insertions, 3286 deletions
@@ -1,4 +1,4 @@ -This is slib.info, produced by makeinfo version 4.0 from slib.texi. +This is slib.info, produced by makeinfo version 4.6 from slib.texi. INFO-DIR-SECTION The Algorithmic Language Scheme START-INFO-DIR-ENTRY @@ -8,8 +8,8 @@ END-INFO-DIR-ENTRY This file documents SLIB, the portable Scheme library. Copyright (C) 1993 Todd R. Eigenschink -Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Aubrey -Jaffer +Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, +2002 Aubrey Jaffer Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -38,6 +38,7 @@ implementation, user, or directory. * Menu: * The Library System:: How to use and customize. +* Universal SLIB Procedures:: Provided for all implementations. | * Scheme Syntax Extension Packages:: * Textual Conversion Packages:: * Mathematical Packages:: @@ -47,31 +48,32 @@ implementation, user, or directory. * Index:: -File: slib.info, Node: The Library System, Next: Scheme Syntax Extension Packages, Prev: Top, Up: Top - +File: slib.info, Node: The Library System, Next: Universal SLIB Procedures, Prev: Top, Up: Top + | The Library System ****************** * Menu: * Feature:: SLIB names. -* Requesting Features:: +* Require:: | * Library Catalogs:: -* Catalog Compilation:: -* Built-in Support:: -* About this manual:: +* Catalog Creation:: | +* Catalog Vicinities:: | +* Compiling Scheme:: | -File: slib.info, Node: Feature, Next: Requesting Features, Prev: The Library System, Up: The Library System - +File: slib.info, Node: Feature, Next: Require, Prev: The Library System, Up: The Library System + | Feature ======= SLIB denotes "features" by symbols. SLIB maintains a list of features -supported by the Scheme "session". The set of features provided by a -session may change over time. Some features are properties of the -Scheme implementation being used. The following features detail what -sort of numbers are available from an implementation. +supported by a Scheme "session". The set of features provided by a | +session may change during that session. Some features are properties | +of the Scheme implementation being used. The following "intrinsic | +feature"s detail what sort of numbers are available from an | +implementation: | * 'inexact @@ -83,29 +85,63 @@ sort of numbers are available from an implementation. * 'bignum -Other features correspond to the presence of sets of Scheme procedures -or syntax (macros). +SLIB initialization (in `require.scm') tests and "provide"s any of | +these numeric features which are appropriate. | + | +Other features correspond to the presence of packages of Scheme | +procedures or syntax (macros). | - Function: provided? feature - Returns `#t' if FEATURE is supported by the current Scheme session. + Returns `#t' if FEATURE is present in the current Scheme session; | + otherwise `#f'. More specifically, `provided?' returns `#t' if | + the symbol FEATURE is the `software-type' or if FEATURE has been | + provided by a module already loaded; and `#f' otherwise. | + | + In some implementations `provided?' tests whether a module has | + been `require'd by any module or in any thread; other | + implementations will have `provided?' reflect only the modules | + `require'd by that particular session or thread. | + | + To work portably in both scenarios, use `provided?' only to test | + whether intrinsic properties (like those above) are present. | + | + The FEATURE argument can also be an expression calling `and', | + `or', and `not' of features. The boolean result of the logical | + question asked by FEATURE is returned. | + | +The generalization of `provided?' for arbitrary features and catalog is | +`feature-eval': | + | + - Function: feature-eval expression provided? | + Evaluates `and', `or', and `not' forms in EXPRESSION, using the | + values returned by calling PROVIDED? on the leaf symbols. | + `feature-eval' returns the boolean result of the logical | + combinations. | - Procedure: provide feature - Informs SLIB that FEATURE is supported. Henceforth `(provided? - FEATURE)' will return `#t'. + Informs SLIB that FEATURE is supported in this session. | (provided? 'foo) => #f (provide 'foo) (provided? 'foo) => #t -File: slib.info, Node: Requesting Features, Next: Library Catalogs, Prev: Feature, Up: The Library System - -Requesting Features -=================== +File: slib.info, Node: Require, Next: Library Catalogs, Prev: Feature, Up: The Library System + | +Require | +======= | SLIB creates and maintains a "catalog" mapping features to locations of files introducing procedures and syntax denoted by those features. + - Variable: *catalog* | + Is an association list of features (symbols) and pathnames which | + will supply those features. The pathname can be either a string | + or a pair. If pathname is a pair then the first element should be | + a macro feature symbol, `source', `compiled', or one of the other | + cases described in *Note Library Catalogs::. The cdr of the | + pathname should be either a string or a list. | + | At the beginning of each section of this manual, there is a line like `(require 'FEATURE)'. The Scheme files comprising SLIB are cataloged so that these feature names map to the corresponding files. @@ -114,52 +150,55 @@ SLIB provides a form, `require', which loads the files providing the requested feature. - Procedure: require feature - * If `(provided? FEATURE)' is true, then `require' just returns - an unspecified value. + * If `(provided? FEATURE)' is true, then `require' just returns. | * Otherwise, if FEATURE is found in the catalog, then the - corresponding files will be loaded and an unspecified value - returned. - - Subsequently `(provided? FEATURE)' will return `#t'. + corresponding files will be loaded and `(provided? FEATURE)' | + will henceforth return `#t'. That FEATURE is thereafter | + `provided'. | * Otherwise (FEATURE not found in the catalog), an error is signaled. -The catalog can also be queried using `require:feature->path'. +There is a related form `require-if', used primarily for enabling | +compilers to statically include modules which would be dynamically | +loaded by interpreters. | - - Function: require:feature->path feature - * If FEATURE is already provided, then returns `#t'. + - Procedure: require-if condition feature | + Requires FEATURE if CONDITION is true. | - * Otherwise, if FEATURE is in the catalog, the path or list of - paths associated with FEATURE is returned. +The `random' module uses `require-if' to flag `object->string' as a | +(dynamic) required module. | - * Otherwise, returns `#f'. + (require 'byte) | + (require 'logical) | + (require-if 'compiling 'object->string) | - -File: slib.info, Node: Library Catalogs, Next: Catalog Compilation, Prev: Requesting Features, Up: The Library System +The `batch' module uses `require-if' to flag `posix-time' as a module | +to load if the implementation supports large precision exact integers. | -Library Catalogs -================ + (require-if '(and bignum compiling) 'posix-time) | -At the start of a session no catalog is present, but is created with the -first catalog inquiry (such as `(require 'random)'). Several sources -of catalog information are combined to produce the catalog: +The `commutative-ring' module uses `require-if' to ensure that it has | +an exponentiation routine, regardless of whether the implementation | +supports inexact numbers: | - * standard SLIB packages. + (require-if '(not inexact) 'logical) ;for integer-expt | + (define number^ (if (provided? 'inexact) expt integer-expt)) | - * additional packages of interest to this site. +The catalog can also be queried using `slib:in-catalog?'. | - * packages specifically for the variety of Scheme which this session - is running. + - Function: slib:in-catalog? feature | + Returns a `CDR' of the catalog entry if one was found for the | + symbol FEATURE in the alist `*catalog*' (and transitively through | + any symbol aliases encountered). Otherwise, returns `#f'. The | + format of catalog entries is explained in *Note Library Catalogs::. | - * packages this user wants to always have available. This catalog - is the file `homecat' in the user's "HOME" directory. - - * packages germane to working in this (current working) directory. - This catalog is the file `usercat' in the directory to which it - applies. One would typically `cd' to this directory before - starting the Scheme session. + +File: slib.info, Node: Library Catalogs, Next: Catalog Creation, Prev: Require, Up: The Library System + | +Library Catalogs | +================ | Catalog files consist of one or more "association list"s. In the circumstance where a feature symbol appears in more than one list, the @@ -178,6 +217,9 @@ for elements of catalog lists: `(FEATURE compiled "<path>" ...)' `slib:load-compiled's the files <path> .... +`(FEATURE aggregate <symbol> ...)' + `slib:require's the features <symbol> .... | + The various macro styles first `require' the named macro package, then just load <path> or load-and-macro-expand <path> as appropriate for the implementation. @@ -200,22 +242,33 @@ implementation. `(FEATURE syntactic-closures "<path>")' `macro:load's the Scheme source file <path>. -Here is an example of a `usercat' catalog. A Program in this directory -can invoke the `run' feature with `(require 'run)'. + +File: slib.info, Node: Catalog Creation, Next: Catalog Vicinities, Prev: Library Catalogs, Up: The Library System + | +Catalog Creation | +================ | - ;;; "usercat": SLIB catalog additions for SIMSYNCH. -*-scheme-*- - - ( - (simsynch . "../synch/simsynch.scm") - (run . "../synch/run.scm") - (schlep . "schlep.scm") - ) +At the start of an interactive session no catalog is present, but is | +created with the first catalog inquiry (such as `(require 'random)'). | +Several sources of catalog information are combined to produce the | +catalog: | - -File: slib.info, Node: Catalog Compilation, Next: Built-in Support, Prev: Library Catalogs, Up: The Library System + * standard SLIB packages. | -Catalog Compilation -=================== + * additional packages of interest to this site. | + | + * packages specifically for the variety of Scheme which this session | + is running. | + | + * packages this user wants to always have available. This catalog | + is the file `homecat' in the user's "HOME" directory. | + | + * packages germane to working in this (current working) directory. | + This catalog is the file `usercat' in the directory to which it | + applies. One would typically `cd' to this directory before | + starting the Scheme session. | + | + * packages which are part of an application program. | SLIB combines the catalog information which doesn't vary per user into the file `slibcat' in the implementation-vicinity. Therefore `slibcat' @@ -226,27 +279,34 @@ is used with. The definition of `*SLIB-VERSION*' in SLIB file `require.scm' is checked against the catalog association of `*SLIB-VERSION*' to -ascertain when versions have changed. I recommend that the definition -of `*SLIB-VERSION*' be changed whenever the library is changed. If -multiple implementations of Scheme use SLIB, remember that recompiling -one `slibcat' will fix only that implementation's catalog. +ascertain when versions have changed. It is a reasonable practice to | +change the definition of `*SLIB-VERSION*' whenever the library is | +changed. If multiple implementations of Scheme use SLIB, remember that | +recompiling one `slibcat' will update only that implementation's | +catalog. | The compilation scripts of Scheme implementations which work with SLIB can automatically trigger catalog compilation by deleting `slibcat' or -by invoking a special form of `require': +by invoking `require' of a special feature: | - Procedure: require 'new-catalog This will load `mklibcat', which compiles and writes a new `slibcat'. -Another special form of `require' erases SLIB's catalog, forcing it to -be reloaded the next time the catalog is queried. +Another special feature of `require' erases SLIB's catalog, forcing it | +to be reloaded the next time the catalog is queried. | - Procedure: require #f Removes SLIB's catalog information. This should be done before saving an executable image so that, when restored, its catalog will be loaded afresh. + +File: slib.info, Node: Catalog Vicinities, Next: Compiling Scheme, Prev: Catalog Creation, Up: The Library System + | +Catalog Vicinities | +================== | + | Each file in the table below is descibed in terms of its file-system independent "vicinity" (*note Vicinity::). The entries of a catalog in the table override those of catalogs above it in the table. @@ -279,101 +339,381 @@ the table override those of catalogs above it in the table. This file contains the associations specific to an SLIB user. `user-vicinity' `usercat' - This file contains associations effecting only those sessions whose + This file contains associations affecting only those sessions whose | "working directory" is `user-vicinity'. - -File: slib.info, Node: Built-in Support, Next: About this manual, Prev: Catalog Compilation, Up: The Library System -Built-in Support +Here is an example of a `usercat' catalog. A program in this directory | +can invoke the `run' feature with `(require 'run)'. | + | + ;;; "usercat": SLIB catalog additions for SIMSYNCH. -*-scheme-*- | + ( | + (simsynch . "../synch/simsynch.scm") | + (run . "../synch/run.scm") | + (schlep . "schlep.scm") | + ) | + | +Copying `usercat' to many directories is inconvenient. Application | +programs which aren't always run in specially prepared directories can | +nonetheless register their features during initialization. | + | + - Procedure: catalog:read vicinity catalog | + Reads file named by string CATALOG in VICINITY, resolving all | + paths relative to VICINITY, and adds those feature associations to | + *CATALOG*. | + | + `catalog:read' would typically be used by an application program | + having dynamically loadable modules. For instance, to register | + factoring and other modules in *CATALOG*, JACAL does: | + | + (catalog:read (program-vicinity) "jacalcat") | + | + | +For an application program there are three appropriate venues for | +registering its catalog associations: | + | + * in a `usercat' file in the directory where the program runs; or | + | + * in an `implcat' file in the `implementation-vicinity'; or | + | + * in an application program directory; loaded by calling | + `catalog:read'. | + | + +File: slib.info, Node: Compiling Scheme, Prev: Catalog Vicinities, Up: The Library System + | +Compiling Scheme | ================ -The procedures described in these sections are supported by all -implementations as part of the `*.init' files or by `require.scm'. +To use Scheme compilers effectively with SLIB the compiler needs to | +know which SLIB modules are to be compiled and which symbols are | +exported from those modules. | + | + The procedures in this section automate the extraction of this | +information from SLIB modules. They are guaranteed to work on SLIB | +modules; to use them on other sources, those sources should follow SLIB | +conventions. | * Menu: -* Require:: Module Management -* Vicinity:: Pathname Management -* Configuration:: Characteristics of Scheme Implementation -* Input/Output:: Things not provided by the Scheme specs. -* Legacy:: -* System:: LOADing, EVALing, ERRORing, and EXITing +* Module Conventions:: | +* Module Manifests:: | +* Module Semantics:: | +* Top-level Variable References:: | +* Module Analysis:: | -File: slib.info, Node: Require, Next: Vicinity, Prev: Built-in Support, Up: Built-in Support - -Require -------- - - - Variable: *features* - Is a list of symbols denoting features supported in this - implementation. *FEATURES* can grow as modules are `require'd. - *FEATURES* must be defined by all implementations (*note - Porting::). - - Here are features which SLIB (`require.scm') adds to *FEATURES* - when appropriate. +File: slib.info, Node: Module Conventions, Next: Module Manifests, Prev: Compiling Scheme, Up: Compiling Scheme + | +Module Conventions | +------------------ | - * 'inexact + * All the top-level `require' commands have one quoted argument and | + are positioned before other Scheme definitions and expressions in | + the file. | - * 'rational + * Any conditionally `require'd SLIB modules (1) also appear at the | + beginning of their files conditioned on the feature `compiling' | + using `require-if' (*note require-if: Require.). | - * 'real + (require 'logical) | + (require 'multiarg/and-) | + (require-if 'compiling 'sort) | + (require-if 'compiling 'ciexyz) | - * 'complex + * Schmooz-style comments preceding a definition, identify that | + definition as an exported identifier (*note Schmooz::). For | + non-schmooz files, putting `;@' at the beginning of the line | + immediately preceding the definition (`define', `define-syntax', | + or `defmacro') suffices. | - * 'bignum + ;@ | + (define (make-vicinity <pathname>) <pathname>) | - For each item, `(provided? 'FEATURE)' will return `#t' if that - feature is available, and `#f' if not. + * Syntax (macro) definitions are grouped at the end of a module file. | - - Variable: *modules* - Is a list of pathnames denoting files which have been loaded. + * Modules defining macros do not invoke those macros. SLIB macro | + implementations are exempt from this rule. | - - Variable: *catalog* - Is an association list of features (symbols) and pathnames which - will supply those features. The pathname can be either a string - or a pair. If pathname is a pair then the first element should be - a macro feature symbol, `source', or `compiled'. The cdr of the - pathname should be either a string or a list. + An example of how to expand macro invocations is: | -In the following functions if the argument FEATURE is not a symbol it -is assumed to be a pathname. + (require 'macros-that-work) | + (require 'yasos) | + (require 'pprint-file) | + (pprint-filter-file "collect.scm" macwork:expand) | + | - - Function: provided? feature - Returns `#t' if FEATURE is a member of `*features*' or `*modules*' - or if FEATURE is supported by a file already loaded and `#f' - otherwise. + ---------- Footnotes ---------- | - - Procedure: require feature - FEATURE is a symbol. If `(provided? FEATURE)' is true `require' - returns. Otherwise, if `(assq FEATURE *catalog*)' is not `#f', - the associated files will be loaded and `(provided? FEATURE)' will - henceforth return `#t'. An unspecified value is returned. If - FEATURE is not found in `*catalog*', then an error is signaled. + (1) There are some functions with internal `require' calls to delay | +loading modules until they are needed. While this reduces startup | +latency for interpreters, it can produce headaches for compilers. | - - Procedure: require pathname - PATHNAME is a string. If PATHNAME has not already been given as - an argument to `require', PATHNAME is loaded. An unspecified - value is returned. + +File: slib.info, Node: Module Manifests, Next: Module Semantics, Prev: Module Conventions, Up: Compiling Scheme + | +Module Manifests | +---------------- | - - Procedure: provide feature - Assures that FEATURE is contained in `*features*' if FEATURE is a - symbol and `*modules*' otherwise. +`(require 'manifest)' | - - Function: require:feature->path feature - Returns `#t' if FEATURE is a member of `*features*' or `*modules*' - or if FEATURE is supported by a file already loaded. Returns a - path if one was found in `*catalog*' under the feature name, and - `#f' otherwise. The path can either be a string suitable as an - argument to load or a pair as described above for *catalog*. +In some of these examples, SLIB:CATALOG is the SLIB part of the | +catalog; it is free of compiled and implementation-specific entries. | +It would be defined by: | + | + (define slib:catalog (cdr (member (assq 'null *catalog*) *catalog*))) | + | + - Function: file->requires file provided? catalog | + Returns a list of the features `require'd by FILE assuming the | + predicate PROVIDED? and association-list CATALOG. | + | + (define (provided+? . features) | + (lambda (feature) | + (or (memq feature features) (provided? feature)))) | + | + (file->requires "obj2str.scm" (provided+? 'compiling) '()) | + => (string-port generic-write) | + | + (file->requires "obj2str.scm" provided? '()) | + => (string-port) | + | + - Function: feature->requires feature provided? catalog | + Returns a list of the features `require'd by FEATURE assuming the | + predicate PROVIDED? and association-list CATALOG. | + | + (feature->requires 'batch (provided+? 'compiling) *catalog*) | + => (tree line-i/o databases parameters string-port | + pretty-print common-list-functions posix-time) | + | + (feature->requires 'batch provided? *catalog*) | + => (tree line-i/o databases parameters string-port | + pretty-print common-list-functions) | + | + (feature->requires 'batch provided? '((batch . "batch"))) | + => (tree line-i/o databases parameters string-port | + pretty-print common-list-functions) | + | + - Function: file->loads file | + Returns a list of strings naming existing files loaded (load | + slib:load slib:load-source macro:load defmacro:load syncase:load | + synclo:load macwork:load) by FILE or any of the files it loads. | + | + (file->loads (in-vicinity (library-vicinity) "scainit.scm")) | + => ("/usr/local/lib/slib/scaexpp.scm" | + "/usr/local/lib/slib/scaglob.scm" | + "/usr/local/lib/slib/scaoutp.scm") | + | + - Function: load->path exp | + Given a `(load '<expr>)', where <expr> is a string or vicinity | + stuff), `(load->path <expr>)' figures a path to the file. | + `load->path' returns that path if it names an existing file; | + otherwise #f. | + | + (load->path '(in-vicinity (library-vicinity) "mklibcat")) | + => "/usr/local/lib/slib/mklibcat.scm" | + | + - Function: file->definitions file | + Returns a list of the identifier symbols defined by SLIB (or | + SLIB-style) file FILE. | + | + (file->definitions "random.scm") | + => (*random-state* make-random-state | + seed->random-state copy-random-state random | + random:chunk) | + | + - Function: file->exports file | + Returns a list of the identifier symbols exported (advertised) by | + SLIB (or SLIB-style) file FILE. | + | + (file->exports "random.scm") | + => (make-random-state seed->random-state | + copy-random-state random) | + | + (file->exports "randinex.scm") | + => (random:solid-sphere! random:hollow-sphere! | + random:normal-vector! random:normal | + random:exp random:uniform) | + | + - Function: feature->export-alist feature catalog | + Returns a list of lists; each sublist holding the name of the file | + implementing FEATURE, and the identifier symbols exported | + (advertised) by SLIB (or SLIB-style) feature FEATURE, in CATALOG. | + | + - Function: feature->exports feature catalog | + Returns a list of all exports of FEATURE. | + | +In the case of `aggregate' features, more than one file may have export | +lists to report: | + | + (feature->export-alist 'r5rs slib:catalog)) | + => (("/usr/local/lib/slib/values.scm" | + call-with-values values) | + ("/usr/local/lib/slib/mbe.scm" | + define-syntax macro:expand | + macro:load macro:eval) | + ("/usr/local/lib/slib/eval.scm" | + eval scheme-report-environment | + null-environment interaction-environment)) | + | + (feature->export-alist 'stdio *catalog*) | + => (("/usr/local/lib/slib/scanf.scm" | + fscanf sscanf scanf scanf-read-list) | + ("/usr/local/lib/slib/printf.scm" | + sprintf printf fprintf) | + ("/usr/local/lib/slib/stdio.scm" | + stderr stdout stdin)) | + | + (feature->exports 'stdio slib:catalog) | + => (fscanf sscanf scanf scanf-read-list | + sprintf printf fprintf stderr stdout stdin) | -File: slib.info, Node: Vicinity, Next: Configuration, Prev: Require, Up: Built-in Support - +File: slib.info, Node: Module Semantics, Next: Top-level Variable References, Prev: Module Manifests, Up: Compiling Scheme + | +Module Semantics | +---------------- | + | +For the purpose of compiling Scheme code, each top-level `require' | +makes the identifiers exported by its feature's module `defined' (or | +defmacroed or defined-syntaxed) within the file (being compiled) headed | +with those requires. | + | + Top-level occurrences of `require-if' make defined the exports from | +the module named by the second argument _if_ the FEATURE-EXPRESSION | +first argument is true in the target environment. The target feature | +`compiling' should be provided during this phase of compilation. | + | + Non-top-level SLIB occurences of `require' and `require-if' of quoted | +features can be ignored by compilers. The SLIB modules will all have | +top-level constructs for those features. | + | + Note that aggregate catalog entries import more than one module. | +Implementations of `require' may or may _not_ be transitive; code which | +uses module exports without requiring the providing module is in error. | + | + In the SLIB modules `modular', `batch', `hash', `common-lisp-time', | +`commutative-ring', `charplot', `logical', `common-list-functions', | +`coerce' and `break' there is code conditional on features being | +`provided?'. Most are testing for the presence of features which are | +intrinsic to implementations (inexacts, bignums, ...). | + | + In all cases these `provided?' tests can be evaluated at compile-time | +using `feature-eval' (*note feature-eval: Feature.). The simplest way | +to compile these constructs may be to treat `provided?' as a macro. | + | + +File: slib.info, Node: Top-level Variable References, Next: Module Analysis, Prev: Module Semantics, Up: Compiling Scheme + | +Top-level Variable References | +----------------------------- | + | +`(require 'top-refs)' | + | +These procedures complement those in *Note Module Manifests:: by | +finding the top-level variable references in Scheme source code. They | +work by traversing expressions and definitions, keeping track of | +bindings encountered. It is certainly possible to foil these | +functions, but they return useful information about SLIB source code. | + | + - Function: top-refs obj | + Returns a list of the top-level variables referenced by the Scheme | + expression OBJ. | + | + - Function: top-refs<-file filename | + FILENAME should be a string naming an existing file containing | + Scheme source code. `top-refs<-file' returns a list of the | + top-level variable references made by expressions in the file | + named by FILENAME. | + | + Code in modules which FILENAME `require's is not traversed. Code | + in files loaded from top-level _is_ traversed if the expression | + argument to `load', `slib:load', `slib:load-source', `macro:load', | + `defmacro:load', `synclo:load', `syncase:load', or `macwork:load' | + is a literal string constant or composed of combinations of | + vicinity functions and string literal constants; and the resulting | + file exists (possibly with ".scm" appended). | + | +The following function parses an "Info" Index. (1) | + | + - Function: exports<-info-index file n ... | + N ... must be an increasing series of positive integers. | + `exports<-info-index' returns a list of all the identifiers | + appearing in the Nth ... (info) indexes of FILE. The identifiers | + have the case that the implementation's `read' uses for symbols. | + Identifiers containing spaces (eg. `close-base on base-table') are | + _not_ included. | + | + Each info index is headed by a `* Menu:' line. To list the | + symbols in the first and third info indexes do: | + | + (exports<-info-index "slib.info" 1 3) | + | + ---------- Footnotes ---------- | + | + (1) Although it will work on large info files, feeding it an excerpt | +is much faster; and has less chance of being confused by unusual text | +in the info file. This command excerpts the SLIB index into | +`slib-index.info': | + | + info -f slib2d6.info -n "Index" -o slib-index.info | + | + +File: slib.info, Node: Module Analysis, Prev: Top-level Variable References, Up: Compiling Scheme + | +Module Analysis | +--------------- | + | +`(require 'vet)' | + | + - Function: vet-slib | + Using the procedures in the `top-refs' and `manifest' modules, | + `vet-slib' analyzes each SLIB module, reporting about any | + procedure or macro defined whether it is: | + | + orphaned | + defined, not called, not exported; | + | + missing | + called, not defined, and not exported by its `require'd | + modules; | + | + undocumented-export | + Exported by module, but no index entry in `slib.info'; | + | + | + And for the library as a whole: | + | + documented-unexport | + Index entry in `slib.info', but no module exports it. | + | + | + This straightforward analysis caught three full days worth of | + never-executed branches, transitive require assumptions, spelling | + errors, undocumented procedures, missing procedures, and cyclic | + dependencies in SLIB. | + | + +File: slib.info, Node: Universal SLIB Procedures, Next: Scheme Syntax Extension Packages, Prev: The Library System, Up: Top + | +Universal SLIB Procedures | +************************* | + | +The procedures described in these sections are supported by all | +implementations as part of the `*.init' files or by `require.scm'. | + | +* Menu: | + | +* Vicinity:: Pathname Management | +* Configuration:: Characteristics of Scheme Implementation | +* Input/Output:: Things not provided by the Scheme specs. | +* System:: LOADing, EVALing, ERRORing, and EXITing | +* Miscellany:: | + | + +File: slib.info, Node: Vicinity, Next: Configuration, Prev: Universal SLIB Procedures, Up: Universal SLIB Procedures + | Vicinity --------- +======== | A vicinity is a descriptor for a place in the file system. Vicinities hide from the programmer the concepts of host, volume, directory, and @@ -386,8 +726,14 @@ these procedures are file system dependent. These procedures are provided by all implementations. - - Function: make-vicinity path - Returns the vicinity of PATH for use by `in-vicinity'. + - Function: make-vicinity dirpath + Returns DIRPATH as a vicinity for use as first argument to + `in-vicinity'. + + - Function: pathname->vicinity path + Returns the vicinity containing PATH. + (pathname->vicinity "/usr/local/lib/scm/Link.scm") + => "/usr/local/lib/scm/" - Function: program-vicinity Returns the vicinity of the currently loading Scheme code. For an @@ -417,6 +763,10 @@ These procedures are provided by all implementations. a daemon) or if this concept is meaningless for the platform, then `home-vicinity' returns `#f'. + - Function: vicinity:suffix? chr | + Returns the `#t' if CHR is a vicinity suffix character; and `#f' | + otherwise. Typical vicinity suffixes are `/', `:', and `\', | + | - Function: in-vicinity vicinity filename Returns a filename suitable for use by `slib:load', `slib:load-source', `slib:load-compiled', `open-input-file', @@ -435,10 +785,10 @@ These procedures are provided by all implementations. return a pathname of the subdirectory NAME of VICINITY. -File: slib.info, Node: Configuration, Next: Input/Output, Prev: Vicinity, Up: Built-in Support - +File: slib.info, Node: Configuration, Next: Input/Output, Prev: Vicinity, Up: Universal SLIB Procedures + | Configuration -------------- +============= | These constants and procedures describe characteristics of the Scheme and underlying operating system. They are provided by all @@ -474,7 +824,7 @@ implementations. implementation and the name of the operating system. An unspecified value is returned. - (slib:report-version) => slib "2d2" on scm "5b1" on unix | + (slib:report-version) => slib "3a1" on scm "5b1" on unix | - Function: slib:report Displays the information of `(slib:report-version)' followed by @@ -489,9 +839,9 @@ implementations. (slib:report) => - slib "2d2" on scm "5b1" on unix | - (implementation-vicinity) is "/home/jaffer/scm/" - (library-vicinity) is "/home/jaffer/slib/" + slib "3a1" on scm "5b1" on unix | + (implementation-vicinity) is "/usr/local/lib/scm/" | + (library-vicinity) is "/usr/local/lib/slib/" | (scheme-file-suffix) is ".scm" loaded *features* : trace alist qp sort @@ -501,7 +851,7 @@ implementations. bignum complex real rational inexact vicinity ed getenv tmpnam abort transcript with-file - ieee-p1178 rev4-report rev4-optional-procedures hash + ieee-p1178 r4rs rev4-optional-procedures hash | object-hash delay eval dynamic-wind multiarg-apply multiarg/and- logical defmacro string-port source current-time record @@ -509,32 +859,79 @@ implementations. array dump char-ready? full-continuation system implementation *catalog* : - (i/o-extensions compiled "/home/jaffer/scm/ioext.so") + (i/o-extensions compiled "/usr/local/lib/scm/ioext.so") | ... -File: slib.info, Node: Input/Output, Next: Legacy, Prev: Configuration, Up: Built-in Support - +File: slib.info, Node: Input/Output, Next: System, Prev: Configuration, Up: Universal SLIB Procedures + | Input/Output ------------- +============ | These procedures are provided by all implementations. - - Procedure: file-exists? filename + - Function: file-exists? filename Returns `#t' if the specified file exists. Otherwise, returns `#f'. If the underlying implementation does not support this feature then `#f' is always returned. - - Procedure: delete-file filename + - Function: delete-file filename Deletes the file specified by FILENAME. If FILENAME can not be deleted, `#f' is returned. Otherwise, `#t' is returned. - - Procedure: tmpnam + - Function: open-file filename modes + FILENAME should be a string naming a file. `open-file' returns a + port depending on the symbol MODES: + + r + an input port capable of delivering characters from the file. + + rb + a _binary_ input port capable of delivering characters from + the file. + + w + an output port capable of writing characters to a new file by + that name. + + wb + a _binary_ output port capable of writing characters to a new + file by that name. + + If an implementation does not distinguish between binary and + non-binary files, then it must treat rb as r and wb as w. + + If the file cannot be opened, either #f is returned or an error is + signalled. For output, if a file with the given name already + exists, the effect is unspecified. + + - Function: port? obj + Returns #t if OBJ is an input or output port, otherwise returns #f. + + - Procedure: close-port port + Closes the file associated with PORT, rendering the PORT incapable + of delivering or accepting characters. + + `close-file' has no effect if the file has already been closed. + The value returned is unspecified. + + - Function: call-with-open-ports proc ports ... + - Function: call-with-open-ports ports ... proc + PROC should be a procedure that accepts as many arguments as there + are PORTS passed to `call-with-open-ports'. + `call-with-open-ports' calls PROC with PORTS .... If PROC + returns, then the ports are closed automatically and the value + yielded by the PROC is returned. If PROC does not return, then + the ports will not be closed automatically unless it is possible + to prove that the ports will never again be used for a read or + write operation. + + - Function: tmpnam Returns a pathname for a file which will likely not be used by any other process. Successive calls to `(tmpnam)' will return different pathnames. - - Procedure: current-error-port + - Function: current-error-port Returns the current port to which diagnostic and error output is directed. @@ -545,60 +942,23 @@ These procedures are provided by all implementations. omitted, in which case it defaults to the value returned by `(current-output-port)'. - - Procedure: output-port-width - - Procedure: output-port-width port + - Function: output-port-width + - Function: output-port-width port Returns the width of PORT, which defaults to `(current-output-port)' if absent. If the width cannot be determined 79 is returned. - - Procedure: output-port-height - - Procedure: output-port-height port + - Function: output-port-height + - Function: output-port-height port Returns the height of PORT, which defaults to `(current-output-port)' if absent. If the height cannot be determined 24 is returned. -File: slib.info, Node: Legacy, Next: System, Prev: Input/Output, Up: Built-in Support - -Legacy ------- - - These procedures are provided by all implementations. - - - Function: identity x - IDENTITY returns its argument. - - Example: - (identity 3) - => 3 - (identity '(foo bar)) - => (foo bar) - (map identity LST) - == (copy-list LST) - -The following procedures were present in Scheme until R4RS (*note -Language changes: (r4rs)Notes.). They are provided by all SLIB -implementations. - - - Constant: t - Derfined as `#t'. - - - Constant: nil - Defined as `#f'. - - - Function: last-pair l - Returns the last pair in the list L. Example: - (last-pair (cons 1 2)) - => (1 . 2) - (last-pair '(1 2)) - => (2) - == (cons 2 '()) - - -File: slib.info, Node: System, Prev: Legacy, Up: Built-in Support - +File: slib.info, Node: System, Next: Miscellany, Prev: Input/Output, Up: Universal SLIB Procedures + | System ------- +====== | These procedures are provided by all implementations. @@ -653,26 +1013,93 @@ These procedures are provided by all implementations. the system (if possible). If the Scheme session cannot exit an unspecified value is returned from `slib:exit'. + - Function: browse-url url + Web browsers have become so ubiquitous that programming languagues + should support a uniform interface to them. + + If a `netscape' browser is running, `browse-url' causes the + browser to display the page specified by string URL and returns #t. + + If the browser is not running, `browse-url' starts a browser + displaying the argument URL. If the browser starts as a + background job, `browse-url' returns #t immediately; if the + browser starts as a foreground job, then `browse-url' returns #t + when the browser exits; otherwise it returns #f. + -File: slib.info, Node: About this manual, Prev: Built-in Support, Up: The Library System +File: slib.info, Node: Miscellany, Prev: System, Up: Universal SLIB Procedures + | +Miscellany +========== | -About this manual -================= +These procedures are provided by all implementations. - * Entries that are labeled as Functions are called for their return - values. Entries that are labeled as Procedures are called - primarily for their side effects. + - Function: identity x + IDENTITY returns its argument. - * Examples in this text were produced using the `scm' Scheme - implementation. + Example: + (identity 3) + => 3 + (identity '(foo bar)) + => (foo bar) + (map identity LST) + == (copy-list LST) - * At the beginning of each section, there is a line that looks like - `(require 'feature)'. Include this line in your code prior to - using the package. +Mutual Exclusion +---------------- | - -File: slib.info, Node: Scheme Syntax Extension Packages, Next: Textual Conversion Packages, Prev: The Library System, Up: Top +An "exchanger" is a procedure of one argument regulating mutually +exclusive access to a resource. When a exchanger is called, its current +content is returned, while being replaced by its argument in an atomic +operation. + + - Function: make-exchanger obj + Returns a new exchanger with the argument OBJ as its initial + content. + + (define queue (make-exchanger (list a))) + + A queue implemented as an exchanger holding a list can be + protected from reentrant execution thus: + + (define (pop queue) + (let ((lst #f)) + (dynamic-wind + (lambda () (set! lst (queue #f))) + (lambda () (and lst (not (null? lst)) + (let ((ret (car lst))) + (set! lst (cdr lst)) + ret))) + (lambda () (and lst (queue lst)))))) + + (pop queue) => a + + (pop queue) => #f +Legacy +------ | + +The following procedures were present in Scheme until R4RS (*note +Language changes: (r4rs)Notes.). They are provided by all SLIB +implementations. + + - Constant: t + Derfined as `#t'. + + - Constant: nil + Defined as `#f'. + + - Function: last-pair l + Returns the last pair in the list L. Example: + (last-pair (cons 1 2)) + => (1 . 2) + (last-pair '(1 2)) + => (2) + == (cons 2 '()) + + +File: slib.info, Node: Scheme Syntax Extension Packages, Next: Textual Conversion Packages, Prev: Universal SLIB Procedures, Up: Top + | Scheme Syntax Extension Packages ******************************** @@ -686,7 +1113,7 @@ Scheme Syntax Extension Packages * Syntactic Closures:: 'syntactic-closures * Syntax-Case Macros:: 'syntax-case -Syntax extensions (macros) included with SLIB. | +Syntax extensions (macros) included with SLIB. * Fluid-Let:: 'fluid-let * Yasos:: 'yasos, 'oop, 'collect @@ -697,7 +1124,7 @@ File: slib.info, Node: Defmacro, Next: R4RS Macros, Prev: Scheme Syntax Exten Defmacro ======== - Defmacros are supported by all implementations. +Defmacros are supported by all implementations. - Function: gentemp Returns a new (interned) symbol each time it is called. The symbol @@ -739,7 +1166,7 @@ Defmacro Defmacroexpand -------------- - `(require 'defmacroexpand)' +`(require 'defmacroexpand)' - Function: defmacro:expand* e Returns the result of expanding all defmacros in scheme expression @@ -751,9 +1178,9 @@ File: slib.info, Node: R4RS Macros, Next: Macro by Example, Prev: Defmacro, R4RS Macros =========== - `(require 'macro)' is the appropriate call if you want R4RS -high-level macros but don't care about the low level implementation. If -an SLIB R4RS macro implementation is already loaded it will be used. +`(require 'macro)' is the appropriate call if you want R4RS high-level +macros but don't care about the low level implementation. If an SLIB +R4RS macro implementation is already loaded it will be used. Otherwise, one of the R4RS macros implemetations is loaded. The SLIB R4RS macro implementations support the following uniform @@ -781,7 +1208,7 @@ File: slib.info, Node: Macro by Example, Next: Macros That Work, Prev: R4RS M Macro by Example ================ - `(require 'macro-by-example)' +`(require 'macro-by-example)' A vanilla implementation of `Macro by Example' (Eugene Kohlbecker, R4RS) by Dorai Sitaram, (dorai @ cs.rice.edu) using `defmacro'. @@ -801,7 +1228,7 @@ R4RS) by Dorai Sitaram, (dorai @ cs.rice.edu) using `defmacro'. Caveat ------ - These macros are not referentially transparent (*note Macros: +These macros are not referentially transparent (*note Macros: (r4rs)Macros.). Lexically scoped macros (i.e., `let-syntax' and `letrec-syntax') are not supported. In any case, the problem of referential transparency gains poignancy only when `let-syntax' and @@ -856,7 +1283,7 @@ File: slib.info, Node: Macros That Work, Next: Syntactic Closures, Prev: Macr Macros That Work ================ - `(require 'macros-that-work)' +`(require 'macros-that-work)' `Macros That Work' differs from the other R4RS macro implementations in that it does not expand derived expression types to primitive @@ -889,10 +1316,9 @@ Rees [editors]. To appear in LISP Pointers. Also available as a technical report from the University of Oregon, MIT AI Lab, and Cornell. Macros That Work. Clinger and Rees. POPL '91. - - The supported syntax differs from the R4RS in that vectors are allowed -as patterns and as templates and are not allowed as pattern or template -data. + The supported syntax +differs from the R4RS in that vectors are allowed as patterns and as +templates and are not allowed as pattern or template data. transformer spec ==> (syntax-rules literals rules) @@ -966,10 +1392,11 @@ Variables opened by an ellipsis template pattern variables whose rank is greater than the rank of the ellipsis template. + Restrictions ------------ - No pattern variable appears more than once within a pattern. +No pattern variable appears more than once within a pattern. For every occurrence of a pattern variable within a template, the template rank of the occurrence must be greater than or equal to the @@ -1038,7 +1465,7 @@ File: slib.info, Node: Syntactic Closures, Next: Syntax-Case Macros, Prev: Ma Syntactic Closures ================== - `(require 'syntactic-closures)' +`(require 'syntactic-closures)' - Function: macro:expand expression - Function: synclo:expand expression @@ -1064,19 +1491,18 @@ Syntactic Closure Macro Facility -------------------------------- A Syntactic Closures Macro Facility - by Chris Hanson - 9 November 1991 + This +document describes "syntactic closures", a low-level macro facility for +the Scheme programming language. The facility is an alternative to the +low-level macro facility described in the `Revised^4 Report on Scheme.' +This document is an addendum to that report. - This document describes "syntactic closures", a low-level macro -facility for the Scheme programming language. The facility is an -alternative to the low-level macro facility described in the `Revised^4 -Report on Scheme.' This document is an addendum to that report. - - The syntactic closures facility extends the BNF rule for TRANSFORMER +The syntactic closures facility extends the BNF rule for TRANSFORMER SPEC to allow a new keyword that introduces a low-level macro transformer: + TRANSFORMER SPEC := (transformer EXPRESSION) Additionally, the following procedures are added: @@ -1094,7 +1520,7 @@ compatible with `syntax-rules'. Terminology ........... - This section defines the concepts and data types used by the syntactic +This section defines the concepts and data types used by the syntactic closures facility. * "Forms" are the syntactic entities out of which programs are @@ -1102,6 +1528,7 @@ closures facility. definition, any syntactic keyword, or any syntactic closure. The variable name that appears in a `set!' special form is also a form. Examples of forms: + 17 #t car @@ -1141,7 +1568,7 @@ closures facility. Transformer Definition ...................... - This section describes the `transformer' special form and the +This section describes the `transformer' special form and the procedures `make-syntactic-closure' and `capture-syntactic-environment'. - Syntax: transformer expression @@ -1165,6 +1592,7 @@ procedures `make-syntactic-closure' and `capture-syntactic-environment'. For example, here is a definition of a push macro using `syntax-rules': + (define-syntax push (syntax-rules () ((push item list) @@ -1189,6 +1617,7 @@ procedures `make-syntactic-closure' and `capture-syntactic-environment'. escape procedure. The binding of `exit' is intended to capture free references to `exit' in the body of the loop, so `exit' must be left free when the body is closed: + (define-syntax loop (transformer (lambda (exp env) @@ -1248,6 +1677,7 @@ procedures `make-syntactic-closure' and `capture-syntactic-environment'. An example will make this clear. Suppose we wanted to define a simple `loop-until' keyword equivalent to + (define-syntax loop-until (syntax-rules () ((loop-until id init test return step) @@ -1291,6 +1721,7 @@ procedures `make-syntactic-closure' and `capture-syntactic-environment'. the identifier loop has been added. `capture-syntactic-environment' captures exactly that environment as follows: + (define-syntax loop-until (transformer (lambda (exp env) @@ -1321,6 +1752,7 @@ procedures `make-syntactic-closure' and `capture-syntactic-environment'. A common use of `capture-syntactic-environment' is to get the transformer environment of a macro transformer: + (transformer (lambda (exp env) (capture-syntactic-environment @@ -1330,7 +1762,7 @@ procedures `make-syntactic-closure' and `capture-syntactic-environment'. Identifiers ........... - This section describes the procedures that create and manipulate +This section describes the procedures that create and manipulate identifiers. Previous syntactic closure proposals did not have an identifier data type - they just used symbols. The identifier data type extends the syntactic closures facility to be compatible with the @@ -1339,6 +1771,7 @@ high-level `syntax-rules' facility. As discussed earlier, an identifier is either a symbol or an "alias". An alias is implemented as a syntactic closure whose "form" is an identifier: + (make-syntactic-closure env '() 'a) => an "alias" @@ -1362,6 +1795,7 @@ roles of the substituted input subforms. - Function: identifier? object Returns `#t' if OBJECT is an identifier, otherwise returns `#f'. Examples: + (identifier? 'a) => #t (identifier? (make-syntactic-closure env '() 'a)) @@ -1428,11 +1862,10 @@ roles of the substituted input subforms. Acknowledgements ................ - The syntactic closures facility was invented by Alan Bawden and -Jonathan Rees. The use of aliases to implement `syntax-rules' was -invented by Alan Bawden (who prefers to call them "synthetic names"). -Much of this proposal is derived from an earlier proposal by Alan -Bawden. +The syntactic closures facility was invented by Alan Bawden and Jonathan +Rees. The use of aliases to implement `syntax-rules' was invented by +Alan Bawden (who prefers to call them "synthetic names"). Much of this +proposal is derived from an earlier proposal by Alan Bawden. File: slib.info, Node: Syntax-Case Macros, Next: Fluid-Let, Prev: Syntactic Closures, Up: Scheme Syntax Extension Packages @@ -1440,7 +1873,7 @@ File: slib.info, Node: Syntax-Case Macros, Next: Fluid-Let, Prev: Syntactic C Syntax-Case Macros ================== - `(require 'syntax-case)' +`(require 'syntax-case)' - Function: macro:expand expression - Function: syncase:expand expression @@ -1465,9 +1898,9 @@ Syntax-Case Macros This is version 2.1 of `syntax-case', the low-level macro facility proposed and implemented by Robert Hieb and R. Kent Dybvig. - This version is further adapted by Harald Hanche-Olsen <hanche @ | -imf.unit.no> to make it compatible with, and easily usable with, SLIB. | -Mainly, these adaptations consisted of: | + This version is further adapted by Harald Hanche-Olsen <hanche @ +imf.unit.no> to make it compatible with, and easily usable with, SLIB. +Mainly, these adaptations consisted of: * Removing white space from `expand.pp' to save space in the distribution. This file is not meant for human readers anyway... @@ -1510,7 +1943,7 @@ Gambit). Notes ----- - All R4RS syntactic forms are defined, including `delay'. Along with +All R4RS syntactic forms are defined, including `delay'. Along with `delay' are simple definitions for `make-promise' (into which `delay' expressions expand) and `force'. @@ -1537,12 +1970,14 @@ 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). -Note from maintainer --------------------- +Note from SLIB maintainer | +------------------------- | - Included with the `syntax-case' files was `structure.scm' which -defines a macro `define-structure'. There is no documentation for this -macro and it is not used by any code in SLIB. +`(require 'structure)' | + | + Included with the `syntax-case' files was `structure.scm' which | +defines a macro `define-structure'. I have no documentation for this | +macro; it is not used by any other code in SLIB. | File: slib.info, Node: Fluid-Let, Next: Yasos, Prev: Syntax-Case Macros, Up: Scheme Syntax Extension Packages @@ -1550,7 +1985,7 @@ File: slib.info, Node: Fluid-Let, Next: Yasos, Prev: Syntax-Case Macros, Up: Fluid-Let ========= - `(require 'fluid-let)' +`(require 'fluid-let)' - Syntax: fluid-let `(BINDINGS ...)' FORMS... @@ -1575,7 +2010,7 @@ File: slib.info, Node: Yasos, Prev: Fluid-Let, Up: Scheme Syntax Extension Pa Yasos ===== - `(require 'oop)' or `(require 'yasos)' +`(require 'oop)' or `(require 'yasos)' `Yet Another Scheme Object System' is a simple object system for Scheme based on the paper by Norman Adams and Jonathan Rees: `Object @@ -1677,16 +2112,15 @@ File: slib.info, Node: Setters, Next: Yasos examples, Prev: Yasos interface, Setters ------- - "Setters" implement "generalized locations" for objects associated -with some sort of mutable state. A "getter" operation retrieves a -value from a generalized location and the corresponding setter -operation stores a value into the location. Only the getter is named - -the setter is specified by a procedure call as below. (Dylan uses -special syntax.) Typically, but not necessarily, getters are access -operations to extract values from Yasos objects (*note Yasos::). -Several setters are predefined, corresponding to getters `car', `cdr', -`string-ref' and `vector-ref' e.g., `(setter car)' is equivalent to -`set-car!'. +"Setters" implement "generalized locations" for objects associated with +some sort of mutable state. A "getter" operation retrieves a value +from a generalized location and the corresponding setter operation +stores a value into the location. Only the getter is named - the +setter is specified by a procedure call as below. (Dylan uses special +syntax.) Typically, but not necessarily, getters are access operations +to extract values from Yasos objects (*note Yasos::). Several setters +are predefined, corresponding to getters `car', `cdr', `string-ref' and +`vector-ref' e.g., `(setter car)' is equivalent to `set-car!'. This implementation of setters is similar to that in Dylan(TM) (`Dylan: An object-oriented dynamic language', Apple Computer Eastern @@ -1753,7 +2187,7 @@ Examples ((string? obj) (string-length obj)) ((char? obj) 1) (else - (error "Operation not supported: size" obj)))) + (slib:error "Operation not supported: size" obj)))) (define-predicate cell?) (define-operation (fetch obj)) @@ -1842,13 +2276,14 @@ Textual Conversion Packages * Format:: Common-Lisp Format * Standard Formatted I/O:: Posix printf and scanf * Programs and Arguments:: -* HTML:: +* HTML:: Generating * HTML Tables:: Databases meet HTML * HTTP and CGI:: Serve WWW sites +* Parsing HTML:: 'html-for-each * URI:: Uniform Resource Identifier * Printing Scheme:: Nicely * Time and Date:: -* Vector Graphics:: +* NCBI-DNA:: DNA and protein sequences * Schmooz:: Documentation markup for Scheme programs @@ -1857,7 +2292,7 @@ File: slib.info, Node: Precedence Parsing, Next: Format, Prev: Textual Conver Precedence Parsing ================== - `(require 'precedence-parse)' or `(require 'parse)' +`(require 'precedence-parse)' or `(require 'parse)' This package implements: @@ -1873,13 +2308,14 @@ This package implements: * Menu: * Precedence Parsing Overview:: +* Rule Types:: * Ruleset Definition and Use:: * Token definition:: * Nud and Led Definition:: * Grammar Rule Definition:: -File: slib.info, Node: Precedence Parsing Overview, Next: Ruleset Definition and Use, Prev: Precedence Parsing, Up: Precedence Parsing +File: slib.info, Node: Precedence Parsing Overview, Next: Rule Types, Prev: Precedence Parsing, Up: Precedence Parsing Precedence Parsing Overview --------------------------- @@ -1900,6 +2336,35 @@ This package offers improvements over previous parsers. structure as was parsed when the error occured; The symbol `?' is substituted for missing input. +The notion of "binding power" may be unfamiliar to those accustomed to +BNF grammars. + +When two consecutive objects are parsed, the first might be the prefix +to the second, or the second might be a suffix of the first. Comparing +the left and right binding powers of the two objects decides which way +to interpret them. + +Objects at each level of syntactic grouping have binding powers. + +A syntax tree is not built unless the rules explicitly do so. The call +graph of grammar rules effectively instantiate the sytnax tree. + +The JACAL symbolic math system +(<http://swissnet.ai.mit.edu/~jaffer/JACAL.html>) uses +precedence-parse. Its grammar definitions in the file +`jacal/English.scm' can serve as examples of use. + + ---------- Footnotes ---------- + + (1) How do I know this? I parsed 250kbyte of random input (an e-mail +file) with a non-trivial grammar utilizing all constructs. + + +File: slib.info, Node: Rule Types, Next: Ruleset Definition and Use, Prev: Precedence Parsing Overview, Up: Precedence Parsing + +Rule Types +---------- + Here are the higher-level syntax types and an example of each. Precedence considerations are omitted for clarity. See *Note Grammar Rule Definition:: for full details. @@ -1944,13 +2409,8 @@ Rule Definition:: for full details. set foo bar; delimits the extent of the restfix operator `set'. - ---------- Footnotes ---------- - - (1) How do I know this? I parsed 250kbyte of random input (an e-mail -file) with a non-trivial grammar utilizing all constructs. - -File: slib.info, Node: Ruleset Definition and Use, Next: Token definition, Prev: Precedence Parsing Overview, Up: Precedence Parsing +File: slib.info, Node: Ruleset Definition and Use, Next: Token definition, Prev: Rule Types, Up: Precedence Parsing Ruleset Definition and Use -------------------------- @@ -2064,14 +2524,22 @@ The following convenient constants are provided for use with Is the string consisting of all characters between 0 and 255 for which `char-whitespace?' returns true. +For the purpose of reporting problems in error messages, this package | +keeps track of the "current column". When the column does not simply | +track input characters, `tok:bump-column' can be used to adjust the | +current-column. | + | + - Function: tok:bump-column pos port | + Adds POS to the current-column for input-port PORT. | + | File: slib.info, Node: Nud and Led Definition, Next: Grammar Rule Definition, Prev: Token definition, Up: Precedence Parsing Nud and Led Definition ---------------------- - This section describes advanced features. You can skip this section -on first reading. +This section describes advanced features. You can skip this section on +first reading. The "Null Denotation" (or "nud") of a token is the procedure and arguments applying for that token when "Left", an unclaimed parsed @@ -2300,458 +2768,9 @@ File: slib.info, Node: Format, Next: Standard Formatted I/O, Prev: Precedence Format (version 3.0) ==================== - `(require 'format)' - -* Menu: - -* Format Interface:: -* Format Specification:: - - -File: slib.info, Node: Format Interface, Next: Format Specification, Prev: Format, Up: Format - -Format Interface ----------------- - - - Function: format destination format-string . arguments - An almost complete implementation of Common LISP format description - according to the CL reference book `Common LISP' from Guy L. - Steele, Digital Press. Backward compatible to most of the - available Scheme format implementations. - - Returns `#t', `#f' or a string; has side effect of printing - according to FORMAT-STRING. If DESTINATION is `#t', the output is - to the current output port and `#t' is returned. If DESTINATION - is `#f', a formatted string is returned as the result of the call. - NEW: If DESTINATION is a string, DESTINATION is regarded as the - format string; FORMAT-STRING is then the first argument and the - output is returned as a string. If DESTINATION is a number, the - output is to the current error port if available by the - implementation. Otherwise DESTINATION must be an output port and - `#t' is returned. - - FORMAT-STRING must be a string. In case of a formatting error - format returns `#f' and prints a message on the current output or - error port. Characters are output as if the string were output by - the `display' function with the exception of those prefixed by a - tilde (~). For a detailed description of the FORMAT-STRING syntax - please consult a Common LISP format reference manual. For a test - suite to verify this format implementation load `formatst.scm'. - Please send bug reports to `lutzeb@cs.tu-berlin.de'. - - Note: `format' is not reentrant, i.e. only one `format'-call may - be executed at a time. - - - -File: slib.info, Node: Format Specification, Prev: Format Interface, Up: Format - -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 `formatst.scm'. - - This implementation supports directive parameters and modifiers (`:' -and `@' characters). Multiple parameters must be separated by a comma -(`,'). Parameters can be numerical parameters (positive or negative), -character parameters (prefixed by a quote character (`''), variable -parameters (`v'), number of rest arguments parameter (`#'), empty and -default parameters. Directive characters are case independent. The -general form of a directive is: - -DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER - -DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ] - -Implemented CL Format Control Directives -........................................ - - Documentation syntax: Uppercase characters represent the corresponding -control directive characters. Lowercase characters represent control -directive parameter descriptions. - -`~A' - Any (print as `display' does). - `~@A' - left pad. - - `~MINCOL,COLINC,MINPAD,PADCHARA' - full padding. - -`~S' - S-expression (print as `write' does). - `~@S' - left pad. - - `~MINCOL,COLINC,MINPAD,PADCHARS' - full padding. - -`~D' - Decimal. - `~@D' - print number sign always. - - `~:D' - print comma separated. - - `~MINCOL,PADCHAR,COMMACHARD' - padding. - -`~X' - Hexadecimal. - `~@X' - print number sign always. - - `~:X' - print comma separated. - - `~MINCOL,PADCHAR,COMMACHARX' - padding. - -`~O' - Octal. - `~@O' - print number sign always. - - `~:O' - print comma separated. - - `~MINCOL,PADCHAR,COMMACHARO' - padding. - -`~B' - Binary. - `~@B' - print number sign always. - - `~:B' - print comma separated. - - `~MINCOL,PADCHAR,COMMACHARB' - padding. - -`~NR' - Radix N. - `~N,MINCOL,PADCHAR,COMMACHARR' - padding. - -`~@R' - print a number as a Roman numeral. - -`~:@R' - print a number as an "old fashioned" Roman numeral. - -`~:R' - print a number as an ordinal English number. - -`~R' - print a number as a cardinal English number. - -`~P' - Plural. - `~@P' - prints `y' and `ies'. - - `~:P' - as `~P but jumps 1 argument backward.' - - `~:@P' - as `~@P but jumps 1 argument backward.' - -`~C' - Character. - `~@C' - prints a character as the reader can understand it (i.e. `#\' - prefixing). - - `~:C' - prints a character as emacs does (eg. `^C' for ASCII 03). - -`~F' - Fixed-format floating-point (prints a flonum like MMM.NNN). - `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF' - - `~@F' - If the number is positive a plus sign is printed. - -`~E' - Exponential floating-point (prints a flonum like MMM.NNN`E'EE). - `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE' - - `~@E' - If the number is positive a plus sign is printed. - -`~G' - General floating-point (prints a flonum either fixed or - exponential). - `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG' - - `~@G' - If the number is positive a plus sign is printed. - -`~$' - Dollars floating-point (prints a flonum in fixed with signs - separated). - `~DIGITS,SCALE,WIDTH,PADCHAR$' - - `~@$' - If the number is positive a plus sign is printed. - - `~:@$' - A sign is always printed and appears before the padding. - - `~:$' - The sign appears before the padding. - -`~%' - Newline. - `~N%' - print N newlines. - -`~&' - print newline if not at the beginning of the output line. - `~N&' - prints `~&' and then N-1 newlines. - -`~|' - Page Separator. - `~N|' - print N page separators. - -`~~' - Tilde. - `~N~' - print N tildes. - -`~'<newline> - Continuation Line. - `~:'<newline> - newline is ignored, white space left. - - `~@'<newline> - newline is left, white space ignored. - -`~T' - Tabulation. - `~@T' - relative tabulation. - - `~COLNUM,COLINCT' - full tabulation. - -`~?' - Indirection (expects indirect arguments as a list). - `~@?' - extracts indirect arguments from format arguments. - -`~(STR~)' - Case conversion (converts by `string-downcase'). - `~:(STR~)' - converts by `string-capitalize'. - - `~@(STR~)' - converts by `string-capitalize-first'. - - `~:@(STR~)' - converts by `string-upcase'. - -`~*' - Argument Jumping (jumps 1 argument forward). - `~N*' - jumps N arguments forward. - - `~:*' - jumps 1 argument backward. - - `~N:*' - jumps N arguments backward. - - `~@*' - jumps to the 0th argument. - - `~N@*' - jumps to the Nth argument (beginning from 0) - -`~[STR0~;STR1~;...~;STRN~]' - Conditional Expression (numerical clause conditional). - `~N[' - take argument from N. - - `~@[' - true test conditional. - - `~:[' - if-else-then conditional. - - `~;' - clause separator. - - `~:;' - default clause follows. - -`~{STR~}' - Iteration (args come from the next argument (a list)). - `~N{' - at most N iterations. - - `~:{' - args from next arg (a list of lists). - - `~@{' - args from the rest of arguments. - - `~:@{' - args from the rest args (lists). - -`~^' - Up and out. - `~N^' - aborts if N = 0 - - `~N,M^' - aborts if N = M - - `~N,M,K^' - aborts if N <= M <= K - -Not Implemented CL Format Control Directives -............................................ - -`~:A' - print `#f' as an empty list (see below). - -`~:S' - print `#f' as an empty list (see below). - -`~<~>' - Justification. - -`~:^' - (sorry I don't understand its semantics completely) - -Extended, Replaced and Additional Control Directives -.................................................... - -`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD' - -`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX' - -`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO' - -`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB' - -`~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR' - COMMAWIDTH is the number of characters between two comma - characters. - -`~I' - print a R4RS complex number as `~F~@Fi' with passed parameters for - `~F'. - -`~Y' - Pretty print formatting of an argument for scheme code lists. - -`~K' - Same as `~?.' - -`~!' - Flushes the output if format DESTINATION is a port. - -`~_' - Print a `#\space' character - `~N_' - print N `#\space' characters. - -`~/' - Print a `#\tab' character - `~N/' - print N `#\tab' characters. - -`~NC' - Takes N as an integer representation for a character. No arguments - are consumed. N is converted to a character by `integer->char'. N - must be a positive decimal number. - -`~:S' - Print out readproof. Prints out internal objects represented as - `#<...>' as strings `"#<...>"' so that the format output can always - be processed by `read'. - -`~:A' - Print out readproof. Prints out internal objects represented as - `#<...>' as strings `"#<...>"' so that the format output can always - be processed by `read'. - -`~Q' - Prints information and a copyright notice on the format - implementation. - `~:Q' - prints format version. - -`~F, ~E, ~G, ~$' - may also print number strings, i.e. passing a number as a string - and format it accordingly. - -Configuration Variables -....................... - - Format has some configuration variables at the beginning of -`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. - -FORMAT:SYMBOL-CASE-CONV - Symbols are converted by `symbol->string' so the case type of the - printed symbols is implementation dependent. - `format:symbol-case-conv' is a one arg closure which is either - `#f' (no conversion), `string-upcase', `string-downcase' or - `string-capitalize'. (default `#f') - -FORMAT:IOBJ-CASE-CONV - As FORMAT:SYMBOL-CASE-CONV but applies for the representation of - implementation internal objects. (default `#f') - -FORMAT:EXPCH - The character prefixing the exponent value in `~E' printing. - (default `#\E') - -Compatibility With Other Format Implementations -............................................... - -SLIB format 2.x: - See `format.doc'. - -SLIB format 1.4: - Downward compatible except for padding support and `~A', `~S', - `~P', `~X' uppercase printing. SLIB format 1.4 uses C-style - `printf' padding support which is completely replaced by the CL - `format' padding style. - -MIT C-Scheme 7.1: - Downward compatible except for `~', which is not documented - (ignores all characters inside the format string up to a newline - character). (7.1 implements `~a', `~s', ~NEWLINE, `~~', `~%', - numerical and variable parameters and `:/@' modifiers in the CL - sense). - -Elk 1.5/2.0: - Downward compatible except for `~A' and `~S' which print in - uppercase. (Elk implements `~a', `~s', `~~', and `~%' (no - directive parameters or modifiers)). - -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 `~a', `~s', `~c', `~%', and `~~' (no directive - parameters or modifiers)). - - This implementation of format is solely useful in the SLIB context -because it requires other components provided by SLIB. +The `format.scm' package was removed because it was not reentrant. | +<http://swissnet.ai.mit.edu/~jaffer/SLIB.FAQ> explains more about | +FORMAT's woes. | File: slib.info, Node: Standard Formatted I/O, Next: Programs and Arguments, Prev: Format, Up: Textual Conversion Packages @@ -2767,7 +2786,7 @@ Standard Formatted I/O stdio ----- - `(require 'stdio)' +`(require 'stdio)' `require's `printf' and `scanf' and additionally defines the symbols: @@ -2786,7 +2805,7 @@ File: slib.info, Node: Standard Formatted Output, Next: Standard Formatted Inp Standard Formatted Output ------------------------- - `(require 'printf)' +`(require 'printf)' - Procedure: printf format arg1 ... - Procedure: fprintf port format arg1 ... @@ -2921,11 +2940,11 @@ Standard Formatted Output Exact Conversions ................. - `b', `B' | - Print an integer as an unsigned binary number. | - | - _Note:_ `%b' and `%B' are SLIB extensions. | - | + `b', `B' + Print an integer as an unsigned binary number. + + _Note:_ `%b' and `%B' are SLIB extensions. + `d', `i' Print an integer as a signed decimal number. `%d' and `%i' are synonymous for output, but are different when used with @@ -2966,6 +2985,7 @@ Inexact Conversions after the number, which is scaled accordingly. `%K' outputs a space between number and prefix, `%k' does not. + Other Conversions ................. @@ -2991,8 +3011,8 @@ Other Conversions `%' Print a literal `%' character. No argument is consumed. It - is an error to specify flags, field width, precision, or type | - modifiers with `%%'. | + is an error to specify flags, field width, precision, or type + modifiers with `%%'. File: slib.info, Node: Standard Formatted Input, Prev: Standard Formatted Output, Up: Standard Formatted I/O @@ -3000,7 +3020,7 @@ File: slib.info, Node: Standard Formatted Input, Prev: Standard Formatted Outp Standard Formatted Input ------------------------ - `(require 'scanf)' +`(require 'scanf)' - Function: scanf-read-list format - Function: scanf-read-list format port @@ -3174,49 +3194,65 @@ File: slib.info, Node: Getopt, Next: Command Line, Prev: Programs and Argumen Getopt ------ - `(require 'getopt)' +`(require 'getopt)' This routine implements Posix command line argument parsing. Notice that returning values through global variables means that `getopt' is _not_ reentrant. + Obedience to Posix format for the `getopt' calls sows confusion. +Passing ARGC and ARGV as arguments while referencing OPTIND as a global +variable leads to strange behavior, especially when the calls to +`getopt' are buried in other procedures. + + Even in C, ARGC can be derived from ARGV; what purpose does it serve +beyond providing an opportunity for ARGV/ARGC mismatch? Just such a +mismatch existed for years in a SLIB `getopt--' example. + + I have removed the ARGC and ARGV arguments to getopt procedures; and +replaced them with a global variable: + + - Variable: *argv* + Define *ARGV* with a list of arguments before calling getopt + procedures. If you don't want the first (0th) element to be + ignored, set *OPTIND* to 0 (after requiring getopt). + - Variable: *optind* Is the index of the current element of the command line. It is initially one. In order to parse a new command line or reparse an - old one, *OPTING* must be reset. + old one, *OPTIND* must be reset. - Variable: *optarg* Is set by getopt to the (string) option-argument of the current option. - - Procedure: getopt argc argv optstring - Returns the next option letter in ARGV (starting from `(vector-ref - argv *optind*)') that matches a letter in OPTSTRING. ARGV is a - vector or list of strings, the 0th of which getopt usually - ignores. ARGC is the argument count, usually the length of ARGV. - OPTSTRING is a string of recognized option characters; if a - character is followed by a colon, the option takes an argument - which may be immediately following it in the string or in the next - element of ARGV. - - *OPTIND* is the index of the next element of the ARGV vector to be - processed. It is initialized to 1 by `getopt.scm', and `getopt' - updates it when it finishes with each element of ARGV. - - `getopt' returns the next option character from ARGV that matches - a character in OPTSTRING, if there is one that matches. If the - option takes an argument, `getopt' sets the variable *OPTARG* to - the option-argument as follows: + - Function: getopt optstring | + Returns the next option letter in *ARGV* (starting from + `(vector-ref argv *optind*)') that matches a letter in OPTSTRING. + *ARGV* is a vector or list of strings, the 0th of which getopt + usually ignores. OPTSTRING is a string of recognized option + characters; if a character is followed by a colon, the option + takes an argument which may be immediately following it in the + string or in the next element of *ARGV*. + + *OPTIND* is the index of the next element of the *ARGV* vector to + be processed. It is initialized to 1 by `getopt.scm', and + `getopt' updates it when it finishes with each element of *ARGV*. + + `getopt' returns the next option character from *ARGV* that + matches a character in OPTSTRING, if there is one that matches. + If the option takes an argument, `getopt' sets the variable + *OPTARG* to the option-argument as follows: * If the option was the last character in the string pointed to - by an element of ARGV, then *OPTARG* contains the next - element of ARGV, and *OPTIND* is incremented by 2. If the - resulting value of *OPTIND* is greater than or equal to ARGC, - this indicates a missing option argument, and `getopt' - returns an error indication. + by an element of *ARGV*, then *OPTARG* contains the next + element of *ARGV*, and *OPTIND* is incremented by 2. If the + resulting value of *OPTIND* is greater than or equal to + `(length *ARGV*)', this indicates a missing option argument, + and `getopt' returns an error indication. * Otherwise, *OPTARG* is set to the string following the option - character in that element of ARGV, and *OPTIND* is + character in that element of *ARGV*, and *OPTIND* is incremented by 1. If, when `getopt' is called, the string `(vector-ref argv @@ -3273,10 +3309,10 @@ _not_ reentrant. (slib:exit) -Getopt- -------- +Getopt-- +-------- - - Function: getopt- argc argv optstring + - Function: `getopt--' optstring | The procedure `getopt--' is an extended version of `getopt' which parses "long option names" of the form `--hold-the-onions' and `--verbosity-level=extreme'. `Getopt--' behaves as `getopt' @@ -3289,20 +3325,19 @@ Getopt- No information is passed to `getopt--' concerning which long options should be accepted or whether such options can take - arguments. If a long option did not have an argument, `*optarg' + arguments. If a long option did not have an argument, `*optarg*' will be set to `#f'. The caller is responsible for detecting and reporting errors. (define opts ":-:b:") - (define argc 5) - (define argv '("foo" "-b9" "--f1" "--2=" "--g3=35234.342" "--")) + (define *argv* '("foo" "-b9" "--f1" "--2=" "--g3=35234.342" "--")) (define *optind* 1) (define *optarg* #f) (require 'qp) (do ((i 5 (+ -1 i))) ((zero? i)) - (define opt (getopt-- argc argv opts)) - (print *optind* opt *optarg*))) + (let ((opt (getopt-- opts))) + (print *optind* opt *optarg*))) -| 2 #\b "9" 3 "f1" #f @@ -3316,7 +3351,7 @@ File: slib.info, Node: Command Line, Next: Parameter lists, Prev: Getopt, Up Command Line ------------ - `(require 'read-command)' +`(require 'read-command)' - Function: read-command port - Function: read-command @@ -3391,7 +3426,7 @@ File: slib.info, Node: Parameter lists, Next: Getopt Parameter lists, Prev: C Parameter lists --------------- - `(require 'parameters)' +`(require 'parameters)' Arguments to procedures in scheme are distinguished from each other by their position in the procedure call. This can be confusing when a @@ -3487,11 +3522,11 @@ File: slib.info, Node: Getopt Parameter lists, Next: Filenames, Prev: Paramet Getopt Parameter lists ---------------------- - `(require 'getopt-parameters)' +`(require 'getopt-parameters)' - - Function: getopt->parameter-list argc argv optnames arities types - aliases desc ... - Returns ARGV converted to a parameter-list. OPTNAMES are the + - Function: getopt->parameter-list optnames arities types aliases desc + ... + Returns *ARGV* converted to a parameter-list. OPTNAMES are the parameter-names. ARITIES and TYPES are lists of symbols corresponding to OPTNAMES. @@ -3516,16 +3551,16 @@ Getopt Parameter lists In all cases, if unclaimed arguments remain after processing, a warning is signaled and #f is returned. - - Function: getopt->arglist argc argv optnames positions arities types + - Function: getopt->arglist optnames positions arities types defaulters checks aliases desc ... - Like `getopt->parameter-list', but converts ARGV to an + Like `getopt->parameter-list', but converts *ARGV* to an argument-list as specified by OPTNAMES, POSITIONS, ARITIES, TYPES, DEFAULTERS, CHECKS, and ALIASES. If the options supplied violate the ARITIES or CHECKS constraints, then a warning is signaled and #f is returned. These `getopt' functions can be used with SLIB relational databases. -For an example, *Note make-command-server: Database Utilities. +For an example, *Note make-command-server: Using Databases. If errors are encountered while processing options, directions for using the options (and argument strings DESC ...) are printed to @@ -3533,9 +3568,8 @@ the options (and argument strings DESC ...) are printed to (begin (set! *optind* 1) + (set! *argv* '("cmd" "-?") (getopt->parameter-list - 2 - '("cmd" "-?") '(flag number symbols symbols string flag2 flag3 num2 num3) '(boolean optional nary1 nary single boolean boolean nary nary) '(boolean integer symbol symbol string boolean boolean integer integer) @@ -3574,7 +3608,7 @@ File: slib.info, Node: Filenames, Next: Batch, Prev: Getopt Parameter lists, Filenames --------- - `(require 'filename)' or `(require 'glob)' +`(require 'filename)' or `(require 'glob)' - Function: filename:match?? pattern - Function: filename:match-ci?? pattern @@ -3601,7 +3635,6 @@ Filenames `-' or `]' may be matched by including it as the first or last character in the set. - - Function: filename:substitute?? pattern template - Function: filename:substitute-ci?? pattern template Returns a function transforming a single string argument according @@ -3622,15 +3655,16 @@ Filenames substrings matched by wildcard specifications will be returned, otherwise TEMPLATE will not be called and `#f' will be returned. - ((filename:substitute?? "scm_[0-9]*.html" "scm5c4_??.htm") - "scm_10.html") - => "scm5c4_10.htm" - ((filename:substitute?? "??" "beg?mid?end") "AZ") - => "begAmidZend" - ((filename:substitute?? "*na*" "?NA?") "banana") - => "banaNA" - ((filename:substitute?? "?*?" (lambda (s1 s2 s3) (string-append s3 s1))) "ABZ") - => "ZA" + ((filename:substitute?? "scm_[0-9]*.html" "scm5c4_??.htm") + "scm_10.html") + => "scm5c4_10.htm" + ((filename:substitute?? "??" "beg?mid?end") "AZ") + => "begAmidZend" + ((filename:substitute?? "*na*" "?NA?") "banana") + => "banaNA" + ((filename:substitute?? "?*?" (lambda (s1 s2 s3) (string-append s3 s1))) | + "ABZ") | + => "ZA" - Function: replace-suffix str old new STR can be a string or a list of strings. Returns a new string @@ -3638,16 +3672,31 @@ Filenames removed and the suffix string NEW appended. If the end of STR does not match OLD, an error is signaled. - (replace-suffix "/usr/local/lib/slib/batch.scm" ".scm" ".c") - => "/usr/local/lib/slib/batch.c" + (replace-suffix "/usr/local/lib/slib/batch.scm" ".scm" ".c") + => "/usr/local/lib/slib/batch.c" + - Function: call-with-tmpnam proc k | + - Function: call-with-tmpnam proc | + Calls PROC with K arguments, strings returned by successive calls | + to `tmpnam'. If PROC returns, then any files named by the | + arguments to PROC are deleted automatically and the value(s) | + yielded by the PROC is(are) returned. K may be ommited, in which | + case it defaults to `1'. | + | + - Function: call-with-tmpnam proc suffix1 ... | + Calls PROC with strings returned by successive calls to `tmpnam', | + each with the corresponding SUFFIX string appended. If PROC | + returns, then any files named by the arguments to PROC are deleted | + automatically and the value(s) yielded by the PROC is(are) | + returned. | + | File: slib.info, Node: Batch, Prev: Filenames, Up: Programs and Arguments Batch ----- - `(require 'batch)' +`(require 'batch)' The batch procedures provide a way to write and execute portable scripts for a variety of operating systems. Each `batch:' procedure takes as @@ -3666,24 +3715,24 @@ currently uses 2 of these: * vms - * amigados + * amigaos * system * *unknown* -`batch.scm' uses 2 enhanced relational tables (*note Database -Utilities::) to store information linking the names of -`operating-system's to `batch-dialect'es. +`batch.scm' uses 2 enhanced relational tables (*note Using Databases::) +to store information linking the names of `operating-system's to +`batch-dialect'es. - Function: batch:initialize! database Defines `operating-system' and `batch-dialect' tables and adds the domain `operating-system' to the enhanced relational database DATABASE. - - Variable: batch:platform + - Variable: *operating-system* Is batch's best guess as to which operating-system it is running - under. `batch:platform' is set to `(software-type)' (*note + under. `*operating-system*' is set to `(software-type)' (*note Configuration::) unless `(software-type)' is `unix', in which case finer distinctions are made. @@ -3785,7 +3834,7 @@ scripts: Here is an example of the use of most of batch's procedures: - (require 'database-utilities) + (require 'databases) (require 'parameters) (require 'batch) (require 'glob) @@ -3794,8 +3843,8 @@ Here is an example of the use of most of batch's procedures: (batch:initialize! batch) (define my-parameters - (list (list 'batch-dialect (os->batch-dialect batch:platform)) - (list 'platform batch:platform) + (list (list 'batch-dialect (os->batch-dialect *operating-system*)) + (list 'operating-system *operating-system*) (list 'batch-port (current-output-port)))) ;gets filled in later (batch:call-with-output-script @@ -3826,7 +3875,7 @@ Here is an example of the use of most of batch's procedures: Produces the file `my-batch': - #!/bin/sh + #! /bin/sh # "my-batch" script created by SLIB/batch Sun Oct 31 18:24:10 1999 # ================ Write file with C program. mv -f hello.c hello.c~ @@ -3857,7 +3906,7 @@ File: slib.info, Node: HTML, Next: HTML Tables, Prev: Programs and Arguments, HTML ==== - `(require 'html-form)' +`(require 'html-form)' - Function: html:atval txt Returns a string with character substitutions appropriate to send @@ -3994,6 +4043,12 @@ HTML Forms delimited list. Apply map `form:delimited' to the list returned by `command->p-specs'. + - Function: html:delimited-list row ... | + Wraps its arguments with delimited-list (`DL' command. | + | + - Function: get-foreign-choices tab | + Returns a list of the `visible-name' or first fields of table TAB. | + | - Function: command->p-specs rdb command-table command The symbol COMMAND-TABLE names a command table in the RDB relational database. The symbol COMMAND names a key in @@ -4014,16 +4069,16 @@ HTML Forms (html:head 'commands) (html:body (sprintf #f "<H2>%s:</H2><BLOCKQUOTE>%s</BLOCKQUOTE>\\n" - (html:plain 'build) - (html:plain ((comtab 'get 'documentation) 'build))) + (html:plain 'build) + (html:plain ((comtab 'get 'documentation) 'build))) (html:form - 'post - (or "http://localhost:8081/buildscm" "/cgi-bin/build.cgi") - (apply html:delimited-list - (apply map form:delimited - (command->p-specs build '*commands* 'build))) - (form:submit 'build) - (form:reset)))) + 'post + (or "http://localhost:8081/buildscm" "/cgi-bin/build.cgi") + (apply html:delimited-list + (apply map form:delimited + (command->p-specs build '*commands* 'build))) + (form:submit 'build) + (form:reset)))) port))) @@ -4032,7 +4087,7 @@ File: slib.info, Node: HTML Tables, Next: HTTP and CGI, Prev: HTML, Up: Text HTML Tables =========== - `(require 'db->html)' +`(require 'db->html)' - Function: html:table options row ... @@ -4116,10 +4171,11 @@ performed. - Function: command:modify-table table-name null-keys update - Function: command:modify-table table-name null-keys Returns procedure (of DB) which returns procedure to modify row of - TABLE-NAME. NULL-KEYS is the list of "null" keys which indicate - that the row is to be deleted. Optional arguments UPDATE, DELETE, - and RETRIEVE default to the `row:update', `row:delete', and - `row:retrieve' of TABLE-NAME in DB. + TABLE-NAME. NULL-KEYS is the list of "null" keys indicating the + row is to be deleted when any matches its corresponding primary + key. Optional arguments UPDATE, DELETE, and RETRIEVE default to + the `row:update', `row:delete', and `row:retrieve' of TABLE-NAME + in DB. - Function: command:make-editable-table rdb table-name arg ... Given TABLE-NAME in RDB, creates parameter and `*command*' tables @@ -4184,16 +4240,16 @@ HTML databases - Function: db->netscape db dir index-filename - Function: db->netscape db dir `db->netscape' is just like `db->html-directory', but calls - `browse-url-netscape' with the uri for the top page after the - pages are created. + `browse-url' with the uri for the top page after the pages are + created. -File: slib.info, Node: HTTP and CGI, Next: URI, Prev: HTML Tables, Up: Textual Conversion Packages +File: slib.info, Node: HTTP and CGI, Next: Parsing HTML, Prev: HTML Tables, Up: Textual Conversion Packages HTTP and CGI ============ - `(require 'http)' or `(require 'cgi)' +`(require 'http)' or `(require 'cgi)' - Function: http:header alist Returns a string containing lines for each element of ALIST; the @@ -4287,12 +4343,79 @@ HTTP and CGI arguments described in its table. -File: slib.info, Node: URI, Next: Printing Scheme, Prev: HTTP and CGI, Up: Textual Conversion Packages +File: slib.info, Node: Parsing HTML, Next: URI, Prev: HTTP and CGI, Up: Textual Conversion Packages + +Parsing HTML +============ + +`(require 'html-for-each)' + + - Function: html-for-each file word-proc markup-proc white-proc + newline-proc + FILE is an input port or a string naming an existing file + containing HTML text. WORD-PROC is a procedure of one argument or + #f. MARKUP-PROC is a procedure of one argument or #f. WHITE-PROC + is a procedure of one argument or #f. NEWLINE-PROC is a procedure + of no arguments or #f. + + `html-for-each' opens and reads characters from port FILE or the + file named by string FILE. Sequential groups of characters are + assembled into strings which are either + + * enclosed by `<' and `>' (hypertext markups or comments); + + * end-of-line; + + * whitespace; or + + * none of the above (words). + + Procedures are called according to these distinctions in order of + the string's occurrence in FILE. + + NEWLINE-PROC is called with no arguments for end-of-line _not + within a markup or comment_. + + WHITE-PROC is called with strings of non-newline whitespace. + + MARKUP-PROC is called with hypertext markup strings (including `<' + and `>'). + + WORD-PROC is called with the remaining strings. + + `html-for-each' returns an unspecified value. + + - Function: html:read-title file limit + - Function: html:read-title file + FILE is an input port or a string naming an existing file + containing HTML text. If supplied, LIMIT must be an integer. + LIMIT defaults to 1000. + + `html:read-title' opens and reads HTML from port FILE or the file + named by string FILE, until reaching the (mandatory) `TITLE' + field. `html:read-title' returns the title string with adjacent + whitespaces collapsed to one space. `html:read-title' returns #f + if the title field is empty, absent, if the first character read + from FILE is not `#\<', or if the end of title is not found within + the first (approximately) LIMIT words. + + - Function: htm-fields htm + HTM is a hypertext markup string. + + If HTM is a (hypertext) comment, then `htm-fields' returns #f. + Otherwise `htm-fields' returns the hypertext element symbol + (created by `string-ci->symbol') consed onto an association list + of the attribute name-symbols and values. Each value is a number + or string; or #t if the name had no value assigned within the + markup. + + +File: slib.info, Node: URI, Next: Printing Scheme, Prev: Parsing HTML, Up: Textual Conversion Packages URI === - `(require 'uri)' +`(require 'uri)' Implements "Uniform Resource Identifiers" (URI) as described in RFC 2396. @@ -4306,6 +4429,9 @@ Implements "Uniform Resource Identifiers" (URI) as described in RFC Returns a Uniform Resource Identifier string from component arguments. + - Function: uri:make-path path | + Returns a URI string combining the components of list PATH. | + | - Function: html:anchor name Returns a string which defines this location in the (HTML) file as NAME. The hypertext `<A HREF="#NAME">' will link to this point. @@ -4329,13 +4455,16 @@ Implements "Uniform Resource Identifiers" (URI) as described in RFC Returns a string specifying the search PROMPT of a document, for inclusion in the HEAD of the document (*note head: HTML.). - - Function: uri->tree uri-reference base-tree ... + - Function: uri->tree uri-reference base-tree + - Function: uri->tree uri-reference Returns a list of 5 elements corresponding to the parts (SCHEME AUTHORITY PATH QUERY FRAGMENT) of string URI-REFERENCE. Elements corresponding to absent parts are #f. The PATH is a list of strings. If the first string is empty, then - the path is absolute; otherwise relative. + the path is absolute; otherwise relative. The optional BASE-TREE + is a tree as returned by `uri->tree'; and is used as the base + address for relative URIs. If the AUTHORITY component is a "Server-based Naming Authority", then it is a list of the USERINFO, HOST, and PORT strings (or #f). @@ -4346,6 +4475,13 @@ Implements "Uniform Resource Identifiers" (URI) as described in RFC => (http "www.ics.uci.edu" ("" "pub" "ietf" "uri" "") #f "Related") + - Function: uri:split-fields txt chr | + Returns a list of TXT split at each occurrence of CHR. CHR does | + not appear in the returned list of strings. | + | + - Function: uri:decode-query query-string + Converts a "URI" encoded QUERY-STRING to a query-alist. + `uric:' prefixes indicate procedures dealing with URI-components. - Function: uric:encode uri-component allows @@ -4359,6 +4495,50 @@ Implements "Uniform Resource Identifiers" (URI) as described in RFC it encodes. This routine is useful for showing URI contents on error pages. + - Function: uri:path->keys path-list ptypes | + PATH-LIST is a path-list as returned by `uri:split-fields'. | + `uri:path->keys' returns a list of items returned by | + `uri:decode-path', coerced to types PTYPES. | + | +File-system Locators and Predicates +----------------------------------- + + - Function: path->uri path + Returns a URI-string for PATH on the local host. + + - Function: absolute-uri? str + Returns #t if STR is an absolute-URI as indicated by a + syntactically valid (per RFC 2396) "scheme"; otherwise returns #f. + + - Function: absolute-path? file-name + Returns #t if FILE-NAME is a fully specified pathname (does not + depend on the current working directory); otherwise returns #f. + + - Function: null-directory? str + Returns #t if changing directory to STR would leave the current + directory unchanged; otherwise returns #f. + + - Function: glob-pattern? str + Returns #t if the string STR contains characters used for + specifying glob patterns, namely `*', `?', or `['. + +Before RFC 2396, the "File Transfer Protocol" (FTP) served a similar +purpose. + + - Function: parse-ftp-address uri + Returns a list of the decoded FTP URI; or #f if indecipherable. + FTP "Uniform Resource Locator", "ange-ftp", and "getit" formats + are handled. The returned list has four elements which are + strings or #f: + + 0. username + + 1. password + + 2. remote-site + + 3. remote-directory + File: slib.info, Node: Printing Scheme, Next: Time and Date, Prev: URI, Up: Textual Conversion Packages @@ -4377,7 +4557,7 @@ File: slib.info, Node: Generic-Write, Next: Object-To-String, Prev: Printing Generic-Write ------------- - `(require 'generic-write)' +`(require 'generic-write)' `generic-write' is a procedure that transforms a Scheme data value (or Scheme program expression) into its textual representation and @@ -4421,7 +4601,7 @@ File: slib.info, Node: Object-To-String, Next: Pretty-Print, Prev: Generic-Wr Object-To-String ---------------- - `(require 'object->string)' +`(require 'object->string)' - Function: object->string obj Returns the textual representation of OBJ as a string. @@ -4436,7 +4616,7 @@ File: slib.info, Node: Pretty-Print, Prev: Object-To-String, Up: Printing Sch Pretty-Print ------------ - `(require 'pretty-print)' +`(require 'pretty-print)' - Procedure: pretty-print obj - Procedure: pretty-print obj port @@ -4522,7 +4702,7 @@ thus can reduce loading time. The following will write into (pprint-filter-file "code.scm" defmacro:expand* "exp-code.scm") -File: slib.info, Node: Time and Date, Next: Vector Graphics, Prev: Printing Scheme, Up: Textual Conversion Packages +File: slib.info, Node: Time and Date, Next: NCBI-DNA, Prev: Printing Scheme, Up: Textual Conversion Packages Time and Date ============= @@ -4559,7 +4739,7 @@ File: slib.info, Node: Time Zone, Next: Posix Time, Prev: Time and Date, Up: Time Zone --------- - (require 'time-zone) +(require 'time-zone) - Data Format: TZ-string POSIX standards specify several formats for encoding time-zone @@ -4641,6 +4821,11 @@ Time Zone made of any timezone at any calendar time. + - Function: tz:std-offset tz | + TZ is a time-zone object. `tz:std-offset' returns the number of | + seconds west of the Prime Meridian timezone TZ is. | + | + | The rest of these procedures and variables are provided for POSIX compatability. Because of shared state they are not thread-safe. @@ -4797,81 +4982,53 @@ Common-Lisp Time match the arguments to `encode-universal-time'. -File: slib.info, Node: Vector Graphics, Next: Schmooz, Prev: Time and Date, Up: Textual Conversion Packages - -Vector Graphics -=============== - -* Menu: - -* Tektronix Graphics Support:: - - -File: slib.info, Node: Tektronix Graphics Support, Prev: Vector Graphics, Up: Vector Graphics - -Tektronix Graphics Support --------------------------- - - _Note:_ The Tektronix graphics support files need more work, and are -not complete. - -Tektronix 4000 Series Graphics -.............................. - - The Tektronix 4000 series graphics protocol gives the user a 1024 by -1024 square drawing area. The origin is in the lower left corner of the -screen. Increasing y is up and increasing x is to the right. - - The graphics control codes are sent over the current-output-port and -can be mixed with regular text and ANSI or other terminal control -sequences. +File: slib.info, Node: NCBI-DNA, Next: Schmooz, Prev: Time and Date, Up: Textual Conversion Packages - - Procedure: tek40:init - - - Procedure: tek40:graphics - - - Procedure: tek40:text - - - Procedure: tek40:linetype linetype - - - Procedure: tek40:move x y - - - Procedure: tek40:draw x y - - - Procedure: tek40:put-text x y str - - - Procedure: tek40:reset - -Tektronix 4100 Series Graphics -.............................. +NCBI-DNA +======== - The graphics control codes are sent over the current-output-port and -can be mixed with regular text and ANSI or other terminal control -sequences. + - Function: ncbi:read-dna-sequence port + Reads the NCBI-format DNA sequence following the word `ORIGIN' + from PORT. - - Procedure: tek41:init + - Function: ncbi:read-file file + Reads the NCBI-format DNA sequence following the word `ORIGIN' + from FILE. - - Procedure: tek41:reset + - Function: mrna<-cdna str + Replaces `T' with `U' in STR - - Procedure: tek41:graphics + - Function: codons<-cdna cdna + Returns a list of three-letter symbol codons comprising the protein + sequence encoded by CDNA starting with its first occurence of + `atg'. - - Procedure: tek41:move x y + - Function: protein<-cdna cdna + Returns a list of three-letter symbols for the protein sequence + encoded by CDNA starting with its first occurence of `atg'. - - Procedure: tek41:draw x y + - Function: p<-cdna cdna + Returns a string of one-letter amino acid codes for the protein + sequence encoded by CDNA starting with its first occurence of + `atg'. - - Procedure: tek41:point x y number + These cDNA count routines provide a means to check the nucleotide +sequence with the `BASE COUNT' line preceding the sequence from NCBI. - - Procedure: tek41:encode-x-y x y + - Function: cdna:base-count cdna + Returns a list of counts of `a', `c', `g', and `t' occurrencing in + CDNA. - - Procedure: tek41:encode-int number + - Function: cdna:report-base-count cdna + Prints the counts of `a', `c', `g', and `t' occurrencing in CDNA. -File: slib.info, Node: Schmooz, Prev: Vector Graphics, Up: Textual Conversion Packages +File: slib.info, Node: Schmooz, Prev: NCBI-DNA, Up: Textual Conversion Packages Schmooz ======= - "Schmooz" is a simple, lightweight markup language for interspersing +"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 `txi' files which can be imported into the documentation using the Texinfo command `@include'. @@ -4880,20 +5037,20 @@ imported into the documentation using the Texinfo command `@include'. process files. Files containing schmooz documentation should not contain `(require 'schmooz)'. - - Procedure: schmooz filenamescm ... - FILENAMEscm should be a string ending with `scm' naming an + - Procedure: schmooz filename.scm ... + FILENAME.scm should be a string ending with `.scm' naming an existing file containing Scheme source code. `schmooz' extracts - top-level comments containing schmooz commands from FILENAMEscm + top-level comments containing schmooz commands from FILENAME.scm and writes the converted Texinfo source to a file named - FILENAMEtxi. + FILENAME.txi. - - Procedure: schmooz filenametexi ... - - Procedure: schmooz filenametex ... - - Procedure: schmooz filenametxi ... + - Procedure: schmooz filename.texi ... + - Procedure: schmooz filename.tex ... + - Procedure: schmooz filename.txi ... FILENAME should be a string naming an existing file containing Texinfo source code. For every occurrence of the string `@include - FILENAMEtxi' within that file, `schmooz' calls itself with the - argument `FILENAMEscm'. + FILENAME.txi' within that file, `schmooz' calls itself with the + argument `FILENAME.scm'. Schmooz comments are distinguished (from non-schmooz comments) by their first line, which must start with an at-sign (@) preceded by one @@ -4977,12 +5134,14 @@ Mathematical Packages * Prime Numbers:: 'factor * Random Numbers:: 'random * Fast Fourier Transform:: 'fft -* Cyclic Checksum:: 'make-crc -* Plotting:: 'charplot +* Cyclic Checksum:: 'crc +* Graphing:: | +* Solid Modeling:: VRML97 +* Color:: * Root Finding:: 'root * Minimizing:: 'minimize * Commutative Rings:: 'commutative-ring -* Determinant:: 'determinant +* Matrix Algebra:: 'determinant File: slib.info, Node: Bit-Twiddling, Next: Modular Arithmetic, Prev: Mathematical Packages, Up: Mathematical Packages @@ -4990,9 +5149,9 @@ File: slib.info, Node: Bit-Twiddling, Next: Modular Arithmetic, Prev: Mathema Bit-Twiddling ============= - `(require 'logical)' +`(require 'logical)' - The bit-twiddling functions are made available through the use of the +The bit-twiddling functions are made available through the use of the `logical' package. `logical' is loaded by inserting `(require 'logical)' before the code that uses these functions. These functions behave as though operating on integers in two's-complement @@ -5085,14 +5244,14 @@ Bit Within Word Fields of Bits -------------- + - Function: logical:ones n | + Returns the smallest non-negative integer having N binary ones. | + | - Function: bit-field n start end Returns the integer composed of the START (inclusive) through END (exclusive) bits of N. The STARTth bit becomes the 0-th bit in the result. - - This function was called `bit-extract' in previous versions of - SLIB. - + | Example: (number->string (bit-field #b1101101010 0 4) 2) => "1010" @@ -5111,8 +5270,8 @@ Fields of Bits (number->string (copy-bit-field #b1101101010 0 4 -1) 2) => "1101101111" - - Function: ash int count - Returns an integer equivalent to `(inexact->exact (floor (* INT + - Function: ash n count + Returns an integer equivalent to `(inexact->exact (floor (* N (expt 2 COUNT))))'. Example: @@ -5141,13 +5300,117 @@ Fields of Bits (integer-expt -3 3) => -27 +Bit order and Lamination +------------------------ + + - Function: logical:rotate k count len + Returns the low-order LEN bits of K cyclically permuted COUNT bits + towards high-order. + + Example: + (number->string (logical:rotate #b0100 3 4) 2) + => "10" + (number->string (logical:rotate #b0100 -1 4) 2) + => "10" + + - Function: bit-reverse k n + Returns the low-order K bits of N with the bit order reversed. + The low-order bit of N is the high order bit of the returned value. + + (number->string (bit-reverse 8 #xa7) 16) + => "e5" + + - Function: integer->list k len + - Function: integer->list k + `integer->list' returns a list of LEN booleans corresponding to + each bit of the given integer. #t is coded for each 1; #f for 0. + The LEN argument defaults to `(integer-length K)'. + + - Function: list->integer list + `list->integer' returns an integer formed from the booleans in the + list LIST, which must be a list of booleans. A 1 bit is coded for + each #t; a 0 bit for #f. + + `integer->list' and `list->integer' are inverses so far as + `equal?' is concerned. + + - Function: booleans->integer bool1 ... + Returns the integer coded by the BOOL1 ... arguments. + + - Function: bitwise:laminate k1 ... + Returns an integer composed of the bits of K1 ... interlaced in + argument order. Given K1, ... KN, the n low-order bits of the + returned value will be the lowest-order bit of each argument. + + - Function: bitwise:delaminate count k + Returns a list of COUNT integers comprised of every COUNTh bit of + the integer K. + + For any non-negative integers K and COUNT: + (eqv? k (bitwise:laminate (bitwise:delaminate count k))) + +Gray code +--------- + +A "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. + +Gray codes find use communicating incrementally changing values between +asynchronous agents. De-laminated Gray codes comprise the coordinates +of Peano-Hilbert space-filling curves. + + - Function: integer->gray-code k + Converts K to a Gray code of the same `integer-length' as K. + + - Function: gray-code->integer k + Converts the Gray code K to an integer of the same + `integer-length' as K. + + For any non-negative integer K, + (eqv? k (gray-code->integer (integer->gray-code k))) + + - Function: = k1 k2 + - Function: gray-code<? k1 k2 + - Function: gray-code>? k1 k2 + - Function: gray-code<=? k1 k2 + - Function: 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 K1 and K2, the Gray code predicate + of `(integer->gray-code k1)' and `(integer->gray-code k2)' will + return the same value as the corresponding predicate of K1 and K2. + File: slib.info, Node: Modular Arithmetic, Next: Prime Numbers, Prev: Bit-Twiddling, Up: Mathematical Packages Modular Arithmetic ================== - `(require 'modular)' +`(require 'modular)' + + - Function: mod x1 x2 + - Function: rem x1 x2 + These procedures implement the Common-Lisp functions of the same + names. The real number X2 must be non-zero. `mod' returns `(- X1 + (* X2 (floor (/ X1 X2))))'. `rem' returns `(- X1 (* X2 (truncate + (/ X1 X2))))'. + + If X1 and X2 are integers, then `mod' behaves like `modulo' and + `rem' behaves like `remainder'. + + (mod -90 360) => 270 + (rem -90 180) => -90 + + (mod 540 360) => 180 + (rem 540 360) => 180 + + (mod (* 5/2 pi) (* 2 pi)) => 1.5707963267948965 + (rem (* -5/2 pi) (* 2 pi)) => -1.5707963267948965 - Function: extended-euclid n1 n2 Returns a list of 3 integers `(d x y)' such that d = gcd(N1, N2) = @@ -5185,27 +5448,27 @@ If all the arguments are fixnums the computation will use only fixnums. Returns `#t' if there exists an integer n such that K * n == 1 mod MODULUS, and `#f' otherwise. - - Function: modular:invert modulus k2 - Returns an integer n such that 1 = (n * K2) mod MODULUS. If K2 + - Function: modular:invert modulus n2 + Returns an integer n such that 1 = (n * N2) mod MODULUS. If N2 has no inverse mod MODULUS an error is signaled. - - Function: modular:negate modulus k2 - Returns (-K2) mod MODULUS. + - Function: modular:negate modulus n2 + Returns (-N2) mod MODULUS. - - Function: modular:+ modulus k2 k3 - Returns (K2 + K3) mod MODULUS. + - Function: modular:+ modulus n2 n3 + Returns (N2 + N3) mod MODULUS. - - Function: modular:- modulus k2 k3 - Returns (K2 - K3) mod MODULUS. + - Function: modular:- modulus n2 n3 + Returns (N2 - N3) mod MODULUS. - - Function: modular:* modulus k2 k3 - Returns (K2 * K3) mod MODULUS. + - Function: modular:* modulus n2 n3 + Returns (N2 * N3) mod MODULUS. The Scheme code for `modular:*' with negative MODULUS is not completed for fixnum-only implementations. - - Function: modular:expt modulus k2 k3 - Returns (K2 ^ K3) mod MODULUS. + - Function: modular:expt modulus n2 n3 + Returns (N2 ^ N3) mod MODULUS. File: slib.info, Node: Prime Numbers, Next: Random Numbers, Prev: Modular Arithmetic, Up: Mathematical Packages @@ -5213,7 +5476,7 @@ File: slib.info, Node: Prime Numbers, Next: Random Numbers, Prev: Modular Ari Prime Numbers ============= - `(require 'factor)' +`(require 'factor)' - Variable: prime:prngs PRIME:PRNGS is the random-state (*note Random Numbers::) used by @@ -5258,24 +5521,34 @@ File: slib.info, Node: Random Numbers, Next: Fast Fourier Transform, Prev: Pr Random Numbers ============== - `(require 'random)' - - 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 "DIEHARD" -(<http://stat.fsu.edu/~geo/diehard.html>). `diehard.c' has a bug which -the patch +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 "DIEHARD" (<http://stat.fsu.edu/~geo/diehard.html>). | +`diehard.c' has a bug which the patch | <http://swissnet.ai.mit.edu/ftpdir/users/jaffer/diehard.c.pat> corrects. - SLIB's new PRNG generates 8 bits at a time. With the degenerate seed + SLIB's PRNG generates 8 bits at a time. With the degenerate seed | `0', the numbers generated pass DIEHARD; but when bits are combined from sequential bytes, tests fail. With the seed `http://swissnet.ai.mit.edu/~jaffer/SLIB.html', all of those tests pass. - - Function: random n +* Menu: | + | +* Exact Random Numbers:: 'random | +* Inexact Random Numbers:: 'random-inexact | + | + +File: slib.info, Node: Exact Random Numbers, Next: Inexact Random Numbers, Prev: Random Numbers, Up: Random Numbers + | +Exact Random Numbers | +-------------------- | + | +`(require 'random)' | + | - Function: random n state - Accepts a positive integer or real N and returns a number of the - same type between zero (inclusive) and N (exclusive). The values + - Function: random n | + N must be an exact positive integer. `random' returns an exact | + integer between zero (inclusive) and N (exclusive). The values | returned by `random' are uniformly distributed from 0 to N. The optional argument STATE must be of the type returned by @@ -5316,9 +5589,13 @@ from sequential bytes, tests fail. With the seed representation will be used as the seed. Otherwise the value of `*random-state*' is used as the seed. - If inexact numbers are supported by the Scheme implementation, -`randinex.scm' will be loaded as well. `randinex.scm' contains -procedures for generating inexact distributions. + +File: slib.info, Node: Inexact Random Numbers, Prev: Exact Random Numbers, Up: Random Numbers + | +Inexact Random Numbers | +---------------------- | + | +`(require 'random-inexact)' | - Function: random:uniform - Function: random:uniform state @@ -5337,21 +5614,21 @@ procedures for generating inexact distributions. standard deviation 1. For a normal distribution with mean M and standard deviation D use `(+ M (* D (random:normal)))'. - - Function: random:normal-vector! vect - - Function: random:normal-vector! vect state + - Procedure: random:normal-vector! vect | + - Procedure: random:normal-vector! vect state | Fills VECT with inexact real random numbers which are independent and standard normally distributed (i.e., with mean 0 and variance 1). - - Function: random:hollow-sphere! vect - - Function: random:hollow-sphere! vect state + - Procedure: random:hollow-sphere! vect | + - Procedure: random:hollow-sphere! vect state | Fills VECT with inexact real random numbers the sum of whose squares is equal to 1.0. Thinking of VECT as coordinates in space of dimension n = `(vector-length VECT)', the coordinates are uniformly distributed over the surface of the unit n-shere. - - Function: random:solid-sphere! vect - - Function: random:solid-sphere! vect state + - Procedure: random:solid-sphere! vect | + - Procedure: random:solid-sphere! vect state | Fills VECT with inexact real random numbers the sum of whose squares is less than 1.0. Thinking of VECT as coordinates in space of dimension N = `(vector-length VECT)', the coordinates are @@ -5364,7 +5641,7 @@ File: slib.info, Node: Fast Fourier Transform, Next: Cyclic Checksum, Prev: R Fast Fourier Transform ====================== - `(require 'fft)' +`(require 'fft)' - Function: fft array ARRAY is an array of `(expt 2 n)' numbers. `fft' returns an array @@ -5375,7 +5652,7 @@ Fast Fourier Transform `fft-1' returns an array of complex numbers comprising the inverse Discrete Fourier Transform of ARRAY. - `(fft-1 (fft ARRAY))' will return an array of values close to ARRAY. +`(fft-1 (fft ARRAY))' will return an array of values close to ARRAY. (fft '#(1 0+i -1 0-i 1 0+i -1 0-i)) => @@ -5388,126 +5665,2098 @@ Fast Fourier Transform 1.0 -61.23031769111886e-18+1.0i -1.0 61.23031769111886e-18-1.0i) -File: slib.info, Node: Cyclic Checksum, Next: Plotting, Prev: Fast Fourier Transform, Up: Mathematical Packages - +File: slib.info, Node: Cyclic Checksum, Next: Graphing, Prev: Fast Fourier Transform, Up: Mathematical Packages + | Cyclic Checksum =============== - `(require 'make-crc)' +`(require 'crc)' + +Cyclic Redundancy Checks using Galois field GF(2) polynomial arithmetic +are used for error detection in many data transmission and storage +applications. + +The generator polynomials for various CRC protocols are availble from +many sources. But the polynomial is just one of many parameters which +must match in order for a CRC implementation to interoperate with +existing systems: + + * the byte-order and bit-order of the data stream; + + * whether the CRC or its inverse is being calculated; + + * the initial CRC value; and + + * whether and where the CRC value is appended (inverted or + non-inverted) to the data stream. + + +There is even some controversy over the polynomials themselves. + + - Constant: crc-32-polynomial + For CRC-32, http://www2.sis.pitt.edu/~jkabara/tele-2100/lect08.html + gives x^32+x^26+x^23+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x^1+1. + + But + http://www.cs.ncl.ac.uk/people/harry.whitfield/home.formal/CRCs.html, + http://duchon.umuc.edu/Web_Pages/duchon/99_f_cm435/ShiftRegister.htm, + http://spinroot.com/spin/Doc/Book91_PDF/ch3.pdf, + http://www.erg.abdn.ac.uk/users/gorry/course/dl-pages/crc.html, + http://www.rad.com/networks/1994/err_con/crc_most.htm, and + http://www.gpfn.sk.ca/~rhg/csc8550s02/crc.html, + http://www.nobugconsulting.ro/crc.php give + x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x+1. + + SLIB `crc-32-polynomial' uses the latter definition. | + + - Constant: crc-ccitt-polynomial + http://www.math.grin.edu/~rebelsky/Courses/CS364/2000S/Outlines/outline.12.html, + http://duchon.umuc.edu/Web_Pages/duchon/99_f_cm435/ShiftRegister.htm, + http://www.cs.ncl.ac.uk/people/harry.whitfield/home.formal/CRCs.html, + http://www2.sis.pitt.edu/~jkabara/tele-2100/lect08.html, and + http://www.gpfn.sk.ca/~rhg/csc8550s02/crc.html give CRC-CCITT: + x^16+x^12+x^5+1. + + - Constant: crc-16-polynomial + http://www.math.grin.edu/~rebelsky/Courses/CS364/2000S/Outlines/outline.12.html, + http://duchon.umuc.edu/Web_Pages/duchon/99_f_cm435/ShiftRegister.htm, + http://www.cs.ncl.ac.uk/people/harry.whitfield/home.formal/CRCs.html, + http://www.gpfn.sk.ca/~rhg/csc8550s02/crc.html, and + http://www.usb.org/developers/data/crcdes.pdf give CRC-16: + x^16+x^15+x^2+1. - - Function: make-port-crc - - Function: make-port-crc degree - Returns an expression for a procedure of one argument, a port. - This procedure reads characters from the port until the end of - file and returns the integer checksum of the bytes read. + - Constant: crc-12-polynomial + http://www.math.grin.edu/~rebelsky/Courses/CS364/2000S/Outlines/outline.12.html, + http://www.cs.ncl.ac.uk/people/harry.whitfield/home.formal/CRCs.html, + http://www.it.iitb.ac.in/it605/lectures/link/node4.html, and + http://spinroot.com/spin/Doc/Book91_PDF/ch3.pdf give CRC-12: + x^12+x^11+x^3+x^2+1. - The integer DEGREE, if given, specifies the degree of the - polynomial being computed - which is also the number of bits - computed in the checksums. The default value is 32. + But + http://www.ffldusoe.edu/Faculty/Denenberg/Topics/Networks/Error_Detection_Correction/crc.html, + http://duchon.umuc.edu/Web_Pages/duchon/99_f_cm435/ShiftRegister.htm, + http://www.eng.uwi.tt/depts/elec/staff/kimal/errorcc.html, + http://www.ee.uwa.edu.au/~roberto/teach/itc314/java/CRC/, + http://www.gpfn.sk.ca/~rhg/csc8550s02/crc.html, and + http://www.efg2.com/Lab/Mathematics/CRC.htm give CRC-12: + x^12+x^11+x^3+x^2+x+1. - - Function: make-port-crc generator - The integer GENERATOR specifies the polynomial being computed. - The power of 2 generating each 1 bit is the exponent of a term of - the polynomial. The value of GENERATOR must be larger than 127. + 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. | - - Function: make-port-crc degree generator - The integer GENERATOR specifies the polynomial being computed. - The power of 2 generating each 1 bit is the exponent of a term of - the polynomial. The bit at position DEGREE is implicit and should - not be part of GENERATOR. This allows systems with numbers - limited to 32 bits to calculate 32 bit checksums. The default - value of GENERATOR when DEGREE is 32 (its default) is: + - Constant: crc-10-polynomial + http://www.math.grin.edu/~rebelsky/Courses/CS364/2000S/Outlines/outline.12.html + gives CRC-10: x^10+x^9+x^5+x^4+1; but + http://cell-relay.indiana.edu/cell-relay/publications/software/CRC/crc10.html, + http://www.it.iitb.ac.in/it605/lectures/link/node4.html, + http://www.gpfn.sk.ca/~rhg/csc8550s02/crc.html, + http://www.techfest.com/networking/atm/atm.htm, + http://www.protocols.com/pbook/atmcell2.htm, and + http://www.nobugconsulting.ro/crc.php give CRC-10: + x^10+x^9+x^5+x^4+x+1. - (make-port-crc 32 #b00000100110000010001110110110111) + - Constant: crc-08-polynomial + http://www.math.grin.edu/~rebelsky/Courses/CS364/2000S/Outlines/outline.12.html, + http://www.cs.ncl.ac.uk/people/harry.whitfield/home.formal/CRCs.html, + http://www.it.iitb.ac.in/it605/lectures/link/node4.html, and + http://www.nobugconsulting.ro/crc.php give CRC-8: x^8+x^2+x^1+1 - Creates a procedure to calculate the P1003.2/D11.2 (POSIX.2) 32-bit - checksum from the polynomial: + - Constant: atm-hec-polynomial + http://cell-relay.indiana.edu/cell-relay/publications/software/CRC/32bitCRC.tutorial.html + and http://www.gpfn.sk.ca/~rhg/csc8550s02/crc.html give ATM HEC: + x^8+x^2+x+1. - 32 26 23 22 16 12 11 - ( x + x + x + x + x + x + x + - - 10 8 7 5 4 2 1 - x + x + x + x + x + x + x + 1 ) mod 2 + - Constant: dowcrc-polynomial + http://www.cs.ncl.ac.uk/people/harry.whitfield/home.formal/CRCs.html + gives DOWCRC: x^8+x^5+x^4+1. - (require 'make-crc) - (define crc32 (slib:eval (make-port-crc))) - (define (file-check-sum file) (call-with-input-file file crc32)) - (file-check-sum (in-vicinity (library-vicinity) "ratize.scm")) - - => 157103930 + - Constant: usb-token-polynomial + http://www.usb.org/developers/data/crcdes.pdf and + http://www.nobugconsulting.ro/crc.php give USB-token: x^5+x^2+1. - -File: slib.info, Node: Plotting, Next: Root Finding, Prev: Cyclic Checksum, Up: Mathematical Packages +Each of these polynomial constants is a string of `1's and `0's, the +exponent of each power of X in descending order. + + - Function: crc:make-table poly + POLY must be string of `1's and `0's beginning with `1' and having + length greater than 8. `crc:make-table' returns a vector of 256 + integers, such that: + + (set! CRC + (logxor (ash (logand (+ -1 (ash 1 (- DEG 8))) CRC) 8) + (vector-ref CRC-TABLE + (logxor (ash CRC (- 8 DEG)) BYTE)))) + + will compute the CRC with the 8 additional bits in BYTE; where CRC + is the previous accumulated CRC value, DEG is the degree of POLY, + and CRC-TABLE is the vector returned by `crc:make-table'. + + If the implementation does not support DEG-bit integers, then + `crc:make-table' returns #f. + + + - Function: cksum file + Computes the P1003.2/D11.2 (POSIX.2) 32-bit checksum of FILE. + + (require 'crc) + (cksum (in-vicinity (library-vicinity) "ratize.scm")) + => 157103930 + + - Function: cksum port + Computes the checksum of the bytes read from PORT until the + end-of-file. + + +`cksum-string', which returns the P1003.2/D11.2 (POSIX.2) 32-bit | +checksum of the bytes in STR, can be defined as follows: | + + (require 'string-port) | + (define (cksum-string str) (call-with-input-string str cksum)) | -Plotting on Character Devices -============================= + - Function: crc16 file + Computes the USB data-packet (16-bit) CRC of FILE. - `(require 'charplot)' + - Function: crc16 port + Computes the USB data-packet (16-bit) CRC of the bytes read from + PORT until the end-of-file. - The plotting procedure is made available through the use of the -`charplot' package. `charplot' is loaded by inserting `(require -'charplot)' before the code that uses this procedure. + `crc16' calculates the same values as the crc16.pl program given + in http://www.usb.org/developers/data/crcdes.pdf. - - Variable: charplot:height - The number of rows to make the plot vertically. - - Variable: charplot:width - The number of columns to make the plot horizontally. + - Function: crc5 file + Computes the USB token (5-bit) CRC of FILE. - - Procedure: plot! coords x-label y-label - COORDS is a list of pairs of x and y coordinates. X-LABEL and - Y-LABEL are strings with which to label the x and y axes. + - Function: crc5 port + Computes the USB token (5-bit) CRC of the bytes read from PORT + until the end-of-file. + + `crc5' calculates the same values as the crc5.pl program given in + http://www.usb.org/developers/data/crcdes.pdf. + + + +File: slib.info, Node: Graphing, Next: Solid Modeling, Prev: Cyclic Checksum, Up: Mathematical Packages + | +Graphing | +======== + +* Menu: | + | +* Character Plotting:: | +* PostScript Graphing:: | + | + +File: slib.info, Node: Character Plotting, Next: PostScript Graphing, Prev: Graphing, Up: Graphing + | +Character Plotting | +------------------ | + | +`(require 'charplot)' + + - Variable: charplot:dimensions + A list of the maximum height (number of lines) and maximum width + (number of columns) for the graph, its scales, and labels. + + The default value for CHARPLOT:DIMENSIONS is the + `output-port-height' and `output-port-width' of + `current-output-port'. + + - Procedure: plot coords x-label y-label + COORDS is a list or vector of coordinates, lists of x and y + coordinates. X-LABEL and Y-LABEL are strings with which to label + the x and y axes. Example: (require 'charplot) - (set! charplot:height 19) - (set! charplot:width 45) + (set! charplot:dimensions '(20 55)) (define (make-points n) (if (zero? n) '() - (cons (cons (/ n 6) (sin (/ n 6))) (make-points (1- n))))) + (cons (list (/ n 6) (sin (/ n 6))) (make-points (1- n))))) - (plot! (make-points 37) "x" "Sin(x)") + (plot (make-points 40) "x" "Sin(x)") -| - Sin(x) ______________________________________________ - 1.25|- | - | | - 1|- **** | - | ** ** | - 0.75|- * * | - | * * | - 0.5|- * * | - | * | - 0.25|- * | - | * * | - 0|-------------------*--------------------------| - | * | - -0.25|- * * | - | * * | - -0.5|- * | - | * * | - -0.75|- * * | - | ** ** | - -1|- **** | - |____________:_____._____:_____._____:_________| - x 2 4 6 - - - Procedure: plot-function! func x1 x2 - - Procedure: plot-function! func x1 x2 npts + Sin(x) _________________________________________ + 1|- **** | + | ** ** | + 0.75|- * * | + | * * | + 0.5|- * * | + | * *| + 0.25|- * * | + | * * | + 0|-------------------*------------------*--| + | * | + -0.25|- * * | + | * * | + -0.5|- * | + | * * | + -0.75|- * * | + | ** ** | + -1|- **** | + |:_____._____:_____._____:_____._____:____| + x 2 4 6 + + - Procedure: plot func x1 x2 + - Procedure: plot func x1 x2 npts Plots the function of one argument FUNC over the range X1 to X2. If the optional integer argument NPTS is supplied, it specifies the number of points to evaluate FUNC at. + (plot sin 0 (* 2 pi)) + -| + _________________________________________ + 1|-: **** | + | : ** ** | + 0.75|-: * * | + | : * * | + 0.5|-: ** ** | + | : * * | + 0.25|-:** ** | + | :* * | + 0|-*------------------*--------------------| + | : * * | + -0.25|-: ** ** | + | : * * | + -0.5|-: * ** | + | : * * | + -0.75|-: * ** | + | : ** ** | + -1|-: **** | + |_:_____._____:_____._____:_____._____:___| + 0 2 4 6 + + - Procedure: histograph data label + Creates and displays a histogram of the numerical values contained + in vector or list DATA + + (require 'random-inexact) | + (histograph (do ((idx 99 (+ -1 idx)) + (lst '() (cons (* .02 (random:normal)) lst))) + ((negative? idx) lst)) + "normal") + -| + _________________________________________ + 8|- : I | + | : I | + 7|- I I : I | + | I I : I | + 6|- III I :I I | + | III I :I I | + 5|- IIIIIIIIII I | + | IIIIIIIIII I | + 4|- IIIIIIIIIIII | + | IIIIIIIIIIII | + 3|-I I I IIIIIIIIIIII II I | + | I I I IIIIIIIIIIII II I | + 2|-I I I IIIIIIIIIIIIIIIII I | + | I I I IIIIIIIIIIIIIIIII I | + 1|-II I I IIIIIIIIIIIIIIIIIIIII I I I | + | II I I IIIIIIIIIIIIIIIIIIIII I I I | + 0|-IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII----| + |__.____:____.____:____.____:____.____:___| + normal -0.025 0 0.025 0.05 + + +File: slib.info, Node: PostScript Graphing, Prev: Character Plotting, Up: Graphing + | +PostScript Graphing | +------------------- | + | +`(require 'eps-graph)' | + | +This is a graphing package creating encapsulated-PostScript files. Its | +motivations and design choice are described in | +<http://swissnet.ai.mit.edu/~jaffer/Docupage/grapheps> | + | +A dataset to be plotted is taken from a 2-dimensional array. | +Corresponding coordinates are in rows. Coordinates from any pair of | +columns can be plotted. | + | + - Function: create-postscript-graph filename.eps size elt1 ... | + FILENAME.EPS should be a string naming an output file to be | + created. SIZE should be an exact integer, a list of two exact | + integers, or #f. ELT1, ... are values returned by graphing | + primitives described here. | + | + `create-postscript-graph' creates an "Encapsulated-PostScript" | + file named FILENAME.EPS containing graphs as directed by the ELT1, | + ... arguments. | + | + The size of the graph is determined by the SIZE argument. If a | + list of two integers, they specify the width and height. If one | + integer, then that integer is the width and the height is 3/4 of | + the width. If #f, the graph will be 800 by 600. | + | +These graphing procedures should be called as arguments to | +`create-postscript-graph'. The order of these arguments is | +significant; PostScript graphics state is affected serially from the | +first ELT argument to the last. | + | + - Function: whole-page | + Pushes a rectangle for the whole encapsulated page onto the | + PostScript stack. This pushed rectangle is an implicit argument to | + `partition-page' or `setup-plot'. | + | +* Menu: | + | +* Column Ranges:: | +* Drawing the Graph:: | +* Graphics Context:: | +* Rectangles:: | +* Legending:: | +* Legacy Plotting:: | +* Example Graph:: | + | -File: slib.info, Node: Root Finding, Next: Minimizing, Prev: Plotting, Up: Mathematical Packages +File: slib.info, Node: Column Ranges, Next: Drawing the Graph, Prev: PostScript Graphing, Up: PostScript Graphing + | +Column Ranges | +............. | + | +A "range" is a list of two numbers, the minimum and the maximum. | +Ranges can be given explicity or computed in PostScript by | +`column-range'. | + | + - Function: column-range array k | + Returns the range of values in 2-dimensional ARRAY column K. | + | + - Function: pad-range range p | + Expands RANGE by P/100 on each end. | + | + - Function: snap-range range | + Expands RANGE to round number of ticks. | + | + - Function: combine-ranges range1 range2 ... | + Returns the minimal range covering all RANGE1, RANGE2, ... | + | + - Function: setup-plot x-range y-range pagerect | + - Function: setup-plot x-range y-range | + X-RANGE and Y-RANGE should each be a list of two numbers or the | + value returned by `pad-range', `snap-range', or `combine-range'. | + PAGERECT is the rectangle bounding the graph to be drawn; if | + missing, the rectangle from the top of the PostScript stack is | + popped and used. | + | + Based on the given ranges, `setup-plot' sets up scaling and | + margins for making a graph. The margins are sized proportional to | + the FONTHEIGHT value at the time of the call to setup-plot. | + `setup-plot' sets two variables: | + | + PLOTRECT | + The region where data points will be plotted. | + | + GRAPHRECT | + The PAGERECT argument to `setup-plot'. Includes plotrect, | + legends, etc. | + | + +File: slib.info, Node: Drawing the Graph, Next: Graphics Context, Prev: Column Ranges, Up: PostScript Graphing + | +Drawing the Graph | +................. | + | + - Function: plot-column array x-column y-column proc3s | + Plots points with x coordinate in X-COLUMN of ARRAY and y | + coordinate Y-COLUMN of ARRAY. The symbol PROC3S specifies the | + type of glyph or drawing style for presenting these coordinates. | + | +The glyphs and drawing styles available are: | + | +`line' | + Draws line connecting points in order. | + | +`mountain' | + Fill area below line connecting points. | + | +`cloud' | + Fill area above line connecting points. | + | +`impulse' | + Draw line from x-axis to each point. | + | +`bargraph' | + Draw rectangle from x-axis to each point. | + | +`disc' | + Solid round dot. | + | +`point' | + Minimal point - invisible if linewidth is 0. | + | +`square' | + Square box. | + | +`diamond' | + Square box at 45.o | + | +`plus' | + Plus sign. | + | +`cross' | + X sign. | + | +`triup' | + Triangle pointing upward | + | +`tridown' | + Triangle pointing downward | + | +`pentagon' | + Five sided polygon | + | +`circle' | + Hollow circle | + | + +File: slib.info, Node: Graphics Context, Next: Rectangles, Prev: Drawing the Graph, Up: PostScript Graphing + | +Graphics Context | +................ | + | + - Function: in-graphic-context arg ... | + Saves the current graphics state, executes ARGS, then restores to | + saved graphics state. | + | + - Function: set-color color | + COLOR should be a string naming a Resene color, a saturate color, | + or a number between 0 and 100. | + | + `set-color' sets the PostScript color to the color of the given | + string, or a grey value between black (0) and white (100). | + | + - Function: set-font name fontheight | + NAME should be a (case-sensitive) string naming a PostScript font. | + FONTHEIGHT should be a positive real number. | + | + `set-font' Changes the current PostScript font to NAME with height | + equal to FONTHEIGHT. The default font is Helvetica (12pt). | + | +The base set of PostScript fonts is: | + | +Times Times-Italic Times-Bold Times-BoldItalic | +Helvetica Helvetica-Oblique Helvetica-Bold Helvetica-BoldOblique | +Courier Courier-Oblique Courier-Bold Courier-BoldOblique | +Symbol | + | +Line parameters do no affect fonts; they do effect glyphs. | + | + - Function: set-linewidth w | + The default linewidth is 1. Setting it to 0 makes the lines drawn | + as skinny as possible. Linewidth must be much smaller than | + glyphsize for readable glyphs. | + | + - Function: set-linedash j k | + Lines are drawn J-on K-off. | + | + - Function: set-linedash j | + Lines are drawn J-on J-off. | + | + - Function: set-linedash | + Turns off dashing. | + | + - Function: set-glyphsize w | + Sets the (PostScript) variable glyphsize to W. The default | + glyphsize is 6. | + | +The effects of `clip-to-rect' are also part of the graphic context. | + | + +File: slib.info, Node: Rectangles, Next: Legending, Prev: Graphics Context, Up: PostScript Graphing + | +Rectangles | +.......... | + | +A "rectangle" is a list of 4 numbers; the first two elements are the x | +and y coordinates of lower left corner of the rectangle. The other two | +elements are the width and height of the rectangle. | + | + - Function: whole-page | + Pushes a rectangle for the whole encapsulated page onto the | + PostScript stack. This pushed rectangle is an implicit argument to | + `partition-page' or `setup-plot'. | + | + - Function: partition-page xparts yparts | + Pops the rectangle currently on top of the stack and pushes XPARTS | + * YPARTS sub-rectangles onto the stack in decreasing y and | + increasing x order. If you are drawing just one graph, then you | + don't need `partition-page'. | + | + - Variable: plotrect | + The rectangle where data points should be plotted. PLOTRECT is | + set by `setup-plot'. | + | + - Variable: graphrect | + The PAGERECT argument of the most recent call to `setup-plot'. | + Includes plotrect, legends, etc. | + | + - Function: fill-rect rect | + fills RECT with the current color. | + | + - Function: outline-rect rect | + Draws the perimiter of RECT in the current color. | + | + - Function: clip-to-rect rect | + Modifies the current graphics-state so that nothing will be drawn | + outside of the rectangle RECT. Use `in-graphic-context' to limit | + the extent of `clip-to-rect'. | + | + +File: slib.info, Node: Legending, Next: Legacy Plotting, Prev: Rectangles, Up: PostScript Graphing + | +Legending | +......... | + | + - Function: title-top title subtitle | + - Function: title-top title | + Puts a TITLE line and an optional SUBTITLE line above the | + `graphrect'. | + | + - Function: title-bottom title subtitle | + - Function: title-bottom title | + Puts a TITLE line and an optional SUBTITLE line below the | + `graphrect'. | + | + - Variable: topedge | + - Variable: bottomedge | + These edge coordinates of `graphrect' are suitable for passing as | + the first argument to `rule-horizontal'. | + | + - Variable: leftedge | + - Variable: rightedge | + These edge coordinates of `graphrect' are suitable for passing as | + the first argument to `rule-vertical'. | + | + - Function: rule-vertical x-coord text tick-width | + Draws a vertical ruler with X coordinate X-COORD and labeled with | + string TEXT. If TICK-WIDTH is positive, then the ticks are | + TICK-WIDTH long on the right side of X-COORD; and TEXT and numeric | + legends are on the left. If TICK-WIDTH is negative, then the | + ticks are -TICK-WIDTH long on the left side of X-COORD; and TEXT | + and numeric legends are on the right. | + | + - Function: rule-horizontal x-coord text tick-height | + Draws a horizontal ruler with X coordinate X-COORD and labeled with | + string TEXT. If TICK-HEIGHT is positive, then the ticks are | + TICK-HEIGHT long on the right side of X-COORD; and TEXT and | + numeric legends are on the left. If TICK-HEIGHT is negative, then | + the ticks are -TICK-HEIGHT long on the left side of X-COORD; and | + TEXT and numeric legends are on the right. | + | + - Function: y-axis | + Draws the y-axis. | + | + - Function: x-axis | + Draws the x-axis. | + | + - Function: grid-verticals | + Draws vertical lines through `graphrect' at each tick on the | + vertical ruler. | + | + - Function: grid-horizontals | + Draws horizontal lines through `graphrect' at each tick on the | + horizontal ruler. | + | + +File: slib.info, Node: Legacy Plotting, Next: Example Graph, Prev: Legending, Up: PostScript Graphing + | +Legacy Plotting | +............... | + | + - Variable: graph:dimensions | + A list of the width and height of the graph to be plotted using | + `plot'. | + | + - Function: plot func x1 x2 npts | + - Function: plot func x1 x2 | + Creates and displays using `(system "gv tmp.eps")' an encapsulated | + PostScript graph of the function of one argument FUNC over the | + range X1 to X2. If the optional integer argument NPTS is | + supplied, it specifies the number of points to evaluate FUNC at. | + | + - Function: plot coords x-label y-label | + COORDS is a list or vector of coordinates, lists of x and y | + coordinates. X-LABEL and Y-LABEL are strings with which to label | + the x and y axes. | + | + +File: slib.info, Node: Example Graph, Prev: Legacy Plotting, Up: PostScript Graphing + | +Example Graph | +............. | + | +The file `am1.5.html', a table of solar irradiance, is fetched with | +`wget' if it isn't already in the working directory. The file is read | +and stored into an array, IRRADIANCE. | + | + `create-postscript-graph' is then called to create an | +encapsulated-PostScript file, `solarad.eps'. The size of the page is | +set to 600 by 300. `whole-page' is called and leaves the rectangle on | +the PostScript stack. `setup-plot' is called with a literal range for | +x and computes the range for column 1. | + | + Two calls to `top-title' are made so a different font can be used for | +the lower half. `in-graphic-context' is used to limit the scope of the | +font change. The graphing area is outlined and a rule drawn on the | +left side. | + | + Because the X range was intentionally reduced, `in-graphic-context' | +is called and `clip-to-rect' limits drawing to the plotting area. A | +black line is drawn from data column 1. That line is then overlayed | +with a mountain plot of the same column colored "Bright Sun". | + | + After returning from the `in-graphic-context', the bottom ruler is | +drawn. Had it been drawn earlier, all its ticks would have been | +painted over by the mountain plot. | + | + The color is then changed to `seagreen' and the same graphrect is | +setup again, this time with a different Y scale, 0 to 1000. The | +graphic context is again clipped to PLOTRECT, linedash is set, and | +column 2 is plotted as a dashed line. Finally the rightedge is ruled. | +Having the line and its scale both in green helps disambiguate the | +scales. | + | + (require 'eps-graph) | + (require 'line-i/o) | + (require 'string-port) | + | + (define irradiance | + (let ((url "http://www.pv.unsw.edu.au/am1.5.html") | + (file "am1.5.html")) | + (define (read->list line) | + (define elts '()) | + (call-with-input-string line | + (lambda (iprt) (do ((elt (read iprt) (read iprt))) | + ((eof-object? elt) elts) | + (set! elts (cons elt elts)))))) | + (if (not (file-exists? file)) | + (system (string-append "wget -c -O" file " " url))) | + (call-with-input-file file | + (lambda (iprt) | + (define lines '()) | + (do ((line (read-line iprt) (read-line iprt))) | + ((eof-object? line) | + (let ((nra (create-array (Ar64) | + (length lines) | + (length (car lines))))) | + (do ((lns lines (cdr lns)) | + (idx (+ -1 (length lines)) (+ -1 idx))) | + ((null? lns) nra) | + (do ((kdx (+ -1 (length (car lines))) (+ -1 kdx)) | + (lst (car lns) (cdr lst))) | + ((null? lst)) | + (array-set! nra (car lst) idx kdx))))) | + (if (and (positive? (string-length line)) | + (char-numeric? (string-ref line 0))) | + (set! lines (cons (read->list line) lines)))))))) | + | + (let ((xrange '(.25 2.5))) | + (create-postscript-graph | + "solarad.eps" '(600 300) | + (whole-page) | + (setup-plot xrange (column-range irradiance 1)) | + (title-top | + "Solar Irradiance http://www.pv.unsw.edu.au/am1.5.html") | + (in-graphic-context | + (set-font "Helvetica-Oblique" 12) | + (title-top | + "" | + "Key Centre for Photovoltaic Engineering UNSW - Air Mass 1.5 Global Spectrum")) + (outline-rect plotrect) | + (rule-vertical leftedge "W/(m^2.um)" 10) | + (in-graphic-context (clip-to-rect plotrect) | + (plot-column irradiance 0 1 'line) | + (set-color "Bright Sun") | + (plot-column irradiance 0 1 'mountain) | + ) | + (rule-horizontal bottomedge "Wavelength in .um" 5) | + (set-color 'seagreen) | + | + (setup-plot xrange '(0 1000) graphrect) | + (in-graphic-context (clip-to-rect plotrect) | + (set-linedash 5 2) | + (plot-column irradiance 0 2 'line)) | + (rule-vertical rightedge "Integrated .W/(m^2)" -10) | + )) | + | + (system "gv solarad.eps") | + | + +File: slib.info, Node: Solid Modeling, Next: Color, Prev: Graphing, Up: Mathematical Packages + | +Solid Modeling +============== + +`(require 'solid)' + +`http://swissnet.ai.mit.edu/~jaffer/Solid/#Example' gives an example +use of this package. + + - Function: vrml node ... + Returns the VRML97 string (including header) of the concatenation + of strings NODES, .... + + - Function: vrml-append node1 node2 ... + Returns the concatenation with interdigitated newlines of strings + NODE1, NODE2, .... + + - Function: vrml-to-file file node ... + Writes to file named FILE the VRML97 string (including header) of + the concatenation of strings NODES, .... + + - Function: world:info title info ... + Returns a VRML97 string setting the title of the file in which it + appears to TITLE. Additional strings INFO, ... are comments. + +VRML97 strings passed to `vrml' and `vrml-to-file' as arguments will +appear in the resulting VRML code. This string turns off the headlight +at the viewpoint: + " NavigationInfo {headlight FALSE}" + + - Function: scene:panorama front right back left top bottom + Specifies the distant images on the inside faces of the cube + enclosing the virtual world. + + - Function: scene:sphere colors angles + COLORS is a list of color objects. Each may be of type *Note + color: Color Data-Type, a 24-bit sRGB integer, or a list of 3 + numbers between 0.0 and 1.0. + + ANGLES is a list of non-increasing angles the same length as + COLORS. Each angle is between 90 and -90 degrees. If 90 or -90 + are not elements of ANGLES, then the color at the zenith and nadir + are taken from the colors paired with the angles nearest them. + + `scene:sphere' fills horizontal bands with interpolated colors on + the backgroud sphere encasing the world. + + - Function: scene:sky-and-dirt + Returns a blue and brown backgroud sphere encasing the world. + + - Function: scene:sky-and-grass + Returns a blue and green backgroud sphere encasing the world. + + - Function: scene:sun latitude julian-day hour turbidity strength + - Function: scene:sun latitude julian-day hour turbidity + LATITUDE is the virtual place's latitude in degrees. JULIAN-DAY + is an integer from 0 to 366, the day of the year. HOUR is a real + number from 0 to 24 for the time of day; 12 is noon. TURBIDITY is + the degree of fogginess described in *Note turbidity: Daylight. + + `scene:sun' returns a bright yellow, distant sphere where the sun + would be at HOUR on JULIAN-DAY at LATITUDE. If STRENGTH is + positive, included is a light source of STRENGTH (default 1). + + - Function: scene:overcast latitude julian-day hour turbidity strength + - Function: scene:overcast latitude julian-day hour turbidity + LATITUDE is the virtual place's latitude in degrees. JULIAN-DAY + is an integer from 0 to 366, the day of the year. HOUR is a real + number from 0 to 24 for the time of day; 12 is noon. TURBIDITY is + the degree of cloudiness described in *Note turbidity: Daylight. + + `scene:overcast' returns an overcast sky as it might look at HOUR + on JULIAN-DAY at LATITUDE. If STRENGTH is positive, included is + an ambient light source of STRENGTH (default 1). + +Viewpoints are objects in the virtual world, and can be transformed +individually or with solid objects. + + - Function: scene:viewpoint name distance compass pitch + - Function: scene:viewpoint name distance compass + Returns a viewpoint named NAME facing the origin and placed + DISTANCE from it. COMPASS is a number from 0 to 360 giving the + compass heading. PITCH is a number from -90 to 90, defaulting to + 0, specifying the angle from the horizontal. + + - Function: scene:viewpoints proximity + Returns 6 viewpoints, one at the center of each face of a cube + with sides 2 * PROXIMITY, centered on the origin. + +Light Sources +------------- + +In VRML97, lights shine only on objects within the same children node +and descendants of that node. Although it would have been convenient +to let light direction be rotated by `solid:rotation', this restricts a +rotated light's visibility to objects rotated with it. + +To workaround this limitation, these directional light source +procedures accept either Cartesian or spherical coordinates for +direction. A spherical coordinate is a list `(THETA AZIMUTH)'; where +THETA is the angle in degrees from the zenith, and AZIMUTH is the angle +in degrees due west of south. + +It is sometimes useful for light sources to be brighter than `1'. When +INTENSITY arguments are greater than 1, these functions gang multiple +sources to reach the desired strength. + + - Function: light:ambient color intensity + - Function: light:ambient color + Ambient light shines on all surfaces with which it is grouped. + + COLOR is a an object of type *Note color: Color Data-Type, a + 24-bit sRGB integer, or a list of 3 numbers between 0.0 and 1.0. + If COLOR is #f, then the default color will be used. INTENSITY is + a real non-negative number defaulting to `1'. + + `light:ambient' returns a light source or sources of COLOR with + total strength of INTENSITY (or 1 if omitted). + + - Function: light:directional color direction intensity + - Function: light:directional color direction + - Function: light:directional color + Directional light shines parallel rays with uniform intensity on + all objects with which it is grouped. + + COLOR is a an object of type *Note color: Color Data-Type, a + 24-bit sRGB integer, or a list of 3 numbers between 0.0 and 1.0. + If COLOR is #f, then the default color will be used. + + DIRECTION must be a list or vector of 2 or 3 numbers specifying + the direction to this light. If DIRECTION has 2 numbers, then + these numbers are the angle from zenith and the azimuth in + degrees; if DIRECTION has 3 numbers, then these are taken as a + Cartesian vector specifying the direction to the light source. + The default direction is upwards; thus its light will shine down. + + INTENSITY is a real non-negative number defaulting to `1'. + + `light:directional' returns a light source or sources of COLOR + with total strength of INTENSITY, shining from DIRECTION. + + - Function: light:beam attenuation radius aperture peak + - Function: light:beam attenuation radius aperture + - Function: light:beam attenuation radius + - Function: light:beam attenuation + ATTENUATION is a list or vector of three nonnegative real numbers + specifying the reduction of intensity, the reduction of intensity + with distance, and the reduction of intensity as the square of + distance. RADIUS is the distance beyond which the light does not + shine. RADIUS defaults to `100'. + + APERTURE is a real number between 0 and 180, the angle centered on + the light's axis through which it sheds some light. PEAK is a + real number between 0 and 90, the angle of greatest illumination. + + - Function: light:point location color intensity beam + - Function: light:point location color intensity + - Function: light:point location color + - Function: light:point location + Point light radiates from LOCATION, intensity decreasing with + distance, towards all objects with which it is grouped. + + COLOR is a an object of type *Note color: Color Data-Type, a + 24-bit sRGB integer, or a list of 3 numbers between 0.0 and 1.0. + If COLOR is #f, then the default color will be used. INTENSITY is + a real non-negative number defaulting to `1'. BEAM is a structure + returned by `light:beam' or #f. + + `light:point' returns a light source or sources at LOCATION of + COLOR with total strength INTENSITY and BEAM properties. Note + that the pointlight itself is not visible. To make it so, place + an object with emissive appearance at LOCATION. + + - Function: light:spot location direction color intensity beam + - Function: light:spot location direction color intensity + - Function: light:spot location direction color + - Function: light:spot location direction + - Function: light:spot location + Spot light radiates from LOCATION towards DIRECTION, intensity + decreasing with distance, illuminating objects with which it is + grouped. + + DIRECTION must be a list or vector of 2 or 3 numbers specifying + the direction to this light. If DIRECTION has 2 numbers, then + these numbers are the angle from zenith and the azimuth in + degrees; if DIRECTION has 3 numbers, then these are taken as a + Cartesian vector specifying the direction to the light source. + The default direction is upwards; thus its light will shine down. + + COLOR is a an object of type *Note color: Color Data-Type, a + 24-bit sRGB integer, or a list of 3 numbers between 0.0 and 1.0. + If COLOR is #f, then the default color will be used. + + INTENSITY is a real non-negative number defaulting to `1'. + + `light:spot' returns a light source or sources at LOCATION of + DIRECTION with total strength COLOR. Note that the spotlight + itself is not visible. To make it so, place an object with + emissive appearance at LOCATION. + +Object Primitives +----------------- + + - Function: solid:box geometry appearance + - Function: solid:box geometry + GEOMETRY must be a number or a list or vector of three numbers. + If GEOMETRY is a number, the `solid:box' returns a cube with sides + of length GEOMETRY centered on the origin. Otherwise, `solid:box' + returns a rectangular box with dimensions GEOMETRY centered on the + origin. APPEARANCE determines the surface properties of the + returned object. + + - Function: solid:cylinder radius height appearance + - Function: solid:cylinder radius height + Returns a right cylinder with dimensions RADIUS and `(abs HEIGHT)' + centered on the origin. If HEIGHT is positive, then the cylinder + ends will be capped. APPEARANCE determines the surface properties + of the returned object. + + - Function: solid:disk radius thickness appearance + - Function: solid:disk radius thickness + THICKNESS must be a positive real number. `solid:disk' returns a + circular disk with dimensions RADIUS and THICKNESS centered on the + origin. APPEARANCE determines the surface properties of the + returned object. + + - Function: solid:cone radius height appearance + - Function: solid:cone radius height + Returns an isosceles cone with dimensions RADIUS and HEIGHT + centered on the origin. APPEARANCE determines the surface + properties of the returned object. + + - Function: solid:pyramid side height appearance + - Function: solid:pyramid side height + Returns an isosceles pyramid with dimensions SIDE and HEIGHT + centered on the origin. APPEARANCE determines the surface + properties of the returned object. + + - Function: solid:sphere radius appearance + - Function: solid:sphere radius + Returns a sphere of radius RADIUS centered on the origin. + APPEARANCE determines the surface properties of the returned + object. + + - Function: solid:ellipsoid geometry appearance + - Function: solid:ellipsoid geometry + GEOMETRY must be a number or a list or vector of three numbers. + If GEOMETRY is a number, the `solid:ellipsoid' returns a sphere of + diameter GEOMETRY centered on the origin. Otherwise, + `solid:ellipsoid' returns an ellipsoid with diameters GEOMETRY + centered on the origin. APPEARANCE determines the surface + properties of the returned object. + + - Function: solid:basrelief width height depth colorray appearance + - Function: solid:basrelief width height depth appearance + - Function: solid:basrelief width height depth + One of WIDTH, HEIGHT, or DEPTH must be a 2-dimensional array; the + others must be real numbers giving the length of the basrelief in + those dimensions. The rest of this description assumes that + HEIGHT is an array of heights. + + `solid:basrelief' returns a WIDTH by DEPTH basrelief solid with + heights per array HEIGHT with the buttom surface centered on the + origin. + + If present, APPEARANCE determines the surface properties of the + returned object. If present, COLORRAY must be an array of objects + of type *Note color: Color Data-Type, 24-bit sRGB integers or + lists of 3 numbers between 0.0 and 1.0. + + If COLORRAY's dimensions match HEIGHT, then each element of + COLORRAY paints its corresponding vertex of HEIGHT. If COLORRAY + has all dimensions one smaller than HEIGHT, then each element of + COLORRAY paints the corresponding face of HEIGHT. Other + dimensions for COLORRAY are in error. + +Surface Attributes +------------------ + + - Function: solid:color diffuseColor ambientIntensity specularColor + shininess emissiveColor transparency + - Function: solid:color diffuseColor ambientIntensity specularColor + shininess emissiveColor + - Function: solid:color diffuseColor ambientIntensity specularColor + shininess + - Function: solid:color diffuseColor ambientIntensity specularColor + - Function: solid:color diffuseColor ambientIntensity + - Function: solid:color diffuseColor + Returns an "appearance", the optical properties of the objects + with which it is associated. AMBIENTINTENSITY, SHININESS, and + TRANSPARENCY must be numbers between 0 and 1. DIFFUSECOLOR, + SPECULARCOLOR, and EMISSIVECOLOR are objects of type *Note color: + Color Data-Type, 24-bit sRGB integers or lists of 3 numbers + between 0.0 and 1.0. If a color argument is omitted or #f, then + the default color will be used. + + - Function: solid:texture image color scale rotation center translation + - Function: solid:texture image color scale rotation center + - Function: solid:texture image color scale rotation + - Function: solid:texture image color scale + - Function: solid:texture image color + - Function: solid:texture image + Returns an "appearance", the optical properties of the objects + with which it is associated. IMAGE is a string naming a JPEG or + PNG image resource. COLOR is #f, a color, or the string returned + by `solid:color'. The rest of the optional arguments specify + 2-dimensional transforms applying to the IMAGE. + + SCALE must be #f, a number, or list or vector of 2 numbers + specifying the scale to apply to IMAGE. ROTATION must be #f or + the number of degrees to rotate IMAGE. CENTER must be #f or a + list or vector of 2 numbers specifying the center of IMAGE + relative to the IMAGE dimensions. TRANSLATION must be #f or a + list or vector of 2 numbers specifying the translation to apply to + IMAGE. + +Aggregating Objects +------------------- + + - Function: solid:center-row-of number solid spacing + Returns a row of NUMBER SOLID objects spaced evenly SPACING apart. + + - Function: solid:center-array-of number-a number-b solid spacing-a + spacing-b + Returns NUMBER-B rows, SPACING-B apart, of NUMBER-A SOLID objects + SPACING-A apart. + + - Function: solid:center-pile-of number-a number-b number-c solid + spacing-a spacing-b spacing-c + Returns NUMBER-C planes, SPACING-C apart, of NUMBER-B rows, + SPACING-B apart, of NUMBER-A SOLID objects SPACING-A apart. + + - Function: solid:arrow center + CENTER must be a list or vector of three numbers. Returns an + upward pointing metallic arrow centered at CENTER. + + - Function: solid:arrow + Returns an upward pointing metallic arrow centered at the origin. + +Spatial Transformations +----------------------- + + - Function: solid:translation center solid ... + CENTER must be a list or vector of three numbers. + `solid:translation' Returns an aggregate of SOLIDS, ... with their + origin moved to CENTER. + + - Function: solid:scale scale solid ... + SCALE must be a number or a list or vector of three numbers. + `solid:scale' Returns an aggregate of SOLIDS, ... scaled per SCALE. + + - Function: solid:rotation axis angle solid ... + AXIS must be a list or vector of three numbers. `solid:rotation' + Returns an aggregate of SOLIDS, ... rotated ANGLE degrees around + the axis AXIS. + + +File: slib.info, Node: Color, Next: Root Finding, Prev: Solid Modeling, Up: Mathematical Packages + +Color +===== + +`http://swissnet.ai.mit.edu/~jaffer/Color' + +The goals of this package are to provide methods to specify, compute, +and transform colors in a core set of additive color spaces. The color +spaces supported should be sufficient for working with the color data +encountered in practice and the literature. + +* Menu: + +* Color Data-Type:: 'color +* Color Spaces:: XYZ, L*a*b*, L*u*v*, L*C*h, RGB709, sRGB +* Spectra:: Color Temperatures and CIEXYZ(1931) +* Color Difference Metrics:: Society of Dyers and Colorists +* Color Conversions:: Low-level +* Color Names:: in relational databases +* Daylight:: Sunlight and sky colors + + +File: slib.info, Node: Color Data-Type, Next: Color Spaces, Prev: Color, Up: Color + +Color Data-Type +--------------- + +`(require 'color)' + + - Function: color? obj + Returns #t if OBJ is a color. + + - Function: color? obj typ + Returns #t if OBJ is a color of color-space TYP. The symbol TYP + must be one of: + + * CIEXYZ + + * RGB709 + + * L*a*b* + + * L*u*v* + + * sRGB + + * e-sRGB + + * L*C*h + + - Function: make-color space arg ... + Returns a color of type SPACE. + + - Function: color-space color + Returns the symbol for the color-space in which COLOR is embedded. + + - Function: color-precision color + For colors in digital color-spaces, `color-precision' returns the + number of bits used for each of the R, G, and B channels of the + encoding. Otherwise, `color-precision' returns #f + + - Function: color-white-point color + Returns the white-point of COLOR in all color-spaces except CIEXYZ. + + - Function: convert-color color space white-point + - Function: convert-color color space + - Function: convert-color color e-sRGB precision + Converts COLOR into SPACE at optional WHITE-POINT. + +External Representation +....................... + +Each color encoding has an external, case-insensitive representation. +To ensure portability, the white-point for all color strings is D65. +(1) + +Color Space External Representation +CIEXYZ CIEXYZ:<X>/<Y>/<Z> +RGB709 RGBi:<R>/<G>/<B> +L*a*b* CIELAB:<L>/<a>/<b> +L*u*v* CIELuv:<L>/<u>/<v> +L*C*h CIELCh:<L>/<C>/<h> + +The X, Y, Z, L, A, B, U, V, C, H, R, G, and B fields are (Scheme) real +numbers within the appropriate ranges. + +Color Space External Representation +sRGB sRGB:<R>/<G>/<B> +e-sRGB10 e-sRGB10:<R>/<G>/<B> +e-sRGB12 e-sRGB12:<R>/<G>/<B> +e-sRGB16 e-sRGB16:<R>/<G>/<B> + +The R, G, and B, fields are non-negative exact decimal integers within +the appropriate ranges. + +Several additional syntaxes are supported by `string->color': + +Color Space External Representation +sRGB sRGB:<RRGGBB> +sRGB #<RRGGBB> +sRGB 0x<RRGGBB> +sRGB #x<RRGGBB> + + Where RRGGBB is a non-negative six-digit hexadecimal number. + + - Function: color->string color + Returns a string representation of COLOR. + + - Function: string->color string + Returns the color represented by STRING. If STRING is not a + syntactically valid notation for a color, then `string->color' + returns #f. + +White +..... + +We experience color relative to the illumination around us. CIEXYZ +coordinates, although subject to uniform scaling, are objective. Thus +other color spaces are specified relative to a "white point" in CIEXYZ +coordinates. + +The white point for digital color spaces is set to D65. For the other +spaces a WHITE-POINT argument can be specified. The default if none is +specified is the white-point with which the color was created or last +converted; and D65 if none has been specified. + + - Constant: D65 + Is the color of 6500.K (blackbody) illumination. D65 is close to + the average color of daylight. + + - Constant: D50 + Is the color of 5000.K (blackbody) illumination. D50 is the color + of indoor lighting by incandescent bulbs, whose filaments have + temperatures around 5000.K. + + ---------- Footnotes ---------- + + (1) Readers may recognize these color string formats from Xlib. +X11's color management system was doomed by its fiction that CRT +monitors' (and X11 default) color-spaces were linear RGBi. Unable to +shed this legacy, the only practical way to view pictures on X is to +ignore its color management system and use an sRGB monitor. In this +implementation the device-independent RGB709 and sRGB spaces replace the +device-dependent RGBi and RGB spaces of Xlib. + + +File: slib.info, Node: Color Spaces, Next: Spectra, Prev: Color Data-Type, Up: Color + +Color Spaces +------------ + +Measurement-based Color Spaces +.............................. + +The "tristimulus" color spaces are those whose component values are +proportional measurements of light intensity. The CIEXYZ(1931) system +provides 3 sets of spectra to convolve with a spectrum of interest. +The result of those convolutions is coordinates in CIEXYZ space. All +tristimuls color spaces are related to CIEXYZ by linear transforms, +namely matrix multiplication. Of the color spaces listed here, CIEXYZ +and RGB709 are tristimulus spaces. + + - Color Space: CIEXYZ + The CIEXYZ color space covers the full "gamut". It is the basis + for color-space conversions. + + CIEXYZ is a list of three inexact numbers between 0 and 1.1. '(0. + 0. 0.) is black; '(1. 1. 1.) is white. + + - Function: ciexyz->color xyz + XYZ must be a list of 3 numbers. If XYZ is valid CIEXYZ + coordinates, then `ciexyz->color' returns the color specified by + XYZ; otherwise returns #f. + + - Function: color:ciexyz x y z + Returns the CIEXYZ color composed of X, Y, Z. If the coordinates + do not encode a valid CIEXYZ color, then an error is signaled. + + - Function: color->ciexyz color + Returns the list of 3 numbers encoding COLOR in CIEXYZ. + + - Color Space: RGB709 + BT.709-4 (03/00) `Parameter values for the HDTV standards for + production and international programme exchange' specifies + parameter values for chromaticity, sampling, signal format, frame + rates, etc., of high definition television signals. + + An RGB709 color is represented by a list of three inexact numbers + between 0 and 1. '(0. 0. 0.) is black '(1. 1. 1.) is white. + + - Function: rgb709->color rgb + RGB must be a list of 3 numbers. If RGB is valid RGB709 + coordinates, then `rgb709->color' returns the color specified by + RGB; otherwise returns #f. + + - Function: color:rgb709 r g b + Returns the RGB709 color composed of R, G, B. If the coordinates + do not encode a valid RGB709 color, then an error is signaled. + + - Function: color->rgb709 color + Returns the list of 3 numbers encoding COLOR in RGB709. + +Perceptual Uniformity +..................... + +Although properly encoding the chromaticity, tristimulus spaces do not +match the logarithmic response of human visual systems to intensity. +Minimum detectable differences between colors correspond to a smaller +range of distances (6:1) in the L*a*b* and L*u*v* spaces than in +tristimulus spaces (80:1). For this reason, color distances are +computed in L*a*b* (or L*C*h). + + - Color Space: L*a*b* + Is a CIE color space which better matches the human visual system's + perception of color. It is a list of three numbers: + + * 0 <= L* <= 100 (CIE "Lightness") + + * -500 <= a* <= 500 + + * -200 <= b* <= 200 + + - Function: l*a*b*->color L*a*b* white-point + L*A*B* must be a list of 3 numbers. If L*A*B* is valid L*a*b* + coordinates, then `l*a*b*->color' returns the color specified by + L*A*B*; otherwise returns #f. + + - Function: color:l*a*b* L* a* b* white-point + Returns the L*a*b* color composed of L*, A*, B* with WHITE-POINT. + + - Function: color:l*a*b* L* a* b* + Returns the L*a*b* color composed of L*, A*, B*. If the + coordinates do not encode a valid L*a*b* color, then an error is + signaled. + + - Function: color->l*a*b* color white-point + Returns the list of 3 numbers encoding COLOR in L*a*b* with + WHITE-POINT. + + - Function: color->l*a*b* color + Returns the list of 3 numbers encoding COLOR in L*a*b*. + + - Color Space: L*u*v* + Is another CIE encoding designed to better match the human visual + system's perception of color. + + - Function: l*u*v*->color L*u*v* white-point + L*U*V* must be a list of 3 numbers. If L*U*V* is valid L*u*v* + coordinates, then `l*u*v*->color' returns the color specified by + L*U*V*; otherwise returns #f. + + - Function: color:l*u*v* L* u* v* white-point + Returns the L*u*v* color composed of L*, U*, V* with WHITE-POINT. + + - Function: color:l*u*v* L* u* v* + Returns the L*u*v* color composed of L*, U*, V*. If the + coordinates do not encode a valid L*u*v* color, then an error is + signaled. + + - Function: color->l*u*v* color white-point + Returns the list of 3 numbers encoding COLOR in L*u*v* with + WHITE-POINT. + + - Function: color->l*u*v* color + Returns the list of 3 numbers encoding COLOR in L*u*v*. + +Cylindrical Coordinates +....................... + +HSL (Hue Saturation Lightness), HSV (Hue Saturation Value), HSI (Hue +Saturation Intensity) and HCI (Hue Chroma Intensity) are cylindrical +color spaces (with angle hue). But these spaces are all defined in +terms device-dependent RGB spaces. + +One might wonder if there is some fundamental reason why intuitive +specification of color must be device-dependent. But take heart! A +cylindrical system can be based on L*a*b* and is used for predicting how +close colors seem to observers. + + - Color Space: L*C*h + Expresses the *a and b* of L*a*b* in polar coordinates. It is a + list of three numbers: + + * 0 <= L* <= 100 (CIE "Lightness") + + * C* (CIE "Chroma") is the distance from the neutral (gray) + axis. + + * 0 <= h <= 360 (CIE "Hue") is the angle. + + The colors by quadrant of h are: + + 0 red, orange, yellow 90 + 90 yellow, yellow-green, green 180 + 180 green, cyan (blue-green), blue 270 + 270 blue, purple, magenta 360 + + + - Function: l*c*h->color L*C*h white-point + L*C*H must be a list of 3 numbers. If L*C*H is valid L*C*h + coordinates, then `l*c*h->color' returns the color specified by + L*C*H; otherwise returns #f. + + - Function: color:l*c*h L* C* h white-point + Returns the L*C*h color composed of L*, C*, H with WHITE-POINT. + + - Function: color:l*c*h L* C* h + Returns the L*C*h color composed of L*, C*, H. If the coordinates + do not encode a valid L*C*h color, then an error is signaled. + + - Function: color->l*c*h color white-point + Returns the list of 3 numbers encoding COLOR in L*C*h with + WHITE-POINT. + + - Function: color->l*c*h color + Returns the list of 3 numbers encoding COLOR in L*C*h. + +Digital Color Spaces +.................... + +The color spaces discussed so far are impractical for image data because +of numerical precision and computational requirements. In 1998 the IEC +adopted `A Standard Default Color Space for the Internet - sRGB' +(<http://www.w3.org/Graphics/Color/sRGB>). sRGB was cleverly designed +to employ the 24-bit (256x256x256) color encoding already in widespread +use; and the 2.2 gamma intrinsic to CRT monitors. + +Conversion from CIEXYZ to digital (sRGB) color spaces is accomplished by +conversion first to a RGB709 tristimulus space with D65 white-point; +then each coordinate is individually subjected to the same non-linear +mapping. Inverse operations in the reverse order create the inverse +transform. + + - Color Space: sRGB + Is "A Standard Default Color Space for the Internet". Most display + monitors will work fairly well with sRGB directly. Systems using + ICC profiles (1) should work very well with sRGB. + + + - Function: srgb->color rgb + RGB must be a list of 3 numbers. If RGB is valid sRGB coordinates, + then `srgb->color' returns the color specified by RGB; otherwise + returns #f. + + - Function: color:srgb r g b + Returns the sRGB color composed of R, G, B. If the coordinates do + not encode a valid sRGB color, then an error is signaled. + + - Color Space: xRGB + Represents the equivalent sRGB color with a single 24-bit integer. + The most significant 8 bits encode red, the middle 8 bits blue, + and the least significant 8 bits green. + + - Function: color->srgb color + Returns the list of 3 integers encoding COLOR in sRGB. + + - Function: color->xrgb color + Returns the 24-bit integer encoding COLOR in sRGB. + + - Function: xrgb->color k + Returns the sRGB color composed of the 24-bit integer K. + + - Color Space: e-sRGB + Is "Photography - Electronic still picture imaging - Extended sRGB + color encoding" (PIMA 7667:2001). It extends the gamut of sRGB; + and its higher precision numbers provide a larger dynamic range. + + A triplet of integers represent e-sRGB colors. Three precisions + are supported: + + e-sRGB10 + 0 to 1023 + + e-sRGB12 + 0 to 4095 + + e-sRGB16 + 0 to 65535 + + - Function: e-srgb->color precision rgb + PRECISION must be the integer 10, 12, or 16. RGB must be a list + of 3 numbers. If RGB is valid e-sRGB coordinates, then + `e-srgb->color' returns the color specified by RGB; otherwise + returns #f. + + - Function: color:e-srgb 10 r g b + Returns the e-sRGB10 color composed of integers R, G, B. + + - Function: color:e-srgb 12 r g b + Returns the e-sRGB12 color composed of integers R, G, B. + + - Function: color:e-srgb 16 r g b + Returns the e-sRGB16 color composed of integers R, G, B. If the + coordinates do not encode a valid e-sRGB color, then an error is + signaled. + + - Function: color->e-srgb precision color + PRECISION must be the integer 10, 12, or 16. `color->e-srgb' + returns the list of 3 integers encoding COLOR in sRGB10, sRGB12, + or sRGB16. + + ---------- Footnotes ---------- + + (1) + +A comprehensive encoding of transforms between CIEXYZ and device color +spaces is the International Color Consortium profile format, +ICC.1:1998-09: + + The intent of this format is to provide a cross-platform device + profile format. Such device profiles can be used to translate + color data created on one device into another device's native + color space. + + +File: slib.info, Node: Spectra, Next: Color Difference Metrics, Prev: Color Spaces, Up: Color + +Spectra +------- + +The following functions compute colors from spectra, scale color +luminance, and extract chromaticity. XYZ is used in the names of +procedures for unnormalized colors; the coordinates of CIEXYZ colors are +constrained as described in *Note Color Spaces::. + + `(require 'color-space)' + +A spectrum may be represented as: + + * A procedure of one argument accepting real numbers from 380e-9 to + 780e-9, the wavelength in meters; or + + * A vector of real numbers representing intensity samples evenly + spaced over some range of wavelengths overlapping the range 380e-9 + to 780e-9. + +CIEXYZ values are calculated as dot-product with the X, Y (Luminance), +and Z "Spectral Tristimulus Values". The files `cie1931.xyz' and +`cie1964.xyz' in the distribution contain these CIE-defined values. + + - Feature: cie1964 + Loads the Spectral Tristimulus Values defining `CIE 1964 + Supplementary Standard Colorimetric Observer'. + + - Feature: cie1931 + Loads the Spectral Tristimulus Values defining `CIE 1931 + Supplementary Standard Colorimetric Observer'. + + - Feature: ciexyz + Requires Spectral Tristimulus Values, defaulting to cie1931. + +`(require 'cie1964)' or `(require 'cie1931)' will `load-ciexyz' | +specific values used by the following spectrum conversion procedures. | +The spectrum conversion procedures `(require 'ciexyz)' to assure that a | +set is loaded. | + + - Function: spectrum->XYZ proc + PROC must be a function of one argument. `spectrum->XYZ' computes + the CIEXYZ(1931) values for the spectrum returned by PROC when + called with arguments from 380e-9 to 780e-9, the wavelength in + meters. + + - Function: spectrum->XYZ spectrum x1 x2 + X1 and X2 must be positive real numbers specifying the wavelengths + (in meters) corresponding to the zeroth and last elements of + vector or list SPECTRUM. `spectrum->XYZ' returns the CIEXYZ(1931) + values for a light source with spectral values proportional to the + elements of SPECTRUM at evenly spaced wavelengths between X1 and + X2. + + Compute the colors of 6500.K and 5000.K blackbody radiation: + + (require 'color-space) + (define xyz (spectrum->XYZ (blackbody-spectrum 6500))) + (define y_n (cadr xyz)) + (map (lambda (x) (/ x y_n)) xyz) + => (0.9687111145512467 1.0 1.1210875945303613) + + (define xyz (spectrum->XYZ (blackbody-spectrum 5000))) + (map (lambda (x) (/ x y_n)) xyz) + => (0.2933441826889158 0.2988931825387761 0.25783646831201573) + + - Function: spectrum->CIEXYZ proc + - Function: spectrum->CIEXYZ spectrum x1 x2 + `spectrum->CIEXYZ' computes the CIEXYZ(1931) values for the + spectrum, scaled so their sum is 1. + + - Function: spectrum->chromaticity proc + - Function: spectrum->chromaticity spectrum x1 x2 + Computes the chromaticity for the given spectrum. + + - Function: wavelength->XYZ w + - Function: wavelength->chromaticity w + - Function: wavelength->CIEXYZ w + W must be a number between 380e-9 to 780e-9. `wavelength->XYZ' + returns (unnormalized) XYZ values for a monochromatic light source + with wavelength W. `wavelength->chromaticity' returns the + chromaticity for a monochromatic light source with wavelength W. + `wavelength->CIEXYZ' returns XYZ values for the saturated color + having chromaticity of a monochromatic light source with wavelength + W. + + - Function: blackbody-spectrum temp + - Function: blackbody-spectrum temp span + Returns a procedure of one argument (wavelength in meters), which + returns the radiance of a black body at TEMP. + + The optional argument SPAN is the wavelength analog of bandwidth. + With the default SPAN of 1.nm (1e-9.m), the values returned by the + procedure correspond to the power of the photons with wavelengths + W to W+1e-9. + + - Function: temperature->XYZ x + The positive number X is a temperature in degrees kelvin. + `temperature->XYZ' computes the CIEXYZ(1931) values for the + spectrum of a black body at temperature X. + + Compute the chromaticities of 6500.K and 5000.K blackbody + radiation: + + (require 'color-space) + (XYZ->chromaticity (temperature->XYZ 6500)) + => (0.3135191660557008 0.3236456786200268) + + (XYZ->chromaticity (temperature->XYZ 5000)) + => (0.34508082841161052 0.3516084965163377) + + - Function: temperature->CIEXYZ x + The positive number X is a temperature in degrees kelvin. + `temperature->CIEXYZ' computes the CIEXYZ(1931) values for the + spectrum of a black body at temperature X, scaled to be just + inside the RGB709 gamut. + + - Function: temperature->chromaticity x | + | + - Function: XYZ:normalize xyz + XYZ is a list of three non-negative real numbers. `XYZ:normalize' + returns a list of numbers proportional to XYZ; scaled so their sum + is 1. + + - Function: XYZ:normalize-colors colors ... + COLORS is a list of XYZ triples. `XYZ:normalize-colors' scales + all the triples by a common factor such that the maximum sum of + numbers in a scaled triple is 1. + + - Function: XYZ->chromaticity xyz + Returns a two element list: the x and y components of XYZ + normalized to 1 (= X + Y + Z). + + - Function: chromaticity->CIEXYZ x y + Returns the list of X, and Y, 1 - Y - X. + + - Function: chromaticity->whitepoint x y + Returns the CIEXYZ(1931) values having luminosity 1 and + chromaticity X and Y. + +Many color datasets are expressed in "xyY" format; chromaticity with +CIE luminance (Y). But xyY is not a CIE standard like CIEXYZ, CIELAB, +and CIELUV. Although chrominance is well defined, the luminance +component is sometimes scaled to 1, sometimes to 100, but usually has no +obvious range. With no given whitepoint, the only reasonable course is +to ascertain the luminance range of a dataset and normalize the values +to lie from 0 to 1. + + - Function: XYZ->xyY xyz + Returns a three element list: the X and Y components of XYZ + normalized to 1, and CIE luminance Y. + + - Function: xyY->XYZ xyY + + - Function: xyY:normalize-colors colors + COLORS is a list of xyY triples. `xyY:normalize-colors' scales + each chromaticity so it sums to 1 or less; and divides the Y + values by the maximum Y in the dataset, so all lie between 0 and 1. + + - Function: xyY:normalize-colors colors n + If N is positive real, then `xyY:normalize-colors' divides the Y + values by N times the maximum Y in the dataset. + + If N is an exact non-positive integer, then `xyY:normalize-colors' + divides the Y values by the maximum of the Ys in the dataset + excepting the -N largest Y values. + + In all cases, returned Y values are limited to lie from 0 to 1. + +Why would one want to normalize to other than 1? If the sun or its +reflection is the brightest object in a scene, then normalizing to its +luminance will tend to make the rest of the scene very dark. As with +photographs, limiting the specular highlights looks better than +darkening everything else. + +The results of measurements being what they are, `xyY:normalize-colors' +is extremely tolerant. Negative numbers are replaced with zero, and +chromaticities with sums greater than one are scaled to sum to one. + + +File: slib.info, Node: Color Difference Metrics, Next: Color Conversions, Prev: Spectra, Up: Color + +Color Difference Metrics +------------------------ + +`(require 'color-space)' | + | + The low-level metric functions operate on lists of 3 numbers, lab1, | +lab2, lch1, or lch2. | + | + `(require 'color)' | + | + The wrapped functions operate on objects of type color, color1 and | +color2 in the function entries. | + | + - Function: L*a*b*:DE* lab1 lab2 | + Returns the Euclidean distance between LAB1 and LAB2. | + | + - Function: CIE:DE* color1 color2 white-point + - Function: CIE:DE* color1 color2 + Returns the Euclidean distance in L*a*b* space between COLOR1 and + COLOR2. + + - Function: L*C*h:DE*94 lch1 lch2 parametric-factors | + - Function: L*C*h:DE*94 lch1 lch2 | + - Function: CIE:DE*94 color1 color2 parametric-factors + - Function: CIE:DE*94 color1 color2 + Measures distance in the L*C*h cylindrical color-space. The three | + axes are individually scaled (depending on C*) in their | + contributions to the total distance. + + The CIE has defined reference conditions under which the metric + with default parameters can be expected to perform well. These + are: + + * The specimens are homogeneous in colour. + + * The colour difference (CIELAB) is <= 5 units. + + * They are placed in direct edge contact. + + * Each specimen subtends an angle of >4 degrees to the + assessor, whose colour vision is normal. + + * They are illuminated at 1000 lux, and viewed against a + background of uniform grey, with L* of 50, under illumination + simulating D65. + + The PARAMETRIC-FACTORS argument is a list of 3 quantities kL, kC + and kH. PARAMETRIC-FACTORS independently adjust each + colour-difference term to account for any deviations from the + reference viewing conditions. Under the reference conditions + explained above, the default is kL = kC = kH = 1. + +The Color Measurement Committee of The Society of Dyers and Colorists in +Great Britain created a more sophisticated color-distance function for +use in judging the consistency of dye lots. With CMC:DE* it is possible +to use a single value pass/fail tolerance for all shades. + + - Function: CMC-DE lch1 lch2 parametric-factors | + - Function: CMC-DE lch1 lch2 l c | + - Function: CMC-DE lch1 lch2 l | + - Function: CMC-DE lch1 lch2 | + - Function: CMC:DE* color1 color2 l c + - Function: CMC:DE* color1 color2 + `CMC:DE' is a L*C*h metric. The PARAMETRIC-FACTORS argument is a | + list of 2 numbers L and C. L and C parameterize this metric. 1 | + and 1 are recommended for perceptibility; the default, 2 and 1, | + for acceptability. + + +File: slib.info, Node: Color Conversions, Next: Color Names, Prev: Color Difference Metrics, Up: Color + +Color Conversions +----------------- + +This package contains the low-level color conversion and color metric +routines operating on lists of 3 numbers. There is no type or range +checking. + + `(require 'color-space)' + + - Constant: CIEXYZ:D65 + Is the color of 6500.K (blackbody) illumination. D65 is close to + the average color of daylight. + + - Constant: CIEXYZ:D50 + Is the color of 5000.K (blackbody) illumination. D50 is the color + of indoor lighting by incandescent bulbs. + + - Constant: CIEXYZ:A + - Constant: CIEXYZ:B + - Constant: CIEXYZ:C + - Constant: CIEXYZ:E + CIE 1931 illuminants normalized to 1 = y. + + - Function: color:linear-transform matrix row | + | + - Function: CIEXYZ->RGB709 xyz + - Function: RGB709->CIEXYZ srgb + + - Function: CIEXYZ->L*u*v* xyz white-point + - Function: CIEXYZ->L*u*v* xyz + - Function: L*u*v*->CIEXYZ L*u*v* white-point + - Function: L*u*v*->CIEXYZ L*u*v* + The WHITE-POINT defaults to CIEXYZ:D65. + + - Function: CIEXYZ->L*a*b* xyz white-point + - Function: CIEXYZ->L*a*b* xyz + - Function: L*a*b*->CIEXYZ L*a*b* white-point + - Function: L*a*b*->CIEXYZ L*a*b* + The XYZ WHITE-POINT defaults to CIEXYZ:D65. + + - Function: L*a*b*->L*C*h L*a*b* + - Function: L*C*h->L*a*b* L*C*h + + - Function: CIEXYZ->sRGB xyz + - Function: sRGB->CIEXYZ srgb + + - Function: CIEXYZ->xRGB xyz | + - Function: xRGB->CIEXYZ srgb | + | + - Function: sRGB->xRGB xyz | + - Function: xRGB->sRGB srgb | + | + - Function: CIEXYZ->e-sRGB n xyz + - Function: e-sRGB->CIEXYZ n srgb + + - Function: sRGB->e-sRGB n srgb + - Function: e-sRGB->sRGB n srgb + The integer N must be 10, 12, or 16. Because sRGB and e-sRGB use + the same RGB709 chromaticities, conversion between them is simpler + than conversion through CIEXYZ. + +Do not convert e-sRGB precision through `e-sRGB->sRGB' then +`sRGB->e-sRGB' - values would be truncated to 8-bits! + + - Function: e-sRGB->e-sRGB n1 srgb n2 + The integers N1 and N2 must be 10, 12, or 16. `e-sRGB->e-sRGB' + converts SRGB to e-sRGB of precision N2. + | + +File: slib.info, Node: Color Names, Next: Daylight, Prev: Color Conversions, Up: Color + +Color Names +----------- + +`(require 'color-names)' + +Rather than ballast the color dictionaries with numbered grays, +`file->color-dictionary' discards them. They are provided through the +`grey' procedure: + + - Function: grey k + Returns `(inexact->exact (round (* k 2.55)))', the X11 color + grey<k>. + +A color dictionary is a database table relating "canonical" color-names +to color-strings (*note External Representation: Color Data-Type.). + +The column names in a color dictionary are unimportant; the first field +is the key, and the second is the color-string. + + - Function: color-name:canonicalize name + Returns a downcased copy of the string or symbol NAME with `_', + `-', and whitespace removed. + + - Function: color-name->color name table1 table2 ... + TABLE1, TABLE2, ... must be color-dictionary tables. + `color-name->color' searches for the canonical form of NAME in + TABLE1, TABLE2, ... in order; returning the color-string of the + first matching record; #f otherwise. + + - Function: color-dictionaries->lookup table1 table2 ... + TABLE1, TABLE2, ... must be color-dictionary tables. + `color-dictionaries->lookup' returns a procedure which searches + for the canonical form of its string argument in TABLE1, TABLE2, + ...; returning the color-string of the first matching record; and + #f otherwise. + + - Function: color-dictionary name rdb base-table-type + RDB must be a string naming a relational database file; and the + symbol NAME a table therein. The database will be opened as + BASE-TABLE-TYPE. `color-dictionary' returns the read-only table + NAME in database NAME if it exists; #f otherwise. + + - Function: color-dictionary name rdb + RDB must be an open relational database or a string naming a + relational database file; and the symbol NAME a table therein. + `color-dictionary' returns the read-only table NAME in database + NAME if it exists; #f otherwise. + + - Function: load-color-dictionary name rdb base-table-type + - Function: load-color-dictionary name rdb + RDB must be a string naming a relational database file; and the + symbol NAME a table therein. If the symbol BASE-TABLE-TYPE is + provided, the database will be opened as BASE-TABLE-TYPE. + `load-color-dictionary' creates a top-level definition of the + symbol NAME to a lookup procedure for the color dictionary NAME in + RDB. + + The value returned by `load-color-dictionary' is unspecified. + +Dictionary Creation +................... + +`(require 'color-database)' | + | + - Function: file->color-dictionary file table-name rdb base-table-type + - Function: file->color-dictionary file table-name rdb + RDB must be an open relational database or a string naming a + relational database file, TABLE-NAME a symbol, and the string FILE + must name an existing file with colornames and their corresponding + xRGB (6-digit hex) values. `file->color-dictionary' creates a + table TABLE-NAME in RDB and enters the associations found in FILE + into it. + + - Function: url->color-dictionary url table-name rdb base-table-type + - Function: url->color-dictionary url table-name rdb + RDB must be an open relational database or a string naming a + relational database file and TABLE-NAME a symbol. + `url->color-dictionary' retrieves the resource named by the string + URL using the "wget" program; then calls `file->color-dictionary' + to enter its associations in TABLE-NAME in URL. + +This section has detailed the procedures for creating and loading color +dictionaries. So where are the dictionaries to load? + + `http://swissnet.ai.mit.edu/~jaffer/Color/Dictionaries.html' + +Describes and evaluates several color-name dictionaries on the web. +The following procedure creates a database containing two of these +dictionaries. + + - Function: make-slib-color-name-db + Creates an alist-table relational database in library-vicinity + containing the "Resene" and "saturate" color-name dictionaries. + + If the files `resenecolours.txt' and `saturate.txt' exist in the + library-vicinity, then they used as the source of color-name data. + Otherwise, `make-slib-color-name-db' calls url->color-dictionary + with the URLs of appropriate source files. + +The Short List +.............. + +`(require 'saturate)' + + - Function: saturate name + Looks for NAME among the 19 saturated colors from `Approximate + Colors on CIE Chromaticity Diagram': + + reddish orange orange yellowish orange yellow + greenish yellow yellow green yellowish green green + bluish green blue green greenish blue blue + purplish blue bluish purple purple reddish purple + red purple purplish red red + + (<http://swissnet.ai.mit.edu/~jaffer/Color/saturate.pdf>). If + NAME is found, the corresponding color is returned. Otherwise #f + is returned. Use saturate only for light source colors. + +Resene Paints Limited, New Zealand's largest privately-owned and +operated paint manufacturing company, has generously made their `Resene +RGB Values List' available. + + `(require 'resene)' + + - Function: resene name + Looks for NAME among the 1300 entries in the Resene color-name + dictionary (<http://swissnet.ai.mit.edu/~jaffer/Color/resene.pdf>). + If NAME is found, the corresponding color is returned. Otherwise + #f is returned. The `Resene RGB Values List' is an excellent + source for surface colors. + +If you include the "Resene RGB Values List" in binary form in a +program, then you must include its license with your program: + + Resene RGB Values List + For further information refer to http://www.resene.co.nz + Copyright Resene Paints Ltd 2001 + + Permission to copy this dictionary, to modify it, to redistribute + it, to distribute modified versions, and to use it for any purpose + is granted, subject to the following restrictions and + understandings. + + 1. Any text copy made of this dictionary must include this + copyright notice in full. + + 2. Any redistribution in binary form must reproduce this + copyright notice in the documentation or other materials + provided with the distribution. + + 3. Resene Paints Ltd makes no warranty or representation that | + this dictionary is error-free, and is under no obligation to + provide any services, by way of maintenance, update, or + otherwise. + + 4. There shall be no use of the name of Resene or Resene Paints + Ltd in any advertising, promotional, or sales literature + without prior written consent in each case. + + 5. These RGB colour formulations may not be used to the + detriment of Resene Paints Ltd. + + +File: slib.info, Node: Daylight, Prev: Color Names, Up: Color + +Daylight +-------- + +`(require 'daylight)' + +This package calculates the colors of sky as detailed in: +`http://www.cs.utah.edu/vissim/papers/sunsky/sunsky.pdf' +`A Practical Analytic Model for Daylight' +A. J. Preetham, Peter Shirley, Brian Smits + + - Function: solar-hour julian-day hour + Returns the solar-time in hours given the integer JULIAN-DAY in + the range 1 to 366, and the local time in hours. + + To be meticulous, subtract 4 minutes for each degree of longitude + west of the standard meridian of your time zone. + + - Function: solar-declination julian-day + + - Function: solar-polar declination latitude solar-hour + Returns a list of THETA_S, the solar angle from the zenith, and + PHI_S, the solar azimuth. 0 <= THETA_S measured in degrees. + PHI_S is measured in degrees from due south; west of south being + positive. + +In the following procedures, the number 0 <= THETA_S <= 90 is the solar +angle from the zenith in degrees. + +Turbidity is a measure of the fraction of scattering due to haze as +opposed to molecules. This is a convenient quantity because it can be +estimated based on visibility of distant objects. This model fails for +turbidity values less than 1.3. + + _______________________________________________________________ + 512|-: | + | * pure-air | + 256|-:** | + | : ** exceptionally-clear | + 128|-: * | + | : ** | + 64|-: * | + | : ** very-clear | + 32|-: ** | + | : ** | + 16|-: *** clear | + | : **** | + 8|-: **** | + | : **** light-haze | + 4|-: **** | + | : ****** | + 2|-: ******** haze thin-| + | : *********** fog | + 1|-:----------------------------------------------------*******--| + |_:____.____:____.____:____.____:____.____:____.____:____.____:_| + 1 2 4 8 16 32 64 + Meterorological range (km) versus Turbidity + + - Function: sunlight-spectrum turbidity theta_s + Returns a vector of 41 values, the spectrum of sunlight from + 380.nm to 790.nm for a given TURBIDITY and THETA_S. + + - Function: sunlight-xyz turbidity theta_s + Returns (unnormalized) XYZ values for color of sunlight for a + given TURBIDITY and THETA_S. + + - Function: sunlight-ciexyz turbidity theta_s + Given TURBIDITY and THETA_S, `sunlight-ciexyz' returns the CIEXYZ + triple for color of sunlight scaled to be just inside the RGB709 + gamut. + + - Function: zenith-xyy turbidity theta_s + Returns the xyY (chromaticity and luminance) at the zenith. The + Luminance has units kcd/m^2. + + - Function: overcast-sky-color-xyy turbidity theta_s + TURBIDITY is a positive real number expressing the amount of light + scattering. The real number THETA_S is the solar angle from the + zenith in degrees. + + `overcast-sky-color-xyy' returns a function of one angle THETA, + the angle from the zenith of the viewing direction (in degrees); + and returning the xyY value for light coming from that elevation + of the sky. + + - Function: clear-sky-color-xyy turbidity theta_s phi_s + - Function: sky-color-xyy turbidity theta_s phi_s + TURBIDITY is a positive real number expressing the amount of light + scattering. The real number THETA_S is the solar angle from the + zenith in degrees. The real number PHI_S is the solar angle from + south. + + `clear-sky-color-xyy' returns a function of two angles, THETA and + PHI which specify the angles from the zenith and south meridian of + the viewing direction (in degrees); returning the xyY value for + light coming from that direction of the sky. + + `sky-color-xyY' calls `overcast-sky-color-xyY' for TURBIDITY <= + 20; otherwise the `clear-sky-color-xyy' function. + + +File: slib.info, Node: Root Finding, Next: Minimizing, Prev: Color, Up: Mathematical Packages Root Finding ============ - `(require 'root)' +`(require 'root)' - - Function: newtown:find-integer-root f df/dx x0 + - Function: newton:find-integer-root f df/dx x0 Given integer valued procedure F, its derivative (with respect to its argument) DF/DX, and initial integer value X0 for which DF/DX(X0) is non-zero, returns an integer X for which F(X) is @@ -5600,7 +7849,7 @@ File: slib.info, Node: Minimizing, Next: Commutative Rings, Prev: Root Findin Minimizing ========== - `(require 'minimize)' +`(require 'minimize)' The Golden Section Search (1) algorithm finds minima of functions which are expensive to compute or for which derivatives are not available. @@ -5642,12 +7891,12 @@ approximating the derivative. and Software' Prentice-Hall, 1989, ISBN 0-13-627258-4 -File: slib.info, Node: Commutative Rings, Next: Determinant, Prev: Minimizing, Up: Mathematical Packages +File: slib.info, Node: Commutative Rings, Next: Matrix Algebra, Prev: Minimizing, Up: Mathematical Packages Commutative Rings ================= - Scheme provides a consistent and capable set of numeric functions. +Scheme provides a consistent and capable set of numeric functions. Inexacts implement a field; integers a commutative ring (and Euclidean domain). This package allows one to use basic Scheme numeric functions with symbols and non-numeric elements of commutative rings. @@ -5713,7 +7962,7 @@ restrictive Euclidean (Unique Factorization) Domain. Rules and Rulesets ================== - The "commutative-ring" package allows control of ring properties +The "commutative-ring" package allows control of ring properties through the use of "rulesets". - Variable: *ruleset* @@ -5741,11 +7990,11 @@ through the use of "rulesets". Two rulesets are defined by this package. - Constant: distribute* - Contain the ruleset to distribute multiplication over addition and + Contains the ruleset to distribute multiplication over addition and subtraction. - Constant: distribute/ - Contain the ruleset to distribute division over addition and + Contains the ruleset to distribute division over addition and subtraction. Take care when using both DISTRIBUTE* and DISTRIBUTE/ @@ -5787,12 +8036,12 @@ involving different non-numeric elements. How to Create a Commutative Ring ================================ - The first step in creating your commutative ring is to write -procedures to create elements of the ring. A non-numeric element of -the ring must be represented as a list whose first element is a symbol -or string. This first element identifies the type of the object. A -convenient and clear convention is to make the type-identifying element -be the same symbol whose top-level value is the procedure to create it. +The first step in creating your commutative ring is to write procedures +to create elements of the ring. A non-numeric element of the ring must +be represented as a list whose first element is a symbol or string. +This first element identifies the type of the object. A convenient and +clear convention is to make the type-identifying element be the same +symbol whose top-level value is the procedure to create it. (define (n . list1) (cond ((and (= 2 (length list1)) @@ -5856,14 +8105,14 @@ have _not_ been defined are not changed. (define (splice list1 list2) (cond ((eq? (last1 list1) (first list2)) (append list1 (cdr list2))) - (else (error 'splice list1 list2)))) + (else (slib:error 'splice list1 list2)))) ;;; where cyclicsplice is the result of leaving off the last element of ;;; splice(list1,list2). (define (cyclicsplice list1 list2) (cond ((and (eq? (last1 list1) (first list2)) (eq? (first list1) (last1 list2))) (butlast (splice list1 list2) 1)) - (else (error 'cyclicsplice list1 list2)))) + (else (slib:error 'cyclicsplice list1 list2)))) (N*N (S a b) (S a b)) => (m a b) @@ -5921,18 +8170,41 @@ objects. (* (m a c e b g) (m d f))) -File: slib.info, Node: Determinant, Prev: Commutative Rings, Up: Mathematical Packages +File: slib.info, Node: Matrix Algebra, Prev: Commutative Rings, Up: Mathematical Packages -Determinant -=========== +Matrix Algebra +============== + +`(require 'determinant)' + +A Matrix can be either a list of lists (rows) or an array. As with +linear-algebra texts, this package uses 1-based coordinates. + + - Function: matrix->lists matrix + Returns the list-of-lists form of MATRIX. - - Function: determinant square-matrix - Returns the determinant of SQUARE-MATRIX. + - Function: matrix->array matrix + Returns the (ones-based) array form of MATRIX. + + - Function: determinant matrix + MATRIX must be a square matrix. `determinant' returns the + determinant of MATRIX. (require 'determinant) (determinant '((1 2) (3 4))) => -2 (determinant '((1 2 3) (4 5 6) (7 8 9))) => 0 - (determinant '((1 2 3 4) (5 6 7 8) (9 10 11 12))) => 0 + + - Function: transpose matrix + Returns a copy of MATRIX flipped over the diagonal containing the + 1,1 element. + + - Function: matrix:product m1 m2 + Returns the product of matrices M1 and M2. + + - Function: matrix:inverse matrix + MATRIX must be a square matrix. If MATRIX is singlar, then + `matrix:inverse' returns #f; otherwise `matrix:inverse' returns the + `matrix:product' inverse of MATRIX. File: slib.info, Node: Database Packages, Next: Other Packages, Prev: Mathematical Packages, Up: Top @@ -5941,501 +8213,264 @@ Database Packages ***************** * Menu: - -* Base Table:: + | * Relational Database:: 'relational-database +* Relational Infrastructure:: | * Weight-Balanced Trees:: 'wt-tree -File: slib.info, Node: Base Table, Next: Relational Database, Prev: Database Packages, Up: Database Packages +File: slib.info, Node: Relational Database, Next: Relational Infrastructure, Prev: Database Packages, Up: Database Packages + | +Relational Database +=================== -Base Table -========== +`(require 'relational-database)' - A base table implementation using Scheme association lists is -available as the value of the identifier `alist-table' after doing: - - `(require 'alist-table)' - - Association list base tables are suitable for small databases and -support all Scheme types when temporary and readable/writeable Scheme -types when saved. I hope support for other base table implementations -will be added in the future. - - This rest of this section documents the interface for a base table -implementation from which the *Note Relational Database:: package -constructs a Relational system. It will be of interest primarily to -those wishing to port or write new base-table implementations. - - All of these functions are accessed through a single procedure by -calling that procedure with the symbol name of the operation. A -procedure will be returned if that operation is supported and `#f' -otherwise. For example: - - (require 'alist-table) - (define open-base (alist-table 'make-base)) - make-base => *a procedure* - (define foo (alist-table 'foo)) - foo => #f - - - Function: make-base filename key-dimension column-types - Returns a new, open, low-level database (collection of tables) - associated with FILENAME. This returned database has an empty - table associated with CATALOG-ID. The positive integer - KEY-DIMENSION is the number of keys composed to make a PRIMARY-KEY - for the catalog table. The list of symbols COLUMN-TYPES describes - the types of each column for that table. If the database cannot - be created as specified, `#f' is returned. - - Calling the `close-base' method on this database and possibly other - operations will cause FILENAME to be written to. If FILENAME is - `#f' a temporary, non-disk based database will be created if such - can be supported by the base table implelentation. - - - Function: open-base filename mutable - Returns an open low-level database associated with FILENAME. If - MUTABLE? is `#t', this database will have methods capable of - effecting change to the database. If MUTABLE? is `#f', only - methods for inquiring the database will be available. If the - database cannot be opened as specified `#f' is returned. - - Calling the `close-base' (and possibly other) method on a MUTABLE? - database will cause FILENAME to be written to. - - - Function: write-base lldb filename - Causes the low-level database LLDB to be written to FILENAME. If - the write is successful, also causes LLDB to henceforth be - associated with FILENAME. Calling the `close-database' (and - possibly other) method on LLDB may cause FILENAME to be written - to. If FILENAME is `#f' this database will be changed to a - temporary, non-disk based database if such can be supported by the - underlying base table implelentation. If the operations completed - successfully, `#t' is returned. Otherwise, `#f' is returned. - - - Function: sync-base lldb - Causes the file associated with the low-level database LLDB to be - updated to reflect its current state. If the associated filename - is `#f', no action is taken and `#f' is returned. If this - operation completes successfully, `#t' is returned. Otherwise, - `#f' is returned. + This package implements a database system inspired by the Relational +Model (`E. F. Codd, A Relational Model of Data for Large Shared Data +Banks'). An SLIB relational database implementation can be created +from any *Note Base Table:: implementation. - - Function: close-base lldb - Causes the low-level database LLDB to be written to its associated - file (if any). If the write is successful, subsequent operations - to LLDB will signal an error. If the operations complete - successfully, `#t' is returned. Otherwise, `#f' is returned. - - - Function: make-table lldb key-dimension column-types - Returns the BASE-ID for a new base table, otherwise returns `#f'. - The base table can then be opened using `(open-table LLDB - BASE-ID)'. The positive integer KEY-DIMENSION is the number of - keys composed to make a PRIMARY-KEY for this table. The list of - symbols COLUMN-TYPES describes the types of each column. - - - Constant: catalog-id - A constant BASE-ID suitable for passing as a parameter to - `open-table'. CATALOG-ID will be used as the base table for the - system catalog. - - - Function: open-table lldb base-id key-dimension column-types - Returns a HANDLE for an existing base table in the low-level - database LLDB if that table exists and can be opened in the mode - indicated by MUTABLE?, otherwise returns `#f'. - - As with `make-table', the positive integer KEY-DIMENSION is the - number of keys composed to make a PRIMARY-KEY for this table. The - list of symbols COLUMN-TYPES describes the types of each column. - - - Function: kill-table lldb base-id key-dimension column-types - Returns `#t' if the base table associated with BASE-ID was removed - from the low level database LLDB, and `#f' otherwise. - - - Function: make-keyifier-1 type - Returns a procedure which accepts a single argument which must be - of type TYPE. This returned procedure returns an object suitable - for being a KEY argument in the functions whose descriptions - follow. - - Any 2 arguments of the supported type passed to the returned - function which are not `equal?' must result in returned values - which are not `equal?'. - - - Function: make-list-keyifier key-dimension types - The list of symbols TYPES must have at least KEY-DIMENSION - elements. Returns a procedure which accepts a list of length - KEY-DIMENSION and whose types must corresopond to the types named - by TYPES. This returned procedure combines the elements of its - list argument into an object suitable for being a KEY argument in - the functions whose descriptions follow. - - Any 2 lists of supported types (which must at least include - symbols and non-negative integers) passed to the returned function - which are not `equal?' must result in returned values which are not - `equal?'. - - - Function: make-key-extractor key-dimension types column-number - Returns a procedure which accepts objects produced by application - of the result of `(make-list-keyifier KEY-DIMENSION TYPES)'. This - procedure returns a KEY which is `equal?' to the COLUMN-NUMBERth - element of the list which was passed to create COMBINED-KEY. The - list TYPES must have at least KEY-DIMENSION elements. - - - Function: make-key->list key-dimension types - Returns a procedure which accepts objects produced by application - of the result of `(make-list-keyifier KEY-DIMENSION TYPES)'. This - procedure returns a list of KEYs which are elementwise `equal?' to - the list which was passed to create COMBINED-KEY. - -In the following functions, the KEY argument can always be assumed to -be the value returned by a call to a _keyify_ routine. - -In contrast, a MATCH-KEYS argument is a list of length equal to the -number of primary keys. The MATCH-KEYS restrict the actions of the -table command to those records whose primary keys all satisfy the -corresponding element of the MATCH-KEYS list. The elements and their -actions are: - - `#f' - The false value matches any key in the corresponding position. - - an object of type procedure - This procedure must take a single argument, the key in the - corresponding position. Any key for which the procedure - returns a non-false value is a match; Any key for which the - procedure returns a `#f' is not. - - other values - Any other value matches only those keys `equal?' to it. - -The KEY-DIMENSION and COLUMN-TYPES arguments are needed to decode the -combined-keys for matching with MATCH-KEYS. - - - Function: for-each-key handle procedure key-dimension column-types - match-keys - Calls PROCEDURE once with each KEY in the table opened in HANDLE - which satisfy MATCH-KEYS in an unspecified order. An unspecified - value is returned. - - - Function: map-key handle procedure key-dimension column-types - match-keys - Returns a list of the values returned by calling PROCEDURE once - with each KEY in the table opened in HANDLE which satisfy - MATCH-KEYS in an unspecified order. - - - Function: ordered-for-each-key handle procedure key-dimension - column-types match-keys - Calls PROCEDURE once with each KEY in the table opened in HANDLE - which satisfy MATCH-KEYS in the natural order for the types of the - primary key fields of that table. An unspecified value is - returned. + Why relational database? For motivations and design issues see +`http://swissnet.ai.mit.edu/~jaffer/DBManifesto.html'. - - Function: delete* handle key-dimension column-types match-keys - Removes all rows which satisfy MATCH-KEYS from the table opened in - HANDLE. An unspecified value is returned. +* Menu: - - Function: present? handle key - Returns a non-`#f' value if there is a row associated with KEY in - the table opened in HANDLE and `#f' otherwise. +* Using Databases:: 'databases | +* Table Operations:: +* Database Interpolation:: 'database-interpolate | +* Embedded Commands:: 'database-commands +* Database Macros:: 'within-database | +* Database Browser:: 'database-browse - - Function: delete handle key - Removes the row associated with KEY from the table opened in - HANDLE. An unspecified value is returned. + +File: slib.info, Node: Using Databases, Next: Table Operations, Prev: Relational Database, Up: Relational Database + | +Using Databases +--------------- - - Function: make-getter key-dimension types - Returns a procedure which takes arguments HANDLE and KEY. This - procedure returns a list of the non-primary values of the relation - (in the base table opened in HANDLE) whose primary key is KEY if - it exists, and `#f' otherwise. +`(require 'databases)' - - Function: make-putter key-dimension types - Returns a procedure which takes arguments HANDLE and KEY and - VALUE-LIST. This procedure associates the primary key KEY with - the values in VALUE-LIST (in the base table opened in HANDLE) and - returns an unspecified value. +This enhancement wraps a utility layer on `relational-database' which +provides: - - Function: supported-type? symbol - Returns `#t' if SYMBOL names a type allowed as a column value by - the implementation, and `#f' otherwise. At a minimum, an - implementation must support the types `integer', `symbol', - `string', `boolean', and `base-id'. + * Identification of open databases by filename. - - Function: supported-key-type? symbol - Returns `#t' if SYMBOL names a type allowed as a key value by the - implementation, and `#f' otherwise. At a minimum, an - implementation must support the types `integer', and `symbol'. + * Automatic sharing of open (immutable) databases. -`integer' - Scheme exact integer. + * Automatic loading of base-table package when creating a database. -`symbol' - Scheme symbol. + * Detection and automatic loading of the appropriate base-table + package when opening a database. -`boolean' - `#t' or `#f'. + * Table and data definition from Scheme lists. -`base-id' - Objects suitable for passing as the BASE-ID parameter to - `open-table'. The value of CATALOG-ID must be an acceptable - `base-id'. +Database Sharing +................ - -File: slib.info, Node: Relational Database, Next: Weight-Balanced Trees, Prev: Base Table, Up: Database Packages +"Auto-sharing" refers to a call to the procedure `open-database' +returning an already open database (procedure), rather than opening the +database file a second time. -Relational Database -=================== + _Note:_ Databases returned by `open-database' do not include + wrappers applied by packages like *Note Embedded Commands::. But + wrapped databases do work as arguments to these functions. - `(require 'relational-database)' +When a database is created, it is mutable by the creator and not +auto-sharable. A database opened mutably is also not auto-sharable. +But any number of readers can (open) share a non-mutable database file. - This package implements a database system inspired by the Relational -Model (`E. F. Codd, A Relational Model of Data for Large Shared Data -Banks'). An SLIB relational database implementation can be created -from any *Note Base Table:: implementation. +This next set of procedures mirror the whole-database methods in *Note +Database Operations::. Except for `create-database', each procedure +will accept either a filename or database procedure for its first +argument. -* Menu: + - Function: create-database filename base-table-type + FILENAME should be a string naming a file; or `#f'. | + BASE-TABLE-TYPE must be a symbol naming a feature which can be | + passed to `require'. `create-database' returns a new, open | + relational database (with base-table type BASE-TABLE-TYPE) | + associated with FILENAME, or a new ephemeral database if FILENAME | + is `#f'. | + + `create-database' is the only run-time use of require in SLIB | + which crosses module boundaries. When BASE-TABLE-TYPE is | + `require'd by `create-database'; it adds an association of | + BASE-TABLE-TYPE with its "relational-system" procedure to | + MDBM:*DATABASES*. | + + alist-table is the default base-table type: | + | + (require 'databases) | + (define my-rdb (create-database "my.db" 'alist-table)) | + | +Only `alist-table' and base-table modules which have been `require'd | +will dispatch correctly from the `open-database' procedures. | +Therefore, either pass two arguments to `open-database', or require the | +base-table of your database file uses before calling `open-database' | +with one argument. | + | + - Procedure: open-database! rdb base-table-type | + Returns _mutable_ open relational database or #f. -* Motivations:: Database Manifesto -* Creating and Opening Relational Databases:: -* Relational Database Operations:: -* Table Operations:: -* Catalog Representation:: -* Unresolved Issues:: -* Database Utilities:: 'database-utilities -* Database Reports:: -* Database Browser:: 'database-browse + - Function: open-database rdb base-table-type + Returns an open relational database associated with RDB. The + database will be opened with base-table type BASE-TABLE-TYPE). - -File: slib.info, Node: Motivations, Next: Creating and Opening Relational Databases, Prev: Relational Database, Up: Relational Database + - Function: open-database rdb + Returns an open relational database associated with RDB. + `open-database' will attempt to deduce the correct base-table-type. -Motivations ------------ + - Function: write-database rdb filename + Writes the mutable relational-database RDB to FILENAME. - Most nontrivial programs contain databases: Makefiles, configure -scripts, file backup, calendars, editors, source revision control, CAD -systems, display managers, menu GUIs, games, parsers, debuggers, -profilers, and even error reporting are all rife with databases. Coding -databases is such a common activity in programming that many may not be -aware of how often they do it. - - A database often starts as a dispatch in a program. The author, -perhaps because of the need to make the dispatch configurable, the need -for correlating dispatch in other routines, or because of changes or -growth, devises a data structure to contain the information, a routine -for interpreting that data structure, and perhaps routines for -augmenting and modifying the stored data. The dispatch must be -converted into this form and tested. - - The programmer may need to devise an interactive program for enabling -easy examination and modification of the information contained in this -database. Often, in an attempt to foster modularity and avoid delays in -release, intermediate file formats for the database information are -devised. It often turns out that users prefer modifying these -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 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 _almost_ -has language "xyz" syntax) in order to do simple configuration. - - All of these facilities need to be designed, coded, debugged, -documented, and supported; often causing what was very simple in concept -to become a major developement project. - - This view of databases just outlined is somewhat the reverse of the -view of the originators of the "Relational Model" of database -abstraction. The relational model was devised to unify and allow -interoperation of large multi-user databases running on diverse -platforms. A fairly general purpose "Comprehensive Language" for -database manipulations is mandated (but not specified) as part of the -relational model for databases. - - One aspect of the Relational Model of some importance is that the -"Comprehensive Language" must be expressible in some form which can be -stored in the database. This frees the programmer from having to make -programs data-driven in order to use a database. - - This package includes as one of its basic supported types Scheme -"expression"s. This type allows expressions as defined by the Scheme -standards to be stored in the database. Using `slib:eval' retrieved -expressions can be evaluated (in the top-level environment). Scheme's -`lambda' facilitates closure of environments, modularity, etc. so that -procedures (which could not be stored directly most databases) can -still be effectively retrieved. Since `slib:eval' evaluates -expressions in the top-level environment, built-in and user defined -procedures can be easily accessed by name. - - This package's purpose is to standardize (through a common interface) -database creation and usage in Scheme programs. The relational model's -provision for inclusion of language expressions as data as well as the -description (in tables, of course) of all of its tables assures that -relational databases are powerful enough to assume the roles currently -played by thousands of ad-hoc routines and data formats. - -Such standardization to a relational-like model brings many benefits: - - * Tables, fields, domains, and types can be dealt with by name in - programs. - - * The underlying database implementation can be changed (for - performance or other reasons) by changing a single line of code. - - * The formats of tables can be easily extended or changed without - altering code. - - * Consistency checks are specified as part of the table descriptions. - Changes in checks need only occur in one place. - - * All the configuration information which the developer wishes to - group together is easily grouped, without needing to change - programs aware of only some of these tables. - - * Generalized report generators, interactive entry programs, and - other database utilities can be part of a shared library. The - burden of adding configurability to a program is greatly reduced. - - * Scheme is the "comprehensive language" for these databases. - Scripting for configuration no longer needs to be in a separate - language with additional documentation. - - * Scheme's latent types mesh well with the strict typing and logical - requirements of the relational model. - - * Portable formats allow easy interchange of data. The included - table descriptions help prevent misinterpretation of format. - - -File: slib.info, Node: Creating and Opening Relational Databases, Next: Relational Database Operations, Prev: Motivations, Up: Relational Database - -Creating and Opening Relational Databases ------------------------------------------ + - Function: sync-database rdb + Writes the mutable relational-database RDB to the filename it was + opened with. - - Function: make-relational-system base-table-implementation - Returns a procedure implementing a relational database using the - BASE-TABLE-IMPLEMENTATION. - - All of the operations of a base table implementation are accessed - through a procedure defined by `require'ing that implementation. - Similarly, all of the operations of the relational database - implementation are accessed through the procedure returned by - `make-relational-system'. For instance, a new relational database - could be created from the procedure returned by - `make-relational-system' by: - - (require 'alist-table) - (define relational-alist-system - (make-relational-system alist-table)) - (define create-alist-database - (relational-alist-system 'create-database)) - (define my-database - (create-alist-database "mydata.db")) - -What follows are the descriptions of the methods available from -relational system returned by a call to `make-relational-system'. - - - Function: create-database filename - Returns an open, nearly empty relational database associated with - FILENAME. The only tables defined are the system catalog and - domain table. Calling the `close-database' method on this database - and possibly other operations will cause FILENAME to be written - to. If FILENAME is `#f' a temporary, non-disk based database will - be created if such can be supported by the underlying base table - implelentation. If the database cannot be created as specified - `#f' is returned. For the fields and layout of descriptor tables, - *Note Catalog Representation:: - - - Function: open-database filename mutable? - Returns an open relational database associated with FILENAME. If - MUTABLE? is `#t', this database will have methods capable of - effecting change to the database. If MUTABLE? is `#f', only - methods for inquiring the database will be available. Calling the - `close-database' (and possibly other) method on a MUTABLE? - database will cause FILENAME to be written to. If the database - cannot be opened as specified `#f' is returned. - - -File: slib.info, Node: Relational Database Operations, Next: Table Operations, Prev: Creating and Opening Relational Databases, Up: Relational Database - -Relational Database Operations ------------------------------- + - Function: solidify-database rdb + Syncs RDB and makes it immutable. -These are the descriptions of the methods available from an open -relational database. A method is retrieved from a database by calling -the database with the symbol name of the operation. For example: + - Function: close-database rdb + RDB will only be closed when the count of `open-database' - + `close-database' calls for RDB (and its filename) is 0. + `close-database' returns #t if successful; and #f otherwise. - (define my-database - (create-alist-database "mydata.db")) - (define telephone-table-desc - ((my-database 'create-table) 'telephone-table-desc)) - - - Function: close-database - Causes the relational database to be written to its associated - file (if any). If the write is successful, subsequent operations - to this database will signal an error. If the operations completed - successfully, `#t' is returned. Otherwise, `#f' is returned. - - - Function: write-database filename - Causes the relational database to be written to FILENAME. If the - write is successful, also causes the database to henceforth be - associated with FILENAME. Calling the `close-database' (and - possibly other) method on this database will cause FILENAME to be - written to. If FILENAME is `#f' this database will be changed to - a temporary, non-disk based database if such can be supported by - the underlying base table implelentation. If the operations - completed successfully, `#t' is returned. Otherwise, `#f' is - returned. + - Function: mdbm:report + Prints a table of open database files. The columns are the + base-table type, number of opens, `!' for mutable, the filename, + and the lock certificate (if locked). - - Function: sync-database - Causes any pending updates to the database file to be written out. - If the operations completed successfully, `#t' is returned. - Otherwise, `#f' is returned. + (mdbm:report) + -| + alist-table 003 /usr/local/lib/slib/clrnamdb.scm + alist-table 001 ! sdram.db jaffer@aubrey.jaffer.3166:1038628199 - - Function: table-exists? table-name - Returns `#t' if TABLE-NAME exists in the system catalog, otherwise - returns `#f'. +Opening Tables | +.............. | + | + - Function: open-table rdb table-name | + RDB must be a relational database and TABLE-NAME a symbol. | + | + `open-table' returns a "methods" procedure for an existing | + relational table in RDB if it exists and can be opened for | + reading, otherwise returns `#f'. | + | + - Procedure: open-table! rdb table-name | + RDB must be a relational database and TABLE-NAME a symbol. | + | + `open-table!' returns a "methods" procedure for an existing | + relational table in RDB if it exists and can be opened in mutable | + mode, otherwise returns `#f'. | + | +Defining Tables +............... + + - Function: define-domains rdb row5 ... | + Adds the domain rows ROW5 ... to the `*domains-data*' table in | + RDB. The format of the row is given in *Note Catalog + Representation::. | + | + (define-domains rdb '(permittivity #f complex? c64 #f)) | + | + - Function: add-domain rdb row5 | + Use `define-domains' instead. | + | + - Function: define-tables rdb spec-0 ... + Adds tables as specified in SPEC-0 ... to the open + relational-database RDB. Each SPEC has the form: - - Function: open-table table-name mutable? - Returns a "methods" procedure for an existing relational table in - this database if it exists and can be opened in the mode indicated - by MUTABLE?, otherwise returns `#f'. + (<name> <descriptor-name> <descriptor-name> <rows>) + or + (<name> <primary-key-fields> <other-fields> <rows>) -These methods will be present only in databases which are MUTABLE?. + where <name> is the table name, <descriptor-name> is the symbol + name of a descriptor table, <primary-key-fields> and + <other-fields> describe the primary keys and other fields + respectively, and <rows> is a list of data rows to be added to the + table. - - Function: delete-table table-name - Removes and returns the TABLE-NAME row from the system catalog if - the table or view associated with TABLE-NAME gets removed from the - database, and `#f' otherwise. + <primary-key-fields> and <other-fields> are lists of field + descriptors of the form: - - Function: create-table table-desc-name - Returns a methods procedure for a new (open) relational table for - describing the columns of a new base table in this database, - otherwise returns `#f'. For the fields and layout of descriptor - tables, *Note Catalog Representation::. + (<column-name> <domain>) + or + (<column-name> <domain> <column-integrity-rule>) - - Function: create-table table-name table-desc-name - Returns a methods procedure for a new (open) relational table with - columns as described by TABLE-DESC-NAME, otherwise returns `#f'. + where <column-name> is the column name, <domain> is the domain of + the column, and <column-integrity-rule> is an expression whose + value is a procedure of one argument (which returns `#f' to signal + an error). - - Function: create-view ?? - - Function: project-table ?? - - Function: restrict-table ?? - - Function: cart-prod-tables ?? - Not yet implemented. + If <domain> is not a defined domain name and it matches the name of + this table or an already defined (in one of SPEC-0 ...) single key + field table, a foreign-key domain will be created for it. | - -File: slib.info, Node: Table Operations, Next: Catalog Representation, Prev: Relational Database Operations, Up: Relational Database +Listing Tables +.............. -Table Operations ----------------- + - Function: list-table-definition rdb table-name + If symbol TABLE-NAME exists in the open relational-database RDB, + then returns a list of the table-name, its primary key names and + domains, its other key names and domains, and the table's records + (as lists). Otherwise, returns #f. + + The list returned by `list-table-definition', when passed as an + argument to `define-tables', will recreate the table. + + +File: slib.info, Node: Table Operations, Next: Database Interpolation, Prev: Using Databases, Up: Relational Database + | +Table Operations | +---------------- | These are the descriptions of the methods available from an open -relational table. A method is retrieved from a table by calling the -table with the symbol name of the operation. For example: +relational table. A method is retrieved from a table by calling the | +table with the symbol name of the operation. For example: | + + ((plat 'get 'processor) 'djgpp) => i386 | + +Some operations described below require primary key arguments. Primary | +keys arguments are denoted KEY1 KEY2 .... It is an error to call an | +operation for a table which takes primary key arguments with the wrong | +number of primary keys for that table. | + + - Operation on relational-table: get column-name | + Returns a procedure of arguments KEY1 KEY2 ... which returns the | + value for the COLUMN-NAME column of the row associated with | + primary keys KEY1, KEY2 ... if that row exists in the table, or | + `#f' otherwise. | + + ((plat 'get 'processor) 'djgpp) => i386 | + ((plat 'get 'processor) 'be-os) => #f | + +* Menu: | + +* Single Row Operations:: | +* Match-Keys:: | +* Multi-Row Operations:: | +* Indexed Sequential Access Methods:: | +* Sequential Index Operations:: | +* Table Administration:: | + + +File: slib.info, Node: Single Row Operations, Next: Match-Keys, Prev: Table Operations, Up: Table Operations + | +Single Row Operations | +..................... | + +The term "row" used below refers to a Scheme list of values (one for | +each column) in the order specified in the descriptor (table) for this | +table. Missing values appear as `#f'. Primary keys must not be | +missing. | + | + - Operation on relational-table: row:insert | + Adds the row ROW to this table. If a row for the primary key(s) | + specified by ROW already exists in this table an error is | + signaled. The value returned is unspecified. | (define telephone-table-desc - ((my-database 'create-table) 'telephone-table-desc)) - (require 'common-list-functions) + ((my-database 'create-table) 'telephone-table-desc)) | (define ndrp (telephone-table-desc 'row:insert)) (ndrp '(1 #t name #f string)) (ndrp '(2 #f telephone @@ -6448,38 +8483,70 @@ table with the symbol name of the operation. For example: (string->list d)))) string)) -Some operations described below require primary key arguments. Primary -keys arguments are denoted KEY1 KEY2 .... It is an error to call an -operation for a table which takes primary key arguments with the wrong -number of primary keys for that table. - -The term "row" used below refers to a Scheme list of values (one for -each column) in the order specified in the descriptor (table) for this -table. Missing values appear as `#f'. Primary keys must not be -missing. + - Operation on relational-table: row:update | + Returns a procedure of one argument, ROW, which adds the row, ROW, | + to this table. If a row for the primary key(s) specified by ROW | + already exists in this table, it will be overwritten. The value | + returned is unspecified. | - - Function: get column-name + - Operation on relational-table: row:retrieve | Returns a procedure of arguments KEY1 KEY2 ... which returns the - value for the COLUMN-NAME column of the row associated with - primary keys KEY1, KEY2 ... if that row exists in the table, or + row associated with primary keys KEY1, KEY2 ... if it exists, or | `#f' otherwise. - ((plat 'get 'processor) 'djgpp) => i386 - ((plat 'get 'processor) 'be-os) => #f + ((plat 'row:retrieve) 'linux) => (linux i386 linux gcc) | + ((plat 'row:retrieve) 'multics) => #f | - - Function: get* column-name + - Operation on relational-table: row:remove | + Returns a procedure of arguments KEY1 KEY2 ... which removes and | + returns the row associated with primary keys KEY1, KEY2 ... if it | + exists, or `#f' otherwise. | + | + - Operation on relational-table: row:delete | + Returns a procedure of arguments KEY1 KEY2 ... which deletes the | + row associated with primary keys KEY1, KEY2 ... if it exists. The | + value returned is unspecified. | + | + +File: slib.info, Node: Match-Keys, Next: Multi-Row Operations, Prev: Single Row Operations, Up: Table Operations + | +Match-Keys | +.......... | + | +The (optional) MATCH-KEY1 ... arguments are used to restrict actions of | +a whole-table operation to a subset of that table. Those procedures | +(returned by methods) which accept match-key arguments will accept any | +number of match-key arguments between zero and the number of primary | +keys in the table. Any unspecified MATCH-KEY arguments default to `#f'. | + | +The MATCH-KEY1 ... restrict the actions of the table command to those | +records whose primary keys each satisfy the corresponding MATCH-KEY | +argument. The arguments and their actions are: | + | + `#f' | + The false value matches any key in the corresponding position. | + | + an object of type procedure | + This procedure must take a single argument, the key in the | + corresponding position. Any key for which the procedure | + returns a non-false value is a match; Any key for which the | + procedure returns a `#f' is not. | + | + other values | + Any other value matches only those keys `equal?' to it. | + | + - Operation on relational-table: get* column-name | Returns a procedure of optional arguments MATCH-KEY1 ... which returns a list of the values for the specified column for all rows in this table. The optional MATCH-KEY1 ... arguments restrict - actions to a subset of the table. See the match-key description - below for details. + actions to a subset of the table. | ((plat 'get* 'processor)) => - (i386 8086 i386 8086 i386 i386 8086 m68000 + (i386 i8086 i386 i8086 i386 i386 i8086 m68000 | m68000 m68000 m68000 m68000 powerpc) ((plat 'get* 'processor) #f) => - (i386 8086 i386 8086 i386 i386 8086 m68000 + (i386 i8086 i386 i8086 i386 i386 i8086 m68000 | m68000 m68000 m68000 m68000 powerpc) (define (a-key? key) @@ -6492,19 +8559,17 @@ missing. (atari-st-turbo-c atari-st-gcc amiga-sas/c-5.10 amiga-aztec amiga-dice-c aix) - - Function: row:retrieve - Returns a procedure of arguments KEY1 KEY2 ... which returns the - row associated with primary keys KEY1, KEY2 ... if it exists, or - `#f' otherwise. - - ((plat 'row:retrieve) 'linux) => (linux i386 linux gcc) - ((plat 'row:retrieve) 'multics) => #f + +File: slib.info, Node: Multi-Row Operations, Next: Indexed Sequential Access Methods, Prev: Match-Keys, Up: Table Operations + | +Multi-Row Operations | +.................... | - - Function: row:retrieve* - Returns a procedure of optional arguments MATCH-KEY1 ... which + - Operation on relational-table: row:retrieve* | + Returns a procedure of optional arguments MATCH-KEY1 ... which returns a list of all rows in this table. The optional MATCH-KEY1 - ... arguments restrict actions to a subset of the table. See the - match-key description below for details. + ... arguments restrict actions to a subset of the table. For | + details see *Note Match-Keys::. | ((plat 'row:retrieve*) a-key?) => ((atari-st-turbo-c m68000 atari turbo-c) @@ -6514,278 +8579,358 @@ missing. (amiga-dice-c m68000 amiga dice-c) (aix powerpc aix -)) - - Function: row:remove - Returns a procedure of arguments KEY1 KEY2 ... which removes and - returns the row associated with primary keys KEY1, KEY2 ... if it - exists, or `#f' otherwise. - - - Function: row:remove* + - Operation on relational-table: row:remove* | Returns a procedure of optional arguments MATCH-KEY1 ... which removes and returns a list of all rows in this table. The optional - MATCH-KEY1 ... arguments restrict actions to a subset of the - table. See the match-key description below for details. + MATCH-KEY1 ... arguments restrict actions to a subset of the table. | - - Function: row:delete - Returns a procedure of arguments KEY1 KEY2 ... which deletes the - row associated with primary keys KEY1, KEY2 ... if it exists. The - value returned is unspecified. - - - Function: row:delete* - Returns a procedure of optional arguments MATCH-KEY1 ... which + - Operation on relational-table: row:delete* | + Returns a procedure of optional arguments MATCH-KEY1 ... which Deletes all rows from this table. The optional MATCH-KEY1 ... - arguments restrict deletions to a subset of the table. See the - match-key description below for details. The value returned is - unspecified. The descriptor table and catalog entry for this - table are not affected. - - - Function: row:update - Returns a procedure of one argument, ROW, which adds the row, ROW, - to this table. If a row for the primary key(s) specified by ROW - already exists in this table, it will be overwritten. The value - returned is unspecified. - - - Function: row:update* + arguments restrict deletions to a subset of the table. The value | + returned is unspecified. The descriptor table and catalog entry | + for this table are not affected. | + + - Operation on relational-table: for-each-row | + Returns a procedure of arguments PROC MATCH-KEY1 ... which calls | + PROC with each ROW in this table. The optional MATCH-KEY1 ... | + arguments restrict actions to a subset of the table. For details | + see *Note Match-Keys::. | + +Note that `row:insert*' and `row:update*' do _not_ use match-keys. | + | + - Operation on relational-table: row:insert* | Returns a procedure of one argument, ROWS, which adds each row in the list of rows, ROWS, to this table. If a row for the primary key specified by an element of ROWS already exists in this table, - it will be overwritten. The value returned is unspecified. + an error is signaled. The value returned is unspecified. | - - Function: row:insert - Adds the row ROW to this table. If a row for the primary key(s) - specified by ROW already exists in this table an error is - signaled. The value returned is unspecified. - - - Function: row:insert* + - Operation on relational-table: row:update* | Returns a procedure of one argument, ROWS, which adds each row in the list of rows, ROWS, to this table. If a row for the primary key specified by an element of ROWS already exists in this table, - an error is signaled. The value returned is unspecified. + it will be overwritten. The value returned is unspecified. | - - Function: for-each-row + +File: slib.info, Node: Indexed Sequential Access Methods, Next: Sequential Index Operations, Prev: Multi-Row Operations, Up: Table Operations + | +Indexed Sequential Access Methods | +................................. | + | +"Indexed Sequential Access Methods" are a way of arranging database | +information so that records can be accessed both by key and by key | +sequence (ordering). "ISAM" is not part of Codd's relational model. | +Hardcore relational programmers might use some least-upper-bound join | +for every row to get them into an order. | + | +Associative memory in B-Trees is an example of a database | +implementation which can support a native key ordering. SLIB's | +`alist-table' implementation uses `sort' to implement | +`for-each-row-in-order', but does not support `isam-next' and | +`isam-prev'. | + | +The multi-primary-key ordering employed by these operations is the | +lexicographic collation of those primary-key fields in their given | +order. For example: | + | + (12 a 34) < (12 a 36) < (12 b 1) < (13 a 0) | + | + +File: slib.info, Node: Sequential Index Operations, Next: Table Administration, Prev: Indexed Sequential Access Methods, Up: Table Operations + | +Sequential Index Operations | +........................... | + | +The following procedures are individually optional depending on the | +base-table implememtation. If an operation is _not_ supported, then | +calling the table with that operation symbol will return false. | + | + - Operation on relational-table: for-each-row-in-order | Returns a procedure of arguments PROC MATCH-KEY1 ... which calls PROC with each ROW in this table in the (implementation-dependent) - natural ordering for rows. The optional MATCH-KEY1 ... arguments - restrict actions to a subset of the table. See the match-key - description below for details. - - _Real_ relational programmers would use some least-upper-bound join - for every row to get them in order; But we don't have joins yet. - -The (optional) MATCH-KEY1 ... arguments are used to restrict actions of -a whole-table operation to a subset of that table. Those procedures -(returned by methods) which accept match-key arguments will accept any -number of match-key arguments between zero and the number of primary -keys in the table. Any unspecified MATCH-KEY arguments default to `#f'. - -The MATCH-KEY1 ... restrict the actions of the table command to those -records whose primary keys each satisfy the corresponding MATCH-KEY -argument. The arguments and their actions are: - - `#f' - The false value matches any key in the corresponding position. - - an object of type procedure - This procedure must take a single argument, the key in the - corresponding position. Any key for which the procedure - returns a non-false value is a match; Any key for which the - procedure returns a `#f' is not. - - other values - Any other value matches only those keys `equal?' to it. - - - Function: close-table - Subsequent operations to this table will signal an error. - - - Constant: column-names - - Constant: column-foreigns - - Constant: column-domains - - Constant: column-types + natural, repeatable ordering for rows. The optional MATCH-KEY1 | + ... arguments restrict actions to a subset of the table. For | + details see *Note Match-Keys::. | + + - Operation on relational-table: isam-next | + Returns a procedure of arguments KEY1 KEY2 ... which returns the | + key-list identifying the lowest record higher than KEY1 KEY2 ... | + which is stored in the relational-table; or false if no higher | + record is present. | + + - Operation on relational-table: isam-next column-name | + The symbol COLUMN-NAME names a key field. In the list returned by | + `isam-next', that field, or a field to its left, will be changed. | + This allows one to skip over less significant key fields. | + + - Operation on relational-table: isam-prev | + Returns a procedure of arguments KEY1 KEY2 ... which returns the | + key-list identifying the highest record less than KEY1 KEY2 ... | + which is stored in the relational-table; or false if no lower | + record is present. | + + - Operation on relational-table: isam-prev index | + The symbol COLUMN-NAME names a key field. In the list returned by | + `isam-next', that field, or a field to its left, will be changed. | + This allows one to skip over less significant key fields. | + + For example, if a table has key fields: | + (col1 col2) | + (9 5) | + (9 6) | + (9 7) | + (9 8) | + (12 5) | + (12 6) | + (12 7) | + + Then: | + ((table 'isam-next) '(9 5)) => (9 6) | + ((table 'isam-next 'col2) '(9 5)) => (9 6) | + ((table 'isam-next 'col1) '(9 5)) => (12 5) | + ((table 'isam-prev) '(12 7)) => (12 6) | + ((table 'isam-prev 'col2) '(12 7)) => (12 6) | + ((table 'isam-prev 'col1) '(12 7)) => (9 8) | + + +File: slib.info, Node: Table Administration, Prev: Sequential Index Operations, Up: Table Operations + | +Table Administration | +.................... | + | + - Operation on relational-table: column-names | + - Operation on relational-table: column-foreigns | + - Operation on relational-table: column-domains | + - Operation on relational-table: column-types | Return a list of the column names, foreign-key table names, domain names, or type names respectively for this table. These 4 methods are different from the others in that the list is returned, rather than a procedure to obtain the list. - - Constant: primary-limit + - Operation on relational-table: primary-limit | Returns the number of primary keys fields in the relations in this table. + - Operation on relational-table: close-table | + Subsequent operations to this table will signal an error. | + | -File: slib.info, Node: Catalog Representation, Next: Unresolved Issues, Prev: Table Operations, Up: Relational Database - -Catalog Representation +File: slib.info, Node: Database Interpolation, Next: Embedded Commands, Prev: Table Operations, Up: Relational Database + | +Database Interpolation | ---------------------- -Each database (in an implementation) has a "system catalog" which -describes all the user accessible tables in that database (including -itself). - -The system catalog base table has the following fields. `PRI' -indicates a primary key for that table. - - PRI table-name - column-limit the highest column number - coltab-name descriptor table name - bastab-id data base table identifier - user-integrity-rule - view-procedure A scheme thunk which, when called, - produces a handle for the view. coltab - and bastab are specified if and only if - view-procedure is not. - -Descriptors for base tables (not views) are tables (pointed to by -system catalog). Descriptor (base) tables have the fields: - - PRI column-number sequential integers from 1 - primary-key? boolean TRUE for primary key components - column-name - column-integrity-rule - domain-name - -A "primary key" is any column marked as `primary-key?' in the -corresponding descriptor table. All the `primary-key?' columns must -have lower column numbers than any non-`primary-key?' columns. Every -table must have at least one primary key. Primary keys must be -sufficient to distinguish all rows from each other in the table. All of -the system defined tables have a single primary key. - -This package currently supports tables having from 1 to 4 primary keys -if there are non-primary columns, and any (natural) number if _all_ -columns are primary keys. If you need more than 4 primary keys, I would -like to hear what you are doing! - -A "domain" is a category describing the allowable values to occur in a -column. It is described by a (base) table with the fields: - - PRI domain-name - foreign-table - domain-integrity-rule - type-id - type-param - -The "type-id" field value is a symbol. This symbol may be used by the -underlying base table implementation in storing that field. - -If the `foreign-table' field is non-`#f' then that field names a table -from the catalog. The values for that domain must match a primary key -of the table referenced by the TYPE-PARAM (or `#f', if allowed). This -package currently does not support composite foreign-keys. - -The types for which support is planned are: - atom - symbol - string [<length>] - number [<base>] - money <currency> - date-time - boolean - - foreign-key <table-name> - expression - virtual <expression> +`(require 'database-interpolate)' | - -File: slib.info, Node: Unresolved Issues, Next: Database Utilities, Prev: Catalog Representation, Up: Relational Database +Indexed sequential access methods allow finding the keys (having | +associations) closest to a given value. This facilitates the | +interpolation of associations between those in the table. | -Unresolved Issues ------------------ + - Function: interpolate-from-table table column | + TABLE should be a relational table with one numeric primary key | + field which supports the `isam-prev' and `isam-next' operations. | + COLUMN should be a symbol or exact positive integer designating a | + numerically valued column of TABLE. | - Although `rdms.scm' is not large, I found it very difficult to write -(six rewrites). I am not aware of any other examples of a generalized -relational system (although there is little new in CS). I left out -several aspects of the Relational model in order to simplify the job. -The major features lacking (which might be addressed portably) are -views, transaction boundaries, and protection. - - Protection needs a model for specifying priveledges. Given how -operations are accessed from handles it should not be difficult to -restrict table accesses to those allowed for that user. - - The system catalog has a field called `view-procedure'. This should -allow a purely functional implementation of views. This will work but -is unsatisfying for views resulting from a "select"ion (subset of -rows); for whole table operations it will not be possible to reduce the -number of keys scanned over when the selection is specified only by an -opaque procedure. - - Transaction boundaries present the most intriguing area. Transaction -boundaries are actually a feature of the "Comprehensive Language" of the -Relational database and not of the database. Scheme would seem to -provide the opportunity for an extremely clean semantics for transaction -boundaries since the builtin procedures with side effects are small in -number and easily identified. - - These side-effect builtin procedures might all be portably redefined -to versions which properly handled transactions. Compiled library -routines would need to be recompiled as well. Many system extensions -(delete-file, system, etc.) would also need to be redefined. - -There are 2 scope issues that must be resolved for multiprocess -transaction boundaries: - -Process scope - The actions captured by a transaction should be only for the - process which invoked the start of transaction. Although standard - Scheme does not provide process primitives as such, `dynamic-wind' - would provide a workable hook into process switching for many - implementations. - -Shared utilities with state - Some shared utilities have state which should _not_ be part of a - transaction. An example would be calling a pseudo-random number - generator. If the success of a transaction depended on the - pseudo-random number and failed, the state of the generator would - be set back. Subsequent calls would keep returning the same - number and keep failing. - - Pseudo-random number generators are not reentrant; thus they would - require locks in order to operate properly in a multiprocess - environment. Are all examples of utilities whose state should not - be part of transactions also non-reentrant? If so, perhaps - suspending transaction capture for the duration of locks would - solve this problem. - - -File: slib.info, Node: Database Utilities, Next: Database Reports, Prev: Unresolved Issues, Up: Relational Database - -Database Utilities ------------------- + `interpolate-from-table' calculates and returns a value | + proportionally intermediate between its values in the next and | + previous key records contained in TABLE. For keys larger than all | + the stored keys the value associated with the largest stored key | + is used. For keys smaller than all the stored keys the value | + associated with the smallest stored key is used. | + + +File: slib.info, Node: Embedded Commands, Next: Database Macros, Prev: Database Interpolation, Up: Relational Database + | +Embedded Commands +----------------- - `(require 'database-utilities)' +`(require 'database-commands)' This enhancement wraps a utility layer on `relational-database' which provides: - * Automatic loading of the appropriate base-table package when - opening a database. * Automatic execution of initialization commands stored in database. * Transparent execution of database commands stored in `*commands*' table in database. -Also included are utilities which provide: - * Data definition from Scheme lists and + When an enhanced relational-database is called with a symbol which +matches a NAME in the `*commands*' table, the associated procedure +expression is evaluated and applied to the enhanced +relational-database. A procedure should then be returned which the user +can invoke on (optional) arguments. + + The command `*initialize*' is special. If present in the +`*commands*' table, `open-database' or `open-database!' will return the +value of the `*initialize*' command. Notice that arbitrary code can be +run when the `*initialize*' procedure is automatically applied to the +enhanced relational-database. - * Report generation + Note also that if you wish to shadow or hide from the user +relational-database methods described in *Note Database Operations::, +this can be done by a dispatch in the closure returned by the +`*initialize*' expression rather than by entries in the `*commands*' +table if it is desired that the underlying methods remain accessible to +code in the `*commands*' table. -for any SLIB relational database. +* Menu: - - Function: create-database filename base-table-type - Returns an open, nearly empty enhanced (with `*commands*' table) - relational database (with base-table type BASE-TABLE-TYPE) - associated with FILENAME. +* Database Extension:: +* Command Intrinsics:: +* Define-tables Example:: +* The *commands* Table:: +* Command Service:: +* Command Example:: + + +File: slib.info, Node: Database Extension, Next: Command Intrinsics, Prev: Embedded Commands, Up: Embedded Commands + +Database Extension +.................. - - Function: open-database filename - - Function: open-database filename base-table-type - Returns an open enchanced relational database associated with + - Function: wrap-command-interface rdb + Returns relational database RDB wrapped with additional commands + defined in its *commands* table. + + - Function: add-command-tables rdb + The relational database RDB must be mutable. ADD-COMMAND-TABLES + adds a *command* table to RDB; then returns + `(wrap-command-interface RDB)'. + + - Function: define-*commands* rdb spec-0 ... + Adds commands to the `*commands*' table as specified in SPEC-0 ... + to the open relational-database RDB. Each SPEC has the form: + + ((<name> <rdb>) "comment" <expression1> <expression2> ...) + or + ((<name> <rdb>) <expression1> <expression2> ...) + + where <name> is the command name, <rdb> is a formal passed the + calling relational database, "comment" describes the command, and + <expression1>, <expression1>, ... are the body of the procedure. + + `define-*commands*' adds to the `*commands*' table a command + <name>: + + (lambda (<name> <rdb>) <expression1> <expression2> ...) + + + - Function: open-command-database filename + - Function: open-command-database filename base-table-type + Returns an open enhanced relational database associated with FILENAME. The database will be opened with base-table type BASE-TABLE-TYPE) if supplied. If BASE-TABLE-TYPE is not supplied, - `open-database' will attempt to deduce the correct + `open-command-database' will attempt to deduce the correct base-table-type. If the database can not be opened or if it lacks the `*commands*' table, `#f' is returned. - - Function: open-database! filename - - Function: open-database! filename base-table-type - Returns _mutable_ open enchanced relational database ... + - Function: open-command-database! filename + - Function: open-command-database! filename base-table-type + Returns _mutable_ open enhanced relational database ... + + - Function: open-command-database database + Returns DATABASE if it is an immutable relational database; #f + otherwise. + + - Function: open-command-database! database + Returns DATABASE if it is a mutable relational database; #f + otherwise. + + +File: slib.info, Node: Command Intrinsics, Next: Define-tables Example, Prev: Database Extension, Up: Embedded Commands + +Command Intrinsics +.................. + +Some commands are defined in all extended relational-databases. The are +called just like *Note Database Operations::. + + - Operation on relational-database: add-domain domain-row | + Adds DOMAIN-ROW to the "domains" table if there is no row in the + domains table associated with key `(car DOMAIN-ROW)' and returns + `#t'. Otherwise returns `#f'. + + For the fields and layout of the domain table, *Note Catalog + Representation::. Currently, these fields are + * domain-name + + * foreign-table + + * domain-integrity-rule + + * type-id + + * type-param + + The following example adds 3 domains to the `build' database. + `Optstring' is either a string or `#f'. `filename' is a string + and `build-whats' is a symbol. + + (for-each (build 'add-domain) + '((optstring #f + (lambda (x) (or (not x) (string? x))) + string + #f) + (filename #f #f string #f) + (build-whats #f #f symbol #f))) + + - Operation on relational-database: delete-domain domain-name | + Removes and returns the DOMAIN-NAME row from the "domains" table. + + - Operation on relational-database: domain-checker domain | + Returns a procedure to check an argument for conformance to domain + DOMAIN. + + +File: slib.info, Node: Define-tables Example, Next: The *commands* Table, Prev: Command Intrinsics, Up: Embedded Commands + +Define-tables Example +..................... + +The following example shows a new database with the name of `foo.db' +being created with tables describing processor families and +processor/os/compiler combinations. The database is then solidified; +saved and changed to immutable. + + (require 'databases) + (define my-rdb (create-database "foo.db" 'alist-table)) + (define-tables my-rdb + '(processor-family + ((family atom)) + ((also-ran processor-family)) + ((m68000 #f) + (m68030 m68000) + (i386 i8086) | + (i8086 #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 i8086 ms-dos borland-c) | + (djgpp i386 ms-dos gcc) + (linux i386 linux gcc) + (microsoft-c i8086 ms-dos microsoft-c) | + (os/2-emx i386 os/2 gcc) + (turbo-c-2 i8086 ms-dos turbo-c) | + (watcom-9.0 i386 ms-dos watcom)))) + + (solidify-database my-rdb) + + +File: slib.info, Node: The *commands* Table, Next: Command Service, Prev: Define-tables Example, Up: Embedded Commands + +The *commands* Table +.................... The table `*commands*' in an "enhanced" relational-database has the fields (with domains): @@ -6802,7 +8947,7 @@ The intent of this table is to be of a form such that different user-interfaces (for instance, pull-down menus or plain-text queries) can operate from the same table. A `parameter-list' table has the following fields: - PRI index uint + PRI index ordinal | name symbol arity parameter-arity domain domain @@ -6843,27 +8988,11 @@ of the default value or values as appropriate. Note that since the needed for this column, "sticky" defaults can be implemented using shared state with the domain-integrity-rule. -Invoking Commands -................. - - When an enhanced relational-database is called with a symbol which -matches a NAME in the `*commands*' table, the associated procedure -expression is evaluated and applied to the enhanced -relational-database. A procedure should then be returned which the user -can invoke on (optional) arguments. - - The command `*initialize*' is special. If present in the -`*commands*' table, `open-database' or `open-database!' will return the -value of the `*initialize*' command. Notice that arbitrary code can be -run when the `*initialize*' procedure is automatically applied to the -enhanced relational-database. + +File: slib.info, Node: Command Service, Next: Command Example, Prev: The *commands* Table, Up: Embedded Commands - Note also that if you wish to shadow or hide from the user -relational-database methods described in *Note Relational Database -Operations::, this can be done by a dispatch in the closure returned by -the `*initialize*' expression rather than by entries in the -`*commands*' table if it is desired that the underlying methods remain -accessible to code in the `*commands*' table. +Command Service +............... - Function: make-command-server rdb table-name Returns a procedure of 2 arguments, a (symbol) command and a @@ -6910,16 +9039,26 @@ accessible to code in the `*commands*' table. A list of lists of `(alias parameter-name)'. There can be more than one alias per PARAMETER-NAME. - For information about parameters, *Note Parameter lists::. Here is an -example of setting up a command with arguments and parsing those -arguments from a `getopt' style argument list (*note Getopt::). +For information about parameters, *Note Parameter lists::. - (require 'database-utilities) - (require 'fluid-let) + +File: slib.info, Node: Command Example, Prev: Command Service, Up: Embedded Commands + +Command Example +............... + +Here is an example of setting up a command with arguments and parsing +those arguments from a `getopt' style argument list (*note Getopt::). + + (require 'database-commands) + (require 'databases) + (require 'getopt-parameters) (require 'parameters) (require 'getopt) + (require 'fluid-let) + (require 'printf) - (define my-rdb (create-database #f 'alist-table)) + (define my-rdb (add-command-tables (create-database #f 'alist-table))) (define-tables my-rdb '(foo-params @@ -6931,13 +9070,13 @@ arguments from a `getopt' style argument list (*note Getopt::). (lambda (pl) '()) #f "zero or more symbols") (3 nary1-symbols nary1 symbol (lambda (pl) '(symb)) #f "one or more symbols") - (4 optional-number optional uint + (4 optional-number optional ordinal | (lambda (pl) '()) #f "zero or one number") (5 flag boolean boolean (lambda (pl) '(#f)) #f "a boolean flag"))) '(foo-pnames ((name string)) - ((parameter-index uint)) + ((parameter-index ordinal)) | (("s" 1) ("single-string" 1) ("n" 2) @@ -6960,15 +9099,13 @@ arguments from a `getopt' style argument list (*note Getopt::). (lambda (rdb) (lambda args (print args))) "test command arguments")))) - (define (dbutil:serve-command-line rdb command-table - command argc argv) - (set! argv (if (vector? argv) (vector->list argv) argv)) + (define (dbutil:serve-command-line rdb command-table command argv) + (set! *argv* (if (vector? argv) (vector->list argv) argv)) ((make-command-server rdb command-table) command (lambda (comname comval options positions arities types defaulters dirs aliases) - (apply comval (getopt->arglist - argc argv options positions + (apply comval (getopt->arglist options positions arities types defaulters dirs aliases))))) (define (cmd . opts) @@ -7016,56 +9153,53 @@ arguments from a `getopt' style argument list (*note Getopt::). ERROR: getopt->parameter-list "unrecognized option" "-?" - Some commands are defined in all extended relational-databases. The -are called just like *Note Relational Database Operations::. + +File: slib.info, Node: Database Macros, Next: Database Browser, Prev: Embedded Commands, Up: Relational Database + | +Database Macros +--------------- - - Function: add-domain domain-row - Adds DOMAIN-ROW to the "domains" table if there is no row in the - domains table associated with key `(car DOMAIN-ROW)' and returns - `#t'. Otherwise returns `#f'. +`(require 'within-database)' - For the fields and layout of the domain table, *Note Catalog - Representation::. Currently, these fields are - * domain-name + The object-oriented programming interface to SLIB relational databases +has failed to support clear, understandable, and modular code-writing +for database applications. - * foreign-table + This seems to be a failure of the object-oriented paradigm where the +type of an object is not manifest (or even traceable) in source code. - * domain-integrity-rule + `within-database', along with the `databases' package, reorganizes +high-level database functions toward a more declarative style. Using +this package, one can tag database table and command declarations for +emacs: - * type-id + etags -lscheme -r'/ *(define-\(command\|table\) (\([^; \t]+\)/\2/' \ + source1.scm ... - * type-param +* Menu: - The following example adds 3 domains to the `build' database. - `Optstring' is either a string or `#f'. `filename' is a string - and `build-whats' is a symbol. +* Within-database Example:: - (for-each (build 'add-domain) - '((optstring #f - (lambda (x) (or (not x) (string? x))) - string - #f) - (filename #f #f string #f) - (build-whats #f #f symbol #f))) + - Function: within-database database statement-1 ... + `within-database' creates a lexical scope in which the commands + `define-table' and `define-command' create tables and + `*commands*'-table entries respectively in open relational + database DATABASE. - - Function: delete-domain domain-name - Removes and returns the DOMAIN-NAME row from the "domains" table. + `within-database' Returns DATABASE. - - Function: domain-checker domain - Returns a procedure to check an argument for conformance to domain - DOMAIN. - -Defining Tables -............... + - Syntax: define-command (<name> <rdb>) "comment" <expression1> + <expression2> ... + - Syntax: define-command (<name> <rdb>) <expression1> <expression2> ... + Adds to the `*commands*' table a command <name>: - - Procedure: define-tables rdb spec-0 ... - Adds tables as specified in SPEC-0 ... to the open - relational-database RDB. Each SPEC has the form: + (lambda (<name> <rdb>) <expression1> <expression2> ...) - (<name> <descriptor-name> <descriptor-name> <rows>) - or - (<name> <primary-key-fields> <other-fields> <rows>) + - Syntax: define-table <name> <descriptor-name> <descriptor-name> + <rows> + - Syntax: define-table <name> <primary-key-fields> <other-fields> + <rows> where <name> is the table name, <descriptor-name> is the symbol name of a descriptor table, <primary-key-fields> and <other-fields> describe the primary keys and other fields @@ -7086,203 +9220,676 @@ Defining Tables If <domain> is not a defined domain name and it matches the name of this table or an already defined (in one of SPEC-0 ...) single key - field table, a foriegn-key domain will be created for it. + field table, a foreign-key domain will be created for it. | -The following example shows a new database with the name of `foo.db' -being created with tables describing processor families and -processor/os/compiler combinations. -The database command `define-tables' is defined to call `define-tables' -with its arguments. The database is also configured to print `Welcome' -when the database is opened. The database is then closed and reopened. + +File: slib.info, Node: Within-database Example, Prev: Database Macros, Up: Database Macros - (require '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")))) +Within-database Example +....................... + +Here is an example of `within-database' macros: + + (require 'within-database) - ((my-rdb 'define-tables) - '(processor-family - ((family atom)) - ((also-ran processor-family)) - ((m68000 #f) - (m68030 m68000) - (i386 8086) - (8086 #f) - (powerpc #f))) + (define my-rdb + (add-command-tables + (create-database "foo.db" 'alist-table))) - '(platform - ((name symbol)) - ((processor processor-family) - (os symbol) - (compiler symbol)) - ((aix powerpc aix -) - (amiga-dice-c m68000 amiga dice-c) + (within-database my-rdb + (define-command (*initialize* rdb) + "Print Welcome" + (display "Welcome") + (newline) + rdb) + (define-command (without-documentation rdb) + (display "without-documentation called") + (newline)) + (define-table (processor-family + ((family atom)) + ((also-ran processor-family))) + (m68000 #f) + (m68030 m68000) + (i386 i8086) | + (i8086 #f) | + (powerpc #f)) + (define-table (platform + ((name symbol)) + ((processor processor-family) + (os symbol) + (compiler symbol))) + (aix powerpc aix -) + ;; ... (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)))) + ;; ... + (watcom-9.0 i386 ms-dos watcom)) + (define-command (get-processor rdb) + "Get processor for given platform." + (((rdb 'open-table) 'platform #f) 'get 'processor))) - ((my-rdb 'close-database)) + (close-database my-rdb) - (set! my-rdb (open-database "foo.db" 'alist-table)) + (set! my-rdb (open-command-database! "foo.db")) -| Welcome - -Listing Tables -.............. - - - Procedure: list-table-definition rdb table-name - If symbol TABLE-NAME exists in the open relational-database RDB, - then returns a list of the table-name, its primary key names and - domains, its other key names and domains, and the table's records - (as lists). Otherwise, returns #f. - - The list returned by `list-table-definition', when passed as an - argument to `define-tables', will recreate the table. + + (my-rdb 'without-documentation) + -| + without-documentation called + + ((my-rdb 'get-processor) 'amiga-sas/c-5.10) + => m68000 + + (close-database my-rdb) -File: slib.info, Node: Database Reports, Next: Database Browser, Prev: Database Utilities, Up: Relational Database - -Database Reports +File: slib.info, Node: Database Browser, Prev: Database Macros, Up: Relational Database + | +Database Browser | ---------------- -Code for generating database reports is in `report.scm'. After writing -it using `format', I discovered that Common-Lisp `format' is not -useable for this application because there is no mechanismm for -truncating fields. `report.scm' needs to be rewritten using `printf'. - - - Procedure: create-report rdb destination report-name table - - Procedure: create-report rdb destination report-name - The symbol REPORT-NAME must be primary key in the table named - `*reports*' in the relational database RDB. DESTINATION is a - port, string, or symbol. If DESTINATION is a: - - port - The table is created as ascii text and written to that port. - - string - The table is created as ascii text and written to the file - named by DESTINATION. - - symbol - DESTINATION is the primary key for a row in the table named - *printers*. - - The report is prepared as follows: - - * `Format' (*note Format::) is called with the `header' field - and the (list of) `column-names' of the table. - - * `Format' is called with the `reporter' field and (on - successive calls) each record in the natural order for the - table. A count is kept of the number of newlines output by - format. When the number of newlines to be output exceeds the - number of lines per page, the set of lines will be broken if - there are more than `minimum-break' left on this page and the - number of lines for this row is larger or equal to twice - `minimum-break'. - - * `Format' is called with the `footer' field and the (list of) - `column-names' of the table. The footer field should not - output a newline. - - * A new page is output. +(require 'database-browse) | - * This entire process repeats until all the rows are output. + - Procedure: browse database | + Prints the names of all the tables in DATABASE and sets browse's | + default to DATABASE. | - Each row in the table *reports* has the fields: + - Procedure: browse | + Prints the names of all the tables in the default database. | -name - The report name. + - Procedure: browse table-name | + For each record of the table named by the symbol TABLE-NAME, | + prints a line composed of all the field values. | -default-table - The table to report on if none is specified. + - Procedure: browse pathname | + Opens the database named by the string PATHNAME, prints the names | + of all its tables, and sets browse's default to the database. | -header, footer - A `format' string. At the beginning and end of each page - respectively, `format' is called with this string and the (list of) - column-names of this table. + - Procedure: browse database table-name | + Sets browse's default to DATABASE and prints the records of the | + table named by the symbol TABLE-NAME. | -reporter - A `format' string. For each row in the table, `format' is called - with this string and the row. - -minimum-break - The minimum number of lines into which the report lines for a row - can be broken. Use `0' if a row's lines should not be broken over - page boundaries. - - Each row in the table *printers* has the fields: - -name - The printer name. - -print-procedure - The procedure to call to actually print. + - Procedure: browse pathname table-name | + Opens the database named by the string PATHNAME and sets browse's | + default to it; `browse' prints the records of the table named by | + the symbol TABLE-NAME. | + | -File: slib.info, Node: Database Browser, Prev: Database Reports, Up: Relational Database +File: slib.info, Node: Relational Infrastructure, Next: Weight-Balanced Trees, Prev: Relational Database, Up: Database Packages + | +Relational Infrastructure | +========================= | -Database Browser ----------------- +* Menu: | - (require 'database-browse) +* Base Table:: | +* Catalog Representation:: | +* Relational Database Objects:: | +* Database Operations:: | - - Procedure: browse database - Prints the names of all the tables in DATABASE and sets browse's - default to DATABASE. + +File: slib.info, Node: Base Table, Next: Catalog Representation, Prev: Relational Infrastructure, Up: Relational Infrastructure + | +Base Table | +---------- | - - Procedure: browse - Prints the names of all the tables in the default database. +A "base-table" is the primitive database layer upon which SLIB | +relational databases are built. At the minimum, it must support the | +types integer, symbol, string, and boolean. The base-table may restrict | +the size of integers, symbols, and strings it supports. | - - Procedure: browse table-name - For each record of the table named by the symbol TABLE-NAME, - prints a line composed of all the field values. + A base table implementation is available as the value of the | +identifier naming it (eg. ALIST-TABLE) after requiring the symbol of | +that name. | - - Procedure: browse pathname - Opens the database named by the string PATHNAME, prints the names - of all its tables, and sets browse's default to the database. + - Feature: alist-table | + `(require 'alist-table)' | - - Procedure: browse database table-name - Sets browse's default to DATABASE and prints the records of the - table named by the symbol TABLE-NAME. + Association-list base tables support all Scheme types and are | + suitable for small databases. In order to be retrieved after | + being written to a file, the data stored should include only | + objects which are readable and writeable in the Scheme | + implementation. | - - Procedure: browse pathname table-name - Opens the database named by the string PATHNAME and sets browse's - default to it; `browse' prints the records of the table named by - the symbol TABLE-NAME. + The "alist-table" base-table implementation is included in the | + SLIB distribution. | + "WB" is a B-tree database package with SCM interfaces. Being | +disk-based, WB databases readily store and access hundreds of megabytes | +of data. WB comes with two base-table embeddings. | + | + - Feature: wb-table | + `(require 'wb-table)' | + | + `wb-table' supports scheme expressions for keys and values whose | + text representations are less than 255 characters in length. | + *Note wb-table: (wb)wb-table. | + | + - Feature: rwb-isam | + `(require 'rwb-isam)' | + | + "rwb-isam" is a sophisticated base-table implementation built on | + WB and SCM which uses binary numerical formats for key and non-key | + fields. It supports IEEE floating-point and fixed-precision | + integer keys with the correct numerical collation order. | + | + This rest of this section documents the interface for a base table | +implementation from which the *Note Relational Database:: package | +constructs a Relational system. It will be of interest primarily to | +those wishing to port or write new base-table implementations. | + | + - Variable: *base-table-implementations* | + To support automatic dispatch for `open-database', each base-table | + module adds an association to *BASE-TABLE-IMPLEMENTATIONS* when | + loaded. This association is the list of the base-table symbol and | + the value returned by `(make-relational-system BASE-TABLE)'. | + | +* Menu: | + | +* The Base:: | +* Base Tables:: | +* Base Field Types:: | +* Composite Keys:: | +* Base Record Operations:: | +* Match Keys:: | +* Aggregate Base Operations:: | +* Base ISAM Operations:: | -File: slib.info, Node: Weight-Balanced Trees, Prev: Relational Database, Up: Database Packages +File: slib.info, Node: The Base, Next: Base Tables, Prev: Base Table, Up: Base Table + | +The Base | +........ | + +All of these functions are accessed through a single procedure by | +calling that procedure with the symbol name of the operation. A | +procedure will be returned if that operation is supported and `#f' | +otherwise. For example: | + + (require 'alist-table) | + (define my-base (alist-table 'make-base)) | + my-base => *a procedure* | + (define foo (alist-table 'foo)) | + foo => #f | + + - Operation on base-table: make-base filename key-dimension | + column-types | + Returns a new, open, low-level database (collection of tables) | + associated with FILENAME. This returned database has an empty | + table associated with CATALOG-ID. The positive integer | + KEY-DIMENSION is the number of keys composed to make a PRIMARY-KEY | + for the catalog table. The list of symbols COLUMN-TYPES describes | + the types of each column for that table. If the database cannot | + be created as specified, `#f' is returned. | + + Calling the `close-base' method on this database and possibly other | + operations will cause FILENAME to be written to. If FILENAME is | + `#f' a temporary, non-disk based database will be created if such | + can be supported by the base table implelentation. | + + - Operation on base-table: open-base filename mutable | + Returns an open low-level database associated with FILENAME. If | + MUTABLE is `#t', this database will have methods capable of | + effecting change to the database. If MUTABLE is `#f', only | + methods for inquiring the database will be available. If the | + database cannot be opened as specified `#f' is returned. | + + Calling the `close-base' (and possibly other) method on a MUTABLE | + database will cause FILENAME to be written to. | + + - Operation on base-table: write-base lldb filename | + Causes the low-level database LLDB to be written to FILENAME. If | + the write is successful, also causes LLDB to henceforth be | + associated with FILENAME. Calling the `close-database' (and | + possibly other) method on LLDB may cause FILENAME to be written | + to. If FILENAME is `#f' this database will be changed to a | + temporary, non-disk based database if such can be supported by the | + underlying base table implelentation. If the operations completed | + successfully, `#t' is returned. Otherwise, `#f' is returned. | + + - Operation on base-table: sync-base lldb | + Causes the file associated with the low-level database LLDB to be | + updated to reflect its current state. If the associated filename | + is `#f', no action is taken and `#f' is returned. If this | + operation completes successfully, `#t' is returned. Otherwise, | + `#f' is returned. | + | + - Operation on base-table: close-base lldb | + Causes the low-level database LLDB to be written to its associated | + file (if any). If the write is successful, subsequent operations | + to LLDB will signal an error. If the operations complete | + successfully, `#t' is returned. Otherwise, `#f' is returned. | + +File: slib.info, Node: Base Tables, Next: Base Field Types, Prev: The Base, Up: Base Table + | +Base Tables | +........... | + | + - Operation on base-table: make-table lldb key-dimension column-types | + Returns the ordinal BASE-ID for a new base table, otherwise | + returns `#f'. The base table can then be opened using | + `(open-table LLDB BASE-ID)'. The positive integer KEY-DIMENSION | + is the number of keys composed to make a PRIMARY-KEY for this | + table. The list of symbols COLUMN-TYPES describes the types of | + each column. | + | + - Operation on base-table: open-table lldb base-id key-dimension | + column-types | + Returns a HANDLE for an existing base table in the low-level | + database LLDB if that table exists and can be opened in the mode | + indicated by MUTABLE, otherwise returns `#f'. | + | + As with `make-table', the positive integer KEY-DIMENSION is the | + number of keys composed to make a PRIMARY-KEY for this table. The | + list of symbols COLUMN-TYPES describes the types of each column. | + | + - Operation on base-table: kill-table lldb base-id key-dimension | + column-types | + Returns `#t' if the base table associated with BASE-ID was removed | + from the low level database LLDB, and `#f' otherwise. | + | + - Operation on base-table: catalog-id | + A constant BASE-ID ordinal suitable for passing as a parameter to | + `open-table'. CATALOG-ID will be used as the base table for the | + system catalog. | + | + +File: slib.info, Node: Base Field Types, Next: Composite Keys, Prev: Base Tables, Up: Base Table + | +Base Field Types | +................ | + | + - Operation on base-table: supported-type? symbol | + Returns `#t' if SYMBOL names a type allowed as a column value by | + the implementation, and `#f' otherwise. At a minimum, an | + implementation must support the types `integer', `ordinal', | + `symbol', `string', and `boolean'. | + | + - Operation on base-table: supported-key-type? symbol | + Returns `#t' if SYMBOL names a type allowed as a key value by the | + implementation, and `#f' otherwise. At a minimum, an | + implementation must support the types `ordinal', and `symbol'. | + | +An "ordinal" is an exact positive integer. The other types are | +standard Scheme. | + | + +File: slib.info, Node: Composite Keys, Next: Base Record Operations, Prev: Base Field Types, Up: Base Table + | +Composite Keys | +.............. | + | + - Operation on base-table: make-keyifier-1 type | + Returns a procedure which accepts a single argument which must be | + of type TYPE. This returned procedure returns an object suitable | + for being a KEY argument in the functions whose descriptions | + follow. | + | + Any 2 arguments of the supported type passed to the returned | + function which are not `equal?' must result in returned values | + which are not `equal?'. | + | + - Operation on base-table: make-list-keyifier key-dimension types | + The list of symbols TYPES must have at least KEY-DIMENSION | + elements. Returns a procedure which accepts a list of length | + KEY-DIMENSION and whose types must corresopond to the types named | + by TYPES. This returned procedure combines the elements of its | + list argument into an object suitable for being a KEY argument in | + the functions whose descriptions follow. | + | + Any 2 lists of supported types (which must at least include | + symbols and non-negative integers) passed to the returned function | + which are not `equal?' must result in returned values which are not | + `equal?'. | + | + - Operation on base-table: make-key-extractor key-dimension types | + column-number | + Returns a procedure which accepts objects produced by application | + of the result of `(make-list-keyifier KEY-DIMENSION TYPES)'. This | + procedure returns a KEY which is `equal?' to the COLUMN-NUMBERth | + element of the list which was passed to create COMPOSITE-KEY. The | + list TYPES must have at least KEY-DIMENSION elements. | + | + - Operation on base-table: make-key->list key-dimension types | + Returns a procedure which accepts objects produced by application | + of the result of `(make-list-keyifier KEY-DIMENSION TYPES)'. This | + procedure returns a list of KEYs which are elementwise `equal?' to | + the list which was passed to create COMPOSITE-KEY. | + | + +File: slib.info, Node: Base Record Operations, Next: Match Keys, Prev: Composite Keys, Up: Base Table + | +Base Record Operations | +...................... | + | +In the following functions, the KEY argument can always be assumed to | +be the value returned by a call to a _keyify_ routine. | + | + - Operation on base-table: present? handle key | + Returns a non-`#f' value if there is a row associated with KEY in | + the table opened in HANDLE and `#f' otherwise. | + | + - Operation on base-table: make-getter key-dimension types | + Returns a procedure which takes arguments HANDLE and KEY. This | + procedure returns a list of the non-primary values of the relation | + (in the base table opened in HANDLE) whose primary key is KEY if | + it exists, and `#f' otherwise. | + | +`make-getter-1' is a new operation. The relational-database module | +works with older base-table implementations by using `make-getter'. | + | + - Operation on base-table: make-getter-1 key-dimension types index | + Returns a procedure which takes arguments HANDLE and KEY. This | + procedure returns the value of the INDEXth field (in the base | + table opened in HANDLE) whose primary key is KEY if it exists, and | + `#f' otherwise. | + | + INDEX must be larger than KEY-DIMENSION. | + | + - Operation on base-table: make-putter key-dimension types | + Returns a procedure which takes arguments HANDLE and KEY and | + VALUE-LIST. This procedure associates the primary key KEY with | + the values in VALUE-LIST (in the base table opened in HANDLE) and | + returns an unspecified value. | + | + - Operation on base-table: delete handle key | + Removes the row associated with KEY from the table opened in | + HANDLE. An unspecified value is returned. | + | + +File: slib.info, Node: Match Keys, Next: Aggregate Base Operations, Prev: Base Record Operations, Up: Base Table + | +Match Keys | +.......... | + | +A MATCH-KEYS argument is a list of length equal to the number of | +primary keys. The MATCH-KEYS restrict the actions of the table command | +to those records whose primary keys all satisfy the corresponding | +element of the MATCH-KEYS list. The elements and their actions are: | + | + `#f' | + The false value matches any key in the corresponding position. | + | + an object of type procedure | + This procedure must take a single argument, the key in the | + corresponding position. Any key for which the procedure | + returns a non-false value is a match; Any key for which the | + procedure returns a `#f' is not. | + | + other values | + Any other value matches only those keys `equal?' to it. | + | + +File: slib.info, Node: Aggregate Base Operations, Next: Base ISAM Operations, Prev: Match Keys, Up: Base Table + | +Aggregate Base Operations | +......................... | + | +The KEY-DIMENSION and COLUMN-TYPES arguments are needed to decode the | +composite-keys for matching with MATCH-KEYS. | + | + - Operation on base-table: delete* handle key-dimension column-types | + match-keys | + Removes all rows which satisfy MATCH-KEYS from the table opened in | + HANDLE. An unspecified value is returned. | + | + - Operation on base-table: for-each-key handle procedure key-dimension | + column-types match-keys | + Calls PROCEDURE once with each KEY in the table opened in HANDLE | + which satisfy MATCH-KEYS in an unspecified order. An unspecified | + value is returned. | + | + - Operation on base-table: map-key handle procedure key-dimension | + column-types match-keys | + Returns a list of the values returned by calling PROCEDURE once | + with each KEY in the table opened in HANDLE which satisfy | + MATCH-KEYS in an unspecified order. | + | + +File: slib.info, Node: Base ISAM Operations, Prev: Aggregate Base Operations, Up: Base Table + | +Base ISAM Operations | +.................... | + | +These operations are optional for a Base-Table implementation. | + | + - Operation on base-table: ordered-for-each-key handle procedure | + key-dimension column-types match-keys | + Calls PROCEDURE once with each KEY in the table opened in HANDLE | + which satisfy MATCH-KEYS in the natural order for the types of the | + primary key fields of that table. An unspecified value is | + returned. | + | + - Operation on base-table: make-nexter handle key-dimension | + column-types index | + Returns a procedure of arguments KEY1 KEY2 ... which returns the | + key-list identifying the lowest record higher than KEY1 KEY2 ... | + which is stored in the base-table and which differs in column | + INDEX or a lower indexed key; or false if no higher record is | + present. | + | + - Operation on base-table: make-prever handle key-dimension | + column-types index | + Returns a procedure of arguments KEY1 KEY2 ... which returns the | + key-list identifying the highest record less than KEY1 KEY2 ... | + which is stored in the base-table and which differs in column | + INDEX or a lower indexed key; or false if no higher record is | + present. | + | + +File: slib.info, Node: Catalog Representation, Next: Relational Database Objects, Prev: Base Table, Up: Relational Infrastructure + | +Catalog Representation | +---------------------- | + | +Each database (in an implementation) has a "system catalog" which | +describes all the user accessible tables in that database (including | +itself). | + | +The system catalog base table has the following fields. `PRI' | +indicates a primary key for that table. | + | + PRI table-name | + column-limit the highest column number | + coltab-name descriptor table name | + bastab-id data base table identifier | + user-integrity-rule | + view-procedure A scheme thunk which, when called, | + produces a handle for the view. coltab | + and bastab are specified if and only if | + view-procedure is not. | + | +Descriptors for base tables (not views) are tables (pointed to by | +system catalog). Descriptor (base) tables have the fields: | + | + PRI column-number sequential integers from 1 | + primary-key? boolean TRUE for primary key components | + column-name | + column-integrity-rule | + domain-name | + | +A "primary key" is any column marked as `primary-key?' in the | +corresponding descriptor table. All the `primary-key?' columns must | +have lower column numbers than any non-`primary-key?' columns. Every | +table must have at least one primary key. Primary keys must be | +sufficient to distinguish all rows from each other in the table. All of | +the system defined tables have a single primary key. | + | +A "domain" is a category describing the allowable values to occur in a | +column. It is described by a (base) table with the fields: | + | + PRI domain-name | + foreign-table | + domain-integrity-rule | + type-id | + type-param | + | +The "type-id" field value is a symbol. This symbol may be used by the | +underlying base table implementation in storing that field. | + | +If the `foreign-table' field is non-`#f' then that field names a table | +from the catalog. The values for that domain must match a primary key | +of the table referenced by the TYPE-PARAM (or `#f', if allowed). This | +package currently does not support composite foreign-keys. | + | +The types for which support is planned are: | + atom | + symbol | + string [<length>] | + number [<base>] | + money <currency> | + date-time | + boolean | + | + foreign-key <table-name> | + expression | + virtual <expression> | + | + +File: slib.info, Node: Relational Database Objects, Next: Database Operations, Prev: Catalog Representation, Up: Relational Infrastructure + | +Relational Database Objects | +--------------------------- | + | +This object-oriented interface is deprecated for typical database | +applications; *Note Using Databases:: provides an application programmer | +interface which is easier to understand and use. | + | + - Function: make-relational-system base-table-implementation | + Returns a procedure implementing a relational database using the | + BASE-TABLE-IMPLEMENTATION. | + | + All of the operations of a base table implementation are accessed | + through a procedure defined by `require'ing that implementation. | + Similarly, all of the operations of the relational database | + implementation are accessed through the procedure returned by | + `make-relational-system'. For instance, a new relational database | + could be created from the procedure returned by | + `make-relational-system' by: | + | + (require 'alist-table) | + (define relational-alist-system | + (make-relational-system alist-table)) | + (define create-alist-database | + (relational-alist-system 'create-database)) | + (define my-database | + (create-alist-database "mydata.db")) | + | +What follows are the descriptions of the methods available from | +relational system returned by a call to `make-relational-system'. | + | + - Operation on relational-system: create-database filename | + Returns an open, nearly empty relational database associated with | + FILENAME. The only tables defined are the system catalog and | + domain table. Calling the `close-database' method on this database | + and possibly other operations will cause FILENAME to be written | + to. If FILENAME is `#f' a temporary, non-disk based database will | + be created if such can be supported by the underlying base table | + implelentation. If the database cannot be created as specified | + `#f' is returned. For the fields and layout of descriptor tables, | + *Note Catalog Representation:: | + | + - Operation on relational-system: open-database filename mutable? | + Returns an open relational database associated with FILENAME. If | + MUTABLE? is `#t', this database will have methods capable of | + effecting change to the database. If MUTABLE? is `#f', only | + methods for inquiring the database will be available. Calling the | + `close-database' (and possibly other) method on a MUTABLE? | + database will cause FILENAME to be written to. If the database | + cannot be opened as specified `#f' is returned. | + | + +File: slib.info, Node: Database Operations, Prev: Relational Database Objects, Up: Relational Infrastructure + | +Database Operations | +------------------- | + | +This object-oriented interface is deprecated for typical database | +applications; *Note Using Databases:: provides an application programmer | +interface which is easier to understand and use. | + | +These are the descriptions of the methods available from an open | +relational database. A method is retrieved from a database by calling | +the database with the symbol name of the operation. For example: | + | + (define my-database | + (create-alist-database "mydata.db")) | + (define telephone-table-desc | + ((my-database 'create-table) 'telephone-table-desc)) | + | + - Operation on relational-database: close-database | + Causes the relational database to be written to its associated | + file (if any). If the write is successful, subsequent operations | + to this database will signal an error. If the operations completed | + successfully, `#t' is returned. Otherwise, `#f' is returned. | + | + - Operation on relational-database: write-database filename | + Causes the relational database to be written to FILENAME. If the | + write is successful, also causes the database to henceforth be | + associated with FILENAME. Calling the `close-database' (and | + possibly other) method on this database will cause FILENAME to be | + written to. If FILENAME is `#f' this database will be changed to | + a temporary, non-disk based database if such can be supported by | + the underlying base table implelentation. If the operations | + completed successfully, `#t' is returned. Otherwise, `#f' is | + returned. | + | + - Operation on relational-database: sync-database | + Causes any pending updates to the database file to be written out. | + If the operations completed successfully, `#t' is returned. | + Otherwise, `#f' is returned. | + | + - Operation on relational-database: solidify-database | + Causes any pending updates to the database file to be written out. | + If the writes completed successfully, then the database is | + changed to be immutable and `#t' is returned. Otherwise, `#f' is | + returned. | + | + - Operation on relational-database: table-exists? table-name | + Returns `#t' if TABLE-NAME exists in the system catalog, otherwise | + returns `#f'. | + | + - Operation on relational-database: open-table table-name mutable? | + Returns a "methods" procedure for an existing relational table in | + this database if it exists and can be opened in the mode indicated | + by MUTABLE?, otherwise returns `#f'. | + | +These methods will be present only in mutable databases. | + | + - Operation on relational-database: delete-table table-name | + Removes and returns the TABLE-NAME row from the system catalog if | + the table or view associated with TABLE-NAME gets removed from the | + database, and `#f' otherwise. | + | + - Operation on relational-database: create-table table-desc-name | + Returns a methods procedure for a new (open) relational table for | + describing the columns of a new base table in this database, | + otherwise returns `#f'. For the fields and layout of descriptor | + tables, *Note Catalog Representation::. | + | + - Operation on relational-database: create-table table-name | + table-desc-name | + Returns a methods procedure for a new (open) relational table with | + columns as described by TABLE-DESC-NAME, otherwise returns `#f'. | + | + - Operation on relational-database: create-view ?? | + - Operation on relational-database: project-table ?? | + - Operation on relational-database: restrict-table ?? | + - Operation on relational-database: cart-prod-tables ?? | + Not yet implemented. | + | + +File: slib.info, Node: Weight-Balanced Trees, Prev: Relational Infrastructure, Up: Database Packages + | Weight-Balanced Trees ===================== - `(require 'wt-tree)' +`(require 'wt-tree)' Balanced binary trees are a useful data structure for maintaining large sets of ordered objects or sets of associations whose keys are @@ -7365,7 +9972,7 @@ File: slib.info, Node: Construction of Weight-Balanced Trees, Next: Basic Oper Construction of Weight-Balanced Trees ------------------------------------- - Binary trees require there to be a total order on the keys used to +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 _types_, where the type is an object encapsulating the ordering relation. Creating a tree is a two-stage process. First a tree type @@ -7442,15 +10049,11 @@ File: slib.info, Node: Basic Operations on Weight-Balanced Trees, Next: Advanc Basic Operations on Weight-Balanced Trees ----------------------------------------- - This section describes the basic tree operations on weight balanced +This section describes the basic tree operations on weight balanced trees. These operations are the usual tree operations for insertion, deletion and lookup, some predicates and a procedure for determining the number of associations in a tree. - - - procedure+: wt-tree? object - Returns `#t' if OBJECT is a weight-balanced tree, otherwise - returns `#f'. - + | - procedure+: wt-tree/empty? wt-tree Returns `#t' if WT-TREE contains no associations, otherwise returns `#f'. @@ -7506,7 +10109,7 @@ File: slib.info, Node: Advanced Operations on Weight-Balanced Trees, Next: Ind Advanced Operations on Weight-Balanced Trees -------------------------------------------- - In the following the _size_ of a tree is the number of associations +In the following the _size_ of a tree is the number of associations that the tree contains, and a _smaller_ tree contains fewer associations. @@ -7630,7 +10233,7 @@ File: slib.info, Node: Indexing Operations on Weight-Balanced Trees, Prev: Adv Indexing Operations on Weight-Balanced Trees -------------------------------------------- - Weight balanced trees support operations that view the tree as sorted +Weight balanced trees support operations that view the tree as sorted sequence of associations. Elements of the sequence can be accessed by position, and the position of an element in the sequence can be determined, both in logarthmic time. @@ -7654,11 +10257,9 @@ determined, both in logarthmic time. Indexing can be used to find the median and maximum keys in the tree as follows: - median: (wt-tree/index WT-TREE - (quotient (wt-tree/size WT-TREE) 2)) - - maximum: (wt-tree/index WT-TREE - (-1+ (wt-tree/size WT-TREE))) + median: (wt-tree/index WT-TREE (quotient (wt-tree/size WT-TREE) 2)) + + maximum: (wt-tree/index WT-TREE (-1+ (wt-tree/size WT-TREE))) - procedure+: wt-tree/rank wt-tree key Determines the 0-based position of KEY in the sorted sequence of @@ -7713,68 +10314,147 @@ Other Packages * Menu: * Data Structures:: Various data structures. -* Sorting and Searching:: | +* Sorting and Searching:: * Procedures:: Miscellaneous utility procedures. * Standards Support:: Support for Scheme Standards. * Session Support:: REPL and Debugging. -* Extra-SLIB Packages:: +* System Interface:: 'system, 'getenv, and other programs. +* Extra-SLIB Packages:: Outside the envelope. | File: slib.info, Node: Data Structures, Next: Sorting and Searching, Prev: Other Packages, Up: Other Packages - | + Data Structures =============== * Menu: * Arrays:: 'array +* Subarrays:: 'subarray * Array Mapping:: 'array-for-each * Association Lists:: 'alist * Byte:: 'byte +* Byte/Number Conversions:: 'byte-number | +* MAT-File Format:: 'matfile * Portable Image Files:: 'pnm * Collections:: 'collect * Dynamic Data Type:: 'dynamic * Hash Tables:: 'hash-table -* Hashing:: 'hash, 'sierpinski, 'soundex * Object:: 'object * Priority Queues:: 'priority-queue * Queues:: 'queue -* Records:: 'record | +* Records:: 'record -File: slib.info, Node: Arrays, Next: Array Mapping, Prev: Data Structures, Up: Data Structures +File: slib.info, Node: Arrays, Next: Subarrays, Prev: Data Structures, Up: Data Structures Arrays ------ - `(require 'array)' +`(require 'array)' - Function: array? obj Returns `#t' if the OBJ is an array, and `#f' if not. -_Note:_ Arrays are not disjoint from other Scheme types. Strings and | -vectors also satisfy `array?'. A disjoint array predicate can be | -written: | - | - (define (strict-array? obj) | - (and (array? obj) (not (string? obj)) (not (vector? obj)))) | - | - - Function: array=? array1 array2 | - Returns `#t' if ARRAY1 and ARRAY2 have the same rank and shape and | - the corresponding elements of ARRAY1 and ARRAY2 are `equal?'. | - | - (array=? (make-array 'foo 3 3) (make-array 'foo '(0 2) '(1 2))) | - => #t | - | - - Function: make-array initial-value bound1 bound2 ... - Creates and returns an array with dimensions BOUND1, BOUND2, ... | - and filled with INITIAL-VALUE. | +_Note:_ Arrays are not disjoint from other Scheme types. Strings and +vectors also satisfy `array?'. A disjoint array predicate can be +written: + + (define (strict-array? obj) + (and (array? obj) (not (string? obj)) (not (vector? obj)))) + + - Function: array=? array1 array2 + Returns `#t' if ARRAY1 and ARRAY2 have the same rank and shape and + the corresponding elements of ARRAY1 and ARRAY2 are `equal?'. + + (array=? (create-array '#(foo) 3 3) + (create-array '#(foo) '(0 2) '(0 2))) + => #t + + - Function: create-array prototype bound1 bound2 ... + Creates and returns an array of type PROTOTYPE with dimensions + BOUND1, BOUND2, ... and filled with elements from PROTOTYPE. + PROTOTYPE must be an array, vector, or string. The + implementation-dependent type of the returned array will be the + same as the type of PROTOTYPE; except if that would be a vector or + string with non-zero origin, in which case some variety of array + will be returned. + + If the PROTOTYPE has no elements, then the initial contents of the + returned array are unspecified. Otherwise, the returned array + will be filled with the element at the origin of PROTOTYPE. + +These functions return a prototypical uniform-array enclosing the | +optional argument (which must be of the correct type). If the | +uniform-array type is supported by the implementation, then it is | +returned; defaulting to the next larger precision type; resorting | +finally to vector. | + + - Function: ac64 z + - Function: ac64 + Returns a high-precision complex uniform-array prototype. + + - Function: ac32 z + - Function: ac32 + Returns a complex uniform-array prototype. + + - Function: ar64 x + - Function: ar64 + Returns a high-precision real uniform-array prototype. + + - Function: ar32 x + - Function: ar32 + Returns a real uniform-array prototype. + + - Function: as64 n + - Function: as64 + Returns an exact signed integer uniform-array prototype with at + least 64 bits of precision. + + - Function: as32 n + - Function: as32 + Returns an exact signed integer uniform-array prototype with at + least 32 bits of precision. + + - Function: as16 n + - Function: as16 + Returns an exact signed integer uniform-array prototype with at + least 16 bits of precision. + + - Function: as8 n + - Function: as8 + Returns an exact signed integer uniform-array prototype with at + least 8 bits of precision. + + - Function: au64 k + - Function: au64 + Returns an exact non-negative integer uniform-array prototype with + at least 64 bits of precision. + + - Function: au32 k + - Function: au32 + Returns an exact non-negative integer uniform-array prototype with + at least 32 bits of precision. + + - Function: au16 k + - Function: au16 + Returns an exact non-negative integer uniform-array prototype with + at least 16 bits of precision. + + - Function: au8 k + - Function: au8 + Returns an exact non-negative integer uniform-array prototype with + at least 8 bits of precision. + + - Function: at1 bool + - Function: at1 + Returns a boolean uniform-array prototype. When constructing an array, BOUND is either an inclusive range of indices expressed as a two element list, or an upper bound expressed as a single integer. So - (make-array 'foo 3 3) == (make-array 'foo '(0 2) '(0 2)) + (create-array '#(foo) 3 3) == (create-array '#(foo) '(0 2) '(0 2)) - Function: make-shared-array array mapper bound1 bound2 ... `make-shared-array' can be used to create shared subarrays of other @@ -7783,7 +10463,7 @@ a single integer. So linear, and its range must stay within the bounds of the old array, but it can be otherwise arbitrary. A simple example: - (define fred (make-array #f 8 8)) + (define fred (create-array '#(#f) 8 8)) (define freds-diagonal (make-shared-array fred (lambda (i) (list i i)) 8)) (array-set! freds-diagonal 'foo 3) @@ -7800,37 +10480,123 @@ a single integer. So 0 is returned. - Function: array-shape array - Returns a list of inclusive bounds. | - | - (array-shape (make-array 'foo 3 5)) + Returns a list of inclusive bounds. + + (array-shape (create-array '#() 3 5)) => ((0 2) (0 4)) - Function: array-dimensions array `array-dimensions' is similar to `array-shape' but replaces - elements with a 0 minimum with one greater than the maximum. | - | - (array-dimensions (make-array 'foo 3 5)) + elements with a 0 minimum with one greater than the maximum. + + (array-dimensions (create-array '#() 3 5)) => (3 5) - - Function: array-in-bounds? array index1 index2 ... | + - Function: array-in-bounds? array index1 index2 ... Returns `#t' if its arguments would be acceptable to `array-ref'. - Function: array-ref array index1 index2 ... - Returns the (INDEX1, INDEX2, ...) element of ARRAY. | + Returns the (INDEX1, INDEX2, ...) element of ARRAY. - - Function: array-set! array obj index1 index2 ... | - Stores OBJ in the (INDEX1, INDEX2, ...) element of ARRAY. The | - value returned by `array-set!' is unspecified. | + - Procedure: array-set! array obj index1 index2 ... | + Stores OBJ in the (INDEX1, INDEX2, ...) element of ARRAY. The + value returned by `array-set!' is unspecified. -File: slib.info, Node: Array Mapping, Next: Association Lists, Prev: Arrays, Up: Data Structures +File: slib.info, Node: Subarrays, Next: Array Mapping, Prev: Arrays, Up: Data Structures + +Subarrays +--------- + +`(require 'subarray)' + + - Function: subarray array select ... + selects a subset of an array. For ARRAY of rank n, there must be + at least n SELECTS arguments. For 0 <= j < n, SELECTSj is either + an integer, a list of two integers within the range for the jth + index, or #f. + + When SELECTSj is a list of two integers, then the jth index is + restricted to that subrange in the returned array. + + When SELECTSj is #f, then the full range of the jth index is + accessible in the returned array. An elided argument is + equivalent to #f. + + When SELECTSj is an integer, then the rank of the returned array is + less than ARRAY, and only elements whose jth index equals SELECTSj + are shared. + + > (define ra '#2A((a b c) (d e f))) + #<unspecified> + > (subarray ra 0 #f) + #1A(a b c) + > (subarray ra 1 #f) + #1A(d e f) + > (subarray ra #f 1) + #1A(b e) + > (subarray ra '(0 1) #f) + #2A((a b c) (d e f)) + > (subarray ra #f '(0 1)) + #2A((a b) (d e)) + > (subarray ra #f '(1 2)) + #2A((b c) (e f)) + + - Function: subarray0 array select ... + Behaves like subarray, but aligns the returned array origin to 0 + .... + + - Function: array-align array coord ... + Returns an array shared with ARRAY but with a different origin. + The COORDS are the exact integer coordinates of the new origin. + Indexes corresponding to missing or #f coordinates are not + realigned. + + For example: + (define ra2 (create-array '#(5) '(5 9) '(-4 0))) + (array-shape ra2) => ((5 9) (-4 0)) + (array-shape (array-align ra2 0 0)) => ((0 4) (0 4)) + (array-shape (array-align ra2 0)) => ((0 4) (-4 0)) + (array-shape (array-align ra2)) => ((5 9) (-4 0)) + (array-shape (array-align ra2 0 #f)) => ((0 4) (-4 0)) + (array-shape (array-align ra2 #f 0)) => ((5 9) (0 4)) + + - Function: array-trim array trim ... + Returns a subarray sharing contents with ARRAY except for slices + removed from either side of each dimension. Each of the TRIMS is + an exact integer indicating how much to trim. A positive S trims + the data from the lower end and reduces the upper bound of the + result; a negative S trims from the upper end and increases the + lower bound. + + For example: + (array-trim '#(0 1 2 3 4) 1) => #1A(1 2 3 4) ;; shape is ((0 3)) + (array-trim '#(0 1 2 3 4) -1) => #1A(0 1 2 3) ;; shape is ((1 4)) + + (require 'array-for-each) + (define (centered-difference ra) + (array-map - (array-trim ra 1) (array-trim ra -1))) + (define (forward-difference ra) + (array-map - (array-trim ra 1) ra)) + (define (backward-difference ra) + (array-map - ra (array-trim ra -1))) + + (centered-difference '#(0 1 3 5 9 22)) + => #1A(3 4 6 17) ;;shape is ((1 4)) + (backward-difference '#(0 1 3 5 9 22)) + => #1A(1 2 2 4 13) ;; shape is ((1 5)) + (forward-difference '#(0 1 3 5 9 22)) + => #(1 2 2 4 13) ;; shape is ((0 4)) + + +File: slib.info, Node: Array Mapping, Next: Association Lists, Prev: Subarrays, Up: Data Structures Array Mapping ------------- - `(require 'array-for-each)' +`(require 'array-for-each)' - - Function: array-map! array0 proc array1 ... + - Procedure: array-map! array0 proc array1 ... | ARRAY1, ... must have the same number of dimensions as ARRAY0 and have a range for each index which includes the range for the corresponding index in ARRAY0. PROC is applied to each tuple of @@ -7838,32 +10604,40 @@ Array Mapping corresponding element in ARRAY0. The value returned is unspecified. The order of application is unspecified. - - Function: array-for-each PROC ARRAY0 ... + - Function: array-map prototype proc array1 array2 ... | + ARRAY2, ... must have the same number of dimensions as ARRAY1 and | + have a range for each index which includes the range for the | + corresponding index in ARRAY1. PROC is applied to each tuple of | + elements of ARRAY1, ARRAY2, ... and the result is stored as the | + corresponding element in a new array of type PROTOTYPE. The new | + array is returned. The order of application is unspecified. | + | + - Function: array-for-each proc array0 ... | PROC is applied to each tuple of elements of ARRAY0 ... in row-major order. The value returned is unspecified. - - Function: array-indexes ARRAY + - Function: array-indexes array | Returns an array of lists of indexes for ARRAY such that, if LI is a list of indexes for which ARRAY is defined, (equal? LI (apply array-ref (array-indexes ARRAY) LI)). - - Function: array-index-map! array proc + - Procedure: array-index-map! array proc | applies PROC to the indices of each element of ARRAY in turn, storing the result in the corresponding element. The value returned and the order of application are unspecified. One can implement ARRAY-INDEXES as (define (array-indexes array) - (let ((ra (apply make-array #f (array-shape array)))) + (let ((ra (apply create-array '#() (array-shape array)))) (array-index-map! ra (lambda x x)) ra)) Another example: (define (apl:index-generator n) - (let ((v (make-uniform-vector n 1))) + (let ((v (make-vector n 1))) (array-index-map! v (lambda (i) i)) v)) - - Function: array-copy! source destination + - Procedure: array-copy! source destination | Copies every element from vector or array SOURCE to the corresponding element of DESTINATION. DESTINATION must have the same rank as SOURCE, and be at least as large in each dimension. @@ -7875,7 +10649,7 @@ File: slib.info, Node: Association Lists, Next: Byte, Prev: Array Mapping, U Association Lists ----------------- - `(require 'alist)' +`(require 'alist)' Alist functions provide utilities for treating a list of key-value pairs as an associative database. These functions take an equality @@ -7902,6 +10676,7 @@ tables for improved performance. value associated with KEY will be lost. This returned procedure may or may not have side effects on its ALIST argument. An example of correct usage is: + (define put (alist-associator string-ci=?)) (define alist '()) (set! alist (put alist "Foo" 9)) @@ -7911,6 +10686,7 @@ tables for improved performance. an alist with an association whose KEY is key removed. This returned procedure may or may not have side effects on its ALIST argument. An example of correct usage is: + (define rem (alist-remover string-ci=?)) (set! alist (rem alist "foo")) @@ -7924,14 +10700,14 @@ tables for improved performance. be a function of 2 arguments. The returned value is unspecified. -File: slib.info, Node: Byte, Next: Portable Image Files, Prev: Association Lists, Up: Data Structures - +File: slib.info, Node: Byte, Next: Byte/Number Conversions, Prev: Association Lists, Up: Data Structures + | Byte ---- - `(require 'byte)' +`(require 'byte)' - Some algorithms are expressed in terms of arrays of small integers. +Some algorithms are expressed in terms of arrays of small integers. Using Scheme strings to implement these arrays is not portable vis-a-vis the correspondence between integers and characters and non-ascii character sets. These functions abstract the notion of a "byte". @@ -7941,58 +10717,306 @@ character sets. These functions abstract the notion of a "byte". BYTES using zero-origin indexing. - Procedure: byte-set! bytes k byte - K must be a valid index of BYTES%, and BYTE must be a small - integer. `Byte-set!' stores BYTE in element K of BYTES and - returns an unspecified value. - - - Function: make-bytes k + K must be a valid index of BYTES, and BYTE must be a small | + nonnegative integer. `byte-set!' stores BYTE in element K of | + BYTES and returns an unspecified value. | + | - Function: make-bytes k byte - `Make-bytes' returns a newly allocated byte-array of length K. If + - Function: make-bytes k | + `make-bytes' returns a newly allocated byte-array of length K. If | BYTE is given, then all elements of the byte-array are initialized to BYTE, otherwise the contents of the byte-array are unspecified. - - Function: bytes-length bytes `bytes-length' returns length of byte-array BYTES. + - Function: bytes byte ... + Returns a newly allocated byte-array composed of the small | + nonnegative arguments. | + + - Function: bytes->list bytes + `bytes->list' returns a newly allocated list of the bytes that | + make up the given byte-array. | + | + - Function: list->bytes bytes + `list->bytes' returns a newly allocated byte-array formed from the | + small nonnegative integers in the list BYTES. | + +`Bytes->list' and `list->bytes' are inverses so far as `equal?' is | +concerned. | - - Function: write-byte byte + - Function: bytes-copy bytes | + Returns a newly allocated copy of the given BYTES. | + | + - Procedure: bytes-reverse! bytes | + Reverses the order of byte-array BYTES. | + | + - Function: bytes-reverse bytes | + Returns a newly allocated bytes-array consisting of the elements of | + BYTES in reverse order. | + | +Input and output of bytes should be with ports opened in "binary" mode | +(*note Input/Output::). Calling `open-file' with 'rb or 'wb modes | +argument will return a binary port if the Scheme implementation +supports it. + | - Function: write-byte byte port + - Function: write-byte byte | Writes the byte BYTE (not an external representation of the byte) to the given PORT and returns an unspecified value. The PORT argument may be omitted, in which case it defaults to the value returned by `current-output-port'. - - - - Function: read-byte + | - Function: read-byte port + - Function: read-byte | Returns the next byte available from the input PORT, updating the PORT to point to the following byte. If no more bytes are - available, an end of file object is returned. PORT may be + available, an end-of-file object is returned. PORT may be | omitted, in which case it defaults to the value returned by `current-input-port'. +When reading and writing binary numbers with `read-bytes' and | +`write-bytes', the sign of the length argument determines the | +endianness (order) of bytes. Positive treats them as big-endian, the | +first byte input or output is highest order. Negative treats them as | +little-endian, the first byte input or output is the lowest order. | + | +Once read in, SLIB treats byte sequences as big-endian. The multi-byte | +sequences produced and used by number conversion routines *note | +Byte/Number Conversions:: are always big-endian. | + | + - Function: read-bytes n port | + - Function: read-bytes n | + `read-bytes' returns a newly allocated bytes-array filled with | + `(abs N)' bytes read from PORT. If N is positive, then the first | + byte read is stored at index 0; otherwise the last byte read is | + stored at index 0. Note that the length of the returned string | + will be less than `(abs N)' if PORT reaches end-of-file. | + | + PORT may be omitted, in which case it defaults to the value | + returned by `current-input-port'. | + | + - Function: write-bytes bytes n port | + - Function: write-bytes bytes n | + `write-bytes' writes `(abs N)' bytes to output-port PORT. If N is | + positive, then the first byte written is index 0 of BYTES; | + otherwise the last byte written is index 0 of BYTES. | + `write-bytes' returns an unspecified value. | + | + PORT may be omitted, in which case it defaults to the value | + returned by `current-output-port'. | + | +`substring-read!' and `substring-write' provide lower-level procedures | +for reading and writing blocks of bytes. The relative size of START | +and END determines the order of writing. | + | + - Procedure: substring-read! string start end port | + - Procedure: substring-read! string start end | + Fills STRING with up to `(abs (- START END))' bytes read from | + PORT. The first byte read is stored at index STRING. | + `substring-read!' returns the number of bytes read. | + | + PORT may be omitted, in which case it defaults to the value | + returned by `current-input-port'. | + | + - Function: substring-write string start end port | + - Function: substring-write string start end | + `substring-write' writes `(abs (- START END))' bytes to | + output-port PORT. The first byte written is index START of | + STRING. `substring-write' returns the number of bytes written. | + | + PORT may be omitted, in which case it defaults to the value | + returned by `current-output-port'. | - - Function: bytes byte ... - Returns a newly allocated byte-array composed of the arguments. + +File: slib.info, Node: Byte/Number Conversions, Next: MAT-File Format, Prev: Byte, Up: Data Structures + | +Byte/Number Conversions | +----------------------- | + | +`(require 'byte-number)' | + | +The multi-byte sequences produced and used by numeric conversion | +routines are always big-endian. Endianness can be changed during | +reading and writing bytes using `read-bytes' and `write-bytes' *Note | +read-bytes: Byte. | + | +The sign of the length argument to bytes/integer conversion procedures | +determines the signedness of the number. | + | + - Function: bytes->integer bytes n | + Converts the first `(abs N)' bytes of big-endian BYTES array to an | + integer. If N is negative then the integer coded by the bytes are | + treated as two's-complement (can be negative). | + | + (bytes->integer (bytes 0 0 0 15) -4) => 15 | + (bytes->integer (bytes 0 0 0 15) 4) => 15 | + (bytes->integer (bytes 255 255 255 255) -4) => -1 | + (bytes->integer (bytes 255 255 255 255) 4) => 4294967295 | + (bytes->integer (bytes 128 0 0 0) -4) => -2147483648 | + (bytes->integer (bytes 128 0 0 0) 4) => 2147483648 | + | + - Function: integer->bytes n len | + Converts the integer N to a byte-array of `(abs N)' bytes. If N | + and LEN are both negative, then the bytes in the returned array | + are coded two's-complement. | + | + (bytes->list (integer->bytes 15 -4)) => (0 0 0 15) | + (bytes->list (integer->bytes 15 4)) => (0 0 0 15) | + (bytes->list (integer->bytes -1 -4)) => (255 255 255 255) + (bytes->list (integer->bytes 4294967295 4)) => (255 255 255 255) + (bytes->list (integer->bytes -2147483648 -4)) => (128 0 0 0) | + (bytes->list (integer->bytes 2147483648 4)) => (128 0 0 0) | + | + - Function: bytes->ieee-float bytes | + BYTES must be a 4-element byte-array. `bytes->ieee-float' | + calculates and returns the value of BYTES interpreted as a | + big-endian IEEE 4-byte (32-bit) number. | + | + (bytes->ieee-float (bytes #x40 0 0 0)) => 2.0 | + (bytes->ieee-float (bytes #x40 #xd0 0 0)) => 6.5 | + (bytes->ieee-float (bytes #xc0 #xd0 0 0)) => -6.5 | + | + (bytes->ieee-float (bytes 0 #x80 0 0)) => 11.754943508222875e-39 | + (bytes->ieee-float (bytes 0 #x40 0 0)) => 5.877471754111437e-39 | + (bytes->ieee-float (bytes 0 0 0 1)) => 1.401298464324817e-45 | + | + (bytes->ieee-float (bytes #xff #x80 0 0)) => -1/0 | + (bytes->ieee-float (bytes #x7f #x80 0 0)) => 1/0 | + (bytes->ieee-float (bytes #x7f #x80 0 1)) => 0/0 | + | + - Function: bytes->ieee-double bytes | + BYTES must be a 8-element byte-array. `bytes->ieee-double' | + calculates and returns the value of BYTES interpreted as a | + big-endian IEEE 8-byte (64-bit) number. | + | + (bytes->ieee-double (bytes 0 0 0 0 0 0 0 0)) => 0.0 | + (bytes->ieee-double (bytes #x40 0 0 0 0 0 0 0)) => 2 | + (bytes->ieee-double (bytes #x40 #x1A 0 0 0 0 0 0)) => 6.5 | + (bytes->ieee-double (bytes #xC0 #x1A 0 0 0 0 0 0)) => -6.5 | + | + (bytes->ieee-double (bytes 0 8 0 0 0 0 0 0)) => 11.125369292536006e-309 | + (bytes->ieee-double (bytes 0 4 0 0 0 0 0 0)) => 5.562684646268003e-309 | + (bytes->ieee-double (bytes 0 0 0 0 0 0 0 1)) => 4.0e-324 | + | + (bytes->ieee-double (bytes #xFF #xF0 0 0 0 0 0 0)) => -1/0 | + (bytes->ieee-double (bytes #x7F #xF0 0 0 0 0 0 0)) => 1/0 | + (bytes->ieee-double (bytes #x7F #xF8 0 0 0 0 0 0)) => 0/0 | + | + - Function: ieee-float->bytes x | + Returns a 4-element byte-array encoding the IEEE single-precision | + floating-point of X. | + | + (bytes->list (ieee-float->bytes 2.0)) => (64 0 0 0) + (bytes->list (ieee-float->bytes 6.5)) => (64 208 0 0) + (bytes->list (ieee-float->bytes -6.5)) => (192 208 0 0) + | + (bytes->list (ieee-float->bytes 11.754943508222875e-39)) => ( 0 128 0 0) + (bytes->list (ieee-float->bytes 5.877471754111438e-39)) => ( 0 64 0 0) + (bytes->list (ieee-float->bytes 1.401298464324817e-45)) => ( 0 0 0 1) + | + (bytes->list (ieee-float->bytes -1/0)) => (255 128 0 0) + (bytes->list (ieee-float->bytes 1/0)) => (127 128 0 0) + (bytes->list (ieee-float->bytes 0/0)) => (127 128 0 1) + | + - Function: ieee-double->bytes x | + Returns a 8-element byte-array encoding the IEEE double-precision | + floating-point of X. | + | + (bytes->list (ieee-double->bytes 2.0)) => (64 0 0 0 0 0 0 0) | + (bytes->list (ieee-double->bytes 6.5)) => (64 26 0 0 0 0 0 0) | + (bytes->list (ieee-double->bytes -6.5)) => (192 26 0 0 0 0 0 0) | + | + (bytes->list (ieee-double->bytes 11.125369292536006e-309)) | + => ( 0 8 0 0 0 0 0 0) | + (bytes->list (ieee-double->bytes 5.562684646268003e-309)) | + => ( 0 4 0 0 0 0 0 0) | + (bytes->list (ieee-double->bytes 4.0e-324)) | + => ( 0 0 0 0 0 0 0 1) | + | + (bytes->list (ieee-double->bytes -1/0)) => (255 240 0 0 0 0 0 0) | + (bytes->list (ieee-double->bytes 1/0)) => (127 240 0 0 0 0 0 0) | + (bytes->list (ieee-double->bytes 0/0)) => (127 248 0 0 0 0 0 0) | + | +Byte Collation Order | +.................... | + | +The `string<?' ordering of big-endian byte-array representations of | +fixed and IEEE floating-point numbers agrees with the numerical | +ordering only when those numbers are non-negative. | + | +Straighforward modification of these formats can extend the | +byte-collating order to work for their entire ranges. This agreement | +enables the full range of numbers as keys in | +"indexed-sequential-access-method" databases. | + | + - Procedure: integer-byte-collate! byte-vector | + Modifies sign bit of BYTE-VECTOR so that `string<?' ordering of | + two's-complement byte-vectors matches numerical order. | + `integer-byte-collate!' returns BYTE-VECTOR and is its own | + functional inverse. | + | + - Function: integer-byte-collate byte-vector | + Returns copy of BYTE-VECTOR with sign bit modified so that | + `string<?' ordering of two's-complement byte-vectors matches | + numerical order. `integer-byte-collate' is its own functional | + inverse. | + | + - Procedure: ieee-byte-collate! byte-vector | + Modifies BYTE-VECTOR so that `string<?' ordering of IEEE | + floating-point byte-vectors matches numerical order. | + `ieee-byte-collate!' returns BYTE-VECTOR. | + | + - Procedure: ieee-byte-decollate! byte-vector | + Given BYTE-VECTOR modified by `IEEE-byte-collate!', reverses the | + BYTE-VECTOR modifications. | + | + - Function: ieee-byte-collate byte-vector | + Returns copy of BYTE-VECTOR encoded so that `string<?' ordering of | + IEEE floating-point byte-vectors matches numerical order. | + | + - Function: ieee-byte-decollate byte-vector | + Given BYTE-VECTOR returned by `IEEE-byte-collate', reverses the | + BYTE-VECTOR modifications. | + | + +File: slib.info, Node: MAT-File Format, Next: Portable Image Files, Prev: Byte/Number Conversions, Up: Data Structures + | +MAT-File Format +--------------- +`(require 'matfile)' - - Function: bytes->list bytes - - Function: list->bytes bytes - `Bytes->list' returns a newly allocated list of the bytes that - make up the given byte-array. `List->bytes' returns a newly - allocated byte-array formed from the small integers in the list - BYTES. `Bytes->list' and `list->bytes' are inverses so far as - `equal?' is concerned. +`http://www.mathworks.com/access/helpdesk/help/pdf_doc/matlab/matfile_format.pdf' + +This package reads MAT-File Format version 4 (MATLAB) binary data +files. MAT-files written from big-endian or little-endian computers +having IEEE format numbers are currently supported. Support for files +written from VAX or Cray machines could also be added. +The numeric and text matrix types handled; support for "sparse" +matrices awaits a sample file. + + - Function: matfile:read filename + FILENAME should be a string naming an existing file containing a + MATLAB Version 4 MAT-File. The `matfile:read' procedure reads + matrices from the file and returns a list of the results; a list + of the name string and array for each matrix. + + - Function: matfile:load filename + FILENAME should be a string naming an existing file containing a + MATLAB Version 4 MAT-File. The `matfile:load' procedure reads + matrices from the file and defines the `string-ci->symbol' for + each matrix to its corresponding array. `matfile:load' returns a + list of the symbols defined. -File: slib.info, Node: Portable Image Files, Next: Collections, Prev: Byte, Up: Data Structures +File: slib.info, Node: Portable Image Files, Next: Collections, Prev: MAT-File Format, Up: Data Structures Portable Image Files -------------------- - `(require 'pnm)' +`(require 'pnm)' - Function: pnm:type-dimensions path The string PATH must name a "portable bitmap graphics" file. @@ -8020,7 +11044,6 @@ Portable Image Files RGB (full color) image; red, green, and blue interleaved pixel values are from 0 to MAXVAL - - Function: pnm:image-file->array path array Reads the "portable bitmap graphics" file named by PATH into ARRAY. ARRAY must be the correct size and type for PATH. ARRAY @@ -8030,12 +11053,11 @@ Portable Image Files `pnm:image-file->array' creates and returns an array with the "portable bitmap graphics" file named by PATH read into it. - - - Procedure: pnm:array-write type array maxval path + - Function: pnm:array-write type array maxval path comment ... | Writes the contents of ARRAY to a TYPE image file named PATH. The file will have pixel values between 0 and MAXVAL, which must be compatible with TYPE. For `pbm' files, MAXVAL must be `1'. - + COMMENTs are included in the file header. File: slib.info, Node: Collections, Next: Dynamic Data Type, Prev: Portable Image Files, Up: Data Structures @@ -8043,16 +11065,17 @@ File: slib.info, Node: Collections, Next: Dynamic Data Type, Prev: Portable I Collections ----------- - `(require 'collect)' +`(require 'collect)' - Routines for managing collections. Collections are aggregate data +Routines for managing collections. Collections are aggregate data structures supporting iteration over their elements, similar to the Dylan(TM) language, but with a different interface. They have "elements" indexed by corresponding "keys", although the keys may be implicit (as with lists). - New types of collections may be defined as YASOS objects (*note +New types of collections may be defined as YASOS objects (*note Yasos::). They must support the following operations: + * `(collection? SELF)' (always returns `#t'); * `(size SELF)' returns the number of elements in the collection; @@ -8068,15 +11091,15 @@ Yasos::). They must support the following operations: * `(gen-keys SELF)' is like `gen-elts', but yields the collection's keys in order. - They might support specialized `for-each-key' and `for-each-elt' +They might support specialized `for-each-key' and `for-each-elt' operations. - Function: collection? obj A predicate, true initially of lists, vectors and strings. New sorts of collections must answer `#t' to `collection?'. - - Procedure: map-elts proc collection1 ... | - - Procedure: do-elts proc collection1 ... | + - Procedure: map-elts proc collection1 ... + - Procedure: do-elts proc collection1 ... PROC is a procedure taking as many arguments as there are COLLECTIONS (at least one). The COLLECTIONS are iterated over in their natural order and PROC is applied to the elements yielded by @@ -8091,8 +11114,8 @@ operations. (map-elts + (list 1 2 3) (vector 1 2 3)) => #(2 4 6) - - Procedure: map-keys proc collection1 ... | - - Procedure: do-keys proc collection1 ... | + - Procedure: map-keys proc collection1 ... + - Procedure: do-keys proc collection1 ... These are analogous to `map-elts' and `do-elts', but each iteration is over the COLLECTIONS' _keys_ rather than their elements. @@ -8106,10 +11129,10 @@ operations. These are like `do-keys' and `do-elts' but only for a single collection; they are potentially more efficient. - - Function: reduce proc seed collection1 ... | - A generalization of the list-based `comlist:reduce-init' (*note - Lists as sequences::) to collections which will shadow the - list-based version if `(require 'collect)' follows `(require + - Function: reduce proc seed collection1 ... + A generalization of the list-based `reduce-init' (*note Lists as | + sequences::) to collections which will shadow the list-based | + version if `(require 'collect)' follows `(require | 'common-list-functions)' (*note Common List Functions::). Examples: @@ -8118,7 +11141,7 @@ operations. (reduce union '() '((a b c) (b c d) (d a))) => (c b d a). - - Function: any? pred collection1 ... | + - Function: any? pred collection1 ... A generalization of the list-based `some' (*note Lists as sequences::) to collections. @@ -8126,7 +11149,7 @@ operations. (any? odd? (list 2 3 4 5)) => #t - - Function: every? pred collection1 ... | + - Function: every? pred collection1 ... A generalization of the list-based `every' (*note Lists as sequences::) to collections. @@ -8203,8 +11226,7 @@ operations. ) ((FOR-EACH-ELT self proc) (for-each (lambda (bucket) (proc (cdr bucket))) table) - ) - ) ) ) + ) ) ) ) File: slib.info, Node: Dynamic Data Type, Next: Hash Tables, Prev: Collections, Up: Data Structures @@ -8212,7 +11234,7 @@ File: slib.info, Node: Dynamic Data Type, Next: Hash Tables, Prev: Collection Dynamic Data Type ----------------- - `(require 'dynamic)' +`(require 'dynamic)' - Function: make-dynamic obj Create and returns a new "dynamic" whose global value is OBJ. @@ -8242,12 +11264,12 @@ Dynamic Data Type The `dynamic-bind' macro is not implemented. -File: slib.info, Node: Hash Tables, Next: Hashing, Prev: Dynamic Data Type, Up: Data Structures +File: slib.info, Node: Hash Tables, Next: Object, Prev: Dynamic Data Type, Up: Data Structures Hash Tables ----------- - `(require 'hash-table)' +`(require 'hash-table)' - Function: predicate->hash pred Returns a hash function (like `hashq', `hashv', or `hash') @@ -8255,12 +11277,12 @@ Hash Tables `eq?', `eqv?', `equal?', `=', `char=?', `char-ci=?', `string=?', or `string-ci=?'. - A hash table is a vector of association lists. +A hash table is a vector of association lists. - Function: make-hash-table k Returns a vector of K empty (association) lists. - Hash table functions provide utilities for an associative database. +Hash table functions provide utilities for an associative database. These functions take an equality predicate, PRED, as an argument. PRED should be `eq?', `eqv?', `equal?', `=', `char=?', `char-ci=?', `string=?', or `string-ci=?'. @@ -8272,9 +11294,9 @@ should be `eq?', `eqv?', `equal?', `=', `char=?', `char-ci=?', `#f' if no key in HASHTAB is PRED-equal to the first argument. - Function: hash-inquirer pred - Returns a procedure of 2 arguments, HASHTAB and KEY, which returns | - the value associated with KEY in HASHTAB or `#f' if KEY does not | - appear in HASHTAB. | + Returns a procedure of 2 arguments, HASHTAB and KEY, which returns + the value associated with KEY in HASHTAB or `#f' if KEY does not + appear in HASHTAB. - Function: hash-associator pred Returns a procedure of 3 arguments, HASHTAB, KEY, and VALUE, which @@ -8296,128 +11318,23 @@ should be `eq?', `eqv?', `equal?', `=', `char=?', `char-ci=?', must be a function of 2 arguments. The returned value is unspecified. + - Function: hash-rehasher pred | + `hash-rehasher' accepts a hash table predicate and returns a | + function of two arguments HASHTAB and NEW-K which is specialized | + for that predicate. | + | + This function is used for nondestrutively resizing a hash table. | + HASHTAB should be an existing hash-table using PRED, NEW-K is the | + size of a new hash table to be returned. The new hash table will | + have all of the associations of the old hash table. | + | -File: slib.info, Node: Hashing, Next: Object, Prev: Hash Tables, Up: Data Structures - -Hashing -------- - - `(require 'hash)' - - These hashing functions are for use in quickly classifying objects. -Hash tables use these functions. - - - Function: hashq obj k - - Function: hashv obj k - - Function: hash obj k - Returns an exact non-negative integer less than K. For each - non-negative integer less than K there are arguments OBJ for which - the hashing functions applied to OBJ and K returns that integer. - - For `hashq', `(eq? obj1 obj2)' implies `(= (hashq obj1 k) (hashq - obj2))'. - - For `hashv', `(eqv? obj1 obj2)' implies `(= (hashv obj1 k) (hashv - obj2))'. - - For `hash', `(equal? obj1 obj2)' implies `(= (hash obj1 k) (hash - obj2))'. - - `hash', `hashv', and `hashq' return in time bounded by a constant. - Notice that items having the same `hash' implies the items have - the same `hashv' implies the items have the same `hashq'. - - `(require 'sierpinski)' - - - Function: make-sierpinski-indexer max-coordinate - Returns a procedure (eg hash-function) of 2 numeric arguments which - preserves _nearness_ in its mapping from NxN to N. - - MAX-COORDINATE is the maximum coordinate (a positive integer) of a - population of points. The returned procedures is a function that - takes the x and y coordinates of a point, (non-negative integers) - and returns an integer corresponding to the relative position of - that point along a Sierpinski curve. (You can think of this as - computing a (pseudo-) inverse of the Sierpinski spacefilling - curve.) - - Example use: Make an indexer (hash-function) for integer points - lying in square of integer grid points [0,99]x[0,99]: - (define space-key (make-sierpinski-indexer 100)) - Now let's compute the index of some points: - (space-key 24 78) => 9206 - (space-key 23 80) => 9172 - - Note that locations (24, 78) and (23, 80) are near in index and - therefore, because the Sierpinski spacefilling curve is - continuous, we know they must also be near in the plane. Nearness - in the plane does not, however, necessarily correspond to nearness - in index, although it _tends_ to be so. - - Example applications: - * Sort points by Sierpinski index to get heuristic solution to - _travelling salesman problem_. For details of performance, - see L. Platzman and J. Bartholdi, "Spacefilling curves and the - Euclidean travelling salesman problem", JACM 36(4):719-737 - (October 1989) and references therein. - - * Use Sierpinski index as key by which to store 2-dimensional - data in a 1-dimensional data structure (such as a table). - Then locations that are near each other in 2-d space will - tend to be near each other in 1-d data structure; and - locations that are near in 1-d data structure will be near in - 2-d space. This can significantly speed retrieval from - secondary storage because contiguous regions in the plane - will tend to correspond to contiguous regions in secondary - storage. (This is a standard technique for managing CAD/CAM - or geographic data.) - - - `(require 'soundex)' - - - Function: soundex name - Computes the _soundex_ hash of NAME. Returns a string of an - initial letter and up to three digits between 0 and 6. Soundex - supposedly has the property that names that sound similar in normal - English pronunciation tend to map to the same key. - - Soundex was a classic algorithm used for manual filing of personal - records before the advent of computers. It performs adequately for - English names but has trouble with other languages. - - See Knuth, Vol. 3 `Sorting and searching', pp 391-2 - - To manage unusual inputs, `soundex' omits all non-alphabetic - characters. Consequently, in this implementation: - - (soundex <string of blanks>) => "" - (soundex "") => "" - - Examples from Knuth: - - (map soundex '("Euler" "Gauss" "Hilbert" "Knuth" - "Lloyd" "Lukasiewicz")) - => ("E460" "G200" "H416" "K530" "L300" "L222") - - (map soundex '("Ellery" "Ghosh" "Heilbronn" "Kant" - "Ladd" "Lissajous")) - => ("E460" "G200" "H416" "K530" "L300" "L222") - - Some cases in which the algorithm fails (Knuth): - - (map soundex '("Rogers" "Rodgers")) => ("R262" "R326") - - (map soundex '("Sinclair" "St. Clair")) => ("S524" "S324") - - (map soundex '("Tchebysheff" "Chebyshev")) => ("T212" "C121") - - -File: slib.info, Node: Object, Next: Priority Queues, Prev: Hashing, Up: Data Structures +File: slib.info, Node: Object, Next: Priority Queues, Prev: Hash Tables, Up: Data Structures Macroless Object System ----------------------- - `(require 'object)' +`(require 'object)' This is the Macroless Object System written by Wade Humeniuk (whumeniu@datap.ca). Conceptual Tributes: *Note Yasos::, MacScheme's @@ -8555,7 +11472,7 @@ Examples Inverter Documentation ...................... - Inheritance: +Inheritance: <inverter>::(<number> <description>) Generic-methods <inverter>::value => <number>::value @@ -8568,7 +11485,7 @@ Inverter Documentation Number Documention .................. - Inheritance +Inheritance <number>::() Slots <number>::<x> @@ -8643,8 +11560,11 @@ File: slib.info, Node: Priority Queues, Next: Queues, Prev: Object, Up: Data Priority Queues --------------- - `(require 'priority-queue)' +`(require 'priority-queue)' +This algorithm for priority queues is due to `Introduction to | +Algorithms' by T. Cormen, C. Leiserson, R. Rivest. 1989 MIT Press. | + | - Function: make-heap pred<? Returns a binary heap suitable which can be used for priority queue operations. @@ -8656,21 +11576,18 @@ Priority Queues Inserts ITEM into HEAP. ITEM can be inserted multiple times. The value returned is unspecified. - - Function: heap-extract-max! heap + - Procedure: heap-extract-max! heap | Returns the item which is larger than all others according to the PRED<? argument to `make-heap'. If there are no items in HEAP, an error is signaled. - - The algorithm for priority queues was taken from `Introduction to -Algorithms' by T. Cormen, C. Leiserson, R. Rivest. 1989 MIT Press. - + | File: slib.info, Node: Queues, Next: Records, Prev: Priority Queues, Up: Data Structures Queues ------ - `(require 'queue)' +`(require 'queue)' A "queue" is a list where elements can be added to both the front and rear, and removed from the front (i.e., they are what are often called @@ -8688,30 +11605,32 @@ rear, and removed from the front (i.e., they are what are often called - Procedure: queue-push! q datum Adds DATUM to the front of queue Q. - - Procedure: enquque! q datum + - Procedure: enqueue! q datum Adds DATUM to the rear of queue Q. - All of the following functions raise an error if the queue Q is empty. - + - Procedure: dequeue! q | + - Procedure: queue-pop! q | + Both of these procedures remove and return the datum at the front | + of the queue. `queue-pop!' is used to suggest that the queue is | + being used like a stack. | + All of the following functions raise an error if the queue Q is empty. | + | + - Procedure: dequeue-all! q + Removes and returns (the list) of all contents of queue Q. + | - Function: queue-front q Returns the datum at the front of the queue Q. - Function: queue-rear q Returns the datum at the rear of the queue Q. - - - Prcoedure: queue-pop! q - - Procedure: dequeue! q - Both of these procedures remove and return the datum at the front - of the queue. `queue-pop!' is used to suggest that the queue is - being used like a stack. - + | File: slib.info, Node: Records, Prev: Queues, Up: Data Structures - | + Records ------- - `(require 'record)' +`(require 'record)' The Record package provides a facility for user to define their own record data types. @@ -8779,27 +11698,30 @@ supported. File: slib.info, Node: Sorting and Searching, Next: Procedures, Prev: Data Structures, Up: Other Packages - | -Sorting and Searching | -===================== | + +Sorting and Searching +===================== * Menu: * Common List Functions:: 'common-list-functions -* Tree Operations:: 'tree | +* Tree Operations:: 'tree * Chapter Ordering:: 'chapter-order * Sorting:: 'sort -* Topological Sort:: Keep your socks on. | +* Topological Sort:: Keep your socks on. +* Hashing:: 'hash +* Space-Filling Curves:: 'hilbert and 'sierpinski +* Soundex:: Dimension Reduction of Last Names * String Search:: Also Search from a Port. -* Sequence Comparison:: 'diff and longest-common-subsequence | +* Sequence Comparison:: 'diff and longest-common-subsequence File: slib.info, Node: Common List Functions, Next: Tree Operations, Prev: Sorting and Searching, Up: Sorting and Searching - | + Common List Functions --------------------- - `(require 'common-list-functions)' +`(require 'common-list-functions)' The procedures below follow the Common LISP equivalents apart from optional arguments in some cases. @@ -8818,8 +11740,8 @@ File: slib.info, Node: List construction, Next: Lists as sets, Prev: Common L List construction ................. - - Function: make-list k | - - Function: make-list k init | + - Function: make-list k + - Function: make-list k init `make-list' creates and returns a list of K elements. If INIT is included, all elements in the list are initialized to INIT. @@ -8829,10 +11751,11 @@ List construction (make-list 5 'foo) => (foo foo foo foo foo) - - Function: list* obj1 obj2 ... | + - Function: list* obj1 obj2 ... Works like `list' except that the cdr of the last pair is the last argument unless there is only one argument, when the result is just that argument. Sometimes called `cons*'. E.g.: + (list* 1) => 1 (list* 1 2 3) @@ -8871,7 +11794,7 @@ File: slib.info, Node: Lists as sets, Next: Lists as sequences, Prev: List co Lists as sets ............. - `eqv?' is used to test for membership by procedures which treat lists +`eqv?' is used to test for membership by procedures which treat lists as sets. - Function: adjoin e l @@ -8886,46 +11809,58 @@ as sets. => (foo bar baz bang) - Function: union l1 l2 - `union' returns the combination of L1 and L2. Duplicates between - L1 and L2 are culled. Duplicates within L1 or within L2 may or - may not be removed. + `union' returns a list of all elements that are in L1 or L2. + Duplicates between L1 and L2 are culled. Duplicates within L1 or + within L2 may or may not be removed. Example: (union '(1 2 3 4) '(5 6 7 8)) - => (8 7 6 5 1 2 3 4) | - (union '(1 2 3 4) '(3 4 5 6)) - => (6 5 1 2 3 4) | + => (1 2 3 4 5 6 7 8) + (union '(0 1 2 3 4) '(3 4 5 6)) + => (5 6 0 1 2 3 4) - Function: intersection l1 l2 - `intersection' returns all elements that are in both L1 and L2. + `intersection' returns a list of all elements that are in both L1 + and L2. Example: (intersection '(1 2 3 4) '(3 4 5 6)) - => (3 4) | + => (3 4) (intersection '(1 2 3 4) '(5 6 7 8)) => () - Function: set-difference l1 l2 - `set-difference' returns all elements that are in L1 but not in L2. + `set-difference' returns a list of all elements that are in L1 but + not in L2. Example: (set-difference '(1 2 3 4) '(3 4 5 6)) - => (1 2) | + => (1 2) (set-difference '(1 2 3 4) '(1 2 3 4 5 6)) => () + - Function: subset? list1 list2 + Returns `#t' if every element of LIST1 is `eqv?' an element of + LIST2; otherwise returns `#f'. + + Example: + (subset? '(1 2 3 4) '(3 4 5 6)) + => #f + (subset? '(1 2 3 4) '(6 5 4 3 2 1 0)) + => #t + - Function: member-if pred lst - `member-if' returns LST if `(PRED ELEMENT)' is `#t' for any - ELEMENT in LST. Returns `#f' if PRED does not apply to any - ELEMENT in LST. + `member-if' returns the list headed by the first element of LST to + satisfy `(PRED ELEMENT)'. `Member-if' returns `#f' if PRED + returns `#f' for every ELEMENT in LST. Example: - (member-if vector? '(1 2 3 4)) + (member-if vector? '(a 2 b 4)) => #f - (member-if number? '(1 2 3 4)) - => (1 2 3 4) + (member-if number? '(a 2 b 4)) + => (2 b 4) - - Function: some pred lst1 lst2 ... | + - Function: some pred lst1 lst2 ... PRED is a boolean function of as many arguments as there are list arguments to `some' i.e., LST plus any optional arguments. PRED is applied to successive elements of the list arguments in order. @@ -8940,10 +11875,10 @@ as sets. (some odd? '(2 4 6 8)) => #f - (some > '(2 3) '(1 4)) + (some > '(1 3) '(2 4)) => #f - - Function: every pred lst1 lst2 ... | + - Function: every pred lst1 lst2 ... `every' is analogous to `some' except it returns `#t' if every application of PRED is `#t' and `#f' otherwise. @@ -8957,11 +11892,11 @@ as sets. (every > '(2 3) '(1 4)) => #f - - Function: notany pred lst1 ... | + - Function: notany pred lst1 ... `notany' is analogous to `some' but returns `#t' if no application of PRED returns `#t' or `#f' as soon as any one does. - - Function: notevery pred lst1 ... | + - Function: notevery pred lst1 ... `notevery' is analogous to `some' but returns `#t' as soon as an application of PRED returns `#f', and `#f' otherwise. @@ -9013,10 +11948,10 @@ as sets. Example: (remove 1 '(1 2 1 3 1 4 1 5)) - => (2 3 4 5) | + => (2 3 4 5) (remove 'foo '(bar baz bang)) - => (bar baz bang) | + => (bar baz bang) - Function: remove-if pred lst `remove-if' removes all ELEMENTs from LST where `(PRED ELEMENT)' @@ -9027,7 +11962,7 @@ as sets. => () (remove-if even? '(1 2 3 4 5 6 7 8)) - => (1 3 5 7) | + => (1 3 5 7) - Function: remove-if-not pred lst `remove-if-not' removes all ELEMENTs from LST for which `(PRED @@ -9037,7 +11972,7 @@ as sets. (remove-if-not number? '(foo bar baz)) => () (remove-if-not odd? '(1 2 3 4 5 6 7 8)) - => (1 3 5 7) | + => (1 3 5 7) - Function: has-duplicates? lst returns `#t' if 2 members of LST are `equal?', `#f' otherwise. @@ -9057,10 +11992,10 @@ as sets. Example: (remove-duplicates '(1 2 3 4)) - => (1 2 3 4) | + => (1 2 3 4) (remove-duplicates '(2 4 3 4)) - => (2 4 3) | + => (2 4 3) File: slib.info, Node: Lists as sequences, Next: Destructive list operations, Prev: Lists as sets, Up: Common List Functions @@ -9230,7 +12165,7 @@ File: slib.info, Node: Destructive list operations, Next: Non-List functions, Destructive list operations ........................... - These procedures may mutate the list they operate on, but any such +These procedures may mutate the list they operate on, but any such mutation is undefined. - Procedure: nconc args @@ -9244,8 +12179,8 @@ mutation is undefined. (define (subsets set) (if (null? set) '(()) - (append (mapcar (lambda (sub) (cons (car set) sub)) - (subsets (cdr set))) + (append (map (lambda (sub) (cons (car set) sub)) + (subsets (cdr set))) (subsets (cdr set))))) But that does way more consing than you need. Instead, you could replace the `append' with `nconc', since you don't have any need @@ -9275,6 +12210,7 @@ mutation is undefined. Some people have been confused about how to use `nreverse', thinking that it doesn't return a value. It needs to be pointed out that + (set! lst (nreverse lst)) is the proper usage, not @@ -9287,21 +12223,22 @@ mutation is undefined. Destructive versions of `remove' `remove-if', and `remove-if-not'. Example: - (define lst '(foo bar baz bang)) + (define lst (list 'foo 'bar 'baz 'bang)) (delete 'foo lst) => (bar baz bang) lst => (foo bar baz bang) - (define lst '(1 2 3 4 5 6 7 8 9)) + (define lst (list 1 2 3 4 5 6 7 8 9)) (delete-if odd? lst) => (2 4 6 8) lst => (1 2 4 6 8) Some people have been confused about how to use `delete', - `delete-if', and `delete-if', thinking that they dont' return a + `delete-if', and `delete-if', thinking that they don't return a value. It needs to be pointed out that + (set! lst (delete el lst)) is the proper usage, not @@ -9314,7 +12251,7 @@ File: slib.info, Node: Non-List functions, Prev: Destructive list operations, Non-List functions .................. - - Function: and? arg1 ... | + - Function: and? arg1 ... `and?' checks to see if all its arguments are true. If they are, `and?' returns `#t', otherwise, `#f'. (In contrast to `and', this is a function, so all arguments are always evaluated and in an @@ -9326,7 +12263,7 @@ Non-List functions (and #f 1 2) => #f - - Function: or? arg1 ... | + - Function: or? arg1 ... `or?' checks to see if any of its arguments are true. If any is true, `or?' returns `#t', and `#f' otherwise. (To `or' as `and?' is to `and'.) @@ -9349,26 +12286,26 @@ Non-List functions File: slib.info, Node: Tree Operations, Next: Chapter Ordering, Prev: Common List Functions, Up: Sorting and Searching - | + Tree operations --------------- - `(require 'tree)' +`(require 'tree)' These are operations that treat lists a representations of trees. - - Function: subst new old tree - - Function: subst new old tree equ? | + - Function: subst new old tree | - Function: substq new old tree - Function: substv new old tree + - Function: subst new old tree equ? | `subst' makes a copy of TREE, substituting NEW for every subtree or leaf of TREE which is `equal?' to OLD and returns a modified tree. The original TREE is unchanged, but may share parts with the result. `substq' and `substv' are similar, but test against OLD using - `eq?' and `eqv?' respectively. If `subst' is called with a fourth | - argument, EQU? is the equality predicate. | + `eq?' and `eqv?' respectively. If `subst' is called with a fourth + argument, EQU? is the equality predicate. Examples: (substq 'tempest 'hurricane '(shakespeare wrote (the hurricane))) @@ -9393,11 +12330,11 @@ Tree operations File: slib.info, Node: Chapter Ordering, Next: Sorting, Prev: Tree Operations, Up: Sorting and Searching - | + Chapter Ordering ---------------- - `(require 'chapter-order)' +`(require 'chapter-order)' The `chap:' functions deal with strings which are ordered like chapter numbers (or letters) in a book. Each section of the string @@ -9432,11 +12369,11 @@ like case. File: slib.info, Node: Sorting, Next: Topological Sort, Prev: Chapter Ordering, Up: Sorting and Searching - | + Sorting ------- - `(require 'sort)' +`(require 'sort)' Many Scheme systems provide some kind of sorting functions. They do not, however, always provide the _same_ sorting functions, and those @@ -9526,8 +12463,8 @@ as saying when `x' must _not_ precede `y'. ...' for which `(less? y x)'). Returns `#f' when the sequence contains at least one out-of-order - pair. It is an error if the sequence is neither a list nor a - vector. + pair. It is an error if the sequence is not a list, vector, or | + string. | - Function: merge list1 list2 less? This merges two lists, producing a completely new list as result. @@ -9550,18 +12487,19 @@ as saying when `x' must _not_ precede `y'. done per iteration. (For example, we only have one `null?' test per iteration.) + - Function: sort sequence less? - Accepts either a list or a vector, and returns a new sequence - which is sorted. The new sequence is the same type as the input. - Always `(sorted? (sort sequence less?) less?)'. The original - sequence is not altered in any way. The new sequence shares its - _elements_ with the old one; no elements are copied. + Accepts either a list, vector, or string; and returns a new | + sequence which is sorted. The new sequence is the same type as | + the input. Always `(sorted? (sort sequence less?) less?)'. The | + original sequence is not altered in any way. The new sequence | + shares its _elements_ with the old one; no elements are copied. | - Procedure: sort! sequence less? Returns its sorted result in the original boxes. If the original sequence is a list, no new storage is allocated at all. If the - original sequence is a vector, the sorted elements are put back in - the same vector. + original sequence is a vector or string, the sorted elements are | + put back in the same vector or string. | Some people have been confused about how to use `sort!', thinking that it doesn't return a value. It needs to be pointed out that @@ -9572,6 +12510,7 @@ as saying when `x' must _not_ precede `y'. Note that these functions do _not_ accept a CL-style `:key' argument. A simple device for obtaining the same expressiveness is to define + (define (keyed less? key) (lambda (x y) (less? (key x) (key y)))) @@ -9584,12 +12523,12 @@ in Common LISP, just write in Scheme. -File: slib.info, Node: Topological Sort, Next: String Search, Prev: Sorting, Up: Sorting and Searching - | +File: slib.info, Node: Topological Sort, Next: Hashing, Prev: Sorting, Up: Sorting and Searching + Topological Sort ---------------- - `(require 'topological-sort)' or `(require 'tsort)' +`(require 'topological-sort)' or `(require 'tsort)' The algorithm is inspired by Cormen, Leiserson and Rivest (1990) `Introduction to Algorithms', chapter 23. @@ -9614,6 +12553,7 @@ The algorithm is inspired by Cormen, Leiserson and Rivest (1990) Time complexity: O (|V| + |E|) Example (from Cormen): + Prof. Bumstead topologically sorts his clothing when getting dressed. The first argument to `tsort' describes which garments he needs to put on before others. (For example, @@ -9634,12 +12574,181 @@ The algorithm is inspired by Cormen, Leiserson and Rivest (1990) (socks undershorts pants shoes watch shirt belt tie jacket) -File: slib.info, Node: String Search, Next: Sequence Comparison, Prev: Topological Sort, Up: Sorting and Searching - | +File: slib.info, Node: Hashing, Next: Space-Filling Curves, Prev: Topological Sort, Up: Sorting and Searching + +Hashing +------- + +`(require 'hash)' + + These hashing functions are for use in quickly classifying objects. +Hash tables use these functions. + + - Function: hashq obj k + - Function: hashv obj k + - Function: hash obj k + Returns an exact non-negative integer less than K. For each + non-negative integer less than K there are arguments OBJ for which + the hashing functions applied to OBJ and K returns that integer. + + For `hashq', `(eq? obj1 obj2)' implies `(= (hashq obj1 k) (hashq + obj2))'. + + For `hashv', `(eqv? obj1 obj2)' implies `(= (hashv obj1 k) (hashv + obj2))'. + + For `hash', `(equal? obj1 obj2)' implies `(= (hash obj1 k) (hash + obj2))'. + + `hash', `hashv', and `hashq' return in time bounded by a constant. + Notice that items having the same `hash' implies the items have + the same `hashv' implies the items have the same `hashq'. + + +File: slib.info, Node: Space-Filling Curves, Next: Soundex, Prev: Hashing, Up: Sorting and Searching + +Space-Filling Curves +-------------------- + +* Menu: + +* Peano-Hilbert Space-Filling Curve:: +* Sierpinski Curve:: + + +File: slib.info, Node: Peano-Hilbert Space-Filling Curve, Next: Sierpinski Curve, Prev: Space-Filling Curves, Up: Space-Filling Curves + +Peano-Hilbert Space-Filling Curve +................................. + +`(require 'hilbert-fill)' + +The "Peano-Hilbert Space-Filling Curve" is a one-to-one mapping between +a unit line segment and an N-dimensional unit cube. + +The integer procedures map the non-negative integers to an arbitrarily +large N-dimensional cube with its corner at the origin and all +coordinates are non-negative. + +For any exact nonnegative integers SCALAR and RANK, + + (= SCALAR (hilbert-coordinates->integer + (integer->hilbert-coordinates SCALAR RANK))) + => #t + + - Function: integer->hilbert-coordinates scalar rank + Returns a list of RANK integer coordinates corresponding to exact + non-negative integer SCALAR. The lists returned by + `integer->hilbert-coordinates' for SCALAR arguments 0 and 1 will + differ in the first element. + + - Function: hilbert-coordinates->integer coords + Returns an exact non-negative integer corresponding to COORDS, a + list of non-negative integer coordinates. + + +File: slib.info, Node: Sierpinski Curve, Prev: Peano-Hilbert Space-Filling Curve, Up: Space-Filling Curves + +Sierpinski Curve +................ + +`(require 'sierpinski)' + + - Function: make-sierpinski-indexer max-coordinate + Returns a procedure (eg hash-function) of 2 numeric arguments which + preserves _nearness_ in its mapping from NxN to N. + + MAX-COORDINATE is the maximum coordinate (a positive integer) of a + population of points. The returned procedures is a function that + takes the x and y coordinates of a point, (non-negative integers) + and returns an integer corresponding to the relative position of + that point along a Sierpinski curve. (You can think of this as + computing a (pseudo-) inverse of the Sierpinski spacefilling + curve.) + + Example use: Make an indexer (hash-function) for integer points + lying in square of integer grid points [0,99]x[0,99]: + (define space-key (make-sierpinski-indexer 100)) + Now let's compute the index of some points: + (space-key 24 78) => 9206 + (space-key 23 80) => 9172 + + Note that locations (24, 78) and (23, 80) are near in index and + therefore, because the Sierpinski spacefilling curve is + continuous, we know they must also be near in the plane. Nearness + in the plane does not, however, necessarily correspond to nearness + in index, although it _tends_ to be so. + + Example applications: + * Sort points by Sierpinski index to get heuristic solution to + _travelling salesman problem_. For details of performance, + see L. Platzman and J. Bartholdi, "Spacefilling curves and the + Euclidean travelling salesman problem", JACM 36(4):719-737 + (October 1989) and references therein. + + * Use Sierpinski index as key by which to store 2-dimensional + data in a 1-dimensional data structure (such as a table). + Then locations that are near each other in 2-d space will + tend to be near each other in 1-d data structure; and + locations that are near in 1-d data structure will be near in + 2-d space. This can significantly speed retrieval from + secondary storage because contiguous regions in the plane + will tend to correspond to contiguous regions in secondary + storage. (This is a standard technique for managing CAD/CAM + or geographic data.) + + + +File: slib.info, Node: Soundex, Next: String Search, Prev: Space-Filling Curves, Up: Sorting and Searching + +Soundex +------- + +`(require 'soundex)' + + - Function: soundex name + Computes the _soundex_ hash of NAME. Returns a string of an + initial letter and up to three digits between 0 and 6. Soundex + supposedly has the property that names that sound similar in normal + English pronunciation tend to map to the same key. + + Soundex was a classic algorithm used for manual filing of personal + records before the advent of computers. It performs adequately for + English names but has trouble with other languages. + + See Knuth, Vol. 3 `Sorting and searching', pp 391-2 + + To manage unusual inputs, `soundex' omits all non-alphabetic + characters. Consequently, in this implementation: + + (soundex <string of blanks>) => "" + (soundex "") => "" + + Examples from Knuth: + + (map soundex '("Euler" "Gauss" "Hilbert" "Knuth" + "Lloyd" "Lukasiewicz")) + => ("E460" "G200" "H416" "K530" "L300" "L222") + + (map soundex '("Ellery" "Ghosh" "Heilbronn" "Kant" + "Ladd" "Lissajous")) + => ("E460" "G200" "H416" "K530" "L300" "L222") + + Some cases in which the algorithm fails (Knuth): + + (map soundex '("Rogers" "Rodgers")) => ("R262" "R326") + + (map soundex '("Sinclair" "St. Clair")) => ("S524" "S324") + + (map soundex '("Tchebysheff" "Chebyshev")) => ("T212" "C121") + + +File: slib.info, Node: String Search, Next: Sequence Comparison, Prev: Soundex, Up: Sorting and Searching + String Search ------------- - `(require 'string-search)' +`(require 'string-search)' - Procedure: string-index string char - Procedure: string-index-ci string char @@ -9651,8 +12760,8 @@ String Search Returns the index of the last occurence of CHAR within STRING, or `#f' if the STRING does not contain a character CHAR. - - procedure: substring? pattern string - - procedure: substring-ci? pattern string + - Procedure: substring? pattern string | + - Procedure: substring-ci? pattern string | Searches STRING to see if some substring of STRING is equal to PATTERN. `substring?' returns the index of the first character of the first substring of STRING that is equal to PATTERN; or `#f' if @@ -9690,172 +12799,206 @@ String Search - Function: string-subst txt old1 new1 ... Returns a copy of string TXT with all occurrences of string OLD1 - in TXT replaced with NEW1, OLD2 replaced with NEW2 .... + in TXT replaced with NEW1; then OLD2 replaced with NEW2 .... + Matches are found from the left. Matches do not overlap. + + - Function: count-newlines str | + Returns the number of `#\newline' characters in string STR. File: slib.info, Node: Sequence Comparison, Prev: String Search, Up: Sorting and Searching - | -Sequence Comparison | -------------------- | - | - `(require 'diff)' | - | -This package implements the algorithm: | - | - S. Wu, E. Myers, U. Manber, and W. Miller, | - "An O(NP) Sequence Comparison Algorithm," | - Information Processing Letters 35, 6 (1990), 317-323. | - <http://www.cs.arizona.edu/people/gene/vita.html> | - | -If the items being sequenced are text lines, then the computed | -edit-list is equivalent to the output of the "diff" utility program. | -If the items being sequenced are words, then it is like the lesser | -known "spiff" program. | - | -The values returned by `diff:edit-length' can be used to gauge the | -degree of match between two sequences. | - | -I believe that this algorithm is currently the fastest for these tasks, | -but genome sequencing applications fuel extensive research in this area. | - | - - Function: diff:longest-common-subsequence array1 array2 =? | - - Function: diff:longest-common-subsequence array1 array2 | - ARRAY1 and ARRAY2 are one-dimensional arrays. The procedure =? is | - used to compare sequence tokens for equality. =? defaults to | - `eqv?'. `diff:longest-common-subsequence' returns a | - one-dimensional array of length `(quotient (- (+ len1 len2) | - (fp:edit-length ARRAY1 ARRAY2)) 2)' holding the longest sequence | - common to both ARRAYs. | - | - - Function: diff:edits array1 array2 =? | - - Function: diff:edits array1 array2 | - ARRAY1 and ARRAY2 are one-dimensional arrays. The procedure =? is | - used to compare sequence tokens for equality. =? defaults to | - `eqv?'. `diff:edits' returns a list of length `(fp:edit-length | - ARRAY1 ARRAY2)' composed of a shortest sequence of edits | - transformaing ARRAY1 to ARRAY2. | - | - Each edit is a list of an integer and a symbol: | - (J insert) | - Inserts `(array-ref ARRAY1 J)' into the sequence. | - | - (K delete) | - Deletes `(array-ref ARRAY2 K)' from the sequence. | - | - - Function: diff:edit-length array1 array2 =? | - - Function: diff:edit-length array1 array2 | - ARRAY1 and ARRAY2 are one-dimensional arrays. The procedure =? is | - used to compare sequence tokens for equality. =? defaults to | - `eqv?'. `diff:edit-length' returns the length of the shortest | - sequence of edits transformaing ARRAY1 to ARRAY2. | - | - (diff:longest-common-subsequence '#(f g h i e j c k l m) | - '#(f g e h i j k p q r l m)) | - => #(f g h i j k l m) | - | - (diff:edit-length '#(f g h i e j c k l m) | - '#(f g e h i j k p q r l m)) | - => 6 | - | - (pretty-print (diff:edits '#(f g h i e j c k l m) | - '#(f g e h i j k p q r l m))) | - -| | - ((3 insert) ; e | - (4 delete) ; c | - (6 delete) ; h | - (7 insert) ; p | - (8 insert) ; q | - (9 insert)) ; r | - | + +Sequence Comparison +------------------- + +`(require 'diff)' + +`diff:edit-length' implements the algorithm: + + S. Wu, E. Myers, U. Manber, and W. Miller, + "An O(NP) Sequence Comparison Algorithm," + Information Processing Letters 35, 6 (1990), 317-323. + <http://www.cs.arizona.edu/people/gene/vita.html> + +The values returned by `diff:edit-length' can be used to gauge the +degree of match between two sequences. + +Surprisingly, "An O(NP) Sequence Comparison Algorithm" does not derive +the edit sequence; only the sequence length. Developing this | +linear-space sub-quadratic-time algorithm for computing the edit | +sequence required hundreds of hours of work. I have submitted a paper | +describing the algorithm to the Journal of Computational Biology. | + +If the items being sequenced are text lines, then the computed +edit-list is equivalent to the output of the "diff" utility program. +If the items being sequenced are words, then it is like the lesser +known "spiff" program. + + - Function: diff:longest-common-subsequence array1 array2 =? p-lim + - Function: diff:longest-common-subsequence array1 array2 =? + ARRAY1 and ARRAY2 are one-dimensional arrays. The procedure =? is + used to compare sequence tokens for equality. + + The non-negative integer P-LIM, if provided, is maximum number of + deletions of the shorter sequence to allow. + `diff:longest-common-subsequence' will return `#f' if more + deletions would be necessary. + + `diff:longest-common-subsequence' returns a one-dimensional array + of length `(quotient (- (+ len1 len2) (diff:edit-length ARRAY1 + ARRAY2)) 2)' holding the longest sequence common to both ARRAYs. + + - Function: diff:edits array1 array2 =? p-lim + - Function: diff:edits array1 array2 =? + ARRAY1 and ARRAY2 are one-dimensional arrays. The procedure =? is + used to compare sequence tokens for equality. + + The non-negative integer P-LIM, if provided, is maximum number of + deletions of the shorter sequence to allow. `diff:edits' will + return `#f' if more deletions would be necessary. + + `diff:edits' returns a vector of length `(diff:edit-length ARRAY1 + ARRAY2)' composed of a shortest sequence of edits transformaing + ARRAY1 to ARRAY2. + + Each edit is an integer: + K > 0 + Inserts `(array-ref ARRAY1 (+ -1 J))' into the sequence. + + K < 0 + Deletes `(array-ref ARRAY2 (- -1 K))' from the sequence. + + - Function: diff:edit-length array1 array2 =? p-lim + - Function: diff:edit-length array1 array2 =? + ARRAY1 and ARRAY2 are one-dimensional arrays. The procedure =? is + used to compare sequence tokens for equality. + + The non-negative integer P-LIM, if provided, is maximum number of + deletions of the shorter sequence to allow. `diff:edit-length' + will return `#f' if more deletions would be necessary. + + `diff:edit-length' returns the length of the shortest sequence of + edits transformaing ARRAY1 to ARRAY2. + + (diff:longest-common-subsequence "fghiejcklm" "fgehijkpqrlm" eqv?) + => "fghijklm" + + (diff:edit-length "fghiejcklm" "fgehijkpqrlm" eqv?) + => 6 + + (diff:edits "fghiejcklm" "fgehijkpqrlm" eqv?) + => #As32(3 -5 -7 8 9 10) + ; e c h p q r + File: slib.info, Node: Procedures, Next: Standards Support, Prev: Sorting and Searching, Up: Other Packages - | -Procedures | -========== | - | - Anything that doesn't fall neatly into any of the other categories | -winds up here. | - | -* Menu: | - | -* Type Coercion:: 'coerce | -* String-Case:: 'string-case | -* String Ports:: 'string-port | -* Line I/O:: 'line-i/o | -* Multi-Processing:: 'process | -* Metric Units:: Portable manifest types for numeric values. | - | + +Procedures +========== + +Anything that doesn't fall neatly into any of the other categories winds +up here. + +* Menu: + +* Type Coercion:: 'coerce +* String-Case:: 'string-case +* String Ports:: 'string-port +* Line I/O:: 'line-i/o +* Multi-Processing:: 'process +* Metric Units:: Portable manifest types for numeric values. + File: slib.info, Node: Type Coercion, Next: String-Case, Prev: Procedures, Up: Procedures - | -Type Coercion | -------------- | - | - `(require 'coerce)' | - | - - Function: type-of obj | - Returns a symbol name for the type of OBJ. | - | - - Function: coerce obj result-type | - Converts and returns OBJ of type `char', `number', `string', | - `symbol', `list', or `vector' to RESULT-TYPE (which must be one of | - these symbols). | - | + +Type Coercion +------------- + +`(require 'coerce)' + + - Function: type-of obj + Returns a symbol name for the type of OBJ. + + - Function: coerce obj result-type + Converts and returns OBJ of type `char', `number', `string', + `symbol', `list', or `vector' to RESULT-TYPE (which must be one of + these symbols). + File: slib.info, Node: String-Case, Next: String Ports, Prev: Type Coercion, Up: Procedures - | -String-Case | ------------ | - | - `(require 'string-case)' | - | - - Procedure: string-upcase str | - - Procedure: string-downcase str | - - Procedure: string-capitalize str | - The obvious string conversion routines. These are non-destructive. | - | - - Function: string-upcase! str | - - Function: string-downcase! str | - - Function: string-captialize! str | - The destructive versions of the functions above. | - | - - Function: string-ci->symbol str | - Converts string STR to a symbol having the same case as if the | - symbol had been `read'. | - | - - Function: symbol-append obj1 ... | - Converts OBJ1 ... to strings, appends them, and converts to a | - symbol which is returned. Strings and numbers are converted to | - read's symbol case; the case of symbol characters is not changed. | - #f is converted to the empty string (symbol). | - | + +String-Case +----------- + +`(require 'string-case)' + + - Procedure: string-upcase str + - Procedure: string-downcase str + - Procedure: string-capitalize str + The obvious string conversion routines. These are non-destructive. + + - Function: string-upcase! str + - Function: string-downcase! str + - Function: string-capitalize! str | + The destructive versions of the functions above. + + - Function: string-ci->symbol str + Converts string STR to a symbol having the same case as if the + symbol had been `read'. + + - Function: symbol-append obj1 ... + Converts OBJ1 ... to strings, appends them, and converts to a + symbol which is returned. Strings and numbers are converted to + read's symbol case; the case of symbol characters is not changed. + #f is converted to the empty string (symbol). + + - Function: StudlyCapsExpand str delimiter + - Function: StudlyCapsExpand str + DELIMITER must be a string or character. If absent, DELIMITER + defaults to `-'. `StudlyCapsExpand' returns a copy of STR where + DELIMITER is inserted between each lower-case character + immediately followed by an upper-case character; and between two + upper-case characters immediately followed by a lower-case + character. + + (StudlyCapsExpand "aX" " ") => "a X" + (StudlyCapsExpand "aX" "..") => "a..X" + (StudlyCapsExpand "AX") => "AX" + (StudlyCapsExpand "Ax") => "Ax" + (StudlyCapsExpand "AXLE") => "AXLE" + (StudlyCapsExpand "aAXACz") => "a-AXA-Cz" + (StudlyCapsExpand "AaXACz") => "Aa-XA-Cz" + (StudlyCapsExpand "AAaXACz") => "A-Aa-XA-Cz" + (StudlyCapsExpand "AAaXAC") => "A-Aa-XAC" + + File: slib.info, Node: String Ports, Next: Line I/O, Prev: String-Case, Up: Procedures - | -String Ports | ------------- | - | - `(require 'string-port)' | - | - - Procedure: call-with-output-string proc | - PROC must be a procedure of one argument. This procedure calls | - PROC with one argument: a (newly created) output port. When the | - function returns, the string composed of the characters written | - into the port is returned. | - | - - Procedure: call-with-input-string string proc | - PROC must be a procedure of one argument. This procedure calls | - PROC with one argument: an (newly created) input port from which | - STRING's contents may be read. When PROC returns, the port is | - closed and the value yielded by the procedure PROC is returned. | - | + +String Ports +------------ + +`(require 'string-port)' + + - Procedure: call-with-output-string proc + PROC must be a procedure of one argument. This procedure calls + PROC with one argument: a (newly created) output port. When the + function returns, the string composed of the characters written + into the port is returned. + + - Procedure: call-with-input-string string proc + PROC must be a procedure of one argument. This procedure calls + PROC with one argument: an (newly created) input port from which + STRING's contents may be read. When PROC returns, the port is + closed and the value yielded by the procedure PROC is returned. + File: slib.info, Node: Line I/O, Next: Multi-Processing, Prev: String Ports, Up: Procedures - | + Line I/O -------- - `(require 'line-i/o)' +`(require 'line-i/o)' - Function: read-line - Function: read-line port @@ -9866,8 +13009,8 @@ Line I/O which case it defaults to the value returned by `current-input-port'. - - Function: read-line! string - - Function: read-line! string port + - Procedure: read-line! string | + - Procedure: read-line! string port | Fills STRING with characters up to, but not including a newline or end of file, updating the PORT to point to the last character read or following the newline if it was read. If no characters are @@ -9883,11 +13026,13 @@ Line I/O an unspecified value. The PORT argument may be omitted, in which case it defaults to the value returned by `current-input-port'. - - Function: display-file path - - Function: display-file path port - Displays the contents of the file named by PATH to PORT. The PORT - argument may be ommited, in which case it defaults to the value - returned by `current-output-port'. + - Function: system->line command tmp | + - Function: system->line command | + COMMAND must be a string. The string TMP, if supplied, is a path | + to use as a temporary file. `system->line' calls `system' with | + COMMAND as argument, redirecting stdout to file TMP. | + `system->line' returns a string containing the first line of | + output from TMP. | File: slib.info, Node: Multi-Processing, Next: Metric Units, Prev: Line I/O, Up: Procedures @@ -9895,7 +13040,7 @@ File: slib.info, Node: Multi-Processing, Next: Metric Units, Prev: Line I/O, Multi-Processing ---------------- - `(require 'process)' +`(require 'process)' This module implements asynchronous (non-polled) time-sliced multi-processing in the SCM Scheme implementation using procedures @@ -9923,7 +13068,7 @@ File: slib.info, Node: Metric Units, Prev: Multi-Processing, Up: Procedures Metric Units ------------ - `(require 'metric-units)' +`(require 'metric-units)' <http://swissnet.ai.mit.edu/~jaffer/MIXF.html> @@ -10006,7 +13151,7 @@ SI Prefixes Binary Prefixes ............... - These binary prefixes are valid only with the units B (byte) and bit. +These binary prefixes are valid only with the units B (byte) and bit. However, decimal prefixes can also be used with bit; and decimal multiple (not submultiple) prefixes can also be used with B (byte). @@ -10119,6 +13264,7 @@ Standards Support * Menu: +* RnRS:: Revised Reports on Scheme * With-File:: 'with-file * Transcripts:: 'transcript * Rev2 Procedures:: 'rev2-procedures @@ -10126,19 +13272,52 @@ Standards Support * Multi-argument / and -:: 'multiarg/and- * Multi-argument Apply:: 'multiarg-apply * Rationalize:: 'rationalize -* Promises:: 'promise +* Promises:: 'delay | * Dynamic-Wind:: 'dynamic-wind * Eval:: 'eval * Values:: 'values -* SRFI:: 'http://srfi.schemers.org/srfi-0/srfi-0.html | +* SRFI:: 'http://srfi.schemers.org/srfi-0/srfi-0.html -File: slib.info, Node: With-File, Next: Transcripts, Prev: Standards Support, Up: Standards Support +File: slib.info, Node: RnRS, Next: With-File, Prev: Standards Support, Up: Standards Support + +RnRS +---- + +The `r2rs', `r3rs', `r4rs', and `r5rs' features attempt to provide +procedures and macros to bring a Scheme implementation to the desired +version of Scheme. + + - Feature: r2rs + Requires features implementing procedures and optional procedures + specified by `Revised^2 Report on the Algorithmic Language Scheme'; + namely `rev3-procedures' and `rev2-procedures'. + + - Feature: r3rs + Requires features implementing procedures and optional procedures + specified by `Revised^3 Report on the Algorithmic Language Scheme'; + namely `rev3-procedures'. + + _Note:_ SLIB already mandates the `r3rs' procedures which can be + portably implemented in `r4rs' implementations. + + - Feature: r4rs + Requires features implementing procedures and optional procedures + specified by `Revised^4 Report on the Algorithmic Language Scheme'; + namely `rev4-optional-procedures'. + + - Feature: r5rs + Requires features implementing procedures and optional procedures + specified by `Revised^5 Report on the Algorithmic Language Scheme'; + namely `values', `macro', and `eval'. + + +File: slib.info, Node: With-File, Next: Transcripts, Prev: RnRS, Up: Standards Support With-File --------- - `(require 'with-file)' +`(require 'with-file)' - Function: with-input-from-file file thunk - Function: with-output-to-file file thunk @@ -10150,7 +13329,7 @@ File: slib.info, Node: Transcripts, Next: Rev2 Procedures, Prev: With-File, Transcripts ----------- - `(require 'transcript)' +`(require 'transcript)' - Function: transcript-on filename - Function: transcript-off filename @@ -10163,11 +13342,11 @@ File: slib.info, Node: Rev2 Procedures, Next: Rev4 Optional Procedures, Prev: Rev2 Procedures --------------- - `(require 'rev2-procedures)' +`(require 'rev2-procedures)' The procedures below were specified in the `Revised^2 Report on Scheme'. *N.B.*: The symbols `1+' and `-1+' are not `R4RS' syntax. -Scheme->C, for instance, barfs on this module. +Scheme->C, for instance, chokes on this module. - Procedure: substring-move-left! string1 start1 end1 string2 start2 - Procedure: substring-move-right! string1 start1 end1 string2 start2 @@ -10192,7 +13371,7 @@ Scheme->C, for instance, barfs on this module. - Function: string-null? str == `(= 0 (string-length STR))' - - Procedure: append! pair1 ... | + - Procedure: append! pair1 ... Destructively appends its arguments. Equivalent to `nconc'. - Function: 1+ n @@ -10215,7 +13394,7 @@ File: slib.info, Node: Rev4 Optional Procedures, Next: Multi-argument / and -, Rev4 Optional Procedures ------------------------ - `(require 'rev4-optional-procedures)' +`(require 'rev4-optional-procedures)' For the specification of these optional procedures, *Note Standard procedures: (r4rs)Standard procedures. @@ -10242,21 +13421,14 @@ File: slib.info, Node: Multi-argument / and -, Next: Multi-argument Apply, Pr Multi-argument / and - ---------------------- - `(require 'mutliarg/and-)' +`(require 'multiarg/and-)' For the specification of these optional forms, *Note Numerical -operations: (r4rs)Numerical operations. The `two-arg:'* forms are only -defined if the implementation does not support the many-argument forms. - - - Function: two-arg:/ n1 n2 - The original two-argument version of `/'. - - - Function: / dividend divisor1 ... | +operations: (r4rs)Numerical operations. | - - Function: two-arg:- n1 n2 - The original two-argument version of `-'. - - - Function: - minuend subtrahend1 ... | + - Function: / dividend divisor1 ... + | + - Function: - minuend subtrahend1 ... File: slib.info, Node: Multi-argument Apply, Next: Rationalize, Prev: Multi-argument / and -, Up: Standards Support @@ -10264,16 +13436,12 @@ File: slib.info, Node: Multi-argument Apply, Next: Rationalize, Prev: Multi-a Multi-argument Apply -------------------- - `(require 'multiarg-apply)' +`(require 'multiarg-apply)' For the specification of this optional form, *Note Control features: (r4rs)Control features. - - - Function: two-arg:apply proc l - The implementation's native `apply'. Only defined for - implementations which don't support the many-argument version. - - - Function: apply proc arg1 ... | + | + - Function: apply proc arg1 ... File: slib.info, Node: Rationalize, Next: Promises, Prev: Multi-argument Apply, Up: Standards Support @@ -10281,13 +13449,9 @@ File: slib.info, Node: Rationalize, Next: Promises, Prev: Multi-argument Appl Rationalize ----------- - `(require 'rationalize)' - - The procedure "rationalize" is interesting because most programming -languages do not provide anything analogous to it. Thanks to Alan -Bawden for contributing this algorithm. +`(require 'rationalize)' - - Function: rationalize x y + - Function: rationalize x e | Computes the correct result for exact arguments (provided the implementation supports exact rational numbers of unlimited precision); and produces a reasonable answer for inexact arguments @@ -10297,9 +13461,9 @@ Bawden for contributing this algorithm. (non-integer) rational numbers. The following procedures return a list of the numerator and denominator. - - Function: find-ratio x y + - Function: find-ratio x e | `find-ratio' returns the list of the _simplest_ numerator and - denominator whose quotient differs from X by no more than Y. + denominator whose quotient differs from X by no more than E. | (find-ratio 3/97 .0001) => (3 97) (find-ratio 3/97 .001) => (1 32) @@ -10317,14 +13481,21 @@ File: slib.info, Node: Promises, Next: Dynamic-Wind, Prev: Rationalize, Up: Promises -------- - `(require 'promise)' +`(require 'promise)' - Function: make-promise proc - Change occurrences of `(delay EXPRESSION)' to `(make-promise (lambda -() EXPRESSION))' and `(define force promise:force)' to implement -promises if your implementation doesn't support them (*note Control -features: (r4rs)Control features.). + - Function: force promise | + | + `(require 'delay)' provides `force' and `delay': | + | + - Macro: delay obj | + Change occurrences of `(delay EXPRESSION)' to | + | + (make-promise (lambda () EXPRESSION)) | + | + | + (*note Control features: (r4rs)Control features.). | File: slib.info, Node: Dynamic-Wind, Next: Eval, Prev: Promises, Up: Standards Support @@ -10332,7 +13503,7 @@ File: slib.info, Node: Dynamic-Wind, Next: Eval, Prev: Promises, Up: Standar Dynamic-Wind ------------ - `(require 'dynamic-wind)' +`(require 'dynamic-wind)' This facility is a generalization of Common LISP `unwind-protect', designed to take into account the fact that continuations produced by @@ -10362,7 +13533,7 @@ File: slib.info, Node: Eval, Next: Values, Prev: Dynamic-Wind, Up: Standards Eval ---- - `(require 'eval)' +`(require 'eval)' - Function: eval expression environment-specifier Evaluates EXPRESSION in the specified environment and returns its @@ -10441,11 +13612,11 @@ Here are some more `eval' examples: File: slib.info, Node: Values, Next: SRFI, Prev: Eval, Up: Standards Support - | + Values ------ - `(require 'values)' +`(require 'values)' - Function: values obj ... `values' takes any number of arguments, and passes (returns) them @@ -10465,178 +13636,260 @@ Values File: slib.info, Node: SRFI, Prev: Values, Up: Standards Support - | -SRFI | ----- | - | - `(require 'srfi)' | - | -Implements "Scheme Request For Implementation" (SRFI) as described at | -<http://srfi.schemers.org/> | - | -The Copyright terms of each SRFI states: | - "However, this document itself may not be modified in any way, ..." | - | -Therefore, the specification of SRFI constructs must not be quoted | -without including the complete SRFI document containing discussion and | -a sample implementation program. | - | - - Macro: cond-expand <clause1> <clause2> ... | - _Syntax:_ Each <clause> should be of the form | - | - (<feature> <expression1> ...) | - | - where <feature> is a boolean expression composed of symbols and | - `and', `or', and `not' of boolean expressions. The last <clause> | - may be an "else clause," which has the form | - | - (else <expression1> <expression2> ...). | - | - The first clause whose feature expression is satisfied is expanded. | - If no feature expression is satisfied and there is no else clause, | - an error is signaled. | - | - SLIB `cond-expand' is an extension of SRFI-0, | - <http://srfi.schemers.org/srfi-0/srfi-0.html>. | - | -* Menu: | - | -* SRFI-1:: list-processing | - | + +SRFI +---- + +`(require 'srfi)' + +Implements "Scheme Request For Implementation" (SRFI) as described at +<http://srfi.schemers.org/> + +The Copyright terms of each SRFI states: + + "However, this document itself may not be modified in any way, ..." + +Therefore, the specification of SRFI constructs must not be quoted +without including the complete SRFI document containing discussion and +a sample implementation program. + + - Macro: cond-expand <clause1> <clause2> ... + _Syntax:_ Each <clause> should be of the form + + (<feature> <expression1> ...) + + where <feature> is a boolean expression composed of symbols and + `and', `or', and `not' of boolean expressions. The last <clause> + may be an "else clause," which has the form + + (else <expression1> <expression2> ...). + + The first clause whose feature expression is satisfied is expanded. + If no feature expression is satisfied and there is no else clause, + an error is signaled. + + SLIB `cond-expand' is an extension of SRFI-0, + <http://srfi.schemers.org/srfi-0/srfi-0.html>. + +* Menu: + +* SRFI-1:: list-processing +* SRFI-2:: guarded LET* special form | +* SRFI-8:: Binding to multiple values | +* SRFI-9:: Defining Record Types | + -File: slib.info, Node: SRFI-1, Prev: SRFI, Up: SRFI - | -SRFI-1 | -...... | - | - `(require 'srfi-1)' | - | -Implements the "SRFI-1" "list-processing library" as described at | -<http://srfi.schemers.org/srfi-1/srfi-1.html> | +File: slib.info, Node: SRFI-1, Next: SRFI-2, Prev: SRFI, Up: SRFI | -Constructors | ------------- | - | - - Function: xcons d a | - `(define (xcons d a) (cons a d))'. | - | - - Function: list-tabulate len proc | - Returns a list of length LEN. Element I is `(PROC I)' for 0 <= I | - < LEN. | - | - - Function: cons* obj1 obj2 | - | - - Function: iota count start step | - - Function: iota count start | - - Function: iota count | - Returns a list of COUNT numbers: (START, START+STEP, ..., | - START+(COUNT-1)*STEP). | +SRFI-1 +...... + +`(require 'srfi-1)' + +Implements the "SRFI-1" "list-processing library" as described at +<http://srfi.schemers.org/srfi-1/srfi-1.html> + +Constructors +------------ + + - Function: xcons d a + `(define (xcons d a) (cons a d))'. + + - Function: list-tabulate len proc + Returns a list of length LEN. Element I is `(PROC I)' for 0 <= I + < LEN. + + - Function: cons* obj1 obj2 + + - Function: list-copy flist | | - - Function: circular-list obj1 obj2 ... | - Returns a circular list of OBJ1, OBJ2, .... | + - Function: iota count start step + - Function: iota count start + - Function: iota count + Returns a list of COUNT numbers: (START, START+STEP, ..., + START+(COUNT-1)*STEP). + + - Function: circular-list obj1 obj2 ... + Returns a circular list of OBJ1, OBJ2, .... + +Predicates +---------- + + - Function: proper-list? obj + + - Function: circular-list? x + + - Function: dotted-list? obj + + - Function: null-list? obj + + - Function: not-pair? obj + + - Function: list= =pred list ... + +Selectors +--------- + + - Function: first pair | -Predicates | ----------- | + - Function: second pair | | - - Function: proper-list? obj | + - Function: third pair | | - - Function: circular-list? x | + - Function: fourth pair | | - - Function: dotted-list? obj | + - Function: fifth pair | + - Function: sixth obj + - Function: seventh obj + - Function: eighth obj + - Function: ninth obj + - Function: tenth obj + + - Function: car+cdr pair | - - Function: null-list? obj | + - Function: drop lst k + - Function: take lst k | | - - Function: not-pair? obj | + - Procedure: take! lst k | + + - Function: take-right lst k + + - Function: drop-right lst k | | - - Function: list= =pred list ... | + - Procedure: drop-right! lst k | | -Selectors | ---------- | + - Function: split-at lst k + + - Procedure: split-at! lst k | | - - Function: first pair | - - Function: fifth obj | - - Function: sixth obj | - - Function: seventh obj | - - Function: eighth obj | - - Function: ninth obj | - - Function: tenth obj | + - Function: last lst + (car (last-pair lst)) + +Miscellaneous +------------- + + - Function: length+ obj + + - Function: concatenate lists + - Function: concatenate! lists + + - Procedure: reverse! lst | + + - Function: append-reverse rev-head tail + - Function: append-reverse! rev-head tail + + - Function: zip list1 list2 ... + + - Function: unzip1 lst + - Function: unzip2 lst + - Function: unzip3 lst + - Function: unzip4 lst + - Function: unzip5 lst + + - Function: count pred list1 list2 ... + +Fold and Unfold +--------------- + + - Procedure: map! f list1 clist2 ... | | - - Function: car+cdr pair | + - Function: pair-for-each f clist1 clist2 ... | | - - Function: take lst k | - - Function: drop lst k | +Filtering and Partitioning +-------------------------- + + - Function: filter pred lis | | - - Function: take-right lst k | + - Procedure: filter! pred l | | - - Function: split-at lst k | + - Function: partition pred list | | - - Function: last lst | - (car (last-pair lst)) | +Searching +--------- + + - Function: find pred list + + - Function: find-tail pred list + + - Function: remove pred l | | -Miscellaneous | -------------- | + - Procedure: remove! pred l | | - - Function: length+ obj | + - Function: any pred clist1 clist2 ... | | - - Function: concatenate lists | - - Function: concatenate! lists | + - Function: list-index pred clist1 clist2 ... | | - - Function: reverse! lst | + - Function: span pred list | | - - Function: append-reverse rev-head tail | - - Function: append-reverse! rev-head tail | + - Function: member obj list pred + - Function: member obj list + `member' returns the first sublist of LIST whose car is OBJ, where + the sublists of LIST are the non-empty lists returned by + (list-tail LIST K) for K less than the length of LIST. If OBJ + does not occur in LIST, then #f (not the empty list) is returned. + The procedure PRED is used for testing equality. If PRED is not + provided, `equal?' is used. + +Deleting +-------- + +Association lists +----------------- + + - Function: assoc obj alist pred + - Function: assoc obj alist + ALIST (for "association list") must be a list of pairs. These + procedures find the first pair in ALIST whose car field is OBJ, and + returns that pair. If no pair in ALIST has OBJ as its car, then #f + (not the empty list) is returned. The procedure PRED is used for + testing equality. If PRED is not provided, `equal?' is used. + +Set operations +-------------- + + +File: slib.info, Node: SRFI-2, Next: SRFI-8, Prev: SRFI-1, Up: SRFI | - - Function: zip list1 list2 ... | +SRFI-2 | +...... | | - - Function: unzip1 lst | - - Function: unzip2 lst | - - Function: unzip3 lst | - - Function: unzip4 lst | - - Function: unzip5 lst | +`(require 'srfi-2)' | | - - Function: count pred list1 list2 ... | + - Macro: and-let* claws body ... | + <http://srfi.schemers.org/srfi-2/srfi-2.html> | | -Fold and Unfold | ---------------- | + +File: slib.info, Node: SRFI-8, Next: SRFI-9, Prev: SRFI-2, Up: SRFI | -Filtering and Partitioning | --------------------------- | +SRFI-8 | +...... | | -Searching | ---------- | +`(require 'srfi-8)' | | - - Function: find pred list | + - Special Form: receive formals expression body ... | + <http://srfi.schemers.org/srfi-8/srfi-8.html> | | - - Function: find-tail pred list | + +File: slib.info, Node: SRFI-9, Prev: SRFI-8, Up: SRFI | - - Function: member obj list pred | - - Function: member obj list | - `member' returns the first sublist of LIST whose car is OBJ, where | - the sublists of LIST are the non-empty lists returned by | - (list-tail LIST K) for K less than the length of LIST. If OBJ | - does not occur in LIST, then #f (not the empty list) is returned. | - The procedure PRED is used for testing equality. If PRED is not | - provided, `equal?' is used. | +SRFI-9 | +...... | | -Deleting | --------- | +`(require 'srfi-9)' | | -Association lists | ------------------ | + <http://srfi.schemers.org/srfi-9/srfi-9.html> | | - - Function: assoc obj alist pred | - - Function: assoc obj alist | - ALIST (for "association list") must be a list of pairs. These | - procedures find the first pair in ALIST whose car field is OBJ, and | - returns that pair. If no pair in ALIST has OBJ as its car, then #f | - (not the empty list) is returned. The procedure PRED is used for | - testing equality. If PRED is not provided, `equal?' is used. | + - Special Form: define-record-type <type-name> (<constructor-name> | + <field-tag> ...) <predicate-name> <field spec> ... | + Where | + <field-spec> == (<field-tag> <accessor-name>) | + == (<field-tag> <accessor-name> <modifier-name>) | | -Set operations | --------------- | + `define-record-type' is a syntax wrapper for the SLIB `record' | + module. | | -File: slib.info, Node: Session Support, Next: Extra-SLIB Packages, Prev: Standards Support, Up: Other Packages +File: slib.info, Node: Session Support, Next: System Interface, Prev: Standards Support, Up: Other Packages | Session Support =============== @@ -10648,7 +13901,6 @@ Session Support * Debug:: To err is human ... * Breakpoints:: Pause execution * Trace:: 'trace -* System Interface:: 'system, 'getenv, and 'net-clients File: slib.info, Node: Repl, Next: Quick Print, Prev: Session Support, Up: Session Support @@ -10656,7 +13908,7 @@ File: slib.info, Node: Repl, Next: Quick Print, Prev: Session Support, Up: S Repl ---- - `(require 'repl)' +`(require 'repl)' Here is a read-eval-print-loop which, given an eval, evaluates forms. @@ -10691,7 +13943,7 @@ File: slib.info, Node: Quick Print, Next: Debug, Prev: Repl, Up: Session Sup Quick Print ----------- - `(require 'qp)' +`(require 'qp)' When displaying error messages and warnings, it is paramount that the output generated for circular lists and large data structures be @@ -10713,8 +13965,10 @@ much improved. is like `qpn' except that it returns its last argument. - Variable: *qp-width* - `*qp-width*' is the largest number of characters that `qp' should - use. + *QP-WIDTH* is the largest number of characters that `qp' should + use. If *QP-WIDTH* is #f, then all items will be `write'n. If + *QP-WIDTH* is 0, then all items except procedures will be + `write'n; procedures will be indicated by `#[proc]'. File: slib.info, Node: Debug, Next: Breakpoints, Prev: Quick Print, Up: Session Support @@ -10722,7 +13976,7 @@ File: slib.info, Node: Debug, Next: Breakpoints, Prev: Quick Print, Up: Sess Debug ----- - `(require 'debug)' +`(require 'debug)' Requiring `debug' automatically requires `trace' and `break'. @@ -10755,7 +14009,7 @@ File: slib.info, Node: Breakpoints, Next: Trace, Prev: Debug, Up: Session Su Breakpoints ----------- - `(require 'break)' +`(require 'break)' - Function: init-debug If your Scheme implementation does not support `break' or `abort', @@ -10814,12 +14068,12 @@ supported by your implementation, these might be more convenient to use. (set! SYMBOL (unbreakf SYMBOL)) -File: slib.info, Node: Trace, Next: System Interface, Prev: Breakpoints, Up: Session Support +File: slib.info, Node: Trace, Prev: Breakpoints, Up: Session Support Tracing ------- - `(require 'trace)' +`(require 'trace)' This feature provides three ways to monitor procedure invocations: @@ -10895,6 +14149,10 @@ supported by your implementation, these might be more convenient to use. - Function: tracef proc - Function: tracef proc name + - Function: trackf proc | + - Function: trackf proc name | + - Function: stackf proc | + - Function: stackf proc name | To trace, type (set! SYMBOL (tracef SYMBOL)) @@ -10912,10 +14170,10 @@ supported by your implementation, these might be more convenient to use. (set! SYMBOL (untracef SYMBOL)) -File: slib.info, Node: System Interface, Prev: Trace, Up: Session Support +File: slib.info, Node: System Interface, Next: Extra-SLIB Packages, Prev: Session Support, Up: Other Packages System Interface ----------------- +================ If `(provided? 'getenv)': @@ -10930,100 +14188,233 @@ If `(provided? 'system)': Executes the COMMAND-STRING on the computer and returns the integer status code. -If `system' is provided by the Scheme implementation, the "net-clients" -package provides interfaces to common network client programs like FTP, -mail, and Netscape. +* Menu: + +* Directories:: +* Transactions:: +* CVS:: - `(require 'net-clients)' + +File: slib.info, Node: Directories, Next: Transactions, Prev: System Interface, Up: System Interface - - Function: call-with-tmpnam proc - - Function: call-with-tmpnam proc k - Calls PROC with K arguments, strings returned by successive calls - to `tmpnam'. If PROC returns, then any files named by the - arguments to PROC are deleted automatically and the value(s) - yielded by the PROC is(are) returned. K may be ommited, in which - case it defaults to `1'. +Directories +----------- - - Function: user-email-address - `user-email-address' returns a string of the form - `username@hostname'. If this e-mail address cannot be obtained, - #f is returned. +`(require 'directory)' - Function: current-directory `current-directory' returns a string containing the absolute file name representing the current working directory. If this string cannot be obtained, #f is returned. - If `current-directory' cannot be supported by the platform, the - value of `current-directory' is #f. + If `current-directory' cannot be supported by the platform, then + #f is returned. - Function: make-directory name Creates a sub-directory NAME of the current-directory. If successful, `make-directory' returns #t; otherwise #f. - - Function: null-directory? file-name - Returns #t if changing directory to FILE-NAME makes the current - working directory the same as it is before changing directory; - otherwise returns #f. + - Function: directory-for-each proc directory + PROC must be a procedure taking one argument. + `Directory-For-Each' applies PROC to the (string) name of each + file in DIRECTORY. The dynamic order in which PROC is applied to + the filenames is unspecified. The value returned by + `directory-for-each' is unspecified. - - Function: absolute-path? file-name - Returns #t if FILE-NAME is a fully specified pathname (does not - depend on the current working directory); otherwise returns #f. + - Function: directory-for-each proc directory pred + Applies PROC only to those filenames for which the procedure PRED + returns a non-false value. - - Function: glob-pattern? str - Returns #t if the string STR contains characters used for - specifying glob patterns, namely `*', `?', or `['. + - Function: directory-for-each proc directory match + Applies PROC only to those filenames for which `(filename:match?? + MATCH)' would return a non-false value (*note Filenames: + (slib)Filenames.). - - Function: parse-ftp-address uri - Returns a list of the decoded FTP URI; or #f if indecipherable. - FTP "Uniform Resource Locator", "ange-ftp", and "getit" formats - are handled. The returned list has four elements which are - strings or #f: + (require 'directory) + (directory-for-each print "." "[A-Z]*.scm") + -| + "Bev2slib.scm" + "Template.scm" - 0. username + +File: slib.info, Node: Transactions, Next: CVS, Prev: Directories, Up: System Interface - 1. password +Transactions +------------ - 2. remote-site +If `system' is provided by the Scheme implementation, the "transact" +package provides functions for file-locking and file-replacement +transactions. - 3. remote-directory + `(require 'transact)' + | +File Locking +............ + +Unix file-locking is focussed on write permissions for segments of a +existing file. While this might be employed for (binary) database +access, it is not used for everyday contention (between users) for text +files. + +Microsoft has several file-locking protocols. Their model denies write +access to a file if any reader has it open. This is too restrictive. +Write access is denied even when the reader has reached end-of-file. +And tracking read access (which is much more common than write access) +causes havoc when remote hosts crash or disconnect. + +It is bizarre that the concept of multi-user contention for modifying +files has not been adequately addressed by either of the large +operating system development efforts. There is further irony that both +camps support contention detection and resolution only through weak +conventions of some their document editing programs. + +The "file-lock" procedures implement a transaction method for file +replacement compatible with the methods used by the GNU "emacs" text +editor on Unix systems and the Microsoft "Word" editor. + +Both protocols employ what I term a "certificate" containing the user, +hostname, time, and (on Unix) process-id. Intent to replace FILE is +indicated by adding to FILE's directory a certificate object whose name +is derived from FILE. + +The Microsoft Word certificate is contained in a 162 byte file named +for the visited FILE with a `~$' prefix. Emacs/Unix creates a symbolic +link to a certificate named for the visited FILE prefixed with `.#'. +Because Unix systems can import Microsoft file systems, these routines +maintain and check both Emacs and Word certificates. + + - Function: file-lock-owner path + Returns the string `USER@HOSTNAME' associated with the lock owner + of file PATH if locked; and #f otherwise. + + - Procedure: file-lock! path email | + - Procedure: file-lock! path | + PATH must be a string naming the file to be locked. If supplied, + EMAIL must be a string formatted as `USER@HOSTNAME'. If absent, + EMAIL defaults to the value returned by `user-email-address'. + + If PATH is already locked, then `file-lock!' returns `#f'. If + PATH is unlocked, then `file-lock!' returns the certificate string + associated with the new lock for file PATH. + + - Procedure: file-unlock! path certificate | + PATH must be a string naming the file to be unlocked. CERTIFICATE + must be the string returned by `file-lock!' for PATH. + + If PATH is locked with CERTIFICATE, then `file-unlock!' removes + the locks and returns `#t'. Otherwise, `file-unlock!' leaves the + file system unaltered and returns `#f'. + +File Transactions +................. + + - Function: emacs:backup-name path backup-style + PATH must be a string. BACKUP-STYLE must be a symbol. Depending + on BACKUP-STYLE, `emacs:backup-name' returns: + none + #f + + simple + the string "PATH~" + + numbered + the string "PATH.~N~", where N is one greater than the + highest number appearing in a filename matching "PATH.~*~". N + defauls to 1 when no filename matches. + + existing + the string "PATH.~N~" if a numbered backup already exists in + this directory; otherwise. "PATH~" + + orig + the string "PATH.orig" + + bak + the string "PATH.bak" + + - Function: transact-file-replacement proc path backup-style + certificate + - Function: transact-file-replacement proc path backup-style + - Function: transact-file-replacement proc path + PATH must be a string naming an existing file. BACKUP-STYLE is + one of the symbols none, simple, numbered, existing, orig, bak or + #f; with meanings described above; or a string naming the location + of a backup file. BACKUP-STYLE defaults to #f. If supplied, + CERTIFICATE is the certificate with which PATH is locked. + + PROC must be a procedure taking two string arguments: + * PATH, the original filename (to be read); and + + * a temporary file-name. + + If PATH is locked by other than CERTIFICATE, or if CERTIFICATE is + supplied and PATH is not locked, then `transact-file-replacement' + returns #f. If CERTIFICATE is not supplied, then, + `transact-file-replacement' creates temporary (Emacs and Word) + locks for PATH during the transaction. The lock status of PATH + will be restored before `transact-file-replacement' returns. + + `transact-file-replacement' calls PROC with PATH (which should not + be modified) and a temporary file path to be written. If PROC + returns any value other than #t, then the file named by PATH is + not altered and `transact-file-replacement' returns #f. + Otherwise, `emacs:backup-name' is called with PATH and + BACKUP-STYLE. If it returns a string, then PATH is renamed to it. + + Finally, the temporary file is renamed PATH. + `transact-file-replacement' returns #t if PATH was successfully + replaced; and #f otherwise. + +Identification +.............. - - Function: ftp-upload paths user password remote-site remote-dir - PASSWORD must be a non-empty string or #f. PATHS must be a - non-empty list of pathnames or Glob patterns (*note Filenames::) - matching files to transfer. + - Function: user-email-address + `user-email-address' returns a string of the form + `username@hostname'. If this e-mail address cannot be obtained, + #f is returned. - `ftp-upload' puts the files specified by PATHS into the REMOTE-DIR - directory of FTP REMOTE-SITE using name USER with (optional) - PASSWORD. + +File: slib.info, Node: CVS, Prev: Transactions, Up: System Interface - If PASSWORD is #f and USER is not `ftp' or `anonymous', then USER - is ignored; FTP takes the username and password from the `.netrc' - or equivalent file. +CVS +--- - - Function: path->uri path - Returns a URI-string for PATH on the local host. +`(require 'cvs)' + + - Function: cvs-files directory/ + Returns a list of the local pathnames (with prefix DIRECTORY/) of + all CVS controlled files in DIRECTORY/ and in DIRECTORY/'s + subdirectories. - - Function: browse-url-netscape url - If a `netscape' browser is running, `browse-url-netscape' causes - the browser to display the page specified by string URL and - returns #t. + - Function: cvs-directories directory/ + Returns a list of all of DIRECTORY/ and all DIRECTORY/'s CVS + controlled subdirectories. - If the browser is not running, `browse-url-netscape' runs - `netscape' with the argument URL. If the browser starts as a - background job, `browse-url-netscape' returns #t immediately; if - the browser starts as a foreground job, then `browse-url-netscape' - returns #t when the browser exits; otherwise it returns #f. + - Function: cvs-root path/ + Returns the (string) contents of PATH/CVS/Root; or `(getenv + "CVSROOT")' if Root doesn't exist. + + - Function: cvs-repository directory/ + Returns the (string) contents of DIRECTORY/CVS/Root appended with + DIRECTORY/CVS/Repository; or #f if DIRECTORY/CVS/Repository + doesn't exist. + + - Procedure: cvs-set-root! new-root directory/ | + Writes NEW-ROOT to file CVS/Root of DIRECTORY/ and all its + subdirectories. + + - Function: cvs-vet directory/ + Signals an error if CVS/Repository or CVS/Root files in DIRECTORY/ + or any subdirectory do not match. -File: slib.info, Node: Extra-SLIB Packages, Prev: Session Support, Up: Other Packages +File: slib.info, Node: Extra-SLIB Packages, Prev: System Interface, Up: Other Packages Extra-SLIB Packages =================== - Several Scheme packages have been written using SLIB. There are -several reasons why a package might not be included in the SLIB -distribution: +Several Scheme packages have been written using SLIB. There are several +reasons why a package might not be included in the SLIB distribution: * Because it requires special hardware or software which is not universal. @@ -11052,7 +14443,6 @@ SLIB-PSD ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz - With PSD, you can run a Scheme program in an Emacs buffer, set breakpoints, single step evaluation and access and modify the program's variables. It works by instrumenting the original source @@ -11065,11 +14455,9 @@ SLIB-PSD 1993) is available as http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html - SCHELOG is an embedding of Prolog in Scheme. - http://www.cs.rice.edu/CS/PLT/packages/schelog/ - + http://www.ccs.neu.edu/~dorai/schelog/schelog.html JFILTER is a Scheme program which converts text among the JIS, EUC, and @@ -11085,8 +14473,8 @@ About SLIB More people than I can name have contributed to SLIB. Thanks to all of you! - SLIB 2d2, released July 2001. | - Aubrey Jaffer <agj @ alum.mit.edu> | + SLIB 3a1, released November 2003. | + Aubrey Jaffer <agj @ alum.mit.edu> Hyperactive Software - The Maniac Inside! <http://swissnet.ai.mit.edu/~jaffer/SLIB.html> @@ -11096,6 +14484,7 @@ you! * Porting:: SLIB to new platforms. * Coding Guidelines:: How to write modules for SLIB. * Copyrights:: Intellectual propery issues. +* About this manual:: | File: slib.info, Node: Installation, Next: Porting, Prev: About SLIB, Up: About SLIB @@ -11103,80 +14492,87 @@ File: slib.info, Node: Installation, Next: Porting, Prev: About SLIB, Up: Ab Installation ============ - There are four parts to installation: | - | - * Unpack the SLIB distribution. | - | - * Configure the Scheme implementation(s) to locate the SLIB | - directory. | - | - * Arrange for Scheme implementation to load its SLIB initialization | - file. | - | - * Build the SLIB catalog for the Scheme implementation. | - | -Unpacking the SLIB Distribution | -------------------------------- | - | - If the SLIB distribution is a Linux RPM, it will create the SLIB | -directory `/usr/share/slib'. | - | - If the SLIB distribution is a ZIP file, unzip the distribution to | -create the SLIB directory. Locate this `slib' directory either in your | -home directory (if only you will use this SLIB installation); or put it | -in a location where libraries reside on your system. On unix systems | -this might be `/usr/share/slib', `/usr/local/lib/slib', or | -`/usr/lib/slib'. If you know where SLIB should go on other platforms, | -please inform agj @ alum.mit.edu. | - | -Configure Scheme Implementation to Locate SLIB | ----------------------------------------------- | +There are four parts to installation: + + * Unpack the SLIB distribution. + + * Configure the Scheme implementation(s) to locate the SLIB + directory. + + * Arrange for Scheme implementation to load its SLIB initialization + file. - If the Scheme implementation supports `getenv', then the value of the + * Build the SLIB catalog for the Scheme implementation. + +Unpacking the SLIB Distribution +------------------------------- + +If the SLIB distribution is a Linux RPM, it will create the SLIB +directory `/usr/share/slib'. + + If the SLIB distribution is a ZIP file, unzip the distribution to +create the SLIB directory. Locate this `slib' directory either in your +home directory (if only you will use this SLIB installation); or put it +in a location where libraries reside on your system. On unix systems +this might be `/usr/share/slib', `/usr/local/lib/slib', or +`/usr/lib/slib'. If you know where SLIB should go on other platforms, +please inform agj @ alum.mit.edu. + +Configure Scheme Implementation to Locate SLIB +---------------------------------------------- + +If the Scheme implementation supports `getenv', then the value of the shell environment variable SCHEME_LIBRARY_PATH will be used for `(library-vicinity)' if it is defined. Currently, Chez, Elk, MITScheme, scheme->c, VSCM, and SCM support `getenv'. Scheme48 supports `getenv' but does not use it for determining `library-vicinity'. (That is done from the Makefile.) - The `(library-vicinity)' can also be specified from the SLIB | -initialization file or by implementation-specific means. | - | -Loading SLIB Initialization File | --------------------------------- | - | - Check the manifest in `README' to find a configuration file for your | -Scheme implementation. Initialization files for most IEEE P1178 | -compliant Scheme Implementations are included with this distribution. | - | + The `(library-vicinity)' can also be specified from the SLIB +initialization file or by implementation-specific means. + +Loading SLIB Initialization File +-------------------------------- + +Check the manifest in `README' to find a configuration file for your +Scheme implementation. Initialization files for most IEEE P1178 +compliant Scheme Implementations are included with this distribution. + You should check the definitions of `software-type', `scheme-implementation-version', `implementation-vicinity', and `library-vicinity' in the initialization file. There are comments in the file for how to configure it. - Once this is done, modify the startup file for your Scheme | -implementation to `load' this initialization file. | - | -Build New SLIB Catalog for Implementation | ------------------------------------------ | - | - When SLIB is first used from an implementation, a file named | -`slibcat' is written to the `implementation-vicinity' for that | -implementation. Because users may lack permission to write in | -`implementation-vicinity', it is good practice to build the new catalog | -when installing SLIB. | - | - To build (or rebuild) the catalog, start the Scheme implementation | -(with SLIB), then: | - | - (require 'new-catalog) | - | -Implementation-specific Instructions | ------------------------------------- | + Once this is done, modify the startup file for your Scheme +implementation to `load' this initialization file. + +Build New SLIB Catalog for Implementation +----------------------------------------- + +When SLIB is first used from an implementation, a file named `slibcat' +is written to the `implementation-vicinity' for that implementation. +Because users may lack permission to write in +`implementation-vicinity', it is good practice to build the new catalog +when installing SLIB. + + To build (or rebuild) the catalog, start the Scheme implementation +(with SLIB), then: + + (require 'new-catalog) + + The catalog also supports color-name dictionaries. With an +SLIB-installed scheme implementation, type: + (require 'color-names) + (make-slib-color-name-db) + (require 'new-catalog) + (slib:exit) + +Implementation-specific Instructions +------------------------------------ - Multiple implementations of Scheme can all use the same SLIB -directory. Simply configure each implementation's initialization file -as outlined above. +Multiple implementations of Scheme can all use the same SLIB directory. +Simply configure each implementation's initialization file as outlined +above. - Implementation: SCM The SCM implementation does not require any initialization file as @@ -11221,19 +14617,19 @@ as outlined above. - Implementation: PLT Scheme - Implementation: DrScheme - Implementation: MzScheme - The `init.ss' file in the _slibinit_ collection is an SLIB | - initialization file. | - | - To use SLIB in MzScheme, set the SCHEME_LIBRARY_PATH environment | - variable to the installed SLIB location; then invoke MzScheme thus: | - | - `mzscheme -L init.ss slibinit' | - | - - Implementation: MIT Scheme | - `scheme -load ${SCHEME_LIBRARY_PATH}mitscheme.init' | + The `init.ss' file in the _slibinit_ collection is an SLIB + initialization file. + + To use SLIB in MzScheme, set the SCHEME_LIBRARY_PATH environment + variable to the installed SLIB location; then invoke MzScheme thus: - - Implementation: Guile | - `guile -l ${SCHEME_LIBRARY_PATH}guile.init' | + `mzscheme -f ${SCHEME_LIBRARY_PATH}DrScheme.init' + + - Implementation: MIT Scheme + `scheme -load ${SCHEME_LIBRARY_PATH}mitscheme.init' + + - Implementation: Guile + `guile -l ${SCHEME_LIBRARY_PATH}guile.init' File: slib.info, Node: Porting, Next: Coding Guidelines, Prev: Installation, Up: About SLIB @@ -11241,11 +14637,14 @@ File: slib.info, Node: Porting, Next: Coding Guidelines, Prev: Installation, Porting ======= - If there is no initialization file for your Scheme implementation, you +If there is no initialization file for your Scheme implementation, you will have to create one. Your Scheme implementation must be largely -compliant with `IEEE Std 1178-1990', `Revised^4 Report on the -Algorithmic Language Scheme', or `Revised^5 Report on the Algorithmic -Language Scheme' in order to support SLIB. (1) +compliant with | + `IEEE Std 1178-1990', | + `Revised^4 Report on the Algorithmic Language Scheme', or | + `Revised^5 Report on the Algorithmic Language Scheme' | + | +in order to support SLIB. (1) | `Template.scm' is an example configuration file. The comments inside will direct you on how to customize it to reflect your system. Give @@ -11257,10 +14656,11 @@ initialization file might be called `foo.init'. implementation's initialization. It will load `require.scm' from the library; this will allow the use of `provide', `provided?', and `require' along with the "vicinity" functions (these functions are -documented in the section *Note Require::). The rest of the library -will then be accessible in a system independent fashion. +documented in the sections *Note Feature:: and *Note Require::). The | +rest of the library will then be accessible in a system independent | +fashion. | - Please mail new working configuration files to `agj @ alum.mit.edu' | + Please mail new working configuration files to `agj @ alum.mit.edu' so that they can be included in the SLIB distribution. ---------- Footnotes ---------- @@ -11275,24 +14675,33 @@ File: slib.info, Node: Coding Guidelines, Next: Copyrights, Prev: Porting, U Coding Guidelines ================= - All library packages are written in IEEE P1178 Scheme and assume that -a configuration file and `require.scm' package have already been -loaded. Other versions of Scheme can be supported in library packages -as well by using, for example, `(provided? 'rev3-report)' or `(require -'rev3-report)' (*note Require::). +All library packages are written in IEEE P1178 Scheme and assume that a +configuration file and `require.scm' package have already been loaded. +Other versions of Scheme can be supported in library packages as well +by using, for example, `(provided? 'r3rs)' or `(require 'r3rs)' (*note | +Require::). | - The module name and `:' should prefix each symbol defined in the -package. Definitions for external use should then be exported by having -`(define foo module-name:foo)'. + If a procedure defined in a module is called by other procedures in | +that module, then those procedures should instead call an alias defined | +in that module: | - Code submitted for inclusion in SLIB should not duplicate routines -already in SLIB files. Use `require' to force those library routines -to be used by your package. Care should be taken that there are no -circularities in the `require's and `load's between the library -packages. + (define module-name:foo foo) | + | + The module name and `:' should prefix that symbol for the internal | +name. Do not export internal aliases. | + | + A procedure is exported from a module by putting Schmooz-style | +comments (*note Schmooz::) or `;@' at the beginning of the line | +immediately preceding the definition (`define', `define-syntax', or | +`defmacro'). Modules, exports and other relevant issues are discussed | +in *Note Compiling Scheme::. | + | + Code submitted for inclusion in SLIB should not duplicate (more than | +one) routines already in SLIB files. Use `require' to force those | +library routines to be used by your package. | Documentation should be provided in Emacs Texinfo format if possible, -But documentation must be provided. +but documentation must be provided. | Your package will be released sooner with SLIB if you send me a file which tests your code. Please run this test _before_ you send me the @@ -11301,7 +14710,7 @@ code! Modifications ------------- - Please document your changes. A line or two for `ChangeLog' is +Please document your changes. A line or two for `ChangeLog' is sufficient for simple fixes or extensions. Look at the format of `ChangeLog' to see what information is desired. Please send me `diff' files from the latest SLIB distribution (remember to send `diff's of @@ -11320,12 +14729,12 @@ not have the time to fish through 10000 diffs to find your 10 real fixes. -File: slib.info, Node: Copyrights, Prev: Coding Guidelines, Up: About SLIB - +File: slib.info, Node: Copyrights, Next: About this manual, Prev: Coding Guidelines, Up: About SLIB + | Copyrights ========== - This section has instructions for SLIB authors regarding copyrights. +This section has instructions for SLIB authors regarding copyrights. Each package in SLIB must either be in the public domain, or come with a statement of terms permitting users to copy, redistribute and @@ -11338,40 +14747,39 @@ need to add your copyright or send a disclaimer. Putting code into the Public Domain ----------------------------------- - In order to put code in the public domain you should sign a copyright -disclaimer and send it to the SLIB maintainer. Contact agj @ | -alum.mit.edu for the address to mail the disclaimer to. | +In order to put code in the public domain you should sign a copyright +disclaimer and send it to the SLIB maintainer. Contact agj @ +alum.mit.edu for the address to mail the disclaimer to. - I, NAME, hereby affirm that I have placed the software package - NAME in the public domain. + I, <MY-NAME>, hereby affirm that I have placed the software + package <NAME> in the public domain. I affirm that I am the sole author and sole copyright holder for the software package, that I have the right to place this software package in the public domain, and that I will do nothing to undermine this status in the future. - SIGNATURE AND DATE This wording assumes that you are the sole author. If you are not the -sole author, the wording needs to be different. If you don't want to be -bothered with sending a letter every time you release or modify a +sole author, the wording needs to be different. If you don't want to +be bothered with sending a letter every time you release or modify a module, make your letter say that it also applies to your future revisions of that module. Make sure no employer has any claim to the copyright on the work you are submitting. If there is any doubt, create a copyright disclaimer and have your employer sign it. Mail the signed disclaimer to the SLIB -maintainer. Contact agj @ alum.mit.edu for the address to mail the | +maintainer. Contact agj @ alum.mit.edu for the address to mail the disclaimer to. An example disclaimer follows. Explicit copying terms ---------------------- -If you submit more than about 10 lines of code which you are not placing -into the Public Domain (by sending me a disclaimer) you need to: +If you submit more than about 10 lines of code which you are not +placing into the Public Domain (by sending me a disclaimer) you need to: * Arrange that your name appears in a copyright line for the - appropriate year. Multiple copyright lines are acceptable. + appropriate year. Multiple copyright lines are acceptable. * With your copyright line, specify any terms you require to be different from those already in the file. @@ -11379,34 +14787,50 @@ into the Public Domain (by sending me a disclaimer) you need to: * Make sure no employer has any claim to the copyright on the work you are submitting. If there is any doubt, create a copyright disclaimer and have your employer sign it. Mail the signed - disclaim to the SLIB maintainer. Contact agj @ alum.mit.edu for | + disclaim to the SLIB maintainer. Contact agj @ alum.mit.edu for the address to mail the disclaimer to. Example: Company Copyright Disclaimer ------------------------------------- - This disclaimer should be signed by a vice president or general -manager of the company. If you can't get at them, anyone else -authorized to license out software produced there will do. Here is a -sample wording: +This disclaimer should be signed by a vice president or general manager +of the company. If you can't get at them, anyone else authorized to +license out software produced there will do. Here is a sample wording: - EMPLOYER Corporation hereby disclaims all copyright interest in - the program PROGRAM written by NAME. + <EMPLOYER> Corporation hereby disclaims all copyright interest in + the program <PROGRAM> written by <NAME>. - EMPLOYER Corporation affirms that it has no other intellectual + <EMPLOYER> Corporation affirms that it has no other intellectual property interest that would undermine this release, and will do nothing to undermine it in the future. - SIGNATURE AND DATE, - NAME, TITLE, EMPLOYER Corporation + <SIGNATURE AND DATE>, + <NAME>, <TITLE>, <EMPLOYER> Corporation +File: slib.info, Node: About this manual, Prev: Copyrights, Up: About SLIB + | +About this manual | +================= | + | + * Entries that are labeled as Functions are called for their return | + values. Entries that are labeled as Procedures are called | + primarily for their side effects. | + | + * Examples in this text were produced using the `scm' Scheme | + implementation. | + | + * At the beginning of each section, there is a line that looks like | + `(require 'feature)'. Include this line in your code prior to | + using the package. | + | + File: slib.info, Node: Index, Prev: About SLIB, Up: Top - + | Procedure and Macro Index ************************* - This is an alphabetical list of all the procedures and macros in SLIB. +This is an alphabetical list of all the procedures and macros in SLIB. * Menu: @@ -11416,46 +14840,67 @@ Procedure and Macro Index * 1+: Rev2 Procedures. * <=?: Rev2 Procedures. * <?: Rev2 Procedures. +* =: Bit-Twiddling. * =?: Rev2 Procedures. * >=?: Rev2 Procedures. * >?: Rev2 Procedures. -* absolute-path?: System Interface. -* add-domain: Database Utilities. +* absolute-path?: URI. +* absolute-uri?: URI. +* ac32: Arrays. +* ac64: Arrays. +* add-command-tables: Database Extension. +* add-domain: Using Databases. | +* add-domain on relational-database: Command Intrinsics. | * add-process!: Multi-Processing. * add-setter: Setters. * adjoin: Lists as sets. -* adjoin-parameters!: Parameter lists. -* alarm: Multi-Processing. -* alarm-interrupt: Multi-Processing. +* adjoin-parameters!: Parameter lists. | * alist->wt-tree: Construction of Weight-Balanced Trees. * alist-associator: Association Lists. * alist-for-each: Association Lists. * alist-inquirer: Association Lists. * alist-map: Association Lists. * alist-remover: Association Lists. +* alist-table: The Base. | +* and-let*: SRFI-2. | * and?: Non-List functions. +* any: SRFI-1. | * any?: Collections. * append!: Rev2 Procedures. -* append-reverse: SRFI-1. | -* append-reverse!: SRFI-1. | -* apply: Multi-argument Apply. | +* append-reverse: SRFI-1. +* append-reverse!: SRFI-1. +* apply: Multi-argument Apply. +* ar32: Arrays. +* ar64: Arrays. +* array-align: Subarrays. * array-copy!: Array Mapping. * array-dimensions: Arrays. * array-for-each: Array Mapping. * array-in-bounds?: Arrays. * array-index-map!: Array Mapping. * array-indexes: Array Mapping. +* array-map: Array Mapping. | * array-map!: Array Mapping. * array-rank: Arrays. * array-ref: Arrays. * array-set!: Arrays. * array-shape: Arrays. -* array=?: Arrays. | +* array-trim: Subarrays. +* array=?: Arrays. * array?: Arrays. +* as16: Arrays. +* as32: Arrays. +* as64: Arrays. +* as8: Arrays. * asctime: Posix Time. * ash: Bit-Twiddling. -* assoc: SRFI-1. | +* assoc: SRFI-1. +* at1: Arrays. * atom?: Non-List functions. +* au16: Arrays. +* au32: Arrays. +* au64: Arrays. +* au8: Arrays. * batch:call-with-output-script: Batch. * batch:command: Batch. * batch:comment: Batch. @@ -11465,32 +14910,47 @@ Procedure and Macro Index * batch:rename-file: Batch. * batch:run-script: Batch. * batch:try-chopped-command: Batch. -* batch:try-command: Batch. -* bit-extract: Bit-Twiddling. +* batch:try-command: Batch. | * bit-field: Bit-Twiddling. +* bit-reverse: Bit-Twiddling. * bitwise-if: Bit-Twiddling. +* bitwise:delaminate: Bit-Twiddling. +* bitwise:laminate: Bit-Twiddling. +* blackbody-spectrum: Spectra. +* booleans->integer: Bit-Twiddling. * break: Breakpoints. * break-all: Debug. * breakf: Breakpoints. * breakpoint: Breakpoints. * browse: Database Browser. -* browse-url-netscape: System Interface. +* browse-url: System. * butlast: Lists as sequences. * butnthcdr: Lists as sequences. * byte-ref: Byte. * byte-set!: Byte. * bytes: Byte. +* bytes->ieee-double: Byte/Number Conversions. | +* bytes->ieee-float: Byte/Number Conversions. | +* bytes->integer: Byte/Number Conversions. | * bytes->list: Byte. +* bytes-copy: Byte. | * bytes-length: Byte. +* bytes-reverse: Byte. | +* bytes-reverse!: Byte. | * call-with-dynamic-binding: Dynamic Data Type. * call-with-input-string: String Ports. +* call-with-open-ports: Input/Output. * call-with-output-string: String Ports. -* call-with-tmpnam: System Interface. +* call-with-tmpnam: Filenames. | * call-with-values: Values. * capture-syntactic-environment: Syntactic Closures. -* car+cdr: SRFI-1. | -* cart-prod-tables: Relational Database Operations. +* car+cdr: SRFI-1. +* cart-prod-tables on relational-database: Database Operations. | * catalog->html: HTML Tables. +* catalog-id on base-table: Base Tables. | +* catalog:read: Catalog Vicinities. | +* cdna:base-count: NCBI-DNA. +* cdna:report-base-count: NCBI-DNA. * cgi:serve-query: HTTP and CGI. * chap:next-string: Chapter Ordering. * chap:string<=?: Chapter Ordering. @@ -11498,136 +14958,241 @@ Procedure and Macro Index * chap:string>=?: Chapter Ordering. * chap:string>?: Chapter Ordering. * check-parameters: Parameter lists. -* circular-list: SRFI-1. | -* circular-list?: SRFI-1. | -* close-base: Base Table. -* close-database: Relational Database Operations. -* close-table: Table Operations. +* chromaticity->CIEXYZ: Spectra. +* chromaticity->whitepoint: Spectra. +* CIE:DE*: Color Difference Metrics. +* CIE:DE*94: Color Difference Metrics. +* ciexyz->color: Color Spaces. +* CIEXYZ->e-sRGB: Color Conversions. +* CIEXYZ->L*a*b*: Color Conversions. +* CIEXYZ->L*u*v*: Color Conversions. +* CIEXYZ->RGB709: Color Conversions. +* CIEXYZ->sRGB: Color Conversions. +* CIEXYZ->xRGB: Color Conversions. | +* circular-list: SRFI-1. +* circular-list?: SRFI-1. +* cksum: Cyclic Checksum. | +* clear-sky-color-xyy: Daylight. +* clip-to-rect: Rectangles. | +* close-base on base-table: The Base. | +* close-database: Using Databases. +* close-database on relational-database: Database Operations. | +* close-port: Input/Output. +* close-table on relational-table: Table Administration. | +* CMC-DE: Color Difference Metrics. | +* CMC:DE*: Color Difference Metrics. +* codons<-cdna: NCBI-DNA. * coerce: Type Coercion. * collection?: Collections. +* color->ciexyz: Color Spaces. +* color->e-srgb: Color Spaces. +* color->l*a*b*: Color Spaces. +* color->l*c*h: Color Spaces. +* color->l*u*v*: Color Spaces. +* color->rgb709: Color Spaces. +* color->srgb: Color Spaces. +* color->string: Color Data-Type. +* color->xrgb: Color Spaces. +* color-dictionaries->lookup: Color Names. +* color-dictionary: Color Names. +* color-name->color: Color Names. +* color-name:canonicalize: Color Names. +* color-precision: Color Data-Type. +* color-space: Color Data-Type. +* color-white-point: Color Data-Type. +* color:ciexyz: Color Spaces. +* color:e-srgb: Color Spaces. +* color:l*a*b*: Color Spaces. +* color:l*c*h: Color Spaces. +* color:l*u*v*: Color Spaces. +* color:linear-transform: Color Conversions. | +* color:rgb709: Color Spaces. +* color:srgb: Color Spaces. +* color?: Color Data-Type. +* column-domains on relational-table: Table Administration. | +* column-foreigns on relational-table: Table Administration. | +* column-names on relational-table: Table Administration. | +* column-range: Column Ranges. | +* column-types on relational-table: Table Administration. | +* combine-ranges: Column Ranges. | * combined-rulesets: Commutative Rings. * command->p-specs: HTML. * command:make-editable-table: HTML Tables. * command:modify-table: HTML Tables. -* concatenate: SRFI-1. | -* concatenate!: SRFI-1. | -* cond-expand: SRFI. | -* cons*: SRFI-1. | +* concatenate: SRFI-1. +* concatenate!: SRFI-1. +* cond-expand: SRFI. +* cons*: SRFI-1. * continue: Breakpoints. +* convert-color: Color Data-Type. * copy-bit: Bit-Twiddling. * copy-bit-field: Bit-Twiddling. * copy-list: List construction. -* copy-random-state: Random Numbers. +* copy-random-state: Exact Random Numbers. | * copy-tree: Tree Operations. -* count: SRFI-1. | -* create-database <1>: Database Utilities. -* create-database: Creating and Opening Relational Databases. -* create-report: Database Reports. -* create-table: Relational Database Operations. -* create-view: Relational Database Operations. +* count: SRFI-1. +* count-newlines: String Search. | +* crc16: Cyclic Checksum. +* crc5: Cyclic Checksum. +* crc:make-table: Cyclic Checksum. +* create-array: Arrays. | +* create-database: Using Databases. +* create-database on relational-system: Relational Database Objects. | +* create-postscript-graph: PostScript Graphing. | +* create-table on relational-database: Database Operations. | +* create-view on relational-database: Database Operations. | * cring:define-rule: Commutative Rings. * ctime: Posix Time. -* current-directory: System Interface. +* current-directory: Directories. * current-error-port: Input/Output. * current-input-port <1>: Byte. * current-input-port: Ruleset Definition and Use. * current-output-port: Byte. * current-time: Time and Date. +* cvs-directories: CVS. +* cvs-files: CVS. +* cvs-repository: CVS. +* cvs-root: CVS. +* cvs-set-root!: CVS. +* cvs-vet: CVS. * db->html-directory: HTML Tables. * db->html-files: HTML Tables. * db->netscape: HTML Tables. * decode-universal-time: Common-Lisp Time. +* define-*commands*: Database Extension. * define-access-operation: Setters. +* define-command: Database Macros. +* define-domains: Using Databases. | * define-operation: Yasos interface. -* define-predicate: Yasos interface. | +* define-predicate: Yasos interface. +* define-record-type: SRFI-9. | +* define-structure: Syntax-Case Macros. | * define-syntax: Macro by Example. -* define-tables: Database Utilities. +* define-table: Database Macros. +* define-tables: Using Databases. * defmacro: Defmacro. * defmacro:eval: Defmacro. * defmacro:expand*: Defmacro. * defmacro:load: Defmacro. * defmacro?: Defmacro. -* delete <1>: Destructive list operations. -* delete: Base Table. -* delete*: Base Table. -* delete-domain: Database Utilities. +* delay: Promises. | +* delete: Destructive list operations. | +* delete on base-table: Base Record Operations. | +* delete* on base-table: Aggregate Base Operations. | +* delete-domain on relational-database: Command Intrinsics. | * delete-file: Input/Output. * delete-if: Destructive list operations. * delete-if-not: Destructive list operations. -* delete-table: Relational Database Operations. +* delete-table on relational-database: Database Operations. | * dequeue!: Queues. -* determinant: Determinant. -* diff:edit-length: Sequence Comparison. | -* diff:edits: Sequence Comparison. | -* diff:longest-common-subsequence: Sequence Comparison. | +* dequeue-all!: Queues. +* determinant: Matrix Algebra. +* diff:edit-length: Sequence Comparison. +* diff:edits: Sequence Comparison. +* diff:longest-common-subsequence: Sequence Comparison. * difftime: Time and Date. -* display-file: Line I/O. +* directory-for-each: Directories. | * do-elts: Collections. * do-keys: Collections. -* domain-checker: Database Utilities. -* dotted-list?: SRFI-1. | -* drop: SRFI-1. | +* domain-checker on relational-database: Command Intrinsics. | +* dotted-list?: SRFI-1. +* drop: SRFI-1. +* drop-right: SRFI-1. | +* drop-right!: SRFI-1. | * dynamic-ref: Dynamic Data Type. * dynamic-set!: Dynamic Data Type. * dynamic-wind: Dynamic-Wind. * dynamic?: Dynamic Data Type. -* eighth: SRFI-1. | +* e-sRGB->CIEXYZ: Color Conversions. +* e-srgb->color: Color Spaces. +* e-sRGB->e-sRGB: Color Conversions. +* e-sRGB->sRGB: Color Conversions. +* eighth: SRFI-1. +* emacs:backup-name: Transactions. * empty?: Collections. * encode-universal-time: Common-Lisp Time. -* enquque!: Queues. +* enqueue!: Queues. * equal?: Byte. * eval: Eval. * every: Lists as sets. * every?: Collections. +* exports<-info-index: Top-level Variable References. | * extended-euclid: Modular Arithmetic. * factor: Prime Numbers. +* feature->export-alist: Module Manifests. | +* feature->exports: Module Manifests. | +* feature->requires: Module Manifests. | +* feature-eval: Feature. | * fft: Fast Fourier Transform. * fft-1: Fast Fourier Transform. -* fifth: SRFI-1. | +* fifth: SRFI-1. +* file->color-dictionary: Color Names. +* file->definitions: Module Manifests. | +* file->exports: Module Manifests. | +* file->loads: Module Manifests. | +* file->requires: Module Manifests. | * file-exists?: Input/Output. +* file-lock!: Transactions. +* file-lock-owner: Transactions. +* file-unlock!: Transactions. | * filename:match-ci??: Filenames. * filename:match??: Filenames. * filename:substitute-ci??: Filenames. * filename:substitute??: Filenames. * fill-empty-parameters: Parameter lists. -* find: SRFI-1. | +* fill-rect: Rectangles. | +* filter: SRFI-1. | +* filter!: SRFI-1. | +* find: SRFI-1. * find-if: Lists as sets. * find-ratio: Rationalize. * find-ratio-between: Rationalize. * find-string-from-port?: String Search. -* find-tail: SRFI-1. | -* first: SRFI-1. | +* find-tail: SRFI-1. +* first: SRFI-1. * fluid-let: Fluid-Let. * for-each-elt: Collections. -* for-each-key <1>: Collections. -* for-each-key: Base Table. -* for-each-row: Table Operations. +* for-each-key: Collections. | +* for-each-key on base-table: Aggregate Base Operations. | +* for-each-row on relational-table: Multi-Row Operations. | +* for-each-row-in-order on relational-table: Sequential Index Operations. | +* force: Promises. | * force-output: Input/Output. * form:delimited: HTML. * form:element: HTML. * form:image: HTML. * form:reset: HTML. * form:submit: HTML. -* format: Format Interface. +* fourth: SRFI-1. | * fprintf: Standard Formatted Output. * fscanf: Standard Formatted Input. -* ftp-upload: System Interface. +* gen-elts: Collections. | +* gen-keys: Collections. | * generic-write: Generic-Write. * gentemp: Defmacro. -* get: Table Operations. -* get*: Table Operations. +* get on relational-table: Table Operations. | +* get* on relational-table: Match-Keys. | * get-decoded-time: Common-Lisp Time. +* get-foreign-choices: HTML. | * get-method: Object. * get-universal-time: Common-Lisp Time. * getenv: System Interface. * getopt: Getopt. -* getopt--: Getopt. +* getopt--: Getopt. | * getopt->arglist: Getopt Parameter lists. * getopt->parameter-list: Getopt Parameter lists. -* glob-pattern?: System Interface. +* glob-pattern?: URI. * gmktime: Posix Time. * gmtime: Posix Time. * golden-section-search: Minimizing. +* gray-code->integer: Bit-Twiddling. +* gray-code<=?: Bit-Twiddling. +* gray-code<?: Bit-Twiddling. +* gray-code>=?: Bit-Twiddling. +* gray-code>?: Bit-Twiddling. +* grey: Color Names. +* grid-horizontals: Legending. | +* grid-verticals: Legending. | * gtime: Posix Time. * has-duplicates?: Lists as sets. * hash: Hashing. @@ -11635,13 +15200,18 @@ Procedure and Macro Index * hash-for-each: Hash Tables. * hash-inquirer: Hash Tables. * hash-map: Hash Tables. +* hash-rehasher: Hash Tables. | * hash-remover: Hash Tables. * hashq: Hashing. * hashv: Hashing. * heap-extract-max!: Priority Queues. * heap-insert!: Priority Queues. * heap-length: Priority Queues. +* hilbert-coordinates->integer: Peano-Hilbert Space-Filling Curve. +* histograph: Character Plotting. | * home-vicinity: Vicinity. +* htm-fields: Parsing HTML. +* html-for-each: Parsing HTML. * html:anchor: URI. * html:atval: HTML. * html:base: URI. @@ -11650,6 +15220,7 @@ Procedure and Macro Index * html:caption: HTML Tables. * html:checkbox: HTML. * html:comment: HTML. +* html:delimited-list: HTML. | * html:editable-row-converter: HTML Tables. * html:form: HTML. * html:head: HTML. @@ -11664,6 +15235,7 @@ Procedure and Macro Index * html:meta-refresh: HTML. * html:plain: HTML. * html:pre: HTML. +* html:read-title: Parsing HTML. * html:select: HTML. * html:table: HTML Tables. * html:text: HTML. @@ -11675,40 +15247,77 @@ Procedure and Macro Index * http:serve-query: HTTP and CGI. * identifier=?: Syntactic Closures. * identifier?: Syntactic Closures. -* identity: Legacy. +* identity: Miscellany. +* ieee-byte-collate: Byte/Number Conversions. | +* ieee-byte-collate!: Byte/Number Conversions. | +* ieee-byte-decollate: Byte/Number Conversions. | +* ieee-byte-decollate!: Byte/Number Conversions. | +* ieee-double->bytes: Byte/Number Conversions. | +* ieee-float->bytes: Byte/Number Conversions. | * implementation-vicinity: Vicinity. +* in-graphic-context: Graphics Context. | * in-vicinity: Vicinity. * init-debug: Breakpoints. +* integer->bytes: Byte/Number Conversions. | +* integer->gray-code: Bit-Twiddling. +* integer->hilbert-coordinates: Peano-Hilbert Space-Filling Curve. +* integer->list: Bit-Twiddling. +* integer-byte-collate: Byte/Number Conversions. | +* integer-byte-collate!: Byte/Number Conversions. | * integer-expt: Bit-Twiddling. * integer-length: Bit-Twiddling. * integer-sqrt: Root Finding. * interaction-environment: Eval. +* interpolate-from-table: Database Interpolation. | * intersection: Lists as sets. -* iota: SRFI-1. | +* iota: SRFI-1. +* isam-next on relational-table: Sequential Index Operations. | +* isam-prev on relational-table: Sequential Index Operations. | * jacobi-symbol: Prime Numbers. * kill-process!: Multi-Processing. -* kill-table: Base Table. +* kill-table on base-table: Base Tables. | +* L*a*b*->CIEXYZ: Color Conversions. +* l*a*b*->color: Color Spaces. +* L*a*b*->L*C*h: Color Conversions. +* L*a*b*:DE*: Color Difference Metrics. | +* l*c*h->color: Color Spaces. +* L*C*h->L*a*b*: Color Conversions. +* L*C*h:DE*94: Color Difference Metrics. | +* L*u*v*->CIEXYZ: Color Conversions. +* l*u*v*->color: Color Spaces. * laguerre:find-polynomial-root: Root Finding. * laguerre:find-root: Root Finding. -* last <1>: SRFI-1. | +* last <1>: SRFI-1. * last: Lists as sequences. -* last-pair: Legacy. -* length+: SRFI-1. | +* last-pair: Miscellany. +* length+: SRFI-1. * library-vicinity: Vicinity. +* light:ambient: Solid Modeling. +* light:beam: Solid Modeling. +* light:directional: Solid Modeling. +* light:point: Solid Modeling. +* light:spot: Solid Modeling. * list*: List construction. * list->bytes: Byte. +* list->integer: Bit-Twiddling. * list->string: Rev4 Optional Procedures. * list->vector: Rev4 Optional Procedures. +* list-copy: SRFI-1. | +* list-index: SRFI-1. | * list-of??: Lists as sets. -* list-table-definition: Database Utilities. -* list-tabulate: SRFI-1. | +* list-table-definition: Using Databases. +* list-tabulate: SRFI-1. * list-tail: Rev4 Optional Procedures. -* list=: SRFI-1. | -* load-option: Weight-Balanced Trees. +* list=: SRFI-1. +* load->path: Module Manifests. | +* load-ciexyz: Spectra. | +* load-color-dictionary: Color Names. | * localtime: Posix Time. * logand: Bit-Twiddling. * logbit?: Bit-Twiddling. * logcount: Bit-Twiddling. +* logical:ones: Bit-Twiddling. | +* logical:rotate: Bit-Twiddling. * logior: Bit-Twiddling. * lognot: Bit-Twiddling. * logtest: Bit-Twiddling. @@ -11729,103 +15338,135 @@ Procedure and Macro Index * macroexpand-1: Defmacro. * macwork:eval: Macros That Work. * macwork:expand: Macros That Work. -* macwork:load: Macros That Work. | -* make-array: Arrays. -* make-base: Base Table. +* macwork:load: Macros That Work. +* make-base on base-table: The Base. | * make-bytes: Byte. -* make-command-server: Database Utilities. -* make-directory: System Interface. +* make-color: Color Data-Type. +* make-command-server: Command Service. +* make-directory: Directories. * make-dynamic: Dynamic Data Type. +* make-exchanger: Miscellany. * make-generic-method: Object. * make-generic-predicate: Object. -* make-getter: Base Table. +* make-getter on base-table: Base Record Operations. | +* make-getter-1 on base-table: Base Record Operations. | * make-hash-table: Hash Tables. * make-heap: Priority Queues. -* make-key->list: Base Table. -* make-key-extractor: Base Table. -* make-keyifier-1: Base Table. +* make-key->list on base-table: Composite Keys. | +* make-key-extractor on base-table: Composite Keys. | +* make-keyifier-1 on base-table: Composite Keys. | * make-list: List construction. -* make-list-keyifier: Base Table. +* make-list-keyifier on base-table: Composite Keys. | * make-method!: Object. +* make-nexter on base-table: Base ISAM Operations. | * make-object: Object. * make-parameter-list: Parameter lists. -* make-port-crc: Cyclic Checksum. * make-predicate!: Object. +* make-prever on base-table: Base ISAM Operations. | * make-promise: Promises. -* make-putter: Base Table. +* make-putter on base-table: Base Record Operations. | * make-query-alist-command-server: HTTP and CGI. * make-queue: Queues. -* make-random-state: Random Numbers. +* make-random-state: Exact Random Numbers. | * make-record-type: Records. -* make-relational-system: Creating and Opening Relational Databases. +* make-relational-system: Relational Database Objects. * make-ruleset: Commutative Rings. * make-shared-array: Arrays. -* make-sierpinski-indexer: Hashing. +* make-sierpinski-indexer: Sierpinski Curve. +* make-slib-color-name-db: Color Names. * make-syntactic-closure: Syntactic Closures. -* make-table: Base Table. +* make-table on base-table: Base Tables. | * make-uri: URI. * make-vicinity: Vicinity. * make-wt-tree: Construction of Weight-Balanced Trees. * make-wt-tree-type: Construction of Weight-Balanced Trees. +* map!: SRFI-1. | * map-elts: Collections. -* map-key: Base Table. +* map-key on base-table: Aggregate Base Operations. | * map-keys: Collections. -* member: SRFI-1. | +* matfile:load: MAT-File Format. +* matfile:read: MAT-File Format. +* matrix->array: Matrix Algebra. +* matrix->lists: Matrix Algebra. +* matrix:inverse: Matrix Algebra. +* matrix:product: Matrix Algebra. +* mdbm:report: Using Databases. +* member: SRFI-1. * member-if: Lists as sets. * merge: Sorting. * merge!: Sorting. * mktime: Posix Time. -* modular:: Modular Arithmetic. +* mod: Modular Arithmetic. | * modular:*: Modular Arithmetic. * modular:+: Modular Arithmetic. +* modular:-: Modular Arithmetic. | * modular:expt: Modular Arithmetic. * modular:invert: Modular Arithmetic. * modular:invertable?: Modular Arithmetic. * modular:negate: Modular Arithmetic. * modular:normalize: Modular Arithmetic. * modulus->integer: Modular Arithmetic. +* mrna<-cdna: NCBI-DNA. * must-be-first: Batch. * must-be-last: Batch. +* ncbi:read-dna-sequence: NCBI-DNA. +* ncbi:read-file: NCBI-DNA. * nconc: Destructive list operations. +* newton:find-integer-root: Root Finding. * newton:find-root: Root Finding. -* newtown:find-integer-root: Root Finding. -* ninth: SRFI-1. | -* not-pair?: SRFI-1. | +* ninth: SRFI-1. +* not-pair?: SRFI-1. * notany: Lists as sets. * notevery: Lists as sets. * nreverse: Destructive list operations. * nthcdr: Lists as sequences. -* null-directory?: System Interface. +* null-directory?: URI. * null-environment: Eval. -* null-list?: SRFI-1. | +* null-list?: SRFI-1. * object: Yasos interface. * object->limited-string: Object-To-String. * object->string: Object-To-String. * object-with-ancestors: Yasos interface. * object?: Object. * offset-time: Time and Date. -* open-base: Base Table. -* open-database <1>: Database Utilities. -* open-database: Creating and Opening Relational Databases. -* open-database!: Database Utilities. -* open-table <1>: Relational Database Operations. -* open-table: Base Table. +* open-base on base-table: The Base. | +* open-command-database: Database Extension. +* open-command-database!: Database Extension. | +* open-database: Using Databases. +* open-database on relational-system: Relational Database Objects. | +* open-database!: Using Databases. +* open-file <1>: Byte. | +* open-file: Input/Output. +* open-table: Using Databases. | +* open-table on base-table: Base Tables. | +* open-table on relational-database: Database Operations. | +* open-table!: Using Databases. | * operate-as: Yasos interface. * or?: Non-List functions. -* ordered-for-each-key: Base Table. +* ordered-for-each-key on base-table: Base ISAM Operations. | * os->batch-dialect: Batch. +* outline-rect: Rectangles. | * output-port-height: Input/Output. * output-port-width: Input/Output. +* overcast-sky-color-xyy: Daylight. +* p<-cdna: NCBI-DNA. +* pad-range: Column Ranges. | +* pair-for-each: SRFI-1. | * parameter-list->arglist: Parameter lists. * parameter-list-expand: Parameter lists. * parameter-list-ref: Parameter lists. -* parse-ftp-address: System Interface. -* path->uri: System Interface. -* plot!: Plotting. -* plot-function!: Plotting. +* parse-ftp-address: URI. +* partition: SRFI-1. | +* partition-page: Rectangles. | +* path->uri: URI. +* pathname->vicinity: Vicinity. +* plot <1>: Legacy Plotting. | +* plot: Character Plotting. | +* plot-column: Drawing the Graph. | * pnm:array-write: Portable Image Files. * pnm:image-file->array: Portable Image Files. * pnm:type-dimensions: Portable Image Files. +* port?: Input/Output. * position: Lists as sequences. * pprint-file: Pretty-Print. * pprint-filter-file: Pretty-Print. @@ -11846,9 +15487,10 @@ Procedure and Macro Index * predicate->asso: Association Lists. * predicate->hash: Hash Tables. * predicate->hash-asso: Hash Tables. -* present?: Base Table. +* present? on base-table: Base Record Operations. | * pretty-print: Pretty-Print. * pretty-print->string: Pretty-Print. +* primary-limit on relational-table: Table Administration. | * prime?: Prime Numbers. * primes<: Prime Numbers. * primes>: Prime Numbers. @@ -11857,11 +15499,10 @@ Procedure and Macro Index * printf: Standard Formatted Output. * process:schedule!: Multi-Processing. * program-vicinity: Vicinity. -* project-table: Relational Database Operations. -* proper-list?: SRFI-1. | -* provide <1>: Require. -* provide: Feature. -* provided? <1>: Require. +* project-table on relational-database: Database Operations. | +* proper-list?: SRFI-1. +* protein<-cdna: NCBI-DNA. | +* provide: Feature. | * provided?: Feature. * qp: Quick Print. * qpn: Quick Print. @@ -11872,19 +15513,21 @@ Procedure and Macro Index * queue-push!: Queues. * queue-rear: Queues. * queue?: Queues. -* random: Random Numbers. -* random:exp: Random Numbers. -* random:hollow-sphere!: Random Numbers. -* random:normal: Random Numbers. -* random:normal-vector!: Random Numbers. -* random:solid-sphere!: Random Numbers. -* random:uniform: Random Numbers. +* random: Exact Random Numbers. | +* random:exp: Inexact Random Numbers. | +* random:hollow-sphere!: Inexact Random Numbers. | +* random:normal: Inexact Random Numbers. | +* random:normal-vector!: Inexact Random Numbers. | +* random:solid-sphere!: Inexact Random Numbers. | +* random:uniform: Inexact Random Numbers. | * rationalize: Rationalize. * read-byte: Byte. +* read-bytes: Byte. | * read-command: Command Line. * read-line: Line I/O. * read-line!: Line I/O. * read-options-file: Command Line. +* receive: SRFI-8. | * record-accessor: Records. * record-constructor: Records. * record-modifier: Records. @@ -11892,7 +15535,10 @@ Procedure and Macro Index * reduce <1>: Lists as sequences. * reduce: Collections. * reduce-init: Lists as sequences. +* rem: Modular Arithmetic. +* remove <1>: SRFI-1. | * remove: Lists as sets. +* remove!: SRFI-1. | * remove-duplicates: Lists as sets. * remove-if: Lists as sets. * remove-if-not: Lists as sets. @@ -11901,64 +15547,119 @@ Procedure and Macro Index * repl:quit: Repl. * repl:top-level: Repl. * replace-suffix: Filenames. -* require <1>: Require. -* require <2>: Catalog Compilation. -* require: Requesting Features. -* require:feature->path <1>: Require. -* require:feature->path: Requesting Features. -* restrict-table: Relational Database Operations. -* reverse!: SRFI-1. | -* row:delete: Table Operations. -* row:delete*: Table Operations. -* row:insert: Table Operations. -* row:insert*: Table Operations. -* row:remove: Table Operations. -* row:remove*: Table Operations. -* row:retrieve: Table Operations. -* row:retrieve*: Table Operations. -* row:update: Table Operations. -* row:update*: Table Operations. +* require <1>: Catalog Creation. | +* require: Require. | +* require-if: Require. | +* resene: Color Names. +* restrict-table on relational-database: Database Operations. | +* reverse!: SRFI-1. +* RGB709->CIEXYZ: Color Conversions. +* rgb709->color: Color Spaces. +* row:delete on relational-table: Single Row Operations. | +* row:delete* on relational-table: Multi-Row Operations. | +* row:insert on relational-table: Single Row Operations. | +* row:insert* on relational-table: Multi-Row Operations. | +* row:remove on relational-table: Single Row Operations. | +* row:remove* on relational-table: Multi-Row Operations. | +* row:retrieve on relational-table: Single Row Operations. | +* row:retrieve* on relational-table: Multi-Row Operations. | +* row:update on relational-table: Single Row Operations. | +* row:update* on relational-table: Multi-Row Operations. | +* rule-horizontal: Legending. | +* rule-vertical: Legending. | +* saturate: Color Names. * scanf: Standard Formatted Input. * scanf-read-list: Standard Formatted Input. +* scene:overcast: Solid Modeling. +* scene:panorama: Solid Modeling. +* scene:sky-and-dirt: Solid Modeling. +* scene:sky-and-grass: Solid Modeling. +* scene:sphere: Solid Modeling. +* scene:sun: Solid Modeling. +* scene:viewpoint: Solid Modeling. +* scene:viewpoints: Solid Modeling. * scheme-report-environment: Eval. * schmooz: Schmooz. * secant:find-bracketed-root: Root Finding. * secant:find-root: Root Finding. -* seed->random-state: Random Numbers. -* set: Setters. | +* second: SRFI-1. | +* seed->random-state: Exact Random Numbers. | +* set: Setters. +* set-color: Graphics Context. | * set-difference: Lists as sets. +* set-font: Graphics Context. | +* set-glyphsize: Graphics Context. | +* set-linedash: Graphics Context. | +* set-linewidth: Graphics Context. | * Setter: Collections. * setter: Setters. -* seventh: SRFI-1. | +* setup-plot: Column Ranges. | +* seventh: SRFI-1. * si:conversion-factor: Metric Units. * singleton-wt-tree: Construction of Weight-Balanced Trees. -* sixth: SRFI-1. | +* sixth: SRFI-1. * size <1>: Collections. * size: Yasos interface. +* sky-color-xyy: Daylight. * slib:error: System. * slib:eval: System. * slib:eval-load: System. * slib:exit: System. +* slib:in-catalog?: Require. | * slib:load: System. * slib:load-compiled: System. * slib:load-source: System. * slib:report: Configuration. * slib:report-version: Configuration. * slib:warn: System. +* snap-range: Column Ranges. | * software-type: Configuration. +* solar-declination: Daylight. +* solar-hour: Daylight. +* solar-polar: Daylight. +* solid:arrow: Solid Modeling. +* solid:basrelief: Solid Modeling. +* solid:box: Solid Modeling. +* solid:center-array-of: Solid Modeling. +* solid:center-pile-of: Solid Modeling. +* solid:center-row-of: Solid Modeling. +* solid:color: Solid Modeling. +* solid:cone: Solid Modeling. +* solid:cylinder: Solid Modeling. +* solid:disk: Solid Modeling. +* solid:ellipsoid: Solid Modeling. +* solid:pyramid: Solid Modeling. +* solid:rotation: Solid Modeling. +* solid:scale: Solid Modeling. +* solid:sphere: Solid Modeling. +* solid:texture: Solid Modeling. +* solid:translation: Solid Modeling. | +* solidify-database: Using Databases. +* solidify-database on relational-database: Database Operations. | * some: Lists as sets. * sort: Sorting. * sort!: Sorting. * sorted?: Sorting. -* soundex: Hashing. -* split-at: SRFI-1. | +* soundex: Soundex. +* span: SRFI-1. | +* spectrum->chromaticity: Spectra. +* spectrum->CIEXYZ: Spectra. +* spectrum->XYZ: Spectra. +* split-at: SRFI-1. +* split-at!: SRFI-1. | * sprintf: Standard Formatted Output. +* sRGB->CIEXYZ: Color Conversions. +* srgb->color: Color Spaces. +* sRGB->e-sRGB: Color Conversions. +* sRGB->xRGB: Color Conversions. | * sscanf: Standard Formatted Input. * stack: Trace. * stack-all: Debug. +* stackf: Trace. | +* string->color: Color Data-Type. * string->list: Rev4 Optional Procedures. * string-capitalize: String-Case. -* string-captialize!: String-Case. +* string-capitalize!: String-Case. | * string-ci->symbol: String-Case. * string-copy: Rev4 Optional Procedures. * string-downcase: String-Case. @@ -11973,71 +15674,78 @@ Procedure and Macro Index * string-subst: String Search. * string-upcase: String-Case. * string-upcase!: String-Case. +* StudlyCapsExpand: String-Case. * sub-vicinity: Vicinity. +* subarray: Subarrays. +* subarray0: Subarrays. +* subset?: Lists as sets. * subst: Tree Operations. * substq: Tree Operations. * substring-ci?: String Search. * substring-fill!: Rev2 Procedures. * substring-move-left!: Rev2 Procedures. * substring-move-right!: Rev2 Procedures. +* substring-read!: Byte. | +* substring-write: Byte. | * substring?: String Search. * substv: Tree Operations. -* supported-key-type?: Base Table. -* supported-type?: Base Table. +* sunlight-ciexyz: Daylight. +* sunlight-spectrum: Daylight. +* sunlight-xyz: Daylight. +* supported-key-type? on base-table: Base Field Types. | +* supported-type? on base-table: Base Field Types. | * symbol-append: String-Case. * symmetric:modulus: Modular Arithmetic. -* sync-base: Base Table. -* sync-database: Relational Database Operations. +* sync-base on base-table: The Base. | +* sync-database: Using Databases. +* sync-database on relational-database: Database Operations. | * syncase:eval: Syntax-Case Macros. * syncase:expand: Syntax-Case Macros. * syncase:load: Syntax-Case Macros. +* syncase:sanity-check: Syntax-Case Macros. | * synclo:eval: Syntactic Closures. * synclo:expand: Syntactic Closures. * synclo:load: Syntactic Closures. * syntax-rules: Macro by Example. * system: System Interface. +* system->line: Line I/O. | * table->linked-html: HTML Tables. * table->linked-page: HTML Tables. -* table-exists?: Relational Database Operations. +* table-exists? on relational-database: Database Operations. | * table-name->filename: HTML Tables. -* take: SRFI-1. | -* take-right: SRFI-1. | -* tek40:draw: Tektronix Graphics Support. -* tek40:graphics: Tektronix Graphics Support. -* tek40:init: Tektronix Graphics Support. -* tek40:linetype: Tektronix Graphics Support. -* tek40:move: Tektronix Graphics Support. -* tek40:put-text: Tektronix Graphics Support. -* tek40:reset: Tektronix Graphics Support. -* tek40:text: Tektronix Graphics Support. -* tek41:draw: Tektronix Graphics Support. -* tek41:encode-int: Tektronix Graphics Support. -* tek41:encode-x-y: Tektronix Graphics Support. -* tek41:graphics: Tektronix Graphics Support. -* tek41:init: Tektronix Graphics Support. -* tek41:move: Tektronix Graphics Support. -* tek41:point: Tektronix Graphics Support. -* tek41:reset: Tektronix Graphics Support. -* tenth: SRFI-1. | +* take: SRFI-1. +* take!: SRFI-1. | +* take-right: SRFI-1. +* temperature->chromaticity: Spectra. | +* temperature->CIEXYZ: Spectra. +* temperature->XYZ: Spectra. +* tenth: SRFI-1. +* third: SRFI-1. | * time-zone: Time Zone. +* title-bottom: Legending. | +* title-top: Legending. | * tmpnam: Input/Output. +* tok:bump-column: Token definition. | * tok:char-group: Token definition. +* top-refs: Top-level Variable References. | +* top-refs<-file: Top-level Variable References. | * topological-sort: Topological Sort. * trace: Trace. * trace-all: Debug. * tracef: Trace. * track: Trace. * track-all: Debug. +* trackf: Trace. | +* transact-file-replacement: Transactions. * transcript-off: Transcripts. * transcript-on: Transcripts. * transformer: Syntactic Closures. +* transpose: Matrix Algebra. * truncate-up-to: Batch. -* tsort: Topological Sort. -* two-arg:-: Multi-argument / and -. -* two-arg:/: Multi-argument / and -. -* two-arg:apply: Multi-argument Apply. +* tsort: Topological Sort. | * type-of: Type Coercion. * tz:params: Time Zone. +* tz:std-offset: Time Zone. | * tzset: Time Zone. * unbreak: Breakpoints. * unbreakf: Breakpoints. @@ -12047,24 +15755,44 @@ Procedure and Macro Index * untrace: Trace. * untracef: Trace. * untrack: Trace. -* unzip1: SRFI-1. | -* unzip2: SRFI-1. | -* unzip3: SRFI-1. | -* unzip4: SRFI-1. | -* unzip5: SRFI-1. | +* unzip1: SRFI-1. +* unzip2: SRFI-1. +* unzip3: SRFI-1. +* unzip4: SRFI-1. +* unzip5: SRFI-1. * uri->tree: URI. +* uri:decode-query: URI. +* uri:make-path: URI. | +* uri:path->keys: URI. | +* uri:split-fields: URI. | * uric:decode: URI. * uric:encode: URI. -* user-email-address: System Interface. +* url->color-dictionary: Color Names. +* user-email-address: Transactions. * user-vicinity: Vicinity. -* values: Values. | +* values: Values. * vector->list: Rev4 Optional Procedures. * vector-fill!: Rev4 Optional Procedures. +* vet-slib: Module Analysis. | +* vicinity:suffix?: Vicinity. | +* vrml: Solid Modeling. +* vrml-append: Solid Modeling. +* vrml-to-file: Solid Modeling. +* wavelength->chromaticity: Spectra. +* wavelength->CIEXYZ: Spectra. +* wavelength->XYZ: Spectra. +* whole-page <1>: Rectangles. | +* whole-page: PostScript Graphing. | * with-input-from-file: With-File. * with-output-to-file: With-File. -* write-base: Base Table. +* within-database: Database Macros. +* world:info: Solid Modeling. +* wrap-command-interface: Database Extension. +* write-base on base-table: The Base. | * write-byte: Byte. -* write-database: Relational Database Operations. +* write-bytes: Byte. | +* write-database: Using Databases. +* write-database on relational-database: Database Operations. | * write-line: Line I/O. * wt-tree/add: Basic Operations on Weight-Balanced Trees. * wt-tree/add!: Basic Operations on Weight-Balanced Trees. @@ -12092,166 +15820,262 @@ Procedure and Macro Index * wt-tree/split>: Advanced Operations on Weight-Balanced Trees. * wt-tree/subset?: Advanced Operations on Weight-Balanced Trees. * wt-tree/union: Advanced Operations on Weight-Balanced Trees. -* wt-tree?: Basic Operations on Weight-Balanced Trees. -* xcons: SRFI-1. | -* zip: SRFI-1. | +* x-axis: Legending. | +* xcons: SRFI-1. +* xRGB->CIEXYZ: Color Conversions. | +* xrgb->color: Color Spaces. +* xRGB->sRGB: Color Conversions. | +* xyY->XYZ: Spectra. +* xyY:normalize-colors: Spectra. +* XYZ->chromaticity: Spectra. +* XYZ->xyY: Spectra. +* XYZ:normalize: Spectra. +* XYZ:normalize-colors: Spectra. +* y-axis: Legending. | +* zenith-xyy: Daylight. +* zip: SRFI-1. Variable Index ************** - This is an alphabetical list of all the global variables in SLIB. +This is an alphabetical list of all the global variables in SLIB. * Menu: -* *catalog*: Require. -* *features*: Require. -* *http:byline*: HTTP and CGI. -* *modules*: Require. +* *argv*: Getopt. +* *base-table-implementations*: Base Table. +* *catalog*: Require. | +* *http:byline*: HTTP and CGI. | +* *operating-system*: Batch. * *optarg*: Getopt. * *optind*: Getopt. * *qp-width*: Quick Print. -* *random-state*: Random Numbers. +* *random-state*: Exact Random Numbers. | * *ruleset*: Commutative Rings. * *syn-defs*: Ruleset Definition and Use. * *syn-ignore-whitespace*: Ruleset Definition and Use. * *timezone*: Time Zone. -* batch:platform: Batch. -* catalog-id: Base Table. +* atm-hec-polynomial: Cyclic Checksum. +* bottomedge: Legending. | * char-code-limit: Configuration. -* charplot:height: Plotting. -* charplot:width: Plotting. -* column-domains: Table Operations. -* column-foreigns: Table Operations. -* column-names: Table Operations. -* column-types: Table Operations. +* charplot:dimensions: Character Plotting. | +* CIEXYZ:A: Color Conversions. +* CIEXYZ:B: Color Conversions. +* CIEXYZ:C: Color Conversions. +* CIEXYZ:D50: Color Conversions. +* CIEXYZ:D65: Color Conversions. +* CIEXYZ:E: Color Conversions. | +* crc-08-polynomial: Cyclic Checksum. +* crc-10-polynomial: Cyclic Checksum. +* crc-12-polynomial: Cyclic Checksum. +* crc-16-polynomial: Cyclic Checksum. +* crc-32-polynomial: Cyclic Checksum. +* crc-ccitt-polynomial: Cyclic Checksum. +* D50: Color Data-Type. +* D65: Color Data-Type. * daylight?: Time Zone. * debug:max-count: Trace. * distribute*: Commutative Rings. * distribute/: Commutative Rings. +* dowcrc-polynomial: Cyclic Checksum. +* graph:dimensions: Legacy Plotting. | +* graphrect: Rectangles. | +* leftedge: Legending. | * most-positive-fixnum: Configuration. -* nil: Legacy. +* nil: Miscellany. * number-wt-type: Construction of Weight-Balanced Trees. -* primary-limit: Table Operations. +* plotrect: Rectangles. | * prime:prngs: Prime Numbers. * prime:trials: Prime Numbers. +* rightedge: Legending. | * slib:form-feed: Configuration. * slib:tab: Configuration. * stderr: Standard Formatted I/O. * stdin: Standard Formatted I/O. * stdout: Standard Formatted I/O. * string-wt-type: Construction of Weight-Balanced Trees. -* t: Legacy. +* t: Miscellany. * tok:decimal-digits: Token definition. * tok:lower-case: Token definition. * tok:upper-case: Token definition. * tok:whitespaces: Token definition. +* topedge: Legending. | * tzname: Time Zone. +* usb-token-polynomial: Cyclic Checksum. Concept and Feature Index ************************* * Menu: +* aggregate <1>: Module Semantics. | +* aggregate: Library Catalogs. | +* alarm: Multi-Processing. | +* alarm-interrupt: Multi-Processing. | * alist: Association Lists. -* alist-table <1>: Creating and Opening Relational Databases. +* alist-table <1>: Relational Database Objects. +* alist-table <2>: The Base. | * alist-table: Base Table. -* ange-ftp: System Interface. +* ange-ftp: URI. +* appearance: Solid Modeling. * array: Arrays. * array-for-each: Array Mapping. +* association function: Association Lists. | * attribute-value: HTML. +* Auto-sharing: Using Databases. * balanced binary trees: Weight-Balanced Trees. * base: URI. +* base-table: Base Table. * batch: Batch. +* binary: Byte. * binary trees: Weight-Balanced Trees. * binary trees, as discrete maps: Weight-Balanced Trees. * binary trees, as sets: Weight-Balanced Trees. +* binding power: Precedence Parsing Overview. * break: Breakpoints. * byte: Byte. +* byte-number: Byte/Number Conversions. | * calendar time <1>: Posix Time. * calendar time: Time and Date. * Calendar-Time: Posix Time. * caltime: Posix Time. +* canonical: Color Names. * careful: Commutative Rings. -* catalog: Requesting Features. +* catalog: Require. | * Catalog File: Library Catalogs. -* cgi: HTTP and CGI. | +* certificate: Transactions. +* cgi: HTTP and CGI. * chapter-order: Chapter Ordering. -* charplot: Plotting. +* charplot: Character Plotting. | +* Chroma: Color Spaces. +* cie1931: Spectra. +* cie1964: Spectra. +* ciexyz: Spectra. +* CIEXYZ: Color Spaces. +* cksum-string: Cyclic Checksum. | * coerce: Type Coercion. * collect: Collections. +* color-database: Color Names. | +* color-names: Color Names. | * command line: Command Line. -* commentfix: Precedence Parsing Overview. +* commentfix: Rule Types. * common-list-functions <1>: Common List Functions. * common-list-functions: Collections. * commutative-ring: Commutative Rings. +* compiled: Library Catalogs. | +* compiling: Module Conventions. | * Coordinated Universal Time: Posix Time. -* database-utilities <1>: Database Utilities. -* database-utilities: Batch. +* copyright: Copyrights. +* crc: Cyclic Checksum. +* cvs: CVS. +* database-commands: Command Example. +* databases <1>: Command Example. +* databases <2>: Define-tables Example. +* databases <3>: Using Databases. +* databases: Batch. +* daylight: Daylight. +* db->html: HTML Tables. | * debug <1>: Breakpoints. * debug: Debug. +* defmacro: Library Catalogs. | * defmacroexpand <1>: Pretty-Print. * defmacroexpand: Defmacro. -* delim: Precedence Parsing Overview. -* diff: Sequence Comparison. | +* delim: Rule Types. +* dequeues: Queues. | +* determinant: Matrix Algebra. | +* diff: Sequence Comparison. +* directory: Directories. | +* Discrete Fourier Transform: Fast Fourier Transform. | * discrete maps, using binary trees: Weight-Balanced Trees. * DrScheme: Installation. * dynamic: Dynamic Data Type. * dynamic-wind: Dynamic-Wind. +* e-sRGB: Color Spaces. +* emacs: Transactions. +* Encapsulated-PostScript: PostScript Graphing. | * escaped: URI. * Euclidean Domain: Commutative Rings. +* eval: Eval. +* exchanger: Miscellany. * factor: Prime Numbers. * feature <1>: About this manual. -* feature <2>: Requesting Features. +* feature <2>: Require. | * feature: Feature. * fft: Fast Fourier Transform. -* fluid-let <1>: Database Utilities. +* File Transfer Protocol: URI. +* file-lock: Transactions. +* filename: Filenames. * fluid-let: Fluid-Let. * form: HTML. * format: Format. +* gamut: Color Spaces. * generic-write: Generic-Write. -* getit: System Interface. -* getopt <1>: Database Utilities. +* getit: URI. +* getopt <1>: Command Example. * getopt: Getopt. +* getopt-parameters <1>: Command Example. +* getopt-parameters: Getopt Parameter lists. * glob <1>: Batch. * glob: Filenames. -* Guile: Installation. | +* Gray code: Bit-Twiddling. +* Guile: Installation. * hash: Hashing. * hash-table: Hash Tables. +* Hilbert: Peano-Hilbert Space-Filling Curve. +* hilbert-fill: Peano-Hilbert Space-Filling Curve. * HOME <1>: Vicinity. -* HOME: Library Catalogs. -* homecat: Catalog Compilation. -* html-form: HTML. | -* http: HTTP and CGI. | -* implcat: Catalog Compilation. -* infix: Precedence Parsing Overview. -* inmatchfix: Precedence Parsing Overview. +* HOME: Catalog Creation. | +* homecat: Catalog Vicinities. | +* html-for-each: Parsing HTML. +* html-form: HTML. +* http: HTTP and CGI. +* Hue: Color Spaces. +* ICC Profile: Color Spaces. +* implcat: Catalog Vicinities. | +* indexed-sequential-access-method: Byte/Number Conversions. | +* infix: Rule Types. +* Info: Top-level Variable References. | +* inmatchfix: Rule Types. +* install: Installation. | +* installation: Installation. | +* intrinsic feature: Feature. | +* ISAM: Indexed Sequential Access Methods. | +* L*a*b*: Color Spaces. +* L*C*h: Color Spaces. +* L*u*v*: Color Spaces. * Left Denotation, led: Nud and Led Definition. +* Lightness: Color Spaces. * line-i: Line I/O. -* list-processing library: SRFI-1. | +* list-processing library: SRFI-1. +* load-option: Weight-Balanced Trees. | * logical: Bit-Twiddling. * macro <1>: Repl. -* macro: R4RS Macros. -* macro-by-example: Macro by Example. -* macros-that-work: Macros That Work. -* make-crc: Cyclic Checksum. -* match: Base Table. -* match-keys <1>: Table Operations. -* match-keys: Base Table. -* matchfix: Precedence Parsing Overview. +* macro <2>: R4RS Macros. | +* macro: Library Catalogs. | +* macro-by-example <1>: Macro by Example. | +* macro-by-example: Library Catalogs. | +* macros-that-work <1>: Macros That Work. | +* macros-that-work: Library Catalogs. | +* manifest: Module Manifests. | +* match: Match Keys. | +* match-keys <1>: Match Keys. | +* match-keys: Match-Keys. | +* matchfix: Rule Types. +* matfile: MAT-File Format. +* matlab: MAT-File Format. * metric-units: Metric Units. * minimize: Minimizing. * minimum field width (printf): Standard Formatted Output. -* MIT Scheme: Installation. | -* mkimpcat.scm: Catalog Compilation. -* mklibcat.scm: Catalog Compilation. +* MIT Scheme: Installation. +* mkimpcat.scm: Catalog Vicinities. | +* mklibcat.scm: Catalog Vicinities. | * modular: Modular Arithmetic. +* multiarg: Multi-argument / and -. * multiarg-apply: Multi-argument Apply. -* mutliarg: Multi-argument / and -. * MzScheme: Installation. -* nary: Precedence Parsing Overview. -* net-clients: System Interface. -* new-catalog: Catalog Compilation. -* nofix: Precedence Parsing Overview. +* nary: Rule Types. +* new-catalog: Catalog Creation. | +* nofix: Rule Types. * null: HTML Tables. * Null Denotation, nud: Nud and Led Definition. * object: Object. @@ -12259,20 +16083,30 @@ Concept and Feature Index * oop: Yasos. * option, run-time-loadable: Weight-Balanced Trees. * options file: Command Line. -* parameters <1>: Database Utilities. +* parameters <1>: Command Example. * parameters <2>: Batch. * parameters: Parameter lists. * parse: Precedence Parsing. +* pbm: Portable Image Files. +* pbm-raw: Portable Image Files. +* Peano: Peano-Hilbert Space-Filling Curve. +* Peano-Hilbert Space-Filling Curve: Peano-Hilbert Space-Filling Curve. +* pgm: Portable Image Files. +* pgm-raw: Portable Image Files. * plain-text: HTML. * PLT Scheme: Installation. +* pnm: Portable Image Files. | +* portable bitmap graphics: Portable Image Files. | * posix-time: Posix Time. -* postfix: Precedence Parsing Overview. +* postfix: Rule Types. +* ppm: Portable Image Files. +* ppm-raw: Portable Image Files. * pprint-file: Pretty-Print. * PRE: HTML. * precedence: Precedence Parsing. * precision (printf): Standard Formatted Output. -* prefix: Precedence Parsing Overview. -* prestfix: Precedence Parsing Overview. +* prefix: Rule Types. +* prestfix: Rule Types. * pretty-print: Pretty-Print. * primes: Prime Numbers. * printf: Standard Formatted Output. @@ -12284,230 +16118,344 @@ Concept and Feature Index * qp: Getopt. * query-string: HTTP and CGI. * queue: Queues. -* random: Random Numbers. +* r2rs: RnRS. +* r3rs <1>: Coding Guidelines. | +* r3rs: RnRS. +* r4rs: RnRS. +* r5rs: RnRS. +* random: Exact Random Numbers. | +* random-inexact: Inexact Random Numbers. | +* range: Column Ranges. | * rationalize: Rationalize. * read-command: Command Line. * record: Records. +* rectangle: Rectangles. | * relational-database: Relational Database. +* relational-system: Using Databases. | * repl <1>: Repl. * repl: Syntax-Case Macros. +* resene: Color Names. +* Resene: Color Names. * reset: HTML. -* rev2-procedures: Rev2 Procedures. -* rev3-report: Coding Guidelines. +* rev2-procedures: Rev2 Procedures. | * rev4-optional-procedures: Rev4 Optional Procedures. +* RGB709: Color Spaces. * ring, commutative: Commutative Rings. * RNG: Random Numbers. * root: Root Finding. * run-time-loadable option: Weight-Balanced Trees. +* rwb-isam: Base Table. | +* saturate: Color Names. * scanf: Standard Formatted Input. -* Scheme Request For Implementation: SRFI. | +* scheme: URI. +* Scheme Request For Implementation: SRFI. * Scheme48: Installation. * schmooz: Schmooz. * SCM: Installation. -* self-set: Commutative Rings. | -* Sequence Comparison: Sequence Comparison. | +* self-set: Commutative Rings. +* Sequence Comparison: Sequence Comparison. * Server-based Naming Authority: URI. * session: Feature. * sets, using binary trees: Weight-Balanced Trees. -* sierpinski: Hashing. -* sitecat: Catalog Compilation. -* slibcat: Catalog Compilation. +* shell: Command Line. | +* sierpinski: Sierpinski Curve. +* sitecat: Catalog Vicinities. | +* sky: Daylight. +* slibcat: Catalog Vicinities. | +* solid: Solid Modeling. +* solid-modeling: Solid Modeling. +* solids: Solid Modeling. * sort: Sorting. -* soundex: Hashing. -* spiff: Sequence Comparison. | -* srfi: SRFI. | -* SRFI-1: SRFI-1. | -* srfi-1: SRFI-1. | +* soundex: Soundex. +* source: Library Catalogs. | +* Space-Filling: Peano-Hilbert Space-Filling Curve. +* sparse: MAT-File Format. +* Spectral Tristimulus Values: Spectra. +* spiff: Sequence Comparison. +* srfi: SRFI. +* SRFI-1: SRFI-1. +* srfi-1: SRFI-1. +* srfi-2: SRFI-2. | +* srfi-8: SRFI-8. | +* srfi-9: SRFI-9. | +* sRGB: Color Spaces. * stdio: Standard Formatted I/O. * string-case: String-Case. * string-port: String Ports. -* string-search: String Search. | -* syntactic-closures: Syntactic Closures. -* syntax-case: Syntax-Case Macros. +* string-search: String Search. +* subarray: Subarrays. +* sun: Daylight. +* sunlight: Daylight. +* symmetric: Modular Arithmetic. | +* syntactic-closures <1>: Syntactic Closures. | +* syntactic-closures: Library Catalogs. | +* syntax tree: Precedence Parsing Overview. +* syntax-case <1>: Syntax-Case Macros. | +* syntax-case: Library Catalogs. | * time: Time and Date. * time-zone: Time Zone. +* top-level variable references: Top-level Variable References. | +* top-refs: Top-level Variable References. | * topological-sort: Topological Sort. * trace: Trace. +* transact: Transactions. * transcript: Transcripts. * tree: Tree Operations. * trees, balanced binary: Weight-Balanced Trees. +* tristimulus: Color Spaces. * tsort: Topological Sort. +* turbidity: Daylight. * TZ-string: Time Zone. * Uniform Resource Identifiers: URI. -* Uniform Resource Locator: System Interface. +* Uniform Resource Locator: URI. * Unique Factorization: Commutative Rings. * unsafe: URI. -* uri: URI. | +* URI: URI. +* uri: URI. * URI: HTTP and CGI. -* usercat: Catalog Compilation. +* usercat: Catalog Vicinities. | * UTC: Posix Time. * values: Values. +* variable references: Top-level Variable References. | +* vet: Module Analysis. | * VSCM: Installation. +* WB: Base Table. +* wb-table: Base Table. * weight-balanced binary trees: Weight-Balanced Trees. -* wild-card: Base Table. +* wget: Color Names. +* white point: Color Data-Type. +* wild-card: Match Keys. | * with-file: With-File. +* Word: Transactions. * wt-tree: Weight-Balanced Trees. +* xRGB: Color Spaces. +* xyY: Spectra. * yasos: Yasos. Tag Table: -Node: Top1026 -Node: The Library System1740 -Node: Feature2054 -Node: Requesting Features3004 -Node: Library Catalogs4363 -Node: Catalog Compilation6815 -Node: Built-in Support9624 -Node: Require10255 -Node: Vicinity12747 -Node: Configuration15714 -Node: Input/Output18655 -Node: Legacy20254 -Node: System21096 -Node: About this manual23588 -Node: Scheme Syntax Extension Packages24145 -Node: Defmacro24837 -Node: R4RS Macros26788 -Node: Macro by Example28043 -Node: Macros That Work30922 -Node: Syntactic Closures36980 -Node: Syntax-Case Macros54414 -Node: Fluid-Let58605 -Node: Yasos59546 -Node: Yasos terms60339 -Node: Yasos interface61363 -Node: Setters63438 -Node: Yasos examples66079 -Node: Textual Conversion Packages69073 -Node: Precedence Parsing69751 -Node: Precedence Parsing Overview70414 -Ref: Precedence Parsing Overview-Footnote-172337 -Node: Ruleset Definition and Use72615 -Node: Token definition74996 -Node: Nud and Led Definition77265 -Node: Grammar Rule Definition79714 -Node: Format87288 -Node: Format Interface87536 -Node: Format Specification89273 -Node: Standard Formatted I/O99328 -Node: Standard Formatted Output99894 -Node: Standard Formatted Input109617 -Node: Programs and Arguments116277 -Node: Getopt116777 -Node: Command Line122619 -Node: Parameter lists125808 -Node: Getopt Parameter lists129695 -Node: Filenames132950 -Node: Batch136180 -Node: HTML143973 -Node: HTML Tables150074 -Node: HTTP and CGI156483 -Node: URI161013 -Node: Printing Scheme163686 -Node: Generic-Write163995 -Node: Object-To-String165398 -Node: Pretty-Print165802 -Node: Time and Date168765 -Node: Time Zone169792 -Node: Posix Time174353 -Node: Common-Lisp Time176489 -Node: Vector Graphics178068 -Node: Tektronix Graphics Support178257 -Node: Schmooz179631 -Node: Mathematical Packages183857 -Node: Bit-Twiddling184491 -Node: Modular Arithmetic189082 -Node: Prime Numbers191216 -Node: Random Numbers192899 -Node: Fast Fourier Transform197535 -Node: Cyclic Checksum198453 -Node: Plotting200417 -Node: Root Finding203276 -Node: Minimizing207263 -Ref: Minimizing-Footnote-1208700 -Node: Commutative Rings209303 -Node: Determinant220687 -Node: Database Packages221092 -Node: Base Table221356 -Node: Relational Database231770 -Node: Motivations232554 -Node: Creating and Opening Relational Databases237601 -Node: Relational Database Operations240033 -Node: Table Operations243029 -Node: Catalog Representation250907 -Node: Unresolved Issues253805 -Node: Database Utilities256756 -Node: Database Reports272873 -Node: Database Browser275627 -Node: Weight-Balanced Trees276688 -Node: Construction of Weight-Balanced Trees280559 -Node: Basic Operations on Weight-Balanced Trees284009 -Node: Advanced Operations on Weight-Balanced Trees286974 -Node: Indexing Operations on Weight-Balanced Trees292996 -Node: Other Packages296910 -Node: Data Structures297389 -Node: Arrays298223 -Node: Array Mapping302100 -Node: Association Lists304017 -Node: Byte306268 -Node: Portable Image Files308508 -Node: Collections310055 -Node: Dynamic Data Type316447 -Node: Hash Tables317708 -Node: Hashing319889 -Node: Object324660 -Node: Priority Queues332896 -Node: Queues333739 -Node: Records334865 -Node: Sorting and Searching338436 -Node: Common List Functions339236 -Node: List construction339761 -Node: Lists as sets341607 -Node: Lists as sequences348573 -Node: Destructive list operations353827 -Node: Non-List functions356490 -Node: Tree Operations357667 -Node: Chapter Ordering359507 -Node: Sorting361217 -Node: Topological Sort367084 -Node: String Search368863 -Node: Sequence Comparison371335 -Node: Procedures377271 -Node: Type Coercion378665 -Node: String-Case379881 -Node: String Ports382059 -Node: Line I/O383592 -Node: Multi-Processing385320 -Node: Metric Units386424 -Node: Standards Support394650 -Node: With-File395385 -Node: Transcripts395661 -Node: Rev2 Procedures395982 -Node: Rev4 Optional Procedures397739 -Node: Multi-argument / and -398309 -Node: Multi-argument Apply399048 -Node: Rationalize399583 -Node: Promises400908 -Node: Dynamic-Wind401325 -Node: Eval402579 -Node: Values405916 -Node: SRFI406795 -Node: SRFI-1409905 -Node: Session Support420362 -Node: Repl420909 -Node: Quick Print422192 -Node: Debug423305 -Node: Breakpoints424191 -Node: Trace426214 -Node: System Interface429325 -Node: Extra-SLIB Packages433079 -Node: About SLIB435381 -Node: Installation436084 -Node: Porting443977 -Ref: Porting-Footnote-1421798 -Node: Coding Guidelines445504 -Node: Copyrights447585 -Node: Index450931 +Node: Top1038 +Node: The Library System1832 +Node: Feature2447 +Node: Require5817 +Node: Library Catalogs9665 +Node: Catalog Creation11330 +Node: Catalog Vicinities14797 +Node: Compiling Scheme19397 +Node: Module Conventions20721 +Ref: Module Conventions-Footnote-115614 +Node: Module Manifests23491 +Node: Module Semantics32652 +Node: Top-level Variable References35341 +Ref: Top-level Variable References-Footnote-124139 +Node: Module Analysis39789 +Node: Universal SLIB Procedures42532 +Node: Vicinity43862 +Node: Configuration47550 +Node: Input/Output50710 +Node: System54238 +Node: Miscellany57523 +Node: Scheme Syntax Extension Packages59694 +Node: Defmacro60439 +Node: R4RS Macros62386 +Node: Macro by Example63639 +Node: Macros That Work66514 +Node: Syntactic Closures72567 +Node: Syntax-Case Macros89995 +Node: Fluid-Let94454 +Node: Yasos95393 +Node: Yasos terms96184 +Node: Yasos interface97208 +Node: Setters99283 +Node: Yasos examples101923 +Node: Textual Conversion Packages104922 +Node: Precedence Parsing105719 +Node: Precedence Parsing Overview106395 +Ref: Precedence Parsing Overview-Footnote-188500 +Node: Rule Types108019 +Node: Ruleset Definition and Use109452 +Node: Token definition111816 +Node: Nud and Led Definition114725 +Node: Grammar Rule Definition117172 +Node: Format124746 +Node: Standard Formatted I/O125156 +Node: Standard Formatted Output125720 +Node: Standard Formatted Input135110 +Node: Programs and Arguments141768 +Node: Getopt142268 +Node: Command Line148891 +Node: Parameter lists152078 +Node: Getopt Parameter lists155963 +Node: Filenames159199 +Node: Batch163646 +Node: HTML171449 +Node: HTML Tables178112 +Node: HTTP and CGI184553 +Node: Parsing HTML189090 +Node: URI191584 +Node: Printing Scheme196704 +Node: Generic-Write197013 +Node: Object-To-String198414 +Node: Pretty-Print198816 +Node: Time and Date201777 +Node: Time Zone202797 +Node: Posix Time207756 +Node: Common-Lisp Time209892 +Node: NCBI-DNA211471 +Node: Schmooz212801 +Node: Mathematical Packages217028 +Node: Bit-Twiddling217744 +Node: Modular Arithmetic225665 +Node: Prime Numbers228534 +Node: Random Numbers230215 +Node: Exact Random Numbers231435 +Node: Inexact Random Numbers234181 +Node: Fast Fourier Transform236532 +Node: Cyclic Checksum237446 +Node: Graphing244571 +Node: Character Plotting245251 +Node: PostScript Graphing251089 +Node: Column Ranges255097 +Node: Drawing the Graph258417 +Node: Graphics Context263014 +Node: Rectangles267208 +Node: Legending270354 +Node: Legacy Plotting274779 +Node: Example Graph276487 +Node: Solid Modeling284587 +Node: Color300794 +Node: Color Data-Type301620 +Ref: Color Data-Type-Footnote-1261941 +Node: Color Spaces305581 +Ref: Color Spaces-Footnote-1271875 +Node: Spectra315434 +Node: Color Difference Metrics323004 +Node: Color Conversions326666 +Node: Color Names329317 +Node: Daylight336339 +Node: Root Finding341138 +Node: Minimizing345119 +Ref: Minimizing-Footnote-1301934 +Node: Commutative Rings347157 +Node: Matrix Algebra358549 +Node: Database Packages359679 +Node: Relational Database360087 +Node: Using Databases361118 +Node: Table Operations369657 +Node: Single Row Operations371774 +Node: Match-Keys375050 +Node: Multi-Row Operations378335 +Node: Indexed Sequential Access Methods381431 +Node: Sequential Index Operations383339 +Node: Table Administration387317 +Node: Database Interpolation388727 +Node: Embedded Commands390241 +Node: Database Extension391882 +Node: Command Intrinsics393982 +Node: Define-tables Example395584 +Node: The *commands* Table397396 +Node: Command Service399709 +Node: Command Example401654 +Node: Database Macros406303 +Node: Within-database Example408933 +Node: Database Browser410852 +Node: Relational Infrastructure412730 +Node: Base Table413507 +Node: The Base418368 +Node: Base Tables422788 +Node: Base Field Types425445 +Node: Composite Keys426988 +Node: Base Record Operations430382 +Node: Match Keys433530 +Node: Aggregate Base Operations435329 +Node: Base ISAM Operations437366 +Node: Catalog Representation439784 +Node: Relational Database Objects445280 +Node: Database Operations449505 +Node: Weight-Balanced Trees455859 +Node: Construction of Weight-Balanced Trees459813 +Node: Basic Operations on Weight-Balanced Trees463261 +Node: Advanced Operations on Weight-Balanced Trees466187 +Node: Indexing Operations on Weight-Balanced Trees472207 +Node: Other Packages476032 +Node: Data Structures476583 +Node: Arrays477400 +Node: Subarrays482891 +Node: Array Mapping486245 +Node: Association Lists488990 +Node: Byte491241 +Node: Byte/Number Conversions499604 +Node: MAT-File Format511631 +Node: Portable Image Files512974 +Node: Collections514601 +Node: Dynamic Data Type520757 +Node: Hash Tables522016 +Node: Object524916 +Node: Priority Queues533150 +Node: Queues534217 +Node: Records535855 +Node: Sorting and Searching539345 +Node: Common List Functions540030 +Node: List construction540474 +Node: Lists as sets542169 +Node: Lists as sequences548782 +Node: Destructive list operations554036 +Node: Non-List functions556705 +Node: Tree Operations557775 +Node: Chapter Ordering559541 +Node: Sorting561170 +Node: Topological Sort567171 +Node: Hashing568864 +Node: Space-Filling Curves569865 +Node: Peano-Hilbert Space-Filling Curve570085 +Node: Sierpinski Curve571277 +Node: Soundex573731 +Node: String Search575345 +Node: Sequence Comparison578018 +Node: Procedures581424 +Node: Type Coercion581944 +Node: String-Case582361 +Node: String Ports584209 +Node: Line I/O584966 +Node: Multi-Processing587018 +Node: Metric Units588120 +Node: Standards Support596342 +Node: RnRS597171 +Node: With-File598378 +Node: Transcripts598639 +Node: Rev2 Procedures598958 +Node: Rev4 Optional Procedures600666 +Node: Multi-argument / and -601234 +Node: Multi-argument Apply601748 +Node: Rationalize602150 +Node: Promises603412 +Node: Dynamic-Wind604467 +Node: Eval605719 +Node: Values609054 +Node: SRFI609852 +Node: SRFI-1611285 +Node: SRFI-2617429 +Node: SRFI-8618223 +Node: SRFI-9619017 +Node: Session Support620436 +Node: Repl620913 +Node: Quick Print622194 +Node: Debug623483 +Node: Breakpoints624367 +Node: Trace626388 +Node: System Interface629792 +Node: Directories630353 +Node: Transactions631828 +Node: CVS637524 +Node: Extra-SLIB Packages638596 +Node: About SLIB640897 +Node: Installation641640 +Node: Porting646734 +Ref: Porting-Footnote-1555316 +Node: Coding Guidelines648663 +Node: Copyrights651753 +Node: About this manual655155 +Node: Index656435 End Tag Table |