insects/shtola
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: reconstruct ware source

Browse source
This commit is contained in:
liv 2023-03-19 17:16:49 +01:00
parent 9a474b7fd5
commit e91056fee5
6 changed files with 282 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
Cargo.lock generated
View file

@ -883,7 +883,7 @@ dependencies = [
"serde_yaml",
"tera",
"walkdir",
"ware",
"ware 2.0.1 (registry+https://github.com/rust-lang/crates.io-index)",
]
[[package]]
@ -1182,6 +1182,10 @@ dependencies = [
"winapi-util",
]
[[package]]
name = "ware"
version = "2.0.1"
[[package]]
name = "ware"
version = "2.0.1"

3
Cargo.toml
View file

@ -1,4 +1,5 @@
[workspace]
members = [
"shtola"
"shtola",
"ware"
]

15
ware/Cargo.toml Normal file
View file

@ -0,0 +1,15 @@
[package]
name = "ware"
description = "Simple middleware chains"
version = "2.0.1"
authors = ["Liv <shadows_withal@fastmail.com>"]
edition = "2021"
repository = "https://codeberg.org/shadows_withal/shtola/src/branch/main/ware"
documentation = "https://docs.rs/ware"
homepage = "https://codeberg.org/shadows_withal/shtola/src/branch/main/ware"
readme = "README.md"
categories = ["data-structures"]
keywords = ["middleware"]
license-file = "AGPL-3.0-or-later"
[dependencies]

83
ware/README.md Normal file
View file

@ -0,0 +1,83 @@
# Ware
Immutable and mutable middleware chains.
Ware allows you to create middleware chains that pass through and modify a value
as they go along. You can imagine a middleware chain as something like this:
```rust
let initial_value = 1;
fn middleware_1(value: i32) -> i32 {
value + 1
}
fn middleware_2(value: i32) -> i32 {
value * 5
}
let result = middleware_2(middleware_1(initial_value));
assert_eq!(result, 10);
```
## Mutable middleware
The default is middleware that has free access to mutate the value that's being passed
through, thanks to `RefCell`:
```rust
use ware::Ware;
use std::ops::{Add, Mul};
let mut middleware_chain: Ware<i32> = Ware::new();
middleware_chain.wrap(Box::new(|mut num| {
*num = num.add(1);
}));
middleware_chain.wrap(Box::new(|mut num| {
*num = num.mul(5);
}));
let result = middleware_chain.run(1);
assert_eq!(result, 10);
```
These middleware functions have to return a `()` unit struct, so the best
choice is to leave out a return statement.
Remember to always dereference the argument in a middleware function when directly reassigning,
because otherwise you're destroying the `RefCell`.
## Immutable middleware
If you instead want to rely on immutability, replace `ware::Ware` with `ware::im::Ware`:
```rust
use ware::im::Ware;
let mut middleware_chain: Ware<i32> = Ware::new();
middleware_chain.wrap(Box::new(|num| num + 1));
middleware_chain.wrap(Box::new(|num| num * 5));
let result = middleware_chain.run(1);
assert_eq!(result, 10);
```
Functions that get registered as middleware cannot directly modify their
variables, as they have be of the `Fn` trait. I would
recommend using immutable data structures that are efficient when duplicating values.
Generally, I'd recommend immutable `Ware` when you're working with simple data or when
immutability is absolutely critical to you. However, when you're working with more
complex data structures such as a `HashMap`, that provides its own modification tools,
you might want to opt for the mutable `Ware` instead. You cannot do both, either use the
mutable or the immutable variety.
## Documentation
The documentation is available at https://docs.rs/ware.
## License
Ware is licensed under the AGPL 3.0.

86
ware/src/im.rs Normal file
View file

