This is slib.info, produced by makeinfo version 4.8 from slib.texi. This manual is for SLIB (version 3b1, February 2008), the portable | Scheme library. Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. | Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License." INFO-DIR-SECTION The Algorithmic Language Scheme START-INFO-DIR-ENTRY * SLIB: (slib). Scheme Library END-INFO-DIR-ENTRY  File: slib.info, Node: Top, Next: The Library System, Prev: (dir), Up: (dir) SLIB **** This manual is for SLIB (version 3b1, February 2008), the portable | Scheme library. Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. | Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License." * 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:: * Database Packages:: * Other Packages:: * About SLIB:: Install, etc. * Index::  File: slib.info, Node: The Library System, Next: Universal SLIB Procedures, Prev: Top, Up: Top 1 The Library System ******************** "SLIB" is a portable library for the programming language "Scheme". It provides a platform independent framework for using "packages" of Scheme procedures and syntax. As distributed, SLIB contains useful packages for all Scheme implementations. Its catalog can be transparently extended to accomodate packages specific to a site, implementation, user, or directory. * Menu: * Feature:: SLIB names. * Require:: * Library Catalogs:: * Catalog Creation:: * Catalog Vicinities:: * Compiling Scheme::  File: slib.info, Node: Feature, Next: Require, Prev: The Library System, Up: The Library System 1.1 Feature =========== SLIB denotes "features" by symbols. SLIB maintains a list of features 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 * 'rational * 'real * 'complex * 'bignum 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 present in the current Scheme session; otherwise `#f'. More specifically, `provided?' returns `#t' if the symbol FEATURE is the `software-type', the `scheme-implementation-type' (1), 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 in this session. (provided? 'foo) => #f (provide 'foo) (provided? 'foo) => #t ---------- Footnotes ---------- (1) scheme-implementation-type is the name symbol of the running Scheme implementation (RScheme, |STk|, Bigloo, chez, Elk, gambit, guile, JScheme, kawa, MacScheme, MITScheme, Pocket-Scheme, Scheme48, Scheme->C, Scheme48, Scsh, SISC, T, umb-scheme, or Vscm). Dependence on scheme-implementation-type is almost always the wrong way to do things.  File: slib.info, Node: Require, Next: Library Catalogs, Prev: Feature, Up: The Library System 1.2 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. 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. * Otherwise, if FEATURE is found in the catalog, then the 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. There is a related form `require-if', used primarily for enabling compilers to statically include modules which would be dynamically loaded by interpreters. -- Procedure: require-if condition feature Requires FEATURE if CONDITION is true. The `random' module uses `require-if' to flag `object->string' as a (dynamic) required module. (require 'byte) (require 'logical) (require-if 'compiling 'object->string) The `batch' module uses `require-if' to flag `posix-time' as a module to load if the implementation supports large precision exact integers. (require-if '(and bignum compiling) 'posix-time) The catalog can also be queried using `slib:in-catalog?'. -- 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::.  File: slib.info, Node: Library Catalogs, Next: Catalog Creation, Prev: Require, Up: The Library System 1.3 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 latter list's association is retrieved. Here are the supported formats for elements of catalog lists: `(FEATURE . )' Redirects to the feature named . `(FEATURE . "")' Loads file . `(FEATURE source "")' `slib:load's the Scheme source file . `(FEATURE compiled "" ...)' `slib:load-compiled's the files .... `(FEATURE aggregate ...)' `require's the features .... The various macro styles first `require' the named macro package, then just load or load-and-macro-expand as appropriate for the implementation. `(FEATURE defmacro "")' `defmacro:load's the Scheme source file . `(FEATURE macro-by-example "")' `defmacro:load's the Scheme source file . `(FEATURE macro "")' `macro:load's the Scheme source file . `(FEATURE macros-that-work "")' `macro:load's the Scheme source file . `(FEATURE syntax-case "")' `macro:load's the Scheme source file . `(FEATURE syntactic-closures "")' `macro:load's the Scheme source file .  File: slib.info, Node: Catalog Creation, Next: Catalog Vicinities, Prev: Library Catalogs, Up: The Library System 1.4 Catalog Creation ==================== 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: * standard SLIB packages. * 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' needs change only when new software is installed or compiled. Because the actual pathnames of files can differ from installation to installation, SLIB builds a separate catalog for each implementation it 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. 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 `require' of a special feature: -- Procedure: require 'new-catalog This will load `mklibcat', which compiles and writes a new `slibcat'. 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 1.5 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. `implementation-vicinity' `slibcat' This file contains the associations for the packages comprising SLIB, the `implcat' and the `sitecat's. The associations in the other catalogs override those of the standard catalog. `library-vicinity' `mklibcat.scm' creates `slibcat'. `library-vicinity' `sitecat' This file contains the associations specific to an SLIB installation. `implementation-vicinity' `implcat' This file contains the associations specific to an implementation of Scheme. Different implementations of Scheme should have different `implementation-vicinity'. `implementation-vicinity' `mkimpcat.scm' if present, creates `implcat'. `implementation-vicinity' `sitecat' This file contains the associations specific to a Scheme implementation installation. `home-vicinity' `homecat' This file contains the associations specific to an SLIB user. `user-vicinity' `usercat' This file contains associations affecting only those sessions whose "working directory" is `user-vicinity'. 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 1.6 Compiling Scheme ==================== 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: * Module Conventions:: * Module Manifests:: * Module Semantics:: * Top-level Variable References:: * Module Analysis::  File: slib.info, Node: Module Conventions, Next: Module Manifests, Prev: Compiling Scheme, Up: Compiling Scheme 1.6.1 Module Conventions ------------------------ * All the top-level `require' commands have one quoted argument and are positioned before other Scheme definitions and expressions in the file. * 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.). (require 'logical) (require 'multiarg/and-) (require-if 'compiling 'sort) (require-if 'compiling 'ciexyz) * 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. ;@ (define (identity ) ) * Syntax (macro) definitions are grouped at the end of a module file. * Modules defining macros do not invoke those macros. SLIB macro implementations are exempt from this rule. An example of how to expand macro invocations is: (require 'macros-that-work) (require 'yasos) (require 'pprint-file) (pprint-filter-file "collect.scm" macwork:expand) ---------- Footnotes ---------- (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.  File: slib.info, Node: Module Manifests, Next: Module Semantics, Prev: Module Conventions, Up: Compiling Scheme 1.6.2 Module Manifests ---------------------- `(require 'manifest)' 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: feature->requires* feature provided? catalog Returns a list of the features transitively `require'd by FEATURE assuming the predicate PROVIDED? and association-list CATALOG. -- Function: file->requires* file provided? catalog Returns a list of the features transitively `require'd by FILE assuming the predicate PROVIDED? and association-list CATALOG. -- 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 ')', where is a string or vicinity stuff), `(load->path )' 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 definer ... Returns a list of the identifier symbols defined by SLIB (or SLIB-style) file FILE. The optional arguments DEFINERS should be symbols signifying a defining form. If none are supplied, then the symbols `define-operation', `define', `define-syntax', and `defmacro' are captured. (file->definitions "random.scm") => (*random-state* make-random-state seed->random-state copy-random-state random random:chunk) -- Function: file->exports file definer ... Returns a list of the identifier symbols exported (advertised) by SLIB (or SLIB-style) file FILE. The optional arguments DEFINERS should be symbols signifying a defining form. If none are supplied, then the symbols `define-operation', `define', `define-syntax', and `defmacro' are captured. (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: Module Semantics, Next: Top-level Variable References, Prev: Module Manifests, Up: Compiling Scheme 1.6.3 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 1.6.4 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. #f is returned if the index is not found. 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 1.6.5 Module Analysis --------------------- `(require 'vet)' -- Function: vet-slib file1 ... Using the procedures in the `top-refs' and `manifest' modules, `vet-slib' analyzes each SLIB module and FILE1, ..., 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. The optional arguments FILE1, ... provide a simple way to vet prospective SLIB modules.  File: slib.info, Node: Universal SLIB Procedures, Next: Scheme Syntax Extension Packages, Prev: The Library System, Up: Top 2 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 2.1 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 version. Vicinities express only the concept of a file environment where a file name can be resolved to a file in a system independent manner. Vicinities can even be used on "flat" file systems (which have no directory structure) by having the vicinity express constraints on the file name. All of these procedures are file-system dependent. Use of these vicinity procedures can make programs file-system _in_dependent. These procedures are provided by all implementations. On most systems a vicinity is a string. -- 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 interpreter this would be the directory containing source code. For a compiled system (with multiple files) this would be the directory where the object or executable files are. If no file is currently loading, then the result is undefined. *Warning:* `program-vicinity' can return incorrect values if your program escapes back into a `load' continuation. -- Function: library-vicinity Returns the vicinity of the shared Scheme library. -- Function: implementation-vicinity Returns the vicinity of the underlying Scheme implementation. This vicinity will likely contain startup code and messages and a compiler. -- Function: user-vicinity Returns the vicinity of the current directory of the user. On most systems this is `""' (the empty string). -- Function: home-vicinity Returns the vicinity of the user's "HOME" directory, the directory which typically contains files which customize a computer environment for a user. If scheme is running without a user (eg. 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', `open-output-file', etc. The returned filename is FILENAME in VICINITY. `in-vicinity' should allow FILENAME to override VICINITY when FILENAME is an absolute pathname and VICINITY is equal to the value of `(user-vicinity)'. The behavior of `in-vicinity' when FILENAME is absolute and VICINITY is not equal to the value of `(user-vicinity)' is unspecified. For most systems `in-vicinity' can be `string-append'. -- Function: sub-vicinity vicinity name Returns the vicinity of VICINITY restricted to NAME. This is used for large systems where names of files in subsystems could conflict. On systems with directory structure `sub-vicinity' will return a pathname of the subdirectory NAME of VICINITY. -- Function: with-load-pathname path thunk PATH should be a string naming a file being read or loaded. `with-load-pathname' evaluates THUNK in a dynamic scope where an internal variable is bound to PATH; the internal variable is used for messages and `program-vicinity'. `with-load-pathname' returns the value returned by THUNK.  File: slib.info, Node: Configuration, Next: Input/Output, Prev: Vicinity, Up: Universal SLIB Procedures 2.2 Configuration ================= These constants and procedures describe characteristics of the Scheme and underlying operating system. They are provided by all implementations. -- Constant: char-code-limit An integer 1 larger that the largest value which can be returned by `char->integer'. -- Constant: most-positive-fixnum In implementations which support integers of practically unlimited size, MOST-POSITIVE-FIXNUM is a large exact integer within the range of exact integers that may result from computing the length of a list, vector, or string. In implementations which do not support integers of practically unlimited size, MOST-POSITIVE-FIXNUM is the largest exact integer that may result from computing the length of a list, vector, or string. -- Constant: slib:tab The tab character. -- Constant: slib:form-feed The form-feed character. -- Function: software-type Returns a symbol denoting the generic operating system type. For instance, `unix', `vms', `macos', `amiga', or `ms-dos'. -- Function: slib:report-version Displays the versions of SLIB and the underlying Scheme implementation and the name of the operating system. An unspecified value is returned. (slib:report-version) => slib "3b1" on scm "5b1" on unix | -- Function: slib:report Displays the information of `(slib:report-version)' followed by almost all the information neccessary for submitting a problem report. An unspecified value is returned. -- Function: slib:report #t provides a more verbose listing. -- Function: slib:report filename Writes the report to file `filename'. (slib:report) => slib "3b1" 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 slib:features : trace alist qp sort common-list-functions macro values getopt compiled implementation slib:features : bignum complex real rational inexact vicinity ed getenv tmpnam abort transcript with-file 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 rev3-procedures rev2-procedures sun-dl string-case array dump char-ready? full-continuation system implementation *catalog* : (i/o-extensions compiled "/usr/local/lib/scm/ioext.so") ...  File: slib.info, Node: Input/Output, Next: System, Prev: Configuration, Up: Universal SLIB Procedures 2.3 Input/Output ================ These procedures are provided by all implementations. -- 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. -- Function: delete-file filename Deletes the file specified by FILENAME. If FILENAME can not be deleted, `#f' is returned. Otherwise, `#t' is returned. -- 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. -- Function: current-error-port Returns the current port to which diagnostic and error output is directed. -- Procedure: force-output -- Procedure: force-output port Forces any pending output on PORT to be delivered to the output device 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: file-position port -- Function: file-position port #f PORT must be open to a file. `file-position' returns the current position of the character in PORT which will next be read or written. If the implementation does not support file-position, then `#f' is returned. -- Function: file-position port k PORT must be open to a file. `file-position' sets the current position in PORT which will next be read or written. If successful, `#f' is returned; otherwise `file-position' returns `#f'. -- 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. -- 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: System, Next: Miscellany, Prev: Input/Output, Up: Universal SLIB Procedures 2.4 System ========== These procedures are provided by all implementations. -- Procedure: slib:load-source name Loads a file of Scheme source code from NAME with the default filename extension used in SLIB. For instance if the filename extension used in SLIB is `.scm' then `(slib:load-source "foo")' will load from file `foo.scm'. -- Procedure: slib:load-compiled name On implementations which support separtely loadable compiled modules, loads a file of compiled code from NAME with the implementation's filename extension for compiled code appended. -- Procedure: slib:load name Loads a file of Scheme source or compiled code from NAME with the appropriate suffixes appended. If both source and compiled code are present with the appropriate names then the implementation will load just one. It is up to the implementation to choose which one will be loaded. If an implementation does not support compiled code then `slib:load' will be identical to `slib:load-source'. -- Procedure: slib:eval obj `eval' returns the value of OBJ evaluated in the current top level environment. *Note Eval:: provides a more general evaluation facility. -- Procedure: slib:eval-load filename eval FILENAME should be a string. If filename names an existing file, the Scheme source code expressions and definitions are read from the file and EVAL called with them sequentially. The `slib:eval-load' procedure does not affect the values returned by `current-input-port' and `current-output-port'. -- Procedure: slib:warn arg1 arg2 ... Outputs a warning message containing the arguments. -- Procedure: slib:error arg1 arg2 ... Outputs an error message containing the arguments, aborts evaluation of the current form and responds in a system dependent way to the error. Typical responses are to abort the program or to enter a read-eval-print loop. -- Procedure: slib:exit n -- Procedure: slib:exit Exits from the Scheme session returning status N to the system. If N is omitted or `#t', a success status is returned to the system (if possible). If N is `#f' a failure is returned to the system (if possible). If N is an integer, then N is returned to the system (if possible). If the Scheme session cannot exit, then 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 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 (if no browser) it returns `#f'.  File: slib.info, Node: Miscellany, Prev: System, Up: Universal SLIB Procedures 2.5 Miscellany ============== 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) 2.5.1 Mutual Exclusion ---------------------- 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 2.5.2 Legacy ------------ The following procedures were present in Scheme until R4RS (*note Language changes: (r4rs)Notes.). They are provided by all SLIB implementations. -- Constant: t Defined 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 3 Scheme Syntax Extension Packages ********************************** * Menu: * Defmacro:: Supported by all implementations * R4RS Macros:: 'macro * Macro by Example:: 'macro-by-example * Macros That Work:: 'macros-that-work * Syntactic Closures:: 'syntactic-closures * Syntax-Case Macros:: 'syntax-case Syntax extensions (macros) included with SLIB. * Define-Structure:: 'structure * Define-Record-Type:: 'define-record-type, 'srfi-9 * Fluid-Let:: 'fluid-let * Binding to multiple values:: 'receive, 'srfi-8 * Guarded LET* special form:: 'and-let*, 'srfi-2 * Guarded COND Clause:: 'guarded-cond-clause, 'srfi-61 * Yasos:: 'yasos, 'oop, 'collect  File: slib.info, Node: Defmacro, Next: R4RS Macros, Prev: Scheme Syntax Extension Packages, Up: Scheme Syntax Extension Packages 3.1 Defmacro ============ Defmacros are supported by all implementations. -- Function: gentemp Returns a new (interned) symbol each time it is called. The symbol names are implementation-dependent (gentemp) => scm:G0 (gentemp) => scm:G1 -- Function: defmacro:eval e Returns the `slib:eval' of expanding all defmacros in scheme expression E. -- Function: defmacro:load filename FILENAME should be a string. If filename names an existing file, the `defmacro:load' procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain defmacro definitions. The `macro:load' procedure does not affect the values returned by `current-input-port' and `current-output-port'. -- Function: defmacro? sym Returns `#t' if SYM has been defined by `defmacro', `#f' otherwise. -- Function: macroexpand-1 form -- Function: macroexpand form If FORM is a macro call, `macroexpand-1' will expand the macro call once and return it. A FORM is considered to be a macro call only if it is a cons whose `car' is a symbol for which a `defmacro' has been defined. `macroexpand' is similar to `macroexpand-1', but repeatedly expands FORM until it is no longer a macro call. -- Macro: defmacro name lambda-list form ... When encountered by `defmacro:eval', `defmacro:macroexpand*', or `defmacro:load' defines a new macro which will henceforth be expanded when encountered by `defmacro:eval', `defmacro:macroexpand*', or `defmacro:load'. 3.1.1 Defmacroexpand -------------------- `(require 'defmacroexpand)' -- Function: defmacro:expand* e Returns the result of expanding all defmacros in scheme expression E.  File: slib.info, Node: R4RS Macros, Next: Macro by Example, Prev: Defmacro, Up: Scheme Syntax Extension Packages 3.2 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. Otherwise, one of the R4RS macros implemetations is loaded. The SLIB R4RS macro implementations support the following uniform interface: -- Function: macro:expand sexpression Takes an R4RS expression, macro-expands it, and returns the result of the macro expansion. -- Function: macro:eval sexpression Takes an R4RS expression, macro-expands it, evals the result of the macro expansion, and returns the result of the evaluation. -- Procedure: macro:load filename FILENAME should be a string. If filename names an existing file, the `macro:load' procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The `macro:load' procedure does not affect the values returned by `current-input-port' and `current-output-port'.  File: slib.info, Node: Macro by Example, Next: Macros That Work, Prev: R4RS Macros, Up: Scheme Syntax Extension Packages 3.3 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'. * generating hygienic global `define-syntax' Macro-by-Example macros *cheaply*. * can define macros which use `...'. * needn't worry about a lexical variable in a macro definition clashing with a variable from the macro use context * don't suffer the overhead of redefining the repl if `defmacro' natively supported (most implementations) 3.3.1 Caveat ------------ 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 `letrec-syntax' are used. So you will not be courting large-scale disaster unless you're using system-function names as local variables with unintuitive bindings that the macro can't use. However, if you must have the full `r4rs' macro functionality, look to the more featureful (but also more expensive) versions of syntax-rules available in slib *Note Macros That Work::, *Note Syntactic Closures::, and *Note Syntax-Case Macros::. -- Macro: define-syntax keyword transformer-spec The KEYWORD is an identifier, and the TRANSFORMER-SPEC should be an instance of `syntax-rules'. The top-level syntactic environment is extended by binding the KEYWORD to the specified transformer. (define-syntax let* (syntax-rules () ((let* () body1 body2 ...) (let () body1 body2 ...)) ((let* ((name1 val1) (name2 val2) ...) body1 body2 ...) (let ((name1 val1)) (let* (( name2 val2) ...) body1 body2 ...))))) -- Macro: syntax-rules literals syntax-rule ... LITERALS is a list of identifiers, and each SYNTAX-RULE should be of the form `(PATTERN TEMPLATE)' where the PATTERN and TEMPLATE are as in the grammar above. An instance of `syntax-rules' produces a new macro transformer by specifying a sequence of hygienic rewrite rules. A use of a macro whose keyword is associated with a transformer specified by `syntax-rules' is matched against the patterns contained in the SYNTAX-RULEs, beginning with the leftmost SYNTAX-RULE. When a match is found, the macro use is trancribed hygienically according to the template. Each pattern begins with the keyword for the macro. This keyword is not involved in the matching and is not considered a pattern variable or literal identifier.  File: slib.info, Node: Macros That Work, Next: Syntactic Closures, Prev: Macro by Example, Up: Scheme Syntax Extension Packages 3.4 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 expression types. -- Function: macro:expand expression -- Function: macwork:expand expression Takes an R4RS expression, macro-expands it, and returns the result of the macro expansion. -- Function: macro:eval expression -- Function: macwork:eval expression `macro:eval' returns the value of EXPRESSION in the current top level environment. EXPRESSION can contain macro definitions. Side effects of EXPRESSION will affect the top level environment. -- Procedure: macro:load filename -- Procedure: macwork:load filename FILENAME should be a string. If filename names an existing file, the `macro:load' procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The `macro:load' procedure does not affect the values returned by `current-input-port' and `current-output-port'. References: The `Revised^4 Report on the Algorithmic Language Scheme' Clinger and Rees [editors]. To appear in LISP Pointers. Also available as a technical report from the University of Oregon, MIT AI Lab, and Cornell. 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. transformer spec ==> (syntax-rules literals rules) rules ==> () | (rule . rules) rule ==> (pattern template) pattern ==> pattern_var ; a symbol not in literals | symbol ; a symbol in literals | () | (pattern . pattern) | (ellipsis_pattern) | #(pattern*) ; extends R4RS | #(pattern* ellipsis_pattern) ; extends R4RS | pattern_datum template ==> pattern_var | symbol | () | (template2 . template2) | #(template*) ; extends R4RS | pattern_datum template2 ==> template | ellipsis_template pattern_datum ==> string ; no vector | character | boolean | number ellipsis_pattern ==> pattern ... ellipsis_template ==> template ... pattern_var ==> symbol ; not in literals literals ==> () | (symbol . literals) 3.4.1 Definitions ----------------- Scope of an ellipsis Within a pattern or template, the scope of an ellipsis (`...') is the pattern or template that appears to its left. Rank of a pattern variable The rank of a pattern variable is the number of ellipses within whose scope it appears in the pattern. Rank of a subtemplate The rank of a subtemplate is the number of ellipses within whose scope it appears in the template. Template rank of an occurrence of a pattern variable The template rank of an occurrence of a pattern variable within a template is the rank of that occurrence, viewed as a subtemplate. Variables bound by a pattern The variables bound by a pattern are the pattern variables that appear within it. Referenced variables of a subtemplate The referenced variables of a subtemplate are the pattern variables that appear within it. Variables opened by an ellipsis template The variables opened by an ellipsis template are the referenced pattern variables whose rank is greater than the rank of the ellipsis template. 3.4.2 Restrictions ------------------ 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 pattern variable's rank. Every ellipsis template must open at least one variable. For every ellipsis template, the variables opened by an ellipsis template must all be bound to sequences of the same length. The compiled form of a RULE is rule ==> (pattern template inserted) pattern ==> pattern_var | symbol | () | (pattern . pattern) | ellipsis_pattern | #(pattern) | pattern_datum template ==> pattern_var | symbol | () | (template2 . template2) | #(pattern) | pattern_datum template2 ==> template | ellipsis_template pattern_datum ==> string | character | boolean | number pattern_var ==> #(V symbol rank) ellipsis_pattern ==> #(E pattern pattern_vars) ellipsis_template ==> #(E template pattern_vars) inserted ==> () | (symbol . inserted) pattern_vars ==> () | (pattern_var . pattern_vars) rank ==> exact non-negative integer where V and E are unforgeable values. The pattern variables associated with an ellipsis pattern are the variables bound by the pattern, and the pattern variables associated with an ellipsis template are the variables opened by the ellipsis template. If the template contains a big chunk that contains no pattern variables or inserted identifiers, then the big chunk will be copied unnecessarily. That shouldn't matter very often.  File: slib.info, Node: Syntactic Closures, Next: Syntax-Case Macros, Prev: Macros That Work, Up: Scheme Syntax Extension Packages 3.5 Syntactic Closures ====================== `(require 'syntactic-closures)' -- Function: macro:expand expression -- Function: synclo:expand expression Returns scheme code with the macros and derived expression types of EXPRESSION expanded to primitive expression types. -- Function: macro:eval expression -- Function: synclo:eval expression `macro:eval' returns the value of EXPRESSION in the current top level environment. EXPRESSION can contain macro definitions. Side effects of EXPRESSION will affect the top level environment. -- Procedure: macro:load filename -- Procedure: synclo:load filename FILENAME should be a string. If filename names an existing file, the `macro:load' procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The `macro:load' procedure does not affect the values returned by `current-input-port' and `current-output-port'. 3.5.1 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. 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: make-syntactic-closure capture-syntactic-environment identifier? identifier=? The description of the facility is divided into three parts. The first part defines basic terminology. The second part describes how macro transformers are defined. The third part describes the use of "identifiers", which extend the syntactic closure mechanism to be compatible with `syntax-rules'. 3.5.1.1 Terminology ................... This section defines the concepts and data types used by the syntactic closures facility. * "Forms" are the syntactic entities out of which programs are recursively constructed. A form is any expression, any 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 (+ x 4) (lambda (x) x) (define pi 3.14159) if define * An "alias" is an alternate name for a given symbol. It can appear anywhere in a form that the symbol could be used, and when quoted it is replaced by the symbol; however, it does not satisfy the predicate `symbol?'. Macro transformers rarely distinguish symbols from aliases, referring to both as identifiers. * A "syntactic" environment maps identifiers to their meanings. More precisely, it determines whether an identifier is a syntactic keyword or a variable. If it is a keyword, the meaning is an interpretation for the form in which that keyword appears. If it is a variable, the meaning identifies which binding of that variable is referenced. In short, syntactic environments contain all of the contextual information necessary for interpreting the meaning of a particular form. * A "syntactic closure" consists of a form, a syntactic environment, and a list of identifiers. All identifiers in the form take their meaning from the syntactic environment, except those in the given list. The identifiers in the list are to have their meanings determined later. A syntactic closure may be used in any context in which its form could have been used. Since a syntactic closure is also a form, it may not be used in contexts where a form would be illegal. For example, a form may not appear as a clause in the cond special form. A syntactic closure appearing in a quoted structure is replaced by its form. 3.5.1.2 Transformer Definition .............................. This section describes the `transformer' special form and the procedures `make-syntactic-closure' and `capture-syntactic-environment'. -- Syntax: transformer expression Syntax: It is an error if this syntax occurs except as a TRANSFORMER SPEC. Semantics: The EXPRESSION is evaluated in the standard transformer environment to yield a macro transformer as described below. This macro transformer is bound to a macro keyword by the special form in which the `transformer' expression appears (for example, `let-syntax'). A "macro transformer" is a procedure that takes two arguments, a form and a syntactic environment, and returns a new form. The first argument, the "input form", is the form in which the macro keyword occurred. The second argument, the "usage environment", is the syntactic environment in which the input form occurred. The result of the transformer, the "output form", is automatically closed in the "transformer environment", which is the syntactic environment in which the `transformer' expression occurred. For example, here is a definition of a push macro using `syntax-rules': (define-syntax push (syntax-rules () ((push item list) (set! list (cons item list))))) Here is an equivalent definition using `transformer': (define-syntax push (transformer (lambda (exp env) (let ((item (make-syntactic-closure env '() (cadr exp))) (list (make-syntactic-closure env '() (caddr exp)))) `(set! ,list (cons ,item ,list)))))) In this example, the identifiers `set!' and `cons' are closed in the transformer environment, and thus will not be affected by the meanings of those identifiers in the usage environment `env'. Some macros may be non-hygienic by design. For example, the following defines a loop macro that implicitly binds `exit' to an 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) (let ((body (cdr exp))) `(call-with-current-continuation (lambda (exit) (let f () ,@(map (lambda (exp) (make-syntactic-closure env '(exit) exp)) body) (f)))))))) To assign meanings to the identifiers in a form, use `make-syntactic-closure' to close the form in a syntactic environment. -- Function: make-syntactic-closure environment free-names form ENVIRONMENT must be a syntactic environment, FREE-NAMES must be a list of identifiers, and FORM must be a form. `make-syntactic-closure' constructs and returns a syntactic closure of FORM in ENVIRONMENT, which can be used anywhere that FORM could have been used. All the identifiers used in FORM, except those explicitly excepted by FREE-NAMES, obtain their meanings from ENVIRONMENT. Here is an example where FREE-NAMES is something other than the empty list. It is instructive to compare the use of FREE-NAMES in this example with its use in the `loop' example above: the examples are similar except for the source of the identifier being left free. (define-syntax let1 (transformer (lambda (exp env) (let ((id (cadr exp)) (init (caddr exp)) (exp (cadddr exp))) `((lambda (,id) ,(make-syntactic-closure env (list id) exp)) ,(make-syntactic-closure env '() init)))))) `let1' is a simplified version of `let' that only binds a single identifier, and whose body consists of a single expression. When the body expression is syntactically closed in its original syntactic environment, the identifier that is to be bound by `let1' must be left free, so that it can be properly captured by the `lambda' in the output form. To obtain a syntactic environment other than the usage environment, use `capture-syntactic-environment'. -- Function: capture-syntactic-environment procedure `capture-syntactic-environment' returns a form that will, when transformed, call PROCEDURE on the current syntactic environment. PROCEDURE should compute and return a new form to be transformed, in that same syntactic environment, in place of the form. 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) (letrec ((loop (lambda (id) (if test return (loop step))))) (loop init))))) The following attempt at defining `loop-until' has a subtle bug: (define-syntax loop-until (transformer (lambda (exp env) (let ((id (cadr exp)) (init (caddr exp)) (test (cadddr exp)) (return (cadddr (cdr exp))) (step (cadddr (cddr exp))) (close (lambda (exp free) (make-syntactic-closure env free exp)))) `(letrec ((loop (lambda (,id) (if ,(close test (list id)) ,(close return (list id)) (loop ,(close step (list id))))))) (loop ,(close init '()))))))) This definition appears to take all of the proper precautions to prevent unintended captures. It carefully closes the subexpressions in their original syntactic environment and it leaves the `id' identifier free in the `test', `return', and `step' expressions, so that it will be captured by the binding introduced by the `lambda' expression. Unfortunately it uses the identifiers `if' and `loop' within that `lambda' expression, so if the user of `loop-until' just happens to use, say, `if' for the identifier, it will be inadvertently captured. The syntactic environment that `if' and `loop' want to be exposed to is the one just outside the `lambda' expression: before the user's identifier is added to the syntactic environment, but after the identifier loop has been added. `capture-syntactic-environment' captures exactly that environment as follows: (define-syntax loop-until (transformer (lambda (exp env) (let ((id (cadr exp)) (init (caddr exp)) (test (cadddr exp)) (return (cadddr (cdr exp))) (step (cadddr (cddr exp))) (close (lambda (exp free) (make-syntactic-closure env free exp)))) `(letrec ((loop ,(capture-syntactic-environment (lambda (env) `(lambda (,id) (,(make-syntactic-closure env '() `if) ,(close test (list id)) ,(close return (list id)) (,(make-syntactic-closure env '() `loop) ,(close step (list id))))))))) (loop ,(close init '()))))))) In this case, having captured the desired syntactic environment, it is convenient to construct syntactic closures of the identifiers `if' and the `loop' and use them in the body of the `lambda'. A common use of `capture-syntactic-environment' is to get the transformer environment of a macro transformer: (transformer (lambda (exp env) (capture-syntactic-environment (lambda (transformer-env) ...)))) 3.5.1.3 Identifiers ................... This section describes the procedures that create and manipulate identifiers. Previous syntactic closure proposals did not have an identifier data type - they just used symbols. The identifier data type extends the syntactic closures facility to be compatible with the high-level `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" Aliases are implemented as syntactic closures because they behave just like syntactic closures most of the time. The difference is that an alias may be bound to a new value (for example by `lambda' or `let-syntax'); other syntactic closures may not be used this way. If an alias is bound, then within the scope of that binding it is looked up in the syntactic environment just like any other identifier. Aliases are used in the implementation of the high-level facility `syntax-rules'. A macro transformer created by `syntax-rules' uses a template to generate its output form, substituting subforms of the input form into the template. In a syntactic closures implementation, all of the symbols in the template are replaced by aliases closed in the transformer environment, while the output form itself is closed in the usage environment. This guarantees that the macro transformation is hygienic, without requiring the transformer to know the syntactic 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)) => #t (identifier? "a") => #f (identifier? #\a) => #f (identifier? 97) => #f (identifier? #f) => #f (identifier? '(a)) => #f (identifier? '#(a)) => #f The predicate `eq?' is used to determine if two identifers are "the same". Thus `eq?' can be used to compare identifiers exactly as it would be used to compare symbols. Often, though, it is useful to know whether two identifiers "mean the same thing". For example, the `cond' macro uses the symbol `else' to identify the final clause in the conditional. A macro transformer for `cond' cannot just look for the symbol `else', because the `cond' form might be the output of another macro transformer that replaced the symbol `else' with an alias. Instead the transformer must look for an identifier that "means the same thing" in the usage environment as the symbol `else' means in the transformer environment. -- Function: identifier=? environment1 identifier1 environment2 identifier2 ENVIRONMENT1 and ENVIRONMENT2 must be syntactic environments, and IDENTIFIER1 and IDENTIFIER2 must be identifiers. `identifier=?' returns `#t' if the meaning of IDENTIFIER1 in ENVIRONMENT1 is the same as that of IDENTIFIER2 in ENVIRONMENT2, otherwise it returns `#f'. Examples: (let-syntax ((foo (transformer (lambda (form env) (capture-syntactic-environment (lambda (transformer-env) (identifier=? transformer-env 'x env 'x))))))) (list (foo) (let ((x 3)) (foo)))) => (#t #f) (let-syntax ((bar foo)) (let-syntax ((foo (transformer (lambda (form env) (capture-syntactic-environment (lambda (transformer-env) (identifier=? transformer-env 'foo env (cadr form)))))))) (list (foo foo) (foobar)))) => (#f #t) 3.5.1.4 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.  File: slib.info, Node: Syntax-Case Macros, Next: Define-Structure, Prev: Syntactic Closures, Up: Scheme Syntax Extension Packages 3.6 Syntax-Case Macros ====================== `(require 'syntax-case)' -- Function: macro:expand expression -- Function: syncase:expand expression Returns scheme code with the macros and derived expression types of EXPRESSION expanded to primitive expression types. -- Function: macro:eval expression -- Function: syncase:eval expression `macro:eval' returns the value of EXPRESSION in the current top level environment. EXPRESSION can contain macro definitions. Side effects of EXPRESSION will affect the top level environment. -- Procedure: macro:load filename -- Procedure: syncase:load filename FILENAME should be a string. If filename names an existing file, the `macro:load' procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially. These source code expressions and definitions may contain macro definitions. The `macro:load' procedure does not affect the values returned by `current-input-port' and `current-output-port'. 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 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... * Removed a couple of Chez scheme dependencies. * Renamed global variables used to minimize the possibility of name conflicts. * Adding an SLIB-specific initialization file. * Removing a couple extra files, most notably the documentation (but see below). If you wish, you can see exactly what changes were done by reading the shell script in the file `syncase.sh'. The two PostScript files were omitted in order to not burden the SLIB distribution with them. If you do intend to use `syntax-case', however, you should get these files and print them out on a PostScript printer. They are available with the original `syntax-case' distribution by anonymous FTP in `cs.indiana.edu:/pub/scheme/syntax-case'. In order to use syntax-case from an interactive top level, execute: (require 'syntax-case) (require 'repl) (repl:top-level macro:eval) See the section Repl (*note Repl::) for more information. To check operation of syntax-case get `cs.indiana.edu:/pub/scheme/syntax-case', and type (require 'syntax-case) (syncase:sanity-check) Beware that `syntax-case' takes a long time to load - about 20s on a SPARCstation SLC (with SCM) and about 90s on a Macintosh SE/30 (with Gambit). 3.6.1 Notes ----------- All R4RS syntactic forms are defined, including `delay'. Along with `delay' are simple definitions for `make-promise' (into which `delay' expressions expand) and `force'. `syntax-rules' and `with-syntax' (described in `TR356') are defined. `syntax-case' is actually defined as a macro that expands into calls to the procedure `syntax-dispatch' and the core form `syntax-lambda'; do not redefine these names. Several other top-level bindings not documented in TR356 are created: * the "hooks" in `hooks.ss' * the `build-' procedures in `output.ss' * `expand-syntax' (the expander) The syntax of define has been extended to allow `(define ID)', which assigns ID to some unspecified value. We have attempted to maintain R4RS compatibility where possible. The incompatibilities should be confined to `hooks.ss'. Please let us know if there is some incompatibility that is not flagged as such. Send bug reports, comments, suggestions, and questions to Kent Dybvig (dyb @ iuvax.cs.indiana.edu).  File: slib.info, Node: Define-Structure, Next: Define-Record-Type, Prev: Syntax-Case Macros, Up: Scheme Syntax Extension Packages 3.7 Define-Structure ==================== `(require 'structure)' Included with the `syntax-case' files was `structure.scm' which defines a macro `define-structure'. Here is its documentation from Gambit 4.0: -- special form: define-structure NAME FIELD... Record data types similar to Pascal records and C `struct' types can be defined using the `define-structure' special form. The identifier NAME specifies the name of the new data type. The structure name is followed by K identifiers naming each field of the record. The `define-structure' expands into a set of definitions of the following procedures: * `make-NAME' - A K argument procedure which constructs a new record from the value of its K fields. * `NAME?' - A procedure which tests if its single argument is of the given record type. * `NAME-FIELD' - For each field, a procedure taking as its single argument a value of the given record type and returning the content of the corresponding field of the record. * `NAME-FIELD-set!' - For each field, a two argument procedure taking as its first argument a value of the given record type. The second argument gets assigned to the corresponding field of the record and the void object is returned. Gambit record data types have a printed representation that includes the name of the type and the name and value of each field. For example: > (define-structure point x y color) > (define p (make-point 3 5 'red)) > p # > (point-x p) 3 > (point-color p) red > (point-color-set! p 'black) > p #  File: slib.info, Node: Define-Record-Type, Next: Fluid-Let, Prev: Define-Structure, Up: Scheme Syntax Extension Packages 3.8 Define-Record-Type ====================== `(require 'define-record-type)' or `(require 'srfi-9)' `http://srfi.schemers.org/srfi-9/srfi-9.html' -- Special Form: define-record-type ( ...) ... Where == ( ) == ( ) `define-record-type' is a syntax wrapper for the SLIB `record' module.  File: slib.info, Node: Fluid-Let, Next: Binding to multiple values, Prev: Define-Record-Type, Up: Scheme Syntax Extension Packages 3.9 Fluid-Let ============= `(require 'fluid-let)' -- Syntax: fluid-let `(BINDINGS ...)' FORMS... (fluid-let ((VARIABLE INIT) ...) EXPRESSION EXPRESSION ...) The INITs are evaluated in the current environment (in some unspecified order), the current values of the VARIABLEs are saved, the results are assigned to the VARIABLEs, the EXPRESSIONs are evaluated sequentially in the current environment, the VARIABLEs are restored to their original values, and the value of the last EXPRESSION is returned. The syntax of this special form is similar to that of `let', but `fluid-let' temporarily rebinds existing VARIABLEs. Unlike `let', `fluid-let' creates no new bindings; instead it _assigns_ the values of each INIT to the binding (determined by the rules of lexical scoping) of its corresponding VARIABLE.  File: slib.info, Node: Binding to multiple values, Next: Guarded LET* special form, Prev: Fluid-Let, Up: Scheme Syntax Extension Packages 3.10 Binding to multiple values =============================== `(require 'receive)' or `(require 'srfi-8)' -- Special Form: receive formals expression body ... `http://srfi.schemers.org/srfi-8/srfi-8.html' `(require 'let-values)' or `(require 'srfi-11)' -- Special Form: let-values ((formals expression) ...) body ... -- Special Form: let-values* ((formals expression) ...) body ... `http://srfi.schemers.org/srfi-11/srfi-11.html'  File: slib.info, Node: Guarded LET* special form, Next: Guarded COND Clause, Prev: Binding to multiple values, Up: Scheme Syntax Extension Packages 3.11 Guarded LET* special form ============================== `(require 'and-let*)' or `(require 'srfi-2)' -- Macro: and-let* claws body ... `http://srfi.schemers.org/srfi-2/srfi-2.html'  File: slib.info, Node: Guarded COND Clause, Next: Yasos, Prev: Guarded LET* special form, Up: Scheme Syntax Extension Packages 3.12 Guarded COND Clause ======================== `(require 'guarded-cond-clause)' or `(require 'srfi-61)' `http://srfi.schemers.org/srfi-61/srfi-61.html' -- library syntax: cond ... _Syntax:_ Each should be of the form ( ...) where is any expression. Alternatively, a may be of the form ( => ) The production in the formal syntax of Scheme as written by R5RS in section 7.1.3 is extended with a new option: => ( => ) where , , & are all s. Clauses of this form have the following semantics: is evaluated. It may return arbitrarily many values. is applied to an argument list containing the values in order that returned. If returns a true value for that argument list, is applied with an equivalent argument list. If returns a false value, however, the clause is abandoned and the next one is tried. The last may be an "else clause," which has the form (else ...). This `port->char-list' procedure accepts an input port and returns a list of all the characters it produces until the end. (define (port->char-list port) (cond ((read-char port) char? => (lambda (c) (cons c (port->char-list port)))) (else '()))) (call-with-input-string "foo" port->char-list) ==> (#\f #\o #\o)  File: slib.info, Node: Yasos, Prev: Guarded COND Clause, Up: Scheme Syntax Extension Packages 3.13 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 Oriented Programming in Scheme', Proceedings of the 1988 ACM Conference on LISP and Functional Programming, July 1988 [ACM #552880]. Another reference is: Ken Dickey. Scheming with Objects `AI Expert' Volume 7, Number 10 (October 1992), pp. 24-33. * Menu: * Yasos terms:: Definitions and disclaimer. * Yasos interface:: The Yasos macros and procedures. * Setters:: Dylan-like setters in Yasos. * Yasos examples:: Usage of Yasos and setters.  File: slib.info, Node: Yasos terms, Next: Yasos interface, Prev: Yasos, Up: Yasos 3.13.1 Terms ------------ "Object" Any Scheme data object. "Instance" An instance of the OO system; an "object". "Operation" A METHOD. _Notes:_ The object system supports multiple inheritance. An instance can inherit from 0 or more ancestors. In the case of multiple inherited operations with the same identity, the operation used is that from the first ancestor which contains it (in the ancestor `let'). An operation may be applied to any Scheme data object--not just instances. As code which creates instances is just code, there are no "classes" and no meta-ANYTHING. Method dispatch is by a procedure call a la CLOS rather than by `send' syntax a la Smalltalk. _Disclaimer:_ There are a number of optimizations which can be made. This implementation is expository (although performance should be quite reasonable). See the L&FP paper for some suggestions.  File: slib.info, Node: Yasos interface, Next: Setters, Prev: Yasos terms, Up: Yasos 3.13.2 Interface ---------------- -- Syntax: define-operation `('opname self arg ...`)' DEFAULT-BODY Defines a default behavior for data objects which don't handle the operation OPNAME. The default behavior (for an empty DEFAULT-BODY) is to generate an error. -- Syntax: define-predicate opname? Defines a predicate OPNAME?, usually used for determining the "type" of an object, such that `(OPNAME? OBJECT)' returns `#t' if OBJECT has an operation OPNAME? and `#f' otherwise. -- Syntax: object `((NAME SELF ARG ...) BODY)' ... Returns an object (an instance of the object system) with operations. Invoking `(NAME OBJECT ARG ...' executes the BODY of the OBJECT with SELF bound to OBJECT and with argument(s) ARG.... -- Syntax: object-with-ancestors `(('ancestor1 init1`)' ...`)' operation ... A `let'-like form of `object' for multiple inheritance. It returns an object inheriting the behaviour of ANCESTOR1 etc. An operation will be invoked in an ancestor if the object itself does not provide such a method. In the case of multiple inherited operations with the same identity, the operation used is the one found in the first ancestor in the ancestor list. -- Syntax: operate-as component operation self arg ... Used in an operation definition (of SELF) to invoke the OPERATION in an ancestor COMPONENT but maintain the object's identity. Also known as "send-to-super". -- Procedure: print obj port A default `print' operation is provided which is just `(format PORT OBJ)' (*note Format::) for non-instances and prints OBJ preceded by `#' for instances. -- Function: size obj The default method returns the number of elements in OBJ if it is a vector, string or list, `2' for a pair, `1' for a character and by default id an error otherwise. Objects such as collections (*note Collections::) may override the default in an obvious way.  File: slib.info, Node: Setters, Next: Yasos examples, Prev: Yasos interface, Up: Yasos 3.13.3 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!'. This implementation of setters is similar to that in Dylan(TM) (`Dylan: An object-oriented dynamic language', Apple Computer Eastern Research and Technology). Common LISP provides similar facilities through `setf'. -- Function: setter getter Returns the setter for the procedure GETTER. E.g., since `string-ref' is the getter corresponding to a setter which is actually `string-set!': (define foo "foo") ((setter string-ref) foo 0 #\F) ; set element 0 of foo foo => "Foo" -- Syntax: set place new-value If PLACE is a variable name, `set' is equivalent to `set!'. Otherwise, PLACE must have the form of a procedure call, where the procedure name refers to a getter and the call indicates an accessible generalized location, i.e., the call would return a value. The return value of `set' is usually unspecified unless used with a setter whose definition guarantees to return a useful value. (set (string-ref foo 2) #\O) ; generalized location with getter foo => "FoO" (set foo "foo") ; like set! foo => "foo" -- Procedure: add-setter getter setter Add procedures GETTER and SETTER to the (inaccessible) list of valid setter/getter pairs. SETTER implements the store operation corresponding to the GETTER access operation for the relevant state. The return value is unspecified. -- Procedure: remove-setter-for getter Removes the setter corresponding to the specified GETTER from the list of valid setters. The return value is unspecified. -- Syntax: define-access-operation getter-name Shorthand for a Yasos `define-operation' defining an operation GETTER-NAME that objects may support to return the value of some mutable state. The default operation is to signal an error. The return value is unspecified.  File: slib.info, Node: Yasos examples, Prev: Setters, Up: Yasos 3.13.4 Examples --------------- ;;; These definitions for PRINT and SIZE are ;;; already supplied by (require 'yasos) (define-operation (print obj port) (format port (if (instance? obj) "#" "~s") obj)) (define-operation (size obj) (cond ((vector? obj) (vector-length obj)) ((list? obj) (length obj)) ((pair? obj) 2) ((string? obj) (string-length obj)) ((char? obj) 1) (else (slib:error "Operation not supported: size" obj)))) (define-predicate cell?) (define-operation (fetch obj)) (define-operation (store! obj newValue)) (define (make-cell value) (object ((cell? self) #t) ((fetch self) value) ((store! self newValue) (set! value newValue) newValue) ((size self) 1) ((print self port) (format port "#" (fetch self))))) (define-operation (discard obj value) (format #t "Discarding ~s~%" value)) (define (make-filtered-cell value filter) (object-with-ancestors ((cell (make-cell value))) ((store! self newValue) (if (filter newValue) (store! cell newValue) (discard self newValue))))) (define-predicate array?) (define-operation (array-ref array index)) (define-operation (array-set! array index value)) (define (make-array num-slots) (let ((anArray (make-vector num-slots))) (object ((array? self) #t) ((size self) num-slots) ((array-ref self index) (vector-ref anArray index)) ((array-set! self index newValue) (vector-set! anArray index newValue)) ((print self port) (format port "#" (size self)))))) (define-operation (position obj)) (define-operation (discarded-value obj)) (define (make-cell-with-history value filter size) (let ((pos 0) (most-recent-discard #f)) (object-with-ancestors ((cell (make-filtered-call value filter)) (sequence (make-array size))) ((array? self) #f) ((position self) pos) ((store! self newValue) (operate-as cell store! self newValue) (array-set! self pos newValue) (set! pos (+ pos 1))) ((discard self value) (set! most-recent-discard value)) ((discarded-value self) most-recent-discard) ((print self port) (format port "#" (fetch self)))))) (define-access-operation fetch) (add-setter fetch store!) (define foo (make-cell 1)) (print foo #f) => "#" (set (fetch foo) 2) => (print foo #f) => "#" (fetch foo) => 2  File: slib.info, Node: Textual Conversion Packages, Next: Mathematical Packages, Prev: Scheme Syntax Extension Packages, Up: Top 4 Textual Conversion Packages ***************************** * Menu: * Precedence Parsing:: * Format:: Common-Lisp Format * Standard Formatted I/O:: Posix printf and scanf * Programs and Arguments:: * HTML:: Generating * HTML Tables:: Databases meet HTML * HTTP and CGI:: Serve WWW sites * Parsing HTML:: 'html-for-each * URI:: Uniform Resource Identifier * Parsing XML:: 'parse-xml or 'ssax * Printing Scheme:: Nicely * Time and Date:: * NCBI-DNA:: DNA and protein sequences * Schmooz:: Documentation markup for Scheme programs  File: slib.info, Node: Precedence Parsing, Next: Format, Prev: Textual Conversion Packages, Up: Textual Conversion Packages 4.1 Precedence Parsing ====================== `(require 'precedence-parse)' or `(require 'parse)' This package implements: * a Pratt style precedence parser; * a "tokenizer" which congeals tokens according to assigned classes of constituent characters; * procedures giving direct control of parser rulesets; * procedures for higher level specification of rulesets. * 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: Rule Types, Prev: Precedence Parsing, Up: Precedence Parsing 4.1.1 Precedence Parsing Overview --------------------------------- This package offers improvements over previous parsers. * Common computer language constructs are concisely specified. * Grammars can be changed dynamically. Operators can be assigned different meanings within a lexical context. * Rulesets don't need compilation. Grammars can be changed incrementally. * Operator precedence is specified by integers. * All possibilities of bad input are handled (1) and return as much 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://swiss.csail.mit.edu/~jaffer/JACAL') 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 4.1.2 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. -- Grammar: nofix bye exit bye calls the function `exit' with no arguments. -- Grammar: prefix - negate - 42 Calls the function `negate' with the argument `42'. -- Grammar: infix - difference x - y Calls the function `difference' with arguments `x' and `y'. -- Grammar: nary + sum x + y + z Calls the function `sum' with arguments `x', `y', and `y'. -- Grammar: postfix ! factorial 5 ! Calls the function `factorial' with the argument `5'. -- Grammar: prestfix set set! set foo bar Calls the function `set!' with the arguments `foo' and `bar'. -- Grammar: commentfix /* */ /* almost any text here */ Ignores the comment delimited by `/*' and `*/'. -- Grammar: matchfix { list } {0, 1, 2} Calls the function `list' with the arguments `0', `1', and `2'. -- Grammar: inmatchfix ( funcall ) f(x, y) Calls the function `funcall' with the arguments `f', `x', and `y'. -- Grammar: delim ; set foo bar; delimits the extent of the restfix operator `set'.  File: slib.info, Node: Ruleset Definition and Use, Next: Token definition, Prev: Rule Types, Up: Precedence Parsing 4.1.3 Ruleset Definition and Use -------------------------------- -- Variable: *syn-defs* A grammar is built by one or more calls to `prec:define-grammar'. The rules are appended to *SYN-DEFS*. The value of *SYN-DEFS* is the grammar suitable for passing as an argument to `prec:parse'. -- Constant: *syn-ignore-whitespace* Is a nearly empty grammar with whitespace characters set to group 0, which means they will not be made into tokens. Most rulesets will want to start with `*syn-ignore-whitespace*' In order to start defining a grammar, either (set! *syn-defs* '()) or (set! *syn-defs* *syn-ignore-whitespace*) -- Function: prec:define-grammar rule1 ... Appends RULE1 ... to *SYN-DEFS*. `prec:define-grammar' is used to define both the character classes and rules for tokens. Once your grammar is defined, save the value of `*syn-defs*' in a variable (for use when calling `prec:parse'). (define my-ruleset *syn-defs*) -- Function: prec:parse ruleset delim -- Function: prec:parse ruleset delim port The RULESET argument must be a list of rules as constructed by `prec:define-grammar' and extracted from *SYN-DEFS*. The token DELIM may be a character, symbol, or string. A character DELIM argument will match only a character token; i.e. a character for which no token-group is assigned. A symbol or string will match only a token string; i.e. a token resulting from a token group. `prec:parse' reads a RULESET grammar expression delimited by DELIM from the given input PORT. `prec:parse' returns the next object parsable from the given input PORT, updating PORT to point to the first character past the end of the external representation of the object. If an end of file is encountered in the input before any characters are found that can begin an object, then an end of file object is returned. If a delimiter (such as DELIM) is found before any characters are found that can begin an object, then `#f' is returned. The PORT argument may be omitted, in which case it defaults to the value returned by `current-input-port'. It is an error to parse from a closed port.  File: slib.info, Node: Token definition, Next: Nud and Led Definition, Prev: Ruleset Definition and Use, Up: Precedence Parsing 4.1.4 Token definition ---------------------- -- Function: tok:char-group group chars chars-proc The argument CHARS may be a single character, a list of characters, or a string. Each character in CHARS is treated as though `tok:char-group' was called with that character alone. The argument CHARS-PROC must be a procedure of one argument, a list of characters. After `tokenize' has finished accumulating the characters for a token, it calls CHARS-PROC with the list of characters. The value returned is the token which `tokenize' returns. The argument GROUP may be an exact integer or a procedure of one character argument. The following discussion concerns the treatment which the tokenizing routine, `tokenize', will accord to characters on the basis of their groups. When GROUP is a non-zero integer, characters whose group number is equal to or exactly one less than GROUP will continue to accumulate. Any other character causes the accumulation to stop (until a new token is to be read). The GROUP of zero is special. These characters are ignored when parsed pending a token, and stop the accumulation of token characters when the accumulation has already begun. Whitespace characters are usually put in group 0. If GROUP is a procedure, then, when triggerd by the occurence of an initial (no accumulation) CHARS character, this procedure will be repeatedly called with each successive character from the input stream until the GROUP procedure returns a non-false value. The following convenient constants are provided for use with `tok:char-group'. -- Constant: tok:decimal-digits Is the string `"0123456789"'. -- Constant: tok:upper-case Is the string consisting of all upper-case letters ("ABCDEFGHIJKLMNOPQRSTUVWXYZ"). -- Constant: tok:lower-case Is the string consisting of all lower-case letters ("abcdefghijklmnopqrstuvwxyz"). -- Constant: tok:whitespaces 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 4.1.5 Nud and Led Definition ---------------------------- 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 expression is not extant. The "Left Denotation" (or "led") of a token is the procedure, arguments, and lbp applying for that token when there is a "Left", an unclaimed parsed expression. In his paper, Pratt, V. R. Top Down Operator Precendence. `SIGACT/SIGPLAN Symposium on Principles of Programming Languages', Boston, 1973, pages 41-51 the "left binding power" (or "lbp") was an independent property of tokens. I think this was done in order to allow tokens with NUDs but not LEDs to also be used as delimiters, which was a problem for statically defined syntaxes. It turns out that _dynamically binding_ NUDs and LEDs allows them independence. For the rule-defining procedures that follow, the variable TK may be a character, string, or symbol, or a list composed of characters, strings, and symbols. Each element of TK is treated as though the procedure were called for each element. Character TK arguments will match only character tokens; i.e. characters for which no token-group is assigned. Symbols and strings will both match token strings; i.e. tokens resulting from token groups. -- Function: prec:make-nud tk sop arg1 ... Returns a rule specifying that SOP be called when TK is parsed. If SOP is a procedure, it is called with TK and ARG1 ... as its arguments; the resulting value is incorporated into the expression being built. Otherwise, `(list SOP ARG1 ...)' is incorporated. If no NUD has been defined for a token; then if that token is a string, it is converted to a symbol and returned; if not a string, the token is returned. -- Function: prec:make-led tk sop arg1 ... Returns a rule specifying that SOP be called when TK is parsed and LEFT has an unclaimed parsed expression. If SOP is a procedure, it is called with LEFT, TK, and ARG1 ... as its arguments; the resulting value is incorporated into the expression being built. Otherwise, LEFT is incorporated. If no LED has been defined for a token, and LEFT is set, the parser issues a warning.  File: slib.info, Node: Grammar Rule Definition, Prev: Nud and Led Definition, Up: Precedence Parsing 4.1.6 Grammar Rule Definition ----------------------------- Here are procedures for defining rules for the syntax types introduced in *Note Precedence Parsing Overview::. For the rule-defining procedures that follow, the variable TK may be a character, string, or symbol, or a list composed of characters, strings, and symbols. Each element of TK is treated as though the procedure were called for each element. For procedures prec:delim, ..., prec:prestfix, if the SOP argument is `#f', then the token which triggered this rule is converted to a symbol and returned. A false SOP argument to the procedures prec:commentfix, prec:matchfix, or prec:inmatchfix has a different meaning. Character TK arguments will match only character tokens; i.e. characters for which no token-group is assigned. Symbols and strings will both match token strings; i.e. tokens resulting from token groups. -- Function: prec:delim tk Returns a rule specifying that TK should not be returned from parsing; i.e. TK's function is purely syntactic. The end-of-file is always treated as a delimiter. -- Function: prec:nofix tk sop Returns a rule specifying the following actions take place when TK is parsed: * If SOP is a procedure, it is called with no arguments; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP is incorporated. -- Function: prec:prefix tk sop bp rule1 ... Returns a rule specifying the following actions take place when TK is parsed: * The rules RULE1 ... augment and, in case of conflict, override rules currently in effect. * `prec:parse1' is called with binding-power BP. * If SOP is a procedure, it is called with the expression returned from `prec:parse1'; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP and the expression returned from `prec:parse1' is incorporated. * The ruleset in effect before TK was parsed is restored; RULE1 ... are forgotten. -- Function: prec:infix tk sop lbp bp rule1 ... Returns a rule declaring the left-binding-precedence of the token TK is LBP and specifying the following actions take place when TK is parsed: * The rules RULE1 ... augment and, in case of conflict, override rules currently in effect. * One expression is parsed with binding-power LBP. If instead a delimiter is encountered, a warning is issued. * If SOP is a procedure, it is applied to the list of LEFT and the parsed expression; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP, the LEFT expression, and the parsed expression is incorporated. * The ruleset in effect before TK was parsed is restored; RULE1 ... are forgotten. -- Function: prec:nary tk sop bp Returns a rule declaring the left-binding-precedence of the token TK is BP and specifying the following actions take place when TK is parsed: * Expressions are parsed with binding-power BP as far as they are interleaved with the token TK. * If SOP is a procedure, it is applied to the list of LEFT and the parsed expressions; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP, the LEFT expression, and the parsed expressions is incorporated. -- Function: prec:postfix tk sop lbp Returns a rule declaring the left-binding-precedence of the token TK is LBP and specifying the following actions take place when TK is parsed: * If SOP is a procedure, it is called with the LEFT expression; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP and the LEFT expression is incorporated. -- Function: prec:prestfix tk sop bp rule1 ... Returns a rule specifying the following actions take place when TK is parsed: * The rules RULE1 ... augment and, in case of conflict, override rules currently in effect. * Expressions are parsed with binding-power BP until a delimiter is reached. * If SOP is a procedure, it is applied to the list of parsed expressions; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP and the parsed expressions is incorporated. * The ruleset in effect before TK was parsed is restored; RULE1 ... are forgotten. -- Function: prec:commentfix tk stp match rule1 ... Returns rules specifying the following actions take place when TK is parsed: * The rules RULE1 ... augment and, in case of conflict, override rules currently in effect. * Characters are read until and end-of-file or a sequence of characters is read which matches the _string_ MATCH. * If STP is a procedure, it is called with the string of all that was read between the TK and MATCH (exclusive). * The ruleset in effect before TK was parsed is restored; RULE1 ... are forgotten. Parsing of commentfix syntax differs from the others in several ways. It reads directly from input without tokenizing; It calls STP but does not return its value; nay any value. I added the STP argument so that comment text could be echoed. -- Function: prec:matchfix tk sop sep match rule1 ... Returns a rule specifying the following actions take place when TK is parsed: * The rules RULE1 ... augment and, in case of conflict, override rules currently in effect. * A rule declaring the token MATCH a delimiter takes effect. * Expressions are parsed with binding-power `0' until the token MATCH is reached. If the token SEP does not appear between each pair of expressions parsed, a warning is issued. * If SOP is a procedure, it is applied to the list of parsed expressions; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP and the parsed expressions is incorporated. * The ruleset in effect before TK was parsed is restored; RULE1 ... are forgotten. -- Function: prec:inmatchfix tk sop sep match lbp rule1 ... Returns a rule declaring the left-binding-precedence of the token TK is LBP and specifying the following actions take place when TK is parsed: * The rules RULE1 ... augment and, in case of conflict, override rules currently in effect. * A rule declaring the token MATCH a delimiter takes effect. * Expressions are parsed with binding-power `0' until the token MATCH is reached. If the token SEP does not appear between each pair of expressions parsed, a warning is issued. * If SOP is a procedure, it is applied to the list of LEFT and the parsed expressions; the resulting value is incorporated into the expression being built. Otherwise, the list of SOP, the LEFT expression, and the parsed expressions is incorporated. * The ruleset in effect before TK was parsed is restored; RULE1 ... are forgotten.  File: slib.info, Node: Format, Next: Standard Formatted I/O, Prev: Precedence Parsing, Up: Textual Conversion Packages 4.2 Format (version 3.1) ======================== `(require 'format)' or `(require 'srfi-28)' * Menu: * Format Interface:: * Format Specification::  File: slib.info, Node: Format Interface, Next: Format Specification, Prev: Format, Up: Format 4.2.1 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 4.2.2 Format Specification (Format version 3.1) ----------------------------------------------- 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 | # ] 4.2.2.1 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. `~' Continuation Line. `~:' newline is ignored, white space left. `~@' 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)). Iteration bounding is controlled by configuration variables FORMAT:ITERATION-BOUNDED and FORMAT:MAX-ITERATIONS. With both variables default, a maximum of 100 iterations will be performed. `~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 4.2.2.2 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) 4.2.2.3 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. 4.2.2.4 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') FORMAT:ITERATION-BOUNDED When `#t', a `~{...~}' control will iterate no more than the number of times specified by FORMAT:MAX-ITERATIONS regardless of the number of iterations implied by modifiers and arguments. When `#f', a `~{...~}' control will iterate the number of times implied by modifiers and arguments, unless termination is forced by language or system limitations. (default `#t') FORMAT:MAX-ITERATIONS The maximum number of iterations performed by a `~{...~}' control. Has effect only when FORMAT:ITERATION-BOUNDED is `#t'. (default 100) 4.2.2.5 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.  File: slib.info, Node: Standard Formatted I/O, Next: Programs and Arguments, Prev: Format, Up: Textual Conversion Packages 4.3 Standard Formatted I/O ========================== * Menu: * Standard Formatted Output:: 'printf * Standard Formatted Input:: 'scanf 4.3.1 stdio ----------- `(require 'stdio)' `require's `printf' and `scanf' and additionally defines the symbols: -- Variable: stdin Defined to be `(current-input-port)'. -- Variable: stdout Defined to be `(current-output-port)'. -- Variable: stderr Defined to be `(current-error-port)'.  File: slib.info, Node: Standard Formatted Output, Next: Standard Formatted Input, Prev: Standard Formatted I/O, Up: Standard Formatted I/O 4.3.2 Standard Formatted Output ------------------------------- `(require 'printf)' -- Procedure: printf format arg1 ... -- Procedure: fprintf port format arg1 ... -- Procedure: sprintf str format arg1 ... -- Procedure: sprintf #f format arg1 ... -- Procedure: sprintf k format arg1 ... Each function converts, formats, and outputs its ARG1 ... arguments according to the control string FORMAT argument and returns the number of characters output. `printf' sends its output to the port `(current-output-port)'. `fprintf' sends its output to the port PORT. `sprintf' `string-set!'s locations of the non-constant string argument STR to the output characters. Two extensions of `sprintf' return new strings. If the first argument is `#f', then the returned string's length is as many characters as specified by the FORMAT and data; if the first argument is a non-negative integer K, then the length of the returned string is also bounded by K. The string FORMAT contains plain characters which are copied to the output stream, and conversion specifications, each of which results in fetching zero or more of the arguments ARG1 .... The results are undefined if there are an insufficient number of arguments for the format. If FORMAT is exhausted while some of the ARG1 ... arguments remain unused, the excess ARG1 ... arguments are ignored. The conversion specifications in a format string have the form: % [ FLAGS ] [ WIDTH ] [ . PRECISION ] [ TYPE ] CONVERSION An output conversion specifications consist of an initial `%' character followed in sequence by: * Zero or more "flag characters" that modify the normal behavior of the conversion specification. `-' Left-justify the result in the field. Normally the result is right-justified. `+' For the signed `%d' and `%i' conversions and all inexact conversions, prefix a plus sign if the value is positive. ` ' For the signed `%d' and `%i' conversions, if the result doesn't start with a plus or minus sign, prefix it with a space character instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if both are specified. `#' For inexact conversions, `#' specifies that the result should always include a decimal point, even if no digits follow it. For the `%g' and `%G' conversions, this also forces trailing zeros after the decimal point to be printed where they would otherwise be elided. For the `%o' conversion, force the leading digit to be `0', as if by increasing the precision. For `%x' or `%X', prefix a leading `0x' or `0X' (respectively) to the result. This doesn't do anything useful for the `%d', `%i', or `%u' conversions. Using this flag produces output which can be parsed by the `scanf' functions with the `%i' conversion (*note Standard Formatted Input::). `0' Pad the field with zeros instead of spaces. The zeros are placed after any indication of sign or base. This flag is ignored if the `-' flag is also specified, or if a precision is specified for an exact converson. * An optional decimal integer specifying the "minimum field width". If the normal conversion produces fewer characters than this, the field is padded (with spaces or zeros per the `0' flag) to the specified width. This is a _minimum_ width; if the normal conversion produces more characters than this, the field is _not_ truncated. Alternatively, if the field width is `*', the next argument in the argument list (before the actual value to be printed) is used as the field width. The width value must be an integer. If the value is negative it is as though the `-' flag is set (see above) and the absolute value is used as the field width. * An optional "precision" to specify the number of digits to be written for numeric conversions and the maximum field width for string conversions. The precision is specified by a period (`.') followed optionally by a decimal integer (which defaults to zero if omitted). Alternatively, if the precision is `.*', the next argument in the argument list (before the actual value to be printed) is used as the precision. The value must be an integer, and is ignored if negative. If you specify `*' for both the field width and precision, the field width argument precedes the precision argument. The `.*' precision is an enhancement. C library versions may not accept this syntax. For the `%f', `%e', and `%E' conversions, the precision specifies how many digits follow the decimal-point character. The default precision is `6'. If the precision is explicitly `0', the decimal point character is suppressed. For the `%g' and `%G' conversions, the precision specifies how many significant digits to print. Significant digits are the first digit before the decimal point, and all the digits after it. If the precision is `0' or not specified for `%g' or `%G', it is treated like a value of `1'. If the value being printed cannot be expressed accurately in the specified number of digits, the value is rounded to the nearest number that fits. For exact conversions, if a precision is supplied it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If a precision is not supplied, the number is printed with as many digits as necessary. Converting an exact `0' with an explicit precision of zero produces no characters. * An optional one of `l', `h' or `L', which is ignored for numeric conversions. It is an error to specify these modifiers for non-numeric conversions. * A character that specifies the conversion to be applied. 4.3.2.1 Exact Conversions ......................... `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 `scanf' for input (*note Standard Formatted Input::). `o' Print an integer as an unsigned octal number. `u' Print an integer as an unsigned decimal number. `x', `X' Print an integer as an unsigned hexadecimal number. `%x' prints using the digits `0123456789abcdef'. `%X' prints using the digits `0123456789ABCDEF'. 4.3.2.2 Inexact Conversions ........................... `f' Print a floating-point number in fixed-point notation. `e', `E' Print a floating-point number in exponential notation. `%e' prints `e' between mantissa and exponont. `%E' prints `E' between mantissa and exponont. `g', `G' Print a floating-point number in either fixed or exponential notation, whichever is more appropriate for its magnitude. Unless an `#' flag has been supplied, trailing zeros after a decimal point will be stripped off. `%g' prints `e' between mantissa and exponont. `%G' prints `E' between mantissa and exponent. `k', `K' Print a number like `%g', except that an SI prefix is output after the number, which is scaled accordingly. `%K' outputs a dot between number and prefix, `%k' does not. 4.3.2.3 Other Conversions ......................... `c' Print a single character. The `-' flag is the only one which can be specified. It is an error to specify a precision. `s' Print a string. The `-' flag is the only one which can be specified. A precision specifies the maximum number of characters to output; otherwise all characters in the string are output. `a', `A' Print a scheme expression. The `-' flag left-justifies the output. The `#' flag specifies that strings and characters should be quoted as by `write' (which can be read using `read'); otherwise, output is as `display' prints. A precision specifies the maximum number of characters to output; otherwise as many characters as needed are output. _Note:_ `%a' and `%A' are SLIB extensions. `%' Print a literal `%' character. No argument is consumed. It 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 4.3.3 Standard Formatted Input ------------------------------ `(require 'scanf)' -- Function: scanf-read-list format -- Function: scanf-read-list format port -- Function: scanf-read-list format string -- Macro: scanf format arg1 ... -- Macro: fscanf port format arg1 ... -- Macro: sscanf str format arg1 ... Each function reads characters, interpreting them according to the control string FORMAT argument. `scanf-read-list' returns a list of the items specified as far as the input matches FORMAT. `scanf', `fscanf', and `sscanf' return the number of items successfully matched and stored. `scanf', `fscanf', and `sscanf' also set the location corresponding to ARG1 ... using the methods: symbol `set!' car expression `set-car!' cdr expression `set-cdr!' vector-ref expression `vector-set!' substring expression `substring-move-left!' The argument to a `substring' expression in ARG1 ... must be a non-constant string. Characters will be stored starting at the position specified by the second argument to `substring'. The number of characters stored will be limited by either the position specified by the third argument to `substring' or the length of the matched string, whichever is less. The control string, FORMAT, contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: * White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read (and discarded) up to the next non-white-space character. * An ordinary character (not `%') that must match the next character of the input stream. * Conversion specifications, consisting of the character `%', an optional assignment suppressing character `*', an optional numerical maximum-field width, an optional `l', `h' or `L' which is ignored, and a conversion code. Unless the specification contains the `n' conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is returned in the position of the corresponding argument points, unless `*' indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. _Note:_ This specification of format strings differs from the `ANSI C' and `POSIX' specifications. In SLIB, white space before an input field is not skipped unless white space appears before the conversion specification in the format string. In order to write format strings which work identically with `ANSI C' and SLIB, prepend whitespace to all conversion specifications except `[' and `c'. The conversion code indicates the interpretation of the input field; For a suppressed field, no value is returned. The following conversion codes are legal: `%' A single % is expected in the input at this point; no value is returned. `d', `D' A decimal integer is expected. `u', `U' An unsigned decimal integer is expected. `o', `O' An octal integer is expected. `x', `X' A hexadecimal integer is expected. `i' An integer is expected. Returns the value of the next input item, interpreted according to C conventions; a leading `0' implies octal, a leading `0x' implies hexadecimal; otherwise, decimal is assumed. `n' Returns the total number of bytes (including white space) read by `scanf'. No input is consumed by `%n'. `f', `F', `e', `E', `g', `G' A floating-point number is expected. The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character `.', followed by an optional exponent field consisting of an `E' or an `e', followed by an optional `+', `-', or space, followed by an integer. `c', `C' WIDTH characters are expected. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use `%1s'. If a field width is given, a string is returned; up to the indicated number of characters is read. `s', `S' A character string is expected The input field is terminated by a white-space character. `scanf' cannot read a null string. `[' Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the scanset, and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. `^', when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters not contained in the remainder of the scanset string. Construction of the scanset follows certain conventions. A range of characters may be represented by the construct first-last, enabling `[0123456789]' to be expressed `[0-9]'. Using this convention, first must be lexically less than or equal to last; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a `^') of the scanset, in which case it will not be interpreted syntactically as the closing bracket. At least one character must match for this conversion to succeed. The `scanf' functions terminate their conversions at end-of-file, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream.  File: slib.info, Node: Programs and Arguments, Next: HTML, Prev: Standard Formatted I/O, Up: Textual Conversion Packages 4.4 Program and Arguments ========================= * Menu: * Getopt:: Command Line option parsing * Command Line:: A command line reader for Scheme shells * Parameter lists:: 'parameters * Getopt Parameter lists:: 'getopt-parameters * Filenames:: 'filename * Batch:: 'batch  File: slib.info, Node: Getopt, Next: Command Line, Prev: Programs and Arguments, Up: Programs and Arguments 4.4.1 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, *OPTIND* must be reset. -- Variable: *optarg* Is set by getopt to the (string) option-argument of the current option. -- 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 `(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 incremented by 1. If, when `getopt' is called, the string `(vector-ref argv *optind*)' either does not begin with the character `#\-' or is just `"-"', `getopt' returns `#f' without changing *OPTIND*. If `(vector-ref argv *optind*)' is the string `"--"', `getopt' returns `#f' after incrementing *OPTIND*. If `getopt' encounters an option character that is not contained in OPTSTRING, it returns the question-mark `#\?' character. If it detects a missing option argument, it returns the colon character `#\:' if the first character of OPTSTRING was a colon, or a question-mark character otherwise. In either case, `getopt' sets the variable GETOPT:OPT to the option character that caused the error. The special option `"--"' can be used to delimit the end of the options; `#f' is returned, and `"--"' is skipped. RETURN VALUE `getopt' returns the next option character specified on the command line. A colon `#\:' is returned if `getopt' detects a missing argument and the first character of OPTSTRING was a colon `#\:'. A question-mark `#\?' is returned if `getopt' encounters an option character not in OPTSTRING or detects a missing argument and the first character of OPTSTRING was not a colon `#\:'. Otherwise, `getopt' returns `#f' when all command line options have been parsed. Example: #! /usr/local/bin/scm (require 'program-arguments) | (require 'getopt) (define argv (program-arguments)) | (define opts ":a:b:cd") (let loop ((opt (getopt (length argv) argv opts))) (case opt ((#\a) (print "option a: " *optarg*)) ((#\b) (print "option b: " *optarg*)) ((#\c) (print "option c")) ((#\d) (print "option d")) ((#\?) (print "error" getopt:opt)) ((#\:) (print "missing arg" getopt:opt)) ((#f) (if (< *optind* (length argv)) (print "argv[" *optind* "]=" (list-ref argv *optind*))) (set! *optind* (+ *optind* 1)))) (if (< *optind* (length argv)) (loop (getopt (length argv) argv opts)))) (slib:exit) 4.4.2 Getopt-- -------------- -- 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' except for non-empty options beginning with `--'. Options beginning with `--' are returned as strings rather than characters. If a value is assigned (using `=') to a long option, `*optarg*' is set to the value. The `=' and value are not returned as part of the option string. 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*' will be set to `#f'. The caller is responsible for detecting and reporting errors. (define opts ":-:b:") (define *argv* '("foo" "-b9" "--f1" "--2=" "--g3=35234.342" "--")) (define *optind* 1) (define *optarg* #f) (require 'qp) (do ((i 5 (+ -1 i))) ((zero? i)) (let ((opt (getopt-- opts))) (print *optind* opt *optarg*))) -| 2 #\b "9" 3 "f1" #f 4 "2" "" 5 "g3" "35234.342" 5 #f "35234.342"  File: slib.info, Node: Command Line, Next: Parameter lists, Prev: Getopt, Up: Programs and Arguments 4.4.3 Command Line ------------------ `(require 'read-command)' -- Function: read-command port -- Function: read-command `read-command' converts a "command line" into a list of strings suitable for parsing by `getopt'. The syntax of command lines supported resembles that of popular "shell"s. `read-command' updates PORT to point to the first character past the command delimiter. If an end of file is encountered in the input before any characters are found that can begin an object or comment, then an end of file object is returned. The PORT argument may be omitted, in which case it defaults to the value returned by `current-input-port'. The fields into which the command line is split are delimited by whitespace as defined by `char-whitespace?'. The end of a command is delimited by end-of-file or unescaped semicolon (<;>) or . Any character can be literally included in a field by escaping it with a backslach (<\>). The initial character and types of fields recognized are: `\' The next character has is taken literally and not interpreted as a field delimiter. If <\> is the last character before a , that is just ignored. Processing continues from the characters after the as though the backslash and were not there. `"' The characters up to the next unescaped <"> are taken literally, according to [R4RS] rules for literal strings (*note Strings: (r4rs)Strings.). `(', `%'' One scheme expression is `read' starting with this character. The `read' expression is evaluated, converted to a string (using `display'), and replaces the expression in the returned field. `;' Semicolon delimits a command. Using semicolons more than one command can appear on a line. Escaped semicolons and semicolons inside strings do not delimit commands. The comment field differs from the previous fields in that it must be the first character of a command or appear after whitespace in order to be recognized. <#> can be part of fields if these conditions are not met. For instance, `ab#c' is just the field ab#c. `#' Introduces a comment. The comment continues to the end of the line on which the semicolon appears. Comments are treated as whitespace by `read-dommand-line' and backslashes before s in comments are also ignored. -- Function: read-options-file filename `read-options-file' converts an "options file" into a list of strings suitable for parsing by `getopt'. The syntax of options files is the same as the syntax for command lines, except that s do not terminate reading (only <;> or end of file). If an end of file is encountered before any characters are found that can begin an object or comment, then an end of file object is returned.  File: slib.info, Node: Parameter lists, Next: Getopt Parameter lists, Prev: Command Line, Up: Programs and Arguments 4.4.4 Parameter lists --------------------- `(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 procedure takes many arguments, many of which are not often used. A "parameter-list" is a way of passing named information to a procedure. Procedures are also defined to set unused parameters to default values, check parameters, and combine parameter lists. A PARAMETER has the form `(parameter-name value1 ...)'. This format allows for more than one value per parameter-name. A PARAMETER-LIST is a list of PARAMETERs, each with a different PARAMETER-NAME. -- Function: make-parameter-list parameter-names Returns an empty parameter-list with slots for PARAMETER-NAMES. -- Function: parameter-list-ref parameter-list parameter-name PARAMETER-NAME must name a valid slot of PARAMETER-LIST. `parameter-list-ref' returns the value of parameter PARAMETER-NAME of PARAMETER-LIST. -- Function: remove-parameter parameter-name parameter-list Removes the parameter PARAMETER-NAME from PARAMETER-LIST. `remove-parameter' does not alter the argument PARAMETER-LIST. If there are more than one PARAMETER-NAME parameters, an error is signaled. -- Procedure: adjoin-parameters! parameter-list parameter1 ... Returns PARAMETER-LIST with PARAMETER1 ... merged in. -- Procedure: parameter-list-expand expanders parameter-list EXPANDERS is a list of procedures whose order matches the order of the PARAMETER-NAMEs in the call to `make-parameter-list' which created PARAMETER-LIST. For each non-false element of EXPANDERS that procedure is mapped over the corresponding parameter value and the returned parameter lists are merged into PARAMETER-LIST. This process is repeated until PARAMETER-LIST stops growing. The value returned from `parameter-list-expand' is unspecified. -- Function: fill-empty-parameters defaulters parameter-list DEFAULTERS is a list of procedures whose order matches the order of the PARAMETER-NAMEs in the call to `make-parameter-list' which created PARAMETER-LIST. `fill-empty-parameters' returns a new parameter-list with each empty parameter replaced with the list returned by calling the corresponding DEFAULTER with PARAMETER-LIST as its argument. -- Function: check-parameters checks parameter-list CHECKS is a list of procedures whose order matches the order of the PARAMETER-NAMEs in the call to `make-parameter-list' which created PARAMETER-LIST. `check-parameters' returns PARAMETER-LIST if each CHECK of the corresponding PARAMETER-LIST returns non-false. If some CHECK returns `#f' a warning is signaled. In the following procedures ARITIES is a list of symbols. The elements of `arities' can be: `single' Requires a single parameter. `optional' A single parameter or no parameter is acceptable. `boolean' A single boolean parameter or zero parameters is acceptable. `nary' Any number of parameters are acceptable. `nary1' One or more of parameters are acceptable. -- Function: parameter-list->arglist positions arities parameter-list Returns PARAMETER-LIST converted to an argument list. Parameters of ARITY type `single' and `boolean' are converted to the single value associated with them. The other ARITY types are converted to lists of the value(s). POSITIONS is a list of positive integers whose order matches the order of the PARAMETER-NAMEs in the call to `make-parameter-list' which created PARAMETER-LIST. The integers specify in which argument position the corresponding parameter should appear.  File: slib.info, Node: Getopt Parameter lists, Next: Filenames, Prev: Parameter lists, Up: Programs and Arguments 4.4.5 Getopt Parameter lists ---------------------------- `(require 'getopt-parameters)' -- 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. ALIASES is a list of lists of strings or integers paired with elements of OPTNAMES. Each one-character string will be treated as a single `-' option by `getopt'. Longer strings will be treated as long-named options (*note getopt-: Getopt.). If the ALIASES association list has only strings as its `car's, then all the option-arguments after an option (and before the next option) are adjoined to that option. If the ALIASES association list has integers, then each (string) option will take at most one option-argument. Unoptioned arguments are collected in a list. A `-1' alias will take the last argument in this list; `+1' will take the first argument in the list. The aliases -2 then +2; -3 then +3; ... are tried so long as a positive or negative consecutive alias is found and arguments remain in the list. Finally a `0' alias, if found, absorbs any remaining arguments. In all cases, if unclaimed arguments remain after processing, a warning is signaled and #f is returned. -- Function: getopt->arglist optnames positions arities types defaulters checks aliases desc ... 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: Using Databases. If errors are encountered while processing options, directions for using the options (and argument strings DESC ...) are printed to `current-error-port'. (begin (set! *optind* 1) (set! *argv* '("cmd" "-?") (getopt->parameter-list '(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) '(("flag" flag) ("f" flag) ("Flag" flag2) ("B" flag3) ("optional" number) ("o" number) ("nary1" symbols) ("N" symbols) ("nary" symbols) ("n" symbols) ("single" string) ("s" string) ("a" num2) ("Abs" num3)))) -| Usage: cmd [OPTION ARGUMENT ...] ... -f, --flag -o, --optional= -n, --nary= ... -N, --nary1= ... -s, --single= --Flag -B -a ... --Abs= ... ERROR: getopt->parameter-list "unrecognized option" "-?"  File: slib.info, Node: Filenames, Next: Batch, Prev: Getopt Parameter lists, Up: Programs and Arguments 4.4.6 Filenames --------------- `(require 'filename)' | -- Function: filename:match?? pattern -- Function: filename:match-ci?? pattern Returns a predicate which returns a non-false value if its string argument matches (the string) PATTERN, false otherwise. Filename matching is like "glob" expansion described the bash manpage, except that names beginning with `.' are matched and `/' characters are not treated specially. These functions interpret the following characters specially in PATTERN strings: `*' Matches any string, including the null string. `?' Matches any single character. `[...]' Matches any one of the enclosed characters. A pair of characters separated by a minus sign (-) denotes a range; any character lexically between those two characters, inclusive, is matched. If the first character following the `[' is a `!' or a `^' then any character not enclosed is matched. A `-' 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 to glob patterns PATTERN and TEMPLATE. PATTERN and TEMPLATE must have the same number of wildcard specifications, which need not be identical. PATTERN and TEMPLATE may have a different number of literal sections. If an argument to the function matches PATTERN in the sense of `filename:match??' then it returns a copy of TEMPLATE in which each wildcard specification is replaced by the part of the argument matched by the corresponding wildcard specification in PATTERN. A `*' wildcard matches the longest leftmost string possible. If the argument does not match PATTERN then false is returned. TEMPLATE may be a function accepting the same number of string arguments as there are wildcard specifications in PATTERN. In the case of a match the result of applying TEMPLATE to a list of the 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" -- Function: replace-suffix str old new STR can be a string or a list of strings. Returns a new string (or strings) similar to `str' but with the suffix string OLD 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" -- 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 4.4.7 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 its first argument a parameter-list (*note Parameter lists::). This parameter-list argument PARMS contains named associations. Batch currently uses 2 of these: `batch-port' The port on which to write lines of the batch file. `batch-dialect' The syntax of batch file to generate. Currently supported are: * unix * dos * vms * amigaos * system * *unknown* The `batch' module 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: *operating-system* Is batch's best guess as to which operating-system it is running under. `*operating-system*' is set to `(software-type)' (*note Configuration::) unless `(software-type)' is `unix', in which case finer distinctions are made. -- Function: batch:call-with-output-script parms file proc PROC should be a procedure of one argument. If FILE is an output-port, `batch:call-with-output-script' writes an appropriate header to FILE and then calls PROC with FILE as the only argument. If FILE is a string, `batch:call-with-output-script' opens a output-file of name FILE, writes an appropriate header to FILE, and then calls PROC with the newly opened port as the only argument. Otherwise, `batch:call-with-output-script' acts as if it was called with the result of `(current-output-port)' as its third argument. The rest of the `batch:' procedures write (or execute if `batch-dialect' is `system') commands to the batch port which has been added to PARMS or `(copy-tree PARMS)' by the code: (adjoin-parameters! PARMS (list 'batch-port PORT)) -- Function: batch:command parms string1 string2 ... Calls `batch:try-command' (below) with arguments, but signals an error if `batch:try-command' returns `#f'. These functions return a non-false value if the command was successfully translated into the batch dialect and `#f' if not. In the case of the `system' dialect, the value is non-false if the operation suceeded. -- Function: batch:try-command parms string1 string2 ... Writes a command to the `batch-port' in PARMS which executes the program named STRING1 with arguments STRING2 .... -- Function: batch:try-chopped-command parms arg1 arg2 ... list breaks the last argument LIST into chunks small enough so that the command: ARG1 ARG2 ... CHUNK fits withing the platform's maximum command-line length. `batch:try-chopped-command' calls `batch:try-command' with the command and returns non-false only if the commands all fit and `batch:try-command' of each command line returned non-false. -- Function: batch:run-script parms string1 string2 ... Writes a command to the `batch-port' in PARMS which executes the batch script named STRING1 with arguments STRING2 .... _Note:_ `batch:run-script' and `batch:try-command' are not the same for some operating systems (VMS). -- Function: batch:comment parms line1 ... Writes comment lines LINE1 ... to the `batch-port' in PARMS. -- Function: batch:lines->file parms file line1 ... Writes commands to the `batch-port' in PARMS which create a file named FILE with contents LINE1 .... -- Function: batch:delete-file parms file Writes a command to the `batch-port' in PARMS which deletes the file named FILE. -- Function: batch:rename-file parms old-name new-name Writes a command to the `batch-port' in PARMS which renames the file OLD-NAME to NEW-NAME. In addition, batch provides some small utilities very useful for writing scripts: -- Function: truncate-up-to path char -- Function: truncate-up-to path string -- Function: truncate-up-to path charlist PATH can be a string or a list of strings. Returns PATH sans any prefixes ending with a character of the second argument. This can be used to derive a filename moved locally from elsewhere. (truncate-up-to "/usr/local/lib/slib/batch.scm" "/") => "batch.scm" -- Function: string-join joiner string1 ... Returns a new string consisting of all the strings STRING1 ... in order appended together with the string JOINER between each adjacent pair. -- Function: must-be-first list1 list2 Returns a new list consisting of the elements of LIST2 ordered so that if some elements of LIST1 are `equal?' to elements of LIST2, then those elements will appear first and in the order of LIST1. -- Function: must-be-last list1 list2 Returns a new list consisting of the elements of LIST1 ordered so that if some elements of LIST2 are `equal?' to elements of LIST1, then those elements will appear last and in the order of LIST2. -- Function: os->batch-dialect osname Returns its best guess for the `batch-dialect' to be used for the operating-system named OSNAME. `os->batch-dialect' uses the tables added to DATABASE by `batch:initialize!'. Here is an example of the use of most of batch's procedures: (require 'databases) (require 'parameters) (require 'batch) (require 'filename) | (define batch (create-database #f 'alist-table)) (batch:initialize! batch) (define my-parameters (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 my-parameters "my-batch" (lambda (batch-port) (adjoin-parameters! my-parameters (list 'batch-port batch-port)) (and (batch:comment my-parameters "================ Write file with C program.") (batch:rename-file my-parameters "hello.c" "hello.c~") (batch:lines->file my-parameters "hello.c" "#include " "int main(int argc, char **argv)" "{" " printf(\"hello world\\n\");" " return 0;" "}" ) (batch:command my-parameters "cc" "-c" "hello.c") (batch:command my-parameters "cc" "-o" "hello" (replace-suffix "hello.c" ".c" ".o")) (batch:command my-parameters "hello") (batch:delete-file my-parameters "hello") (batch:delete-file my-parameters "hello.c") (batch:delete-file my-parameters "hello.o") (batch:delete-file my-parameters "my-batch") ))) Produces the file `my-batch': #! /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~ rm -f hello.c echo '#include '>>hello.c echo 'int main(int argc, char **argv)'>>hello.c echo '{'>>hello.c echo ' printf("hello world\n");'>>hello.c echo ' return 0;'>>hello.c echo '}'>>hello.c cc -c hello.c cc -o hello hello.o hello rm -f hello rm -f hello.c rm -f hello.o rm -f my-batch When run, `my-batch' prints: bash$ my-batch mv: hello.c: No such file or directory hello world  File: slib.info, Node: HTML, Next: HTML Tables, Prev: Programs and Arguments, Up: Textual Conversion Packages 4.5 HTML ======== `(require 'html-form)' -- Function: html:atval txt Returns a string with character substitutions appropriate to send TXT as an "attribute-value". -- Function: html:plain txt Returns a string with character substitutions appropriate to send TXT as an "plain-text". -- Function: html:meta name content Returns a tag of meta-information suitable for passing as the third argument to `html:head'. The tag produced is `'. The string or symbol NAME can be `author', `copyright', `keywords', `description', `date', `robots', .... -- Function: html:http-equiv name content Returns a tag of HTTP information suitable for passing as the third argument to `html:head'. The tag produced is `'. The string or symbol NAME can be `Expires', `PICS-Label', `Content-Type', `Refresh', .... -- Function: html:meta-refresh delay uri -- Function: html:meta-refresh delay Returns a tag suitable for passing as the third argument to `html:head'. If URI argument is supplied, then DELAY seconds after displaying the page with this tag, Netscape or IE browsers will fetch and display URI. Otherwise, DELAY seconds after displaying the page with this tag, Netscape or IE browsers will fetch and redisplay this page. -- Function: html:head title backlink tags ... -- Function: html:head title backlink -- Function: html:head title Returns header string for an HTML page named TITLE. If BACKLINK is a string, it is used verbatim between the `H1' tags; otherwise TITLE is used. If string arguments TAGS ... are supplied, then they are included verbatim within the section. -- Function: html:body body ... Returns HTML string to end a page. -- Function: html:pre line1 line ... Returns the strings LINE1, LINES as "PRE"formmated plain text (rendered in fixed-width font). Newlines are inserted between LINE1, LINES. HTML tags (`') within LINES will be visible verbatim. -- Function: html:comment line1 line ... Returns the strings LINE1 as HTML comments. 4.6 HTML Forms ============== -- Function: html:form method action body ... The symbol METHOD is either `get', `head', `post', `put', or `delete'. The strings BODY form the body of the form. `html:form' returns the HTML "form". -- Function: html:hidden name value Returns HTML string which will cause NAME=VALUE in form. -- Function: html:checkbox pname default Returns HTML string for check box. -- Function: html:text pname default size ... Returns HTML string for one-line text box. -- Function: html:text-area pname default-list Returns HTML string for multi-line text box. -- Function: html:select pname arity default-list foreign-values Returns HTML string for pull-down menu selector. -- Function: html:buttons pname arity default-list foreign-values Returns HTML string for any-of selector. -- Function: form:submit submit-label command -- Function: form:submit submit-label The string or symbol SUBMIT-LABEL appears on the button which submits the form. If the optional second argument COMMAND is given, then `*command*=COMMAND' and `*button*=SUBMIT-LABEL' are set in the query. Otherwise, `*command*=SUBMIT-LABEL' is set in the query. -- Function: form:image submit-label image-src The IMAGE-SRC appears on the button which submits the form. -- Function: form:reset Returns a string which generates a "reset" button. -- Function: form:element pname arity default-list foreign-values Returns a string which generates an INPUT element for the field named PNAME. The element appears in the created form with its representation determined by its ARITY and domain. For domains which are foreign-keys: `single' select menu `optional' select menu `nary' check boxes `nary1' check boxes If the foreign-key table has a field named `visible-name', then the contents of that field are the names visible to the user for those choices. Otherwise, the foreign-key itself is visible. For other types of domains: `single' text area `optional' text area `boolean' check box `nary' text area `nary1' text area -- Function: form:delimited pname doc aliat arity default-list foreign-values Returns a HTML string for a form element embedded in a line of a 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 COMMAND-TABLE. `command->p-specs' returns a list of lists of PNAME, DOC, ALIAT, ARITY, DEFAULT-LIST, and FOREIGN-VALUES. The returned list has one element for each parameter of command COMMAND. This example demonstrates how to create a HTML-form for the `build' command. (require (in-vicinity (implementation-vicinity) "build.scm")) (call-with-output-file "buildscm.html" (lambda (port) (display (string-append (html:head 'commands) (html:body (sprintf #f "

