terminal 0.2.1

Unified API over different TUI libraries.
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
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
use crate::backend::crosscurses::constants;
use crate::{
    backend::{
        crosscurses::{current_style::CurrentStyle, mapping::find_closest},
        Backend,
    },
    error, Action, Attribute, Clear, Color, Event, KeyCode, KeyEvent, KeyModifiers, MouseButton,
    Retrieved, Value,
};
use crosscurses::{ToChtype, Window, COLORS};
use std::{
    collections::HashMap, ffi::CStr, fs::File, io, io::Write, os::unix::io::IntoRawFd, result,
    sync::RwLock,
};

/// Checks if the expression result is an error.
/// Returns an Error based on the error code.
/// Does nothing if there's no error.
macro_rules! check {
    ($expr:expr) => (match $expr {
         0 => {},
        -1 => {
            return Err($crate::error::ErrorKind::IoError(std::io::Error::new(std::io::ErrorKind::Other, "Some error occurred while executing the action")))
        }
        3 => {
            return Err($crate::error::ErrorKind::ActionNotSupported("The action is not supported by crosscurses. Either work around it or use an other backend.".to_string()))
        }
        _ => {}
    });
}

#[derive(Default)]
struct InputCache {
    // The mouse on event doesn't have a button,
    // so we have to save it with the mouse down event
    last_mouse_button: Option<MouseButton>,

    stored_event: Option<Event>,
}

pub struct BackendImpl<W: Write> {
    buffer: W,
    // We can batch commands in the crosscurses window.
    // The moment we call `refresh` these are executed.
    window: crosscurses::Window,

    // The cache needed to parse input.
    input_cache: RwLock<InputCache>,

    // ncurses stores color values in pairs (fg, bg) color.
    // We store those pairs in this hashmap on order to keep track of the pairs we initialized.
    color_pairs: HashMap<i16, i32>,

    // Some key code definitions from which we can construct events.
    pub(crate) key_codes: HashMap<i32, Event>,

    // This is necessary to know the style that is currently set.
    current_style: CurrentStyle,
}

impl<W: Write> BackendImpl<W> {
    /// Prints the given string-like value into the window.
    fn print<S: AsRef<str>>(&mut self, asref: S) -> error::Result<()> {
        if cfg!(windows) {
            // PDCurses does an extra intermediate CString allocation, so we just
            // print out each character one at a time to avoid that.
            asref.as_ref().chars().all(|c| self.print_char(c).is_ok());
        } else {
            // NCurses, it seems, doesn't do the intermediate allocation and also uses
            // a faster routine for printing a whole string at once.
            self.window.printw(asref.as_ref());
        }

        Ok(())
    }

    /// Prints the given character into the window.
    fn print_char<T: ToChtype>(&mut self, character: T) -> error::Result<()> {
        self.window.addch(character);
        Ok(())
    }

    /// Updates the stored event.
    pub(crate) fn update_stored_event(&self, btn: Event) {
        let mut lock = self.input_cache.write().unwrap();
        lock.stored_event = Some(btn);
    }

    /// Tries to read event from temporary cache.
    fn try_take(&self) -> Option<Event> {
        self.input_cache.write().unwrap().stored_event.take()
    }

    /// Updates the last used button with a new button.
    pub(crate) fn update_last_btn(&self, btn: MouseButton) {
        let mut lock = self.input_cache.write().unwrap();
        lock.last_mouse_button = Some(btn);
    }

    /// Retrieves the last printed mouse button.
    pub(crate) fn last_btn(&self) -> Option<MouseButton> {
        self.input_cache.read().unwrap().last_mouse_button
    }

    /// Retrieves the foreground color index.
    pub(crate) fn get_fg_index(&mut self, fg_color: Color) -> i32 {
        let closest_fg_color = find_closest(fg_color, COLORS() as i16);
        let closest_bg_color = find_closest(self.current_style.background, COLORS() as i16);

        self.get_or_insert(closest_fg_color, closest_fg_color, closest_bg_color)
    }

