Tested with Rubies 2.1.0, 2.2.4 and 2.3.2
class Button < StateHolder
attr_reader :name
def initialize(opts: {})
@name = opts.fetch :name
super
end
def transition_to(state)
super(state)
end
def prior_state
history[-2] || :NullState
end
end
class Off < State
def press
transition_to(:On)
end
private
def enter
buzz
# turn_light_off
end
def exit
end
def buzz(sec: 0.5)
# sound buzzer for sec seconds
end
end
class On < State
def press
transition_to(:Off)
end
private
def enter
flash(3)
# turn_button_light_on
end
def exit
end
def flash(n)
# n.times { turn_button_light_on_then_off }
end
end
button = Button.new(initial_state: :Off)
on_state = On.new(holder: button)
off_state = Off.new(holder: button)
button.start #=> current_state: Off
button.press #=> current_state: On
button.press #=> current_state: OffSimplestate arose out of a desire for a very low ceremony mechanism to implement a state machine. SimpleDelegator (delegate.rb) is used to implement this. Because SimpleDelegator supports dynamically swapping the object to which methods are delegated, it provides a good base for Simplestate.
The current version (2.0.0) is a rewrite of SimpleState. State logic is provided via instances of the appropriate subclasses of State. A state is referenced via a symbol created by symbolizing the state's name. A list of state instances available for transitions is maintained by the state holder in a hash keyed on the state symbols. This is an incomplete variant of the singleton pattern. It solved some issues I was having with the previous version of SimpleState, but please use some care. For example, there is no logic to actually prevent creation of more than one instance of a given State subclass. Doing this would likely create bugs that will eventually bite you. :-(
The StateHolder class provides the required functionality for a basic state machine: methods to set the initial state and to transition to a new state. To complement this a State class is provided to serve as ancestor to the states of the state holder. A State instance stores a reference to the state holder and a private #transition_to method which simply calls the state holder’s private #transition_to. This calling of a private method of another object is usually to be avoided. Making state_holder#transition_to private is chosen here to allow indication that external users of the state machine should not use state_holder#transition_to. The state_holder and it's associated states are closely linked and share much knowledge about each other. They are "co-dependent" due to the choice of using SimpleDelegator. As such I believe it is acceptable for a state to call the private method in its corresponding state holder.
StateHolder and State are not expected to be used directly. Rather, they are intended to be the ancestors of the actual state holder and states. A state should provide only methods that are unique to it. Methods that are not specific to a state should be provided by the state holder. The public methods of a child state act as receivers of event messages via delegation from the state holder. Such events may cause effects that are managed by the current state and may also cause transition to a new state. State change logic is expected to be held within the current state. Two private methods, #enter and #exit, must be provided by each state. These are called by the state holder #transition_to method at the appropriate points in the state life cycle. Neither #enter nor #exit nor any other private method of a state are intended to be called by a user of the state holder. To avoid potentially stepping on the user's code #enter and #exit are called with __send__.
For convenience StateHolder provides instance methods, #current_state, #history, and #hx_size_limit to provide easy access to the underlying method, __getobj__ of SimpleDelegator, and to the read methods of the StateHistory container. The StateHistory container holds a list of the most recent state transitions from the state holder. Because the transition history could grow quite large that history is limited to the last 10 transitions by default. The history size limit may be changed via #hx_size_limit at creation of the state holder. That limit may NOT be changed later
Simplestate does not provide a DSL for specifying the events, states and allowed state transitions. That logic must be specified within each state. Neither does Simplestate provide any mechanism for serialization. There is no "magic" here. It is just a couple of PORO's. As such, it is very easy to see and to reason about what is happening within Simplestate. It should not be too difficult to add serialization support to Simplestate.
As an aside, I have looked into providing the Simplestate functionality via a module. However, I found that the SimpleDelegator class provides delegation via a mechanism that makes a module based Simplestate implementation very difficult to achieve. The complexity of that implementation seemed to be not worth the effort. I think the StatePattern gem by Daniel Cadenas, the inspiration for Simplestate, ran into just this problem. I chose to avoid that issue by relying solely on inheritance.
Add this line to your application's Gemfile:
gem 'simplestate'And then execute:
$ bundle install
Or install it yourself as:
$ gem install simplestate
Inherit from StateHolder to create the class of the object that will hold states. You may provide a default initial_state. You must call super if you provide an initialize method in your holder class:
class Button < StateHolder
attr_reader :color
def initialize(opts: {})
@color = opts.fetch :color
super
end
# button methods here
endCreation of a StateHolder instance may specify the initial state. StateHolder expects to receive the initial state as a symbol based on the state name. The name case is preserved in creating the symbol.:
button = Button.new( initial_state: :Off )or
button = Button.new()If you want to set additional attributes at creation of a new button, do so within the opts hash when new is called. Set the attribute from the opts hash in initialize.
button = Button.new( opts: {color: 'Red'} )After creation of a state holder it must be started:
button = Button.new
button.start(:Off)If the initial state is not directly supplied to the start method, then it must have been supplied at state holder creation:
button = Button.new( initial_state: :Off )
button.startInherit from State to create a class to provide specific state behaviors:
class Off < State
def press
transition_to(:On)
end
def name
'Off'
end
private
def enter
end
def exit
end
endThe subclassed state must provide private #enter and #exit methods. Any other state methods intended to be available via a method call on the state holder must be public. The private methods, #enter and #exit, will always be called appropriately during state transitions.
A state has access to methods on the state holder via #holder:
holder.specialmethodThe button module (test/dummy/button.rb) provides an example of the usage of Simplestate. Tests of this are provided in button_test.rb.
A working minimal example app is provided at https://github.com/dpneumo/simplestate-demo
If a DSL is desired, complex state functionality is required, events may arrive asynchronously from multiple sources, or state machine functionality must be provided via inclusion of a module rather than via inheritance then Simplestate is probably not appropriate. Consider looking at the Statemachine, AASM or Workflow gems. The Ruby Toolbox provides links to several other statemachine implementations.
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
StateHolderInterfaceTest and StateInterfaceTest are provided to verify that your state holder and state instances respond to the minimum required method calls for each. Simply include these in the tests of your decendents of StateHolder and State and in any dummies of these classes you may use in your tests.
To install this gem onto your local machine, run bundle exec rake install.
Bug reports and pull requests are welcome on GitHub at https://github.com/dpneumo/simplestate. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.