devela 0.28.0

A development substrate of coherence.
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199

// devela::sys::os::term::render::slice

use crate::{Ansi, AnsiColor, NotEnoughSpace, TermRenderer, whilst};

/// # Mutable byte-frame construction
impl<B: AsRef<[u8]> + AsMut<[u8]>> TermRenderer<B> {
    /// Clears the active frame without modifying the underlying bytes.
    pub const fn clear_buffer(&mut self) -> &mut Self {
        self.len = 0;
        self
    }

    /// Appends raw bytes to the active frame.
    ///
    /// Returns `NotEnoughSpace` if the bytes do not fit in the remaining storage.
    pub fn try_push_bytes(&mut self, bytes: &[u8]) -> Result<&mut Self, NotEnoughSpace> {
        let Some(end) = self.len.checked_add(bytes.len()) else {
            return Err(NotEnoughSpace(Some(bytes.len())));
        };
        if end > self.capacity() {
            return Err(NotEnoughSpace(Some(bytes.len())));
        }
        self.buf.as_mut()[self.len..end].copy_from_slice(bytes);
        self.len = end;
        Ok(self)
    }

    /// Appends a string to the active frame.
    pub fn try_push_str(&mut self, text: &str) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(text.as_bytes())
    }

    // /// Begins a full-screen frame.
    // pub fn try_begin_frame(&mut self) -> Result<&mut Self, NotEnoughSpace> {
    //     self.clear_buffer();
    //     self.try_cursor_hide()?;
    //     self.try_clear_screen()?;
    //     self.try_cursor_home()
    // }

    /// Finishes a full-screen frame.
    pub fn try_finish_frame(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_format_reset()?;
        self.try_cursor_show()
    }
    /// Clears the whole terminal screen.
    pub fn try_clear_screen(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::ERASE_SCREEN_B)
    }
    /// Clears the current terminal line.
    pub fn try_clear_line(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::ERASE_LINE_B)
    }

    /// Moves the cursor to the terminal home position.
    pub fn try_cursor_home(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::CURSOR_HOME_B)
    }
    /// Hides the cursor.
    pub fn try_cursor_hide(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::CURSOR_INVISIBLE_B)
    }
    /// Shows the cursor.
    pub fn try_cursor_show(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::CURSOR_VISIBLE_B)
    }
    /// Moves the cursor to one-based terminal coordinates.
    pub fn try_cursor_move_to(&mut self, col: u16, row: u16) -> Result<&mut Self, NotEnoughSpace> {
        let mut tmp = [0u8; 14];
        let seq = Ansi::CURSOR_MOVE_N_B(&mut tmp, col, row);
        self.try_push_bytes(seq)
    }
    /// Moves the cursor to zero-based grid coordinates.
    pub fn try_cursor_move_to0(&mut self, x: u16, y: u16) -> Result<&mut Self, NotEnoughSpace> {
        self.try_cursor_move_to(x.saturating_add(1), y.saturating_add(1))
    }

    /// Resets all terminal presentation attributes and colors to their defaults.
    pub fn try_format_reset(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::RESET_B)
    }
    /// Enables bold style.
    pub fn try_style_bold(&mut self) -> Result<&mut Self, NotEnoughSpace> {
        self.try_push_bytes(&Ansi::BOLD_B)
    }

    /// Sets the foreground color.
    pub fn try_color_fg(&mut self, color: AnsiColor) -> Result<&mut Self, NotEnoughSpace> {
        match color {
            AnsiColor::None => Ok(self),
            AnsiColor::Default => self.try_push_bytes(&Ansi::DEFAULT_FG_B),
            AnsiColor::Dark(c) => self.try_push_bytes(&Ansi::COLOR_FG_B(c)),
            AnsiColor::Bright(c) => self.try_push_bytes(&Ansi::COLOR_FG_BRIGHT_B(c)),
            AnsiColor::Palette(c) => self.try_push_bytes(&Ansi::COLOR8_FG_B(c)),
            AnsiColor::Rgb(c) => self.try_push_bytes(&Ansi::RGB_FG_B(c)),
        }
    }
    /// Sets the background color.
    pub fn try_color_bg(&mut self, color: AnsiColor) -> Result<&mut Self, NotEnoughSpace> {
        match color {
            AnsiColor::None => Ok(self),
            AnsiColor::Default => self.try_push_bytes(&Ansi::DEFAULT_BG_B),
            AnsiColor::Dark(c) => self.try_push_bytes(&Ansi::COLOR_BG_B(c)),
            AnsiColor::Bright(c) => self.try_push_bytes(&Ansi::COLOR_BG_BRIGHT_B(c)),
            AnsiColor::Palette(c) => self.try_push_bytes(&Ansi::COLOR8_BG_B(c)),
            AnsiColor::Rgb(c) => self.try_push_bytes(&Ansi::RGB_BG_B(c)),
        }
    }

    /// Sets foreground and background colors.
    ///
    /// Argument order is `(fg, bg)`, matching ANSI code order.
    pub fn try_colors(
        &mut self,
        fg: AnsiColor,
        bg: AnsiColor,
    ) -> Result<&mut Self, NotEnoughSpace> {
        match (fg, bg) {
            (AnsiColor::None, AnsiColor::None) => Ok(self),
            (AnsiColor::Dark(fg), AnsiColor::Dark(bg)) => {
                self.try_push_bytes(&Ansi::COLORS_B(fg, bg))
            }
            (AnsiColor::Bright(fg), AnsiColor::Bright(bg)) => {
                self.try_push_bytes(&Ansi::COLORS_BRIGHT_B(fg, bg))
            }
            (AnsiColor::Bright(fg), AnsiColor::Dark(bg)) => {
                self.try_push_bytes(&Ansi::COLORS_BRIGHT_FG_B(fg, bg))
            }
            (AnsiColor::Dark(fg), AnsiColor::Bright(bg)) => {
                self.try_push_bytes(&Ansi::COLORS_BRIGHT_BG_B(fg, bg))
            }
            (AnsiColor::Palette(fg), AnsiColor::Palette(bg)) => {
                self.try_push_bytes(&Ansi::COLORS8_B(fg, bg))
            }
            (AnsiColor::Rgb(fg), AnsiColor::Rgb(bg)) => self.try_push_bytes(&Ansi::RGB_B(fg, bg)),
            (fg, bg) => {
                self.try_color_fg(fg)?;
                self.try_color_bg(bg)
            }
        }
    }

    /// Writes text at one-based terminal coordinates.
    pub fn try_text_at(
        &mut self,
        col: u16,
        row: u16,
        text: &str,
    ) -> Result<&mut Self, NotEnoughSpace> {
        self.try_cursor_move_to(col, row)?;
        self.try_push_str(text)
    }
    /// Writes text at zero-based terminal coordinates.
    ///
    /// This moves the cursor, then appends `text` as raw UTF-8 bytes.
    /// It does not clip, wrap, or account for display width.
    pub fn try_text_at0(
        &mut self,
        x: u16,
        y: u16,
        text: &str,
    ) -> Result<&mut Self, NotEnoughSpace> {
        self.try_text_at(x.saturating_add(1), y.saturating_add(1), text)
    }

    /// Draws a horizontal repeated string from zero-based coordinates.
    ///
    /// `unit` is repeated `count` times as raw UTF-8 bytes.
    /// This does not account for display width.
    pub fn try_hline_at0(
        &mut self,
        x: u16,
        y: u16,
        unit: &str,
        count: usize,
    ) -> Result<&mut Self, NotEnoughSpace> {
        self.try_cursor_move_to0(x, y)?;
        whilst! { i in 0..count; { self.try_push_str(unit)?; }}
        Ok(self)
    }
    /// Draws a vertical repeated string from zero-based grid coordinates.
    ///
    /// `unit` is repeated `count` times as raw UTF-8 bytes.
    /// This does not account for display width.
    pub fn try_vline_at0(
        &mut self,
        x: u16,
        y: u16,
        unit: &str,
        count: usize,
    ) -> Result<&mut Self, NotEnoughSpace> {
        whilst! { i in 0..count; {
            let yi = y.saturating_add(i.min(u16::MAX as usize) as u16);
            self.try_cursor_move_to0(x, yi)?;
            self.try_push_str(unit)?;
        }}
        Ok(self)
    }
}