tears 0.9.1

A simple and elegant framework for building TUI applications using The Elm Architecture (TEA)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

//! Demonstrates terminal recovery on panic via [`tears::install_panic_hook`].
//!
//! A TUI puts the terminal into raw mode and an alternate screen. If the
//! application panics, the stack unwinds past the `ratatui::restore()` call that
//! would normally run after [`Runtime::run`], leaving the terminal broken.
//!
//! [`tears::install_panic_hook`] wraps the current panic hook so the terminal is
//! restored *before* the original hook runs, so the `color_eyre` report prints
//! on a clean, usable terminal.
//!
//! Try it:
//! - Press `p` to trigger a panic. The terminal is restored and a `color_eyre`
//!   report is printed normally (no leftover raw mode / alternate screen).
//! - Press `q` to quit normally.
//!
//! To see the broken behavior for comparison, comment out the
//! `tears::install_panic_hook()` call in `main` and press `p`: the report is
//! printed into the alternate screen and the terminal is left in raw mode.
//!
//! Run with: `cargo run --example panic_hook`

use std::io;

use color_eyre::eyre::Result;
use crossterm::event::{Event, KeyCode};
use ratatui::Frame;
use ratatui::text::Text;
use tears::prelude::*;
use tears::subscription::terminal::TerminalEvents;

/// Messages that the application can receive
#[derive(Debug)]
enum Message {
    /// Terminal input event (keyboard, mouse, resize)
    Terminal(Event),
    /// Terminal event stream error
    TerminalError(io::Error),
}

/// Application state
#[derive(Debug, Default)]
struct PanicDemo;

impl Application for PanicDemo {
    type Message = Message;
    type Flags = ();

    fn new(_flags: Self::Flags) -> (Self, Command<Self::Message>) {
        (Self, Command::none())
    }

    fn update(&mut self, msg: Self::Message) -> Command<Self::Message> {
        match msg {
            Message::Terminal(Event::Key(key)) => match key.code {
                // Intentionally panic to demonstrate terminal recovery.
                #[allow(clippy::panic, reason = "demonstrating panic recovery")]
                KeyCode::Char('p') => panic!("intentional panic triggered by 'p'"),
                // Quit normally.
                KeyCode::Char('q') => Command::effect(Action::Quit),
                _ => Command::none(),
            },
            Message::Terminal(_) => Command::none(),
            Message::TerminalError(e) => {
                eprintln!("Terminal error: {e}");
                Command::effect(Action::Quit)
            }
        }
    }

    fn view(&self, frame: &mut Frame<'_>) {
        let text = Text::raw("Press 'p' to panic (terminal should recover), 'q' to quit");
        frame.render_widget(text, frame.area());
    }

    fn subscriptions(&self) -> Vec<Subscription<Self::Message>> {
        vec![
            Subscription::new(TerminalEvents::new()).map(|result| match result {
                Ok(event) => Message::Terminal(event),
                Err(e) => Message::TerminalError(e),
            }),
        ]
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    color_eyre::install()?;

    // Setup terminal
    let mut terminal = ratatui::init();

    // Restore the terminal on panic before the color_eyre report runs.
    // Installed after `color_eyre::install()` so it wraps that hook.
    tears::install_panic_hook();

    // Run the application at 60 FPS
    let runtime = Runtime::<PanicDemo>::try_new((), 60)?;
    let result = runtime.run(&mut terminal).await;

    // Restore terminal (normal exit path)
    ratatui::restore();

    result?;

    Ok(())
}