%s:

%s
\\n" (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)))) port)))  File: slib.info, Node: HTML Tables, Next: HTTP and CGI, Prev: HTML, Up: Textual Conversion Packages 4.7 HTML Tables =============== `(require 'db->html)' -- Function: html:table options row ... -- Function: html:caption caption align -- Function: html:caption caption ALIGN can be `top' or `bottom'. -- Function: html:heading columns Outputs a heading row for the currently-started table. -- Function: html:href-heading columns uris Outputs a heading row with column-names COLUMNS linked to URIs URIS. -- Function: html:linked-row-converter k foreigns The positive integer K is the primary-key-limit (number of primary-keys) of the table. FOREIGNS is a list of the filenames of foreign-key field pages and #f for non foreign-key fields. `html:linked-row-converter' returns a procedure taking a row for its single argument. This returned procedure returns the html string for that table row. -- Function: table-name->filename table-name Returns the symbol TABLE-NAME converted to a filename. -- Function: table->linked-html caption db table-name match-key1 ... Returns HTML string for DB table TABLE-NAME chopped into 50-row HTML tables. Every foreign-key value is linked to the page (of the table) defining that key. The optional MATCH-KEY1 ... arguments restrict actions to a subset of the table. *Note match-key: Table Operations. -- Function: table->linked-page db table-name index-filename arg ... Returns a complete HTML page. The string INDEX-FILENAME names the page which refers to this one. The optional ARGS ... arguments restrict actions to a subset of the table. *Note match-key: Table Operations. -- Function: catalog->html db caption arg ... Returns HTML string for the catalog table of DB. 4.7.1 HTML editing tables ------------------------- A client can modify one row of an editable table at a time. For any change submitted, these routines check if that row has been modified during the time the user has been editing the form. If so, an error page results. The behavior of edited rows is: * If no fields are changed, then no change is made to the table. * If the primary keys equal null-keys (parameter defaults), and no other user has modified that row, then that row is deleted. * If only primary keys are changed, there are non-key fields, and no row with the new keys is in the table, then the old row is deleted and one with the new keys is inserted. * If only non-key fields are changed, and that row has not been modified by another user, then the row is changed to reflect the fields. * If both keys and non-key fields are changed, and no row with the new keys is in the table, then a row is created with the new keys and fields. * If fields are changed, all fields are primary keys, and no row with the new keys is in the table, then a row is created with the new keys. After any change to the table, a `sync-database' of the database is performed. -- Function: command:modify-table table-name null-keys update delete retrieve -- Function: command:modify-table table-name null-keys update delete -- 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 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 for editing one row of TABLE-NAME at a time. `command:make-editable-table' returns a procedure taking a row argument which returns the HTML string for editing that row. Optional ARGS are expressions (lists) added to the call to `command:modify-table'. The domain name of a column determines the expected arity of the data stored in that column. Domain names ending in: `*' have arity `nary'; `+' have arity `nary1'. -- Function: html:editable-row-converter k names edit-point edit-converter The positive integer K is the primary-key-limit (number of primary-keys) of the table. NAMES is a list of the field-names. EDIT-POINT is the list of primary-keys denoting the row to edit (or #f). EDIT-CONVERTER is the procedure called with K, NAMES, and the row to edit. `html:editable-row-converter' returns a procedure taking a row for its single argument. This returned procedure returns the html string for that table row. Each HTML table constructed using `html:editable-row-converter' has first K fields (typically the primary key fields) of each row linked to a text encoding of these fields (the result of calling `row->anchor'). The page so referenced typically allows the user to edit fields of that row. 4.7.2 HTML databases -------------------- -- Function: db->html-files db dir index-filename caption DB must be a relational database. DIR must be #f or a non-empty string naming an existing sub-directory of the current directory. `db->html-files' creates an html page for each table in the database DB in the sub-directory named DIR, or the current directory if DIR is #f. The top level page with the catalog of tables (captioned CAPTION) is written to a file named INDEX-FILENAME. -- Function: db->html-directory db dir index-filename -- Function: db->html-directory db dir DB must be a relational database. DIR must be a non-empty string naming an existing sub-directory of the current directory or one to be created. The optional string INDEX-FILENAME names the filename of the top page, which defaults to `index.html'. `db->html-directory' creates sub-directory DIR if neccessary, and calls `(db->html-files DB DIR INDEX-FILENAME DIR)'. The `file:' URI of INDEX-FILENAME is returned. -- Function: db->netscape db dir index-filename -- Function: db->netscape db dir `db->netscape' is just like `db->html-directory', but calls `browse-url' with the uri for the top page after the pages are created.  File: slib.info, Node: HTTP and CGI, Next: Parsing HTML, Prev: HTML Tables, Up: Textual Conversion Packages 4.8 HTTP and CGI ================ `(require 'http)' or `(require 'cgi)' -- Function: http:header alist Returns a string containing lines for each element of ALIST; the `car' of which is followed by `: ', then the `cdr'. -- Function: http:content alist body ... Returns the concatenation of strings BODY with the `(http:header ALIST)' and the `Content-Length' prepended. -- Variable: *http:byline* String appearing at the bottom of error pages. -- Function: http:error-page status-code reason-phrase html-string ... STATUS-CODE and REASON-PHRASE should be an integer and string as specified in `RFC 2068'. The returned page (string) will show the STATUS-CODE and REASON-PHRASE and any additional HTML-STRINGS ...; with *HTTP:BYLINE* or SLIB's default at the bottom. -- Function: http:forwarding-page title dly uri html-string ... The string or symbol TITLE is the page title. DLY is a non-negative integer. The HTML-STRINGS ... are typically used to explain to the user why this page is being forwarded. `http:forwarding-page' returns an HTML string for a page which automatically forwards to URI after DLY seconds. The returned page (string) contains any HTML-STRINGS ... followed by a manual link to URI, in case the browser does not forward automatically. -- Function: http:serve-query serve-proc input-port output-port reads the "URI" and "query-string" from INPUT-PORT. If the query is a valid `"POST"' or `"GET"' query, then `http:serve-query' calls SERVE-PROC with three arguments, the REQUEST-LINE, QUERY-STRING, and HEADER-ALIST. Otherwise, `http:serve-query' calls SERVE-PROC with the REQUEST-LINE, #f, and HEADER-ALIST. If SERVE-PROC returns a string, it is sent to OUTPUT-PORT. If SERVE-PROC returns a list, then an error page with number 525 and strings from the list. If SERVE-PROC returns #f, then a `Bad Request' (400) page is sent to OUTPUT-PORT. Otherwise, `http:serve-query' replies (to OUTPUT-PORT) with appropriate HTML describing the problem. This example services HTTP queries from PORT-NUMBER: (define socket (make-stream-socket AF_INET 0)) (and (socket:bind socket port-number) ; AF_INET INADDR_ANY (socket:listen socket 10) ; Queue up to 10 requests. (dynamic-wind (lambda () #f) (lambda () (do ((port (socket:accept socket) (socket:accept socket))) (#f) (let ((iport (duplicate-port port "r")) (oport (duplicate-port port "w"))) (http:serve-query build:serve iport oport) (close-port iport) (close-port oport)) (close-port port))) (lambda () (close-port socket)))) -- Function: cgi:serve-query serve-proc reads the "URI" and "query-string" from `(current-input-port)'. If the query is a valid `"POST"' or `"GET"' query, then `cgi:serve-query' calls SERVE-PROC with three arguments, the REQUEST-LINE, QUERY-STRING, and HEADER-ALIST. Otherwise, `cgi:serve-query' calls SERVE-PROC with the REQUEST-LINE, #f, and HEADER-ALIST. If SERVE-PROC returns a string, it is sent to `(current-input-port)'. If SERVE-PROC returns a list, then an error page with number 525 and strings from the list. If SERVE-PROC returns #f, then a `Bad Request' (400) page is sent to `(current-input-port)'. Otherwise, `cgi:serve-query' replies (to `(current-input-port)') with appropriate HTML describing the problem. -- Function: make-query-alist-command-server rdb command-table -- Function: make-query-alist-command-server rdb command-table #t Returns a procedure of one argument. When that procedure is called with a QUERY-ALIST (as returned by `uri:decode-query', the value of the `*command*' association will be the command invoked in COMMAND-TABLE. If `*command*' is not in the QUERY-ALIST then the value of `*suggest*' is tried. If neither name is in the QUERY-ALIST, then the literal value `*default*' is tried in COMMAND-TABLE. If optional third argument is non-false, then the command is called with just the parameter-list; otherwise, command is called with the arguments described in its table.  File: slib.info, Node: Parsing HTML, Next: URI, Prev: HTTP and CGI, Up: Textual Conversion Packages 4.9 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: Parsing XML, Prev: Parsing HTML, Up: Textual Conversion Packages 4.10 URI ======== `(require 'uri)' Implements "Uniform Resource Identifiers" (URI) as described in RFC 2396. -- Function: make-uri -- Function: make-uri fragment -- Function: make-uri query fragment -- Function: make-uri path query fragment -- Function: make-uri authority path query fragment -- Function: make-uri scheme authority path query fragment 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 `' will link to this point. (html:anchor "(section 7)") => "" -- Function: html:link uri highlighted Returns a string which links the HIGHLIGHTED text to URI. (html:link (make-uri "(section 7)") "section 7") => "section 7" -- Function: html:base uri Returns a string specifying the "base" URI of a document, for inclusion in the HEAD of the document (*note head: HTML.). -- Function: html:isindex prompt 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 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 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). For other types of AUTHORITY components the AUTHORITY will be a string. (uri->tree "http://www.ics.uci.edu/pub/ietf/uri/#Related") => (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 Returns a copy of the string URI-COMPONENT in which all "unsafe" octets (as defined in RFC 2396) have been `%' "escaped". `uric:decode' decodes strings encoded by `uric:encode'. -- Function: uric:decode uri-component Returns a copy of the string URI-COMPONENT in which each `%' escaped characters in URI-COMPONENT is replaced with the character 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: Parsing XML, Next: Printing Scheme, Prev: URI, Up: Textual Conversion Packages 4.11 Parsing XML ================ `(require 'xml-parse)' or `(require 'ssax)' The XML standard document referred to in this module is `http://www.w3.org/TR/1998/REC-xml-19980210.html'. The present frameworks fully supports the XML Namespaces Recommendation `http://www.w3.org/TR/REC-xml-names'. 4.11.1 String Glue ------------------ -- Function: ssax:reverse-collect-str list-of-frags Given the list of fragments (some of which are text strings), reverse the list and concatenate adjacent text strings. If LIST-OF-FRAGS has zero or one element, the result of the procedure is `equal?' to its argument. -- Function: ssax:reverse-collect-str-drop-ws list-of-frags Given the list of fragments (some of which are text strings), reverse the list and concatenate adjacent text strings while dropping "unsignificant" whitespace, that is, whitespace in front, behind and between elements. The whitespace that is included in character data is not affected. Use this procedure to "intelligently" drop "insignificant" whitespace in the parsed SXML. If the strict compliance with the XML Recommendation regarding the whitespace is desired, use the `ssax:reverse-collect-str' procedure instead. 4.11.2 Character and Token Functions ------------------------------------ The following functions either skip, or build and return tokens, according to inclusion or delimiting semantics. The list of characters to expect, include, or to break at may vary from one invocation of a function to another. This allows the functions to easily parse even context-sensitive languages. Exceptions are mentioned specifically. The list of expected characters (characters to skip until, or break-characters) may include an EOF "character", which is coded as symbol *eof* The input stream to parse is specified as a PORT, which is the last argument. -- Function: ssax:assert-current-char char-list string port Reads a character from the PORT and looks it up in the CHAR-LIST of expected characters. If the read character was found among expected, it is returned. Otherwise, the procedure writes a message using STRING as a comment and quits. -- Function: ssax:skip-while char-list port Reads characters from the PORT and disregards them, as long as they are mentioned in the CHAR-LIST. The first character (which may be EOF) peeked from the stream that is _not_ a member of the CHAR-LIST is returned. -- Function: ssax:init-buffer Returns an initial buffer for `ssax:next-token*' procedures. `ssax:init-buffer' may allocate a new buffer at each invocation. -- Function: ssax:next-token prefix-char-list break-char-list comment-string port Skips any number of the prefix characters (members of the PREFIX-CHAR-LIST), if any, and reads the sequence of characters up to (but not including) a break character, one of the BREAK-CHAR-LIST. The string of characters thus read is returned. The break character is left on the input stream. BREAK-CHAR-LIST may include the symbol `*eof*'; otherwise, EOF is fatal, generating an error message including a specified COMMENT-STRING. `ssax:next-token-of' is similar to `ssax:next-token' except that it implements an inclusion rather than delimiting semantics. -- Function: ssax:next-token-of inc-charset port Reads characters from the PORT that belong to the list of characters INC-CHARSET. The reading stops at the first character which is not a member of the set. This character is left on the stream. All the read characters are returned in a string. -- Function: ssax:next-token-of pred port Reads characters from the PORT for which PRED (a procedure of one argument) returns non-#f. The reading stops at the first character for which PRED returns #f. That character is left on the stream. All the results of evaluating of PRED up to #f are returned in a string. PRED is a procedure that takes one argument (a character or the EOF object) and returns a character or #f. The returned character does not have to be the same as the input argument to the PRED. For example, (ssax:next-token-of (lambda (c) (cond ((eof-object? c) #f) ((char-alphabetic? c) (char-downcase c)) (else #f))) (current-input-port)) will try to read an alphabetic token from the current input port, and return it in lower case. -- Function: ssax:read-string len port Reads LEN characters from the PORT, and returns them in a string. If EOF is encountered before LEN characters are read, a shorter string will be returned. 4.11.3 Data Types ----------------- `TAG-KIND' A symbol `START', `END', `PI', `DECL', `COMMENT', `CDSECT', or `ENTITY-REF' that identifies a markup token `UNRES-NAME' a name (called GI in the XML Recommendation) as given in an XML document for a markup token: start-tag, PI target, attribute name. If a GI is an NCName, UNRES-NAME is this NCName converted into a Scheme symbol. If a GI is a QName, `UNRES-NAME' is a pair of symbols: `(PREFIX . LOCALPART)'. `RES-NAME' An expanded name, a resolved version of an `UNRES-NAME'. For an element or an attribute name with a non-empty namespace URI, `RES-NAME' is a pair of symbols, `(URI-SYMB . LOCALPART)'. Otherwise, it's a single symbol. `ELEM-CONTENT-MODEL' A symbol: `ANY' anything goes, expect an END tag. `EMPTY-TAG' no content, and no END-tag is coming `EMPTY' no content, expect the END-tag as the next token `PCDATA' expect character data only, and no children elements `MIXED' `ELEM-CONTENT' `URI-SYMB' A symbol representing a namespace URI - or other symbol chosen by the user to represent URI. In the former case, `URI-SYMB' is created by %-quoting of bad URI characters and converting the resulting string into a symbol. `NAMESPACES' A list representing namespaces in effect. An element of the list has one of the following forms: `(PREFIX URI-SYMB . URI-SYMB) or' `(PREFIX USER-PREFIX . URI-SYMB)' USER-PREFIX is a symbol chosen by the user to represent the URI. `(#f USER-PREFIX . URI-SYMB)' Specification of the user-chosen prefix and a URI-SYMBOL. `(*DEFAULT* USER-PREFIX . URI-SYMB)' Declaration of the default namespace `(*DEFAULT* #f . #f)' Un-declaration of the default namespace. This notation represents overriding of the previous declaration A NAMESPACES list may contain several elements for the same PREFIX. The one closest to the beginning of the list takes effect. `ATTLIST' An ordered collection of (NAME . VALUE) pairs, where NAME is a RES-NAME or an UNRES-NAME. The collection is an ADT. `STR-HANDLER' A procedure of three arguments: STRING1 STRING2 SEED returning a new SEED. The procedure is supposed to handle a chunk of character data STRING1 followed by a chunk of character data STRING2. STRING2 is a short string, often `"\n"' and even `""'. `ENTITIES' An assoc list of pairs: (NAMED-ENTITY-NAME . NAMED-ENTITY-BODY) where NAMED-ENTITY-NAME is a symbol under which the entity was declared, NAMED-ENTITY-BODY is either a string, or (for an external entity) a thunk that will return an input port (from which the entity can be read). NAMED-ENTITY-BODY may also be #f. This is an indication that a NAMED-ENTITY-NAME is currently being expanded. A reference to this NAMED-ENTITY-NAME will be an error: violation of the WFC nonrecursion. `XML-TOKEN' This record represents a markup, which is, according to the XML Recommendation, "takes the form of start-tags, end-tags, empty-element tags, entity references, character references, comments, CDATA section delimiters, document type declarations, and processing instructions." kind a TAG-KIND head an UNRES-NAME. For XML-TOKENs of kinds 'COMMENT and 'CDSECT, the head is #f. For example,

