Crate r3bl_rs_utils_core

Expand description

§Why R3BL?

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 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 proc macros to create DSLs to implement something inspired by 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

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

§Table of contents

Introduction
Changelog
Learn how these crates are built, provide feedback

§Introduction

This crate provides lots of low level functionality like Unicode strings (that support emoji), text styling, and more.

It is a dependency of the following crates:

r3bl_tui
r3bl_tuify
r3bl_terminal_async
r3bl_cmdr
r3bl_rs_utils_macro (procedural macros)
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. However, this r3bl_rs_utils crate isn’t really used anymore. It is possible to simply add a dependency on the r3bl_rs_utils_core crate directly, and r3bl_tui for instance.

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.

§Changelog

Please check out the changelog to see how the library has evolved over time.

§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. Please consider subscribing to our newsletter.
If you have questions, please join our discord server.

Re-exports§

pub use calc_str_len::*;
pub use color_text::color_text_default_styles::*;
pub use color_text::*;
pub use common::*;
pub use tui_core::*;
pub use utils::*;

Modules§

calc_str_len
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: A wrapper for pretty_assertions::assert_eq! macro.
assert_eq2_og: Similar to assert_eq! but automatically prints the left and right hand side variables if the assertion fails.
call_if_true: Syntactic sugar to run a conditional statement. Here’s an example.
ch: Creates a new ChUnit amount.
color
debug: This is a really simple macro to make it effortless to use the color console logger.
dec_unsigned: Safely decrements an unsigned number. Does not panic.
get_tui_style
get_tui_styles
inc_unsigned: Safely increments an unsigned number. Does not panic.
mul_unsigned
ok: Simple macro to create a Result with an Ok variant. It is just syntactic sugar that helps having to write Ok(()).
percent
position
print_header
requested_size_percent
send_signal: Send a signal to the main thread of app to render. The two things to pass in this macro are
size: Example:
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.
timed: A decl macro that generates code to measure the performance of the block that it surrounds.
tui_stylesheet: Macro to make building TuiStylesheet easy.
unwrap_option_or_compute_if_none: 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.

Crate r3bl_rs_utils_coreCopy item path