Finite state machines in rust; bendns fork to add types.
| -rw-r--r-- | CHANGELOG.md | 114 | ||||
| -rw-r--r-- | README.md | 78 | ||||
| -rw-r--r-- | doc-example/Cargo.toml | 2 | ||||
| -rw-r--r-- | rust-fsm-dsl/Cargo.toml | 2 | ||||
| -rw-r--r-- | rust-fsm/Cargo.toml | 4 | ||||
| -rw-r--r-- | rust-fsm/src/lib.rs | 2 |
6 files changed, 119 insertions, 83 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 69a235f..6396a50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,104 +1,142 @@ # Changelog + All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog][keepachangelog], and this project adheres to [Semantic Versioning][semver]. ## [Unreleased] + +## [0.8.0] - 2025-07-21 + ### Changed -* Updated `aquamarine` from `0.5` to `0.6`. + +- Updated `aquamarine` from `0.5` to `0.6`. ## [0.7.0] - 2024-06-01 + ### Changed -* All types generated by the `state_machine` macro are now confined in a module. + +- All types generated by the `state_machine` macro are now confined in a module. The name of the module is passed to the macro as the name of the state machine. All generated types now have uniforms names: `Impl`, `Input`, `State`, `Output`. -* If no outputs is specified in the `state_machine` macro, an empty `Output` +- If no outputs is specified in the `state_machine` macro, an empty `Output` enum is generated instead of using `()` for the sake of uniformity. No attributes (e.g. `derive` and `repr`) are applied on an empty `Output`, because many of them are simply not designed to work this way. -* It is now possible to use proper Rust attributes like `#[derive(Debug)]`, +- It is now possible to use proper Rust attributes like `#[derive(Debug)]`, `#[repr(C)]`, etc (any attribute you want really). This replaces the original way this macro had for using derives and specifying representation. -* Use Rust 2021 edition. +- Use Rust 2021 edition. + ### Added -* A type alias `StateMachine` for `rust_fsm::StateMachine<Impl>` is now + +- A type alias `StateMachine` for `rust_fsm::StateMachine<Impl>` is now generated inside the said module. -* Supplying ones own enums for state, input and output in the proc-macro (#10). -* An optional possibility to generate Mermaid diagrams. -* Processing doc comments to generate the state machine module documentation. +- Supplying ones own enums for state, input and output in the proc-macro (#10). +- An optional possibility to generate Mermaid diagrams. +- Processing doc comments to generate the state machine module documentation. ## [0.6.2] - 2024-05-11 + ### Changed -* Update documentation. + +- Update documentation. + ### Added -* Derive `Debug` and `Clone` for `StateMachine` struct + +- Derive `Debug` and `Clone` for `StateMachine` struct ## [0.6.1] - 2022-12-24 + ### Changed -* Use pattern matching in examples. + +- Use pattern matching in examples. + ### Added -* Allow to specify `repr(C)` on generated enums. + +- Allow to specify `repr(C)` on generated enums. ## [0.6.0] - 2021-08-24 + ### Changed -* Updated to `1.x` versions of `syn` and `quote`. + +- Updated to `1.x` versions of `syn` and `quote`. ## [0.5.0] - 2021-02-23 + ### Added -* The re-export of the DSL implementation is gated by the `dsl` feature which is + +- The re-export of the DSL implementation is gated by the `dsl` feature which is enabled by default. + ### Changed -* State transition error is now represented with `TransitionImpossibleError` + +- State transition error is now represented with `TransitionImpossibleError` instead of `()`. -* The library is not `no_std` by default due to the use of `std::error::Error`. +- The library is not `no_std` by default due to the use of `std::error::Error`. Users should disable the new `std` feature to use this library in a `no_std` environment. ## [0.4.0] - 2020-08-25 + ### Added -* Allow deriving different traits for generated traits. -* Add the `from_state` method to start the machine from any given state. -* `no_std` support (thanks @luctius). + +- Allow deriving different traits for generated traits. +- Add the `from_state` method to start the machine from any given state. +- `no_std` support (thanks @luctius). + ### Removed -* All default derives on generated enums. -* `Copy` constraint on `StateMachineImpl::State`. + +- All default derives on generated enums. +- `Copy` constraint on `StateMachineImpl::State`. ## [0.3.0] - 2019-05-22 + ### Changed -* Re-organize repository to import a single crate instead of two. + +- Re-organize repository to import a single crate instead of two. ## [0.2.0] - 2019-05-16 + ### Added -* Allow setting visibitility for generated state machine types by putting a + +- Allow setting visibitility for generated state machine types by putting a visibility modifier before the state machine name. -* Allow to specify multiple transitions from the same state in a more compact +- Allow to specify multiple transitions from the same state in a more compact form. See the example for the details. + ### Changed -* More clear naming: - * Renamed the `StateMachineWrapper` structure to `StateMachine`; - * Renamed the `StateMachine` trait to `StateMachineImpl`. + +- More clear naming: + - Renamed the `StateMachineWrapper` structure to `StateMachine`; + - Renamed the `StateMachine` trait to `StateMachineImpl`. + ### Removed -* Removed the `consume_anyway` function. + +- Removed the `consume_anyway` function. ## [0.1.0] - 2019-04-29 + ### Added -* The `StateMachine` trait for formal definitions of state machines and + +- The `StateMachine` trait for formal definitions of state machines and transducers. -* The `StateMachineWrapper` struct - a convenience wrapper around `StateMachine` +- The `StateMachineWrapper` struct - a convenience wrapper around `StateMachine` for practical usage. -* The first implementation of the DSL for defining state machines that allows +- The first implementation of the DSL for defining state machines that allows to: - * Define a state machine with its initial state; - * Define state transitions; - * Define outputs; - * Generate boilerplates implementing `StateMachine`. + - Define a state machine with its initial state; + - Define state transitions; + - Define outputs; + - Generate boilerplates implementing `StateMachine`. [keepachangelog]: https://keepachangelog.com/en/1.0.0/ [semver]: https://semver.org/spec/v2.0.0.html - -[Unreleased]: https://github.com/eugene-babichenko/rust-fsm/compare/v0.7.0...HEAD +[Unreleased]: + https://github.com/eugene-babichenko/rust-fsm/compare/v0.8.0...HEAD +[0.8.0]: https://github.com/eugene-babichenko/rust-fsm/compare/v0.8.0...v0.7.0 [0.7.0]: https://github.com/eugene-babichenko/rust-fsm/compare/v0.7.0...v0.6.2 [0.6.2]: https://github.com/eugene-babichenko/rust-fsm/compare/v0.6.2...v0.6.1 [0.6.1]: https://github.com/eugene-babichenko/rust-fsm/compare/v0.6.0...v0.6.1 @@ -12,24 +12,24 @@ The essential part of this crate is the [`StateMachineImpl`](trait.StateMachineImpl.html) trait. This trait allows a developer to provide a strict state machine definition, e.g. specify its: -* An input alphabet - a set of entities that the state machine takes as - inputs and performs state transitions based on them. -* Possible states - a set of states this machine could be in. -* An output alphabet - a set of entities that the state machine may output - as results of its work. -* A transition function - a function that changes the state of the state - machine based on its current state and the provided input. -* An output function - a function that outputs something from the output +- An input alphabet - a set of entities that the state machine takes as inputs + and performs state transitions based on them. +- Possible states - a set of states this machine could be in. +- An output alphabet - a set of entities that the state machine may output as + results of its work. +- A transition function - a function that changes the state of the state machine + based on its current state and the provided input. +- An output function - a function that outputs something from the output alphabet based on the current state and the provided inputs. -* The initial state of the machine. +- The initial state of the machine. -Note that on the implementation level such abstraction allows build any type -of state machines: +Note that on the implementation level such abstraction allows build any type of +state machines: -* A classical state machine by providing only an input alphabet, a set of - states and a transition function. -* A Mealy machine by providing all entities listed above. -* A Moore machine by providing an output function that do not depend on the +- A classical state machine by providing only an input alphabet, a set of states + and a transition function. +- A Mealy machine by providing all entities listed above. +- A Moore machine by providing an output function that do not depend on the provided inputs. ## Feature flags @@ -46,9 +46,9 @@ of state machines: ## Usage in `no_std` environments -This library has the feature named `std` which is enabled by default. You -may want to import this library as -`rust-fsm = { version = "0.7", default-features = false, features = ["dsl"] }` +This library has the feature named `std` which is enabled by default. You may +want to import this library as +`rust-fsm = { version = "0.8", default-features = false, features = ["dsl"] }` to use it in a `no_std` environment. This only affects error types (the `Error` trait is only available in `std`). @@ -58,9 +58,9 @@ also enabled by default. ## Use Initially this library was designed to build an easy to use DSL for defining -state machines on top of it. Using the DSL will require to connect an -additional crate `rust-fsm-dsl` (this is due to limitation of the procedural -macros system). +state machines on top of it. Using the DSL will require to connect an additional +crate `rust-fsm-dsl` (this is due to limitation of the procedural macros +system). ### Using the DSL for defining state machines @@ -86,17 +86,16 @@ state_machine! { This code sample: -* Defines a state machine called `circuit_breaker`; -* Derives the `Debug` trait for it. All attributes you use here (like +- Defines a state machine called `circuit_breaker`; +- Derives the `Debug` trait for it. All attributes you use here (like `#[repr(C)]`) will be applied to all types generated by this macro. If you want to apply attributes or a docstring to the `mod` generated by this macro, just put it before the macro invocation. -* Sets the initial state of this state machine to `Closed`; -* Defines state transitions. For example: on receiving the `Successful` - input when in the `HalfOpen` state, the machine must move to the `Closed` - state; -* Defines outputs. For example: on receiving `Unsuccessful` in the - `Closed` state, the machine must output `SetupTimer`. +- Sets the initial state of this state machine to `Closed`; +- Defines state transitions. For example: on receiving the `Successful` input + when in the `HalfOpen` state, the machine must move to the `Closed` state; +- Defines outputs. For example: on receiving `Unsuccessful` in the `Closed` + state, the machine must output `SetupTimer`. This state machine can be used as follows: @@ -120,20 +119,19 @@ if let circuit_breaker::State::Open = machine.state() { The following entities are generated: -* An empty structure `circuit_breaker::Impl` that implements the +- An empty structure `circuit_breaker::Impl` that implements the `StateMachineImpl` trait. -* Enums `circuit_breaker::State`, `circuit_breaker::Input` and +- Enums `circuit_breaker::State`, `circuit_breaker::Input` and `circuit_breaker::Output` that represent the state, the input alphabet and the output alphabet respectively. -* Type alias `circuit_breaker::StateMachine` that expands to -`StateMachine<circuit_breaker::Impl>`. +- Type alias `circuit_breaker::StateMachine` that expands to + `StateMachine<circuit_breaker::Impl>`. Note that if there is no outputs in the specification, the output alphabet is an empty enum and due to technical limitations of many Rust attributes, no attributes (e.g. `derive`, `repr`) are applied to it. -Within the `state_machine` macro you must define at least one state -transition. +Within the `state_machine` macro you must define at least one state transition. #### Visibility @@ -211,16 +209,16 @@ cargo doc -p doc-example --open ### Without DSL -The `state_machine` macro has limited capabilities (for example, a state -cannot carry any additional data), so in certain complex cases a user might -want to write a more complex state machine by hand. +The `state_machine` macro has limited capabilities (for example, a state cannot +carry any additional data), so in certain complex cases a user might want to +write a more complex state machine by hand. All you need to do to build a state machine is to implement the `StateMachineImpl` trait and use it in conjuctions with some of the provided wrappers (for now there is only `StateMachine`). -You can see an example of the Circuit Breaker state machine in the -[project repository][repo]. +You can see an example of the Circuit Breaker state machine in the [project +repository][repo]. [repo]: https://github.com/eugene-babichenko/rust-fsm [docs-badge]: https://docs.rs/rust-fsm/badge.svg diff --git a/doc-example/Cargo.toml b/doc-example/Cargo.toml index bc49037..ad23c09 100644 --- a/doc-example/Cargo.toml +++ b/doc-example/Cargo.toml @@ -4,4 +4,4 @@ version = "0.1.0" edition = "2021" [dependencies] -rust-fsm = { path = "../rust-fsm", version = "0.7", features = ["diagram"] } +rust-fsm = { path = "../rust-fsm", version = "0.8", features = ["diagram"] } diff --git a/rust-fsm-dsl/Cargo.toml b/rust-fsm-dsl/Cargo.toml index 602ad5a..33c7010 100644 --- a/rust-fsm-dsl/Cargo.toml +++ b/rust-fsm-dsl/Cargo.toml @@ -8,7 +8,7 @@ readme = "../README.md" license = "MIT" categories = ["data-structures", "rust-patterns"] keywords = ["fsm"] -version = "0.7.0" +version = "0.8.0" authors = ["Yevhenii Babichenko"] edition = "2021" diff --git a/rust-fsm/Cargo.toml b/rust-fsm/Cargo.toml index a501c53..84645ed 100644 --- a/rust-fsm/Cargo.toml +++ b/rust-fsm/Cargo.toml @@ -8,7 +8,7 @@ readme = "../README.md" license = "MIT" categories = ["data-structures", "rust-patterns"] keywords = ["fsm"] -version = "0.7.0" +version = "0.8.0" authors = ["Yevhenii Babichenko"] edition = "2021" @@ -20,7 +20,7 @@ diagram = ["aquamarine", "rust-fsm-dsl/diagram"] [dependencies] aquamarine = { version = "0.6", optional = true } -rust-fsm-dsl = { path = "../rust-fsm-dsl", version = "0.7.0", optional = true } +rust-fsm-dsl = { path = "../rust-fsm-dsl", version = "0.8.0", optional = true } [profile.dev] panic = "abort" diff --git a/rust-fsm/src/lib.rs b/rust-fsm/src/lib.rs index f8d988a..3324e94 100644 --- a/rust-fsm/src/lib.rs +++ b/rust-fsm/src/lib.rs @@ -45,7 +45,7 @@ of state machines: This library has the feature named `std` which is enabled by default. You may want to import this library as -`rust-fsm = { version = "0.7", default-features = false, features = ["dsl"] }` +`rust-fsm = { version = "0.8", default-features = false, features = ["dsl"] }` to use it in a `no_std` environment. This only affects error types (the `Error` trait is only available in `std`). |