scsh-conservatory
/
scsh-0.6
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Obsolete.

This commit is contained in:
sperber 2002-01-08 15:44:02 +00:00
parent 0e9c2e5626
commit 451f06f0d5
7 changed files with 0 additions and 9668 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

309
doc/big-scheme.txt
View File

@ -1,309 +0,0 @@
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.

4430
doc/external.ps
View File

File diff suppressed because it is too large Load Diff

1417
doc/module.ps
View File

File diff suppressed because it is too large Load Diff

81
doc/package.txt
View File

@ -1,81 +0,0 @@
-- this file is probably obsolete --
The package system interface. Much too complicated.
Signatures
make-simple-signature
make-compound-signature
signature?
signature-ref
signature-walk
Structures
make-structure
structure?
structure-signature
structure-package
structure-name
Packages
make-package
make-simple-package ;start.scm
Lookup and definition operations
package-lookup
package-lookup-type ;comp.scm
package-find-location ;rts/env.scm
package-lookup-location ;segment.scm
probe-package
package-check-assigned
package-check-variable
package-define!
package-define-type! ;hmm.
package-ensure-defined!
Things needed by the form/file/package scanner
for-each-definition ;for integrate-all-primitives!
package-accesses ;for scan-package
package-clauses ;for scan-package
package-file-name ;for scan-package
package-opens ;for scan-package
package-evaluator ;for define-syntax
package-for-syntax ;for define-syntax
Miscellaneous
$note-undefined ;eval.scm
noting-undefined-variables ;eval.scm, etc.
package-uid ;eval.scm
set-shadow-action! ;eval.scm
verify-later! ;for the define-structures macro
reset-packages-state! ;Makefile - for linker
initialize-reified-package! ;for reification
transform-for-structure-ref ;for reification ?
Inessential (for package mutation, programming environment)
check-structure
package-integrate? ;env/debug.scm
set-package-integrate?! ;env/debug.scm
package-loaded? ;env/load-package.scm
set-package-loaded?! ;env/load-package.scm
package-name ;env/command.scm
package-name-table ;env/debuginfo.scm
package-open! ;env/debug.scm
package-system-sentinel ;env/command.scm
package-unstable? ;env/pacman.scm
package? ;env/command.scm
undefined-variables ;env/debug.scm
Location names (also inessential)
flush-location-names
location-name
location-name-table
location-package-name

186
doc/syslog.txt
View File

