tattoy_wezterm_term/
lib.rs

1//! This crate provides the core of the virtual terminal emulator implementation
2//! used by [wezterm](https://wezterm.org/).  The home for this
3//! crate is in the wezterm repo and development is tracked at
4//! <https://github.com/wezterm/wezterm/>.
5//!
6//! It is full featured, providing terminal escape sequence parsing, keyboard
7//! and mouse input encoding, a model for the screen cells including scrollback,
8//! sixel and iTerm2 image support, OSC 8 Hyperlinks and a wide range of
9//! terminal cell attributes.
10//!
11//! This crate does not provide any kind of gui, nor does it directly
12//! manage a PTY; you provide a `std::io::Write` implementation that
13//! could connect to a PTY, and supply bytes to the model via the
14//! `advance_bytes` method.
15//!
16//! The entrypoint to the crate is the [Terminal](terminal/struct.Terminal.html)
17//! struct.
18use anyhow::Error;
19#[cfg(feature = "use_serde")]
20use serde::{Deserialize, Serialize};
21use std::ops::{Deref, DerefMut, Range};
22use std::str;
23use wezterm_dynamic::{FromDynamic, ToDynamic};
24use wezterm_surface::SequenceNo;
25
26pub mod config;
27pub use config::TerminalConfiguration;
28
29pub mod input;
30pub use crate::input::*;
31
32pub use wezterm_cell::*;
33pub use wezterm_surface::line::*;
34
35pub mod screen;
36pub use crate::screen::*;
37
38pub mod terminal;
39pub use crate::terminal::*;
40
41pub mod terminalstate;
42pub use crate::terminalstate::*;
43
44/// Represents the index into screen.lines.  Index 0 is the top of
45/// the scrollback (if any).  The index of the top of the visible screen
46/// depends on the terminal dimensions and the scrollback size.
47pub type PhysRowIndex = usize;
48
49/// Represents an index into the visible portion of the screen.
50/// Value 0 is the first visible row.  `VisibleRowIndex` needs to be
51/// resolved into a `PhysRowIndex` to obtain an actual row.  It is not
52/// valid to have a negative `VisibleRowIndex` value so this type logically
53/// should be unsigned, however, having a different sign is helpful to
54/// have the compiler catch accidental arithmetic performed between
55/// `PhysRowIndex` and `VisibleRowIndex`.  We could define our own type with
56/// its own `Add` and `Sub` operators, but then we'd not be able to iterate
57/// over `Ranges` of these types without also laboriously implementing an
58/// iterator `Skip` trait that is currently only in unstable rust.
59pub type VisibleRowIndex = i64;
60
61/// Like `VisibleRowIndex` above, but can index backwards into scrollback.
62/// This is deliberately a differently sized signed type to catch
63/// accidentally blending together the wrong types of indices.
64/// This is explicitly 32-bit rather than 64-bit as it seems unreasonable
65/// to want to scroll back or select more than ~2billion lines of scrollback.
66pub type ScrollbackOrVisibleRowIndex = i32;
67
68/// Allows referencing a logical line in the scrollback, allowing for scrolling.
69/// The StableRowIndex counts from the top of the scrollback, growing larger
70/// as you move down through the display rows.
71/// Initially the very first line as StableRowIndex==0.  If the scrollback
72/// is filled and lines are purged (say we need to purge 5 lines), then whichever
73/// line is first in the scrollback (PhysRowIndex==0) will now have StableRowIndex==5
74/// which is the same value that that logical line had prior to data being purged
75/// out of the scrollback.
76///
77/// As per ScrollbackOrVisibleRowIndex above, a StableRowIndex can never
78/// legally be a negative number.  We're just using a differently sized type
79/// to have the compiler assist us in detecting improper usage.
80pub type StableRowIndex = isize;
81
82/// Returns true if r1 intersects r2
83pub fn intersects_range<T: Ord + Copy>(r1: Range<T>, r2: Range<T>) -> bool {
84    use std::cmp::{max, min};
85    let start = max(r1.start, r2.start);
86    let end = min(r1.end, r2.end);
87
88    end > start
89}
90
91/// Position allows referring to an absolute visible row number
92/// or a position relative to some existing row number (typically
93/// where the cursor is located).  Both of the cases are represented
94/// as signed numbers so that the math and error checking for out
95/// of range values can be deferred to the point where we execute
96/// the request.
97#[derive(Debug)]
98pub enum Position {
99    Absolute(VisibleRowIndex),
100    Relative(i64),
101}
102
103/// Describes the location of the cursor in the visible portion
104/// of the screen.
105#[cfg_attr(feature = "use_serde", derive(Deserialize, Serialize))]
106#[derive(Debug, Default, Copy, Clone, Eq, PartialEq)]
107pub struct CursorPosition {
108    pub x: usize,
109    pub y: VisibleRowIndex,
110    pub shape: wezterm_surface::CursorShape,
111    pub visibility: wezterm_surface::CursorVisibility,
112    pub seqno: SequenceNo,
113}
114
115#[cfg_attr(feature = "use_serde", derive(Deserialize, Serialize))]
116#[derive(Debug, Clone, Copy, Eq, PartialEq, PartialOrd, Ord, FromDynamic, ToDynamic)]
117pub struct SemanticZone {
118    pub start_y: StableRowIndex,
119    pub start_x: usize,
120    pub end_y: StableRowIndex,
121    pub end_x: usize,
122    pub semantic_type: SemanticType,
123}
124
125pub mod color;
126
127#[cfg(test)]
128mod test;
129
130pub const CSI: &str = "\x1b[";
131pub const OSC: &str = "\x1b]";
132pub const ST: &str = "\x1b\\";
133pub const SS3: &str = "\x1bO";
134pub const DCS: &str = "\x1bP";
tattoy_wezterm_term/lib.rs

tattoy_wezterm_term/
lib.rs
