edge-state-machine 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,4 @@
+--colour
+#--drb
+--format documentation
+#--fail-fast

data/.travis.yml

@@ -0,0 +1 @@
+rvm: 1.9.2

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in edge-state-machine.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,63 @@
+= Travis Build Status
+
+{<img src="https://secure.travis-ci.org/danpersa/edge-state-machine.png"/>}[http://travis-ci.org/danpersa/edge-state-machine]
+
+= Edge State Machine
+
+The gem is based on Rick Olson's code of ActiveModel::StateMachine,
+axed from ActiveModel in {this
+commit}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
+
+And on Krzysiek Heród's gem, {Transitions}[https://github.com/netizer/transitions], which added Mongoid support.
+
+== Installation
+
+If you're using Rails + ActiveRecord + Bundler
+
+  # in your Gemfile
+  gem "edge-state-machine", :require => ["edge-state-machine", "active_record/edge-state-machine"]
+
+  # in your AR models that will use the state machine
+  include ::EdgeStateMachine
+  include ActiveRecord::EdgeStateMachine
+
+  state_machine do
+    state :available # first one is initial state
+    state :out_of_stock
+    state :discontinue
+
+    event :discontinue do
+      transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
+    end
+    event :out_of_stock do
+      transitions :to => :out_of_stock, :from => [:available, :discontinue]
+    end
+    event :available do
+      transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
+    end
+  end
+
+If you're using Rails + Mongoid + Bundler
+
+  # in your Gemfile
+  gem "edge-state-machine", :require => ["edge-state-machine", "mongoid/edge-state-machine"]
+
+  # in your AR models that will use the state machine
+  include ::EdgeStateMachine
+  include Mongoid::EdgeStateMachine
+
+  state_machine do
+    state :available # first one is initial state
+    state :out_of_stock
+    state :discontinue
+
+    event :discontinue do
+      transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
+    end
+    event :out_of_stock do
+      transitions :to => :out_of_stock, :from => [:available, :discontinue]
+    end
+    event :available do
+      transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
+    end
+  end

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'bundler'
+require 'bundler/gem_tasks'
+
+
+Bundler::GemHelper.install_tasks
+Bundler.setup
+
+require 'rake'
+
+begin
+  require 'rspec/core/rake_task'
+  desc 'Run RSpecs to confirm that all functionality is working as expected'
+  RSpec::Core::RakeTask.new('spec') do |t|
+    t.pattern = 'spec/**/*_spec.rb'
+  end
+  task :default => :spec
+rescue LoadError
+  puts "Hiding spec tasks because RSpec is not available"
+end

data/edge-state-machine.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "edge-state-machine/version"
+
+Gem::Specification.new do |s|
+  s.name        = "edge-state-machine"
+  s.version     = EdgeStateMachine::VERSION
+  s.authors     = ["Dan Persa"]
+  s.email       = ["dan.persa@gmail.com"]
+  s.homepage    = "http://github.com/danpersa/edge-state-machine"
+  s.summary     = %q{State machine extracted from ActiveModel}
+  s.description = %q{Lightweight state machine extracted from ActiveModel}
+
+  s.rubyforge_project = "edge-state-machine"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency 'rspec', '~> 2.6'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'mongoid'
+  s.add_development_dependency 'bson_ext'
+  s.add_development_dependency 'sqlite3-ruby'
+  s.add_development_dependency 'activerecord'
+
+  # s.add_runtime_dependency "rest-client"
+end

data/lib/active_record/edge-state-machine.rb

@@ -0,0 +1,34 @@
+module ActiveRecord
+  module EdgeStateMachine
+    extend ActiveSupport::Concern
+
+    included do
+      include ::EdgeStateMachine
+      after_initialize :set_initial_state
+      validates_presence_of :state
+      validate :state_inclusion
+    end
+
+    protected
+
+    def write_state(state_machine, state)
+      self.state = state.to_s
+      save!
+    end
+
+    def read_state(state_machine)
+      self.state.to_sym
+    end
+
+    def set_initial_state
+      self.state ||= self.class.state_machine.initial_state.to_s
+    end
+
+    def state_inclusion
+      unless self.class.state_machine.states.map{|s| s.name.to_s }.include?(self.state.to_s)
+        self.errors.add(:state, :inclusion, :value => self.state)
+      end
+    end
+  end
+end
+

data/lib/edge-state-machine/event.rb

@@ -0,0 +1,107 @@
+module EdgeStateMachine
+  class Event
+    attr_reader :name, :success, :timestamp
+
+    def initialize(machine, name, options = {}, &block)
+      @machine, @name, @transitions = machine, name, []
+      if machine
+        machine.klass.send(:define_method, "#{name}!") do |*args|
+          machine.fire_event(name, self, true, *args)
+        end
+
+        machine.klass.send(:define_method, name.to_s) do |*args|
+          machine.fire_event(name, self, false, *args)
+        end
+      end
+      update(options, &block)
+    end
+
+    def fire(obj, to_state = nil, *args)
+      transitions = @transitions.select { |t| t.from == obj.current_state(@machine ? @machine.name : nil) }
+      raise InvalidTransition if transitions.size == 0
+
+      next_state = nil
+      transitions.each do |transition|
+        next if to_state && !Array(transition.to).include?(to_state)
+        if transition.perform(obj)
+          next_state = to_state || Array(transition.to).first
+          transition.execute(obj, *args)
+          break
+        end
+      end
+      # Update timestamps on obj if a timestamp has been defined
+      update_event_timestamp(obj, next_state) if timestamp_defined?
+      next_state
+    end
+
+    def transitions_from_state?(state)
+      @transitions.any? { |t| t.from? state }
+    end
+
+    def ==(event)
+      if event.is_a? Symbol
+        name == event
+      else
+        name == event.name
+      end
+    end
+    
+    # Has the timestamp option been specified for this event?
+    def timestamp_defined?
+      !@timestamp.nil?
+    end
+
+    def update(options = {}, &block)
+      @success       = options[:success] if options.key?(:success)
+      self.timestamp = options[:timestamp] if options[:timestamp]
+      instance_eval(&block) if block
+      self
+    end
+    
+    # update the timestamp attribute on obj
+    def update_event_timestamp(obj, next_state)
+      obj.send "#{timestamp_attribute_name(obj, next_state)}=", Time.now
+    end
+    
+    # Set the timestamp attribute.
+    # @raise [ArgumentError] timestamp should be either a String, Symbol or true
+    def timestamp=(value)
+      case value
+      when String, Symbol, TrueClass
+        @timestamp = value
+      else
+        raise ArgumentError, "timestamp must be either: true, a String or a Symbol"
+      end
+    end
+    
+
+    private
+    
+    # Returns the name of the timestamp attribute for this event
+    # If the timestamp was simply true it returns the default_timestamp_name
+    # otherwise, returns the user-specified timestamp name
+    def timestamp_attribute_name(obj, next_state)
+      timestamp == true ? default_timestamp_name(obj, next_state) : @timestamp
+    end
+    
+    # If @timestamp is true, try a default timestamp name
+    def default_timestamp_name(obj, next_state)
+      at_name = "%s_at" % next_state
+      on_name = "%s_on" % next_state
+      case
+      when obj.respond_to?(at_name) then at_name
+      when obj.respond_to?(on_name) then on_name
+      else
+        raise NoMethodError, "Couldn't find a suitable timestamp field for event: #{@name}. 
+          Please define #{at_name} or #{on_name} in #{obj.class}"
+      end
+    end
+    
+
+    def transitions(trans_opts)
+      Array(trans_opts[:from]).each do |s|
+        @transitions << StateTransition.new(trans_opts.merge({:from => s.to_sym}))
+      end
+    end
+  end
+end

data/lib/edge-state-machine/machine.rb

@@ -0,0 +1,85 @@
+module EdgeStateMachine
+  class Machine
+    attr_writer :initial_state
+    attr_accessor :states, :events, :state_index
+    attr_reader :klass, :name, :auto_scopes
+
+    def initialize(klass, name, options = {}, &block)
+      @klass, @name, @states, @state_index, @events = klass, name, [], {}, {}
+      update(options, &block)
+    end
+
+    def initial_state
+      @initial_state ||= (states.first ? states.first.name : nil)
+    end
+
+    def update(options = {}, &block)
+      @initial_state = options[:initial] if options.key?(:initial)
+      @auto_scopes = options[:auto_scopes]
+      instance_eval(&block) if block
+      include_scopes if @auto_scopes && defined?(ActiveRecord::Base) && @klass < ActiveRecord::Base
+      self
+    end
+
+    def fire_event(event, record, persist, *args)
+      state_index[record.current_state(@name)].call_action(:exit, record)
+      if new_state = @events[event].fire(record, nil, *args)
+        state_index[new_state].call_action(:enter, record)
+
+        if record.respond_to?(event_fired_callback)
+          record.send(event_fired_callback, record.current_state, new_state, event)
+        end
+
+        record.current_state(@name, new_state, persist)
+        record.send(@events[event].success) if @events[event].success
+        true
+      else
+        if record.respond_to?(event_failed_callback)
+          record.send(event_failed_callback, event)
+        end
+
+        false
+      end
+    end
+
+    def states_for_select
+      states.map { |st| [st.display_name, st.name.to_s] }
+    end
+
+    def events_for(state)
+      events = @events.values.select { |event| event.transitions_from_state?(state) }
+      events.map! { |event| event.name }
+    end
+
+    def current_state_variable
+      "@#{@name}_current_state"
+    end
+
+    private
+
+    def state(name, options = {})
+      @states << (state_index[name] ||= State.new(name, :machine => self)).update(options)
+    end
+
+    def event(name, options = {}, &block)
+      (@events[name] ||= Event.new(self, name)).update(options, &block)
+    end
+
+    def event_fired_callback
+      @event_fired_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_fired'
+    end
+
+    def event_failed_callback
+      @event_failed_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_failed'
+    end
+
+    def include_scopes
+      @states.each do |state|
+        state_name = state.name.to_s
+        raise InvalidMethodOverride if @klass.respond_to?(state_name)
+        @klass.scope state_name, @klass.where(:state => state_name)
+      end
+    end
+  end
+end
+

data/lib/edge-state-machine/state.rb

@@ -0,0 +1,45 @@
+module EdgeStateMachine
+  class State
+    attr_reader :name, :options
+
+    def initialize(name, options = {})
+      @name = name
+      if machine = options.delete(:machine)
+        machine.klass.define_state_query_method(name)
+      end
+      update(options)
+    end
+
+    def ==(state)
+      if state.is_a? Symbol
+        name == state
+      else
+        name == state.name
+      end
+    end
+
+    def call_action(action, record)
+      action = @options[action]
+      case action
+      when Symbol, String
+        record.send(action)
+      when Proc
+        action.call(record)
+      end
+    end
+
+    def display_name
+      @display_name ||= name.to_s.gsub(/_/, ' ').capitalize
+    end
+
+    def for_select
+      [display_name, name.to_s]
+    end
+
+    def update(options = {})
+      @display_name = options.delete(:display) if options.key?(:display)
+      @options = options
+      self
+    end
+  end
+end

data/lib/edge-state-machine/state_transition.rb

@@ -0,0 +1,47 @@
+module EdgeStateMachine
+  class StateTransition
+    attr_reader :from, :to, :options
+
+    def initialize(opts)
+      @from, @to, @guard, @on_transition = opts[:from], opts[:to], opts[:guard], opts[:on_transition]
+      @options = opts
+    end
+
+    def perform(obj)
+      case @guard
+      when Symbol, String
+        obj.send(@guard)
+      when Proc
+        @guard.call(obj)
+      else
+        true
+      end
+    end
+
+    def execute(obj, *args)
+      case @on_transition
+      when Symbol, String
+        obj.send(@on_transition, *args)
+      when Proc
+        @on_transition.call(obj, *args)
+      when Array
+        @on_transition.each do |callback|
+          # Yes, we're passing always the same parameters for each callback in here.
+          # We should probably drop args altogether in case we get an array.
+          obj.send(callback, *args)
+        end
+      else
+        # TODO We probably should check for this in the constructor and not that late.
+        raise ArgumentError, "You can only pass a Symbol, a String, a Proc or an Array to 'on_transition' - got #{@on_transition.class}." unless @on_transition.nil?
+      end
+    end
+
+    def ==(obj)
+      @from == obj.from && @to == obj.to
+    end
+
+    def from?(value)
+      @from == value
+    end
+  end
+end

data/lib/edge-state-machine/version.rb

@@ -0,0 +1,3 @@
+module EdgeStateMachine
+  VERSION = "0.0.1"
+end

data/lib/edge-state-machine.rb

@@ -0,0 +1,71 @@
+require "edge-state-machine/event"
+require "edge-state-machine/machine"
+require "edge-state-machine/state"
+require "edge-state-machine/state_transition"
+require "edge-state-machine/version"
+
+module EdgeStateMachine
+  class InvalidTransition     < StandardError; end
+  class InvalidMethodOverride < StandardError; end
+
+  module ClassMethods
+    def inherited(klass)
+      super
+      klass.state_machines = state_machines
+    end
+
+    def state_machines
+      @state_machines ||= {}
+    end
+
+    def state_machines=(value)
+      @state_machines = value ? value.dup : nil
+    end
+
+    def state_machine(name = nil, options = {}, &block)
+      if name.is_a?(Hash)
+        options = name
+        name    = nil
+      end
+      name ||= :default
+      state_machines[name] ||= Machine.new(self, name)
+      block ? state_machines[name].update(options, &block) : state_machines[name]
+    end
+
+    def define_state_query_method(state_name)
+      name = "#{state_name}?"
+      undef_method(name) if method_defined?(name)
+      class_eval "def #{name}; current_state.to_s == %(#{state_name}) end"
+    end
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  def current_state(name = nil, new_state = nil, persist = false)
+    sm   = self.class.state_machine(name)
+    ivar = sm.current_state_variable
+    if name && new_state
+      if persist && respond_to?(:write_state)
+        write_state(sm, new_state)
+      end
+
+      if respond_to?(:write_state_without_persistence)
+        write_state_without_persistence(sm, new_state)
+      end
+
+      instance_variable_set(ivar, new_state)
+    else
+      instance_variable_set(ivar, nil) unless instance_variable_defined?(ivar)
+      value = instance_variable_get(ivar)
+      return value if value
+
+      if respond_to?(:read_state)
+        value = instance_variable_set(ivar, read_state(sm))
+      end
+
+      value || sm.initial_state
+    end
+  end
+end

data/lib/mongoid/edge-state-machine.rb

@@ -0,0 +1,34 @@
+module Mongoid
+  module EdgeStateMachine
+    extend ActiveSupport::Concern
+
+    included do
+      include ::EdgeStateMachine
+      after_initialize :set_initial_state
+      validates_presence_of :state
+      validate :state_inclusion
+    end
+
+    protected
+
+    def write_state(state_machine, state)
+      self.state = state.to_s
+      save!
+    end
+
+    def read_state(state_machine)
+      self.state.to_sym
+    end
+
+    def set_initial_state
+      self.state ||= self.class.state_machine.initial_state.to_s
+    end
+
+    def state_inclusion
+      unless self.class.state_machine.states.map{|s| s.name.to_s }.include?(self.state.to_s)
+        self.errors.add(:state, :inclusion, :value => self.state)
+      end
+    end
+  end
+end
+

data/spec/active_record_helper.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+require 'active_record'
+require 'active_support/core_ext/module/aliasing'
+require 'migrations/create_orders'
+require 'migrations/create_traffic_lights'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'active_record/edge-state-machine'