s48-refman/user/cmd-proc.texi

@node Command processor
@section Command processor

The Scheme48 command processor is the main development environment.  It
incorporates a read-eval-print loop as well as an interactive inspector
and debugger.  It is well-integrated with the module system for rapid
dynamic development, which is made even more convenient with the Emacs
interface, @file{scheme48.el}; @pxref{Emacs integration}.

@menu

* Basic commands::
* Command processor switches::
* Emacs integration commands::
* Focus value::
* Command levels::
* Module commands::
* SRFI 7::
* Debugging commands::
* Inspector::
* Command programs::
* Image-building commands::
* Resource statistics and control::

@end menu

@node Basic commands
@subsection Basic commands

There are several generally useful commands built-in, along with many
others described in subsequent sections:

@cindex help
@cindex command processor help
@deffn command {,help}
@deffnx command {,help} command
@deffnx command {,?}
@deffnx command {,?} command
Requests help on commands.  @command{,?} is an alias for
@command{,help}.  Plain @samp{,help} lists a synopsis of all commands
available, as well as all @embedref{Command processor switches,
switches}.  @samp{,help @var{command}} requests help on the particular
command @var{command}.
@end deffn

@cindex exiting Scheme
@cindex quitting Scheme
@deffn command {,exit}
@deffnx command {,exit} status
@deffnx command {,exit-when-done}
@deffnx command {,exit-when-done} status
Exits the command processor.  @samp{,exit} immediately exits with an
exit status of 0.  @samp{,exit @var{status}} exits with the status that
evaluating the expression @var{status} in the interaction environment
produces.  @command{,exit-when-done} is like @command{,exit}, but it
waits until all threads complete before exiting.
@end deffn

@deffn command {,go} expression
@command{,go} is like @command{,exit}, except that it requires an
argument, and it evaluates @var{expression} in the interaction
environment in a @emph{tail context} with respect to the command
processor.  This means that the command processor may no longer be
reachable by the garbage collector, and may be collected as garbage
during the evaluation of @var{expression}.  For example, the full
Scheme48 command processor is bootstrapped from a minimal one that
supports the @command{,go} command.  The full command processor is
initiated in an argument to the command, but the minimal one is no
longer reachable, so it may be collected as garbage, leaving only the
full one.
@end deffn

@deffn command {,run} expression
Evaluates @var{expression} in the interaction environment.  Alone, this
command is not very useful, but it is required in situations such as
the @embedref{Inspector, inspector} and @embedref{Command programs,
command programs}.
@end deffn

@deffn command {,undefine} name
Removes the binding for @var{name} in the interaction environment.
@end deffn

@deffn command {,load} filename @dots{}
Loads the contents each @var{filename} as Scheme source code into the
interaction environment.  Each @var{filename} is translated first
(@pxref{Filenames}).  The given filenames may be surrounded or not by
double-quotes; however, if a filename contains spaces, it must be
surrounded by double-quotes.  The differences between the
@command{,load} command and Scheme's @code{load} procedure are that
@command{,load} does not require its arguments to be quoted, allows
arbitrarily many arguments while the @code{load} procedure accepts only
one filename (and an optional environment), and works even in
environments in which @code{load} is not bound.
@end deffn

@deffn command {,translate} from to
A convenience for registering a filename translation without needing to
open the @code{filenames} structure.  For more details on filename
translations, @pxref{Filenames}; this command corresponds with the
@code{filename} structure's @code{set-translation!} procedure.  As
with @command{,load}, each of the filenames @var{from} and @var{to} may
be surrounded or not by double-quotes, unless there is a space in the
filenames, in which case it must be surrounded by double-quotes.

Note that in the exec language (@pxref{Command programs}),
@code{translate} is the same as the @code{filenames} structure's
@code{set-translation!} procedure, @emph{not} the procedure named
@code{translate} from the @code{filenames} structure.
@end deffn

@node Command processor switches
@subsection Switches

@cindex command processor settings
@cindex configuring the command processor
The Scheme48 command processor keeps track of a set of @dfn{switches},
user-settable configurations.

