hojicha_core/
lib.rs

1//! # Hojicha Core
2//!
3//! Core Elm Architecture (TEA) abstractions for building terminal user interfaces in Rust.
4//!
5//! This crate provides the fundamental building blocks of The Elm Architecture:
6//!
7//! ## The Elm Architecture
8//!
9//! Hojicha implements The Elm Architecture (TEA), a pattern for building interactive
10//! applications with a clear separation of concerns:
11//!
12//! - **Model**: Your application state
13//! - **Message**: Events that trigger state changes  
14//! - **Update**: Pure functions that handle messages and update state
15//! - **View**: Pure functions that render your model to the terminal
16//! - **Command**: Side effects that produce messages
17//!
18//! ## Core Traits
19//!
20//! - [`Model`]: The main trait your application must implement
21//! - [`Message`]: Marker trait for your application's message types
22//! - [`Cmd`]: Commands for side effects and async operations
23//!
24//! ## Example
25//!
26//! ```no_run
27//! use hojicha_core::{Model, Cmd};
28//!
29//! struct App {
30//!     counter: u32,
31//! }
32//!
33//! enum Msg {
34//!     Increment,
35//!     Decrement,
36//! }
37//!
38//! impl Model for App {
39//!     type Message = Msg;
40//!
41//!     fn update(&mut self, event: hojicha_core::Event<Self::Message>) -> Cmd<Self::Message> {
42//!         match event {
43//!             hojicha_core::Event::User(Msg::Increment) => self.counter += 1,
44//!             hojicha_core::Event::User(Msg::Decrement) => self.counter -= 1,
45//!             _ => {}
46//!         }
47//!         Cmd::noop()
48//!     }
49//!
50//!     fn view(&self) -> String {
51//!         // Render your UI to a string
52//!         format!("Counter: {}", self.counter)
53//!     }
54//! }
55//! ```
56
57#![warn(missing_docs)]
58#![warn(rustdoc::missing_crate_level_docs)]
59
60// Core TEA abstractions
61pub mod async_helpers;
62pub mod commands;
63pub mod concurrency;
64pub mod core;
65pub mod debug;
66pub mod error;
67pub mod event;
68pub mod fallible;
69pub mod logging;
70pub mod optimized_event;
71
72// Testing utilities (only in tests)
73// Testing utilities (exported for use in tests and examples)
74pub mod testing;
75
76// Re-export core types
77pub use core::{Cmd, Message, Model};
78pub use error::{Error, ErrorContext, ErrorHandler, Result};
79pub use event::{
80    Event, Key, KeyEvent, KeyModifiers, MouseButton, MouseEvent, MouseEventKind, WindowSize,
81};
82
83// Re-export command constructors
84pub use commands::{
85    batch, custom, custom_async, custom_fallible, every, noop, quit, sequence, spawn, tick,
86};
87
88/// Prelude module for convenient imports
89///
90/// This module provides the most commonly used types and functions for building
91/// Hojicha applications. Import everything with:
92///
93/// ```
94/// use hojicha_core::prelude::*;
95/// ```
96///
97/// ## Included Items
98///
99/// ### Core Traits
100/// - [`Model`] - The main trait your application implements
101/// - [`Message`] - Marker trait for messages
102/// - [`Cmd`] - Commands for side effects
103///
104/// ### Events
105/// - [`Event`] - All event types (Key, Mouse, User, etc.)
106/// - [`Key`], [`KeyEvent`], [`KeyModifiers`] - Keyboard handling
107/// - [`MouseEvent`] - Mouse events
108///
109/// ### Commands
110/// - [`none()`] - No-op command
111/// - [`batch()`] - Run commands concurrently
112/// - [`sequence()`] - Run commands in order
113/// - [`tick()`] - Delayed command
114/// - [`every()`] - Recurring command
115/// - [`quit()`] - Exit the program
116///
117/// ### Error Handling
118/// - [`Result`] - Hojicha's Result type
119/// - [`Error`] - Hojicha's Error type
120///
121/// ### Rendering
122/// - String-based rendering with ANSI escape codes
123pub mod prelude {
124    // Core traits and types
125    pub use crate::core::{Cmd, Message, Model};
126
127    // Events
128    pub use crate::event::{
129        Event, Key, KeyEvent, KeyModifiers, MouseButton, MouseEvent, MouseEventKind, WindowSize,
130    };
131
132    // Essential commands
133    pub use crate::commands::{
134        batch, custom, custom_async, custom_fallible, every, noop, quit, sequence, spawn, tick,
135    };
136
137    // Concurrency utilities
138    pub use crate::concurrency::{RequestId, RequestTracker, StateMachine};
139
140    // Testing utilities
141    pub use crate::testing::{HarnessConfig, ScenarioBuilder, UnifiedTestHarness};
142
143    // Error handling
144    pub use crate::error::{Error, Result};
145
146    // String-based rendering for maximum compatibility
147}
148
149// Users will directly import hojicha-runtime as a separate crate
hojicha_core/lib.rs

hojicha_core/
lib.rs
