Documentation for Big Scheme

				   
Big Scheme is a set of generally useful facilities.

Easiest way to access these things:

    > ,open big-scheme
    Load structure big-scheme (y/n)? y
    ...

A better way is to use the module system.

-----

Ascii conversions

(CHAR->ASCII <char>) => <integer>
(ASCII->CHAR <integer>) => <char>
  These are identical to CHAR->INTEGER and INTEGER->CHAR except that
  they use the ASCII encoding.

-----

Bitwise operations

(BITWISE-NOT <integer>) => <integer>
(BITWISE-AND <integer> <integer>) => <integer>
(BITWISE-IOR <integer> <integer>) => <integer>
(BITWISE-XOR <integer> <integer>) => <integer>
  These perform various logical operations on integers on a bit-by-bit
  basis, using a two's-complement representation.

(ARITHMETIC-SHIFT <integer> <bit-count>) => <integer>
  Shift the integer by the given bit count, shifting left for positive
  counts and right for negative ones.  A two's complement
  representation is used.

-----

Hash tables

(MAKE-TABLE) => <table>
(MAKE-STRING-TABLE) => <string-table>
  Make a new, empty table.  MAKE-TABLE returns a table that uses EQ?
  for comparing keys and an ad-hoc hash function.  String tables uses
  strings for keys.

(MAKE-TABLE-MAKER <comparison-procedure> <hash-procedure>) => <procedure>
  Returns a procedure of no arguments that makes tables that use the
  given comparison and hash procedures.
  (<comparison-procedure> <key1> <key2>) => <boolean>
  (<hash-procedure> <key>) => <non-negative-integer>

(TABLE? <x>) => <boolean>
  True if <x> is a table.

(TABLE-REF <table> <key>) => <x>
  Return the value for <key> in <table>, or #F if there is none.
  <key> should be of a type appropriate for <table>.

(TABLE-SET! <table> <key> <value>) => <undefined>
  Make <value> be the value of <key> in <table>.  <key> should be of a
  type appropriate for <table>.

(TABLE-WALK <procedure> <table>) => <undefined>
  Apply <procedure>, which must accept two arguments, to every
  associated key and value in <table>.

-----

Enumerations

(DEFINE-ENUMERATION <type-name> (<name0> <name1> ...))      *SYNTAX*
  Defines <type-name> to be an enumeration with components <name0>
  <name1> ....  Also defines <type-name>-COUNT to be the number of
  components.

(ENUM <type-name> <component-name>) => <integer>            *SYNTAX*
  Evaluates to the value of <component-name> within the enumeration
  <type-name>.  For example, if (DEFINE-ENUMERATION COLOR (GREEN
  RED)), then (ENUM COLOR GREEN) is zero and (ENUM COLOR RED) is one.
  The mapping from name to integer is done at macro-expansion time, so
  there is no run-time overhead.

(ENUMERAND->NAME <integer> <enumeration>) => <symbol>
  Returns the name associated with <integer> within <enumeration>.
  E.g. (ENUMERAND->NAME 1 COLOR) => 'RED.