@deffn command {,set} switch
@deffnx command {,set} switch @{on|off|?@}
@deffnx command {,unset} switch
@deffnx command {,set} ?
@samp{,set @var{switch}} & @samp{,set @var{switch} on} set the switch
@var{switch} on.  @samp{,unset @var{switch}} & @samp{,set @var{switch}
off} turn @var{switch} off.  @samp{,set @var{switch} ?} gives a brief
description of @var{switch}'s current status.  @samp{,set ?} gives
information about all the available switches and their current state.
@end deffn

The following switches are defined.  Each switch is listed with its
name and its default status.

@table @asis
@item @code{ask-before-loading} @emph{(off)}
If this is on, Scheme48 will prompt the user before loading modules'
code.  If it is off, it will quietly just load it.

@cindex batch mode
@item @code{batch} @emph{(off)}
Batch mode is intended for automated uses of the command processor.
With batch mode on, errors cause the command processor to exit, and the
prompt is not printed.

@item @code{break-on-warnings} @emph{(off)}
If the @code{break-on-warnings} switch is on, @embedref{Condition
system, warnings} signalled that reach the command processor's handler
will cause a @embedref{Command levels, command level} to be pushed,
similarly to breakpoints and errors.

@item @code{inline-values} @emph{(off)}
@code{Inline-values} tells whether or not certain procedures may be
integrated in-line.

@cindex command levels
@cindex disabling command levels
@item @code{levels} @emph{(on)}
Errors will push a new @embedref{Command levels, command level} if this
switch is on, or they will just reset back to the top level if
@code{levels} is off.

@item @code{load-noisily} @emph{(off)}
Loading source files will cause messages to be printed if
@code{load-noisily} is on; otherwise they will be suppressed.
@end table

@node Emacs integration commands
@subsection Emacs integration commands

There are several commands that exist mostly for @embedref{Emacs
integration,Emacs integration}; although they may be used elsewhere,
they are not very useful or convenient without @file{scheme48.el}.

@deffn command {,from-file} filename
@deffnx command {,end}
@samp{,from-file @var{filename}} proclaims that the code following the
command, until an @command{,end} command, comes from @var{filename} ---
for example, this may be due to an appropriate Emacs command, such as
@kbd{C-c C-l} in @file{scheme48.el} ---; if this is the first time the
command processor has seen code from @var{filename}, it is registered
to correspond with the interaction environment wherein the
@command{,from-file} command was used.  If it is not the first time,
the code is evaluated within the package that was registered for
@var{filename}.
@end deffn

@deffn command {,forget} filename
Clears the command processor's memory of the package to which
@var{filename} corresponds.
@end deffn

@node Focus value
@subsection Focus value

