r3blrsutils

• Usage
• redux
• Macros
  • Declarative
  • debug!
  • Procedural
  • #[derive(Builder)]
  • makestructsafetoshareandmutate!
  • makesafeasyncfnwrapper!
• treememoryarena (non-binary tree data structure)
• utils
  • LazyMemoValues
  • tty
  • safeunwrap
  • colortext
• tui (experimental)
• Stability

This library provides utility functions:

1. Thread safe asynchronous Redux library (uses Tokio to run subscribers and middleware in separate tasks). The reducer functions are run in sequence (not in Tokio tasks).
2. 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.
3. Non binary tree data structure inspired by memory arenas, that is thread safe and supports parallel tree walking.
4. Functions to unwrap deeply nested objects inspired by Kotlin scope functions.
5. Capabilities to make it easier to build TUIs (Text User Interface apps) in Rust. This is currently experimental and is being actively developed.

💡 To learn more about this library, please read how it was built on developerlife.com:

1. https://developerlife.com/2022/02/24/rust-non-binary-tree/
2. https://developerlife.com/2022/03/12/rust-redux/
3. https://developerlife.com/2022/03/30/rust-proc-macro/

💡 You can also read all the Rust content on developerlife.com here. Also, the equivalent of this library is available for TypeScript and is called r3bl-ts-utils.

Usage

Please add the following to your Cargo.toml file:

toml [dependencies] r3bl_rs_utils = "0.7.14"

redux

Store is thread safe and asynchronous (using Tokio). You have to implement async traits in order to use it, by defining your own reducer, subscriber, and middleware trait objects.