@ -0,0 +1,86 @@
//! An immutable version of ware. Does not use RefCells, instead
//! relying on the user to return the modified variable in the closure.
//!
//! ## Example
//! ```
//! use ware::im::Ware;
//!
//! fn main() {
//! let mut chain: Ware<i32> = Ware::new();
//! chain.wrap(Box::new(|num| num * 10));
//! chain.wrap(Box::new(|num| num - 2));
//! let result = chain.run(5);
//! assert_eq!(result, 48);
//! }
//! ```
/// A middleware chain.
pub struct Ware<T> {
/// The internal list of middleware functions.
pub fns: Vec<Box<dyn Fn(T) -> T>>,
}
impl<T> Ware<T> {
/// Create a new middleware chain with a given type.
///
/// # Example
/// ```
/// use ware::im::Ware;
/// let mut chain: Ware<String> = Ware::new();
/// ```
pub fn new() -> Ware<T> {
let vec: Vec<Box<dyn Fn(T) -> T>> = Vec::new();
Ware { fns: vec }
}
/// Add a new middleware function to the internal function list. This function
/// must be of the `Fn` trait, take the specified type and return the same
/// specified type. It also has to be boxed for memory safety reasons.
///
/// # Example
/// ```
/// use ware::im::Ware;
/// let mut chain: Ware<String> = Ware::new();
/// chain.wrap(Box::new(|st| {
/// let mut s = st.clone();
/// s.push('a');
/// s
/// }))
/// ```
pub fn wrap(&mut self, func: Box<dyn Fn(T) -> T>) {
self.fns.push(func);
}
/// Run the registered middleware functions with the given value to pass
/// through. Returns whatever the last registered middleware function
/// returns.
pub fn run(&self, arg: T) -> T {
self.fns.iter().fold(arg, |acc, func| func(acc))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_works() {
let value = 1;
let mut w: Ware<i32> = Ware::new();
w.wrap(Box::new(|num| num + 1));
assert_eq!(w.run(value), 2);
}
#[test]
fn it_is_immutable() {
let value = 1;
let closure = |num| {
let num = num + 1;
num
};
let mut w: Ware<i32> = Ware::new();
w.wrap(Box::new(closure));
assert_eq!(w.run(value), 2);
assert_eq!(value, 1);
}
}

91
ware/src/lib.rs Normal file
View file

@ -0,0 +1,91 @@
//! Ware provides mutable and immutable middleware abstractions. Basically, it means that
//! you can pass one variable through a series of functions that all have the
//! ability to modify this variable, therefore sending this modified version of
//! it further down the chain.
//!
//! Ware is used like this:
//!
//! ```
//! use ware::Ware;
//! use std::ops::{Mul, Sub};
//!
//! fn main() {
//! let mut chain: Ware<i32> = Ware::new();
//! chain.wrap(Box::new(|mut num| {
//! *num = num.mul(5);
//! }));
//! chain.wrap(Box::new(|mut num| {
//! *num = num.sub(2);
//! }));
//! let result = chain.run(5);
//! assert_eq!(result, 23);
//! }
//! ```
use std::cell::{RefCell, RefMut};
pub mod im;
/// Shorthand version of `RefMut<T>`, if you don't want to import `RefMut`.
pub type WareArg<'a, T> = RefMut<'a, T>;
/// A middleware chain.
pub struct Ware<T> {
/// The internal list of middleware functions.
pub fns: Vec<Box<dyn Fn(WareArg<T>) -> ()>>,
}
impl<T> Ware<T> {
/// Create a new middleware chain with a given type.
///
/// # Example
/// ```
/// use ware::Ware;
/// let mut chain: Ware<String> = Ware::new();
/// ```
pub fn new() -> Ware<T> {
let vec: Vec<Box<dyn Fn(WareArg<T>) -> ()>> = Vec::new();
Ware { fns: vec }
}
/// Add a new middleware function to the internal function list. This function
/// must be of the `Fn` trait, take a `WareArg<T>` and return a unit struct (aka. nothing).
/// It also has to be boxed for memory safety reasons.
///
/// # Example
/// ```
/// use ware::Ware;
/// let mut chain: Ware<String> = Ware::new();
/// chain.wrap(Box::new(|mut st| {
/// st.push('a');
/// }))
/// ```
pub fn wrap(&mut self, func: Box<dyn Fn(WareArg<T>) -> ()>) {
self.fns.push(func);
}
/// Run the registered middleware functions with the given value to pass
/// through. Returns whatever the passed value will be after the last
/// middleware function runs.
pub fn run(&self, arg: T) -> T {
let ware_arg = RefCell::new(arg);
self.fns.iter().for_each(|func| func(ware_arg.borrow_mut()));
ware_arg.into_inner()
}
}
#[cfg(test)]
mod tests {
use std::ops::Add;
use super::*;
#[test]
fn it_works() {
let value = 1;
let mut w: Ware<i32> = Ware::new();
w.wrap(Box::new(|mut num| {
*num = num.add(1);
}));
assert_eq!(w.run(value), 2);
}
}