@ -1,186 +0,0 @@
The Syslog Interface
====================
This is an interface to the syslog facility of most Unix systems. Its
interface differs significantly from that of the Unix library
functionality in order to support multiple simultaneous connections to
the syslog facility.
The functionality is in a structure called SYSLOG.
This documentation is very preliminary. Consult the syslog(3) manpage
alongside this document.
Log Options
===========
(syslog-option syslog-option-name) -> syslog-option
(make-syslog-options list) -> syslog-options
(syslog-options syslog-option-name ...) -> syslog-options
(syslog-options->list syslog-options) -> list of syslog-option
(syslog-options-on? syslog-options syslog-options) -> boolean
(syslog-options=? syslog-options syslog-options) -> boolean
(syslog-options? x) -> boolean
Here is a list of possible names of syslog options:
console
If syslog cannot pass the message to syslogd it will attempt to
write the message to the console.
delay
Delay opening the connection to syslogd immediately until the first
message is logged.
no-delay
Open the connection to syslogd immediately. Normally
the open is delayed until the first message is logged.
Useful for programs that need to manage the order in which
file descriptors are allocated.
NOTA BENE: The delay and no-delay options are included for
completeness, but do not have the expected effect in the present
Scheme interface: Because the Scheme interface has to multiplex
multiple simultaneous connections to the syslog facility over a
single one, open and close operations on that facility happen at
unpredictable times.
standard-error
Write the log messages to standard error output as well to the
system log.
log-pid
Log the process id with each message: useful for identifying
instantiations of daemons.
Log Facilities
==============
(syslog-facility syslog-facility-name) -> syslog-facility)
(syslog-facility? x) -> boolean)
(syslog-facility=? syslog-facility syslog-facility)
Here is a list of possible names of syslog facilities:
authorization
The authorization system: login, su, getty, etc.
cron
The cron daemon.
daemon
System daemons, such as routed, that are not provided for explicitly
by other facilities.
kernel
Messages generated by the kernel.
lpr
The line printer spooling system: lpr, lpc, lpd, etc.
mail
The mail system.
news
The network news system.
user
Messages generated by random user processes.
uucp
The uucp system.
local0 local1 local2 local3 local4 local5 local6 local7
Reserved for local use.
Log Levels
==========
Here is a list of possible names of syslog levels:
(syslog-level syslog-level-name) -> syslog-level
(syslog-level? x) -> boolean
(syslog-level=? syslog-level syslog-level) -> boolean
emergency
A panic condition. This is normally broadcast to all users.
alert
A condition that should be corrected immediately, such as a
corrupted system database.
critical
Critical conditions, e.g., hard device errors.
error
Errors.
warning
Warning messages.
notice
Conditions that are not error conditions, but should possibly be
handled specially.
info
Informational messages.
debug
Messages that contain information normally of use only when
debugging a program.
Log Masks
=========
Log masks can mask out syslog messages at any set of levels. A log
mask is constructed from a set of levels.
(syslog-mask syslog-level-name ...) -> syslog-mask
(levels->syslog-mask list) -> syslog-mask
(syslog-mask->levels syslog-mask) -> list of syslog-level
syslog-mask-all: syslog-mask
(syslog-mask-upto syslog-level) -> syslog-mask
(syslog-mask-levels-on? syslog-mask syslog-mask) -> boolean
(syslog-mask? x) -> boolean
(syslog-mask=? syslog-mask syslog-mask) -> boolean
Logging
=======
(open-syslog-channel string syslog-options syslog-facility syslog-mask)
-> syslog-channel
(close-syslog-channel syslog-channel)
These two create and destroy a connection to the syslog facility,
respectively. The first argument will be prepended to every message.
The other arguments belong to the categories mentioned above. Note
that it is not necessary to explicitly open a syslog channel to do
logging; there is an implicit syslog channel which is already open and
whose parameters can be bound dynamically with WITH-SYSLOG-DESTINATION
below.
(with-syslog-destination maybe-string
maybe-syslog-options
maybe-syslog-facility
maybe-syslog-mask
thunk) -> values
This dynamically binds parameters of the implicit syslog channel and
runs THUNK within those parameter bindings, returning what THUNK
returns. Each of the parameters may be #f in which case the previous
values will be used.
(syslog level message)
(syslog level message channel)
(syslog level message maybe-string)
(syslog level message maybe-string maybe-syslog-options)
(syslog level message maybe-string maybe-syslog-options
maybe-syslog-facility)
(syslog level message maybe-string maybe-syslog-options
maybe-syslog-facility maybe-syslog-mask)
SYSLOG actually logs a message, either to an explicitly specified
syslog channel, or to the implicit syslog channel. Each of the
parameters of the implicit channel can be explicitly specified as
well, overriding the parameters of the channel.

709
doc/user-guide.txt
View File

