211 lines
8.5 KiB
Plaintext
211 lines
8.5 KiB
Plaintext
The Scheme Underground Expect package
|
|
Designed and implemented by David Fisher, Olin Shivers and David Frese
|
|
|
|
(spawn* THUNK) -> task procedure
|
|
|
|
Spawn* forks a process to execute THUNK, and returns a task data-structure
|
|
that contains all of the information that expect-package elements need in
|
|
order to interact with that process.
|
|
|
|
(spawn . EPF) -> task procedure
|
|
|
|
This is syntactic sugar for (spawn* (lambda () (exec-epf EPF))).
|
|
Spawns the epf.
|
|
|
|
(ports->task INPUT-PORT OUTPUT-PORT) -> task procedure
|
|
|
|
This procedure constructs a task from a pair of ports.
|
|
|
|
(task:in TASK) -> output-port procedure
|
|
(task:out TASK) -> input-port procedure
|
|
(task:process TASK) -> process procedure
|
|
|
|
These three procedures return, in order, the input port that can be used to
|
|
get data from the task, the output port that can be used to send data to the
|
|
task, and the process that the task is running.
|
|
|
|
(task:pre-match TASK) -> string procedure
|
|
(task:buf TASK) -> string procedure
|
|
|
|
When an EXPECT pattern matches some input, the task:pre-match field is set to
|
|
the string preceding the matched data, and the task:buf field is set to the
|
|
string coming after the matched data, that is, it saves input that hasn't
|
|
yet been processed. When EXPECT starts, it first considers any data stored
|
|
in the task:buf field.
|
|
|
|
(set-task:pre-match TASK STR)
|
|
(set-task:buf TASK STR)
|
|
...
|
|
|
|
-------------------------------------------------------------------------------
|
|
(EXPECT [<name> <loop-var-inits>] <eclause> ...) -> values syntax
|
|
|
|
<eclause> ::= (<task> <aclause> ...) [Task clause.]
|
|
| <option-clause>
|
|
|
|
Action clauses:
|
|
<aclause> ::= (ON-EOF <body> ...) [Do on EOF.]
|
|
| (<pattern> <matchvars> <exp> ...) [Do if pattern matches.]
|
|
| (TEST <exp> <body> ...)
|
|
| (TEST <exp> => <proc>)
|
|
| (ELSE <body> ...)
|
|
|
|
<matchvars> ::= () [No match info]
|
|
| (<matchvar>) [Match struct only]
|
|
| (<matchvar> <submatch-var0> ...) [...also submatch strings.]
|
|
|
|
<option-clause> ::= (OPTION <option> ...)
|
|
<option> ::= (TIMEOUT <nsecs>)
|
|
| (ECHO <bool>) ; Not supported
|
|
| (MAX-SIZE <nchars>) ; Not supported
|
|
| (MONITOR <proc>)
|
|
| (ON-TIMEOUT <body> ...) [Do on timeout.]
|
|
|
|
Expect takes a number of tasks, and waits for a number of patterns to
|
|
be output by these tasks. When expect sees a pattern for which it has been
|
|
waiting, it executes the appropriate list of commands. The two types of
|
|
expect clauses are option clauses and task-pattern clauses.
|
|
|
|
Option clauses take the form (OPTION <option> ...)
|
|
where an <option> is one of
|
|
(TIMEOUT <nsecs>) This controls how long expect waits for the patterns
|
|
before timing out. The lowest timeout clause
|
|
determines when the entire expect form will time out.
|
|
A timeout value of #f means no timeout. The default
|
|
value is 10 seconds.
|
|
|
|
(MONITOR <proc>) This hook establishes a monitor procedure for the
|
|
the expect processing. A monitor is a procedure
|
|
of two arguments, that is applied when various
|
|
events occur. The second argument specifies the
|
|
event that occured for a task, which is passed
|
|
as the first argument (expect for the timeout
|
|
event which will have #f as the first argument).
|
|
#F EOF
|
|
regexp Match occurred.
|
|
string New input arrived.
|
|
This string will not span a match.
|
|
That is, if new input arrives and
|
|
is matched, then we only report the
|
|
new input up to the end of the match.
|
|
The rest of the input is saved in the
|
|
task's push-back buffer and is not reported.
|
|
'timeout EXPECT timed out.
|
|
|
|
(ON-TIMEOUT <body> ...)
|
|
This option specifies a special timeout-handler,
|
|
which has to be a function with no arguments,
|
|
which is called after the monitor is informed of
|
|
the timeout, and whose return value is the
|
|
return value of the whole expect call.
|
|
|
|
An action clause <aclause> can be one of
|
|
(<pattern> <matchvars> <body> ...)
|
|
If the pattern matches input read from the task, expect binds the
|
|
match vars and then executes the body forms. The value of the whole
|
|
EXPECT form is the value produced by the last body form. The match
|
|
vars list is of the form
|
|
([<match-var> [<sub-match-var0> ... <sub-match-varN>]])
|
|
<match-var> is bound to the regexp match structure. <sub-match-varI>
|
|
is bound to the string corresponding to the regexp's Ith sub-match
|
|
(where sub-match 0 is the string for the whole match). Any of these
|
|
variables may be #F instead of an identifier, meaning a "don't-care"
|
|
binding.
|
|
|
|
(on-eof EXPRESSION ...)
|
|
If EXPECT hits EOF on the task without finding a match, this clause
|
|
is triggered. If EXPECT hits EOF and there is no ON-EOF clause for
|
|
the task, nothing happens.
|
|
|
|
(test <exp> <body> ...)
|
|
(test <exp> => <proc>)
|
|
(else <body> ...)
|
|
This allows for general conditionals to be placed into the
|
|
EXPECT form.
|
|
|
|
-------------------------------------------------------------------------------
|
|
(INTERACT <task> <iclause> ...) syntax
|
|
|
|
Interact allows the user to interact with a running task, relaying the
|
|
keys pressed by the user to the task and outputting the characters
|
|
provided by the task to the user. For this purpose interact also turns
|
|
the terminal modes for the current input port to raw mode and turns
|
|
the echo off. If clauses are provided by the programmer, interact will
|
|
filter input before passing it along to the task, or filter output
|
|
from the task before showing it to the user. A clause is either a
|
|
timeout-clause or a pattern-clause.
|
|
|
|
(TIMEOUT <seconds> <handler>)
|
|
If none of the pattern-clauses match within the given number of
|
|
seconds, then the handler-procedure is called with a continuation
|
|
procedure that can be called to return from the interact-call. If
|
|
the continuation is not called, interact continues normally.
|
|
|
|
(<pattern> (<flag> ...) (k m ...) <body> ...)
|
|
The pattern can either be a character, a string or a regular
|
|
expression, although only characters are supported in this
|
|
version.
|
|
|
|
If the pattern matches some portion of the input from
|
|
the user or the output of the task, the continuation of the
|
|
interact-call is bound to K, M is bound to the matched character,
|
|
string or regexp-match object respectively, and if the pattern is
|
|
a regexp and more variable names are given, then the correspoding
|
|
submatches are bound to these names. Finally the body expressions
|
|
are executed. If the continuation is not called, interact
|
|
continues normally.
|
|
|
|
Furhtermore, the pattern can also be the special value
|
|
eof-pattern, which make it possible to react to an end-of-file
|
|
signal while either reading from the user or reading the output of
|
|
the task. In this case M is bound to #f, and the interaction is
|
|
not restarted after the body is executed.
|
|
|
|
Possible flags are:
|
|
output The whole pattern should be applied to the output of the
|
|
task. If this flag is not present, the pattern is matched
|
|
against the user-input.
|
|
reset The terminal modes are restored before the body is
|
|
executed, and set back to raw when it finishes.
|
|
echo The characters that match a pattern, are sent back to the
|
|
process that generated them (either the user or the task).
|
|
[not implemented]
|
|
|
|
Example: ((rx "a") () (return m) (display "You pressed a\n"))
|
|
|
|
(EOF (<flag> ...) <body> ...)
|
|
This a shortcut for
|
|
(eof-pattern (<flag>) (k m) <body> ...)
|
|
|
|
-------------------------------------------------------------------------------
|
|
(send STRING TASK) -> (undefined) procedure
|
|
|
|
Send sends the string to the task, as if a user had typed it.
|
|
|
|
(close-task TASK) -> (undefined) procedure
|
|
|
|
Close-task closes all input and output ports corresponding to the indicated
|
|
task.
|
|
|
|
(wait-task TASK) -> (undefined) procedure
|
|
|
|
Wait-task waits for the indicated task to complete, reaping the task.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Tty-Utils Package
|
|
|
|
(modify-tty-info PROC [PORT]) procedure
|
|
|
|
Modify-tty-info applies PROC to either the tty-info of the current
|
|
input port, or the indicated PORT, changing the state of the terminal.
|
|
There are five procedures provided to use with modify-tty-info:
|
|
|
|
echo-off Turns terminal echoing off.
|
|
echo-on Turns terminal echoing on.
|
|
raw Puts the terminal into raw mode. Raw-initialize _must_
|
|
be used after raw for it to work right.
|
|
raw-initialize Initializes the min and time fields of a raw terminal.
|
|
canonical Puts the terminal into raw mode.
|
|
|
|
|