///|
/// The terminal's size in columns and rows.
pub struct Size {
width : Int32
height : Int32
} derive(Eq, Debug)
///|
/// A full-screen terminal session.
///
/// A `Terminal` exists only inside `with_terminal`. Draw complete frames to it
/// with `draw` and read what the user did with `read_event`.
struct Terminal {
tty : @tty.Tty
mut size : Size
// The frame currently on screen, or `None` when the screen content is
// unknown (before the first draw and after a resize).
mut shown : Frame?
// The program `set_clipboard` also hands the text to, found once when the
// session starts.
clipboard : ClipboardCommand?
}
///|
/// Run `f` with the terminal in full-screen mode, and restore it afterwards
/// whether `f` returns, raises, or is cancelled.
///
/// Opens the controlling terminal, switches to raw mode and the alternate
/// screen, requests the kitty keyboard "disambiguate" level, and enables
/// bracketed paste. Raises if the process has no terminal.
///
/// With `mouse`, clicks, drags, and the scroll wheel arrive as `Mouse` events
/// from `read_event`. The terminal then stops handling the mouse itself, so
/// its own text selection no longer works while the session runs; use a
/// `Selection` to provide one.
pub async fn[T] with_terminal(
mouse~ : Bool = false,
f : async (Terminal) -> T,
) -> T {
let clipboard = find_clipboard_command(@env.get_env_var, path => {
@fs.exists(path) catch {
_ => false
}
})
let tty = @tty.Tty::open()
defer tty.close()
let window = tty.window_size()
let terminal = Terminal::{
tty,
size: { width: window.cols, height: window.rows, },
shown: None,
clipboard,
}
let keyboard = @tty.KeyboardEnhancementFlags::disambiguate()
tty.with_raw_mode(() => {
tty.with_alt_screen(() => {
tty.with_keyboard_enhancements(keyboard, () => {
tty.with_bracketed_paste(() => {
tty.hide_cursor()
defer @async.protect_from_cancel(() => {
tty.execute([ResetStyle, ShowCursor])
})
if mouse {
tty.with_mouse(Drag, () => f(terminal))
} else {
f(terminal)
}
})
})
})
})
}
///|
/// The terminal's current size. It changes when `read_event` returns a
/// `Resize` event.
pub fn Terminal::size(self : Terminal) -> Size {
self.size
}
///|
/// Make the screen show `frame`.
///
/// Only the cells that differ from the frame already on screen are sent to the
/// terminal, in one write. A frame larger than the terminal is clipped. `frame`
/// is copied, so it can be reused or dropped after the call.
pub async fn Terminal::draw(self : Terminal, frame : Frame) -> Unit {
let frame = frame.clipped(width=self.size.width, height=self.size.height)
let commands = diff(self.shown, frame)
self.shown = Some(frame)
if commands.is_empty() {
return
}
self.tty.execute([BeginSynchronizedUpdate, ..commands, EndSynchronizedUpdate])
}
///|
/// Wait for the next terminal event: a key, a paste, a resize, or, when the
/// session was started with `mouse`, a mouse action.
///
/// After a `Resize` event `size` reports the new size, and the next `draw`
/// repaints the whole screen.
///
/// A lone Escape byte could be the Escape key or the start of a longer key
/// sequence; `esc_timeout_ms` is how long to wait for the rest before deciding
/// it was the key.
pub async fn Terminal::read_event(
self : Terminal,
esc_timeout_ms~ : Int32 = 50,
) -> @tty.Event {
let event = self.tty.read_event(esc_timeout_ms~)
if event is Resize(window) {
self.size = { width: window.cols, height: window.rows, }
self.shown = None
}
event
}
///|
/// Put `text` on the system clipboard, replacing what was there.
///
/// This asks the terminal to do it (OSC 52), which also works over SSH. Not
/// every terminal supports the request, so when the program runs on the
/// user's own machine the text is also handed to the system's clipboard
/// program: `pbcopy` on macOS, `wl-copy`, `xclip`, or `xsel` on Linux. Over
/// SSH only the terminal can reach the user's clipboard.
///
/// There is no way to tell whether it worked: a terminal that does not
/// support the request ignores it, and a failing clipboard program is
/// ignored too. Waits for the clipboard program, at most two seconds.
pub async fn Terminal::set_clipboard(
self : Terminal,
text : StringView,
) -> Unit {
self.tty.set_clipboard(text)
if self.clipboard is Some(command) {
command.copy(text)
}
}