https://github.com/nulldef/statum
Ruby state machine
https://github.com/nulldef/statum
declarative fsm ruby state-machine
Last synced: 11 months ago
JSON representation
Ruby state machine
- Host: GitHub
- URL: https://github.com/nulldef/statum
- Owner: nulldef
- License: mit
- Created: 2017-11-26T21:06:12.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2017-12-10T16:09:36.000Z (over 8 years ago)
- Last Synced: 2025-04-16T13:15:05.115Z (11 months ago)
- Topics: declarative, fsm, ruby, state-machine
- Language: Ruby
- Homepage: http://www.rubydoc.info/github/nulldef/statum
- Size: 33.2 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Statum
[](https://travis-ci.org/nulldef/statum)
[](https://coveralls.io/github/nulldef/statum?branch=master&v=0.3.1)
[](https://badge.fury.io/rb/statum)
Finite state machine for your objects
Supported Ruby 2.2.0+
- [Installation](#installation)
- [Usage](#usage)
- [Basic usage](#basic-usage)
- [Multiple state machines](#multiple-state-machines)
- [Hooks](#hooks)
- [Contributing](#contributing)
- [License](#license)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'statum'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install statum
## Usage
### Basic usage
Statum provides a DSL for defining state machine for your class
```ruby
class Car
include Statum
attr_accessor :state
statum :state, initial: :idle do
state :idle
state :riding
event :ride, idle: :riding
end
end
```
Then `Car` object will receive following methods:
```ruby
car = Car.new
car.idle? # => true
car.riding? # => false
car.ride! # changes idle state to riding
```
You can define an array of states which will be able to fire event:
```ruby
class Car
include Statum
attr_accessor :state
statum :state, initial: :idle do
state :idle
state :parked
state :riding
event :ride, %i[idle parked] => :riding
end
end
```
Also you can use `any_state` helper to say, that event can be fired from any of defined states
```ruby
class Car
include Statum
attr_accessor :state
statum :state, initial: :idle do
state :idle
state :parked
state :riding
event :ride, any_state => :riding
end
end
```
### Multiple state machines
You can define more than one state machine on your object.
**IMPORTANT** use unique fields to work with two or more states
```ruby
class Car
include Statum
attr_accessor :state, :engine
statum :state do
state :riding
state :idle
event :ride, idle: :riding
end
statum :engine do
state :stopped
state :started
event :start, stopped: :started
end
end
```
```ruby
car = Car.new
car.start! # changes engine to started
car.ride! # changes state to riding
```
### Hooks
You can be able to execute some procs before and after event will be fired
```ruby
class Car
include Statum
attr_accessor :state, :started
statum :state, initial: :idle do
state :idle
state :riding
event :ride, idle: :riding,
before: -> { self.started = true },
after: :stop_engine
end
def stop_engine
self.started = false
end
end
```
And then before state changes will be executed `before` proc, and after
changing - `after` proc (in instance context).
If you will wait for argument in hook - the instance will be passed.
```ruby
...
event :ride, idle: :riding,
before: -> (instance) { instance.started = true}
...
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/nulldef/statum.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).