mode/
lib.rs

1// Copyright 2019 Andrew Thomas Christensen
2//
3// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0> or the
4// MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option. This file may not be copied,
5// modified, or distributed except according to those terms.
6
7//! A simple and effective state machine library, written in in idiomatic, 100% safe, stable Rust code.
8//! 
9//! This library provides three main types, `Automaton`, `Mode`, and `Family`, which facilitate the creation of finite
10//! state machines. An `Automaton` can be used to quickly create a state machine over some `Family` of concrete types
11//! that implement the `Mode` trait. This can contain either:
12//! 
13//! - a single, concrete type representing all states in the state machine, e.g. a `struct` or an `enum`, or
14//! - one or more separate types that all implement some common `dyn Trait`, with each type representing a distinct
15//!   state in the state machine.
16//! 
17//! The `Automaton` keeps track of a current instance of `Mode`, and provides external access to any members that are
18//! common to all `Mode`s in the `Family`. A flexible transition system provides a way to swap in a new `Mode` in the
19//! same `Family`, when ready, and is designed such that state from the current `Mode` can be moved directly into the
20//! new `Mode` being created. This can help prevent spikes in memory usage when transitioning between `Mode`s that own
21//! large amounts of data.
22//! 
23//! # Examples
24//!  - For a simple example of how to use this library to implement a simple state machine over a single, concrete type,
25//!    please see `examples/enum.rs`.
26//!  - For a more advanced example demonstrating a state machine over several types in the same `Family`, please see
27//!    `examples/activity.rs`.
28//!  - For an example demonstrating how to pass context into and out of transition functions, please see
29//!    `examples/turing.rs`.
30//! 
31//! You can run the examples using the following Cargo commands:
32//! ```shell
33//! cargo run --example enum
34//! cargo run --example activity
35//! cargo run --example turing
36//! ```
37//! 
38//! # Getting started
39//! A good place to start reading would be the [`Automaton`](struct.Automaton.html) documentation, followed by
40//! [`Mode`](trait.Mode.html) and then [`Family`](trait.Family.html).
41//! 
42mod automaton;
43mod family;
44mod mode;
45
46pub use self::automaton::*;
47pub use self::family::*;
48pub use self::mode::*;