With this macro you can easily implement Finite State Machine in declarative way.
State machine consists of:
Each state node contains:
Each command reaction contains:
Let's say we'd like to implement such machine:
Corresponding code will look like:
```rust
declare_machine!( MyMachine(A {counter: 0}) // Name and initial state with initial value states[A,B] // List of states commands[Next] // List of commands (A context{counter: i16}: // State node and this state context description with name binding
{ // Executed on state A enter println!("Enter A: {:?}", context); context.counter = context.counter + 1; } << { // Executed on state A leave println!("Leave A: {:?}", context); context.counter = context.counter + 1; } Next { println!("Next in A: {:?}", context); context.counter = context.counter + 1; } => B {counter: context.counter}; // Command Reaction. Now on command Next we add 1 to our context. Also we change state to B and init it with our counter value. ) (B context{counter: i16}: { println!("Enter B: {:?}", context); context.counter = context.counter + 1; } << { println!("Leave B: {:?}", context); context.counter = context.counter + 1; } Next { println!("Next in B: {:?}", context); context.counter = context.counter + 1; } => A {counter: context.counter}; ) );
fn main() { use MyMachine::*; let mut machine = MyMachine::new(); machine.execute(&MyMachine::Commands::Next).unwrap(); machine.execute(&MyMachine::Commands::Next).unwrap(); } ```
Simplest state machine example:
```rust
declare_machine!( Simple(A) // Name and initial State states[A,B] // list of States commands[Next] // list of Commands (A: // State Node Next => B; // Command Reaction. Just change state to B ) (B: Next => A; // And back to A ) ); ```
So, now you can use state machine:
rust
fn main() {
use Simple::*;
let mut machine = Simple::new();
machine.execute(&Simple::Commands::Next).unwrap();
machine.execute(&Simple::Commands::Next).unwrap();
}
You can add some intelligence to machine.
Each state can hold some data. On State change you can transmit some data between states. It looks like you just create struct with some fields initialization:
```rust
declare_machine!( Simple(A{counter:0}) // Name and initial State with initial value states[A,B] // list of States commands[Next] // list of Commands (A context{counter:i16}: // State Node and this state context description with binding name Next {context.counter=context.counter+1}=> B{counter:context.counter}; // Command Reaction. Now on command Next we add 1 to our context. Also we change state to B and init it with our x value. ) (B context{counter:i16}: Next {context.counter=context.counter+1}=> A{counter:context.counter}; ) ); ```
Let's check our state transmission:
```rust fn main() { use Simple::*; let mut machine = Simple::new();
// We are in state A and have our initial value 0
assert!(match machine.get_current_state(){
States::A{context}=> if context.counter == 0 {true} else {false},
_=>false
});
machine.execute(&Simple::Commands::Next).unwrap();
// We are in state B and have counter == 1
assert!(match machine.get_current_state(){
States::B{context}=> if context.counter == 1 {true} else {false},
_=>false
});
machine.execute(&Simple::Commands::Next).unwrap();
// Again in state A and have counter == 2
assert!(match machine.get_current_state(){
States::A{context}=> if context.counter == 2 {true} else {false},
_=>false
});
} ```
Also there is callbacks on each entrance and each leave of state.
```rust
declare_machine!( Simple(A{counter:0}) // Name and initial State with initial value states[A,B] // list of States commands[Next] // list of Commands (A context{counter:i16}: // State Node and this state context description with binding name
{context.counter = context.counter+1;} // Execute when enter state A << {context.counter = context.counter+1;} // Execute when leave state A Next {context.counter=context.counter+1;} => B{counter:context.counter}; // Command Reaction. Now on command Next we add 1 to our context. Also we change state to B and init it with our x value. ) (B context{counter:i16}: Next {context.counter=context.counter+1} => A{counter:context.counter}; ) ); fn main() { use Simple::*; let mut machine = Simple::new(); assert!(match machine.getcurrentstate(){ // We are in state A and have value 1. Because Enter State callback executed. States::A{context}=> if context.counter == 1 {true} else {false}, =>false }); machine.execute(&Simple::Commands::Next).unwrap(); assert!(match machine.getcurrentstate(){ // We are in state B and have counter == 3. Increment happen on User Code execution and execution of Leave state callback. States::B{context}=> {println!("context counter: {}", context.counter);if context.counter == 3 {true} else {false}}, _=>false }); machine.execute(&Simple::Commands::Next).unwrap(); assert!(match machine.getcurrent_state(){ // Again in state A and have counter == 5. Increment happen on User Code execution and on state A enter. States::A{context}=> if context.counter == 5 {true} else {false}, _=>false }); } ```
Example of Machine-scoped context. This context exist in machine life-time.
Let's count machine's state changes:
```rust
declaremachine!( Simple machinecontext{counter: i16} (A) // Declare machine scoped context states[A,B] commands[Next] (A :
{machinecontext.counter=machinecontext.counter+1;} // Add 1 when enter in state Next => B; // Just switch to other state ) (B : {machinecontext.counter=machinecontext.counter+1;} Next => A; ) ); fn main() { use Simple::*; let mut machine = Simple::new(0); // Create machine and initiate machine context by 0 let context = machine.getinnercontext(); assert!(context.counter == 1); machine.execute(&Simple::Commands::Next).unwrap(); let context = machine.getinnercontext(); assert!(context.counter == 2); machine.execute(&Simple::Commands::Next).unwrap(); let context = machine.getinnercontext(); assert!(context.counter == 3); } ```