summaryrefslogtreecommitdiffstats
path: root/slib.info-7
diff options
context:
space:
mode:
Diffstat (limited to 'slib.info-7')
-rw-r--r--slib.info-7615
1 files changed, 615 insertions, 0 deletions
diff --git a/slib.info-7 b/slib.info-7
new file mode 100644
index 0000000..2ed9fcd
--- /dev/null
+++ b/slib.info-7
@@ -0,0 +1,615 @@
+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
+