=> kind=START, head=P

=> kind=END, head=P
=> kind=EMPTY-EL, head=BR => kind=DECL, head=DOCTYPE => kind=PI, head=xml &my-ent; => kind=ENTITY-REF, head=my-ent Character references are not represented by xml-tokens as these references are transparently resolved into the corresponding characters. `XML-DECL' The record represents a datatype of an XML document: the list of declared elements and their attributes, declared notations, list of replacement strings or loading procedures for parsed general entities, etc. Normally an XML-DECL record is created from a DTD or an XML Schema, although it can be created and filled in in many other ways (e.g., loaded from a file). ELEMS an (assoc) list of decl-elem or #f. The latter instructs the parser to do no validation of elements and attributes. DECL-ELEM declaration of one element: `(ELEM-NAME ELEM-CONTENT DECL-ATTRS)' ELEM-NAME is an UNRES-NAME for the element. ELEM-CONTENT is an ELEM-CONTENT-MODEL. DECL-ATTRS is an `ATTLIST', of `(ATTR-NAME . VALUE)' associations. This element can declare a user procedure to handle parsing of an element (e.g., to do a custom validation, or to build a hash of IDs as they're encountered). DECL-ATTR an element of an `ATTLIST', declaration of one attribute: `(ATTR-NAME CONTENT-TYPE USE-TYPE DEFAULT-VALUE)' ATTR-NAME is an UNRES-NAME for the declared attribute. CONTENT-TYPE is a symbol: `CDATA', `NMTOKEN', `NMTOKENS', ... or a list of strings for the enumerated type. USE-TYPE is a symbol: `REQUIRED', `IMPLIED', or `FIXED'. DEFAULT-VALUE is a string for the default value, or #f if not given. 4.11.4 Low-Level Parsers and Scanners ------------------------------------- These procedures deal with primitive lexical units (Names, whitespaces, tags) and with pieces of more generic productions. Most of these parsers must be called in appropriate context. For example, `ssax:complete-start-tag' must be called only when the start-tag has been detected and its GI has been read. -- Function: ssax:skip-s port Skip the S (whitespace) production as defined by [3] S ::= (#x20 | #x09 | #x0D | #x0A) `ssax:skip-s' returns the first not-whitespace character it encounters while scanning the PORT. This character is left on the input stream. -- Function: ssax:read-ncname port Read a NCName starting from the current position in the PORT and return it as a symbol. [4] NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' | CombiningChar | Extender [5] Name ::= (Letter | '_' | ':') (NameChar)* This code supports the XML Namespace Recommendation REC-xml-names, which modifies the above productions as follows: [4] NCNameChar ::= Letter | Digit | '.' | '-' | '_' | CombiningChar | Extender [5] NCName ::= (Letter | '_') (NCNameChar)* As the Rec-xml-names says, "An XML document conforms to this specification if all other tokens [other than element types and attribute names] in the document which are required, for XML conformance, to match the XML production for Name, match this specification's production for NCName." Element types and attribute names must match the production QName, defined below. -- Function: ssax:read-qname port Read a (namespace-) Qualified Name, QName, from the current position in PORT; and return an UNRES-NAME. From REC-xml-names: [6] QName ::= (Prefix ':')? LocalPart [7] Prefix ::= NCName [8] LocalPart ::= NCName -- Function: ssax:read-markup-token port This procedure starts parsing of a markup token. The current position in the stream must be `<'. This procedure scans enough of the input stream to figure out what kind of a markup token it is seeing. The procedure returns an XML-TOKEN structure describing the token. Note, generally reading of the current markup is not finished! In particular, no attributes of the start-tag token are scanned. Here's a detailed break out of the return values and the position in the PORT when that particular value is returned: PI-token only PI-target is read. To finish the Processing-Instruction and disregard it, call `ssax:skip-pi'. `ssax:read-attributes' may be useful as well (for PIs whose content is attribute-value pairs). END-token The end tag is read completely; the current position is right after the terminating `>' character. COMMENT is read and skipped completely. The current position is right after `-->' that terminates the comment. CDSECT The current position is right after `' combination that terminates PI. [16] PI ::= '' Char*)))? '?>' -- Function: ssax:skip-internal-dtd port The current pos in the port is inside an internal DTD subset (e.g., after reading `#\[' that begins an internal DTD subset) Skip until the `]>' combination that terminates this DTD. -- Function: ssax:read-cdata-body port str-handler seed This procedure must be called after we have read a string `' combination is the end of the CDATA section. `>' is treated as an embedded `>' character. * `<' and `&' are not specially recognized (and are not expanded)! -- Function: ssax:read-char-ref port [66] CharRef ::= '&#' [0-9]+ ';' | '&#x' [0-9a-fA-F]+ ';' This procedure must be called after we we have read `&#' that introduces a char reference. The procedure reads this reference and returns the corresponding char. The current position in PORT will be after the `;' that terminates the char reference. Faults detected: WFC: XML-Spec.html#wf-Legalchar According to Section `4.1 Character and Entity References' of the XML Recommendation: "[Definition: A character reference refers to a specific character in the ISO/IEC 10646 character set, for example one not directly accessible from available input devices.]" -- Function: ssax:handle-parsed-entity port name entities content-handler str-handler seed Expands and handles a parsed-entity reference. NAME is a symbol, the name of the parsed entity to expand. CONTENT-HANDLER is a procedure of arguments PORT, ENTITIES, and SEED that returns a seed. STR-HANDLER is called if the entity in question is a pre-declared entity. `ssax:handle-parsed-entity' returns the result returned by CONTENT-HANDLER or STR-HANDLER. Faults detected: WFC: XML-Spec.html#wf-entdeclared WFC: XML-Spec.html#norecursion -- Function: attlist-add attlist name-value Add a NAME-VALUE pair to the existing ATTLIST, preserving its sorted ascending order; and return the new list. Return #f if a pair with the same name already exists in ATTLIST -- Function: attlist-remove-top attlist Given an non-null ATTLIST, return a pair of values: the top and the rest. -- Function: ssax:read-attributes port entities This procedure reads and parses a production "Attribute". [41] Attribute ::= Name Eq AttValue [10] AttValue ::= '"' ([^<&"] | Reference)* '"' | "'" ([^<&'] | Reference)* "'" [25] Eq ::= S? '=' S? The procedure returns an ATTLIST, of Name (as UNRES-NAME), Value (as string) pairs. The current character on the PORT is a non-whitespace character that is not an NCName-starting character. Note the following rules to keep in mind when reading an "AttValue": Before the value of an attribute is passed to the application or checked for validity, the XML processor must normalize it as follows: * A character reference is processed by appending the referenced character to the attribute value. * An entity reference is processed by recursively processing the replacement text of the entity. The named entities `amp', `lt', `gt', `quot', and `apos' are pre-declared. * A whitespace character (#x20, #x0D, #x0A, #x09) is processed by appending #x20 to the normalized value, except that only a single #x20 is appended for a "#x0D#x0A" sequence that is part of an external parsed entity or the literal entity value of an internal parsed entity. * Other characters are processed by appending them to the normalized value. Faults detected: WFC: XML-Spec.html#CleanAttrVals WFC: XML-Spec.html#uniqattspec -- Function: ssax:resolve-name port unres-name namespaces apply-default-ns? Convert an UNRES-NAME to a RES-NAME, given the appropriate NAMESPACES declarations. The last parameter, APPLY-DEFAULT-NS?, determines if the default namespace applies (for instance, it does not for attribute names). Per REC-xml-names/#nsc-NSDeclared, the "xml" prefix is considered pre-declared and bound to the namespace name "http://www.w3.org/XML/1998/namespace". `ssax:resolve-name' tests for the namespace constraints: `http://www.w3.org/TR/REC-xml-names/#nsc-NSDeclared' -- Function: ssax:complete-start-tag tag port elems entities namespaces Complete parsing of a start-tag markup. `ssax:complete-start-tag' must be called after the start tag token has been read. TAG is an UNRES-NAME. ELEMS is an instance of the ELEMS slot of XML-DECL; it can be #f to tell the function to do _no_ validation of elements and their attributes. `ssax:complete-start-tag' returns several values: * ELEM-GI: a RES-NAME. * ATTRIBUTES: element's attributes, an ATTLIST of (RES-NAME . STRING) pairs. The list does NOT include xmlns attributes. * NAMESPACES: the input list of namespaces amended with namespace (re-)declarations contained within the start-tag under parsing * ELEM-CONTENT-MODEL On exit, the current position in PORT will be the first character after `>' that terminates the start-tag markup. Faults detected: VC: XML-Spec.html#enum VC: XML-Spec.html#RequiredAttr VC: XML-Spec.html#FixedAttr VC: XML-Spec.html#ValueType WFC: XML-Spec.html#uniqattspec (after namespaces prefixes are resolved) VC: XML-Spec.html#elementvalid WFC: REC-xml-names/#dt-NSName _Note_: although XML Recommendation does not explicitly say it, xmlns and xmlns: attributes don't have to be declared (although they can be declared, to specify their default value). -- Function: ssax:read-external-id port Parses an ExternalID production: [75] ExternalID ::= 'SYSTEM' S SystemLiteral | 'PUBLIC' S PubidLiteral S SystemLiteral [11] SystemLiteral ::= ('"' [^"]* '"') | ("'" [^']* "'") [12] PubidLiteral ::= '"' PubidChar* '"' | "'" (PubidChar - "'")* "'" [13] PubidChar ::= #x20 | #x0D | #x0A | [a-zA-Z0-9] | [-'()+,./:=?;!*#@$_%] Call `ssax:read-external-id' when an ExternalID is expected; that is, the current character must be either #\S or #\P that starts correspondingly a SYSTEM or PUBLIC token. `ssax:read-external-id' returns the SYSTEMLITERAL as a string. A PUBIDLITERAL is disregarded if present. 4.11.5 Mid-Level Parsers and Scanners ------------------------------------- These procedures parse productions corresponding to the whole (document) entity or its higher-level pieces (prolog, root element, etc). -- Function: ssax:scan-misc port Scan the Misc production in the context: [1] document ::= prolog element Misc* [22] prolog ::= XMLDecl? Misc* (doctypedec l Misc*)? [27] Misc ::= Comment | PI | S Call `ssax:scan-misc' in the prolog or epilog contexts. In these contexts, whitespaces are completely ignored. The return value from `ssax:scan-misc' is either a PI-token, a DECL-token, a START token, or *EOF*. Comments are ignored and not reported. -- Function: ssax:read-char-data port expect-eof? str-handler iseed Read the character content of an XML document or an XML element. [43] content ::= (element | CharData | Reference | CDSect | PI | Comment)* To be more precise, `ssax:read-char-data' reads CharData, expands CDSect and character entities, and skips comments. `ssax:read-char-data' stops at a named reference, EOF, at the beginning of a PI, or a start/end tag. EXPECT-EOF? is a boolean indicating if EOF is normal; i.e., the character data may be terminated by the EOF. EOF is normal while processing a parsed entity. ISEED is an argument passed to the first invocation of STR-HANDLER. `ssax:read-char-data' returns two results: SEED and TOKEN. The SEED is the result of the last invocation of STR-HANDLER, or the original ISEED if STR-HANDLER was never called. TOKEN can be either an eof-object (this can happen only if EXPECT-EOF? was #t), or: * an xml-token describing a START tag or an END-tag; For a start token, the caller has to finish reading it. * an xml-token describing the beginning of a PI. It's up to an application to read or skip through the rest of this PI; * an xml-token describing a named entity reference. CDATA sections and character references are expanded inline and never returned. Comments are silently disregarded. As the XML Recommendation requires, all whitespace in character data must be preserved. However, a CR character (#x0D) must be disregarded if it appears before a LF character (#x0A), or replaced by a #x0A character otherwise. See Secs. 2.10 and 2.11 of the XML Recommendation. See also the canonical XML Recommendation. -- Function: ssax:assert-token token kind gi error-cont Make sure that TOKEN is of anticipated KIND and has anticipated GI. Note that the GI argument may actually be a pair of two symbols, Namespace-URI or the prefix, and of the localname. If the assertion fails, ERROR-CONT is evaluated by passing it three arguments: TOKEN KIND GI. The result of ERROR-CONT is returned. 4.11.6 High-level Parsers ------------------------- These procedures are to instantiate a SSAX parser. A user can instantiate the parser to do the full validation, or no validation, or any particular validation. The user specifies which PI he wants to be notified about. The user tells what to do with the parsed character and element data. The latter handlers determine if the parsing follows a SAX or a DOM model. -- Function: ssax:make-pi-parser my-pi-handlers Create a parser to parse and process one Processing Element (PI). MY-PI-HANDLERS is an association list of pairs `(PI-TAG . PI-HANDLER)' where PI-TAG is an NCName symbol, the PI target; and PI-HANDLER is a procedure taking arguments PORT, PI-TAG, and SEED. PI-HANDLER should read the rest of the PI up to and including the combination `?>' that terminates the PI. The handler should return a new seed. One of the PI-TAGs may be the symbol `*DEFAULT*'. The corresponding handler will handle PIs that no other handler will. If the *DEFAULT* PI-TAG is not specified, `ssax:make-pi-parser' will assume the default handler that skips the body of the PI. `ssax:make-pi-parser' returns a procedure of arguments PORT, PI-TAG, and SEED; that will parse the current PI according to MY-PI-HANDLERS. -- Function: ssax:make-elem-parser my-new-level-seed my-finish-element my-char-data-handler my-pi-handlers Create a parser to parse and process one element, including its character content or children elements. The parser is typically applied to the root element of a document. MY-NEW-LEVEL-SEED is a procedure taking arguments: ELEM-GI ATTRIBUTES NAMESPACES EXPECTED-CONTENT SEED where ELEM-GI is a RES-NAME of the element about to be processed. MY-NEW-LEVEL-SEED is to generate the seed to be passed to handlers that process the content of the element. MY-FINISH-ELEMENT is a procedure taking arguments: ELEM-GI ATTRIBUTES NAMESPACES PARENT-SEED SEED MY-FINISH-ELEMENT is called when parsing of ELEM-GI is finished. The SEED is the result from the last content parser (or from MY-NEW-LEVEL-SEED if the element has the empty content). PARENT-SEED is the same seed as was passed to MY-NEW-LEVEL-SEED. MY-FINISH-ELEMENT is to generate a seed that will be the result of the element parser. MY-CHAR-DATA-HANDLER is a STR-HANDLER as described in Data Types above. MY-PI-HANDLERS is as described for `ssax:make-pi-handler' above. The generated parser is a procedure taking arguments: START-TAG-HEAD PORT ELEMS ENTITIES NAMESPACES PRESERVE-WS? SEED The procedure must be called after the start tag token has been read. START-TAG-HEAD is an UNRES-NAME from the start-element tag. ELEMS is an instance of ELEMS slot of XML-DECL. Faults detected: VC: XML-Spec.html#elementvalid WFC: XML-Spec.html#GIMatch -- Function: ssax:make-parser user-handler-tag user-handler ... Create an XML parser, an instance of the XML parsing framework. This will be a SAX, a DOM, or a specialized parser depending on the supplied user-handlers. `ssax:make-parser' takes an even number of arguments; USER-HANDLER-TAG is a symbol that identifies a procedure (or association list for `PROCESSING-INSTRUCTIONS') (USER-HANDLER) that follows the tag. Given below are tags and signatures of the corresponding procedures. Not all tags have to be specified. If some are omitted, reasonable defaults will apply. `DOCTYPE' handler-procedure: PORT DOCNAME SYSTEMID INTERNAL-SUBSET? SEED If INTERNAL-SUBSET? is #t, the current position in the port is right after we have read `[' that begins the internal DTD subset. We must finish reading of this subset before we return (or must call `skip-internal-dtd' if we aren't interested in reading it). PORT at exit must be at the first symbol after the whole DOCTYPE declaration. The handler-procedure must generate four values: ELEMS ENTITIES NAMESPACES SEED ELEMS is as defined for the ELEMS slot of XML-DECL. It may be #f to switch off validation. NAMESPACES will typically contain USER-PREFIXes for selected URI-SYMBs. The default handler-procedure skips the internal subset, if any, and returns `(values #f '() '() seed)'. `UNDECL-ROOT' procedure: ELEM-GI SEED where ELEM-GI is an UNRES-NAME of the root element. This procedure is called when an XML document under parsing contains _no_ DOCTYPE declaration. The handler-procedure, as a DOCTYPE handler procedure above, must generate four values: ELEMS ENTITIES NAMESPACES SEED The default handler-procedure returns (values #f '() '() seed) `DECL-ROOT' procedure: ELEM-GI SEED where ELEM-GI is an UNRES-NAME of the root element. This procedure is called when an XML document under parsing does contains the DOCTYPE declaration. The handler-procedure must generate a new SEED (and verify that the name of the root element matches the doctype, if the handler so wishes). The default handler-procedure is the identity function. `NEW-LEVEL-SEED' procedure: see ssax:make-elem-parser, my-new-level-seed `FINISH-ELEMENT' procedure: see ssax:make-elem-parser, my-finish-element `CHAR-DATA-HANDLER' procedure: see ssax:make-elem-parser, my-char-data-handler `PROCESSING-INSTRUCTIONS' association list as is passed to `ssax:make-pi-parser'. The default value is '() The generated parser is a procedure of arguments PORT and SEED. This procedure parses the document prolog and then exits to an element parser (created by `ssax:make-elem-parser') to handle the rest. [1] document ::= prolog element Misc* [22] prolog ::= XMLDecl? Misc* (doctypedec | Misc*)? [27] Misc ::= Comment | PI | S [28] doctypedecl ::= '' [29] markupdecl ::= elementdecl | AttlistDecl | EntityDecl | NotationDecl | PI | Comment 4.11.7 Parsing XML to SXML -------------------------- -- Function: ssax:xml->sxml port namespace-prefix-assig This is an instance of the SSAX parser that returns an SXML representation of the XML document to be read from PORT. NAMESPACE-PREFIX-ASSIG is a list of `(USER-PREFIX . URI-STRING)' that assigns USER-PREFIXes to certain namespaces identified by particular URI-STRINGs. It may be an empty list. `ssax:xml->sxml' returns an SXML tree. The port points out to the first character after the root element.  File: slib.info, Node: Printing Scheme, Next: Time and Date, Prev: Parsing XML, Up: Textual Conversion Packages 4.12 Printing Scheme ==================== * Menu: * Generic-Write:: 'generic-write * Object-To-String:: 'object->string * Pretty-Print:: 'pretty-print, 'pprint-file  File: slib.info, Node: Generic-Write, Next: Object-To-String, Prev: Printing Scheme, Up: Printing Scheme 4.12.1 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 prints it. The interface to the procedure is sufficiently general to easily implement other useful formatting procedures such as pretty printing, output to a string and truncated output. -- Procedure: generic-write obj display? width output OBJ Scheme data value to transform. DISPLAY? Boolean, controls whether characters and strings are quoted. WIDTH Extended boolean, selects format: #f single line format integer > 0 pretty-print (value = max nb of chars per line) OUTPUT Procedure of 1 argument of string type, called repeatedly with successive substrings of the textual representation. This procedure can return `#f' to stop the transformation. The value returned by `generic-write' is undefined. Examples: (write obj) == (generic-write obj #f #f DISPLAY-STRING) (display obj) == (generic-write obj #t #f DISPLAY-STRING) where DISPLAY-STRING == (lambda (s) (for-each write-char (string->list s)) #t)  File: slib.info, Node: Object-To-String, Next: Pretty-Print, Prev: Generic-Write, Up: Printing Scheme 4.12.2 Object-To-String ----------------------- `(require 'object->string)' -- Function: object->string obj Returns the textual representation of OBJ as a string. -- Function: object->limited-string obj limit Returns the textual representation of OBJ as a string of length at most LIMIT.  File: slib.info, Node: Pretty-Print, Prev: Object-To-String, Up: Printing Scheme 4.12.3 Pretty-Print ------------------- `(require 'pretty-print)' -- Procedure: pretty-print obj -- Procedure: pretty-print obj port `pretty-print's OBJ on PORT. If PORT is not specified, `current-output-port' is used. Example: (pretty-print '((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) (16 17 18 19 20) (21 22 23 24 25))) -| ((1 2 3 4 5) -| (6 7 8 9 10) -| (11 12 13 14 15) -| (16 17 18 19 20) -| (21 22 23 24 25)) -- Procedure: pretty-print->string obj -- Procedure: pretty-print->string obj width Returns the string of OBJ `pretty-print'ed in WIDTH columns. If WIDTH is not specified, `(output-port-width)' is used. Example: (pretty-print->string '((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) (16 17 18 19 20) (21 22 23 24 25))) => "((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) (16 17 18 19 20) (21 22 23 24 25)) " (pretty-print->string '((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) (16 17 18 19 20) (21 22 23 24 25)) 16) => "((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15) (16 17 18 19 20) (21 22 23 24 25)) " `(require 'pprint-file)' -- Procedure: pprint-file infile -- Procedure: pprint-file infile outfile Pretty-prints all the code in INFILE. If OUTFILE is specified, the output goes to OUTFILE, otherwise it goes to `(current-output-port)'. -- Function: pprint-filter-file infile proc outfile -- Function: pprint-filter-file infile proc INFILE is a port or a string naming an existing file. Scheme source code expressions and definitions are read from the port (or file) and PROC is applied to them sequentially. OUTFILE is a port or a string. If no OUTFILE is specified then `current-output-port' is assumed. These expanded expressions are then `pretty-print'ed to this port. Whitepsace and comments (introduced by `;') which are not part of scheme expressions are reproduced in the output. This procedure does not affect the values returned by `current-input-port' and `current-output-port'. `pprint-filter-file' can be used to pre-compile macro-expansion and thus can reduce loading time. The following will write into `exp-code.scm' the result of expanding all defmacros in `code.scm'. (require 'pprint-file) (require 'defmacroexpand) (defmacro:load "my-macros.scm") (pprint-filter-file "code.scm" defmacro:expand* "exp-code.scm")  File: slib.info, Node: Time and Date, Next: NCBI-DNA, Prev: Printing Scheme, Up: Textual Conversion Packages 4.13 Time and Date ================== * Menu: * Time Zone:: * Posix Time:: 'posix-time * Common-Lisp Time:: 'common-lisp-time * Time Infrastructure:: If `(provided? 'current-time)': The procedures `current-time', `difftime', and `offset-time' deal with a "calendar time" datatype which may or may not be disjoint from other Scheme datatypes. -- Function: current-time Returns the time since 00:00:00 GMT, January 1, 1970, measured in seconds. Note that the reference time is different from the reference time for `get-universal-time' in *Note Common-Lisp Time::. -- Function: difftime caltime1 caltime0 Returns the difference (number of seconds) between twe calendar times: CALTIME1 - CALTIME0. CALTIME0 may also be a number. -- Function: offset-time caltime offset Returns the calendar time of CALTIME offset by OFFSET number of seconds `(+ caltime offset)'.  File: slib.info, Node: Time Zone, Next: Posix Time, Prev: Time and Date, Up: Time and Date 4.13.1 Time Zone ---------------- (require 'time-zone) -- Data Format: TZ-string POSIX standards specify several formats for encoding time-zone rules. : If the first character of is `/', then specifies the absolute pathname of a tzfile(5) format time-zone file. Otherwise, is interpreted as a pathname within TZFILE:VICINITY (/usr/lib/zoneinfo/) naming a tzfile(5) format time-zone file. The string consists of 3 or more alphabetic characters. specifies the time difference from GMT. The is positive if the local time zone is west of the Prime Meridian and negative if it is east. can be the number of hours or hours and minutes (and optionally seconds) separated by `:'. For example, `-4:30'. is the at least 3 alphabetic characters naming the local daylight-savings-time. specifies the offset from the Prime Meridian when daylight-savings-time is in effect. The non-tzfile formats can optionally be followed by transition times specifying the day and time when a zone changes from standard to daylight-savings and back again. ,/