    /// Retrieves the background color index.
    fn get_bg_index(&mut self, bg_color: Color) -> i32 {
        let closest_fg_color = find_closest(self.current_style.foreground, COLORS() as i16);
        let closest_bg_color = find_closest(bg_color, COLORS() as i16);

        self.get_or_insert(closest_bg_color, closest_fg_color, closest_bg_color)
    }

    /// Retrieves the color pair index, if the given color pair doesn't exist yet,
    /// it will be created and the index will be returned.
    fn get_or_insert(&mut self, key: i16, fg_color: i16, bg_color: i16) -> i32 {
        let index = self.new_color_pair_index();

        *self.color_pairs.entry(key).or_insert_with(|| {
            crosscurses::init_pair(index as i16, fg_color, bg_color);
            index
        })
    }

    /// Returns a new color pair index.
    fn new_color_pair_index(&mut self) -> i32 {
        let n = 1 + self.color_pairs.len() as i32;

        if 256 > n {
            // We still have plenty of space for everyone.
            n
        } else {
            // resize color pairs
            let target = n - 1;
            // Remove the mapping to n-1
            self.color_pairs.retain(|_, &mut v| v != target);
            target
        }
    }
}

fn init_stdout_window() -> Window {
    // Windows currently will only work on stdout because of this default crosscurses initialisation.
    // TODO: support using `newterm` like `init_unix_window` so that we are not depended on stdout.
    crosscurses::initscr()
}

#[cfg(unix)]
fn init_custom_window() -> Window {
    // By default crosscurses use stdout.
    // We can change this by calling `new_term` with an FILE pointer to the source.
    // Which is /dev/tty in our case.
    let file = File::create("/dev/tty").unwrap();

    let c_file = unsafe {
        libc::fdopen(
            file.into_raw_fd(),
            CStr::from_bytes_with_nul_unchecked(b"w+\0").as_ptr(),
        )
    };

    if cfg!(unix)
        && std::env::var("TERM")
            .map(|var| var.is_empty())
            .unwrap_or(false)
    {
        init_stdout_window()
    } else {
        // Create screen pointer which we will be using for this backend.
        let screen = crosscurses::newterm(None, c_file, c_file);

        // Set the created screen as active.
        crosscurses::set_term(screen);

        // Get `Window` of the created screen.
        crosscurses::stdscr()
    }
}

impl<W: Write> Backend<W> for BackendImpl<W> {
    fn create(buffer: W) -> Self {
        // The delay is the time ncurses wait after pressing ESC
        // to see if it's an escape sequence.
        // Default delay is way too long. 25 is imperceptible yet works fine.
        ::std::env::set_var("ESCDELAY", "25");

        #[cfg(windows)]
        let window = init_stdout_window();

        #[cfg(unix)]
        let window = init_custom_window();

        // Some default settings
        window.keypad(true);
        crosscurses::start_color();
        crosscurses::use_default_colors();
        crosscurses::mousemask(constants::MOUSE_EVENT_MASK, ::std::ptr::null_mut());

        // Initialize the default fore and background.
        let mut map = HashMap::<i16, i32>::new();
        map.insert(-1, 0);
        crosscurses::init_pair(0, -1, -1);

        BackendImpl {
            window,
            input_cache: RwLock::new(InputCache::default()),
            color_pairs: map,
            key_codes: initialize_keymap(),
            current_style: CurrentStyle::new(),
            buffer,
        }
    }

    fn act(&mut self, action: Action) -> error::Result<()> {
        self.batch(action)?;
        self.flush_batch()
    }

