Crate tattoy_wezterm_term 

This crate provides the core of the virtual terminal emulator implementation used by wezterm. The home for this crate is in the wezterm repo and development is tracked at https://github.com/wezterm/wezterm/.

It is full featured, providing terminal escape sequence parsing, keyboard and mouse input encoding, a model for the screen cells including scrollback, sixel and iTerm2 image support, OSC 8 Hyperlinks and a wide range of terminal cell attributes.

This crate does not provide any kind of gui, nor does it directly manage a PTY; you provide a std::io::Write implementation that could connect to a PTY, and supply bytes to the model via the advance_bytes method.

The entrypoint to the crate is the Terminal struct.

Re-exports

pub use config::TerminalConfiguration;

pub use crate::input::*;

pub use crate::screen::*;

pub use crate::terminal::*;

pub use crate::terminalstate::*;

Modules

color

Colors for attributes

config

image

Images. This module has some helpers for modeling terminal cells that are filled with image data. We’re targeting the iTerm image protocol initially, with sixel as an obvious follow up. Kitty has an extensive and complex graphics protocol whose docs are here: https://github.com/kovidgoyal/kitty/blob/master/docs/graphics-protocol.rst Both iTerm2 and Sixel appear to have semantics that allow replacing the contents of a single chararcter cell with image data, whereas the kitty protocol appears to track the images out of band as attachments with z-order.

input

screen

terminal

terminalstate

Structs

Cell

Models the contents of a cell on the terminal display

CellAttributes

Holds the attributes for a cell. Most style attributes are stored internally as part of a bitfield to reduce per-cell overhead. The setter methods return a mutable self reference so that they can be chained together.

CursorPosition

Describes the location of the cursor in the visible portion of the screen.

Hyperlink

Line

SemanticZone

UnicodeVersion

Enums

AttributeChange

Models a change in the attributes of a cell in a stream of changes. Each variant specifies one of the possible attributes; the corresponding value holds the new value to be used for that attribute.

Blink

Specify whether you want to slowly or rapidly annoy your users

CellRef

DoubleClickRange

Intensity

The Intensity of a cell describes its boldness. Most terminals implement Intensity::Bold by either using a bold font or by simply using an alternative color. Some terminals implement Intensity::Half as a dimmer color variant.

Position

Position allows referring to an absolute visible row number or a position relative to some existing row number (typically where the cursor is located). Both of the cases are represented as signed numbers so that the math and error checking for out of range values can be deferred to the point where we execute the request.

Presentation

SemanticType

Describes the semantic “type” of the cell. This categorizes cells into Output (from the actions the user is taking; this is the default if left unspecified), Input (that the user typed) and Prompt (effectively, “chrome” provided by the shell or application that the user is interacting with.

Underline

Specify just how underlined you want your Cell to be

VerticalAlign

Constants

CSI

DCS

LATEST_UNICODE_VERSION

OSC

SS3

ST

Functions

grapheme_column_width

Returns the number of cells visually occupied by a grapheme. The input string must be a single grapheme.

intersects_range

Returns true if r1 intersects r2

is_white_space_char

Returns true if the char c has the unicode White_Space property

is_white_space_grapheme

Returns true if the grapheme string g consists entirely of characters that have the unicode White_Space property.

unicode_column_width

Returns the number of cells visually occupied by a sequence of graphemes. Calls through to grapheme_column_width for each grapheme and sums up the length.

Type Aliases

PhysRowIndex

Represents the index into screen.lines. Index 0 is the top of the scrollback (if any). The index of the top of the visible screen depends on the terminal dimensions and the scrollback size.

ScrollbackOrVisibleRowIndex

Like VisibleRowIndex above, but can index backwards into scrollback. This is deliberately a differently sized signed type to catch accidentally blending together the wrong types of indices. This is explicitly 32-bit rather than 64-bit as it seems unreasonable to want to scroll back or select more than ~2billion lines of scrollback.

StableRowIndex

Allows referencing a logical line in the scrollback, allowing for scrolling. The StableRowIndex counts from the top of the scrollback, growing larger as you move down through the display rows. Initially the very first line as StableRowIndex==0. If the scrollback is filled and lines are purged (say we need to purge 5 lines), then whichever line is first in the scrollback (PhysRowIndex==0) will now have StableRowIndex==5 which is the same value that that logical line had prior to data being purged out of the scrollback.

VisibleRowIndex

Represents an index into the visible portion of the screen. Value 0 is the first visible row. VisibleRowIndex needs to be resolved into a PhysRowIndex to obtain an actual row. It is not valid to have a negative VisibleRowIndex value so this type logically should be unsigned, however, having a different sign is helpful to have the compiler catch accidental arithmetic performed between PhysRowIndex and VisibleRowIndex. We could define our own type with its own Add and Sub operators, but then we’d not be able to iterate over Ranges of these types without also laboriously implementing an iterator Skip trait that is currently only in unstable rust.