slib

— 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 ¹, or if feature has been provided by a module already loaded; and #f otherwise.

In some implementations provided? tests whether a module has been required by any module or in any thread; other implementations will have provided? reflect only the modules required 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.

— 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

— 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 Library Catalogs. The cdr of the pathname should be either a string or a list.

— 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.

— Procedure: require-if condition feature

Requires feature if condition is true.

     (require 'byte)
     (require 'logical)
     (require-if 'compiling 'object->string)

     (require-if '(and bignum compiling) 'posix-time)

— 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 Library Catalogs.

— Procedure: require 'new-catalog

This will load mklibcat, which compiles and writes a new slibcat.

— 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.

     ;;; "usercat": SLIB catalog additions for SIMSYNCH.     -*-scheme-*-
     (
      (simsynch      . "../synch/simsynch.scm")
      (run           . "../synch/run.scm")
      (schlep        . "schlep.scm")
     )

— 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")
     

     (define slib:catalog (cdr (member (assq 'null *catalog*) *catalog*)))

— Function: file->requires file provided? catalog

Returns a list of the features required 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 required 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 required by feature assuming the predicate provided? and association-list catalog.

— Function: file->requires* file provided? catalog

Returns a list of the features transitively required 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 '<expr>), where <expr> is a string or vicinity stuff), (load->path <expr>) figures a path to the file. load->path returns that path if it names an existing file; otherwise #f.

     (load->path '(in-vicinity (library-vicinity) "mklibcat"))
             => "/usr/local/lib/slib/mklibcat.scm"

— Function: file->definitions file 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.

     (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)

— 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 requires 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).

— 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)
     

— 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 required 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.

— 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.

— 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")
                  ...
     

— 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.

— 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. 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.

— Function: identity x

identity returns its argument.

Example:

          (identity 3)
             => 3
          (identity '(foo bar))
             => (foo bar)
          (map identity lst)
             == (copy-list lst)
     

— 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
     

— 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 '())
     

— 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.

— Function: defmacro:expand* e

Returns the result of expanding all defmacros in scheme expression e.

— 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.

— 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.

— 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.

     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)

     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

— 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.

     transformer spec := (transformer expression)

     make-syntactic-closure
     capture-syntactic-environment
     identifier?
     identifier=?

— 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)
                ...))))
     

     (make-syntactic-closure env '() 'a)
        => an alias

— 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)
     

