path: root/slib.info-7

This is Info file slib.info, produced by Makeinfo-1.64 from the input
file slib.texi.

  This file documents SLIB, the portable Scheme library.

  Copyright (C) 1993 Todd R. Eigenschink Copyright (C) 1993, 1994, 1995
Aubrey Jaffer

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the author.


File: slib.info,  Node: Getopt,  Next: Command Line,  Prev: Trace,  Up: Session Support

Getopt
======

  `(require 'getopt)'

  This routine implements Posix command line argument parsing.  Notice
that returning values through global variables means that `getopt' is
*not* reentrant.

 - Variable: *optind*
     Is the index of the current element of the command line.  It is
     initially one.  In order to parse a new command line or reparse an
     old one, *OPTING* must be reset.

 - Variable: *optarg*
     Is set by getopt to the (string) option-argument of the current
     option.

 - Procedure: getopt ARGC ARGV OPTSTRING
     Returns the next option letter in ARGV (starting from `(vector-ref
     argv *optind*)') that matches a letter in OPTSTRING.  ARGV is a
     vector or list of strings, the 0th of which getopt usually
     ignores. ARGC is the argument count, usually the length of ARGV.
     OPTSTRING is a string of recognized option characters; if a
     character is followed by a colon, the option takes an argument
     which may be immediately following it in the string or in the next
     element of ARGV.

     *OPTIND* is the index of the next element of the ARGV vector to be
     processed.  It is initialized to 1 by `getopt.scm', and `getopt'
     updates it when it finishes with each element of ARGV.

     `getopt' returns the next option character from ARGV that matches
     a character in OPTSTRING, if there is one that matches.  If the
     option takes an argument, `getopt' sets the variable *OPTARG* to
     the option-argument as follows:

        * If the option was the last character in the string pointed to
          by an element of ARGV, then *OPTARG* contains the next
          element of ARGV, and *OPTIND* is incremented by 2.  If the
          resulting value of *OPTIND* is greater than or equal to ARGC,
          this indicates a missing option argument, and `getopt'
          returns an error indication.

        * 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
          ;;;This code is SCM specific.
          (define argv (program-arguments))
          (require 'getopt)
          
          (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)

Getopt-
=======

 - Function: getopt- ARGC ARGV 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 argc 5)
          (define argv '("foo" "-b9" "--f1" "--2=" "--g3=35234.342" "--"))
          (define *optind* 1)
          (define *optarg* #f)
          (require 'qp)
          (do ((i 5 (+ -1 i)))
              ((zero? i))
            (define opt (getopt-- argc argv opts))
            (print *optind* opt *optarg*)))
          -|
          2 #\b "9"
          3 "f1" #f
          4 "2" ""
          5 "g3" "35234.342"
          5 #f "35234.342"


File: slib.info,  Node: Command Line,  Next: System Interface,  Prev: Getopt,  Up: Session Support

Command Line
============

  `(require 'read-command)'

 - Function: read-command PORT
 - Function: read-command
     `read-command' converts a "command line" into a list of strings
     suitable for parsing by `getopt'.  The syntax of command lines
     supported resembles that of popular "shell"s.  `read-command'
     updates PORT to point to the first character past the command
     delimiter.

     If an end of file is encountered in the input before any
     characters are found that can begin an object or comment, then an
     end of file object is returned.

     The PORT argument may be omitted, in which case it defaults to the
     value returned by `current-input-port'.

     The fields into which the command line is split are delimited by
     whitespace as defined by `char-whitespace?'.  The end of a command
     is delimited by end-of-file or unescaped semicolon (;) or 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 (*note Strings:
          (r4rs)Strings.).

    `(', `%''
          One scheme expression is `read' starting with this character.
          The `read' expression is evaluated, converted to a string
          (using `display'), and replaces the expression in the returned
          field.

    `;'
          Semicolon delimits a command.  Using semicolons more than one
          command can appear on a line.  Escaped semicolons and
          semicolons inside strings do not delimit commands.

     The comment field differs from the previous fields in that it must
     be the first character of a command or appear after whitespace in
     order to be recognized.  # can be part of fields if these
     conditions are not met.  For instance, `ab#c' is just the field
     ab#c.

    `#'
          Introduces a comment.  The comment continues to the end of
          the line on which the semicolon appears.  Comments are
          treated as whitespace by `read-dommand-line' and backslashes
          before newlines in comments are also ignored.


File: slib.info,  Node: System Interface,  Next: Require,  Prev: Command Line,  Up: Session Support

System Interface
================

  If `(provided? 'getenv)':

 - Function: getenv NAME
     Looks up NAME, a string, in the program environment.  If NAME is
     found a string of its value is returned.  Otherwise, `#f' is
     returned.

  If `(provided? 'system)':

 - Function: system COMMAND-STRING
     Executes the COMMAND-STRING on the computer and returns the
     integer status code.


File: slib.info,  Node: Require,  Next: Vicinity,  Prev: System Interface,  Up: Session Support

Require
=======

  These variables and procedures are provided by all implementations.

 - Variable: *features*
     Is a list of symbols denoting features supported in this
     implementation.

 - Variable: *modules*
     Is a list of pathnames denoting files which have been loaded.

 - Variable: *catalog*
     Is an association list of features (symbols) and pathnames which
     will supply those features.  The pathname can be either a string
     or a pair.  If pathname is a pair then the first element should be
     a macro feature symbol, `source', or `compiled'.  The cdr of the
     pathname should be either a string or a list.

  In the following three functions if FEATURE is not a symbol it is
assumed to be a pathname.

 - Function: provided? FEATURE
     Returns `#t' if FEATURE is a member of `*features*' or `*modules*'
     or if FEATURE is supported by a file already loaded and `#f'
     otherwise.

 - Procedure: require FEATURE
     If `(not (provided? FEATURE))' it is loaded if FEATURE is a
     pathname or if `(assq FEATURE *catalog*)'.  Otherwise an error is
     signaled.

 - Procedure: provide FEATURE
     Assures that FEATURE is contained in `*features*' if FEATURE is a
     symbol and `*modules*' otherwise.

 - Function: require:feature->path FEATURE
     Returns `#t' if FEATURE is a member of `*features*' or `*modules*'
     or if FEATURE is supported by a file already loaded.  Returns a
     path if one was found in `*catalog*' under the feature name, and
     `#f' otherwise.  The path can either be a string suitable as an
     argument to load or a pair as described above for *catalog*.

  Below is a list of features that are automatically determined by
`require'.  For each item, `(provided? 'FEATURE)' will return `#t' if
that feature is available, and `#f' if not.

   * 'inexact

   * 'rational

   * 'real

   * 'complex

   * 'bignum


File: slib.info,  Node: Vicinity,  Next: Configuration,  Prev: Require,  Up: Session Support

Vicinity
========

  A vicinity is a descriptor for a place in the file system.  Vicinities
hide from the programmer the concepts of host, volume, directory, and
version.  Vicinities express only the concept of a file environment
where a file name can be resolved to a file in a system independent
manner.  Vicinities can even be used on "flat" file systems (which have
no directory structure) by having the vicinity express constraints on
the file name.  On most systems a vicinity would be a string.  All of
these procedures are file system dependent.

  These procedures are provided by all implementations.

 - Function: make-vicinity FILENAME
     Returns the vicinity of FILENAME for use by `in-vicinity'.

 - 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 it the result is undefined.  *Warning:*
     `program-vicinity' can return incorrectl values if your program
     escapes back into a `load'.

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


File: slib.info,  Node: Configuration,  Next: Input/Output,  Prev: Vicinity,  Up: Session Support

Configuration
=============

  These constants and procedures describe characteristics of the Scheme
and underlying operating system.  They are provided by all
implementations.

 - Constant: char-code-limit
     An integer 1 larger that the largest value which can be returned by
     `char->integer'.

 - Constant: most-positive-fixnum
     The immediate integer closest to positive infinity.

 - 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 "2a3" on scm "4e1" 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 "2a3" on scm "4e1" on unix
          (implementation-vicinity) is "/usr/local/src/scm/"
          (library-vicinity) is "/usr/local/lib/slib/"
          (scheme-file-suffix) is ".scm"
          implementation *features* :
                  bignum complex real rational
                  inexact vicinity ed getenv
                  tmpnam system abort transcript
                  with-file ieee-p1178 rev4-report rev4-optional-procedures
                  hash object-hash delay eval
                  dynamic-wind multiarg-apply multiarg/and- logical
                  defmacro string-port source array-for-each
                  array full-continuation char-ready? line-i/o
                  i/o-extensions pipe
          implementation *catalog* :
                  (rev4-optional-procedures . "/usr/local/lib/slib/sc4opt")
                  ...


File: slib.info,  Node: Input/Output,  Next: Legacy,  Prev: Configuration,  Up: Session Support

Input/Output
============

  These procedures are provided by all implementations.

 - Procedure: file-exists? FILENAME
     Returns `#t' if the specified file exists.  Otherwise, returns
     `#f'.  If the underlying implementation does not support this
     feature then `#f' is always returned.

 - Procedure: delete-file FILENAME
     Deletes the file specified by FILENAME.  If FILENAME can not be
     deleted, `#f' is returned.  Otherwise, `#t' is returned.

 - Procedure: tmpnam
     Returns a pathname for a file which will likely not be used by any
     other process.  Successive calls to `(tmpnam)' will return
     different pathnames.

 - Procedure: current-error-port
     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)'.

 - Procedure: output-port-width
 - Procedure: output-port-width PORT
     Returns the width of PORT, which defaults to
     `(current-output-port)' if absent.  If the width cannot be
     determined 79 is returned.

 - Procedure: output-port-height
 - Procedure: output-port-height PORT
     Returns the height of PORT, which defaults to
     `(current-output-port)' if absent.  If the height cannot be
     determined 24 is returned.


File: slib.info,  Node: Legacy,  Next: System,  Prev: Input/Output,  Up: Session Support

Legacy
======

 - Function: identity X
     IDENTITY returns its argument.

     Example:
          (identity 3)
             => 3
          (identity '(foo bar))
             => (foo bar)
          (map identity LST)
             == (copy-list LST)

  These were present in Scheme until R4RS (*note Language changes:
(r4rs)Notes.).

 - Constant: t
     Derfined as `#t'.

 - Constant: nil
     Defined as `#f'.

 - Function: last-pair L
     Returns the last pair in the list L.  Example:
          (last-pair (cons 1 2))
             => (1 . 2)
          (last-pair '(1 2))
             => (2)
              == (cons 2 '())


File: slib.info,  Node: System,  Prev: Legacy,  Up: Session Support

System
======

  These procedures are provided by all implementations.

 - Procedure: slib:load-source NAME
     Loads a file of Scheme source code from NAME with the default
     filename extension used in SLIB.  For instance if the filename
     extension used in SLIB is `.scm' then `(slib:load-source "foo")'
     will load from file `foo.scm'.

 - Procedure: slib:load-compiled NAME
     On implementations which support separtely loadable compiled
     modules, loads a file of compiled code from NAME with the
     implementation's filename extension for compiled code appended.

 - Procedure: slib:load NAME
     Loads a file of Scheme source or compiled code from NAME with the
     appropriate suffixes appended.  If both source and compiled code
     are present with the appropriate names then the implementation
     will load just one.  It is up to the implementation to choose
     which one will be loaded.

     If an implementation does not support compiled code then
     `slib:load' will be identical to `slib:load-source'.

 - Procedure: slib:eval OBJ
     `eval' returns the value of OBJ evaluated in the current top level
     environment.

 - 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: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 an
     unspecified value is returned from `slib:exit'.


File: slib.info,  Node: Optional SLIB Packages,  Next: Procedure and Macro Index,  Prev: Session Support,  Up: Top

Optional SLIB Packages
**********************

  Several Scheme packages have been written using SLIB.  There are
several reasons why a package might not be included in the SLIB
distribution:
   * Because it requires special hardware or software which is not
     universal.

   * Because it is large and of limited interest to most Scheme users.

   * Because it has copying terms different enough from the other SLIB
     packages that its inclusion would cause confusion.

   * Because it is an application program, rather than a library module.

   * Because I have been too busy to integrate it.

  Once an optional package is installed (and an entry added to
`*catalog*', the `require' mechanism allows it to be called up and used
as easily as any other SLIB package.  Some optional packages (for which
`*catalog*' already has entries) available from SLIB sites are:

SLIB-PSD is a portable debugger for Scheme (requires emacs editor).
          ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
          prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz
          ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz
          ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz

     With PSD, you can run a Scheme program in an Emacs buffer, set
     breakpoints, single step evaluation and access and modify the
     program's variables. It works by instrumenting the original source
     code, so it should run with any R4RS compliant Scheme. It has been
     tested with SCM, Elk 1.5, and the sci interpreter in the Scheme->C
     system, but should work with other Schemes with a minimal amount
     of porting, if at all. Includes documentation and user's manual.
     Written by Pertti Kellom\"aki, pk@cs.tut.fi.  The Lisp Pointers
     article describing PSD (Lisp Pointers VI(1):15-23, January-March
     1993) is available as
          http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html

SLIB-SCHELOG is an embedding of Prolog in Scheme.
          ftp-swiss.ai.mit.edu:pub/scm/slib-schelog.tar.gz
          prep.ai.mit.edu:pub/gnu/jacal/slib-schelog.tar.gz
          ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-schelog.tar.gz
          ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-schelog.tar.gz