1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
//! # Banish
//! Banish is a declarative DSL for building rule-based state machines in Rust.
//! States evaluate their rules until reaching a fixed point or triggering a transition,
//! reducing control flow boilerplate.
//!
//! ## How It Works
//! A `banish!` block contains one or more states. The machine starts at the first declared
//! state and advances through them in declaration order. Within each state, rules are
//! evaluated top to bottom on every pass. If any rule fires, the state loops and re-evaluates
//! from the top. Once a full pass completes with no rules firing, the state has reached its
//! fixed point and the machine advances to the next state.
//!
//! ## Syntax
//!
//! | Syntax | Description |
//! |---|---|
//! | `@name` | Declares a state. |
//! | `rule ? condition { }` | A conditional rule. Fires when `condition` is true, then re-evaluates the state. |
//! | `rule ? { }` | A conditionless rule. Fires exactly once on the first pass of each state entry. |
//! | `!? { }` | Fallback branch. Runs when the preceding rule's condition is false. |
//! | `=> @state;` | Explicit transition. Immediately jumps to another state, bypassing the scheduler. |
//! | `return expr;` | Exits the entire `banish!` block with a value. |
//! | `break;` | Exits the current state's loop immediately, letting the scheduler advance normally. |
//! | `continue;` | Restarts rule evaluation from the top of the current state immediately. |
//!
//! ## State Attributes
//! Attributes can be placed above a state declaration to modify its behavior.
//!
//! | Attribute | Description |
//! |---|---|
//! | `isolate` | Removes the state from implicit scheduling. Only reachable via `=> @state`. |
//! | `max_iter = N` | Caps the fixed-point loop to N iterations, then advances normally. |
//! | `max_iter = N => @state` | Same, but transitions to `@state` on exhaustion instead of advancing. |
//! | `max_entry = N` | Limits how many times this state can be entered. Returns on the (N+1)th entry. |
//! | `max_entry = N => @state` | Same, but transitions to `@state` on exhaustion instead of returning. |
//! | `trace` | Emits diagnostics via [`log::trace!`] on state entry and rule evaluation. Requires a `log`-compatible backend. |
//!
//! ## Tracing
//! The `trace` attribute emits diagnostics through the [`log`] facade. Add a backend such as
//! [`env_logger`](https://docs.rs/env_logger) to capture the output:
//!
//! ```toml
//! [dependencies]
//! env_logger = "0.11.9"
//! ```
//!
//! ```rust,ignore
//! fn main() {
//! env_logger::init();
//! // ...
//! }
//! ```
//!
//! Then run with `RUST_LOG=trace` to capture output:
//!
//! ```text
//! # bash / zsh
//! RUST_LOG=trace cargo run -q 2> trace.log
//!
//! # PowerShell
//! $env:RUST_LOG="trace"; cargo run -q 2> trace.log
//! ```
//!
//! ## Example
//! A traffic light that cycles through red, green, and yellow twice before exiting.
//!
//! ```rust
//! use banish::banish;
//!
//! fn main() {
//! let mut ticks: i32 = 0;
//! banish! {
//! // Returns on the third entry immediately
//! #[max_entry = 2]
//! @red
//! announce? {
//! ticks = 0;
//! println!("Red light");
//! }
//! timer ? ticks < 3 {
//! ticks += 1;
//! }
//!
//! @green
//! announce? {
//! println!("Green light");
//! }
//! timer ? ticks < 6 {
//! ticks += 1;
//! }
//!
//! @yellow
//! announce? {
//! println!("Yellow light");
//! }
//! timer ? ticks < 10 {
//! ticks += 1;
//! } !? { => @red; }
//! }
//! }
//! ```
//!
//! ## More Examples
//!
//! The [Dragon Fight](https://github.com/LoganFlaherty/banish/blob/main/docs/README.md#dragon-fight)
//! example demonstrates early return with a value, multi-state transitions, and external crate usage.
//! The [Double For Loop](https://github.com/LoganFlaherty/banish/blob/main/docs/README.md#double-for-loop)
//! example shows self-transitions and returning a tuple.
//!
//! For a full treatment of every feature, attribute, and error, see the
//! [Reference](https://github.com/LoganFlaherty/banish/blob/main/docs/reference.md).
pub use banish;
pub use log;