    #[allow(clippy::cognitive_complexity)]
    fn batch(&mut self, action: Action) -> error::Result<()> {
        match action {
            Action::MoveCursorTo(x, y) => {
                // Coordinates are reversed here
                check!(self.window.mv(y as i32, x as i32));
            }
            Action::HideCursor => {
                check!(crosscurses::curs_set(0));
            }
            Action::ShowCursor => {
                check!(crosscurses::curs_set(1));
            }
            Action::EnableBlinking => {
                check!(crosscurses::set_blink(true));
            }
            Action::DisableBlinking => {
                check!(crosscurses::set_blink(false));
            }
            Action::ClearTerminal(clear_type) => {
                check!(match clear_type {
                    Clear::All => self.window.clear(),
                    Clear::FromCursorDown => self.window.clrtobot(),
                    Clear::UntilNewLine => self.window.clrtoeol(),
                    Clear::FromCursorUp => 3, // TODO, not supported by crosscurses
                    Clear::CurrentLine => 3,  // TODO, not supported by crosscurses
                });
            }
            Action::SetTerminalSize(cols, rows) => {
                crosscurses::resize_term(rows as i32, cols as i32);
            }
            Action::EnableRawMode => {
                check!(crosscurses::noecho());
                check!(crosscurses::raw());
                check!(crosscurses::nonl());
            }
            Action::DisableRawMode => {
                check!(crosscurses::echo());
                check!(crosscurses::noraw());
                check!(crosscurses::nl());
            }
            Action::EnableMouseCapture => {
                self.buffer
                    .write_all(constants::ENABLE_MOUSE_CAPTURE.as_bytes())?;
                self.buffer.flush()?;
            }
            Action::DisableMouseCapture => {
                self.buffer
                    .write_all(constants::DISABLE_MOUSE_CAPTURE.as_bytes())?;
                self.buffer.flush()?;
            }
            Action::ResetColor => {
                let style = crosscurses::COLOR_PAIR(0 as crosscurses::chtype);
                check!(self.window.attron(style));
                check!(self.window.attroff(self.current_style.attributes));
                check!(self.window.refresh());
            }
            Action::SetForegroundColor(color) => {
                self.current_style.foreground = color;
                let index = self.get_fg_index(color);
                let style = crosscurses::COLOR_PAIR(index as crosscurses::chtype);
                check!(self.window.attron(style));
                check!(self.window.refresh());
            }
            Action::SetBackgroundColor(color) => {
                self.current_style.background = color;
                let index = self.get_bg_index(color);
                let style = crosscurses::COLOR_PAIR(index as crosscurses::chtype);
                check!(self.window.attron(style));
                check!(self.window.refresh());
            }
            Action::SetAttribute(attr) => {
                let no_match1 = match attr {
                    Attribute::Reset => Some(crosscurses::Attribute::Normal),
                    Attribute::Bold => Some(crosscurses::Attribute::Bold),
                    Attribute::Italic => Some(crosscurses::Attribute::Italic),
                    Attribute::Underlined => Some(crosscurses::Attribute::Underline),
                    Attribute::SlowBlink | Attribute::RapidBlink => {
                        Some(crosscurses::Attribute::Blink)
                    }
                    Attribute::Crossed => Some(crosscurses::Attribute::Strikeout),
                    Attribute::Reversed => Some(crosscurses::Attribute::Reverse),
                    Attribute::Conceal => Some(crosscurses::Attribute::Invisible),
                    _ => None, // OFF attributes and Fraktur, NormalIntensity, Framed
                }
                .map(|attribute| {
                    self.window.attron(attribute);
                    self.current_style.attributes = self.current_style.attributes | attribute;
                });

                let no_match2 = match attr {
                    Attribute::BoldOff => Some(crosscurses::Attribute::Bold),
                    Attribute::ItalicOff => Some(crosscurses::Attribute::Italic),
                    Attribute::UnderlinedOff => Some(crosscurses::Attribute::Underline),
                    Attribute::BlinkOff => Some(crosscurses::Attribute::Blink),
                    Attribute::CrossedOff => Some(crosscurses::Attribute::Strikeout),
                    Attribute::ReversedOff => Some(crosscurses::Attribute::Reverse),
                    Attribute::ConcealOff => Some(crosscurses::Attribute::Invisible),
                    _ => None, // OFF attributes and Fraktur, NormalIntensity, Framed
                }
                .map(|attribute| {
                    self.window.attroff(attribute);
                    self.current_style.attributes = self.current_style.attributes ^ attribute;
                });

                if no_match1.is_none() && no_match2.is_none() {
                    return Err(error::ErrorKind::AttributeNotSupported(String::from(attr)));
                }
            }
            Action::EnterAlternateScreen
            | Action::LeaveAlternateScreen
            | Action::ScrollUp(_)
            | Action::ScrollDown(_) => check!(3),
        };

        Ok(())
    }

