tears 0.8.0

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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! Terminal event subscription.
//!
//! This module provides the [`TerminalEvents`] subscription source for handling
//! terminal input events using crossterm.

use std::hash::{DefaultHasher, Hash, Hasher};
use std::io;

use crossterm::event::{Event, EventStream};
use futures::{StreamExt, stream::BoxStream};

use super::{SubscriptionId, SubscriptionSource};

/// A subscription source for terminal events.
///
/// This provides a stream of terminal events such as keyboard input, mouse events,
/// and window resize events using crossterm's `EventStream`.
///
/// # Example
///
/// ```rust,no_run
/// use tears::subscription::{Subscription, terminal::TerminalEvents};
/// use crossterm::event::{Event, KeyCode};
///
/// enum Message {
///     Input(Event),
///     InputError(std::io::Error),
/// }
///
/// // Create a subscription for terminal events
/// let sub = Subscription::new(TerminalEvents::new())
///     .map(|result| match result {
///         Ok(event) => Message::Input(event),
///         Err(e) => Message::InputError(e),
///     });
/// ```
///
/// # Error Handling
///
/// This subscription yields `Result<Event, io::Error>` values. Applications are
/// responsible for handling errors appropriately. Common error scenarios include:
///
/// - **Terminal disconnection**: Usually unrecoverable, may want to exit gracefully
/// - **I/O errors**: May be transient or permanent depending on the cause
///
/// You can choose to:
/// - Log errors and continue (errors stop producing further events)
/// - Display an error message to the user
/// - Attempt to recreate the subscription
/// - Exit the application
///
/// ```rust,no_run
/// # use tears::prelude::*;
/// # use crossterm::event::Event;
/// # struct App;
/// enum Message {
///     Input(Event),
///     InputError(std::io::Error),
/// }
/// # impl Application for App {
/// #     type Message = Message;
/// #     type Flags = ();
/// #     fn new(_: ()) -> (Self, Command<Message>) { (App, Command::none()) }
/// #     fn view(&self, _: &mut ratatui::Frame) {}
/// #     fn subscriptions(&self) -> Vec<Subscription<Message>> { vec![] }
///
/// fn update(&mut self, msg: Message) -> Command<Message> {
///     match msg {
///         Message::Input(event) => {
///             // Handle the event
///             Command::none()
///         }
///         Message::InputError(e) => {
///             // Handle the error (log, show UI, exit, etc.)
///             eprintln!("Terminal error: {}", e);
///             Command::effect(Action::Quit)
///         }
///     }
/// }
/// # }
/// ```
///
/// # Note
///
/// This is a singleton subscription - all instances are considered identical
/// and only one terminal event stream will be active at a time.
#[derive(Debug, Clone, PartialEq, Eq, Default, Hash)]
pub struct TerminalEvents;

impl TerminalEvents {
    /// Create a new terminal events subscription.
    ///
    /// # Example
    ///
    /// ```
    /// use tears::subscription::terminal::TerminalEvents;
    ///
    /// let events = TerminalEvents::new();
    /// ```
    #[must_use]
    pub const fn new() -> Self {
        Self
    }
}

impl SubscriptionSource for TerminalEvents {
    type Output = Result<Event, io::Error>;

    fn stream(&self) -> BoxStream<'static, Self::Output> {
        let stream = EventStream::new();

        // Create a stream that yields terminal events as Results
        futures::stream::unfold(stream, |mut stream| async move {
            // NOTE: EventStream::next() returns Result<Event, io::Error>
            // We pass the Result directly to the application, allowing users to
            // decide how to handle errors (log, retry, show error UI, etc.)
            stream.next().await.map(|result| (result, stream))
        })
        .boxed()
    }

    fn id(&self) -> SubscriptionId {
        // Since TerminalEvents is a singleton (no parameters), use a constant ID
        let mut hasher = DefaultHasher::new();
        self.hash(&mut hasher);
        SubscriptionId::of::<Self>(hasher.finish())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_terminal_events_new() {
        let events = TerminalEvents::new();
        assert_eq!(events, TerminalEvents);
    }

    #[test]
    fn test_terminal_events_id_consistency() {
        let events1 = TerminalEvents::new();
        let events2 = TerminalEvents::new();

        // Same subscription should have the same ID
        assert_eq!(events1.id(), events2.id());
    }
}