expectrl

For scenarios requiring complex logic (like reading passwords from stdin or reacting to specific output patterns dynamically), use InteractSession.

InteractSession allows you to define an output_action closure that inspects the process buffer (ctx.buf) and determines how the session should proceed. This is useful for stateful interactions where the next step depends on the output received.

use std::io::stdout;
use expectrl::{
    interact::{actions::lookup::Lookup, InteractSession},
    stream::stdin::Stdin,
    ControlCode, Error, Expect, Regex,
};

fn main() -> Result<(), Error> {
    let mut p = expectrl::spawn("ftp bks4-speedtest-1.tele2.net")?;

    let mut search = Lookup::new();
    let mut stdin = Stdin::open()?;

    let authenticated = {
        let mut session = InteractSession::new(&mut p, &mut stdin, stdout(), false);
        session.set_output_action(move |ctx| {
            let found = search.on(ctx.buf, ctx.eof, "Login successful")?;
            if found.is_some() {
                *ctx.state = true;
                return Ok(true);
            }

            Ok(false)
        });

        session.spawn()?;

        session.into_state()
    };

    stdin.close()?;

    if !authenticated {
        println!("An authentication was not passed");
        return Ok(());
    }

    p.expect("ftp>")?;
    p.send_line("cd upload")?;
    p.expect("successfully changed.")?;
    p.send_line("pwd")?;
    p.expect(Regex("[0-9]+ \"/upload\""))?;
    p.send(ControlCode::EndOfTransmission)?;
    p.expect("Goodbye.")?;

    Ok(())
}

You can automate terminal applications by spawning a process and using .expect() to wait for specific patterns (strings or regex) and .send_line() to provide input. This mimics a human interacting with a CLI.

Key methods:

• expectrl::spawn(cmd): Spawns the child process.
• p.expect(pattern): Waits for a pattern. Patterns can be a string literal, a Regex, or the Eof constant.
• p.send_line(text): Sends a line of text followed by a newline.
• p.send(ControlCode): Sends specific control codes.

use expectrl::{Regex, Eof, Error, Expect};

fn main() -> Result<(), Error> {
    let mut p = expectrl::spawn("ftp speedtest.tele2.net")?;
    p.expect(Regex("Name \(.*\):"))?;
    p.send_line("anonymous")?;
    p.expect("Password")?;
    p.send_line("test")?;
    p.expect("ftp>")?;
    p.send_line("cd upload")?;
    p.expect("successfully changed.\r\nftp>")?;
    p.send_line("pwd")?;
    p.expect(Regex("[0-9]+ \"/upload\""))?;
    p.send_line("exit")?;
    p.expect(Eof)?;

    Ok(())
}

The Any<I> struct allows you to combine multiple Needle implementations into a single search operation. It checks the provided needles in the order they are provided and returns the first successful match it finds.

Using fixed-size arrays or slices

You can pass arrays or slices of types that implement Needle directly to Any:

// Using an array of strings
let needle = Any(["we", "are", "here"]);

Using Any::boxed for heterogeneous needles

If you need to combine different types of needles (e.g., a String and an NBytes), you must use Any::boxed with a Vec<Box<dyn Needle>>:

use expectrl::{Any, NBytes};

let needle = Any::boxed(vec![
    Box::new("we"), 
    Box::new(NBytes(3))
]);

use expectrl::{spawn, Any};

let mut p = spawn("cat").unwrap();
p.expect(Any(["we", "are", "here"])).unwrap();

// For mixed types:
let mut p = spawn("cat").unwrap();
p.expect(Any::boxed(vec![Box::new("we"), Box::new(NBytes(3))])).unwrap();

The Captures struct represents the result of a pattern match within a buffer. It allows you to retrieve the specific byte slices that matched a pattern, the data preceding the first match, or iterate through all matches found.

Key methods:

• is_empty(): Returns true if no matches were found.
• get(index: usize): Returns an Option<&[u8]> containing the bytes of the match at the specified index. Returns None if the index is out of bounds.
• before(): Returns a slice of the bytes appearing before the very first match.
• as_bytes(): Returns the entire underlying buffer.
• matches(): Returns a MatchIter to iterate over all matched byte slices.
• Index<usize>: You can use standard indexing (e.g., &captures[0]) to access matches, but this will panic if the index is out of bounds or if no matches exist.

// Assuming Captures is provided by the library
let captures = Captures::new(b"You can use iterator".to_vec(), vec![Match::new(0, 3), Match::new(4, 7)]);

// Access specific matches safely
if let Some(first_match) = captures.get(0) {
    println!("Found: {:?}", first_match); // b"You"
}

// Access data before the first match
let prefix = captures.before(); 

// Access all bytes
let all_bytes = captures.as_bytes();