engine/io/mod.rs
1//! Generic input/output primitives.
2//!
3//! The Engine provides the *mechanisms* for streams, pipes, and interactive
4//! screens; it does not assign them operating-system meaning. The Shell
5//! layer routes command stdin/stdout/stderr through these primitives, the OS
6//! commands consume and produce them, and the Terminal layer plugs its
7//! screen in as an output.
8//!
9//! The [`Terminal`] interface is an Engine primitive for the same reason
10//! [`Input`] and [`Output`] are: a rectangular screen, a cursor, and a key
11//! stream are generic abstractions usable by editors, games, and any other
12//! stateful application — not operating-system concepts. Concrete rendering
13//! (ANSI parsing, screen buffers) lives above the Engine.
14//!
15//! # Notes
16//!
17//! - [`Pipe`] is an in-memory, effectively unbounded channel. It exists to
18//! coordinate *sequential* virtual command execution (producer finishes,
19//! then consumer reads); it is not a host OS pipe and does not claim host
20//! concurrency semantics. The Shell runtime layer decides how commands are
21//! scheduled.
22//! - Streams are `Send + Sync` so the Shell may move them between command
23//! invocations.
24
25mod input;
26mod output;
27mod pipe;
28mod terminal;
29
30pub use input::{BytesInput, EmptyInput, Input, InputError, StringInput};
31pub use output::{BytesOutput, Output, OutputError, SinkOutput};
32pub use pipe::Pipe;
33pub use terminal::{InputMode, Key, KeyEvent, Size, Terminal};
34
35#[cfg(test)]
36mod tests {
37 use super::*;
38
39 #[test]
40 fn bytes_round_trip_through_a_pipe() {
41 let pipe = Pipe::new();
42 let mut input = pipe.input();
43 let mut output = pipe.output();
44 output.write(b"hello ").unwrap();
45 output.write(b"world").unwrap();
46 drop(output);
47 let mut bytes = Vec::new();
48 input.read_to_end(&mut bytes).unwrap();
49 assert_eq!(bytes, b"hello world");
50 }
51
52 #[test]
53 fn empty_input_reports_eof() {
54 let mut input = EmptyInput::new();
55 let mut bytes = Vec::new();
56 input.read_to_end(&mut bytes).unwrap();
57 assert!(bytes.is_empty());
58 }
59
60 #[test]
61 fn bytes_input_replays_its_data() {
62 let mut input = BytesInput::new(b"line one\nline two\n");
63 let mut line = String::new();
64 input.read_line(&mut line).unwrap();
65 assert_eq!(line, "line one\n");
66 }
67
68 #[test]
69 fn bytes_output_accumulates() {
70 let mut output = BytesOutput::new();
71 output.write(b"a").unwrap();
72 output.write(b"b").unwrap();
73 assert_eq!(output.into_bytes(), b"ab");
74 }
75
76 #[test]
77 fn sink_output_discards() {
78 let mut output = SinkOutput::new();
79 output.write(b"anything").unwrap();
80 }
81}