Crate expectrl

A tool for automating terminal applications on alike original expect.

Using the library you can:

• Spawn process
• Control process
• Interact with process’s IO(input/output).

expectrl like original expect may shine when you’re working with interactive applications. If your application is not interactive you may not find the library the best choise.

Feature flags

• async: Enables a async/await public API.
• polling: Enables polling backend in interact session. Be cautious to use it on windows.

Examples

An example for interacting via ftp.

use expectrl::{spawn, Regex, Eof, WaitStatus};

let mut p = spawn("ftp speedtest.tele2.net").unwrap();
p.expect(Regex("Name \\(.*\\):")).unwrap();
p.send_line("anonymous").unwrap();
p.expect("Password").unwrap();
p.send_line("test").unwrap();
p.expect("ftp>").unwrap();
p.send_line("cd upload").unwrap();
p.expect("successfully changed.\r\nftp>").unwrap();
p.send_line("pwd").unwrap();
p.expect(Regex("[0-9]+ \"/upload\"")).unwrap();
p.send_line("exit").unwrap();
p.expect(Eof).unwrap();
assert_eq!(p.wait().unwrap(), WaitStatus::Exited(p.pid(), 0));

The example inspired by the one in [philippkeller/rexpect].

An example when Command is used.

use std::{process::Command, io::prelude::*};
use expectrl::Session;

let mut echo_hello = Command::new("sh");
echo_hello.arg("-c").arg("echo hello");

let mut p = Session::spawn(echo_hello).unwrap();
p.expect("hello").unwrap();

An example of logging.

use std::io::{stdout, prelude::*};
use expectrl::{spawn, session::log};

let mut sh = log(spawn("sh").unwrap(), stdout()).unwrap();

writeln!(sh, "Hello World").unwrap();

An example of async feature.

You need to provide a features=["async"] flag to use it.

use expectrl::spawn;

let mut p = spawn("cat").await.unwrap();
p.expect("hello").await.unwrap();

An example of interact session with STDIN and STDOUT

use expectrl::{spawn, stream::stdin::Stdin};
use std::io::stdout;

let mut sh = spawn("cat").expect("Failed to spawn a 'cat' process");

let mut stdin = Stdin::open().expect("Failed to create stdin");

sh.interact(&mut stdin, stdout())
    .spawn()
    .expect("Failed to start interact session");

stdin.close().expect("Failed to close a stdin");

For more examples, check the examples directory.

Re-exports

pub use session::Session;

Modules

interact

This module contains a routines for running and utilizing an interacting session with a Session.

process

This module contains a platform independent abstraction over an os process.

repl

This module contains a list of special Sessions that can be spawned.

session

This module contains a system independent Session representation.

stream

Stream module contains a set of IO (write/read) wrappers.

Macros

check

Check macros provides a convient way to check if things are available in a stream of a process.

Structs

Any

Any matches uses all provided lookups and returns a match from a first successfull match.

Captures

Captures is a represention of matched pattern.

Eof

Eof consider a match when an EOF is reached.

NBytes

NBytes matches N bytes from the stream.

Regex

Regex tries to look up a match by a regex.

Enums

ControlCode

ControlCode represents the standard ASCII control codes wiki

Error

An main error type used in crate.

Signal

Types of operating system signals

WaitStatus

Possible return values from wait() or waitpid().

Traits

Needle

Needle an interface for search of a match in a buffer.

Functions

spawn

Spawn spawnes a new session.