simple_states

A super-slim statemachine-like support library

Description

A super-slim (~200 loc) statemachine-like support library focussed on use in Travis CI.

Note that the current version behaves slightly differently, and comes with reduced features compared to the original version. If you are looking for the original version see the tag v1.1.0.rc11.

Code Quality Rank: L5

Monthly Downloads: 3,335

Programming language: Ruby

License: MIT License

Tags: State Machines     Rails Plugins    

Latest version: v2.0.1

README

simple_states

A super-slim (~200 loc) statemachine-like support library focussed on use in Travis CI.

Note that the current version behaves slightly differently, and comes with reduced features compared to the original version. If you are looking for the original version see the tag v1.1.0.rc11.

Usage

Define states and events like this:

class Foo
  include SimpleStates

  event :start,  if: :start?
  event :finish, to: [:passed, :failed], after: :notify, unless: :finished?

  attr_accessor :state, :started_at, :finished_at

  def start
    # start foo
  end

  def start?
    true
  end

  def notify(event)
    # notify about event on foo
  end
end

SimpleStates expects your model to support attribute accessors for :state.

Event options have the following well-known meanings:

:to     # allowed target states to transition to, deferred from the event name if not given
:if     # only proceed if the given method returns true
:unless # only proceed if the given method returns false
:before # run the given method before running `super` and setting the new state
:after  # run the given method at the very end

All of these options except can be given as a single symbol or string or as an Array of symbols or strings.

Calling event will effectively add methods to a proxy module which is prepended to your class (included to the singleton class of your class' instances on 1.9). E.g. declaring event :start in the example above will add methods start and start! to a module included to the singleton class of instances of Foo.

This method will

1. check if :if/:unless conditions apply (if given) and just return from the method otherwise
2. run :before callbacks (if given)
3. set the object's state to the target state
4. set the object's [state]_at attribute to Time.now if the object defines a writer for it
5. call super if Foo defines the current method (i.e. call start but not finish in the example above)
6. run :after callbacks (if given)

You can define options for all events like so:

event :finish, after: :cleanup
event :all,    after: :notify

This will call :cleanup first and then :notify on :finish.

If no target state was given for an event then SimpleStates will try to derive it from the event name. I.e. for an event start it will check the states list for a state started and use it. If it can not find a target state this way then it will raise an exception.