facebookincubator/superconsole

The superconsole crate provides a handler and building blocks for powerful, yet minimally intrusive TUIs. It is cross platform, supporting Windows 7+, Linux, and MacOS. Rustaceans who want to create non-interactive TUIs can use the component composition building block system to quickly deploy their code.

A component-based framework for building Rust Text-based User Interfaces (TUIs)

There are several copies of this repo on GitHub, facebookincubator/superconsole is the canonical one.

The superconsole framework provides a powerful line based abstraction over text based rendering to the terminal. It also provides basic building blocks like line manipulation, and a higher level of composable components. A base set of "batteries" components are included to help developers create Text-based User Interfaces (TUIs) as quickly as possible.

The design choices that underly superconsole are selected to prioritize testability, ease of composition, and flexibility.

Superconsole also offers stylization, including italics, underlining, bolding, and coloring text. Furthermore, relying on crossterm ensures that it is compatible with Windows, Unix, and MacOS.

Finally, superconsole delineates between rendering logic and program state - each render call accepts an immutable reference to state, which components may use to inject state into their otherwise immutable rendering logic.

Demo

Examples

use std::convert::TryInto;
use superconsole::components::bordering::{Bordered, BorderedSpec};
use superconsole::{Component, Dimensions, DrawMode, Lines, SuperConsole};

#[derive(Debug)]
struct HelloWorld;

impl Component for HelloWorld {
    fn draw_unchecked(&self, _dimensions: Dimensions, _mode: DrawMode) -> anyhow::Result<Lines> {
        Ok(Lines(vec![
            vec!["Hello world!".to_owned()].try_into().unwrap(),
        ]))
    }
}

pub fn main() -> anyhow::Result<()> {
    let bordering = BorderedSpec::default();
    let mut superconsole = SuperConsole::new().ok_or_else(|| anyhow::anyhow!("Not a TTY"))?;
    let component = Bordered::new(HelloWorld, bordering);
    superconsole.render(&component)?;
    superconsole.finalize(&component)?;
    Ok(())
}

See the CONTRIBUTING file for how to help out.

License

Superconsole is both MIT and Apache License, Version 2.0 licensed, as found in the LICENSE-MIT and LICENSE-APACHE files.

superconsole's Issues

State is not very type safe

As i stated in my other issue [#5] I'm very much enjoying using this library. Thanks again!

I would love to have some more type safety around state. If I decide to change the type of some piece of state, the compiler isn't going to complain and I will hit runtime errors. If state were instead a generic type then I could fill that in with the state type for my app and run into these errors at compile time.

Interfaces for languages beyond Rust

This is exactly the library I've been looking for. However, I'd need to include it in a C++ project.

I don't have a lot of experience with Rust, so I'm not sure how viable it would be to make the superconsole interface available to languages like C++ or Python without having to re-write large parts of the core.

Any feedback on the viability would be appreciated.

Consider not using anyhow::Error

I recently started using superconsole and I really like it. Thanks for making this! 🙏

The use of anyhow presents a bit of an ergonomics problem however. For example, in my application I use eyre and I have to manually map_err your anyhow errors to eyre::Reports. It seems that under the hood you are using thiserror to define errors. Perhaps these could be brought up to the surface instead of wrapping them in anyhow::Error?

Remove `rust-toolchain` file

I do understand that using superconsole strictly as a dependency, I'm not really affected by the toolchain file.

My grumble is more on the QA side of things. Looks like the requirement for a pinned nightly version comes from some Meta internal CI or something. That rust-toolchain file kind of indicates, that superconsole is basically never build with current stable, no?

So, for the public superconsole repo, I think, the toolchain file should either be removed or use the stable channel.