Crate r3bl_rs_utils

source · [−]
Expand description

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

  1. Thread-safe & fully asynchronous Redux library (using Tokio to run subscribers and middleware in separate tasks). The reducer functions are run sequentially.
  2. Loosely coupled & fully asynchronous TUI framework to make it possible (and easy) to build sophisticated TUIs (Text User Interface apps) in Rust. This is currently under active development.
  3. 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.
  4. Non binary tree data structure inspired by memory arenas, that is thread safe and supports parallel tree walking.
  5. Utility functions to improve ergonomics of commonly used patterns in Rust programming, ranging from things like colorizing stdout, stderr output, to having less noisy Result and Error types.

Learn more about how this library is built

Re-exports

pub use redux::*;
pub use tree_memory_arena::*;
pub use tui::*;
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
redux

References

tree_memory_arena

This module contains Arena a non-binary tree implementation that is thread safe, and MTArena a variant of the tree that supports parallel tree walking.

tui

tui package

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

This module contains a lot of utility functions that are meant to:

Macros

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 the 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.

colorize_using_lolcat

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

convert_to_base_unit

Converts a variety of types (i32, usize) to a UnitType.

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.

debug_log_no_err

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.

exec

Given a crossterm command, this will run it and log! the Result that is returned. If log! fails, then it will print a message to stderr.

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.

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.

make_api_call_for

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

make_safe_async_fn_wrapper
make_shareable_fn_wrapper
make_struct_safe_to_share_and_mutate
my_print

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

print_header
raw_mode

This will automatically disable raw mode when the enclosed block ends. Note that this macro must be called from a function that returns a Result.

spawn_and_consume_event

Helper macro that works w/ EventPropagation. This code block commonly appears in places where an input event is processed and an EventPropagation is returned.

spawn_dispatch_action
style
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.

trace_log_no_err

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

tw_command_queue

This works together w/ TWCommand to enqueue commands, but not flush them. It will return a TWCommandQueue. Here’s an example.

unwrap

Macros to unwrap various locks.

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>.

unwrap_or_err

Unwrap the $option, and if None then return the given $err_type. Otherwise return the unwrapped $option. 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.

Structs

ColorUtils
ColorWheelControl

A struct to contain info we need to print with every character.

CommonError

Common error struct. Docs

GraphemeClusterSegment
Lolcat
OutputCollector
Pair

Pair, defined as [left, right].

Percent

Represents an integer value between 0 and 100 (inclusive).

Position

Here is a visual representation of how position and sizing works for the layout engine.

RequestedSizePercent

Size, defined as [height, width].

Size

Here is a visual representation of how position and sizing works for the layout engine.

Style

Use the StyleBuilder to create a Style. Style objects are meant to be immutable. If you need to modify a Style, you should use the StyleBuilder to create a new one.

StyleFlag

https://docs.rs/bitflags/0.8.2/bitflags/macro.bitflags.html

Stylesheet
TWColor
UnicodeString

Enums

ColorChangeSpeed
CommonErrorType

Some common errors that can occur.

Traits

LolcatStringExt
SafeToMutate

This trait marks a type as being safe to mutate (interior mutability) across threads (parallel safe) and tasks (async safe). These are just convenience static methods. You can simply use the read() and write() methods directly on the Arc reference.

SafeToShare

This trait marks a type as being safe to share across threads (parallel safe) and tasks (async safe).

SupportsColor
UnicodeStringExt

A grapheme cluster is a user-perceived character. Rust uses UTF-8 to represent text in String. So each character takes up 8 bits or one byte. Grapheme clusters can take up many more bytes, eg 4 bytes or 2 or 3, etc.

Functions

calc_percentage

Return the calculated percentage of the given value.

eprint_header
print_header

Equivalent for template string literal. One way to do this using format!

strip_ansi
style_dimmed
style_error
style_primary
style_prompt

Type Definitions

CommonResult

Type alias to make it easy to work with Results.

OutputCollectorType
UnitType

Maps to whatever base units crossterm uses.

Derive Macros

Builder