scsh-conservatory
/
scsh-expect
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- 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

88
doc/expect.doc
View File

@ -1,5 +1,5 @@
The Scheme Underground Expect package 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 (spawn* THUNK) -> task procedure
@ -42,12 +42,13 @@ in the task:buf field.
<eclause> ::= (<task> <aclause> ...) [Task clause.] <eclause> ::= (<task> <aclause> ...) [Task clause.]
| <option-clause> | <option-clause>
| (ON-TIMEOUT <body> ...) [Do on timeout.]
Action clauses: Action clauses:
<aclause> ::= (ON-EOF <body> ...) [Do on EOF.] <aclause> ::= (ON-EOF <body> ...) [Do on EOF.]
| (<pattern> <matchvars> <exp> ...) [Do if pattern matches.] | (<pattern> <matchvars> <exp> ...) [Do if pattern matches.]
| (TEST . <cond-clause>) | (TEST <exp> <body> ...)
| (TEST <exp> => <proc>)
| (ELSE <body> ...)
<matchvars> ::= () [No match info] <matchvars> ::= () [No match info]
| (<matchvar>) [Match struct only] | (<matchvar>) [Match struct only]
@ -58,6 +59,7 @@ Action clauses:
| (ECHO <bool>) ; Not supported | (ECHO <bool>) ; Not supported
| (MAX-SIZE <nchars>) ; Not supported | (MAX-SIZE <nchars>) ; Not supported
| (MONITOR <proc>) | (MONITOR <proc>)
| (ON-TIMEOUT <body> ...) [Do on timeout.]
Expect takes a number of tasks, and waits for a number of patterns to 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 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 before timing out. The lowest timeout clause
determines when the entire expect form will time out. determines when the entire expect form will time out.
A timeout value of #f means no timeout. The default 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 (MONITOR <proc>) This hook establishes a monitor procedure for the
the expect processing. A monitor is a procedure the expect processing. A monitor is a procedure
of one argument, that is applied when various of two arguments, that is applied when various
events occur: 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 #F EOF
regexp Match occurred. regexp Match occurred.
string New input arrived. string New input arrived.
@ -87,6 +92,13 @@ where an <option> is one of
task's push-back buffer and is not reported. task's push-back buffer and is not reported.
'timeout EXPECT timed out. '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 An action clause <aclause> can be one of
(<pattern> <matchvars> <body> ...) (<pattern> <matchvars> <body> ...)
If the pattern matches input read from the task, expect binds the 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 is triggered. If EXPECT hits EOF and there is no ON-EOF clause for
the task, nothing happens. 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 This allows for general conditionals to be placed into the
EXPECT form. 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 Interact allows the user to interact with a running task, relaying the
keys pressed by the user to the task and outputting the characters 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 provided by the task to the user. For this purpose interact also turns
programmer, interact will filter input before passing it along to the the terminal modes for the current input port to raw mode and turns
task. A clause is either a character-clause or a filter-clause. 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> ...) (TIMEOUT <seconds> <handler>)
When interact matches the character, it bind the continuation variable If none of the pattern-clauses match within the given number of
to the continuation out of the interaction, then evaluates the clause seconds, then the handler-procedure is called with a continuation
body. <character> can also be 'eof'. procedure that can be called to return from the interact-call. If
the continuation is not called, interact continues normally.
(FILTER <procedure>) (<pattern> (<flag> ...) (k m ...) <body> ...)
Where filter is passed two variables, the character input and the The pattern can either be a character, a string or a regular
continuation out of the interaction. In both cases, if the clause expression, although only characters are supported in this
returns true, it falls through to the next clause. If all clauses version.
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.
Example: (filter (lambda (c k) If the pattern matches some portion of the input from
(if 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 STRING TASK) -> (undefined) procedure
Send sends the string to the task, as if a user had typed it. 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. Wait-task waits for the indicated task to complete, reaping the task.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
Tty-Mung Package Tty-Utils Package
(modify-tty-info PROC [PORT]) procedure (modify-tty-info PROC [PORT]) procedure