315 lines
11 KiB
Plaintext
315 lines
11 KiB
Plaintext
|
|
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
|
|
reuse the storage of the list argument. DELETE removes all elements
|
|
for which <predicate> is true.
|
|
|
|
(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.
|
|
|
|
-----
|
|
|
|
I couldn't bear to document DEFINE-RECORD-TYPE.
|
|
|
|
|
|
-----
|
|
|
|
Original by RK, 26 Jan 1993.
|
|
Minor changes by JAR, 5 Dec 1993.
|