• The middleware, subscribers will be run in asynchronously via Tokio tasks. However, they are run one after another (in the order in which they're added).
• The reducer functions are also are async functions that are run in the tokio runtime. They're also run one after another in the order in which they're added. A macro fire_and_forget! is provided so that you can spawn parallel blocks of code in your async functions.

⚡ Any functions or blocks that you write which uses the Redux library will have to be marked async as well. And you will have to spawn the Tokio runtime by using the #[tokio::main] macro. If you use the default runtime then Tokio will use multiple threads and its task stealing implementation to give you parallel and concurrent behavior. You can also use the single threaded runtime; its really up to you.

1. To create middleware you have to implement the AsyncMiddleware trait.
   • If the run() method returns a Some(Action) then the action will be dispatched to the store. If None is returned, then nothing is dispatched.
   • The run() method will be passed two arguments: the Store and the Action.
   • You can use the Store reference to dispatch an action if you're using the fire_and_forget! macro.
   • Please read the AsyncMiddleware docs to make sure that you are not deadlocking.
2. To create reducers you have to implement the AsyncReducer trait.
   • These should be pure functions and simply return a new State object.
   • The run() method will be passed two arguments: a ref to Action and ref to State.
3. To create subscribers you have to implement the AsyncSubscriber trait.
   • The run() method will be passed a State object as an argument.
   • It returns nothing ().

Here's the gist of how to make & use one of these:

1. Create a struct. Make it derive Default. Or you can add your own properties / fields to this struct, and construct it yourself, or even provide a constructor function.
   • A default constructor function new() is provided for you by the trait.
   • Just follow that works for when you need to make your own constructor function for a struct w/ your own properties.
2. Implement the AsyncMiddleware, AsyncReducer, or AsyncSubscriber trait on your struct.
3. Register this struct w/ the store using one of the add_middleware(), add_reducer(), or add_subscriber() methods. You can register multiple of these.
   • If you have a struct w/ no properties, you can just use the default ::new() method to create an instance and pass that to the add_???() methods.
   • If you have a struct w/ custom properties, you can either implement your own constructor function or use the following as an argument to the add_???() methods: Arc::new(RwLock::new($YOUR_STRUCT)).

Here's an example of how to use it. Let's say we have the following action enum, and state struct.

💡 There are lots of examples in the tests for this library and in this CLI application built using it.

```rust /// Action enum.

[derive(Debug, PartialEq, Eq, Hash, Clone)]

pub enum Action { Add(i32, i32), AddPop(i32), Clear, MiddlewareCreateClearAction, Noop, }

impl Default for Action { fn default() -> Self { Action::Noop } }

/// State.

[derive(Clone, Default, PartialEq, Debug, Hash)]

pub struct State { pub stack: Vec, } ```

Here's an example of the reducer function.

```rust /// Reducer function (pure).

[derive(Default)]

struct MyReducer;

[async_trait]

impl AsyncReducer for MyReducer { async fn run( &self, action: &Action, state: &State, ) -> State { match action { Action::Add(a, b) => { let sum = a + b; State { stack: vec![sum] } } Action::AddPop(a) => { let sum = a + state.stack[0]; State { stack: vec![sum] } } Action::Clear => State { stack: vec![] }, _ => state.clone(), } } } ```

Here's an example of an async subscriber function (which are run in parallel after an action is dispatched). The following example uses a lambda that captures a shared object. This is a pretty common pattern that you might encounter when creating subscribers that share state in your enclosing block or scope.

```rust /// This shared object is used to collect results from the subscriber /// function & test it later. let shared_object = Arc::new(Mutex::new(Vec::::new()));

[derive(Default)]

struct MySubscriber { pub sharedobjectref: Arc>>, }

[async_trait]

impl AsyncSubscriber for MySubscriber { async fn run( &self, state: State, ) { let mut stack = self .sharedobjectref .lock() .unwrap(); if !state.stack.is_empty() { stack.push(state.stack[0]); } } }

let mysubscriber = MySubscriber { sharedobjectref: sharedobject_ref.clone(), }; ```

Here are two types of async middleware functions. One that returns an action (which will get dispatched once this middleware returns), and another that doesn't return anything (like a logger middleware that just dumps the current action to the console). Note that both these functions share the shared_object reference from above.

```rust /// This middleware function is curried to capture a reference to the /// shared object.

[derive(Default)]

struct MwReturnsNone { pub sharedobjectref: Arc>>, }

[async_trait]

impl AsyncMiddleware for MwReturnsNone { async fn run( &self, action: Action, storeref: Arc>>, ) -> Option { let mut stack = self .sharedobjectref .lock() .unwrap(); match action { Action::MwReturnsNoneAdd(, ) => stack.push(-1), Action::MwReturnsNoneAddPop() => stack.push(-2), Action::MwReturnsNoneClear => stack.push(-3), _ => {} } None } }

let mwreturnsnone = MwReturnsNone { sharedobjectref: sharedobjectref.clone(), };

/// This middleware function is curried to capture a reference to the /// shared object.

[derive(Default)]

struct MwReturnsAction { pub sharedobjectref: Arc>>, }

[async_trait]

impl AsyncMiddleware for MwReturnsAction { async fn run( &self, action: Action, storeref: Arc>>, ) -> Option { let mut stack = self .sharedobjectref .lock() .unwrap(); match action { Action::MwReturnsAction_SetState => stack.push(-4), _ => {} } Some(Action::Clear) } }

let mwreturnsaction = MwReturnsAction { sharedobjectref: sharedobjectref.clone(), }; ```

Here's how you can setup a store with the above reducer, middleware, and subscriber functions.

rust // Setup store. let mut store = Store::<State, Action>::default(); store .add_reducer(MyReducer::new()) // Note the use of `new()` here. .await .add_subscriber(Arc::new(RwLock::new( // We aren't using `new()` here my_subscriber, // because the struct has properties. ))) .await .add_middleware(Arc::new(RwLock::new( // We aren't using `new()` here mw_returns_action, // because the struct has properties. ))) .await .add_middleware(Arc::new(RwLock::new( // We aren't using `new()` here mw_returns_none, // because the struct has properties. ))) .await;

Finally here's an example of how to dispatch an action in a test. You can dispatch actions asynchronously using dispatch_spawn() which is "fire and forget" meaning that the caller won't block or wait for the dispatch_spawn() to return. Then you can dispatch actions synchronously if that's what you would like using dispatch().

```rust // Test reducer and subscriber by dispatching Add and AddPop actions asynchronously. store.dispatchspawn(Action::Add(10, 10)).await; store.dispatch(&Action::Add(1, 2)).await; asserteq!(sharedobject.lock().unwrap().pop(), Some(3)); store.dispatch(&Action::AddPop(1)).await; asserteq!(sharedobject.lock().unwrap().pop(), Some(21)); store.clearsubscribers().await;

// Test async middleware: mwreturnsaction. sharedobject.lock().unwrap().clear(); store .addmiddleware(SafeMiddlewareFnWrapper::new(mwreturnsaction)) .dispatch(&Action::MiddlewareCreateClearAction) .await; asserteq!(store.getstate().stack.len(), 0); asserteq!(sharedobject.lock().unwrap().pop(), Some(-4)); ```

Macros

Declarative

There are quite a few declarative macros that you will find in the library. They tend to be used internally in the implementation of the library itself. Here are some that are actually externally exposed via #[macro_export].

debug!

This is a really simple macro to make it effortless to use the color console logger. It takes an identifier as an argument. It simply dumps an arrow symbol, followed by the identifier (stringified) 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.

rust let my_string = "Hello World!"; debug!(my_string);

Procedural

All the procedural macros are organized in 3 crates using an internal or core crate: the public crate, an internal or core crate, and the proc macro crate.

#[derive(Builder)]

This derive macro makes it easy to generate builders when annotating a struct or enum. It generates It has full support for generics. It can be used like this.

```rust

[derive(Builder)]

struct Point where X: std::fmt::Display + Clone, Y: std::fmt::Display + Clone, { x: X, y: Y, }

let mypt: Point = PointBuilder::new() .setx(1 as i32) .set_y(2 as i32) .build();

asserteq!(mypt.x, 1); asserteq!(mypt.y, 2); ```

makestructsafetoshareandmutate!

This function like macro (with custom syntax) makes it easy to manage shareability and interior mutability of a struct. We call this pattern the "manager" of "things").