@ -1,709 +0,0 @@
A User's Guide to Scheme 48
A line may take us hours, yet if it does not seem a moment's thought
All our stitching and unstitching has been as nought.
Yeats
Adam's Curse
Introduction
Scheme 48 is an implementation of the Scheme programming language as
described in the Revised^4 Report on the Algorithmic Language Scheme.
It is based on a compiler and interpreter for a virtual Scheme
machine. The name derives from our desire to have an implementation
that is simple and lucid enough that it looks as if it were written in
just 48 hours. We don't claim to have reached that stage yet; much
more simplification is necessary.
Scheme 48 tries to be faithful to the upcoming Revised^5 Scheme
Report, providing neither more nor less in the initial user
environment. (This is not to say that more isn't available in other
environments; see below.) Support for numbers is weak: bignums are
slow and floating point is almost nonexistent (see description of
floatnums, below). DEFINE-SYNTAX, LET-SYNTAX, LETREC-SYNTAX, and
SYNTAX-RULES are supported, but not the rest of the Revised^4 Scheme
macro proposal.
The Revised^5 Report hasn't been published yet, but it will be very
similar to the Revised^4 Report. For a list of differences, see
doc/meeting.tex.
This is what might be called an alpha release. Please report bugs,
especially in the VM, especially core dumps, to
scheme-48-bugs@altdorf.ai.mit.edu. Include the version number x.yy
from the "Welcome to Scheme 48 x.yy" greeting message in your bug
report. It is a goal of this project to produce a bullet-proof
system; we want no bugs and, especially, no crashes. (There are a few
known bugs, listed in the TODO file that comes with the distribution.)
Send mail to scheme-48-request@altdorf.ai.mit.edu to be put on a
mailing list for announcements, discussion, bug reports, and bug
fixes.
-----
Command line arguments
A few command line arguments are processed by the virtual machine as
it starts up.
scheme48 [-i image] [-h heapsize] [-o filename] [-s stacksize]
[-a argument ...]
-i image
specifies a heap image file to resume. This defaults to a heap
image that runs a Scheme command processor. Heap images are
created by the ,dump and ,build commands, for which see below.
-h heapsize
specifies how much space should be reserved for allocation.
Heapsize is in words (where one word = 4 bytes), and covers both
semispaces, only one of which is in use at any given time (except
during garbage collection). Cons cells are currently 3 words, so
if you want to make sure you can allocate a million cons cells,
you should specify -h 6000000 (actually somewhat more than this,
to account for the initial heap image and breathing room).
-s stacksize
specifies how much space should be reserved for the continuation
and environment stack. If this space is exhausted, continuations
and environments are copied to the heap. stacksize is in words
and defaults to 2500.
-o filename
This specifies an executable file in which foreign identifiers can be
looked up for the foreign function interface. Filename should be the
file that contains the scheme48vm executable image. See
doc/external.txt.
-a argument ...
is only useful with images built using ,build. The arguments are
passed as a list to the procedure specified in the ,build command.
E.g.
> ,build (lambda (a) (for-each display a) (newline) 0) foo.image
> ,exit
% scheme48vm -i foo.image -a mumble "foo x"
mumblefoo x
%
The usual definition of the "s48" or "scheme48" command is actually a
shell script that starts up the virtual machine with a -i argument
specifying the development environment heap image, and a -o argument
specifying the location of the virtual machine.
-----
Command processor
When you invoke the default heap image, a command processor starts
running. At the > prompt, you can type either a Scheme form
(expression or definition), or a command beginning with a comma.
Logistical commands:
,load <filename> ... load Scheme source file(s)
Easier to type than (load "filename") because you don't have to
shift to type the parentheses or quote marks. Also, it works in
any package, unlike (load "filename"), which will work only work
in packages in which the variable LOAD is defined properly.
,exit [<exp>] leave
Exit back out to shell (or executive or whatever invoked Scheme 48
in the first place). <exp> should evaluate to an integer. The
integer is returned to the calling program. (On Unix, 0 is
generally interpreted as success, nonzero as failure.)
Command levels:
If an errors occurs, you are put in a command loop at the dynamic
point at which the error occurred. The prompt will then be "n >"
where n is the command level nesting depth.
<eof>
Pop out one level (running any dynamic-wind "after" thunks), and
resumes running all non-broken threads. EOF after a keyboard
interrupt resumes running the interrupted thread. <eof> is usually
control-D at a Unix shell or using the Emacs "cmuscheme48" library.
,reset top level
Unwind all the way back out to top level.
,level <number> go to command level
Unwind out to a given level. ,level 0 is the same as ,reset.
,push
Go to a deeper command level. (See ,levels, below.)
Debugging commands:
,preview
Sort of like a backtrace, but because of tail recursion you see
less than you might in debuggers for some other languages.
,threads
Invoke the inspector on the threads running on the next level out.
,proceed <exp> ...
Proceed after an interrupt or error, delivering the values of <exp>
... to the continuation.
,trace <name> ...
Start tracing calls to the named procedure or procedures.
With no arguments, displays all procedures currently traced.
This affects the binding of <name>, not the behavior of the
procedure that's it's current value. The effect is similar to
(define <name> (make-traced <name>))
where make-traced is a procedure-returning procedure.
,untrace <name> ...
Stop tracing calls to the named procedure or procedures.
With no argument, stop tracing all calls to all procedures.
,condition
The ,condition command selects and displays the condition object
describing the error or interrupt that initiated the current
command level. This is particularly useful in conjunction with
the inspector. E.g. if a procedure is passed the wrong number of
arguments, do ,condition followed by ,inspect ## to inspect the
procedure and its arguments.
,bound? <name>
Display the binding of <name>, if there is one.
,expand <form>
Show macro expansion of <form>, if any.
,where <procedure>
Display name of source file in which <procedure> is defined.
Building images:
,dump <filename> [<identification>]
This writes out the current heap. When the new image is resumed,
it starts in the command processor. If present, <identification>
should be a string (written with double quotes); this string will
be part of the greeting message as the image starts up.
,build <exp> <filename>
<exp> should evaluate to a procedure of one argument. When
<filename> is resumed, that procedure will be invoked on the VM's
-a arguments, which are passed as a list of strings. The
procedure should return an integer (as for ,exit). The command
processor and debugging system are not included in the image
(unless you go to some effort to preserve them, such as retaining
a continuation).
Doing ",flush" before building an image will make for smaller
images, but if an error occurs, the error message may be less
helpful. Doing ",flush source maps" before loading any programs
will make the image still smaller.
Modes:
When given no argument, all of these commands toggle the corresponding
mode. With the argument ?, the current setting is displayed.
Otherwise the argument should be ON or OFF.
,batch [on | off | ?]
In "batch mode," any error or interrupt that comes up will cause
Scheme 48 to exit immediately with a non-zero exit status. Also,
the command processor doesn't print prompts. The default is
interactive mode.
,form-preferred [on | off | ?]
Enable or disable "form preferred" mode. In this mode, command
processor commands needn't be prefixed by comma. To see the value
of a variable (or number - this should be fixed), do (begin
<name>). "Command preferred" mode is the default.
,levels [on | off | ?]
Enable or disable command levels. With levels enabled (the
default), errors "push" a new command level, and <eof> (see above)
or ,reset is required to return to top level. The effects of
pushed command levels include:
- a longer prompt
- retention of the continuation in effect at the point of errors
- longer ,previews
- confusion among some newcomers
With levels disabled, one must issue a ,push command immediately
following an error in order to retain the error continuation for
debugging purposes; otherwise the continuation is lost after the
next evaluation request. If you don't know anything about the
available debugging tools, then levels might as well be disabled.
This is an experimental feature inspired by gripes about how
confusing recursive command loop levels are to newcomers to
Scheme. Let me know (jar@ai.mit.edu) if you like it; otherwise it
might get flushed.
Each level has its own set of threads, so pushing a new level stops
all threads running at the current level.
,break-on-warnings [on | off | ?]
When a warning is produced, enter a new command level, just as
when an error occurs.
Resource query and control:
,time <exp>
Measure execution time.
,collect
Invoke the garbage collector. Ordinarily this happens
automatically, but the command tells how much space is available
before and after the collection.
,keep <kind>
,flush <kind>
These control the amount of debugging information retained after
compiling procedures. This information can consume a fair amount
of space. <kind> is one of the following:
. maps - environment maps (local variable names, for inspector)
. source - source code for continuations (displayed by inspector)
. names - procedure names (as displayed by WRITE and in error
messages)
. files - source file names
These commands refer to future compilations only, not to procedures
that already exist. To have any effect, they must be done before
programs are loaded.
,flush
The flush command with no argument deletes the database of names
of initial procedures. Doing ",flush" before a ,build or ,dump
will make the resulting image significantly smaller (by up to 200K
bytes), but will compromise the information content of many error
messages.
Quite obscure:
,go <exp>
This is like ,exit <exp> except that the evaluation of <exp>
is tail-recursive with respect to the command processor. This
means that the command processor itself can probably be GC'ed,
should a garbage collection occur in the execution of <exp>.
Any errors will be treated as in batch mode.
,translate <from> <to>
For LOAD and the ,load command (but not for OPEN-xxPUT-FILE), file
names beginning with the string <from> will be changed so that the
initial <from> is replaced by the string <to>. E.g.
,translate /usr/gjc/ /zu/gjc/
will cause (load "/usr/gjc/foo.scm") to have the same effect as
(load "/zu/gjc/foo.scm").
,from-file <filename> <form> ... ,end
This is used by the cmuscheme48 Emacs library.
Other commands are (or should be) described in the module system
document.
-----
Editing
We recommend running Scheme 48 under Gnu Emacs using the cmuscheme48
command package. This is in the Scheme 48 distribution's emacs/
subdirectory. It is a variant of the "cmuscheme" library, which
comes to us courtesy of Olin Shivers, formerly of CMU. You might want
to put the following in your emacs init file (.emacs):
(setq scheme-program-name "scheme48")
(autoload 'run-scheme "cmuscheme48" "Run an inferior Scheme process." t)
To make the autoload and (require ...) forms work, you will also need
to put the directory containing cmuscheme and related files in your
emacs load-path:
(setq load-path (append load-path '("<scheme-48-directory>/emacs")))
For further documentation see emacs/cmuscheme48.el and emacs/comint.el.
-----
Performance
If you want to generally have your code run faster than it normally
would, enter "benchmark mode" before loading anything. Otherwise
calls to primitives (like + and cons) and in-line procedures (like not
and cadr) won't be open-coded, and programs will run more slowly.
Enter benchmark mode by issuing the ,bench command to the command
processor.
The system doesn't start in benchmark mode by default because the
Scheme report permits redefinitions of built-in procedures. In
benchmark mode, such redefinitions don't work according to the report,
because previously compiled calls may have in-lined the old
definition, leaving no opportunity to call the new definition.
",bench" toggles benchmark mode. ",bench on" and ",bench off" turn it
on and off.
-----
Inspector
There is a low-tech inspector available via the ,inspect and ,debug
commands. The ,inspect command starts an inspector command loop.
There is a focus object (the same as the command processor's ##), for
which a menu of selectable components is displayed. To inspect a
particular component, just type the corresponding number in the menu.
For example:
,inspect '(a (b c) d)
(a (b c) d)
[0] a
[1] (b c)
[2] d
inspect: 1
(b c)
[0] b
[1] c
inspect:
When a new object is selected, the previous one is pushed onto a
stack. You can pop the stack, reverting to the previous object, with
the U command.
The inspector is particularly useful with procedures, continuations,
and records.
Other inspector commands:
u pop object stack
d down stack (current object must be a continuation)
m print more of a long menu
(...) evaluate a form and select result
t select a closure or continuation's template
q quit
## is always the object currently being inspected. After a Q command,
or an error in the inspector, ## is the last object that was being
inspected.
The inspector also accepts arbitrary command processor commands, e.g.
the ,dis command (see below). The leading comma is optional.
After an error occurs, ,debug invokes the inspector on the
continuation at the point of the error. The U and D (up and down)
commands then make the inspector look like a conventional stack
debugger, with continuations playing the role of stack frames. D goes
to older or deeper continuations (frames), and U goes back up to more
recent ones.
Templates are the static components of procedures; these are found
inside of procedures and continuations, and contain the quoted
constants and top-level variables referred to by byte-compiled code.
-----
Disassembler
The ,dis command disassembles procedures.
> ,dis cons
cons
0 (check-nargs= 2)
2 (pop)
3 (make-stored-object 2 pair)
6 (return)
>
The command argument is optional; if unsupplied it defaults to the
current focus object (##).
The disassembler can also be invoked on continuations and templates.
-----
Module system
For information on the module (package) system, see doc/module.tex.
-----
Library
A number of useful utilities are either built in to Scheme 48 or can
be loaded from an external library. These utilities are not visible
in the user environment by default, but can be made available with the
,open command. For example, to use the tables structure, do
> ,open tables
>
If the utility is not already loaded, then the ,open command will
offer to load it:
> ,open queues
Load structure queues (y/n)?
Or, you can load something explicitly (without opening it) using the
load-package command:
> ,load-package queues
...
> ,open queues
When loading a utility, the message "Note: optional optimizer not
invoked" is innocuous. Feel free to ignore it.
See also the package system documentation, doc/module.tex.
Unfortunately, few of these wonderful things are documented. They are
listed, however, in files rts-packages.scm, comp-packages.scm, and
more-packages.scm in the distribution directory, and the bindings they
export are listed in interfaces.scm and more-interfaces.scm. Here is
a little information on the more generally useful structures.
architecture
Information about the virtual machine. E.g.
(enum op eq?) => the integer opcode of the EQ? instruction
arrays
Arrays. See comments at the top of file big/array.scm.
ascii
CHAR->ASCII and ASCII->CHAR. Similar to CHAR->INTEGER and
INTEGER->CHAR except that ASCII encoding is guaranteed.
big-scheme
Many generally useful features. See doc/big-scheme.txt.
bigbit
Extensions to the bitwise logical operators (exported by
the BITWISE structure) so that they operate on bignums.
To use these you should do
,load-package bigbit
,open bitwise
bitwise
Bitwise logical operators. See doc/big-scheme.txt.
conditions
Part of the condition system: DEFINE-CONDITION-PREDICATE and
routines for examining condition objects. (See also handle,
signals.)
define-record-types
A DEFINE-RECORD-TYPE macro, providing a concise front end to the
record package. (Richard and Jonathan favor different
record type defining macros; this one is Jonathan's.)
The general syntax is:
(define-record-type <tag> <type-name>
(<constructor-name> <field-tag>*)
<predicate-name>
(<field-tag> <accessor-name> [<modifier-name>])*)
Example:
(define-record-type pare :pare
(kons x y)
pare?
(x kar set-kar!)
(y kdr))
This defines KONS to be a constructor, KAR and KDR to be
accessors, SET-KAR! to be a modifier, and PARE? to be a predicate
for a new type of object. The type itself is named :PARE.
PARE is a tag used in printing the new objects.
The field tags X and Y are used in the inspector and to match
constructor arguments with fields.
By default, the new objects print as #{Pare}. The print method
can be modified using DEFINE-RECORD-DISCLOSER:
(define-record-discloser :pare
(lambda (p) `(pare ,(kar p) ,(kdr p))))
defpackage
The module system: DEFINE-STRUCTURE and DEFINE-INTERFACE.
defrecord
A define-record-type macro, providing more concise use of the
record package. (Richard and Jonathan favor different
record type defining macros; this one is Richard's.)
destructuring
DESTRUCTURE macro. See doc/big-scheme.txt.
display-conditions
Displaying condition objects.
(DISPLAY-CONDITION condition port) => unspecific
Display condition in an easily readable form. E.g.
> ,open display-conditions handle conditions
> (display-condition
(call-with-current-continuation
(lambda (k)
(with-handler (lambda (c punt)
(if (error? c)
(k c)
(punt)))
(lambda () (+ 1 'a)))))
(current-output-port))
Error: exception
(+ 1 'a)
>
enumerated
Enumerated types. See doc/big-scheme.txt.
extended-ports
Ports for reading from and writing to strings, and related things.
See doc/big-scheme.txt.
externals
Rudimentary external function interface. See doc/external.txt.
filenames
Rudimentary file name parsing and synthesis. E.g.
file-name-directory and file-name-nondirectory are as in Gnu emacs.
floatnums
Floating point numbers. These are in a very crude state; use at
your own risk. They are slow and do not read or print correctly.
fluids
Dynamically bound "variables."
(MAKE-FLUID top-level-value) => a "fluid" object
(FLUID fluid) => current value of fluid object
(SET-FLUID! fluid value) => unspecific; changes current value of
fluid object
(LET-FLUID fluid value thunk) => whatever thunk returns
Within the dynamic extent of execution of (thunk), the fluid
object has value as its binding (unless changed by SET-FLUID!
or overridden by another LET-FLUID).
E.g.
(define f (make-fluid 7))
(define (baz) (+ (fluid f) 1))
(baz) ;=> 8
(let-fluid f 4 (lambda () (+ (baz) 1))) ;=> 6
formats
A simple FORMAT procedure, similar to Common Lisp's or T's.
See doc/big-scheme.txt for documentation.
general-tables
An extended version of TABLES; supports tables keyed by strings.
See doc/big-scheme.txt.
handle
Part of the condition system.
(WITH-HANDLER handler thunk) => whatever thunk returns.
handler is a procedure of two arguments. The first argument
is a condition object, and the second is a "punt" procedure.
The handler should examine the condition object (using ERROR?,
etc. from the CONDITIONS structure). If it decides not to do
anything special, it should tail-call the "punt" procedure.
Otherwise it should take appropriate action and perform a
non-local exit. It should not just return unless it knows
damn well what it's doing; returns in certain situations can
cause VM crashes.
interrupts
Interrupt system
ports
A few extra port-related operations, notably FORCE-OUTPUT.
pp
A pretty-printer. (p <exp>) will pretty-print the result of <exp>,
which must be an S-expression. (Source code for procedures is not
retained or reconstructed.) You can also do (p <exp> <port>) to
print to a specific port.
The procedure pretty-print takes three arguments: the object to be
printed, a port to write to, and the current horizontal cursor
position. If you've just done a newline, then pass in zero for
the position argument.
The algorithm is very peculiar, and sometimes buggy.
queues
FIFO queues.
random
Not-very-random random number generator. The <seed> should be between
0 and 2^28 exclusive.
> (define random (make-random <seed>))
> (random) => a pseudo-random number between 0 and 2^28
receiving
Convenient interface to the call-with-values procedure, like
Common Lisp's multiple-value-bind macro. See doc/big-scheme.txt.
records
MAKE-RECORD-TYPE and friends. See the Scheme of Things column in
Lisp Pointers, volume 4, number 1, for documentation.
recnums
Complex numbers. This should be loaded (e.g. with ,load-package)
but needn't be opened.
search-trees
Balanced binary search trees. See comments at top of
big/search-tree.scm.
signals
ERROR, WARN, and related procedures.
sort
Online merge sort (see comment at top of file big/sort.scm).
(sort-list <list> <pred>)
(sort-list! <list> <pred>)
sicp
Compatibility package for the Scheme dialect used in the book
"Structure and Interpretation of Computer Programs."
sockets
Interface to Unix BSD sockets. See comments at top of file
misc/socket.scm.
tables
Hashed association tables. Keys are compared using EQ?.
See doc/big-scheme.txt.
threads
Multitasking. See doc/threads.txt.
util
SUBLIST, ANY, REDUCE, FILTER, and some other useful things.
weak
Weak pointers and populations.
(MAKE-WEAK-POINTER thing) => weak-pointer
(WEAK-POINTER-REF weak-pointer) => thing or #F
#F if the thing has been gc'ed.
writing
(RECURRING-WRITE thing port recur) => unspecific
This is the same as WRITE except that recursive calls invoke
the recur argument instead of WRITE. For an example, see
the definition of LIMITED-WRITE in env/dispcond.scm, which
implements processing similar to common Lisp's *print-level*
and *print-length*.
-----
Acknowledgment
Thanks to Deborah Tatar for providing the Yeats quotation.

2536
doc/utilities.ps
View File

File diff suppressed because it is too large Load Diff