README.md
<div align="center">
<a href="https://piotrmurach.github.io/finite_machine/"><img width="236" src="https://github.com/piotrmurach/finite_machine/raw/master/assets/finite_machine_logo.png" alt="finite machine logo" /></a>
</div>
# FiniteMachine
[][gem]
[][gh_actions_ci]
[][appveyor]
[][codeclimate]
[][coverage]
[][inchpages]
[][gitter]
[gem]: http://badge.fury.io/rb/finite_machine
[gh_actions_ci]: https://github.com/piotrmurach/finite_machine/actions?query=workflow%3ACI
[appveyor]: https://ci.appveyor.com/project/piotrmurach/finite-machine
[codeclimate]: https://codeclimate.com/github/piotrmurach/finite_machine
[coverage]: https://coveralls.io/github/piotrmurach/finite_machine?branch=master
[inchpages]: http://inch-ci.org/github/piotrmurach/finite_machine
[gitter]: https://gitter.im/piotrmurach/finite_machine
> A minimal finite state machine with a straightforward and intuitive syntax. You can quickly model states and transitions and register callbacks to watch for triggered transitions.
## Features
* plain object state machine
* easy [custom object integration](#29-target)
* natural DSL for declaring events, callbacks and exception handlers
* [callbacks](#4-callbacks) for state and event changes
* ability to check [reachable](#28-can-and-cannot) state(s)
* ability to check for [terminal](#25-terminal) state(s)
* transition [guard conditions](#38-conditional-transitions)
* dynamic [choice pseudostates](#39-choice-pseudostates)
* thread safe
## Installation
Add this line to your application's Gemfile:
gem "finite_machine"
Then execute:
$ bundle
Or install it yourself as:
$ gem install finite_machine
## Contents
* [1. Usage](#1-usage)
* [2. API](#2-api)
* [2.1 new](#21-new)
* [2.2 define](#22-define)
* [2.3 current](#23-current)
* [2.4 initial](#24-initial)
* [2.5 terminal](#25-terminal)
* [2.6 is?](#26-is)
* [2.7 trigger](#27-trigger)
* [2.7.1 :auto_methods](#271-auto_methods)
* [2.8 can? and cannot?](#28-can-and-cannot)
* [2.9 target](#29-target)
* [2.9.1 :alias_target](#27-alias_target)
* [2.10 restore!](#210-restore)
* [2.11 states](#211-states)
* [2.12 events](#212-events)
* [3. States and Transitions](#3-states-and-transitions)
* [3.1 Triggering transitions](#31-triggering-transitions)
* [3.2 Dangerous transitions](#32-dangerous-transitions)
* [3.3 Multiple from states](#33-multiple-from-states)
* [3.4 any_state transitions](#34-any_state-transitions)
* [3.5 Collapsing transitions](#35-collapsing-transitions)
* [3.6 Silent transitions](#36-silent-transitions)
* [3.7 Logging transitions](#37-logging-transitions)
* [3.8 Conditional transitions](#38-conditional-transitions)
* [3.8.1 Using a Proc](#381-using-a-proc)
* [3.8.2 Using a Symbol](#382-using-a-symbol)
* [3.8.3 Using a String](#383-using-a-string)
* [3.8.4 Combining transition conditions](#384-combining-transition-conditions)
* [3.9 Choice pseudostates](#39-choice-pseudostates)
* [3.9.1 Dynamic choice conditions](#391-dynamic-choice-conditions)
* [3.9.2 Multiple from states](#392-multiple-from-states)
* [4. Callbacks](#4-callbacks)
* [4.1 on_(enter|transition|exit)](#41-on_entertransitionexit)
* [4.2 on_(before|after)](#42-on_beforeafter)
* [4.3 once_on](#43-once_on)
* [4.4 Execution sequence](#44-execution-sequence)
* [4.5 Callback parameters](#45-callback-parameters)
* [4.6 Duplicate callbacks](#46-duplicate-callbacks)
* [4.7 Fluid callbacks](#47-fluid-callbacks)
* [4.8 Methods inside callbacks](#48-methods-inside-callbacks)
* [4.9 Cancelling callbacks](#49-cancelling-callbacks)
* [4.10 Asynchronous callbacks](#410-asynchronous-callbacks)
* [4.11 Instance callbacks](#411-instance-callbacks)
* [5. Error Handling](#5-error-handling)
* [5.1 Using target](#51-using-target)
* [6. Stand-alone](#6-stand-alone)
* [6.1 Creating a Definition](#61-creating-a-definition)
* [6.2 Targeting definition](#62-targeting-definition)
* [6.3 Definition inheritance](#63-definition-inheritance)
* [7. Integration](#7-integration)
* [7.1 Plain Ruby Objects](#71-plain-ruby-objects)
* [7.2 ActiveRecord](#72-activerecord)
* [7.3 Transactions](#73-transactions)
* [8. Tips](#8-tips)
## 1. Usage
Here is a very simple example of a state machine:
```ruby
fm = FiniteMachine.new do
initial :red
event :ready, :red => :yellow
event :go, :yellow => :green
event :stop, :green => :red
on_before(:ready) { |event| ... }
on_exit(:yellow) { |event| ... }
on_enter(:green) { |event| ... }
on_after(:stop) { |event| ... }
end
```
By calling the `new` method on **FiniteMachine**, you gain access to a powerful DSL for expressing transitions and registering callbacks.
Having declared the states and transitions, you can check current state:
```ruby
fm.current # => :red
````
And then trigger transitions using the `trigger`:
```ruby
fm.trigger(:ready)
```
Or you can use direct method calls:
```ruby
fm.ready
```
Read [States and Transitions](#3-states-and-transitions) and [Callbacks](#4-callbacks) sections for more details.
Alternatively, you can construct the state machine like a regular object using the same DSL methods. Similar machine could be reimplemented as follows:
```ruby
fm = FiniteMachine.new(initial: :red)
fm.event(:ready, :red => :yellow)
fm.event(:go, :yellow => :green)
fm.event(:stop, :green => :red)
fm.on_before(:ready) { |event| ... }
fm.on_exit(:yellow) { |event| ... }
fm.on_enter(:green) { |event| ... }
fm.on_after(:stop) { |event| ... }
```
## 2. API
### 2.1 new
In most cases you will want to create an instance of **FiniteMachine** class using the `new` method. At the bare minimum you need specify the transition events inside a block using the `event` helper:
```ruby
fm = FiniteMachine.new do
initial :green
event :slow, :green => :yellow
event :stop, :yellow => :red
event :ready, :red => :yellow
event :go, :yellow => :green
end
```
Alternatively, you can skip block definition and instead call DSL methods directly on the state machine instance:
```ruby
fm = FiniteMachine.new
fm.initial(:green)
fm.event(:slow, :green => :yellow)
fm.event(:stop, :yellow => :red)
fm.event(:ready,:red => :yellow)
fm.event(:go, :yellow => :green)
```
As a guiding rule, any method exposed via DSL is available as a regular method call on the state machine instance.
### 2.2 define
To create a reusable definition for a state machine use `define` method. By calling `define` you're creating an anonymous class that can act as a factory for state machines. For example, below we create a `TrafficLights` class that contains our state machine definition:
```ruby
TrafficLights = FiniteMachine.define do
initial :green
event :slow, :green => :yellow
event :stop, :yellow => :red
event :ready, :red => :yellow
event :go, :yellow => :green
end
```
Then we can create however many instance of above class:
```ruby
lights_fm_a = TrafficLights.new
lights_fm_b = TrafficLights.new
```
Each instance will start in consistent state:
```ruby
lights_fm_a.current # => :green
lights_fm_b.current # => :green
```
We can then trigger event for one instance and not the other:
```ruby
lights_fm_a.slow
lights_fm_a.current # => :yellow
lights_fm_b.current # => :green
```
### 2.3 current
The **FiniteMachine** allows you to query the current state by calling the `current` method.
```ruby
fm.current # => :red
```
### 2.4 initial
There are number of ways to provide the initial state in **FiniteMachine** depending on your requirements.
By default the **FiniteMachine** will be in the `:none` state and you will need to provide an explicit event to transition out of this state.
```ruby
fm = FiniteMachine.new do
event :init, :none => :green
event :slow, :green => :yellow
event :stop, :yellow => :red
end
fm.current # => :none
fm.init # => true
fm.current # => :green
```
If you specify initial state using the `initial` helper, then the state machine will be created already in that state and an implicit `init` event will be created for you and automatically triggered upon the state machine initialization.
```ruby
fm = FiniteMachine.new do
initial :green # fires init event that transitions from :none to :green state
event :slow, :green => :yellow
event :stop, :yellow => :red
end
fm.current # => :green
```
Or by passing named argument `:initial` like so:
```ruby
fm = FiniteMachine.new(initial: :green) do
...
end
```
If you want to defer setting the initial state, pass the `:defer` option to the `initial` helper. By default **FiniteMachine** will create `init` event that will allow to transition from `:none` state to the new state.
```ruby
fm = FiniteMachine.new do
initial :green, defer: true # Defer calling :init event
event :slow, :green => :yellow
event :stop, :yellow => :red
end
fm.current # => :none
fm.init # execute initial transition
fm.current # => :green
```
If your target object already has `init` method or one of the events names redefines `init`, you can use different name by passing `:event` option to `initial` helper.
```ruby
fm = FiniteMachine.new do
initial :green, event: :start, defer: true # Rename event from :init to :start
event :slow, :green => :yellow
event :stop, :yellow => :red
end
fm.current # => :none
fm.start # => call the renamed event
fm.current # => :green
```
By default the `initial` does not trigger any callbacks. If you need to fire callbacks and any event associated actions on initial transition, pass the `silent` option set to `false` like so:
```ruby
fm = FiniteMachine.new do
initial :green, silent: false # callbacks are triggered
event :slow, :green => :yellow
event :stop, :yellow => :red
end
```
### 2.5 terminal
To specify a final state **FiniteMachine** uses the `terminal` method.
```ruby
fm = FiniteMachine.new do
initial :green
terminal :red
event :slow, :green => :yellow
event :stop, :yellow => :red
event :go, :red => :green
end
```
When the terminal state has been specified, you can use `terminated?` method on the state machine instance to verify if the terminal state has been reached or not.
```ruby
fm.terminated? # => false
fm.slow # => true
fm.terminated? # => false
fm.stop # => true
fm.terminated? # => true
```
The `terminal` can accept more than one state.
```ruby
fm = FiniteMachine.new do
initial :open
terminal :close, :canceled
event :resolve, :open => :close
event :decline, :open => :canceled
end
```
And the terminal state can be checked using `terminated?`:
```ruby
fm.decline
fm.terminated? # => true
```
### 2.6 is?
To verify whether or not a state machine is in a given state, **FiniteMachine** uses `is?` method. It returns `true` if the machine is found to be in the given state, or `false` otherwise.
```ruby
fm.is?(:red) # => true
fm.is?(:yellow) # => false
```
Moreover, you can use helper methods to check for current state using the state name itself like so
```ruby
fm.red? # => true
fm.yellow? # => false
```
### 2.7 trigger
Transition events can be fired by calling the `trigger` method with the event name and remaining arguments as data. The return value is either `true` or `false` depending whether the transition succeeded or not:
```ruby
fm.trigger(:ready) # => true
fm.trigger(:ready, "one", "two", "three") # => true
```
By default, the **FiniteMachine** automatically converts all the transition event names into methods:
```ruby
fm.ready # => true
fm.ready("one", "two", "three") # => true
```
Please see [States and Transitions](#3-states-and-transitions) for in-depth treatment of firing transitions.
#### 2.7.1 `:auto_methods`
By default, all event names will be converted by **FiniteMachine** into method names. This also means that you won't be able to use event names such as `:fail` or `:trigger` as these are already defined on the machine instance. In situations when you wish to use any event name for your event names use `:auto_methods` keyword to disable automatic methods generation. For example, to define `:fail` event:
```ruby
fm = FiniteMachine.new(auto_methods: false) do
initial :green
event :fail, :green => :red
end
```
And then you can use `trigger` to fire the event:
```ruby
fm.trigger(:fail)
fm.current # => :red
```
### 2.8 `can?` and `cannot?`
To verify whether or not an event can be fired, **FiniteMachine** provides `can?` or `cannot?` methods. `can?` checks if **FiniteMachine** can fire a given event, returning `true`, otherwise, it will return `false`. The `cannot?` is simply the inverse of `can?`.
```ruby
fm.can?(:ready) # => true
fm.can?(:go) # => false
fm.cannot?(:ready) # => false
fm.cannot?(:go) # => true
```
The `can?` and `cannot?` helper methods take into account the `:if` and `:unless` conditions applied to events. The set of values that `:if` or `:unless` condition takes as block parameter can be passed in directly via `can?` and `cannot?` methods' arguments, after the name of the event. For instance,
```ruby
fm = FiniteMachine.new do
initial :green
event :slow, :green => :yellow
event :stop, :yellow => :red, if: ->(_, param) { :breaks == param }
end
fm.can?(:slow) # => true
fm.can?(:stop) # => false
fm.slow # => true
fm.can?(:stop, :breaks) # => true
fm.can?(:stop, :no_breaks) # => false
```
### 2.9 target
If you need to execute some external code in the context of the current state machine, pass that object as a first argument to `new` method.
Assuming we have a simple `Engine` class that holds an internal state whether the car's engine is on or off:
```ruby
class Engine
def initialize
@engine = false
end
def turn_on
@engine = true
end
def turn_off
@engine = false
end
def engine_on?
@engine
end
end
```
And given an instance of `Engine` class:
```ruby
engine = Engine.new
```
You can provide a context to a state machine by passing it as a first argument to a `new` call. You can then reference this context inside the callbacks by calling the `target` helper:
```ruby
fm = FiniteMachine.new(engine) do
initial :neutral
event :start, :neutral => :one, unless: "engine_on?"
event :stop, :one => :neutral
on_before_start { |event| target.turn_on }
on_after_stop { |event| target.turn_off }
end
```
For more complex example see [Integration](#7-integration) section.
#### 2.9.1 `:alias_target`
If you wish to better express the intention behind the context object, in particular when calling actions in callbacks, you can use the `:alias_target` option:
```ruby
engine = Engine.new
fm = FiniteMachine.new(engine, alias_target: :engine) do
initial :neutral
event :start, :neutral => :one, unless: "engine_on?"
event :stop, :none => :neutral, if: "engine_on?"
on_before_start { |event| engine.turn_on }
on_after_stop { |event| engine.turn_off }
end
```
Alternatively, you can use the `alias_target` helper method:
```ruby
engine = Engine.new
Car = FiniteMachine.define do
alias_target :engine
initial :neutral
event :start, :neutral => :one, if: "engine_on?"
event :stop, :none => :neutral, if: "engine_on?"
on_before_start { |event| engine.turn_on }
on_after_stop { |event| engine.turn_off }
end
```
Then to link `Car` definition with `Engine` instance, pass the `Engine` instance as a first argument:
```ruby
car = Car.new(engine)
```
Triggering `start` event will change `Engine` instance state from `false` to `true`:
```ruby
engine.engine_on? # => false
car.start
car.current # => :one
engine.engine_on? # => true
```
### 2.10 restore!
In order to set the machine to a given state and thus skip triggering callbacks use the `restore!` method:
```ruby
fm.restore!(:neutral)
```
This method may be suitable when used testing your state machine or in restoring the state from datastore.
### 2.11 states
You can use the `states` method to return an array of all the states for a given state machine.
```ruby
fm.states # => [:none, :green, :yellow, :red]
```
### 2.12 events
To find out all the event names supported by the state machine issue `events` method:
```ruby
fm.events # => [:init, :ready, :go, :stop]
```
## 3. States and Transitions
The **FiniteMachine** DSL exposes the `event` helper to define possible state transitions.
The `event` helper accepts as a first argument the transition's name which will later be used to create
method on the **FiniteMachine** instance. As a second argument the `event` accepts an arbitrary number of states either
in the form of `:from` and `:to` hash keys or by using the state names themselves as key value pairs.
```ruby
event :start, from: :neutral, to: :first
# or
event :start, :neutral => :first
```
Once specified, the **FiniteMachine** will create custom methods for transitioning between each state.
The following methods trigger transitions for the example state machine.
* ready
* go
* stop
You can always opt out from automatic method generation by using [:auto_methods](#271-auto_methods) option.
### 3.1 Triggering transitions
In order to transition to the next reachable state, simply call the event's name on the **FiniteMachine** instance. If the transition succeeds the `true` value is returned, otherwise `false`.
```ruby
fm.ready # => true
fm.current # => :yellow
```
If you prefer you can also use `trigger` method to fire any event by its name:
```ruby
fm.trigger(:ready) # => true
```
Furthermore, you can pass additional parameters with the method call that will be available in the triggered callback as well as used by any present guarding conditions.
```ruby
fm.go("Piotr!") # => true
fm.current # => :green
```
By default **FiniteMachine** will swallow all exceptions when and return `false` on failure. If you prefer to be notified when illegal transition occurs see [Dangerous transitions](#22-dangerous-transitions).
### 3.2 Dangerous transitions
When you declare event, for instance `ready`, the **FiniteMachine** will provide a dangerous version with a bang `ready!`. In the case when you attempt to perform illegal transition or **FiniteMachine** throws internal error, the state machine will propagate the errors. You can use handlers to decide how to handle errors on case by case basis see [6. Error Handling](#6-errors)
```ruby
fm.ready! # => raises FiniteMachine::InvalidStateError
```
If you prefer you can also use `trigger!` method to fire event:
```ruby
fm.trigger!(:ready)
```
### 3.3 Multiple from states
If an event transitions from multiple states to the same state then all the states can be grouped into an array.
Alternatively, you can create separate events under the same name for each transition that needs combining.
```ruby
fm = FiniteMachine.new do
initial :neutral
event :start, :neutral => :one
event :shift, :one => :two
event :shift, :two => :three
event :shift, :three => :four
event :slow, [:one, :two, :three] => :one
end
```
### 3.4 `any_state` transitions
The **FiniteMachine** offers few ways to transition out of any state. This is particularly useful when the machine already defines many states.
You can use `any_state` as the name for a given state, for instance:
```ruby
event :run, from: any_state, to: :green
# or
event :run, any_state => :green
```
Alternatively, you can skip the `any_state` call and just specify `to` state:
```ruby
event :run, to: :green
```
All the above `run` event definitions will always transition the state machine into `:green` state.
### 3.5 Collapsing transitions
Another way to specify state transitions under single event name is to group all your state transitions into a single hash like so:
```ruby
fm = FiniteMachine.new do
initial :initial
event :bump, :initial => :low,
:low => :medium,
:medium => :high
end
```
The same can be more naturally rewritten also as:
```ruby
fm = FiniteMachine.new do
initial :initial
event :bump, :initial => :low
event :bump, :low => :medium
event :bump, :medium => :high
end
```
### 3.6 Silent transitions
The **FiniteMachine** allows to selectively silence events and thus prevent any callbacks from firing. Using the `silent` option passed to event definition like so:
```ruby
fm = FiniteMachine.new do
initial :yellow
event :go :yellow => :green, silent: true
event :stop, :green => :red
end
fm.go # no callbacks
fm.stop # callbacks are fired
```
### 3.7 Logging transitions
To help debug your state machine, **FiniteMachine** provides `:log_transitions` option.
```ruby
FiniteMachine.new(log_transitions: true) do
...
end
```
### 3.8 Conditional transitions
Each event takes an optional `:if` and `:unless` options which act as a predicate for the transition. The `:if` and `:unless` can take a symbol, a string, a Proc or an array. Use `:if` option when you want to specify when the transition **should** happen. If you want to specify when the transition **should not** happen then use `:unless` option.
#### 3.8.1 Using a Proc
You can associate the `:if` and `:unless` options with a Proc object that will get called right before transition happens. Proc object gives you ability to write inline condition instead of separate method.
```ruby
fm = FiniteMachine.new do
initial :green
event :slow, :green => :yellow, if: -> { return false }
end
fm.slow # doesn't transition to :yellow state
fm.current # => :green
```
Condition by default receives the current context, which is the current state machine instance, followed by extra arguments.
```ruby
fm = FiniteMachine.new do
initial :red
event :go, :red => :green,
if: ->(context, a) { context.current == a }
end
fm.go(:yellow) # doesn't transition
fm.go # raises ArgumentError
```
**Note** If you specify condition with a given number of arguments then you need to call an event with the exact number of arguments, otherwise you will get `ArgumentError`. Thus in above scenario to prevent errors specify condition like so:
```ruby
if: ->(context, *args) { ... }
```
Provided your **FiniteMachine** is associated with another object through `target` helper. Then the target object together with event arguments will be passed to the `:if` or `:unless` condition scope.
```ruby
class Engine
def initialize
@engine = false
end
def turn_on
@engine = true
end
def turn_off
@engine = false
end
def engine_on?
@engine
end
end
engine = Engine.new
engine.turn_on
car = FiniteMachine.new(engine) do
initial :neutral
event :start, :neutral => :one, if: ->(target, state) do
state ? target.engine_on : target.engine_off
end
end
fm.start(false)
fm.current # => :neutral
engine.engine_on? # => false
fm.start(true)
fm.current # => :one
engine.engine_on? # => true
```
When the one-liner conditions are not enough for your needs, you can perform conditional logic inside the callbacks. See [4.9 Cancelling callbacks](#49-cancelling-inside-callbacks)
#### 3.8.2 Using a Symbol
You can also use a symbol corresponding to the name of a method that will get called right before transition happens.
```ruby
fm = FiniteMachine.new(engine) do
initial :neutral
event :start, :neutral => :one, if: :engine_on?
end
```
#### 3.8.3 Using a String
Finally, it's possible to use string that will be evaluated using `eval` and needs to contain valid Ruby code. It should only be used when the string represents a short condition.
```ruby
fm = FiniteMachine.new(engine) do
initial :neutral
event :start, :neutral => :one, if: "engine_on?"
end
```
#### 3.8.4 Combining transition conditions
When multiple conditions define whether or not a transition should happen, an Array can be used. Furthermore, you can apply both `:if` and `:unless` to the same transition.
```ruby
fm = FiniteMachine.new do
initial :green
event :slow, :green => :yellow,
if: [ -> { return true }, -> { return true} ],
unless: -> { return true }
event :stop, :yellow => :red
end
```
The transition only runs when all the `:if` conditions and none of the `unless` conditions are evaluated to `true`.
### 3.9 Choice pseudostates
Choice pseudostate allows you to implement conditional branch. The conditions of an event's transitions are evaluated in order to select only one outgoing transition.
You can implement the conditional branch as ordinary events grouped under the same name and use familiar `:if/:unless` conditions:
```ruby
fm = FiniteMachine.define do
initial :green
event :next, :green => :yellow, if: -> { false }
event :next, :green => :red, if: -> { true }
end
fm.current # => :green
fm.next
fm.current # => :red
```
The same conditional logic can be implemented using much shorter and more descriptive style using `choice` method:
```ruby
fm = FiniteMachine.new do
initial :green
event :next, from: :green do
choice :yellow, if: -> { false }
choice :red, if: -> { true }
end
end
fm.current # => :green
fm.next
fm.current # => :red
```
#### 3.9.1 Dynamic choice conditions
Just as with event conditions you can make conditional logic dynamic and dependent on parameters passed in:
```ruby
fm = FiniteMachine.new do
initial :green
event :next, from: :green do
choice :yellow, if: ->(context, a) { a < 1 }
choice :red, if: ->(context, a) { a > 1 }
default :red
end
end
fm.current # => :green
fm.next(0)
fm.current # => :yellow
```
If more than one of the conditions evaluates to true, a first matching one is chosen. If none of the conditions evaluate to true, then the `default` state is matched. However if default state is not present and non of the conditions match, no transition is performed. To avoid such situation always specify `default` choice.
#### 3.9.2 Multiple from states
Similarly to event definitions, you can specify the event to transition from a group of states:
```ruby
FiniteMachine.new do
initial :red
event :next, from: [:yellow, :red] do
choice :pink, if: -> { false }
choice :green
end
end
```
Or from any state using the `:any` state name like so:
```ruby
FiniteMachine.new do
initial :red
event :next, from: :any do
choice :pink, if: -> { false }
choice :green
end
end
```
## 4. Callbacks
You can register a callback to listen for state transitions and events triggered, and based on these perform custom actions. There are five callbacks available in **FiniteMachine**:
* `on_before` - triggered before any transition
* `on_exit` - triggered when leaving any state
* `on_transition` - triggered during any transition
* `on_enter` - triggered when entering any state
* `on_after` - triggered after any transition
Use the state or event name as a first parameter to the callback helper followed by block with event argument and a list arguments that you expect to receive like so:
```ruby
on_enter(:green) { |event, a, b, c| ... }
```
When you subscribe to the `:green` state change, the callback will be called whenever someone triggers event that transitions in or out of that state. The same will happen on subscription to event `ready`, namely, the callback will be called each time the state transition method is triggered regardless of the states it transitions from or to.
```ruby
fm = FiniteMachine.new do
initial :red
event :ready, :red => :yellow
event :go, :yellow => :green
event :stop, :green => :red
on_before :ready do |event, time1, time2, time3|
puts "#{time1} #{time2} #{time3} Go!" }
end
on_before :go do |event, name|
puts "Going fast #{name}"
end
on_before(:stop) { |event| ... }
end
fm.ready(1, 2, 3)
fm.go("Piotr!")
```
**Note** Regardless of how the state is entered or exited, all the associated callbacks will be executed. This provides means for guaranteed initialization and cleanup.
### 4.1 on_(enter|transition|exit)
The `on_enter` callback is executed before given state change is fired. By passing state name you can narrow down the listener to only watch out for enter state changes. Otherwise, all enter state changes will be watched.
The `on_transition` callback is executed when given state change happens. By passing state name you can narrow down the listener to only watch out for transition state changes. Otherwise, all transition state changes will be watched.
The `on_exit` callback is executed after a given state change happens. By passing state name you can narrow down the listener to only watch out for exit state changes. Otherwise, all exit state changes will be watched.
### 4.2 on_(before|after)
The `on_before` callback is executed before a given event happens. By default it will listen out for all events, you can also listen out for specific events by passing event's name.
This callback is executed after a given event happened. By default it will listen out for all events, you can also listen out for specific events by passing event's name.
### 4.3 once_on
**FiniteMachine** allows you to listen on initial state change or when the event is fired first time by using the following 5 types of callbacks:
* `once_on_enter`
* `once_on_transition`
* `once_on_exit`
* `once_before`
* `once_after`
### 4.4 Execution sequence
Assuming we have the following event specified:
```ruby
event :go, :red => :yellow
```
Then by calling `go` event the following callbacks sequence will be executed:
* `on_before` - generic callback before `any` event
* `on_before :go` - callback before the `go` event
* `on_exit` - generic callback for exit from `any` state
* `on_exit :red` - callback for the `:red` state exit
* `on_transition` - callback for transition from `any` state to `any` state
* `on_transition :yellow` - callback for the `:red` to `:yellow` transition
* `on_enter` - generic callback for entry to `any` state
* `on_enter :yellow` - callback for the `:yellow` state entry
* `on_after` - generic callback after `any` event
* `on_after :go` - callback after the `go` event
### 4.5 Callback parameters
All callbacks as a first argument yielded to a block receive the `TransitionEvent` object with the following attributes:
* `name` - the event name`
* `from` - the state transitioning from`
* `to` - the state transitioning to`
followed by the rest of arguments that were passed to the event method.
```ruby
fm = FiniteMachine.new do
initial :red
event :ready, :red => :yellow
on_before_ready do |event, time|
puts "lights switching from #{event.from} to #{event.to} in #{time} seconds"
end
end
fm.ready(3)
# => "lights switching from red to yellow in 3 seconds"
```
### 4.6 Duplicate callbacks
You can define any number of the same kind of callback. These callbacks will be executed in the order they are specified.
Given the following state machine instance:
```ruby
fm = FiniteMachine.new do
initial :green
event :slow, :green => :yellow
on_enter(:yellow) { puts "this is run first" }
on_enter(:yellow) { puts "then this is run" }
end
```
Triggerring the `:slow` event results in:
```ruby
fm.slow
# => "this is run first"
# => "then this is run"
```
### 4.7 Fluid callbacks
Callbacks can also be specified as full method calls separated with underscores:
```ruby
fm = FiniteMachine.define do
initial :red
event :ready, :red => :yellow
event :go, :yellow => :green
event :stop, :green => :red
on_before_ready { |event| ... }
on_before_go { |event| ... }
on_before_stop { |event| ... }
end
```
### 4.8 Methods inside callbacks
Given a class `Car`:
```ruby
class Car
attr_accessor :reverse_lights
def turn_reverse_lights_off
@reverse_lights = false
end
def turn_reverse_lights_on
@reverse_lights = true
end
end
```
We can easily manipulate state for an instance of a `Car` class:
```ruby
car = Car.new
```
By defining finite machine using the instance:
```ruby
fm = FiniteMachine.new(car) do
initial :neutral
event :forward, [:reverse, :neutral] => :one
event :back, [:neutral, :one] => :reverse
on_enter_reverse { |event| target.turn_reverse_lights_on }
on_exit_reverse { |event| target.turn_reverse_lights_off }
end
```
Note that you can also fire events from callbacks.
```ruby
fm = FiniteMachine.new do
initial :neutral
event :forward, [:reverse, :neutral] => :one
event :back, [:neutral, :one] => :reverse
on_enter_reverse { |event| forward("Piotr!") }
on_exit_reverse { |event, name| puts "Go #{name}" }
end
```
Then triggerring `:back` event gives:
```ruby
fm.back # => Go Piotr!
```
For more complex example see [Integration](#7-integration) section.
### 4.9 Cancelling callbacks
A simple way to prevent transitions is to use [3 Conditional transitions](#3-conditional-transitions).
There are times when you want to cancel transition in a callback. For example, you have logic which allows transition to happen only under certain complex conditions. Using `cancel_event` inside the `on_(enter|transition|exit)` or `on_(before|after)` callbacks will stop all the callbacks from firing and prevent current transition from happening.
For example, the following state machine cancels any event leaving `:red` state:
```ruby
fm = FiniteMachine.new do
initial :red
event :ready, :red => :yellow
event :go, :yellow => :green
event :stop, :green => :red
on_exit :red do |event|
...
cancel_event
end
end
```
Then firing `:ready` event will not transition out of the current `:red` state:
```ruby
fm.current # => :red
fm.ready
fm.current # => :red
```
### 4.10 Asynchronous callbacks
By default all callbacks are run synchronously. In order to add a callback that runs asynchronously, you need to pass second `:async` argument like so:
```ruby
on_enter(:green, :async) do |event| ... end
# or
on_enter_green(:async) { |event| }
```
This will ensure that when the callback is fired it will run in separate thread outside of the main execution thread.
### 4.11 Instance callbacks
When defining callbacks you are not limited to the **FiniteMachine** block definition. After creating an instance, you can register callbacks the same way as before by calling `on` and supplying the type of notification and state/event you are interested in.
For example, given the following state machine:
```ruby
fm = FiniteMachine.new do
initial :red
event :ready, :red => :yellow
event :go, :yellow => :green
event :stop, :green => :red
end
```
We can add callbacks as follows:
```ruby
fm.on_enter(:yellow) { |event| ... }
# or
fm.en_enter_yellow { |event| ... }
```
## 5. Error Handling
By default, the **FiniteMachine** will throw an exception whenever the machine is in invalid state or fails to transition.
* `FiniteMachine::TransitionError`
* `FiniteMachine::InvalidStateError`
* `FiniteMachine::InvalidCallbackError`
You can attach specific error handler using the 'handle' with the name of the error as a first argument and a callback to be executed when the error happens. The `handle` receives a list of exception class or exception class names, and an option `:with` with a name of the method or a Proc object to be called to handle the error. As an alternative, you can pass a block.
```ruby
fm = FiniteMachine.new do
initial :green, event: :start
event :slow, :green => :yellow
event :stop, :yellow => :red
handle FiniteMachine::InvalidStateError do |exception|
# run some custom logging
raise exception
end
handle FiniteMachine::TransitionError, with: -> { |exception| ... }
end
```
### 5.1 Using target
You can pass an external context as a first argument to the **FiniteMachine** initialization that will be available as context in the handler block or `:with` value. For example, the `log_error` method is made available when `:with` option key is used:
```ruby
class Logger
def log_error(exception)
puts "Exception : #{exception.message}"
end
end
fm = FiniteMachine.new(logger) do
initial :green
event :slow, :green => :yellow
event :stop, :yellow => :red
handle "InvalidStateError", with: :log_error
end
```
## 6. Stand-alone
**FiniteMachine** allows you to separate your state machine from the target class so that you can keep your concerns broken in small maintainable pieces.
### 6.1 Creating a Definition
You can turn a class into a **FiniteMachine** by simply subclassing `FiniteMachine::Definition`. As a rule of thumb, every single public method of the **FiniteMachine** is available inside your class:
```ruby
class Engine < FiniteMachine::Definition
initial :neutral
event :forward, [:reverse, :neutral] => :one
event :shift, :one => :two
event :back, [:neutral, :one] => :reverse
on_enter :reverse do |event|
target.turn_reverse_lights_on
end
on_exit :reverse do |event|
target.turn_reverse_lights_off
end
handle FiniteMachine::InvalidStateError do |exception|
...
end
end
```
### 6.2 Targeting definition
The next step is to instantiate your state machine and use a custom class instance to load specific context.
For example, having the following `Car` class:
```ruby
class Car
def turn_reverse_lights_off
@reverse_lights = false
end
def turn_reverse_lights_on
@reverse_lights = true
end
def reverse_lights?
@reverse_lights ||= false
end
end
```
Thus, to associate `Engine` to `Car` do:
```ruby
car = Car.new
engine = Engine.new(car)
car.reverse_lignts? # => false
engine.back
car.reverse_lights? # => true
```
Alternatively, create method inside the `Car` that will do the integration like so:
```ruby
class Car
... # as above
def engine
@engine ||= Engine.new(self)
end
end
```
### 6.3 Definition inheritance
You can create more specialised versions of a generic definition by using inheritance. Assuming a generic state machine definition:
```ruby
class GenericStateMachine < FiniteMachine::Definition
initial :red
event :start, :red => :green
on_enter { |event| ... }
end
```
You can easily create a more specific definition that adds new events and more specific callbacks to the mix.
```ruby
class SpecificStateMachine < GenericStateMachine
event :stop, :green => :yellow
on_enter(:yellow) { |event| ... }
end
```
Finally to use the specific state machine definition do:
```ruby
specific_fsm = SpecificStateMachine.new
```
## 7. Integration
Since **FiniteMachine** is an object in its own right, it leaves integration with other systems up to you. In contrast to other Ruby libraries, it does not extend from models (i.e. ActiveRecord) to transform them into a state machine or require mixing into existing classes.
### 7.1 Plain Ruby Objects
In order to use **FiniteMachine** with an object, you need to define a method that will construct the state machine. You can implement the state machine using the `new` DSL or create a separate object that can be instantiated. To complete integration you will need to specify `target` context to allow state machine to communicate with the other methods inside the class like so:
```ruby
class Car
def turn_reverse_lights_off
@reverse_lights = false
end
def turn_reverse_lights_on
@reverse_lights = true
end
def reverse_lights_on?
@reverse_lights || false
end
def gears
@gears ||= FiniteMachine.new(self) do
initial :neutral
event :start, :neutral => :one
event :shift, :one => :two
event :shift, :two => :one
event :back, [:neutral, :one] => :reverse
on_enter :reverse do |event|
target.turn_reverse_lights_on
end
on_exit :reverse do |event|
target.turn_reverse_lights_off
end
on_transition do |event|
puts "shifted from #{event.from} to #{event.to}"
end
end
end
end
```
Having written the class, you can use it as follows:
```ruby
car = Car.new
car.gears.current # => :neutral
car.reverse_lights_on? # => false
car.gears.start # => "shifted from neutral to one"
car.gears.back # => "shifted from one to reverse"
car.gears.current # => :reverse
car.reverse_lights_on? # => true
```
### 7.2 ActiveRecord
In order to integrate **FiniteMachine** with ActiveRecord simply add a method with state machine definition. You can also define the state machine in separate module to aid reusability. Once the state machine is defined use the `target` helper to reference the current class. Having defined `target` you call ActiveRecord methods inside the callbacks to persist the state.
You can use the `restore!` method to specify which state the **FiniteMachine** should be put back into as follows:
```ruby
class Account < ActiveRecord::Base
validates :state, presence: true
before_validation :set_initial_state, on: :create
def set_initial_state
self.state = manage.current
end
after_find :restore_state
after_initialize :restore_state
def restore_state
manage.restore!(state.to_sym) if state.present?
end
def manage
@manage ||= FiniteMachine.new(self) do
initial :unapproved
event :enqueue, :unapproved => :pending
event :authorize, :pending => :access
on_enter do |event|
target.state = event.to
end
end
end
end
account = Account.new
account.state # => :unapproved
account.manage.enqueue
account.state # => :pending
account.manage.authorize
account.state # => :access
```
Please note that you do not need to call `target.save` inside callback, it is enough to just set the state. It is much more preferable to let the `ActiveRecord` object to persist when it makes sense for the application and thus keep the state machine focused on managing the state transitions.
### 7.3 Transactions
When using **FiniteMachine** with ActiveRecord it advisable to trigger state changes inside transactions to ensure integrity of the database. Given Account example from section 7.2 one can run event in transaction in the following way:
```ruby
ActiveRecord::Base.transaction do
account.manage.enqueue
end
```
If the transition fails it will raise `TransitionError` which will cause the transaction to rollback.
Please check the ORM of your choice if it supports database transactions.
## 8 Tips
Creating a standalone **FiniteMachine** brings a number of benefits, one of them being easier testing. This is especially true if the state machine is extremely complex itself. Ideally, you would test the machine in isolation and then integrate it with other objects or ORMs.
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## Code of Conduct
Everyone interacting in the FiniteMachine project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/finite_machine/blob/master/CODE_OF_CONDUCT.md).
## Copyright
Copyright (c) 2014 Piotr Murach. See LICENSE for further details.