Struct Session 

pub struct Session<M = ()> { /* private fields */ }

A connection to a terminal that speaks TSP. Dropping it closes it (surfaces, modes, tty).

Implementations

impl<M> Session<M>

pub fn connect(options: Options) -> Result<Option<Self>, Error>

Connects to the process’s terminal (Unix and Windows only): Ok(None) when TSP isn’t available (TERN_TSP=0, stdin or stdout not a tty, inside screen or zellij, inside tmux unless Tern draws its session, or the terminal answers DA1 first or not in time). Inside tmux it sends hello without DA1 (tmux answers DA1 itself) and turns the pane’s allow-set-title off until the session ends.

Errors

When the tty can’t be switched to raw mode or I/O fails.

Examples found in repository

examples/progress.rs (line 102)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new())? else {
		for (i, step) in STEPS.iter().enumerate() {
			println!("[{}/{}] {step}", i + 1, STEPS.len());
			std::thread::sleep(STEP);
		}
		println!("Built demo.");
		return Ok(());
	};
	let start = Instant::now();
	let sf = session.open(SurfaceOptions::flow().title("progress"))?;
	let mut build =
		Build { log: String::new(), done: 0, took: None, status: Status::Running };
	session.render(sf, view(&build))?;
	for step in STEPS {
		if wait(&mut session, STEP)? {
			build.status = Status::Cancelled;
			break;
		}
		build.log.push_str("\x1b[32m✓\x1b[0m ");
		build.log.push_str(step);
		build.log.push_str("\r\n");
		build.done += 1;
		session.render(sf, view(&build))?;
	}
	if build.status == Status::Running {
		build.status = Status::Done;
	}
	let took = start.elapsed();
	build.took = Some(took.as_millis() as u64);
	session.render(sf, view(&build))?;
	session.close()?;
	match build.status {
		Status::Done => println!("Built demo in {:.1}s.", took.as_secs_f64()),
		_ => println!("Build cancelled."),
	}
	Ok(())
}

examples/dashboard.rs (line 1123)

fn main() -> Result<(), tern_sdk::Error> {
	let mut dash = Dash::new();
	let Some(mut session) = Session::connect(Options::new().app("dashboard"))? else {
		print!("{}", dash.view(true).plain(100));
		return Ok(());
	};
	let sf = session.open(SurfaceOptions::screen().title("Fleet").font(Font::Sans))?;
	session.render(sf, dash.view(false))?;
	let mut next = Instant::now() + TICK;
	loop {
		let left = next.saturating_duration_since(Instant::now());
		match session.next(Some(left))? {
			None => {
				dash.tick();
				next = Instant::now() + TICK;
			},
			Some(Input::Msg(msg, _)) => dash.update(msg),
			Some(Input::Key(key)) => {
				if key.is("escape") && dash.confirming.is_some() {
					dash.update(Msg::Keep);
				} else if key.is("enter") && dash.confirming.is_some() {
					dash.update(Msg::Confirm);
				} else if key.is("escape") || key.is("q") || key.is("ctrl+c") {
					break;
				} else if key.is("tab") || key.is("]") {
					dash.page = dash.page.turn(false);
				} else if key.is("shift+tab") || key.is("[") {
					dash.page = dash.page.turn(true);
				} else if key.is("up") || key.is("k") {
					dash.pick(dash.page, -1);
				} else if key.is("down") || key.is("j") {
					dash.pick(dash.page, 1);
				} else if key.is("r") {
					dash.update(Msg::Refresh);
				} else if key.is("a") {
					dash.act_selected();
				} else if key.is("enter") {
					if let Some(id) = dash.selected[dash.page.index()] {
						dash.update(Msg::Open(dash.page, id.into()));
					}
				} else {
					continue;
				}
			},
			Some(Input::Event(_) | Input::Clipboard(_)) => continue,
		}
		session.render(sf, dash.view(false))?;
	}
	session.close()?;
	Ok(())
}

