4.9 KiB
wdye(1)
Name
wdye - what did you expect: Lua-based Expect tool
Synopsis
wdye program.lua
Description
wdye executes a Lua script, providing an expect(1)-like API targeted at application testing.
API
This list is logically ordered. Uppercase names represent object types.
wdye.spawn {file [, arg1, …] [, environ=env]}
Creates a new pseudoterminal, spawns the given program in it, and returns a process object. When file doesn’t contain slashes, the program will be searched for in PATH.
The env map may be used to override environment variables, notably TERM. Variables evaluating to false will be removed from the environment.
The program’s whole process group receives SIGKILL when the process is garbage-collected, unless wait has collected the process group leader.
wdye.expect ([pattern1, …])
Waits until any pattern is ready, in order. When no timeout (or default) patterns are included, one is added implicitly.
The function returns the matching pattern's values, while replacing any included functions with the results of their immediate evaluation, passing the matching pattern as their sole argument.
wdye.timeout {[timeout, ] [value1, …]}
Returns a new timeout pattern. When no timeout is given, which is specified in seconds, a default timeout value is assumed. Any further values are remembered to be later processed by expect.
wdye.continue ()
Raises a nil error, which is interpreted by expect as a signal to restart all processing.
PROCESS.buffer
A string with the process' current read buffer contents.
PROCESS.pid
An integer with the process' process ID, or -1 if wait has collected it.
PROCESS.term
A table with the process' terminfo(5) capabilities, notably containing all key_… codes. This functionality may not be enabled, then this table will always be empty.
PROCESS:send ([string, …])
Writes the given strings to the process' terminal slave, and returns the process for method chaining.
Beware of echoing and deadlocks, as only expect can read from the process, and thus consume the terminal slave’s output queue.
PROCESS:regex {pattern [, nocase=true] [, notransfer=true] [, value1, …]}
Returns a new regular expression pattern. The pattern is a POSIX Extended Regular Expression. Whether it can match NUL bytes depends on your system C library.
When the nocase option is true, the expression will be matched case-insensitively.
Unless the notransfer option is true, all data up until the end of the match will be erased from the process' read buffer upon a successful match.
PROCESS:exact {literal [, nocase=true] [, notransfer=true] [, value1, …]}
Returns a new literal string pattern. This behaves as if the literal had its ERE special characters quoted, and was then passed to regex. This pattern can always match NUL bytes.
PROCESS:eof {[notransfer=true, ] [value1, …]}
Returns a new end-of-file pattern, which matches the entire read buffer contents once the child process closes the terminal.
PROCESS:wait ([nowait])
Waits for the program to terminate, and returns three values:
a combined status as used by $? in shells,
an exit status, and a termination signal number.
One of the latter two values will be nil, as appropriate.
When the nowait option is true, the function returns immediately. If the process hasn’t terminated yet, the function then returns no values.
PROCESS:default {[timeout, ] [notransfer=true, ] [value1, …]}
Returns a new pattern combining wdye.timeout with eof.
PATTERN.process
A reference to the pattern's respective process, or nil.
PATTERN[group]
For patterns that can match data, the zeroth group will be the whole matched input sequence. For regex patterns, positive groups relate to regular expression subgroups. Missing groups evaluate to nil.
Example
for k, v in pairs(wdye) do _G[k] = v end
local rot13 = spawn {"tr", "A-Za-z", "N-ZA-Mn-za-m", environ={TERM="dumb"}}
rot13:send "Hello\r"
expect(rot13:exact {"Uryyb\r"})
Environment
- WDYE_LOGGING
-
When this environment variable is present, wdye produces asciicast v2 files for every spawned program, in the current working directory.
Reporting bugs
Use https://git.janouch.name/p/liberty to report bugs, request features, or submit pull requests.
See also
expect(1), terminfo(5), regex(7)