rust_expect/
session.rs

1//! Session module for managing spawned process interactions.
2//!
3//! This module provides the core session types and functionality for
4//! interacting with spawned processes, including the session handle,
5//! builder, lifecycle management, and screen buffer integration.
6//!
7//! # Overview
8//!
9//! The [`Session`] type is the main entry point for interacting with
10//! terminal applications. It provides methods for:
11//!
12//! - Spawning processes with [`Session::spawn`]
13//! - Sending input with [`Session::send`], [`Session::send_line`]
14//! - Expecting output with [`Session::expect`], [`Session::expect_any`]
15//! - Running dialogs with [`Session::run_dialog`]
16//!
17//! # Examples
18//!
19//! ## Basic Usage
20//!
21//! ```no_run
22//! use rust_expect::Session;
23//!
24//! #[tokio::main]
25//! async fn main() -> Result<(), rust_expect::ExpectError> {
26//!     // Spawn a bash shell
27//!     let mut session = Session::spawn("/bin/bash", &[]).await?;
28//!
29//!     // Wait for the prompt
30//!     session.expect("$ ").await?;
31//!
32//!     // Send a command
33//!     session.send_line("echo 'Hello, World!'").await?;
34//!
35//!     // Expect the output
36//!     session.expect("Hello, World!").await?;
37//!
38//!     // Clean exit
39//!     session.send_line("exit").await?;
40//!     Ok(())
41//! }
42//! ```
43//!
44//! ## Using the Builder
45//!
46//! ```no_run
47//! use rust_expect::{Session, SessionBuilder};
48//! use std::time::Duration;
49//!
50//! #[tokio::main]
51//! async fn main() -> Result<(), rust_expect::ExpectError> {
52//!     // Builder produces a SessionConfig; spawn via Session::spawn_with_config.
53//!     let config = SessionBuilder::new()
54//!         .command("/bin/bash")
55//!         .args(["-l"])
56//!         .timeout(Duration::from_secs(30))
57//!         .dimensions(120, 40)
58//!         .env("TERM", "xterm-256color")
59//!         .build();
60//!
61//!     let mut session = Session::spawn_with_config(
62//!         &config.command,
63//!         &config.args.iter().map(String::as_str).collect::<Vec<_>>(),
64//!         config.clone(),
65//!     ).await?;
66//!
67//!     session.expect("$ ").await?;
68//!     Ok(())
69//! }
70//! ```
71//!
72//! ## Multi-Pattern Matching
73//!
74//! ```no_run
75//! use rust_expect::{Session, Pattern, PatternSet};
76//! use std::time::Duration;
77//!
78//! #[tokio::main]
79//! async fn main() -> Result<(), rust_expect::ExpectError> {
80//!     let mut session = Session::spawn("/bin/bash", &[]).await?;
81//!
82//!     // Create a pattern set with multiple options
83//!     let mut patterns = PatternSet::new();
84//!     patterns
85//!         .add(Pattern::literal("$ "))
86//!         .add(Pattern::literal("# "));
87//!
88//!     // Expect any of the patterns; pass a bound via expect_timeout if needed.
89//!     let _ = Duration::from_secs(5);
90//!     let result = session.expect_any(&patterns).await?;
91//!     println!("Matched: {}", result.matched);
92//!     Ok(())
93//! }
94//! ```
95
96mod builder;
97mod handle;
98mod lifecycle;
99mod screen;
100
101pub use builder::{QuickSession, SessionBuilder};
102pub use handle::{OutputTap, Session, SessionExt, TapId};
103pub use lifecycle::{
104    LifecycleCallback, LifecycleEvent, LifecycleManager, ShutdownConfig, ShutdownStrategy, Signal,
105};
106pub use screen::{Cell, CellAttributes, Color, Position, Region, ScreenBuffer};
rust_expect/session.rs

rust_expect/
session.rs
