scsh-expect/doc/expect.doc

167 lines
6.4 KiB
Plaintext
Raw Normal View History

2004-07-15 13:34:52 -04:00
The Scheme Underground Expect package
Designed and implemented by David Fisher and Olin Shivers
(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>
| (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>)
<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>)
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 ... 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:
#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.
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 . COND-CLAUSE)
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. 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.
(<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'.
2004-07-15 13:34:52 -04:00
(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.
Example: (filter (lambda (c k)
(if
(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-Mung 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.