— 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.

     (require 'syntax-case)
     (require 'repl)
     (repl:top-level macro:eval)

     (require 'syntax-case)
     (syncase:sanity-check)

— 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 #3 x: 3 y: 5 color: red>
          > (point-x p)
          3
          > (point-color p)
          red
          > (point-color-set! p 'black)
          > p
          #<point #3 x: 3 y: 5 color: black>
     

— Special Form: define-record-type <type-name> (<constructor-name> <field-tag> ...) <predicate-name> <field-spec> ...

Where

          <field-spec> == (<field-tag> <accessor-name>)
                       == (<field-tag> <accessor-name> <modifier-name>)
          
     

define-record-type is a syntax wrapper for the SLIB record module.

— Syntax: fluid-let (bindings ...) forms...

     (fluid-let ((variable init) ...)
        expression expression ...)

— Special Form: receive formals expression body ...

http://srfi.schemers.org/srfi-8/srfi-8.html

— Special Form: let-values ((formals expression) ...) body ...
— Special Form: let-values* ((formals expression) ...) body ...

http://srfi.schemers.org/srfi-11/srfi-11.html

— Macro: and-let* claws body ...

http://srfi.schemers.org/srfi-2/srfi-2.html

— library syntax: cond <clause1> <clause2> ...

Syntax: Each <clause> should be of the form

(<test> <expression1> ...)
     

where <test> is any expression. Alternatively, a <clause> may be of the form

(<test> => <expression>)
     

The <clause> production in the formal syntax of Scheme as written by R5RS in section 7.1.3 is extended with a new option:

<clause> => (<generator> <guard> => <receiver>)
     

where <generator>, <guard>, & <receiver> are all <expression>s.

Clauses of this form have the following semantics: <generator> is evaluated. It may return arbitrarily many values. <Guard> is applied to an argument list containing the values in order that <generator> returned. If <guard> returns a true value for that argument list, <receiver> is applied with an equivalent argument list. If <guard> returns a false value, however, the clause is abandoned and the next one is tried.

The last <clause> may be an “else clause,” which has the form

(else <expression1> <expression2> ...).
     

     (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)

— 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) (see Format) for non-instances and prints obj preceded by `#<INSTANCE>' 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 (see Collections) may override the default in an obvious way.

— 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.

     ;;; These definitions for PRINT and SIZE are
     ;;; already supplied by
     (require 'yasos)
     
     (define-operation (print obj port)
       (format port
               (if (instance? obj) "#<instance>" "~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 "#<Cell: ~s>" (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 "#<Array ~s>" (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 "#<Cell-with-history ~s>"
                   (fetch self))))))
     
     (define-access-operation fetch)
     (add-setter fetch store!)
     (define foo (make-cell 1))
     (print foo #f)
     => "#<Cell: 1>"
     (set (fetch foo) 2)
     =>
     (print foo #f)
     => "#<Cell: 2>"
     (fetch foo)
     => 2

— 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.

— 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*

     (set! *syn-defs* '())

     (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.

     (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.

— 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.

— 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.

— Function: tok:bump-column pos port

Adds pos to the current-column for input-port port.

— 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.

— 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.

— 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.

— 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.

— Variable: stdin

Defined to be (current-input-port).

— Variable: stdout

Defined to be (current-output-port).

— Variable: stderr

Defined to be (current-error-port).

— 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 (see 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 (see 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 `%%'.

— 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.

— 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)
     

— 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"
     

— 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 shells. 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 <newline>. 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 <newline>, that <newline> is just ignored. Processing continues from the characters after the <newline> as though the backslash and <newline> were not there.

`"'

The characters up to the next unescaped <"> are taken literally, according to [R4RS] rules for literal strings (see 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 <newline>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 <newline>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.

— 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.

— 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.

— 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 (see getopt–).

If the aliases association list has only strings as its cars, 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.

     (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=<number>
       -n, --nary=<symbols> ...
       -N, --nary1=<symbols> ...
       -s, --single=<string>
           --Flag
       -B
       -a        <num2> ...
           --Abs=<num3> ...
     
     ERROR: getopt->parameter-list "unrecognized option" "-?"

— 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.

— 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) (see 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.

     (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.

— 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.

— 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!.

     (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 <stdio.h>"
                            "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")
         )))

     #! /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 <stdio.h>'>>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

     bash$ my-batch
     mv: hello.c: No such file or directory
     hello world

— 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 `<META NAME="name" CONTENT="content">'. 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 `<META HTTP-EQUIV="name" CONTENT="content">'. 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 <HEAD> section.

— Function: html:body body ...

Returns HTML string to end a page.

— Function: html:pre line1 line ...

Returns the strings line1, lines as PREformmated plain text (rendered in fixed-width font). Newlines are inserted between line1, lines. HTML tags (`<tag>') within lines will be visible verbatim.

— Function: html:comment line1 line ...

Returns the strings line1 as HTML comments.

— 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 "<H2>%s:</H2><BLOCKQUOTE>%s</BLOCKQUOTE>\\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)))
     

— 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. See match-key.

— 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. See match-key.

— Function: catalog->html db caption arg ...

Returns HTML string for the catalog table of db.

— 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.

— 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.

— 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.

     
     (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.

— 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.

— 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 `<A HREF="#name">' will link to this point.

          (html:anchor "(section 7)")
          =>
          "<A NAME=\"(section%207)\"></A>"
     

— Function: html:link uri highlighted

Returns a string which links the highlighted text to uri.

          (html:link (make-uri "(section 7)") "section 7")
          =>
          "<A HREF=\"#(section%207)\">section 7</A>"
     

— Function: html:base uri

Returns a string specifying the base uri of a document, for inclusion in the HEAD of the document (see head).

— Function: html:isindex prompt

Returns a string specifying the search prompt of a document, for inclusion in the HEAD of the document (see head).

— 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.

— 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.

— 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 `['.

— 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

— 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.

— 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.

— 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.

— 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.