- adjusted documentation for expect and interact

This commit is contained in:
frese 2004-08-25 16:00:13 +00:00
parent adbb0856af
commit e80f450175
1 changed files with 65 additions and 25 deletions

View File

@ -1,5 +1,5 @@
The Scheme Underground Expect package
Designed and implemented by David Fisher and Olin Shivers
Designed and implemented by David Fisher, Olin Shivers and David Frese
(spawn* THUNK) -> task procedure
@ -42,12 +42,13 @@ in the task:buf field.
<eclause> ::= (<task> <aclause> ...) [Task clause.]
| <option-clause>
| (ON-TIMEOUT <body> ...) [Do on timeout.]
Action clauses:
<aclause> ::= (ON-EOF <body> ...) [Do on EOF.]
| (<pattern> <matchvars> <exp> ...) [Do if pattern matches.]
| (TEST . <cond-clause>)
| (TEST <exp> <body> ...)
| (TEST <exp> => <proc>)
| (ELSE <body> ...)
<matchvars> ::= () [No match info]
| (<matchvar>) [Match struct only]
@ -58,6 +59,7 @@ Action clauses:
| (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
@ -70,12 +72,15 @@ where an <option> is one of
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 ... seconds.
value is 10 seconds.
(MONITOR <proc>) This hook establishes a monitor procedure for the
the expect processing. A monitor is a procedure
of one argument, that is applied when various
events occur:
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.
@ -87,6 +92,13 @@ where an <option> is one of
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
@ -105,7 +117,9 @@ An action clause <aclause> can be one of
is triggered. If EXPECT hits EOF and there is no ON-EOF clause for
the task, nothing happens.
(test . COND-CLAUSE)
(test <exp> <body> ...)
(test <exp> => <proc>)
(else <body> ...)
This allows for general conditionals to be placed into the
EXPECT form.
@ -114,26 +128,52 @@ An action clause <aclause> can be one of
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. If clauses are provided by the
programmer, interact will filter input before passing it along to the
task. A clause is either a character-clause or a filter-clause.
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.
(<character> <continuation-variable> <body> ...)
When interact matches the character, it bind the continuation variable
to the continuation out of the interaction, then evaluates the clause
body. <character> can also be 'eof'.
(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.
(FILTER <procedure>)
Where filter is passed two variables, the character input and the
continuation out of the interaction. In both cases, if the clause
returns true, it falls through to the next clause. If all clauses
fall through, the character is passed on to the task. However, the
continuation still needs to be called in order to break out of the
interaction.
(<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.
Example: (filter (lambda (c k)
(if
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.
@ -148,7 +188,7 @@ task.
Wait-task waits for the indicated task to complete, reaping the task.
-------------------------------------------------------------------------------
Tty-Mung Package
Tty-Utils Package
(modify-tty-info PROC [PORT]) procedure