A simple and effective state machine library, written in idiomatic Rust.
What is mode
?
This library provides three main types, Automaton
, Mode
, and Family
, that facilitate the creation of finite state
machines. An Automaton
can be used to quickly create a state machine over a Family
of states, where each state is an
object that implements the Mode
trait.
Features
mode
supports creating several different kinds of state machine:- Simple state machines, where each state is a separate
enum
value and transitions are handled externally. - More complex state machines, where each state is a separate
struct
that implements some commondyn Trait
, and the responsibility for transitioning to the nextMode
is delegated to the currentMode
implementation. - Data-driven state machines, where all states are represented by the same concrete type with different input.
- Simple state machines, where each state is a separate
- Function calls can be dispatched to the current
Mode
easily through the containingAutomaton
, viaDeref
coercion. - You have total control over which public interface is exposed for the current
Mode
outside of theAutomaton
. - A flexible transition system allows the next
Mode
in the state machine to steal state from the previousMode
when it transitions in. Mode
s can be stored in-place or heap-allocated, i.e. stored in aBox<T>
,Rc<T>
, orArc<T>
.- The library itself uses zero allocations. Any and all allocations are controlled by you and passed into the
Automaton
.
Why use mode
?
- It's flexible. This library imposes very few restrictions on how you write and organize your code. All lifetimes, allocations, and conventions are in your total control.
- It's well-documented. All public types have detailed documentation and examples, so getting up to speed is easy.
- It's easy to digest. Barring examples and comments, the whole library clocks in at less than 200 lines of code.
That means digging into the internals of
mode
to figure out how something works is effortless. - It's pure Rust. No macro magic. No convoluted attribute markup. Just
trait
s,struct
s, and generics. - 100% safe, 100% stable. There are zero
unsafe
blocks in this library, and no features that require thenightly
toolchain. That meansmode
is dependable and robust.
Releases
See the full list of releases on GitHub.
Upgrading to version 0.4
A lot has been streamlined in version 0.4
, in an effort to make mode
even easier to understand and use. If you're
interested in upgrading your project from version 0.3
to 0.4
of mode
, please see
UPGRADING-v0.4.md for a step-by-step guide.
Documentation
Please see docs.rs for detailed documentation.
Example
use ;
// This meta-struct represents a group of all Modes that can be used with the same Automaton, i.e. all states in the
// same state machine. By implementing Family, we can specify the common interface that will be exposed for all states
// (type Base) and how the current state will be stored in the Automaton (type Mode). The important thing to note is
// that this struct will never be instantiated. It only exists to group a set of states (Modes) together.
//
;
// This trait defines a common interface for all Modes in ActivityFamily.
//
// Each state in the state machine implements both Activity (the Base type) and Mode.
//
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contributing
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
If you find bugs, please feel free to open an issue on GitHub! Otherwise, if
you would like to propose changes to this library, feel free to send me a pull request or message me on the mode
Gitter channel.
I'll try to respond to these requests as quickly as I can.