Crate andiskaz

This crate provides basic utilities for writing applications with Terminal User Interface (TUI). It provides an event listener, and it provides a handle to a double buffered screen renderer.

Examples

This is an example for a simple Hello, World! application. For more examples, see examples folder.

use andiskaz::{
    color::Color2,
    emergency_restore,
    error::Error,
    event::Event,
    style::Style,
    terminal::Terminal,
    tstring,
};
use std::{panic, process::exit};

/// Asynchronous main of a tokio project.
#[tokio::main]
async fn main() {
    // Sets panic hook so we can see the panic even if terminal was being used
    // in raw mode.
    panic::set_hook(Box::new(|info| {
        let _ = emergency_restore();
        eprintln!("{}", info);
    }));

// Creates a terminal with default settings and runs it.
    let result = Terminal::run(term_main).await;
    // If error, prints it out and exits with bad code.
    if let Ok(Err(error)) | Err(error) = result {
        eprintln!("{}", error);
        exit(-1);
    }
}

/// The terminal main function.
async fn term_main(mut term: Terminal) -> Result<(), Error> {
    // Allocates memory for a string which is safe to be printed.
    let string = tstring!["Hello, World! Press any key..."];
    // Style for the string.
    let style = Style::with_colors(Color2::default());
    // Initial rendering.
    term.lock_now().await?.screen().styled_text(&string, style);

    loop {
        // Awaits for an event (key pressed, screen resized, etc).
        let mut session = term.listen().await?;

        // Gets the event for the current terminal session.
        match session.event() {
            // We expect a key to exit the example.
            Some(Event::Key(_)) => break,
            // User resized screen? Then the whole screen was thrown out,
            // re-rendering is required.
            Some(Event::Resize(_)) => {
                session.screen().styled_text(&string, style);
            },
            // Won't really happen since we waited for an event.
            None => (),
        }
    }

    Ok(())
}

Modules

color

This module provides colors that are usable with the terminal handle implemented by this library.

coord

Provides types related to the coordinate system.

error

This module exports error types used by the terminal handles.

event

This module defines input events of a terminal.

screen

This module defines screen related utilities.

string

This module provides a string type used to be printed to the terminal. It is called “TermString”. You can use the macro tstring! to build a TermString as a shortcut for TermString::new_lossy.

style

This module provides styles for terminal text.

terminal

This crate exports a terminal terminal and its utilites.

tile

This module exports items related to a “tile” in the screen, i.e. a character with foreground and background colors, corresponding to a graphic unit.

ui

UI helpers.

Macros

tdebug

Writes the given formatting expression into the file debug.txt.

tstring

Creates a TermString from string literal. Currently, invalid string get the unicode replacement character in their invalid characters. However, implementation may change to panic in those cases.

tstring_concat

Concatenates various TermString or TermString-like into a new TermString. It takes everything by reference, and it is possible to mix types.

Functions

emergency_restore

Best-effort function to restore the terminal in a panic.