    fn flush_batch(&mut self) -> error::Result<()> {
        self.window.refresh();
        Ok(())
    }

    fn get(&self, retrieve_operation: Value) -> error::Result<Retrieved> {
        match retrieve_operation {
            Value::TerminalSize => {
                // Coordinates are reversed here
                let (y, x) = self.window.get_max_yx();
                Ok(Retrieved::TerminalSize(x as u16, y as u16))
            }
            Value::CursorPosition => {
                let (y, x) = self.window.get_cur_yx();
                Ok(Retrieved::CursorPosition(y as u16, x as u16))
            }
            Value::Event(duration) => {
                if let Some(event) = self.try_take() {
                    return Ok(Retrieved::Event(Some(event)));
                }

                let duration = duration.map_or(-1, |f| f.as_millis() as i32);

                self.window.timeout(duration);

                if let Some(input) = self.window.getch() {
                    return Ok(Retrieved::Event(Some(self.parse_next(input))));
                }

                Ok(Retrieved::Event(None))
            }
        }
    }
}

impl<W: Write> Drop for BackendImpl<W> {
    fn drop(&mut self) {
        let _ = self.act(Action::DisableMouseCapture);
        crosscurses::endwin();
    }
}

impl<W: Write> Write for BackendImpl<W> {
    fn write(&mut self, buf: &[u8]) -> result::Result<usize, io::Error> {
        let string = std::str::from_utf8(buf).unwrap();
        let len = string.len();
        // We need to write strings to crosscurses window instead of directly to the buffer.
        self.print(string).unwrap();
        Ok(len)
    }

    fn flush(&mut self) -> result::Result<(), io::Error> {
        self.window.refresh();
        Ok(())
    }
}

fn initialize_keymap() -> HashMap<i32, Event> {
    let mut map = HashMap::default();

    fill_key_codes(&mut map, crosscurses::keyname);

    map
}

#[allow(clippy::eq_op)]
fn fill_key_codes<F>(target: &mut HashMap<i32, Event>, f: F)
where
    F: Fn(i32) -> Option<String>,
{
    let mut key_names = HashMap::<&str, KeyCode>::new();
    key_names.insert("DC", KeyCode::Delete);
    key_names.insert("DN", KeyCode::Down);
    key_names.insert("END", KeyCode::End);
    key_names.insert("HOM", KeyCode::Home);
    key_names.insert("IC", KeyCode::Insert);
    key_names.insert("LFT", KeyCode::Left);
    key_names.insert("NXT", KeyCode::PageDown);
    key_names.insert("PRV", KeyCode::PageUp);
    key_names.insert("RIT", KeyCode::Right);
    key_names.insert("UP", KeyCode::Up);

    for code in 512..1024 {
        let name = match f(code) {
            Some(name) => name,
            None => continue,
        };

        if !name.starts_with('k') {
            continue;
        }

        let (key_name, modifier) = name[1..].split_at(name.len() - 2);
        let key = match key_names.get(key_name) {
            Some(&key) => key,
            None => continue,
        };

        let event = match modifier {
            "3" => Event::Key(KeyEvent {
                code: key,
                modifiers: KeyModifiers::ALT,
            }),
            "4" => Event::Key(KeyEvent {
                code: key,
                modifiers: KeyModifiers::ALT | KeyModifiers::SHIFT,
            }),
            "5" => Event::Key(KeyEvent {
                code: key,
                modifiers: KeyModifiers::CONTROL,
            }),
            "6" => Event::Key(KeyEvent {
                code: key,
                modifiers: (KeyModifiers::CONTROL | KeyModifiers::CONTROL),
            }),
            "7" => Event::Key(KeyEvent {
                code: key,
                modifiers: (KeyModifiers::CONTROL | KeyModifiers::ALT),
            }),
            _ => continue,
        };

        target.insert(code, event);
    }
}

#[cfg(test)]
mod test {
    use crate::error;

    fn a(return_val: i32) -> error::Result<()> {
        check!(return_val);
        Ok(())
    }

    #[test]
    fn test_check_macro() {
        assert!(a(0).is_ok());
        assert!(a(1).is_ok());
        assert!(a(3).is_err());
        assert!(a(-1).is_err());
    }
}