sunterlib/scsh/interaction/README

The interaction library currently offers three structures that provide
a programmatic interface to Scheme 48's debugging facilities: 

* REPLS starts the read-eval-print-loop with arbitrary input and
  output ports.

* INSPECT-EXCEPTION provides exception handlers that allow interactive
  inspection of exceptions and their backtrace.

* GC provides a small run-time interface to the garbage collector.

================================================================================

After installation, use the switches

-lel module-system/load.scm -lel interaction/load.scm 

to load this library.

================================================================================

The structure REPLS offers procedures to start up the
read-eval-print-loop (REPL) from a script.

(script-repl greeting focus-value iport oport eport)

This procedure starts up a new REPL which greets the user with
GREETING, has FOCUS-VALUE as initial focus-value (accessible through
##) and uses the ports IPORT for input, OPORT for output and eport for
error messages.



(remote-repl greeting focus-value port)

Same as above but communication is done via a socket on port PORT.



The structure SOCKET2STDPORTS offers a very simple facility to map the
current input and output ports to the ports of a socket.

(socket<->stdports host port)

This procedure first establishes a TCP socket to port PORT on host
HOST. Afterwards is reads all data from (current-input-port) and
forwards it into the socket's input port. Likewise it reads all data
from the socket's output port and prints it to
(current-output-port).


The structure INSPECT-EXCEPTION makes some of the functionality of the
,debug and ,preview commands available.

(with-inspecting-handler port prepare thunk)

This procedure installs a exception handler which captures all
conditions which satisfy the predicate ERROR?. In case of an exception
PREPARE is applied to the condition. If it returns #t,
WITH-INSPECTING-HANDLER will fire up a remote REPL on port PORT with
the continuation of the condition as focus value. Currently, the
continuation of the REPL is the continuation of the call to
WITH-INSPECTING-HANDLER. If PREPARE returns #f the surrounding handler
is called.


As an example for the usage of the remote inspecting utility, consider
a program using WITH-INSPECTING-HANDLER with an obviously bogus body:

>(with-inspecting-handler 8080 
                        (lambda (cond) (display "Help me on port 8080") #t)
                        (lambda () (/ 1 0)))
Help me on port 8080

Now start a second scsh:

[0 gasbichl@ventoux interaction] scsh -lm interfaces.scm -lm packages.scm -o 'socket2stdports'
Welcome to scsh 0.6.3
Type ,? for help.
> (socket<->stdports "ventoux" 8080)
Welcome to the command processor of the remote scsh
#{Exception-continuation (pc 69) (integer/ in ratnums)}
> ,debug
'#{Exception-continuation (pc 69) (integer/ in ratnums)}

 [0] 1
 [1] 0
inspect: d  
'#{Exception-continuation (pc 15) (/ in scheme-level-0)}

inspect: d
'#{Continuation (pc 13) (unnamed in unnamed in unnamed ---)}

 [0] '#{Procedure 1319 (unnamed in continuation->procedure in wind)}
 [1: k] '#{Procedure 1319 (unnamed in continuation->procedure in wind)}
 [2: accept] '#{Procedure 1319 (unnamed in continuation->procedure in wind)}
 [3: handler] '#{Procedure 14367 (unnamed in with-inspecting-handler in inspect-exception)}
 [4: thunk] '#{Procedure 14379}
inspect: ,go 34
Terminating command processor with value 34 


Unfortunately, SOCKET<->STD-PORTS is currently not able to exit
gracefully if the connection dies:

Error: exception
       os-error
       (channel-maybe-write 32 '#{Byte-vector 10} 0 1 '#{Output-channel 4} ---)

WARNING: Returning does not work from a scsh with a running REPL!!!



(with-fatal-and-capturing-error-handler handler thunk)

An exception handler with allows to capture the continuation of the
exception. Here HANDLER is a procedure like

(handler condition raw-continuation condition decline) -> val

CONDITION and DECLINE are the same as in the usual WITH-HANDLER
procedure. RAW-CONTINUATION and CONTIUNATION represent the
continuation of the exception. RAW-CONTINUATION is not a procedure but
the VM's continuation object. The continuation of HANDLER is the
continuation of WITH-FATAL-AND-CAPTURING-ERROR-HANDLER.


(display-continuation raw-continuation [port] -> unspecified

The procedural analogy to the ,proceed command. Continuation must be a
raw continuation object as captured by
WITH-FATAL-AND-CAPTURING-ERROR-HANDLER, not a procedure as captured by
CALL-WITH-CURRENT-CONTINUATION.


The structure GC provides a procedure equivalent to the ,collect
command and offers some statistics about the garbage collector.

(collect outport) -> unspecified

Invokes the GC and prints the number of free words before and after
the collection to OUTPORT.

(gc-count) -> number

Returns the number of times the garbage collector has been invoked
since the start of the system.