examples/chat.rs (line 129)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new().feature(feature::SEND))? else {
		return plain();
	};
	let sf = session.open(SurfaceOptions::inline().title("chat"))?;
	let mut chat = Chat::default();
	session.render(sf, chat.view())?;
	session.focus(sf, Some(EDITOR))?;
	while let Some(input) = session.next(None)? {
		match input {
			Input::Key(key) => {
				if key.is("escape") || key.is("ctrl+c") || key.is("ctrl+d") {
					break;
				}
				match key.name.as_str() {
					"enter" if !key.shift && !key.alt => {
						let text = std::mem::take(&mut chat.draft);
						chat.cursor = 0;
						chat.send(text);
					},
					"enter" => chat.insert("\n"),
					"backspace" if chat.cursor > 0 => {
						let at = chat.byte(chat.cursor - 1);
						chat.draft.remove(at);
						chat.cursor -= 1;
					},
					"delete" if chat.cursor < chat.draft.chars().count() => {
						let at = chat.byte(chat.cursor);
						chat.draft.remove(at);
					},
					"left" => chat.cursor = chat.cursor.saturating_sub(1),
					"right" => chat.cursor = (chat.cursor + 1).min(chat.draft.chars().count()),
					"home" => chat.cursor = 0,
					"end" => chat.cursor = chat.draft.chars().count(),
					"paste" => chat.insert(key.text.as_deref().unwrap_or_default()),
					_ => match key.typed() {
						Some(text) => chat.insert(text),
						None => continue,
					},
				}
			},
			Input::Msg(Msg::Send(text), _) => chat.send(text),
			Input::Msg(Msg::Focus, _) => session.focus(sf, Some(EDITOR))?,
			Input::Event(_) | Input::Clipboard(_) => continue,
		}
		session.render(sf, chat.view())?;
	}
	session.close()?;
	println!("Chat closed after {} messages.", chat.transcript.len());
	Ok(())
}

pub fn with_terminal( term: impl Terminal + 'static, options: Options, ) -> Result<Option<Self>, Error>

Runs the handshake over term (already in raw mode): writes hello and a DA1 request and waits for the reply. Ok(None), with the terminal restored, when DA1 answers first or nothing answers in time.

Errors

When I/O fails or the recording can’t be opened.

pub const fn caps(&self) -> &Capabilities

What the terminal supports.

pub fn open(&mut self, options: SurfaceOptions) -> Result<Surface, Error>

Opens a surface.

Errors

When writing fails.

Examples found in repository

examples/progress.rs (line 111)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new())? else {
		for (i, step) in STEPS.iter().enumerate() {
			println!("[{}/{}] {step}", i + 1, STEPS.len());
			std::thread::sleep(STEP);
		}
		println!("Built demo.");
		return Ok(());
	};
	let start = Instant::now();
	let sf = session.open(SurfaceOptions::flow().title("progress"))?;
	let mut build =
		Build { log: String::new(), done: 0, took: None, status: Status::Running };
	session.render(sf, view(&build))?;
	for step in STEPS {
		if wait(&mut session, STEP)? {
			build.status = Status::Cancelled;
			break;
		}
		build.log.push_str("\x1b[32m✓\x1b[0m ");
		build.log.push_str(step);
		build.log.push_str("\r\n");
		build.done += 1;
		session.render(sf, view(&build))?;
	}
	if build.status == Status::Running {
		build.status = Status::Done;
	}
	let took = start.elapsed();
	build.took = Some(took.as_millis() as u64);
	session.render(sf, view(&build))?;
	session.close()?;
	match build.status {
		Status::Done => println!("Built demo in {:.1}s.", took.as_secs_f64()),
		_ => println!("Build cancelled."),
	}
	Ok(())
}

examples/dashboard.rs (line 1127)

