Crate expectrl

source ·
Expand description

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

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.