feat: reconstruct ware source

Cargo.lock

@@ -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"

Cargo.toml

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

ware/Cargo.toml

@@ -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]

ware/README.md

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

ware/src/im.rs

@@ -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);
+    }
+}

ware/src/lib.rs

@@ -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);
+    }
+}