fn main() -> Result<(), tern_sdk::Error> {
	let mut dash = Dash::new();
	let Some(mut session) = Session::connect(Options::new().app("dashboard"))? else {
		print!("{}", dash.view(true).plain(100));
		return Ok(());
	};
	let sf = session.open(SurfaceOptions::screen().title("Fleet").font(Font::Sans))?;
	session.render(sf, dash.view(false))?;
	let mut next = Instant::now() + TICK;
	loop {
		let left = next.saturating_duration_since(Instant::now());
		match session.next(Some(left))? {
			None => {
				dash.tick();
				next = Instant::now() + TICK;
			},
			Some(Input::Msg(msg, _)) => dash.update(msg),
			Some(Input::Key(key)) => {
				if key.is("escape") && dash.confirming.is_some() {
					dash.update(Msg::Keep);
				} else if key.is("enter") && dash.confirming.is_some() {
					dash.update(Msg::Confirm);
				} else if key.is("escape") || key.is("q") || key.is("ctrl+c") {
					break;
				} else if key.is("tab") || key.is("]") {
					dash.page = dash.page.turn(false);
				} else if key.is("shift+tab") || key.is("[") {
					dash.page = dash.page.turn(true);
				} else if key.is("up") || key.is("k") {
					dash.pick(dash.page, -1);
				} else if key.is("down") || key.is("j") {
					dash.pick(dash.page, 1);
				} else if key.is("r") {
					dash.update(Msg::Refresh);
				} else if key.is("a") {
					dash.act_selected();
				} else if key.is("enter") {
					if let Some(id) = dash.selected[dash.page.index()] {
						dash.update(Msg::Open(dash.page, id.into()));
					}
				} else {
					continue;
				}
			},
			Some(Input::Event(_) | Input::Clipboard(_)) => continue,
		}
		session.render(sf, dash.view(false))?;
	}
	session.close()?;
	Ok(())
}

examples/chat.rs (line 132)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new().feature(feature::SEND))? else {
		return plain();
	};
	let sf = session.open(SurfaceOptions::inline().title("chat"))?;
	let mut chat = Chat::default();
	session.render(sf, chat.view())?;
	session.focus(sf, Some(EDITOR))?;
	while let Some(input) = session.next(None)? {
		match input {
			Input::Key(key) => {
				if key.is("escape") || key.is("ctrl+c") || key.is("ctrl+d") {
					break;
				}
				match key.name.as_str() {
					"enter" if !key.shift && !key.alt => {
						let text = std::mem::take(&mut chat.draft);
						chat.cursor = 0;
						chat.send(text);
					},
					"enter" => chat.insert("\n"),
					"backspace" if chat.cursor > 0 => {
						let at = chat.byte(chat.cursor - 1);
						chat.draft.remove(at);
						chat.cursor -= 1;
					},
					"delete" if chat.cursor < chat.draft.chars().count() => {
						let at = chat.byte(chat.cursor);
						chat.draft.remove(at);
					},
					"left" => chat.cursor = chat.cursor.saturating_sub(1),
					"right" => chat.cursor = (chat.cursor + 1).min(chat.draft.chars().count()),
					"home" => chat.cursor = 0,
					"end" => chat.cursor = chat.draft.chars().count(),
					"paste" => chat.insert(key.text.as_deref().unwrap_or_default()),
					_ => match key.typed() {
						Some(text) => chat.insert(text),
						None => continue,
					},
				}
			},
			Input::Msg(Msg::Send(text), _) => chat.send(text),
			Input::Msg(Msg::Focus, _) => session.focus(sf, Some(EDITOR))?,
			Input::Event(_) | Input::Clipboard(_) => continue,
		}
		session.render(sf, chat.view())?;
	}
	session.close()?;
	println!("Chat closed after {} messages.", chat.transcript.len());
	Ok(())
}

pub fn surface_id(&self, sf: Surface) -> &str

The id of sf.

Panics

When sf comes from another session.

pub fn is_open(&self, sf: Surface) -> bool

Whether sf is still open (not closed, and not gone).

Panics

When sf comes from another session.

pub fn render( &mut self, sf: Surface, view: impl Into<View<M>>, ) -> Result<(), Error>

Renders view on sf: sends the difference from the last view sent, or, while out of credits, stores it for the frame an ack releases. Its handlers replace the last view’s. A bare node or list is main’s children.

