r3bl-open-core

R3BL TUI library & suite of apps focused on developer productivity

We are working on building command line apps in Rust which have rich text user interfaces (TUI). We want to lean into the terminal as a place of productivity, and build all kinds of awesome apps for it.

1. 🔮 Instead of just building one app, we are building a library to enable any kind of rich TUI development w/ a twist: taking concepts that work really well for the frontend mobile and web development world and re-imagining them for TUI & Rust.

• Taking inspiration from things like React, SolidJS, Elm, iced-rs, Jetpack Compose, JSX, CSS, but making everything async (so they can be run in parallel & concurrent via Tokio).
• Even the thread running the main event loop doesn't block since it is async.
• Using macros to create DSLs to implement something inspired by CSS & JSX.

2. 🌎 We are building apps to enhance developer productivity & workflows.

• The idea here is not to rebuild tmux in Rust (separate processes mux'd onto a single terminal window). Rather it is to build a set of integrated "apps" (or "tasks") that run in the same process that renders to one terminal window.
• Inside of this terminal window, we can implement things like "applet" switching, routing, tiling layout, stacking layout, etc. so that we can manage a lot of TUI apps (which are tightly integrated) that are running in the same process, in the same window. So you can imagine that all these "applets" have shared application state. Each "applet" may also have its own local application state.
• You can mix and match "Full TUI" with "Partial TUI" to build for whatever use case you need. r3bl_tui allows you to create application state that can be moved between various "applets", where each "applet" can be "Full TUI" or "Partial TUI".
• Here are some examples of the types of "app"s we plan to build (for which this infrastructure acts as the open source engine):
  1. Multi user text editors w/ syntax highlighting.
  2. Integrations w/ github issues.
  3. Integrations w/ calendar, email, contacts APIs.

Welcome to the monorepo and workspace

All the crates in the r3bl-open-core monorepo provide lots of useful functionality to help you build TUI (text user interface) apps, along w/ general niceties & ergonomics that all Rustaceans 🦀 can enjoy 🎉.

Any top-level folder in this repository that contains a Cargo.toml file is a Rust project, also known as a crate. These crates are likely published to crates.io. Together, they form a Rust workspace.

Here's the changelog for this monorepo containing a Rust workspace. The changelog is a great place to start to get familiar with what has changed recently in each of the crates in this Rust workspace.

Table of contents:

• This workspace contains crates for building TUI, CLI, TTY apps
  • Full TUI (async, raw mode, full screen) for immersive TUI apps
  • Partial TUI (async, partial raw mode, async readline) for choice-based user interaction
  • Partial TUI (async, partial raw mode, async readline) for async REPL
• Power via composition
  • Main library crate
  • Main binary crate
• Learn how these crates are built, provide feedback
• Build the workspace and run tests
• Star History
• Archive

This workspace contains crates for building TUI, CLI, TTY apps

The r3bl_tui crate is the main crate that contains the core functionality for building TUI apps. It allows you to build apps that range from "full" TUI to "partial" TUI, and everything in the middle.

Here are some videos that you can watch to get a better understanding of TTY programming.

• Build with Naz: TTY playlist
• Build with Naz: async readline

Full TUI (async, raw mode, full screen) for immersive TUI apps

tui gives you "raw mode", "alternate screen" and "full screen" support, while being totally async. An example of this is the "Full TUI" app edi in the r3bl-cmdr crate. You can install & run this with the following command:

cargo install r3bl-cmdr
edi

Partial TUI (async, partial raw mode, async readline) for choice based user interaction

choose allows you to build less interactive apps that ask a user user to make choices from a list of options and then use a decision tree to perform actions.

An example of this is this "Partial TUI" app giti in the r3bl-cmdr crate. You can install & run this with the following command:

cargo install r3bl-cmdr
giti

Partial TUI (async, partial raw mode, async readline) for async REPL

readline_async gives you the ability to easily ask for user input in a line editor. You can customize the prompt, and other behaviors, like input history.

Using this, you can build your own async shell programs using "async readline & stdout". Use advanced features like showing indeterminate progress spinners, and even write to stdout in an async manner, without clobbering the prompt / async readline, or the spinner. When the spinner is active, it pauses output to stdout, and resumes it when the spinner is stopped.

An example of this is this "Partial TUI" app giti in the r3bl-cmdr crate. You can install & run this with the following command:

cargo install r3bl-cmdr
giti

Here are other examples of this:

1. https://github.com/nazmulidris/rust-scratch/tree/main/tcp-api-server
2. https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples

Power via composition

You can mix and match "Full TUI" with "Partial TUI" to build for whatever use case you need. r3bl_tui allows you to create application state that can be moved between various "applets", where each "applet" can be "Full TUI" or "Partial TUI".

Main library crate

There is just one main library crate in this workspace: r3bl_tui.

Main binary crate

There is just one main binary crate that contains user facing apps that are built using the library crates: r3bl-cmdr. This crate contains these apps:

• giti: Interactive git workflows made easy.
• edi: Beautiful Markdown editor with advanced rendering and editing features.

You can install & run this with the following command:

cargo install r3bl-cmdr
# Interactive git workflows made easy.
giti --version
# Beautiful Markdown editor with advanced rendering and editing features.
edi --version

Learn how these crates are built, provide feedback

To learn how we built this crate, please take a look at the following resources.

• If you like consuming video content, here's our YT channel. Please consider subscribing.
• If you like consuming written content, here's our developer site.
• If you have questions, please join our discord server.

Build the workspace and run tests

There's a nushell script that you can use to run the build and release pipeline for this workspace, and more (local only operations).

To get a list of these, you can review the nushell script in the root of this repo run.nu. To get an idea of the commands that you can run, try running the following command:

cargo install nu
nu run.nu

You should see output that looks like this:

Usage: run <command> [args]
<command> can be:
    all
    all-cicd
    build
    build-full
    clean
    install-cargo-tools
    test
    watch-all-tests
    docs
    check
    check-watch
    clippy
    clippy-watch
    rustfmt
    upgrade-deps
    serve-docs
    audit-deps
    unmaintained
    ramdisk-create
    ramdisk-delete
    build-server
    help

For example:

• The nu run.nu all-cicd command will run the build and release pipeline for this workspace.
• However, you can run the nu run.nu all command to run the above command and more: install all the necessary tooling required for the script to work.

Each crate that's contained in this workspace may also have its own nushell script that is also named run.nu. This is a convention that is used in this workspace.

• You can run the run.nu script in each of the crates to get a list of commands that are specific to that crate.
• For e.g., this is how you can run all the tui examples:

  cd tui
  nu run.nu examples

Star History

Archive

As this repo grows, changes, and matures, pruning is necessary. The r3bl-open-core-archive is where all the code and artifacts that are no longer needed are moved to.

This way nothing is "lost" and if you need to use some of the code that was removed, you can find it there.

Also if you want to make changes to this code and maintain it yourself, please let us know.

1. You can submit PRs and we can also accept them, and publish them to crates.io if that makes sense.
2. Or we can even work out and arrangements to move ownership of the code & crate to you if you would like to commit to maintaining it.