rich_embed/lib.rs
1//! Other programs and web pages inside an intuiTUIve app.
2//!
3//! - [`terminal`] runs any program in a pane of the app: a shell, `htop`,
4//! an editor, a terminal browser. Keys, the mouse, pastes and resizes go
5//! to the program; its screen is followed by rs-rich-record's VT
6//! emulator (vt100, with rich's character widths) and drawn in the pane,
7//! with scrollback; its exit is a signal and a callback.
8//! - [`web_view`] shows a web page in a pane, with an address bar, and
9//! back, forward, reload, the address and the loading state as signals.
10//!
11//! Each sits on a trait, as intuiTUIve's terminals sit on `Backend`: what
12//! runs behind it can be swapped for another implementation, including one
13//! the app writes itself.
14//!
15//! - [`PtyHost`] starts a program and carries its bytes and size.
16//! [`LocalPty`] runs one on this machine (a PTY on Unix, ConPTY on
17//! Windows); [`ReplayHost`] plays bytes back, for tests. An SSH session
18//! is a third, passed to [`terminal_with`].
19//! - [`WebEngine`] opens pages, takes input and hands back frames, of
20//! cells or of pixels. [`ProgramEngine`] (the default) runs a terminal
21//! browser (Carbonyl, Browsh, Chawan, w3m) in a pane; `ChromeEngine`
22//! (feature `chrome`) drives a headless Chrome or Chromium the user
23//! installed, over the DevTools protocol; `BrowshEngine` (feature
24//! `browsh`) reads pages as text from Browsh's HTTP server. Pixel frames
25//! are drawn as coloured half blocks.
26//!
27//! No browser ships with this crate, and none is downloaded: each is a
28//! program the user chooses and installs.
29//!
30//! ```no_run
31//! # extern crate rich_intuituive as intuituive;
32//! use intuituive::prelude::*;
33//! use rich_embed::{terminal, web_view_with, ProgramEngine};
34//!
35//! fn main() -> std::io::Result<()> {
36//! App::new(|| {
37//! let page = web_view_with(ProgramEngine::new("w3m"), "https://example.com");
38//! row([
39//! terminal("bash").on_exit(|_, cx| cx.quit()).node().panel("shell"),
40//! page.node().panel("web"),
41//! ])
42//! })
43//! .run()
44//! }
45//! ```
46//!
47//! The panes need a running app: like [`signal`](rich_intuituive::signal),
48//! [`terminal`] and [`web_view`] are called inside `App::new`'s closure or
49//! a node's.
50
51// A builder method that returns `Self` is `#[must_use]`: dropping its
52// result drops the value (CONTRIBUTING.md, "API conventions").
53#![warn(clippy::return_self_not_must_use)]
54
55#[cfg(feature = "browsh")]
56pub mod browsh;
57#[cfg(feature = "chrome")]
58pub mod chrome;
59mod host;
60pub mod keys;
61mod pane;
62mod pixels;
63mod program;
64mod term;
65mod wake;
66mod web;
67
68#[cfg(feature = "browsh")]
69pub use browsh::BrowshEngine;
70#[cfg(feature = "chrome")]
71pub use chrome::{ChromeEngine, DevTools, DevToolsEvent, Downloads, FrameMeta, ScreencastFrame};
72pub use host::{Command, ExitStatus, LocalPty, Notify, PtyHost, ReplayHandle, ReplayHost};
73pub use pane::{DEFAULT_SCROLLBACK, TerminalPane, terminal, terminal_with};
74pub use pixels::{Pixels, half_blocks};
75pub use program::{BROWSER_VARIABLE, KNOWN_BROWSERS, ProgramEngine};
76pub use web::{
77 PageState, WebEngine, WebFrame, WebHandle, WebInput, WebView, web_view, web_view_with,
78};