Errors

Error::DuplicateId (nothing is sent), a closed surface, or I/O.

Examples found in repository

examples/progress.rs (line 114)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new())? else {
		for (i, step) in STEPS.iter().enumerate() {
			println!("[{}/{}] {step}", i + 1, STEPS.len());
			std::thread::sleep(STEP);
		}
		println!("Built demo.");
		return Ok(());
	};
	let start = Instant::now();
	let sf = session.open(SurfaceOptions::flow().title("progress"))?;
	let mut build =
		Build { log: String::new(), done: 0, took: None, status: Status::Running };
	session.render(sf, view(&build))?;
	for step in STEPS {
		if wait(&mut session, STEP)? {
			build.status = Status::Cancelled;
			break;
		}
		build.log.push_str("\x1b[32m✓\x1b[0m ");
		build.log.push_str(step);
		build.log.push_str("\r\n");
		build.done += 1;
		session.render(sf, view(&build))?;
	}
	if build.status == Status::Running {
		build.status = Status::Done;
	}
	let took = start.elapsed();
	build.took = Some(took.as_millis() as u64);
	session.render(sf, view(&build))?;
	session.close()?;
	match build.status {
		Status::Done => println!("Built demo in {:.1}s.", took.as_secs_f64()),
		_ => println!("Build cancelled."),
	}
	Ok(())
}

examples/dashboard.rs (line 1128)

fn main() -> Result<(), tern_sdk::Error> {
	let mut dash = Dash::new();
	let Some(mut session) = Session::connect(Options::new().app("dashboard"))? else {
		print!("{}", dash.view(true).plain(100));
		return Ok(());
	};
	let sf = session.open(SurfaceOptions::screen().title("Fleet").font(Font::Sans))?;
	session.render(sf, dash.view(false))?;
	let mut next = Instant::now() + TICK;
	loop {
		let left = next.saturating_duration_since(Instant::now());
		match session.next(Some(left))? {
			None => {
				dash.tick();
				next = Instant::now() + TICK;
			},
			Some(Input::Msg(msg, _)) => dash.update(msg),
			Some(Input::Key(key)) => {
				if key.is("escape") && dash.confirming.is_some() {
					dash.update(Msg::Keep);
				} else if key.is("enter") && dash.confirming.is_some() {
					dash.update(Msg::Confirm);
				} else if key.is("escape") || key.is("q") || key.is("ctrl+c") {
					break;
				} else if key.is("tab") || key.is("]") {
					dash.page = dash.page.turn(false);
				} else if key.is("shift+tab") || key.is("[") {
					dash.page = dash.page.turn(true);
				} else if key.is("up") || key.is("k") {
					dash.pick(dash.page, -1);
				} else if key.is("down") || key.is("j") {
					dash.pick(dash.page, 1);
				} else if key.is("r") {
					dash.update(Msg::Refresh);
				} else if key.is("a") {
					dash.act_selected();
				} else if key.is("enter") {
					if let Some(id) = dash.selected[dash.page.index()] {
						dash.update(Msg::Open(dash.page, id.into()));
					}
				} else {
					continue;
				}
			},
			Some(Input::Event(_) | Input::Clipboard(_)) => continue,
		}
		session.render(sf, dash.view(false))?;
	}
	session.close()?;
	Ok(())
}

