Struct ProgramBuilder

pub struct ProgramBuilder<M: Model> { /* private fields */ }

A builder for creating and configuring Program instances.

The ProgramBuilder provides a fluent API for setting various configuration options before building the final Program.

Implementations

impl<M: Model> ProgramBuilder<M>

pub fn with_environment(self, env: HashMap<String, String>) -> Self

Sets environment variables to apply to external process commands created via command::exec_process.

These environment variables will be merged with the system environment when spawning external processes through commands.

Arguments

• env - A HashMap of environment variable key-value pairs.

Example

use std::collections::HashMap;
use bubbletea_rs::Program;

let mut env = HashMap::new();
env.insert("CUSTOM_VAR".to_string(), "value".to_string());

let program = Program::<MyModel>::builder()
    .with_environment(env)
    .build();

pub fn alt_screen(self, enabled: bool) -> Self

Sets whether to use the alternate screen buffer.

When enabled, the application will run in an alternate screen buffer, preserving the main terminal content.

pub fn mouse_motion(self, motion: MouseMotion) -> Self

Sets the mouse motion reporting mode.

Arguments

• motion - The desired MouseMotion mode.

pub fn report_focus(self, enabled: bool) -> Self

Sets whether to report focus events.

When enabled, the application will receive FocusMsg and BlurMsg when the terminal gains or loses focus.

pub fn with_fps(self, fps: u32) -> Self

Sets the target frames per second for rendering.

This controls how often the view method of the model is called and the terminal is updated.

Arguments

• fps - The target frames per second.

pub fn without_renderer(self) -> Self

Disables the renderer.

When disabled, the view method will not be called and no output will be rendered to the terminal. This is useful for testing or headless operations.

pub fn catch_panics(self, enabled: bool) -> Self

Sets whether to catch panics.

When enabled, application panics will be caught and converted into ProgramPanic errors, allowing for graceful shutdown.

pub fn signal_handler(self, enabled: bool) -> Self

Sets whether to enable signal handling.

When enabled, the Program will listen for OS signals (e.g., Ctrl+C) and attempt a graceful shutdown.

pub fn bracketed_paste(self, enabled: bool) -> Self

Sets whether to enable bracketed paste mode.

When enabled, pasted text will be wrapped in special escape sequences, allowing the application to distinguish pasted input from typed input.

pub fn input_tty(self) -> Self

Configures the program to use the default terminal input (stdin).

This is the default behavior, so calling this method is optional. It’s provided for explicit configuration when needed.

Returns

The ProgramBuilder instance for method chaining.

pub fn input(self, reader: impl AsyncRead + Send + Unpin + 'static) -> Self

Sets a custom input reader for the program.

Arguments

• reader - A custom input stream that implements tokio::io::AsyncRead + Send + Unpin.

pub fn output(self, writer: impl AsyncWrite + Send + Unpin + 'static) -> Self

Sets a custom output writer for the program.

Arguments

• writer - A custom output stream that implements tokio::io::AsyncWrite + Send + Unpin.

pub fn context(self, token: CancellationToken) -> Self

Sets an external cancellation token for the program.

When the token is cancelled, the program’s event loop will gracefully shut down.

Arguments

• token - The CancellationToken to use for external cancellation.

pub fn filter(self, f: impl Fn(&M, Msg) -> Option<Msg> + Send + 'static) -> Self

Sets a model-aware message filter function.

The provided closure will be called for each incoming message with access to the current model, allowing for context-aware transformation or filtering.

Arguments

• f - A closure that takes &M and Msg, returning an Option<Msg>.

pub fn event_channel_buffer(self, buffer_size: Option<usize>) -> Self

Sets the event channel buffer size.

By default, the channel has a buffer of 1000 messages. Setting this to None will use an unbounded channel (not recommended for production), while setting it to Some(size) will use a bounded channel with the specified buffer size.

Arguments

• buffer_size - The buffer size for the event channel.

pub fn memory_monitoring(self, enabled: bool) -> Self

Enables memory usage monitoring.

When enabled, the program will track memory usage metrics that can be accessed for debugging and performance analysis.

pub fn build(self) -> Result<Program<M>, Error>

Builds the Program instance with the configured options.

Returns

A Result containing the Program instance or an Error if building fails.