🪄 You can read all about it here.

1. This struct gets wrapped in a RwLock for thread safety.
2. That is then wrapped inside an Arc so we can share it across threads.
3. Additionally it works w/ Tokio so that it is totally async. It also fully supports generics and trait bounds w/ an optional where clause.

Here's a very simple usage:

rust make_struct_safe_to_share_and_mutate! { named MyMapManager<K, V> where K: Default + Send + Sync + 'static, V: Default + Send + Sync + 'static containing my_map of_type std::collections::HashMap<K, V> }

Here's an async example.

```rust

[tokio::test]

async fn testcustomsyntaxnowhereclause() { makestructsafetoshareandmutate! { named StringMap // where is optional and is missing here. containing mymap of_type std::collections::HashMap }

let mymanager: StringMap = StringMap::default(); let lockedmap = mymanager.mymap.read().await; asserteq!(lockedmap.len(), 0); drop(locked_map); } ```

makesafeasyncfnwrapper!

This function like macro (with custom syntax) makes it easy to share functions and lambdas that are async. They should be safe to share between threads and they should support either being invoked or spawned.

🪄 You can read all about how to write proc macros here.

1. A struct is generated that wraps the given function or lambda in an Arc<RwLock<>> for thread safety and interior mutability.
2. A get() method is generated which makes it possible to share this struct across threads.
3. A from() method is generated which makes it easy to create this struct from a function or lambda.
4. A spawn() method is generated which makes it possible to spawn the enclosed function or lambda asynchronously using Tokio.
5. An invoke() method is generated which makes it possible to invoke the enclosed function or lambda synchronously.

Here's an example of how to use this macro.

```rust use r3blrsutils::makesafeasyncfnwrapper;

makesafeasyncfnwrapper! { named SafeMiddlewareFnWrapper containing fnmut oftype FnMut(A) -> Option } ```

let result_node_list = thread_handle.join().unwrap();
println!("{:#?}", result_node_list);

let result_node_list = thread_handle.join().unwrap();
println!("{:#?}", result_node_list);