examples/chat.rs (line 134)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new().feature(feature::SEND))? else {
		return plain();
	};
	let sf = session.open(SurfaceOptions::inline().title("chat"))?;
	let mut chat = Chat::default();
	session.render(sf, chat.view())?;
	session.focus(sf, Some(EDITOR))?;
	while let Some(input) = session.next(None)? {
		match input {
			Input::Key(key) => {
				if key.is("escape") || key.is("ctrl+c") || key.is("ctrl+d") {
					break;
				}
				match key.name.as_str() {
					"enter" if !key.shift && !key.alt => {
						let text = std::mem::take(&mut chat.draft);
						chat.cursor = 0;
						chat.send(text);
					},
					"enter" => chat.insert("\n"),
					"backspace" if chat.cursor > 0 => {
						let at = chat.byte(chat.cursor - 1);
						chat.draft.remove(at);
						chat.cursor -= 1;
					},
					"delete" if chat.cursor < chat.draft.chars().count() => {
						let at = chat.byte(chat.cursor);
						chat.draft.remove(at);
					},
					"left" => chat.cursor = chat.cursor.saturating_sub(1),
					"right" => chat.cursor = (chat.cursor + 1).min(chat.draft.chars().count()),
					"home" => chat.cursor = 0,
					"end" => chat.cursor = chat.draft.chars().count(),
					"paste" => chat.insert(key.text.as_deref().unwrap_or_default()),
					_ => match key.typed() {
						Some(text) => chat.insert(text),
						None => continue,
					},
				}
			},
			Input::Msg(Msg::Send(text), _) => chat.send(text),
			Input::Msg(Msg::Focus, _) => session.focus(sf, Some(EDITOR))?,
			Input::Event(_) | Input::Clipboard(_) => continue,
		}
		session.render(sf, chat.view())?;
	}
	session.close()?;
	println!("Chat closed after {} messages.", chat.transcript.len());
	Ok(())
}

pub fn send(&mut self, sf: Surface, ops: Vec<Op>) -> Result<(), Error>

Sends ops on sf in one frame, after anything waiting, or queues them while out of credits (the raw escape hatch).

Errors

A closed surface, or I/O.

pub fn focus(&mut self, sf: Surface, id: Option<&str>) -> Result<(), Error>

Moves the caret to field id, or nowhere.

Errors

As send.

Examples found in repository

examples/chat.rs (line 135)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new().feature(feature::SEND))? else {
		return plain();
	};
	let sf = session.open(SurfaceOptions::inline().title("chat"))?;
	let mut chat = Chat::default();
	session.render(sf, chat.view())?;
	session.focus(sf, Some(EDITOR))?;
	while let Some(input) = session.next(None)? {
		match input {
			Input::Key(key) => {
				if key.is("escape") || key.is("ctrl+c") || key.is("ctrl+d") {
					break;
				}
				match key.name.as_str() {
					"enter" if !key.shift && !key.alt => {
						let text = std::mem::take(&mut chat.draft);
						chat.cursor = 0;
						chat.send(text);
					},
					"enter" => chat.insert("\n"),
					"backspace" if chat.cursor > 0 => {
						let at = chat.byte(chat.cursor - 1);
						chat.draft.remove(at);
						chat.cursor -= 1;
					},
					"delete" if chat.cursor < chat.draft.chars().count() => {
						let at = chat.byte(chat.cursor);
						chat.draft.remove(at);
					},
					"left" => chat.cursor = chat.cursor.saturating_sub(1),
					"right" => chat.cursor = (chat.cursor + 1).min(chat.draft.chars().count()),
					"home" => chat.cursor = 0,
					"end" => chat.cursor = chat.draft.chars().count(),
					"paste" => chat.insert(key.text.as_deref().unwrap_or_default()),
					_ => match key.typed() {
						Some(text) => chat.insert(text),
						None => continue,
					},
				}
			},
			Input::Msg(Msg::Send(text), _) => chat.send(text),
			Input::Msg(Msg::Focus, _) => session.focus(sf, Some(EDITOR))?,
			Input::Event(_) | Input::Clipboard(_) => continue,
		}
		session.render(sf, chat.view())?;
	}
	session.close()?;
	println!("Chat closed after {} messages.", chat.transcript.len());
	Ok(())
}

pub fn reveal( &mut self, sf: Surface, id: &str, at: RevealAt, ) -> Result<(), Error>

Scrolls node id into view.

Errors

As send.

pub fn scroll( &mut self, sf: Surface, id: &str, by: ScrollBy, ) -> Result<(), Error>

Scrolls the container around node id.

Errors

As send.

