Crate r3bl_rs_utils_core

Expand description

Context

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.

🔮 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 things like React, JSX, CSS, and Redux, but making everything async (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 proc macros to create DSLs to implement CSS & JSX.
🌎 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 “app” 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 “app“s have shared application state (that is in a Redux store). Each “app” may also have its own Redux store.
- Here are some examples of the types of “app“s we want to build:
  1. multi user text editors w/ syntax highlighting
  2. integrations w/ github issues
  3. integrations w/ calendar, email, contacts APIs

These crates provides lots of useful functionality to help you build TUI (text user interface) apps, along w/ general niceties & ergonomics that all Rustaceans 🦀 can enjoy 🎉:

Loosely coupled & fully asynchronous TUI framework to make it possible (and easy) to build sophisticated TUIs (Text User Interface apps) in Rust that are inspired by React, Redux, CSS and Flexbox.
Thread-safe & fully asynchronous Redux crate (using Tokio to run subscribers and middleware in separate tasks). The reducer functions are run sequentially.
Lots of declarative macros, and procedural macros (both function like and derive) to avoid having to write lots of boilerplate code for many common (and complex) tasks. And even less noisy Result and Error types.
Non binary tree data structure inspired by memory arenas, that is thread safe and supports parallel tree walking.
Utility functions to improve ergonomics of commonly used patterns in Rust programming, ranging from things like colorizing stdout, stderr output to lazy value holders.

Learn more about how this library is built

🦜 Here are some articles (on developerlife.com) about how this crate is made:

🦀 You can also find all the Rust related content on developerlife.com here.

Other crates that depend on this crate

This crate is a dependency of the following crates:

r3bl_rs_utils_macro (procedural macros)
r3bl_tui
r3bl_redux
r3bl_rs_utils

Due to the requirements of proc macros being in a separate crate, this breakdown of one crate into multiple crates is necessary:

Put some code in a separate crate (r3bl_rs_utils_core) that is used by other crates.
Put the proc macros in a separate crate (r3bl_rs_utils_macro). This crate also depends on the r3bl_rs_utils_core crate.
Finally, make the “public” crate (r3bl_rs_utils) depend on the other two.

As a way to hide this kind of layering from the users of the “main” r3bl_rs_utils crate, all the modules tend to be re-exported, making them available from the “main” or top-level crate; more info on this here.

Re-exports

pub use async_safe_share_mutate::*;

pub use color_text::styles::*;

pub use color_text::*;

pub use common::*;

pub use decl_macros::*;

pub use tui_core::*;

pub use utils::*;

Modules

async_safe_share_mutate

color_text

ANSI colorized text https://github.com/ogham/rust-ansi-term helper methods.

common

decl_macros

tui_core

All the modules in the r3bl_rs_utils_core crate are in support of the tui module in the “main” r3bl_rs_utils crate.

utils

Macros

add_unsigned

Safely adds two unsigned numbers and returns the result. Does not panic.

assert_eq2

Similar to assert_eq! but automatically prints the left and right hand side variables if the assertion fails. Useful for debugging tests, since cargo would just print out the left and right values w/out providing information on what variables were being compared.

call_if_true

Syntactic sugar to run a conditional statement. Here’s an example.

ch

Creates a new ChUnit amount.

color

colorize_using_lolcat

Given a mutable Lolcat, colorize the token tree that follows.

debug

This is a really simple macro to make it effortless to use the color console logger. It takes a single identifier as an argument, or any number of them. It simply dumps an arrow symbol, followed by the identifier (stringify’d) along with the value that it contains (using the Debug formatter). All of the output is colorized for easy readability. You can use it like this.

dec_unsigned

Safely decrements an unsigned number. Does not panic.

fire_and_forget

Declarative macro to surround the given block with a call to tokio::spawn. This is useful for spawning a task that will run in the background from a function that is NOT async.

get_style

get_styles

inc_unsigned

Safely increments an unsigned number. Does not panic.

log

This macro will log the message if the log level is set to the given level. The log is output to a file logger. Since there could be issues w/ accessing this file, this macro can itself throw an error. This is why it returns a CommonResult. If you want to use a version of this macro that does not throw an error, use log_no_err!.

log_no_err

This is very similar to log! except that if it fails, it will not propagate the log error. Here’s an example.

log_no_err_debug

This is a really simple macro to make it effortless to debug into a log. It takes a single identifier as an argument, or any number of them. It simply dumps an arrow symbol, followed by the identifier (stringify’d) along with the value that it contains (using the Debug formatter). All of the output is colorized for easy readability. You can use it like this.

log_no_err_trace

Very similar to log_no_err_debug! except that it outputs TRACE. Here’s an example.

make_api_call_for

Declarative macro to generate the API call functions. This adds the following:

mul_unsigned

my_print

Docs: https://doc.rust-lang.org/stable/std/fmt/struct.Arguments.html

percent

position

print_header

requested_size_percent

size

Example:

stylesheet

Macro to make building Stylesheet easy.

sub_unsigned

Safely subtracts two unsigned numbers and returns the result. Does not panic.

throws

Wrap the given block or stmt so that it returns a Result<()>. It is just syntactic sugar that helps having to write Ok(()) repeatedly.

throws_with_return

Wrap the given block or stmt so that it returns a Result<$it>. It is just syntactic sugar that helps having to write Ok($it) repeatedly.

unwrap_option_or_compute_if_none

Unwrap the $option, and if None then run the $next closure which must return a value that is set to $option. Basically a way to compute something lazily when it (the Option) is set to None.

unwrap_option_or_run_fn_returning_err

Unwrap the $option, and if None then run the $next closure which must return an error. This macro must be called in a block that returns a CommonResult<T>.

with

Runs the $code block after evaluating the $eval expression and assigning it to $id.

with_mut

Similar to with! except $id is a mutable reference to the $eval expression.

with_mut_returns

Similar to with_mut! except that it returns the value of the $code block.