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
// Copyright (c) 2025 R3BL LLC. Licensed under Apache License, Version 2.0.
// cSpell:words VMIN VTIME deciseconds Interbyte
//! Raw mode terminal configuration constants.
//!
//! This module contains constants specific to raw mode terminal configuration,
//! particularly for POSIX termios special codes (VMIN and VTIME).
//!
//! # Architecture Context
//!
//! This module is part of a 3-layer raw mode architecture:
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │ terminal_lib_backends/raw_mode.rs (High-level) │
//! │ └─ RawMode struct for render pipeline integration │
//! ├─────────────────────────────────────────────────────────────┤
//! │ terminal_raw_mode/ (Mid-level) │
//! │ └─ enable_raw_mode(), disable_raw_mode(), RawModeGuard │
//! ├─────────────────────────────────────────────────────────────┤
//! │ constants/raw_mode.rs (This module - Low-level) ◄───────│
//! │ └─ VMIN_RAW_MODE, VTIME_RAW_MODE │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! **You are here**: The constants layer, defining POSIX termios special codes
//! used by [`terminal_raw_mode`] when configuring the terminal.
//!
//! **See also**:
//! - [`terminal_raw_mode`] - Core enable/disable functions and RAII guard
//! - [`RawMode`] - High-level render pipeline integration
//!
//! [`terminal_raw_mode`]: crate::core::ansi::terminal_raw_mode
//! [`RawMode`]: crate::tui::terminal_lib_backends::raw_mode::RawMode
//!
//! # Raw Mode Configuration
//!
//! Raw mode disables terminal line buffering and processing, allowing applications
//! to read input character-by-character. The behavior is controlled by two special
//! codes in the termios structure:
//!
//! - **VMIN**: Minimum number of bytes to read before returning
//! - **VTIME**: Timeout in deciseconds (0.1s units)
//!
//! ## Standard Raw Mode Settings
//!
//! For typical raw mode (immediate, byte-by-byte input with no timeout):
//! - VMIN = 1: Return after reading at least 1 byte
//! - VTIME = 0: No timeout, blocking read
//!
//! This configuration is used by:
//! - `cfmakeraw()` in POSIX
//! - crossterm's raw mode implementation
//! - Most TUI applications requiring immediate input
//!
//! ## Example Usage
//!
//! ```no_run
//! use rustix::termios::{self, SpecialCodeIndex};
//! use std::io::stdin;
//! use r3bl_tui::{VMIN_RAW_MODE, VTIME_RAW_MODE};
//!
//! // Get current terminal settings
//! let mut termios = termios::tcgetattr(&stdin()).unwrap();
//!
//! // Configure for raw mode: byte-by-byte, no timeout
//! termios.special_codes[SpecialCodeIndex::VMIN] = VMIN_RAW_MODE;
//! termios.special_codes[SpecialCodeIndex::VTIME] = VTIME_RAW_MODE;
//!
//! // Apply settings
//! termios::tcsetattr(&stdin(), termios::OptionalActions::Now, &termios).unwrap();
//! ```
//!
//! ## VMIN/VTIME Interaction Matrix
//!
//! | VMIN | VTIME | Behavior |
//! |:-------|:--------|:----------------------------------------------------|
//! | 0 | 0 | Non-blocking: return immediately with available |
//! | 0 | >0 | Timed read: return after timeout or data |
//! | >0 | 0 | Blocking: return after VMIN bytes (no timeout) |
//! | >0 | >0 | Interbyte timeout: return after VMIN or timeout |
//!
//! Raw mode uses **VMIN=1, VTIME=0** for immediate, blocking input.
// ==================== Special Codes for Raw Mode ====================
/// VMIN value for raw mode: return after reading 1 byte.
///
/// In raw mode, `VMIN=1` means `read()` will block until at least one byte
/// is available, then return immediately with that byte. This enables
/// character-by-character input processing without line buffering.
///
/// This is the standard setting for:
/// - POSIX `cfmakeraw()`
/// - crossterm raw mode
/// - Interactive TUI applications
pub const VMIN_RAW_MODE: u8 = 1;
/// VTIME value for raw mode: no timeout (blocking read).
///
/// In raw mode, `VTIME=0` means `read()` will block indefinitely until
/// `VMIN` bytes are available (when VMIN > 0). Combined with `VMIN=1`,
/// this creates a simple blocking, byte-by-byte read behavior.
///
/// The unit for VTIME is deciseconds (0.1 second increments), so:
/// - 0 = no timeout (block forever)
/// - 1 = 0.1 second timeout
/// - 10 = 1 second timeout
pub const VTIME_RAW_MODE: u8 = 0;