pub fn settle(&mut self, sf: Surface, id: &str) -> Result<(), Error>

Hints that node id won’t change soon.

Errors

As send.

pub fn suspend(&mut self, sf: Surface) -> Result<(), Error>

Hands the pane back to the grid.

Errors

As send.

pub fn resume(&mut self, sf: Surface) -> Result<(), Error>

Takes the pane again after suspend.

Errors

As send.

pub fn stylesheet( &mut self, sf: Surface, name: &str, css: Option<&str>, ) -> Result<(), Error>

Installs or replaces stylesheet name of sf; None removes it.

Errors

A closed surface, or I/O.

pub fn close_surface(&mut self, sf: Surface, keep: bool) -> Result<(), Error>

Closes sf: sends what still waits (credits or not), then x.

Errors

A closed surface, or I/O.

pub fn blob( &mut self, data: Vec<u8>, mime: Option<&str>, ) -> Result<String, Error>

Sends a blob once per session and returns its id.

Errors

Error::BlobTooLarge over 16 MiB, or I/O.

pub fn blobs(&mut self, ids: Vec<String>) -> Result<Vec<String>, Error>

Asks which of ids Tern still holds. Input arriving meanwhile waits for next.

Errors

Error::Timeout without a reply in 2 s, or I/O.

pub fn waker(&self) -> Option<Waker>

The terminal’s waker: Waker::wake from any thread makes the current or next next return Ok(None). None when the terminal has no waker.

pub fn write_raw(&mut self, bytes: &[u8]) -> Result<(), Error>

Writes bytes to the terminal as they are (OSC sequences, mode switches), outside any surface.

Errors

When the output fails.

pub fn next( &mut self, timeout: Option<Duration>, ) -> Result<Option<Input<M>>, Error>

Waits up to timeout (None: until something arrives) for the next key, unhandled event, handler message, or clipboard packet. Ok(None): the timeout passed or the waker was woken.

Errors

Error::InputClosed at the end of input, or I/O.

Examples found in repository

examples/progress.rs (line 93)

fn wait(session: &mut Session, time: Duration) -> Result<bool, tern_sdk::Error> {
	let until = Instant::now() + time;
	loop {
		let left = until.saturating_duration_since(Instant::now());
		match session.next(Some(left))? {
			None => return Ok(false),
			Some(Input::Key(key)) if key.is("ctrl+c") => return Ok(true),
			Some(_) => {},
		}
	}
}

examples/dashboard.rs (line 1132)

fn main() -> Result<(), tern_sdk::Error> {
	let mut dash = Dash::new();
	let Some(mut session) = Session::connect(Options::new().app("dashboard"))? else {
		print!("{}", dash.view(true).plain(100));
		return Ok(());
	};
	let sf = session.open(SurfaceOptions::screen().title("Fleet").font(Font::Sans))?;
	session.render(sf, dash.view(false))?;
	let mut next = Instant::now() + TICK;
	loop {
		let left = next.saturating_duration_since(Instant::now());
		match session.next(Some(left))? {
			None => {
				dash.tick();
				next = Instant::now() + TICK;
			},
			Some(Input::Msg(msg, _)) => dash.update(msg),
			Some(Input::Key(key)) => {
				if key.is("escape") && dash.confirming.is_some() {
					dash.update(Msg::Keep);
				} else if key.is("enter") && dash.confirming.is_some() {
					dash.update(Msg::Confirm);
				} else if key.is("escape") || key.is("q") || key.is("ctrl+c") {
					break;
				} else if key.is("tab") || key.is("]") {
					dash.page = dash.page.turn(false);
				} else if key.is("shift+tab") || key.is("[") {
					dash.page = dash.page.turn(true);
				} else if key.is("up") || key.is("k") {
					dash.pick(dash.page, -1);
				} else if key.is("down") || key.is("j") {
					dash.pick(dash.page, 1);
				} else if key.is("r") {
					dash.update(Msg::Refresh);
				} else if key.is("a") {
					dash.act_selected();
				} else if key.is("enter") {
					if let Some(id) = dash.selected[dash.page.index()] {
						dash.update(Msg::Open(dash.page, id.into()));
					}
				} else {
					continue;
				}
			},
			Some(Input::Event(_) | Input::Clipboard(_)) => continue,
		}
		session.render(sf, dash.view(false))?;
	}
	session.close()?;
	Ok(())
}

