betamax_core/lib.rs
1#![warn(missing_docs)]
2#![cfg_attr(
3 windows,
4 doc = "This crate is not supported on Windows because libghostty-vt-sys does not support Windows builds."
5)]
6
7//! Core library for Betamax terminal capture.
8//!
9//! `betamax-core` is the reusable engine behind the `betamax` command-line
10//! application. It parses VHS-style tape source, executes commands in a PTY,
11//! feeds terminal output into `libghostty-vt`, renders terminal frames, writes
12//! media artifacts, and can return structured terminal state for snapshot tests.
13//!
14//! Most applications should start with [`Tape`] and [`Runner`]:
15//!
16//! The full tape language is documented on the
17//! [Betamax documentation site](https://www.joshka.net/betamax/reference/tape-reference/),
18//! including each command's behavior and each setting's default value.
19//!
20//! ```no_run
21//! use betamax_core::{Runner, Tape};
22//!
23//! # fn main() -> betamax_core::Result<()> {
24//! let tape = Tape::parse(
25//! r#"
26//! Output /tmp/betamax-state.json
27//! Set Shell "bash"
28//! Type "printf 'hello\n'"
29//! Enter
30//! Wait+Screen "hello"
31//! Hide
32//! Type "exit"
33//! Enter
34//! "#,
35//! )?;
36//! let artifacts = Runner::new().run_artifacts(&tape)?;
37//! assert!(artifacts.final_state.is_some());
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! # Module Guide
43//!
44//! - [`tape`] contains the parser and in-memory command model. Use it when you need to inspect or
45//! construct tape commands before execution.
46//! - [`runner`] executes a parsed tape and writes requested outputs.
47//! - [`ghostty`] exposes the lower-level libghostty-vt session, theme, frame capture, and
48//! terminal-state types used by the runner.
49//! - [`media`] contains raw frame types and format writers. These are public for embedders that
50//! want to render or encode frames directly, but the higher level [`Runner`] API is the stable
51//! path for most users.
52//!
53//! # Stability Notes
54//!
55//! The crate is pre-`1.0`. The tape parser and runner are intended to become the
56//! primary stable API. Lower-level rendering and media modules are public because
57//! they are useful for tests and tools, but their exact shape may still change as
58//! libghostty exposes more rendering functionality.
59
60#[cfg(windows)]
61compile_error!("betamax-core is not supported on Windows because libghostty-vt-sys does not support Windows builds.");
62
63mod assertion;
64mod error;
65pub mod ghostty;
66mod key;
67pub mod media;
68mod output;
69pub mod runner;
70mod shell;
71pub mod state_diff;
72pub mod tape;
73mod trace;
74mod wait;
75
76#[doc(inline)]
77pub use error::{Error, Result};
78#[doc(inline)]
79pub use runner::{FrameCapture, RunArtifacts, Runner, TerminalSession};
80#[doc(inline)]
81pub use tape::Tape;