clap_tui/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(missing_docs, clippy::all, clippy::pedantic)]
3#![deny(rust_2018_idioms)]
4#![warn(rust_2024_compatibility)]
5
6//! `clap-tui` turns a `clap` CLI into an interactive terminal UI while preserving the original
7//! command-line interface.
8//!
9//! You can keep `clap` as the source of truth, collect input in the TUI, and then hand the
10//! selected command value back to your normal application dispatch.
11//!
12//! It reduces trial-and-error for complex CLIs by making commands, flags, and values easier to
13//! explore before execution. It also improves discoverability without changing the CLI behavior
14//! your existing scripts and docs already rely on.
15//!
16//! This crate was heavily inspired by [Trogon](https://github.com/Textualize/trogon).
17//! `clap-tui` is a community crate and is not an official `clap` project.
18//!
19//! ![clap-tui hero screenshot](https://raw.githubusercontent.com/gitseti/clap-tui/main/docs/assets/hero.png)
20//!
21//! # Quick Start
22//!
23//! Add a `Tui` subcommand and delegate to [`Tui::run`].
24//!
25//! The recommended integration model is to define a normal `tui` subcommand in your own CLI and
26//! run [`Tui`] from that dispatch branch:
27//!
28//! ```no_run
29//! use clap::Parser;
30//! use clap_tui::Tui;
31//!
32//! #[derive(Debug, Parser, PartialEq, Eq)]
33//! #[command(name = "tool")]
34//! enum Command {
35//!     Tui,
36//!     Hello {
37//!         #[arg(long, default_value = "world")]
38//!         name: String,
39//!     },
40//! }
41//!
42//! fn dispatch(command: Command) {
43//!     match command {
44//!         Command::Tui => {}
45//!         Command::Hello { name } => println!("Hello, {name}!"),
46//!     }
47//! }
48//!
49//! fn main() -> Result<(), clap_tui::TuiError> {
50//!     match Command::parse() {
51//!         Command::Tui => {
52//!             if let Some(command) = Tui::<Command>::new().hide_entrypoint("tui")?.run()? {
53//!                 dispatch(command);
54//!             }
55//!         }
56//!         command => dispatch(command),
57//!     }
58//!
59//!     Ok(())
60//! }
61//! ```
62//!
63//! # Choosing An Entry Point
64//!
65//! Use [`Tui`] (recommended).
66//!
67//! - Use [`Tui::<T>::run()`][Tui::run] when you want typed results from a derive-based parser.
68//! - Use [`TuiApp`] when you are working directly with a hand-built [`clap::Command`] or need a
69//!   lower-level integration surface.
70//!
71//! # Typed Outcomes
72//!
73//! You can also use [`Tui`] with a single struct instead of an enum:
74//!
75//! ```no_run
76//! use clap::Parser;
77//! use clap_tui::Tui;
78//!
79//! #[derive(Debug, Parser, PartialEq, Eq)]
80//! #[command(name = "tool")]
81//! struct Cli {
82//!     #[arg(long)]
83//!     name: String,
84//! }
85//!
86//! fn main() -> Result<(), clap_tui::TuiError> {
87//!     if let Some(cli) = Tui::<Cli>::new().run()? {
88//!         println!("Hello, {}!", cli.name);
89//!     }
90//!     Ok(())
91//! }
92//! ```
93//!
94//! [`Tui::run`] returns:
95//! - `Some(T)` when the user submits a valid command
96//! - `None` when the user cancels before submission
97//! - `Err(TuiError)` for runtime failures or clap-driven flows such as help and version handling
98//!
99//! See [`TuiError`] for the detailed error taxonomy.
100//!
101//! # Feature Flags
102//!
103//! - The default `mouse` feature enables mouse capture and mouse-driven controls.
104//!
105//! # Runtime Expectations
106//!
107//! - The default [`CrosstermRuntime`] requires a terminal supporting raw mode and an alternate
108//!   screen.
109//!
110//! # Customization
111//!
112//! - [`TuiConfig`] controls theme, layout, key bindings, and initial command selection.
113//! - [`Theme`] and [`ThemePreset`] help you start from a built-in look and adjust from there.
114//! - [`Runtime`] plus the exported runtime event types support custom event loops or embedding into
115//!   existing runtimes.
116//!
117//! # Examples
118//!
119//! The crate ships with four public examples:
120//! - `simple` for minimal `Command::Tui` setup
121//! - `showcase` for a realistic, compact command tree
122//! - `subcommands` for typed dispatch across command trees
123//! - `clap_features` for the full [`TuiApp`] compatibility fixture
124
125mod app;
126mod argv_serializer;
127mod config;
128mod controller;
129mod editor_state;
130mod error;
131mod form_editor;
132mod frame_snapshot;
133mod input;
134mod layout;
135mod pipeline;
136mod query;
137mod repeated_field;
138mod runtime;
139mod spec;
140mod ui;
141mod update;
142
143/// TUI application entry points.
144pub use app::{Tui, TuiApp};
145/// Public configuration and theming types.
146pub use config::{Keymap, LayoutConfig, Theme, ThemePreset, TuiConfig};
147/// Error type returned by public `clap-tui` operations.
148pub use error::TuiError;
149/// Runtime customization surface for advanced integrations.
150pub use runtime::{
151    AppEvent, AppKeyCode, AppKeyEvent, AppKeyModifiers, AppMouseButton, AppMouseEvent,
152    AppMouseEventKind, CrosstermRuntime, Runtime,
153};
clap_tui/lib.rs

clap_tui/
lib.rs
