Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_tui/src/lib_tui/term/mod.rs

3.1 KiB, 11 runs

created by r1870400018:20807, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! A terminal model: a byte stream in, a screen you can draw out.
2//!
3//! A pseudoterminal hands over a stream of bytes. Somewhere between those bytes and a window there
4//! has to be a thing that knows a screen is eighty columns wide, that `ESC [ 2 J` means clear it,
5//! and that the half of a character delivered at the end of one read belongs to the byte at the
6//! start of the next. This module is that thing. It draws nothing and reads nothing; it is a model,
7//! and a renderer of any kind, whether a text user interface, a canvas in a browser or a test,
8//! reads the model and paints.
9//!
10//! ```no_run
11//! use oxedyne_fe2o3_tui::lib_tui::term::Terminal;
12//! use oxedyne_fe2o3_core::prelude::*;
13//!
14//! fn example(bytes: &[u8]) -> Outcome<()> {
15//! let mut term = res!(Terminal::new(80, 24));
16//! res!(term.feed(bytes));
17//! for row in term.damage().dirty_rows() {
18//! let _line = term.screen().row_text(row);
19//! // Paint the row.
20//! }
21//! term.clear_damage();
22//! Ok(())
23//! }
24//! ```
25//!
26//! ## The parts
27//!
28//! - [`parse`] is the state machine over the byte stream. It turns bytes into [`parse::Act`]s and
29//! holds whatever is incomplete between calls.
30//! - [`charset`] is the DEC special graphics set and the machinery that puts it in front of the
31//! printable ASCII range, which is how a curses programme draws a line.
32//! - [`screen`] is the grid, the cursor, the scrolling region, the tab stops, the scrollback and
33//! the rewrapping a resize does.
34//! - [`cell`] is what one cell holds: a character, a pen and whether it is half of a wide one.
35//! - [`width`] answers how many cells a character occupies.
36//! - [`emu`] joins the parser to the screen and is what a caller holds.
37//!
38//! ## What a renderer reads
39//!
40//! [`Terminal::screen`] gives the grid. [`Terminal::damage`] gives the rows that changed since the
41//! renderer last called [`Terminal::clear_damage`], so that a screenful of output does not cost a
42//! screenful of drawing. [`cell::runs`] splits a row into runs of constant pen, which is the unit
43//! most renderers emit most cheaply.
44//!
45//! ## What a caller must not forget
46//!
47//! [`Terminal::take_replies`] returns bytes the application asked for and must be written back to
48//! the pseudoterminal. An application that asks where the cursor is and never hears back will wait.
49//!
50//! ## Where the Unicode width data belongs
51//!
52//! [`width`] carries a condensed copy of the East Asian width property. The generator behind
53//! `oxedyne_fe2o3_text::unicode` already downloads `EastAsianWidth.txt` in order to build the line
54//! breaking table, so that crate is the better long term home for the data and this module should
55//! defer to it once it exposes a width function.
56
57pub mod cell;
58pub mod charset;
59pub mod emu;
60pub mod parse;
61pub mod screen;
62pub mod width;
63
64pub use cell::{
65 runs,
66 Attrs,
67 Cell,
68 NamedColour,
69 Pen,
70 Run,
71 TermColour,
72 Wide,
73};
74pub use charset::{
75 Charset,
76 Charsets,
77};
78pub use emu::{
79 Modes,
80 Terminal,
81};
82pub use parse::{
83 Act,
84 Parser,
85};
86pub use screen::{
87 Cursor,
88 Damage,
89 Erase,
90 Line,
91 Screen,
92 Surface,
93};
94pub use width::{
95 char_width,
96 str_width,
97 CharWidth,
98};