examples/chat.rs (line 136)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new().feature(feature::SEND))? else {
		return plain();
	};
	let sf = session.open(SurfaceOptions::inline().title("chat"))?;
	let mut chat = Chat::default();
	session.render(sf, chat.view())?;
	session.focus(sf, Some(EDITOR))?;
	while let Some(input) = session.next(None)? {
		match input {
			Input::Key(key) => {
				if key.is("escape") || key.is("ctrl+c") || key.is("ctrl+d") {
					break;
				}
				match key.name.as_str() {
					"enter" if !key.shift && !key.alt => {
						let text = std::mem::take(&mut chat.draft);
						chat.cursor = 0;
						chat.send(text);
					},
					"enter" => chat.insert("\n"),
					"backspace" if chat.cursor > 0 => {
						let at = chat.byte(chat.cursor - 1);
						chat.draft.remove(at);
						chat.cursor -= 1;
					},
					"delete" if chat.cursor < chat.draft.chars().count() => {
						let at = chat.byte(chat.cursor);
						chat.draft.remove(at);
					},
					"left" => chat.cursor = chat.cursor.saturating_sub(1),
					"right" => chat.cursor = (chat.cursor + 1).min(chat.draft.chars().count()),
					"home" => chat.cursor = 0,
					"end" => chat.cursor = chat.draft.chars().count(),
					"paste" => chat.insert(key.text.as_deref().unwrap_or_default()),
					_ => match key.typed() {
						Some(text) => chat.insert(text),
						None => continue,
					},
				}
			},
			Input::Msg(Msg::Send(text), _) => chat.send(text),
			Input::Msg(Msg::Focus, _) => session.focus(sf, Some(EDITOR))?,
			Input::Event(_) | Input::Clipboard(_) => continue,
		}
		session.render(sf, chat.view())?;
	}
	session.close()?;
	println!("Chat closed after {} messages.", chat.transcript.len());
	Ok(())
}

pub fn pump(&mut self, timeout: Duration) -> Result<(), Error>

Processes input for up to timeout without returning it: acks release waiting frames; keys and events wait for next.

Errors

Error::InputClosed at the end of input, or I/O.

pub fn close(self) -> Result<(), Error>

Closes the session: open surfaces (each as its options say), the input modes, a short drain of late input, and the tty.

Errors

The first I/O error; every step still runs.

Examples found in repository

examples/progress.rs (line 132)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new())? else {
		for (i, step) in STEPS.iter().enumerate() {
			println!("[{}/{}] {step}", i + 1, STEPS.len());
			std::thread::sleep(STEP);
		}
		println!("Built demo.");
		return Ok(());
	};
	let start = Instant::now();
	let sf = session.open(SurfaceOptions::flow().title("progress"))?;
	let mut build =
		Build { log: String::new(), done: 0, took: None, status: Status::Running };
	session.render(sf, view(&build))?;
	for step in STEPS {
		if wait(&mut session, STEP)? {
			build.status = Status::Cancelled;
			break;
		}
		build.log.push_str("\x1b[32m✓\x1b[0m ");
		build.log.push_str(step);
		build.log.push_str("\r\n");
		build.done += 1;
		session.render(sf, view(&build))?;
	}
	if build.status == Status::Running {
		build.status = Status::Done;
	}
	let took = start.elapsed();
	build.took = Some(took.as_millis() as u64);
	session.render(sf, view(&build))?;
	session.close()?;
	match build.status {
		Status::Done => println!("Built demo in {:.1}s.", took.as_secs_f64()),
		_ => println!("Build cancelled."),
	}
	Ok(())
}

examples/dashboard.rs (line 1169)