(NAME->ENUMERAND <symbol> <enumeration>)  => <integer>
  Returns the integer associated with <symbol> within <enumeration>.
  E.g. (ENUMERAND->NAME 'GREEN COLOR) => 0.

-----

Port extensions

(MAKE-TRACKING-INPUT-PORT  <input-port>)  => <input-port>
(MAKE-TRACKING-OUTPUT-PORT <output-port>) => <output-port>
  These return ports that keep track of the current row and column and
  are otherwise identical to their arguments.

(MAKE-STRING-INPUT-PORT <string>) => <input-port>
  Returns a port that reads characters from the supplied string.

(CALL-WITH-STRING-OUTPUT-PORT <procedure>) => <string>
  The procedure is called on a port.  When it returns, CALL-WITH-STRING-
  OUTPUT-PORT returns a string containing the characters written to the port.

(WRITE-ONE-LINE <output-port> <character-count> <procedure>) => <unspecified>
  The procedure is called on an output port.  Output written to that
  port is copied to <output-port> until <character-count> characters
  have been written, at which point WRITE-ONE-LINE returns.

(CURRENT-ROW    <port>) => <integer> or #f
(CURRENT-COLUMN <port>) => <integer> or #f
  These return the current read or write location of the port.  #F is
  returned if the port does not keep track of its location.

(FRESH-LINE <output-port>) => <undefined>
  Write a newline character to <output-port> if its current column is not 0.

(INPUT-PORT?  <any>) => <boolean>
(OUTPUT-PORT? <any>) => <boolean>
  These are versions of the standard Scheme predicates that answer true for
  extended ports.

-----

Queues

(MAKE-QUEUE) => <queue>
  Returns a new, empty queue.

(ENQUEUE! <queue> <x>) => <undefined>
  Puts <x> on the queue.

(DEQUEUE! <queue>) => <x>
  Removes and returns the first element of the queue.

(QUEUE-EMPTY? <queue>) => <boolean>
  True if the queue is empty.

(QUEUE? <x>) => <boolean>
  True if <x> is a queue.

(QUEUE->LIST <queue>) => <list>
  Returns a list of the elements of the queue, in order.

(QUEUE-LENGTH <queue>) => <integer>
  The number of elements currently on the queue.

(DELETE-FROM-QUEUE! <queue> <x>) => <boolean>
  Removes the first occurance of <x> from the queue, returning true if
  it was found and false otherwise.

-----

Little utility procedures

(ATOM? <any>)          => <boolean>
  (ATOM? x) == (NOT (PAIR? x))

(NULL-LIST? <list>)    => <boolean>
  Returns #t for the empty list, #f for a pair, and signals an error
  otherwise.

(NEQ? <any> <any>)     => <boolean>
  (NEQ? x y) is the same as (NOT (EQ? x y)).

(N= <number> <number>) => <boolean>
  (N= x y) is the same as (NOT (= x y)).

(IDENTITY <any>) => <any>
(NO-OP <any>)    => <any>
  These both just return their argument.  NO-OP is guaranteed not to
  be compiled in-line, IDENTITY may be.

-----

List utilities

(MEMQ? <element> <list>) => <boolean>
  Returns true if <element> is in <list>, false otherwise.

(ANY?   <predicate> <list>) => <boolean>
  Returns true if <predicate> is true for any element of <list>.

(EVERY? <predicate> <list>) => <boolean>
  Returns true if <predicate> is true for every element of <list>.

(ANY   <predicate> <list>)
(FIRST <predicate> <list>)
  ANY returns some element of <list> for which <predicate> is true, or
  #F if there are none.  FIRST does the same except that it returns
  the first element for which <predicate> is true.

(FILTER  <predicate> <list>)
(FILTER! <predicate> <list>)
  Returns a list containing all of the elements of <list> for which
  <predicate> is true.  The order of the elements is preserved.
  FILTER! may reuse the storage of <list>.

(FILTER-MAP <procedure> <list>)
  The same as FILTER except the returned list contains the results of
  applying <procedure> instead of elements of <list>.  (FILTER-MAP p
  l) is the same as (FILTER IDENTITY (MAP p l)).

(PARTITION-LIST  <predicate> <list>) => <list> <list>
(PARTITION-LIST! <predicate> <list>) => <list> <list>
  The first return value contains those elements <list> for which
  <predicate> is true, the second contains the remaining elements.
  The order of the elements is preserved.  PARTITION-LIST! may resuse
  the storage of the <list>.

(REMOVE-DUPLICATES <list>) => <list>
  Returns its argument with all duplicate elements removed.  The first
  instance of each element is preserved.

(DELQ   <element>   <list>) => <list>
(DELQ!  <element>   <list>) => <list>
(DELETE <predicate> <list>) => <list>
  All three of these return <list> with some elements removed.  DELQ
  removes all elements EQ? to <element>.  DELQ! does the same and may
  modify the list argument.  DELETE removes all elements for which
  <predicate> is true.  Both DELQ and DELETE may reuse some of the
  storage in the list argument, but won't modify it.

(REVERSE! <list>) => <list>
  Destructively reverses <list>.

(SORT-LIST  <list> <a<b-procedure>) => <list>
(SORT-LIST! <list> <a<b-procedure>) => <list>
  Returns a sorted copy of <list>.  The sorting algorithm is stable.
  (SORT-LIST '(6 5 1 3 2 4) <) => '(1 2 3 4 5 6)

-----

Additional syntax

(DESTRUCTURE ((<pattern> <init>) ...) <body> ...)              *SYNTAX*
  The <init>s are evaluated and their values are dissasembled
  according to the corresponding patterns, with identifiers in the
  patterns being bound to fresh locations holding the corresponding
  part, and the body is evaluated in the extended environment.
  Patterns may be any of the following:

     #f                     Discard the corresponding part.
     <identifier>           Bind the <indentifier> to the part.
     (<pattern> ...)        The part must be a list at least as long as the
                             pattern.
     (<pattern1> ... . <patternN>)
                            The same thing, except that the final CDR of the
                             part is dissasembled according to <patternN>.
     #(<pattern> ...)       The part must be a vector at least as long as the
                             pattern.

(RECEIVE <identifiers> <exp> <body> ...)                       *SYNTAX*
  => (CALL-WITH-VALUES (LAMBDA () <exp>) (LAMBDA <identifiers> <body> ...))
  Bind <identifiers> to the values returned by <exp>, and evaluate the
  body in the resulting environment.

-----

Printing and related procedures

(CONCATENATE-SYMBOL . <components>)
  Returns the symbol whose name is produced by concatenating the DISPLAYed
  representations of <components>.
  (CONCATENATE-SYMBOL 'abc "-" 4) => 'abc-4

(FORMAT <port-spec> <format-string> . <arguments>) => <string> or <undefined>
  Prints the arguments to the port as directed by the string.  <port-spec>
  should be either:
    An output port.  The output is written directly to the port.  The result
       of the call to FORMAT is undefined.
    #T.  The output is written to the current output port.  The result of the
       call to FORMAT is undefined.
    #F.  The output is written to a string, which is then the value returned
       from the call to FORMAT.
  Characters in <format-string> which are not preceded by a ~ are written
  directly to the output.  Characters preceded by a ~ have the following
  meaning (case is irrelevant; ~a and ~A have the same meaning):
    ~~ prints a single ~
    ~A prints the next argument using DISPLAY
    ~D prints the next argument as a decimal number
    ~S prints the next argument using WRITE
    ~% prints a newline character
    ~& prints a NEWLINE character if the previous printed character was not one
       (this is implemented using FRESH-LINE)
    ~? performs a recursive call to FORMAT using the next two arguments as the
       string and the list of arguments

(ERROR <format-string> . <format-arguments>)
(BREAKPOINT <format-string> . <format-arguments>)
  Signals an error or breakpoint condition, passing it the result of
  applying FORMAT to the arguments.

(P <thing>)
(P <thing> <output-port>)
(PRETTY-PRINT <thing> <output-port> <position>)
  Pretty-print <thing>.  The current output port is used if no port is
  specified.  <position> is the starting offset.  <thing> will be
  pretty-printed to the right of this column.


Original by RK, 26 Jan 1993.
Minor changes by JAR, 5 Dec 1993.