scsh-expect/doc/expect.doc

207 lines
8.4 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"))
-------------------------------------------------------------------------------
(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.