feat: add engcon procedural macro with distillation column example

Author: DarthB

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - "**/**.md"
+      - "**/LICENSE"
+      - "**/.gitignore"
+      - "**/.github/ISSUE_TEMPLATE/**"
+      - "**/.config/**"
+  pull_request:
+    branches:
+      - master
+    paths-ignore:
+      - "**/**.md"
+      - "**/LICENSE"
+      - "**/.gitignore"
+      - "**/.github/ISSUE_TEMPLATE/**"
+      - "**/.config/**"
+
+jobs:
+  core:
+    uses: blackportal-ai/infra/.github/workflows/core.yml@master

.gitignore

@@ -5,7 +5,7 @@ target/
 
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
-Cargo.lock
+# Cargo.lock
 
 # These are backup files generated by rustfmt
 **/*.rs.bk

Cargo.lock

@@ -0,0 +1,3 @@
+[workspace]
+members = ["engcon", "engcon_macros", "examples/distillation"]
+resolver = "2"

Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "engcon"
+version = "0.1.0"
+edition = "2021"
+authors = ["Tim Janus <tim@janus.rs>"]
+license = "MIT OR Apache-2.0"
+
+description = "Helpful macros to define contracts for constraints at rust struct level."
+#keywords = ["engineering", "contracts"]
+#categories = []
+
+#documentation = "https://docs.rs/strum"
+homepage = "https://github.com/DarthB/engcon"
+repository = "https://github.com/DarthB/engcon"
+readme = "README.md"
+
+[features]
+derive = ["engcon_macros"]
+
+[dependencies]
+engcon_macros = { path = "../engcon_macros", optional = true, version = "0.1" }
+
+[dev-dependencies]
+engcon_macros = { path = "../engcon_macros", version = "0.1" }
+
+[package.metadata.docs.rs]
+features = ["derive"]
+rustdoc-args = ["--cfg", "docsrs"]

engcon/Cargo.toml

@@ -0,0 +1,183 @@
+//! # EngCon
+//!
+//! EngCon is a set of macros and traits defining contracts often found in
+//! engineering problems, e.g. the design of a distilation column.
+//!
+//! # Including EngCon in your Project
+//!
+//! Import engcon and engcon_macros into your project by adding the following lines to your Cargo.toml.
+//! engcon_macros contains the macros needed to derive the traits in EngCon.
+//!
+//! ```toml
+//! [dependencies]
+//! engcon = "0.1"
+//! engcon_macros = "0.1"
+//!
+//! # You can also access engcon_macros exports directly through strum using the "derive" feature
+//! engcon = { version = "0.1", features = ["derive"] }
+//! ```
+//!
+//! This pattern is also used by by the well known [strum crate](https://docs.rs/strum/latest/strum/) that has helpful procedural macros
+//! for enumerations.
+//!
+
+use std::{
+    error::Error,
+    fmt::Display,
+    ops::{Deref, DerefMut},
+};
+
+#[cfg(feature = "derive")]
+pub use engcon_macros::*;
+
+/// A new-type  that ensures validated data for a generic T.
+///
+/// Use the [Validatable] dervice macro and it's rules to
+/// implement define validation rules on a type T.
+///
+/// The type parameter `T` must be [Sized] and implement the [Validator] trait.
+pub struct Validated<T: Validator + Sized> {
+    inner: T,
+}
+
+/// An error type that is used when a validation error occurs
+#[derive(Debug, Clone, PartialEq)]
+pub struct ValidationError {
+    msg: String,
+    src: String,
+}
+
+/// Provides methods to validate and to transform into a [Validated] new-type.
+///
+/// Using the derive macro [Validatable] is recommended instead of a manual implemenation.
+pub trait Validator: Sized {
+    /// Checks if the underlying data is valid and returns an [ValidationError] if not.
+    ///
+    /// Using the derive macro [Validatable] is recommended instead of a
+    /// manual implemenation.
+    fn validate(&self) -> Result<(), ValidationError>;
+
+    /// tries to transform Self into a [Validated] may give an [ValidationError]
+    fn try_into_validated(self) -> Result<Validated<Self>, ValidationError> {
+        match self.validate() {
+            Ok(_) => {
+                // just checked if that is validated...
+                let reval = unsafe { Validated::new_unchecked(self) };
+                Ok(reval)
+            }
+            Err(err) => Err(err),
+        }
+    }
+}
+
+impl Error for ValidationError {}
+
+impl ValidationError {
+    pub fn new(msg: String, src: String) -> Self {
+        ValidationError { msg, src }
+    }
+}
+
+impl Display for ValidationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Error validating '{}': {}", self.src, self.msg)
+    }
+}
+
+impl<T: Validator + Sized> Validated<T> {
+    /// Generates a validated instance of T, usable for compile-time API safety.
+    ///
+    /// # Safety
+    /// The caller has to ensure Validator::validate returns true for that function
+    pub unsafe fn new_unchecked(inner: T) -> Self {
+        Validated::<T> { inner }
+    }
+
+    /// gets the inner unchecked type
+    pub fn into_inner(self) -> T {
+        self.inner
+    }
+}
+
+/* TODO: I don't get where a Into<Validated<T>> has been implemented...
+ *       All the codegen of TryFrom Into etc. was commented out once
+ * error[E0119]: conflicting implementations of trait `std::convert::TryFrom<_>` for type `Validated<_>`
+  --> engcon\src\lib.rs:69:1
+   |
+69 | impl<T: Validator + Sized> TryFrom<T> for Validated<T> {
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = note: conflicting implementation in crate `core`:
+           - impl<T, U> std::convert::TryFrom<U> for T
+             where U: std::convert::Into<T>;
+
+
+ */
+/*
+impl<T: Validator + Sized> TryFrom<T> for Validated<T> {
+    type Error = ValidationError;
+
+    fn try_from(value: T) -> Result<Self, Self::Error> {
+        match value.validate() {
+            Ok(_) => Ok(Validated::<T> { inner: value }),
+            Err(err) => Err(err),
+        }
+    }
+}
+ */
+
+impl<T: Validator + Sized> Deref for Validated<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<T: Validator + Sized> DerefMut for Validated<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+#[cfg(test)]
+mod tests {
+
+    #[derive(Debug, Clone, PartialEq)]
+    struct PlainOldData {
+        only_lower: String,
+    }
+
+    impl Validator for PlainOldData {
+        fn validate(&self) -> Result<(), ValidationError> {
+            if self.only_lower.chars().any(|ch| !ch.is_lowercase()) {
+                Err(ValidationError::new(
+                    "String is not entirely lower-case".to_owned(),
+                    "Src".to_owned(),
+                ))
+            } else {
+                Ok(())
+            }
+        }
+    }
+
+    use super::*;
+
+    #[test]
+    fn all_lowercase_works() {
+        let tmp = PlainOldData {
+            only_lower: "thisisonlylowercase".to_owned(),
+        };
+        let result = tmp.clone().validate();
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn whitespaces_are_errors() {
+        let tmp = PlainOldData {
+            only_lower: "this is not only lowercase".to_owned(),
+        };
+        let result = tmp.clone().validate();
+        assert!(result.is_err());
+    }
+}

engcon/src/lib.rs

@@ -0,0 +1,27 @@
+[package]
+name = "engcon_macros"
+version = "0.1.0"
+edition = "2021"
+authors = ["Tim Janus <tim@janus.rs>"]
+license = "MIT OR Apache-2.0"
+
+description = "Helpful macros to define contracts for constraints at rust struct level."
+#keywords = ["engineering", "contracts"]
+#categories = []
+
+#documentation = "https://docs.rs/strum"
+homepage = "https://github.com/DarthB/engcon"
+repository = "https://github.com/DarthB/engcon"
+readme = "README.md"
+
+[lib]
+path = "src/lib.rs"
+proc-macro = true
+
+[dependencies]
+syn = { version = "2.0", features = ["extra-traits"] }
+quote = { version = "1.0" }
+proc-macro2 = { version = "1.0" }
+
+[dev-dependencies]
+engcon = { path = "../engcon" }

engcon_macros/Cargo.toml

@@ -0,0 +1,56 @@
+use proc_macro2::Span;
+use syn::punctuated::Punctuated;
+use syn::Expr;
+use syn::Path;
+use syn::PathSegment;
+
+/// This Result returns in both cases a TokenStream whereby the TokenStream of the Error case
+/// contains at least one `compile_error!(...)` expression
+pub(crate) type MacroResult = std::result::Result<proc_macro::TokenStream, proc_macro::TokenStream>;
+
+/// converts a syn::Error to a tokenstream, useful in `map_err`
+pub(crate) fn synerr_to_tokens(err: syn::Error) -> proc_macro::TokenStream {
+    err.to_compile_error().into()
+}
+
+/// Adapts an expression that contains an ident `field` with a preceeding self generating: `self.field`
+pub(crate) fn adapt_ident_with_self(expr: &mut Expr) -> bool {
+    let adaption: Option<syn::ExprField> = match &expr {
+        Expr::Path(orig_path) => {
+            // check if we're using just an ident:
+            if orig_path.path.segments.len() == 1 {
+                let ident = orig_path.path.segments.first().unwrap().ident.clone();
+                let self_segment = PathSegment {
+                    ident: syn::Ident::new("self", Span::call_site()),
+                    arguments: syn::PathArguments::None,
+                };
+                let mut segments = Punctuated::new();
+                segments.push(self_segment);
+                Some(syn::ExprField {
+                    attrs: vec![],
+                    base: Box::new(Expr::Path(syn::ExprPath {
+                        attrs: vec![],
+                        qself: None,
+                        path: Path {
+                            leading_colon: None,
+                            segments,
+                        },
+                    })),
+                    dot_token: Default::default(),
+                    member: syn::Member::Named(ident),
+                })
+            } else {
+                None
+            }
+        }
+        _ => None,
+    };
+
+    // if we use an identifier without self. we adapt the statement here
+    if let Some(a) = adaption {
+        *expr = Expr::Field(a);
+        true
+    } else {
+        false
+    }
+}