fn main() -> Result<(), tern_sdk::Error> {
	let mut dash = Dash::new();
	let Some(mut session) = Session::connect(Options::new().app("dashboard"))? else {
		print!("{}", dash.view(true).plain(100));
		return Ok(());
	};
	let sf = session.open(SurfaceOptions::screen().title("Fleet").font(Font::Sans))?;
	session.render(sf, dash.view(false))?;
	let mut next = Instant::now() + TICK;
	loop {
		let left = next.saturating_duration_since(Instant::now());
		match session.next(Some(left))? {
			None => {
				dash.tick();
				next = Instant::now() + TICK;
			},
			Some(Input::Msg(msg, _)) => dash.update(msg),
			Some(Input::Key(key)) => {
				if key.is("escape") && dash.confirming.is_some() {
					dash.update(Msg::Keep);
				} else if key.is("enter") && dash.confirming.is_some() {
					dash.update(Msg::Confirm);
				} else if key.is("escape") || key.is("q") || key.is("ctrl+c") {
					break;
				} else if key.is("tab") || key.is("]") {
					dash.page = dash.page.turn(false);
				} else if key.is("shift+tab") || key.is("[") {
					dash.page = dash.page.turn(true);
				} else if key.is("up") || key.is("k") {
					dash.pick(dash.page, -1);
				} else if key.is("down") || key.is("j") {
					dash.pick(dash.page, 1);
				} else if key.is("r") {
					dash.update(Msg::Refresh);
				} else if key.is("a") {
					dash.act_selected();
				} else if key.is("enter") {
					if let Some(id) = dash.selected[dash.page.index()] {
						dash.update(Msg::Open(dash.page, id.into()));
					}
				} else {
					continue;
				}
			},
			Some(Input::Event(_) | Input::Clipboard(_)) => continue,
		}
		session.render(sf, dash.view(false))?;
	}
	session.close()?;
	Ok(())
}

examples/chat.rs (line 175)

fn main() -> Result<(), tern_sdk::Error> {
	let Some(mut session) = Session::connect(Options::new().feature(feature::SEND))? else {
		return plain();
	};
	let sf = session.open(SurfaceOptions::inline().title("chat"))?;
	let mut chat = Chat::default();
	session.render(sf, chat.view())?;
	session.focus(sf, Some(EDITOR))?;
	while let Some(input) = session.next(None)? {
		match input {
			Input::Key(key) => {
				if key.is("escape") || key.is("ctrl+c") || key.is("ctrl+d") {
					break;
				}
				match key.name.as_str() {
					"enter" if !key.shift && !key.alt => {
						let text = std::mem::take(&mut chat.draft);
						chat.cursor = 0;
						chat.send(text);
					},
					"enter" => chat.insert("\n"),
					"backspace" if chat.cursor > 0 => {
						let at = chat.byte(chat.cursor - 1);
						chat.draft.remove(at);
						chat.cursor -= 1;
					},
					"delete" if chat.cursor < chat.draft.chars().count() => {
						let at = chat.byte(chat.cursor);
						chat.draft.remove(at);
					},
					"left" => chat.cursor = chat.cursor.saturating_sub(1),
					"right" => chat.cursor = (chat.cursor + 1).min(chat.draft.chars().count()),
					"home" => chat.cursor = 0,
					"end" => chat.cursor = chat.draft.chars().count(),
					"paste" => chat.insert(key.text.as_deref().unwrap_or_default()),
					_ => match key.typed() {
						Some(text) => chat.insert(text),
						None => continue,
					},
				}
			},
			Input::Msg(Msg::Send(text), _) => chat.send(text),
			Input::Msg(Msg::Focus, _) => session.focus(sf, Some(EDITOR))?,
			Input::Event(_) | Input::Clipboard(_) => continue,
		}
		session.render(sf, chat.view())?;
	}
	session.close()?;
	println!("Chat closed after {} messages.", chat.transcript.len());
	Ok(())
}

Trait Implementations

impl<M> Drop for Session<M>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.