Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Ruby Statemachine that focuses on events instead of states.
branch: master

This branch is 123 commits behind mdh:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
autotest
examples
lib
spec
.gitignore
.rspec
Gemfile
LICENSE
README.rdoc
Rakefile
simple_state_machine.gemspec

README.rdoc

SimpleStateMachine

A simple DSL to decorate existing methods with state transition guards.

Instead of using a DSL to define events, SimpleStateMachine decorates methods to help you encapsulate state and guard state transitions.

Example usage

Write a method, arguments are allowed:

def activate_account(activation_code)
  # call other methods, no need to add these in callbacks
  ...
  log.debug "Try to activate account with #{activation_code}"
end

Now mark the method as an event and specify how the state should transition when the method is called. In this example, the activate_account method will set the state to :active if the initial state is :pending.

event :activate_account, :pending => :active

That's it! You can now call the method and the state will automatically change. If the state change is not allowed, a SimpleStateMachine::Error is raised.

Example usage with ActiveRecord / ActiveModel

When using ActiveRecord / ActiveModel you can add an error to the errors object. This will prevent the state from being changed.

def activate_account(activation_code)
  if activation_code_invalid?(activation_code)
    errors.add(:activation_code, 'Invalid')
  end
end

Example usage with exceptions

You can rescue exceptions and specify the failure state

def download_data
  Service.download_data
end
event :download_data, :pending => :downloaded,
      Service::ConnectionError => :download_failed

More complete implementation

To add a state machine:

  • extend SimpleStateMachine

  • set the initial state

  • turn methods into events

    class LampWithHotelSwitch
    
      extend SimpleStateMachine
    
      def initialize
        self.state = :off
      end
    
      def push_switch_1
        puts 'pushed switch 1 #{state}'
      end
      event :push_switch_1, :off => :on,
                            :on  => :off
    
      # define another event
      # note that implementation of :push_switch_2 is optional
      event :push_switch_2, :off => :on,
                            :on  => :off
    
    end

ActiveRecord Example

To add a state machine with ActiveRecord persistence:

  • extend SimpleStateMachine::ActiveRecord,

  • set the initial state in after_initialize,

  • turn methods into events

    class User < ActiveRecord::Base
    
      extend SimpleStateMachine::ActiveRecord
      # define a custum state_method (state is default)
      state_machine_definition.state_method = :ssm_state
    
      def after_initialize
        self.ssm_state ||= 'new'
        # if you get an ActiveRecord::MissingAttributeError
        # you'll probably need to do (http://bit.ly/35q23b):
        #   write_attribute(:ssm_state, "new") unless read_attribute(:ssm_state)
      end
    
      def invite
        self.activation_code = Digest::SHA1.hexdigest("salt #{Time.now.to_f}")
        #send_activation_email
      end
      event :invite, :new => :invited
    
      def confirm_invitation activation_code
        if self.activation_code != activation_code
          errors.add 'activation_code', 'is invalid'
        end
      end
      event :confirm_invitation, :invited => :active
    
      # :all can be used to catch all from states
      event :suspend, :all => :suspended
    end

This generates the following methods

  • {event}_and_save works like save

  • {event}_and_save! works like save!

  • {event}! works the same as {event}_and_save!

  • {state}? whether or not the current state is {state}

This code was just released, we do not claim it to be stable.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright

Copyright © 2010 Marek & Petrik. See LICENSE for details.

Something went wrong with that request. Please try again.