banish/lib.rs
1//! # Banish
2//! Banish is a declarative DSL for building rule-based state machines in Rust.
3//! States evaluate their rules until reaching a fixed point or triggering a transition, reducing control flow boilerplate.
4//!
5//! ## Syntax
6//! - **@state** : Defines a state. A state re-evaluates until no rule triggers or a transition occurs.
7//! - **rule ? condition {}** : Defines a rule. Executes if its condition is true. Rules execute from top to bottom.
8//! - **!? {}** : Defines a fallback branch. Executes when the rule's condition is false.
9//! - **rule ? {}** : A rule without a condition. Executes exactly once per state entry. Cannot have a fallback branch.
10//! - **=> @state;** : Explicit transition. Immediately transfers to another state. Valid only at the top level of a rule body.
11//! - **return value;** : Immediately exit banish! and return a value if provided.
12//! - **break;** : Immediately exits out of the state.
13//!
14//! ## Examples
15//! https://github.com/LoganFlaherty/banish/blob/main/docs/README.md
16//!
17//! ```rust
18//! use banish::banish;
19//!
20//! fn main() {
21//! let mut ticks: i32 = 0;
22//! let mut loop_count: i32 = 0;
23//! banish! {
24//! @red
25//! announce ? {
26//! ticks = 0;
27//! println!("Red light");
28//! loop_count += 1;
29//! }
30//!
31//! timer ? ticks < 3 {
32//! ticks += 1;
33//! }
34//!
35//! @green
36//! announce ? {
37//! println!("Green light");
38//! }
39//!
40//! timer ? ticks < 6 {
41//! ticks += 1;
42//! }
43//!
44//! @yellow
45//! announce ? {
46//! println!("Yellow light");
47//! }
48//!
49//! timer ? ticks < 10 {
50//! ticks += 1;
51//! } !? {
52//! loop_count += 1;
53//! => @red;
54//! }
55//!
56//! end ? loop_count = 1 { return; }
57//! }
58//! ```
59
60pub use banish_derive::banish;