bubbletea_rs/
lib.rs

1//! # bubbletea-rs
2//!
3//! A comprehensive Rust implementation of the Bubble Tea TUI framework.
4//! This library provides developers with the tools to build interactive terminal
5//! applications using the Model-View-Update (MVU) architecture pattern.
6//!
7//! ## Features
8//!
9//! - **Model-View-Update Architecture**: Clean separation of state, logic, and rendering
10//! - **Async Command System**: Non-blocking operations with command-based side effects
11//! - **Terminal Interface Abstraction**: Works with real terminals and test environments
12//! - **Comprehensive Event Handling**: Keyboard, mouse, window resize, and focus events
13//! - **Memory Monitoring**: Built-in memory usage tracking and leak detection
14//! - **Gradient Rendering**: Rich color gradients for progress bars and visual elements
15//! - **Flexible Input Sources**: Support for different input mechanisms and testing
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use bubbletea_rs::{Model, Program, Msg, Cmd};
21//!
22//! struct MyModel {
23//!     counter: i32,
24//! }
25//!
26//! impl Model for MyModel {
27//!     fn init() -> (Self, Option<Cmd>) {
28//!         (Self { counter: 0 }, None)
29//!     }
30//!
31//!     fn update(&mut self, _msg: Msg) -> Option<Cmd> {
32//!         None
33//!     }
34//!
35//!     fn view(&self) -> String {
36//!         format!("Counter: {}", self.counter)
37//!     }
38//! }
39//!
40//! #[tokio::main]
41//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
42//!     let program = Program::<MyModel>::builder().build()?;
43//!     program.run().await?;
44//!     Ok(())
45//! }
46//! ```
47//!
48//! ## Architecture Overview
49//!
50//! The library follows the Elm Architecture pattern:
51//!
52//! 1. **Model**: Your application state implementing the `Model` trait
53//! 2. **Messages**: Events that trigger state changes (keyboard, mouse, timers, etc.)
54//! 3. **Update**: Process messages and optionally issue commands
55//! 4. **View**: Render your model as a string for terminal display
56//! 5. **Commands**: Async operations that can produce future messages
57//!
58//! ## Memory Safety
59//!
60//! The framework includes built-in memory monitoring to help detect leaks and optimize
61//! performance. Use the `MemoryMonitor` to track allocations in your applications.
62//!
63//! ## Testing
64//!
65//! Testing is supported through the `DummyTerminal` which allows you to test your
66//! applications without requiring an actual terminal interface.
67
68#![warn(missing_docs)]
69
70/// Commands for async operations that produce messages.
71pub mod command;
72/// Error types and handling.
73pub mod error;
74/// Event types and message passing system.
75pub mod event;
76/// Gradient rendering utilities for progress bars and color transitions.
77pub mod gradient;
78/// Input handling abstraction for different sources.
79pub mod input;
80/// Logging utilities for debugging and monitoring.
81pub mod logging;
82/// Memory monitoring and leak detection.
83pub mod memory;
84/// The core Model trait defining application behavior.
85pub mod model;
86/// Program runtime and builder for TUI applications.
87pub mod program;
88/// Terminal interface abstraction and implementations.
89pub mod terminal;
90
91pub use command::{
92    batch, cancel_all_timers, cancel_timer, clear_screen, disable_bracketed_paste, disable_mouse,
93    disable_report_focus, enable_bracketed_paste, enable_mouse_all_motion,
94    enable_mouse_cell_motion, enable_report_focus, enter_alt_screen, every, every_with_id,
95    exec_process, exit_alt_screen, hide_cursor, interrupt, printf, println, quit, sequence,
96    set_window_title, show_cursor, suspend, tick, window_size, Batch, Cmd,
97};
98pub use error::Error;
99pub use event::{
100    BatchMsgInternal, BlurMsg, CancelAllTimersMsg, CancelTimerMsg, ClearScreenMsg,
101    DisableBracketedPasteMsg, DisableMouseMsg, DisableReportFocusMsg, EnableBracketedPasteMsg,
102    EnableMouseAllMotionMsg, EnableMouseCellMotionMsg, EnableReportFocusMsg, EnterAltScreenMsg,
103    EventReceiver, EventSender, ExitAltScreenMsg, FocusMsg, HideCursorMsg, InterruptMsg, KeyMsg,
104    KillMsg, MouseMsg, Msg, PasteMsg, PrintMsg, PrintfMsg, QuitMsg, RequestWindowSizeMsg,
105    ResumeMsg, SetWindowTitleMsg, ShowCursorMsg, SuspendMsg, WindowSizeMsg,
106};
107pub use gradient::{
108    charm_default_gradient, gradient_filled_segment, gradient_filled_segment_with_buffer, lerp_rgb,
109};
110pub use input::{InputHandler, InputSource};
111pub use memory::{MemoryHealth, MemoryMonitor, MemorySnapshot};
112pub use model::Model;
113pub use program::{MouseMotion, Program, ProgramBuilder, ProgramConfig};
114pub use terminal::{DummyTerminal, Terminal, TerminalInterface};
115
116#[cfg(feature = "logging")]
117pub use logging::log_to_file;
118
119pub mod prelude {
120    //! Convenient re-exports of the most commonly used types.
121
122    pub use crate::{Cmd, Error, Model, Msg, Program};
123    pub use crate::{KeyMsg, KillMsg, MouseMsg, PasteMsg, QuitMsg, WindowSizeMsg};
124
125    #[cfg(feature = "logging")]
126    pub use crate::log_to_file;
127}
bubbletea_rs/lib.rs

bubbletea_rs/
lib.rs
