Skip to main content

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}