The Scheme48 command processor maintains a current @dfn{focus value}.
This is typically the value that the last expression evaluated to, or a
list of values if it returned multiple values.  If it evaluated to
either zero values or Scheme48's `unspecific' token (@pxref{System
features}), the focus value is unchanged.  At the initial startup of
Scheme48, the focus value is set to the arguments passed to Scheme48's
virtual machine after the @option{-a} argument on the command-line
(@pxref{Running Scheme48}).  The focus value is accessed through the
@code{##} syntax; the reader substitutes a special quotation (special
so that the compiler will not generate warnings about a regular
@code{quote} expression containing a weird value) for occurrences of
@code{##}. Several commands, such as @command{,inspect} and
@command{,dis}, either accept an argument or use the current focus
value.  Also, in the @embedref{Inspector, inspector}, the focus object
is the object that is currently being inspected.

@example
> (cons 1 2)
'(1 . 2)
> ##
'(1 . 2)
> (begin (display "Hello, world!") (newline))
Hello, world!
> ##
'(1 . 2)
> (cdr ##)
2
> (define x 5)
; no values returned
> (+ ## x)
7
> (values 1 2 3)
; 3 values returned
1
2
3
> ##
'(1 2 3)@end example

@node Command levels
@subsection Command levels

@cindex command levels
The Scheme48 command processor maintains a stack of @dfn{command
levels}, or recursive invocations of the command processor.  Each
command level retains information about the point from the previous
command level at which it was pushed: the threads that were running ---
which the command processor suspends ---, including the thread of that
command level itself; the continuation of what pushed the level; and,
if applicable, the @embedref{Condition system, condition} that caused
the command level to be pushed.  Each command level has its own thread
scheduler, which controls all threads running at that level, including
those threads' children.

@cindex disabling command levels
Some beginning users may find command levels confusing, particularly
those who are new to Scheme or who are familiar with the more
simplistic interaction methods of other Scheme systems.  These users
may disable the command level system with the @embedref{Command
processor switches, @code{levels} switch} by writing the command
@samp{,set levels off}.

@deffn command {,push}
@deffnx command {,pop}
@deffnx command {,resume}
@deffnx command {,resume} level
@deffnx command {,reset}
@deffnx command {,reset} level
@samp{,push} pushes a new command level.  @samp{,pop} pops the current
command level.  @kbd{C-d}/@kbd{^D}, or EOF, has the same effect as the
@command{,pop} command.  Popping the top command level inquires the
user whether to exit or to return to the top level.  @samp{,resume
@var{level}} pops all command levels down to @var{level} and resumes
all threads that were running at @var{level} when it was suspended to
push another command level.  @samp{,reset @var{level}} resets the
command processor to @var{level}, terminating all threads at that
level but the command reader thread.  @command{,resume} &
@command{,reset} with no argument use the top command level.
@end deffn

@deffn command {,condition}
@deffnx command {,threads}
@samp{,condition} sets the focus value to the condition that caused the
command level to be pushed, or prints `no condition' if there was no
relevant condition.  @samp{,threads} invokes the inspector on the list
of threads of the previous command level, or on nothing if the current
command level is the top one.
@end deffn

@example
> ,push
1> ,push
2> ,pop
1> ,reset

Top level
> ,open threads formats
> ,push
1> ,push
2> (spawn (lambda ()
            (let loop ()
              (sleep 10000)    ; Sleep for ten seconds.
              (format #t "~&foo~%")
              (loop)))
          'my-thread)
2> 
foo
,push
3> ,threads
; 2 values returned
 [0] '#@{Thread 4 my-thread@}
 [1] '#@{Thread 3 command-loop@}
3: q
'(#@{Thread 4 my-thread@} #@{Thread 3 command-loop@})
3> ,resume 1

foo
2> 
foo
,push
3> ,reset 1
Back to 1> ,pop
> @end example

@node Module commands
@subsection Module commands

Scheme48's command processor is well-integrated with its
@embedref{Module system, module system}.  It has several dedicated
environments, including the user package and the config package, and
can be used to evaluate code within most packages in the Scheme48 image
during program development.  The config package includes bindings for
Scheme48's configuration language; structure & interface definitions
may be evaluated in it.  The command processor also has provisions
to support rapid development and module reloading by automatically
updating references to redefined variables in compiled code without
having to reload all of that code.

@cindex opening structures
@cindex structures, opening
@deffn command {,open} struct @dots{}
Opens each @var{struct} into the interaction environment, making all
of its exported bindings available.  This may have the consequence of
loading code to implement those bindings.  If there was code evaluated
in the interaction environment that referred to a previously undefined
variable for whose name a binding was exported by one of these
structures, a message is printed to the effect that that binding is
now available, and the code that referred to that undefined variable
will be modified to subsequently refer to the newly available binding.
@end deffn

@deffn command {,load-package} struct
@cindex reloading code
@cindex code reloading
@deffnx command {,reload-package} struct
@command{,load-package} and @command{,reload-package} both load the
code associated with the package underlying @var{struct}, after
ensuring that all of the other structures opened by that package are
loaded as well.  @command{,load-package} loads the code only if has
not already been loaded; @command{,reload-package} unconditionally
loads it.
@end deffn

@cindex user package
@cindex config package
@deffn command {,user}
@deffnx command {,user} command-or-exp
@deffnx command {,config}
@deffnx command {,config} command-or-exp
@deffnx command {,for-syntax}
@deffnx command {,for-syntax} command-or-exp
@deffnx command {,new-package}
@deffnx command {,in} structure
@deffnx command {,in} structure command-or-exp
These all operate on the interaction environment.  @samp{,user} sets it
to the user package, which is the default at initial startup.
@samp{,user @var{command-or-exp}} temporarily sets the interaction
environment to the user package, processes @var{command-or-exp}, and
reverts the interaction environment to what it was before
@command{,user} was invoked.  The @command{,config} &
@command{,for-syntax} commands are similar, except that they operate on
the config package and the package used for the user package's macros
(@pxref{Macros in concert with modules}).  @samp{,new-package} creates
a temporary, unnamed package with a vanilla R5RS environment and sets
the interaction environment to it.  That new package is not accessible
in any way except to the user of the command processor, and it is
destroyed after the user switches to another environment (unless the
user uses the @command{,structure} command; see below).  @samp{,in
@var{structure}} sets the interaction environment to be
@var{structure}'s package; @var{structure} is a name whose value is
extracted from the config package.  @samp{,in @var{structure}
@var{command-or-exp}} sets the interaction environment to
@var{structure} temporarily to process @var{command-or-exp} and then
reverts it to what it was before the use of @command{,in}.  Note that,
within a structure, the bindings available are exactly those bindings
that would be available within the structure's static code, @ie{} code
in the structure's @code{begin} package clauses or code in files
referred to by @code{files} package clauses.  
@end deffn

@deffn command {,user-package-is} struct
@deffnx command {,config-package-is} struct
@command{,user-package-is} & @command{,config-package-is} set the user
& config packages, respectively, to be @var{struct}'s package.
@var{Struct} is a name whose value is accessed from the current config
package.
@end deffn

@deffn command {,structure} name interface
This defines a structure named @var{name} in the config package that is
a view of @var{interface} on the current interaction environment.
@end deffn

@node SRFI 7
@subsection SRFI 7

@stindex srfi-7
Scheme48 supports [SRFI 7] after loading the @code{srfi-7} structure by
providing two commands for loading [SRFI 7] programs:

@deffn command {,load-srfi-7-program} name filename
@deffnx command {,load-srfi-7-script} name filename
These load [SRFI 7] a program into a newly constructed structure, named
@var{name}, which opens whatever other structures are needed by
features specified in the program.  @command{,load-srfi-7-program}
loads a simple [SRFI 7] program; @command{,load-srfi-7-script} skips
the first line, intended for [SRFI 22] Unix scripts.
@end deffn

@node Debugging commands
@subsection Debugging commands

There are a number of commands useful for debugging, along with a
continuation inspector, all of which composes a convenient debugger.

@deffn command {,bound?} name
@deffnx command {,where}
@deffnx command {,where} procedure
@command{,bound?} prints out binding information about @var{name}, if
it is bound in the interaction environment, or `Not bound' if
@var{name} is unbound.  @command{,where} prints out information about
what file and package its procedure argument was created in.  If
@var{procedure} is not passed, @command{,where} uses the focus value.
If @command{,where}'s argument is not a procedure, it informs the user
of this fact.  If @command{,where} cannot find the location of its
argument's creation, it prints `Source file not recorded.'
@end deffn

@cindex macro expansion
@cindex expanding macros
@cindex syntax expansion
@cindex disassembly
@deffn command {,expand}
@deffnx command {,expand} exp
@deffnx command {,dis}
@deffnx command {,dis} proc
@command{,expand} prints out a macro-expansion of @var{exp}, or the
focus value if @var{exp} is not provided.  The expression to be
expanded should be an ordinary S-expression.  The expansion may contain
`generated names' and `qualified names.'  These merely contain lexical
context information that allow one to differentiate between identifiers
with the same name.  Generated names look like @code{#@{Generated
@var{name} @var{unique-numeric-id}@}}.  Qualified names appear to be
vectors; they look like @code{#(>> @var{introducer-macro} @var{name}
@var{unique-numeric-id})}, where @var{introducer-macro} is the macro
that introduced the name.

@command{,dis} prints out a disassembly of its procedure, continuation,
or template argument.  If @var{proc} is passed, it is evaluated in the
interaction environment; if not, @command{,dis} disassembles the focus
value.  The disassembly is of Scheme48's virtual machine's byte
code.@footnote{A description of the byte code is forthcoming, although
it does not have much priority to this manual's author.  For now, users
can read the rudimentary descriptions of the Scheme48 virtual machine's
byte code instruction set in @file{vm/interp/arch.scm} of Scheme48's
Scheme source.}
@end deffn

@deffn command {,condition}
@deffnx command {,threads}
For the descriptions of these commands, @pxref{Command levels}.  These
are mentioned here because they are relevant in the context of
debugging.
@end deffn

@cindex tracing
@cindex procedures, tracing
@deffn command {,trace}
@deffnx command {,trace} name @dots{}
@deffnx command {,untrace}
@deffnx command {,untrace} name @dots{}
Traced procedures will print out information about when they are
entered and when they exit.  @samp{,trace} lists all of the traced
procedures' bindings.  @samp{,trace @var{name} @dots{}} sets each
@var{name} in the interaction environment, which should be bound to a
procedure, to be a traced procedure over the original procedure.
@samp{,untrace} resets all traced procedures to their original,
untraced procedures.  @samp{,untrace @var{name} @dots{}} untraces each
individual traced procedure of @var{name} @dots{} in the interaction
environment.
@end deffn

@cindex backtrace
@cindex continuation previews
@cindex previewing continuations
@deffn command {,preview}
Prints a trace of the previous command level's suspended continuation.
This is analogous with stack traces in many debuggers.
@end deffn

@deffn command {,debug}
Invokes the debugger: runs the inspector on the previous command
level's saved continuation.  For more details, @pxref{Inspector}.
@end deffn

@cindex proceeding from errors
@cindex returning from errors
@cindex condition restarting
@deffn command {,proceed}
@deffnx command {,proceed} exp
Returns to the continuation of the condition signalling of the previous
command level.  Only certain kinds of conditions will push a new
command level, however --- breakpoints, errors, and interrupts, and,
if the @code{break-on-warnings} switch is on, warnings ---; also,
certain kinds of errors that do push new command levels do not permit
being proceeded from.  In particular, only with a few VM primitives may
the @command{,proceed} command be used.  If @var{exp} is passed, it is
evaluated in the interaction environment to produce the values to
return; if it is not passed, zero values are returned.
@end deffn

@node Inspector
@subsection Inspector

Scheme48 provides a simple interactive object inspector.  The command
processor's prompt's end changes from @samp{>} to @samp{:} when in
inspection mode.  The inspector is the basis of the debugger, which is,
for the most part, merely an inspector of continuations.  In the
debugger, the prompt is @samp{debug:}.  In the inspector, objects are
printed followed by menus of their components.  Entries in the menu are
printed with the index, which optionally includes a symbolic name, and
the value of the component.  For example, a pair whose car is the
symbol @code{a} and whose cdr is the symbol @code{b} would be printed
by the inspector like this:

@example
'(a . b)

 [0: car] 'a
 [1: cdr] 'b@end example

The inspector maintains a stack of the focus objects it previously
inspected.  Selecting a new focus object pushes the current one onto
the stack; the @command{u} command pops the stack.

@deffn command {,inspect}
@deffnx command {,inspect} exp
Invokes the inspector.  If @var{exp} is present, it is evaluated in the
user package and its result is inspected (or a list of results, if it
returned multiple values, is inspected).  If @var{exp} is absent, the
current focus value is inspected.
@end deffn

The inspector operates with its own set of commands, separate from the
regular interaction commands, although regular commands may be invoked
from the inspector as normal.  Inspector commands are entered with or
without a preceding comma at the inspector prompt.  Multiple inspector
commands may be entered on one line; an input may also consist of an
expression to be evaluated.  If an expression is evaluated, its value
is selected as the focus object.  Note, however, that, since inspector
commands are symbols, variables cannot be evaluated just by entering
their names; one must use either the @command{,run} command or wrap the
variables in a @code{begin}.

These inspector commands are defined:

@deffn {inspector command} menu
@deffnx {inspector command} m
@command{Menu} prints a menu for the focus object.  @command{M} moves
forward in the current menu if there are more than sixteen items to be
displayed.
@end deffn

@deffn {inspector command} u
Pops the stack of focus objects, discarding the current one and setting
the focus object to the current top of the stack.
@end deffn

@deffn {inspector command} q
Quits the inspector, going back into the read-eval-print loop.
@end deffn

@deffn {inspector command} template
Attempts to coerce the focus object into a template.  If successful,
this selects it as the new focus object; if not, this prints an error
to that effect.  Templates are the static components of closures and
continuations: they contain the code for the procedure, the top-level
references made by the procedure, literal constants used in the code,
and any inferior templates of closures that may be constructed by the
code.
@end deffn

@deffn {inspector command} d
Goes down to the parent of the continuation being inspected.  This
command is valid only in the debugger mode, @ie{} when the focus object
is a continuation.
@end deffn

@node Command programs
@subsection Command programs

@cindex exec language
@cindex exec package
The Scheme48 command processor can be controlled programmatically by
@dfn{command programs}, programs written in the @dfn{exec language}.
This language is essentially a mirror of the commands but in a syntax
using S-expressions.  The language also includes all of Scheme.  The
exec language is defined as part of the @dfn{exec package}.

@deffn command {,exec}
@deffnx command {,exec} command
Sets the interaction environment to be the exec package.  If an
argument is passed, it is set temporarily, only to run the given
command.
@end deffn

Commands in the exec language are invoked as procedures in Scheme.
Arguments should be passed as follows:

@itemize @bullet
@item
Identifiers, such as those of structure names in the config package,
should be passed as literal symbols.  For instance, the command
@samp{,in frobbotz} would become in the exec language @code{(in
'frobbotz)}.

@item
Filenames should be passed as strings; @eg{}, @samp{,dump frob.image}
becomes @code{(dump "frob.image")}.

@item
Commands should be represented in list values with the car being the
command name and the cdr being the arguments.  Note that when applying
a command an argument that is a command invocation is often quoted to
produce a list, but the list should not include any quotation; for
instance, @samp{,in mumble ,undefine frobnicate} would become @code{(in
'mumble '(undefine frobnicate))}, even though simply @samp{,undefine
frobnicate} would become @code{(undefine 'frobnicate)}.

The reason for this is that the command invocation in the exec language
is different from a list that represents a command invocation passed as
an argument to another command; since commands in the exec language are
ordinary procedures, the arguments must be quoted, but the quoted
arguments are not themselves evaluated: they are applied as commands.

An argument to a command that expects a command invocation can also be
a procedure, which would simply be called with zero arguments.  For
instance, @code{(config (lambda () (display (interaction-environment))
(newline)))} will call the given procedure with the interaction
environment set to the config package.

@item
Expressions must be passed using the @command{run} command.  For
example, the equivalent of @samp{,user (+ 1 2)} in the exec language
would be @code{(user '(run (+ 1 2)))}.
@end itemize

Command programs can be loaded by running the @command{,load} command
in the exec package.  Scripts to load application bundles are usually
written in the exec language and loaded into the exec package.  For
example, this command program, when loaded into the exec package, will
load @file{foo.scm} into the config package, ensure that the package
@code{frobbotzim} is loaded, and open the @code{quuxim} structure in
the user package:

@lisp
(config '(load "foo.scm"))
(load-package 'frobbotzim)
(user '(open quuxim))@end lisp

@node Image-building commands
@subsection Image-building commands

@cindex dumping heap images
@cindex heap image dumping
@cindex image dumping
@cindex writing heap images
@cindex heap image writing
@cindex image writing
Since Scheme48's operation revolves about an image-based model, these
commands provide a way to save heap images on the file system, which
may be resumed by invoking the Scheme48 virtual machine on them as in
@ref{Running Scheme48}.

@deffn command {,build} resumer filename
@deffnx command {,dump} filename
@deffnx command {,dump} filename message
@command{,build} evaluates @var{resumer}, whose value should be a unary
procedure, and builds a heap image in @var{filename} that, when resumed
by the virtual machine, will pass the resumer all of the command-line
arguments after the @option{-a} argument to the virtual machine.  The
run-time system will have been initialized as with @embedref{Suspending
and resuming heap images,usual resumers}, and a basic condition handler
will have been installed by the time that the resumer is called.  On
Unix, @var{resumer} must return an integer exit status for the process.
@command{,dump} dumps the Scheme48 command processor, including all of
the current settings, to @var{filename}.  If @var{message} is passed,
it should be a string delimited by double-quotes, and it will be
printed as part of the welcome banner on startup; its default value, if
it is not present, is @code{"(suspended image)"}.
@end deffn

@node Resource statistics and control
@subsection Resource statistics and control

Scheme48 provides several devices for querying statistics about various
resources and controlling resources, both in the command processor and
programmatically.

@cindex garbage collection, forcing
@cindex forcing garbage collection
@deffn command {,collect}
Forces a garbage collection and prints the amount of space in the heap
before and after the collection.
@end deffn

@cindex timing execution
@cindex execution timing
@deffn command {,time} expression
Evaluates @var{expression} and prints how long it took.  Three numbers
are printed: run time, GC time, and real time.  The run time is the
amount of time in Scheme code; the GC time is the amount of time spent
in the garbage collector; and the real time is the actual amount of
time that passed during the expression's evaluation.  
@end deffn

@cindex debug data storage control
@cindex storage control of debug data
@deffn command {,keep}
@deffnx command {,keep} kind @dots{}
@deffnx command {,flush}
@deffnx command {,flush} kind @dots{}
Scheme48 maintains several different kinds of information used for
debugging information.  @samp{,keep} with no arguments shows what kinds
of debugging data are preserved and what kinds are not.  @samp{,keep
@var{kind} @dots{}} requests that the debugging data of the given kinds
should be kept; the @command{,flush} command requests the opposite.
@samp{,flush} with no arguments flushes location names and resets the
debug data table.  The following are the kinds of debugging data:

@table @code
@item names
procedure names
@item maps
environment maps used by the debugger to show local variable names
@item files
filenames where procedures were defined
@item source
source code surrounding continuations, printed by the debugger
@item tabulate
if true, will store debug data records in a global table that can be
easily flushed; if false, will store directly in compiled code
@end table

@command{,flush} can also accept @code{location-names}, which will
flush the table of top-level variables' names (printed, for example, by
the @command{,bound?} command); @code{file-packages}, which will flush
the table that maps filenames to packages in which code from those files
should be evaluated; or @code{table}, in which case the table of debug
data is flushed.

Removing much debug data can significantly reduce the size of Scheme48
heap images, but it can also make error messages and debugging much
more difficult.  Usually, all debug data is retained; only for images
that must be small and that do not need to be debuggable should the
debugging data flags be turned off.
@end deffn

@cindex space usage analysis
@cindex heap space analysis
@cindex displaying heap usage
@stindex spatial
The @code{spatial} structure exports these utilities for displaying
various statistics about the heap:

@deffn procedure space @returns{} unspecified
@deffnx procedure vector-space [predicate] @returns{} unspecified
@deffnx procedure record-space [predicate] @returns{} unspecified
@code{Space} prints out a list of the numbers of all objects and the
number of bytes allocated for those objects on the heap, partitioned by
the objects' primitive types and whether or not they are immutable
(pure) or mutable (impure).  @code{Vector-space} prints the number of
vectors and the number of bytes used to store those vectors of several
different varieties, based on certain heuristics about their form.  If
the predicate argument is passed, it gathers only vectors that satisfy
that predicate.  @code{Record-space} prints out, for each record type
in the heap, both the number of all instances of that record type and
the number of bytes used to store all of those instances.  Like
@code{vector-space}, if the predicate argument is passed,
@code{record-space} will consider only those records that satisfy the
predicate.

All of these three procedures first invoke the garbage collector before
gathering statistics.
@end deffn

@cindex object reference analysis
@cindex storage leak analysis
@cindex heap traversal
@stindex traverse
The @code{traverse} structure provides a simple utility for finding
paths by which objects refer to one another.

@deffn procedure traverse-breadth-first object @returns{} unspecified
@deffnx procedure traverse-depth-first object @returns{} unspecified
These traverse the heap, starting at @var{object}, recording all
objects transitively referred to.  @code{Traverse-breadth-first} uses
a FIFO-queue-directed breadth-first graph traversal, while
@code{traverse-depth-first} uses a LIFO-stack-directed depth-first
graph traversal.  The traversal halts at any leaves in the graph,
which are distinguished by an internal @dfn{leaf predicate} in the
module.  See below on @code{set-leaf-predicate!} on how to customize
this and what the default is.

The traversal information is recorded in a global resource; it is not
thread-safe, and intended only for interactive usage.  The record can
be reset by passing some simple object with no references to either
@code{traverse-breadth-first} or @code{traverse-depth-first}; @eg{},
@code{(traverse-depth-first #f)}.
@end deffn

@deffn procedure trail object @returns{} unspecified
After traversing the heap from an initial object, @code{(trail
@var{object})} prints the path of references and intermediate objects
by which the initial object holds a transitive reference to
@var{object}.
@end deffn

@deffn procedure set-leaf-predicate! predicate @returns{} unspecified
@deffnx procedure usual-leaf-predicate object @returns{} boolean
@code{Set-leaf-predicate!} sets the current leaf predicate to be
@var{predicate}.  @code{Usual-leaf-predicate} is the default leaf
predicate; it considers simple numbers (integers and flonums),
strings, byte vectors, characters, and immediate objects (true, false,
nil, and the unspecific object) to be leaves, and everything else to
be branches.
@end deffn