Implement guard expressions

Author: michalsustr

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog][keepachangelog], and this project
 adheres to [Semantic Versioning][semver].
 
+
+## [0.0.3] - 2025-04-26
+### Update
+* Improve error messages.
+* Add support for guards expressions.
+* strum_macros is no longer a dependency.
+* Nicer mermaid diagrams for self-transitions.
+* Dropped `dot` feature due to ugly output.
+
 ## [0.0.2] - 2025-04-23
 ### Update
 * Improve documentation.

Makefile

@@ -5,10 +5,10 @@ test:
 	TMPDIR=~/tmp cargo test
 
 doc:
-	RUSTDOCFLAGS="--html-in-header ./examples/assets/graphviz-header.html" cargo doc --no-deps --document-private-items
+	cargo doc --no-deps --document-private-items
 
 doc-open:
-	RUSTDOCFLAGS="--html-in-header ./examples/assets/graphviz-header.html" cargo doc --no-deps --document-private-items--open
+	cargo doc --no-deps --document-private-items--open
 
 clean:
 	cargo clean

README.md

@@ -109,14 +109,12 @@ Major:
 - [ ] Add support for capturing traces of the machine and replaying them.
 
 Minor (soon):
-- [ ] Guards as bool expressions
+- [x] Guards as bool expressions
+- [ ] Performance improvements
 - [ ] Logging transitions -- tracing?
-- [ ] Configurable `should_panic` for invalid transitions
+- [ ] Configurable `should_panic` for invalid transitions  
 - [ ] Better error messages
   - sig checks for guards
-  - `dont_expand` for debugging
-- [ ] Reconsider if handlers should get mut self, based on usage examples.
-- [ ] better doc links, nicer dot links
 
 ## Contributions are welcome!
 
@@ -131,7 +129,6 @@ Also, I'd be happy if you star the repo!
 ## Feature flags
 
 - `mermaid` - generate Mermaid state diagrams in the doc strings. 
-- `dot` - generate DOT state diagrams in the doc strings.
 - `dsl` (default) - re-export the DSL into doc strings.
 
 ## Without DSL

examples/Cargo.toml

@@ -4,4 +4,4 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-rust-automata = { path = "../rust-automata", version = "0.0.2", features = ["mermaid", "dot", "dsl"] }
+rust-automata = { path = "../rust-automata", version = "0.0.3", features = ["mermaid", "dsl"] }

examples/assets/graphviz-header.html

@@ -84,7 +84,7 @@ pub mod inputs {
         (states::Closed, inputs::Fail)    -> (states::Closed) :  guard_below_threshold = handle_count_increment,
         (states::Closed, inputs::Fail)    -> (states::Open)   :  guard_not_below_threshold = handle_trip_breaker,
 
-        (states::Open) -> (states::Open)     :  guard_not_timeout,
+        (states::Open) -> (states::Open)     :  !guard_timeout,
         (states::Open) -> (states::HalfOpen) :  guard_timeout,
 
         (states::HalfOpen, inputs::Fail)    -> (states::Open) = handle_setup_timer,
@@ -108,13 +108,14 @@ impl CircuitBreaker {
     fn guard_not_below_threshold(&self, closed: &states::Closed) -> bool {
         closed.count >= self.threshold
     }
-    fn guard_not_timeout(&self, open: &states::Open) -> bool {
-        !open.timer.is_timeout()
-    }
     fn handle_count_reset(&mut self, _: states::Closed, _: inputs::Success) -> states::Closed {
         states::Closed { count: 0 }
     }
-    fn handle_count_increment(&mut self, closed: states::Closed, _: inputs::Fail) -> states::Closed {
+    fn handle_count_increment(
+        &mut self,
+        closed: states::Closed,
+        _: inputs::Fail,
+    ) -> states::Closed {
         states::Closed {
             count: closed.count + 1,
         }

examples/src/circuit_breaker.rs

@@ -8,7 +8,7 @@ readme = "README.md"
 license = "MIT"
 categories = ["data-structures", "rust-patterns"]
 keywords = ["fsm", "automata", "state", "machine"]
-version = "0.0.2"
+version = "0.0.3"
 authors = ["Michal Sustr"]
 edition = "2021"
 
@@ -17,7 +17,6 @@ proc-macro = true
 
 [features]
 mermaid = []
-dot = []
 dsl = []
 
 [dependencies]

rust-automata-macros/Cargo.toml

@@ -4,6 +4,7 @@ use quote::quote;
 
 #[cfg(feature = "dsl")]
 pub fn attr(m: &parser::MachineAttr) -> TokenStream2 {
+    use crate::parser::guard_expr_to_string;
     use crate::util;
     use crate::util::key;
     use std::fmt::Write;
@@ -113,7 +114,12 @@ pub fn attr(m: &parser::MachineAttr) -> TokenStream2 {
 
             // Add guard if present
             if let Some(ref guard) = tr.guard {
-                write!(dsl, " : {}", guard).unwrap();
+                write!(
+                    dsl,
+                    " : {}",
+                    guard_expr_to_string(guard, &|path| util::key(path))
+                )
+                .unwrap();
             }
 
             // Add handler if present

rust-automata-macros/src/annotations/dot.rs

@@ -5,10 +5,10 @@ use quote::quote;
 #[cfg(feature = "mermaid")]
 fn transition_label(tr: &parser::Transition) -> String {
     use crate::annotations::doc_link;
+    use crate::parser::guard_expr_to_string;
     use crate::util;
     use crate::GUARD_PREFIX;
     use crate::HANDLE_PREFIX;
-
     let mut label = String::new();
     if let Some(ref i) = tr.input {
         let ev = util::last(i);
@@ -24,15 +24,23 @@ fn transition_label(tr: &parser::Transition) -> String {
         ));
     }
     if let Some(ref g) = tr.guard {
+        let guard_str = guard_expr_to_string(g, &|path| {
+            let guard_id = util::key(path);
+            format!(
+                "<a href='#method.{}'>{}</a>",
+                guard_id,
+                guard_id.replace(GUARD_PREFIX, "")
+            )
+        });
         label.push_str(&format!(
-            "{0}&nbsp;<a href='#method.{g}'>{1}</a>",
+            "{0}&nbsp;{1}",
             if label.is_empty() { "" } else { "<br>" },
-            g.to_string().replace(GUARD_PREFIX, "")
+            guard_str
         ));
     }
     if let Some(ref h) = tr.handler {
         label.push_str(&format!(
-            "{0}&nbsp;<a href='#method.{h}'>{1}</a>",
+            "{0}↪️&nbsp;<a href='#method.{h}'>{1}</a>",
             if label.is_empty() { "" } else { "<br>" },
             h.to_string().replace(HANDLE_PREFIX, "")
         ));
@@ -53,7 +61,11 @@ pub fn attr(m: &parser::MachineAttr) -> TokenStream2 {
     let mut md = String::new();
     writeln!(md, "///```mermaid").unwrap();
     writeln!(md, "///stateDiagram-v2").unwrap();
-    writeln!(md, "///    classDef selfLoop fill:#eee,stroke-width:0px,shape:rectangle,margin:0,padding:0").unwrap();
+    writeln!(
+        md,
+        "///    classDef selfLoop fill:#eee,stroke-width:0px,shape:rectangle,margin:0,padding:0"
+    )
+    .unwrap();
     writeln!(md, "///    [*] --> {}", initial).unwrap();
 
     // Clickable state aliases