ardm-is-state_machine 1.2.0

data/lib/dm-is-state_machine/is/dsl/state_dsl.rb

@@ -0,0 +1,40 @@
+module DataMapper
+  module Is
+    module StateMachine
+      # State DSL (Domain Specific Language)
+      module StateDsl
+
+        # Define a state of the system.
+        #
+        # Example:
+        #
+        #   class TrafficLight
+        #     include DataMapper::Resource
+        #     property :id, Serial
+        #     is :state_machine do
+        #       state :green,  :enter => Proc.new { |o| o.log("G") }
+        #       state :yellow, :enter => Proc.new { |o| o.log("Y") }
+        #       state :red,    :enter => Proc.new { |o| o.log("R") }
+        #
+        #       # event definitions go here...
+        #     end
+        #
+        #     def log(string)
+        #       Merb::Logger.info(string)
+        #     end
+        #   end
+        def state(name, options = {})
+          unless state_machine_context?(:is)
+            raise InvalidContext, "Valid only in 'is :state_machine' block"
+          end
+
+          # ===== Setup context =====
+          machine = @is_state_machine[:machine]
+          state = Data::State.new(name, machine, options)
+          machine.states << state
+        end
+
+      end # StateDsl
+    end # StateMachine
+  end # Is
+end # DataMapper

data/lib/dm-is-state_machine/is/state_machine.rb

@@ -0,0 +1,139 @@
+module DataMapper
+  module Is
+    module StateMachine
+
+      class InvalidContext  < RuntimeError; end
+      class InvalidState    < RuntimeError; end
+      class InvalidEvent    < RuntimeError; end
+      class EventConfusion  < RuntimeError; end
+      class DuplicateStates < RuntimeError; end
+      class NoInitialState  < RuntimeError; end
+
+      ##
+      # Makes a column ('state' by default) act as a state machine. It will
+      # define the property if it does not exist.
+      #
+      # @example [Usage]
+      #   is :state_machine
+      #   is :state_machine, :initial => :internal
+      #   is :state_machine, :column => :availability
+      #   is :state_machine, :column => :availability, :initial => :external
+      #
+      # @param options<Hash> a hash of options
+      #
+      # @option :column<Symbol> the name of the custom column
+      #
+      def is_state_machine(options = {}, &block)
+        extend DataMapper::Is::StateMachine::EventDsl
+        extend DataMapper::Is::StateMachine::StateDsl
+        include DataMapper::Is::StateMachine::InstanceMethods
+
+        # ===== Setup context =====
+        options = { :column => :state, :initial => nil }.merge(options)
+        column  = options[:column]
+        initial = options[:initial].to_s
+        unless properties.detect { |p| p.name == column }
+          property column, String, :default => initial
+        end
+        machine = Data::Machine.new(column, initial)
+        @is_state_machine = { :machine => machine }
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{column}=(value)
+            value = value.to_s if value.kind_of?(Symbol)
+            attribute_set(#{column.inspect}, value)
+          end
+        RUBY
+
+        # ===== Define callbacks =====
+        # TODO: define callbacks
+        # before :save do
+        #   if self.new_record?
+        #     # ...
+        #   else
+        #     # ...
+        #   end
+        # end
+
+        before :destroy do
+          # Do we need to do anything here?
+        end
+
+        # ===== Setup context =====
+        push_state_machine_context(:is)
+
+        yield if block_given?
+
+        # ===== Teardown context =====
+        pop_state_machine_context
+      end
+
+      def inherited(base)
+        super
+        base.class_eval do
+          @is_state_machine = superclass.instance_variable_get(:@is_state_machine)
+        end
+      end
+
+      protected
+
+      def push_state_machine_context(label)
+        @is_state_machine ||= {}
+        @is_state_machine[:context] ||= []
+        @is_state_machine[:context] << label
+
+        # Compacted, but barely readable for humans
+        # ((@is_state_machine ||= {})[:context] ||= []) << label
+      end
+
+      def pop_state_machine_context
+        @is_state_machine[:context].pop
+      end
+
+      def state_machine_context?(label)
+        (i = @is_state_machine) && (c = i[:context]) &&
+        c.respond_to?(:include?) && c.include?(label)
+      end
+
+      module InstanceMethods
+
+        def initialize(*args)
+          super
+          # ===== Run :enter hook if present =====
+          return unless is_sm = model.instance_variable_get(:@is_state_machine)
+          return unless machine = is_sm[:machine]
+          return unless initial = machine.initial
+          return unless initial_state = machine.find_state(initial)
+          run_hook_if_present initial_state.options[:enter]
+        end
+
+        # hook may be either a Proc or symbol
+        def run_hook_if_present(hook)
+          return unless hook
+          if hook.respond_to?(:call)
+            hook.call(self)
+          else
+            __send__(hook)
+          end
+        end
+
+        def transition!(event_name)
+          machine = model.instance_variable_get(:@is_state_machine)[:machine]
+          column = machine.column
+          machine.current_state_name = __send__(column)
+          machine.fire_event(event_name, self)
+          __send__("#{column}=", machine.current_state_name)
+        end
+
+      end # InstanceMethods
+
+    end # StateMachine
+  end # Is
+end # DataMapper
+
+# Notes
+# -----
+#
+# Since this gets mixed into a class, I try to keep the namespace pollution
+# down to a minimum.  This is why I only use the @is_state_machine instance
+# variable.

data/lib/dm-is-state_machine/is/version.rb

@@ -0,0 +1,7 @@
+module DataMapper
+  module Is
+    module StateMachine
+      VERSION = '1.2.0'
+    end
+  end
+end

data/spec/examples/invalid_events.rb

@@ -0,0 +1,20 @@
+# An invalid example.
+class InvalidEvents
+  include DataMapper::Resource
+
+  property :id, Serial
+
+  is :state_machine do
+    state :day
+    state :night
+  end
+
+  # The next lines are intentionally incorrect.
+  #
+  # 'event' only makes sense in a block under 'is :state_machine'
+  event :sunrise
+  event :sunset
+
+end
+
+InvalidEvents.auto_migrate!

data/spec/examples/invalid_states.rb

@@ -0,0 +1,20 @@
+# An invalid example.
+class InvalidStates
+  include DataMapper::Resource
+
+  property :id, Serial
+
+  is :state_machine do
+    event :sunrise
+    event :sunset
+  end
+
+  # The next lines are intentionally incorrect.
+  #
+  # 'state' only makes sense in a block under 'is :state_machine'
+  state :light
+  state :dark
+
+end
+
+InvalidStates.auto_migrate!

data/spec/examples/invalid_transitions_1.rb

@@ -0,0 +1,22 @@
+# An invalid example.
+class InvalidTransitions1
+  include DataMapper::Resource
+
+  property :id, Serial
+
+  is :state_machine do
+    state :happy
+    state :sad
+
+    event :toggle
+
+    # The next lines are intentionally incorrect.
+    #
+    # 'transition' is only valid when nested beneath 'event'
+    transition :to => :happy, :from => :sad
+    transition :to => :sad,   :from => :happy
+  end
+
+end
+
+InvalidTransitions1.auto_migrate!

data/spec/examples/invalid_transitions_2.rb

@@ -0,0 +1,22 @@
+# An invalid example.
+class InvalidTransitions2
+  include DataMapper::Resource
+
+  property :id, Serial
+
+  is :state_machine do
+    state :happy
+    state :sad
+
+    event :toggle
+  end
+
+  # The next lines are intentionally incorrect.
+  #
+  # 'transition' is only valid when nested beneath 'event'
+  transition :to => :happy, :from => :sad
+  transition :to => :sad,   :from => :happy
+
+end
+
+InvalidTransitions2.auto_migrate!

data/spec/examples/light_switch.rb

@@ -0,0 +1,25 @@
+class LightSwitch
+  include DataMapper::Resource
+  property :id,   Serial
+  property :type, Discriminator
+
+  is :state_machine, :initial => :off do
+    state :off
+    state :on, :enter => :on_hook
+
+    event :switch do
+      transition :from => :on, :to => :off
+      transition :from => :off, :to => :on
+    end
+  end
+
+  def on_hook
+    puts "Light turned on!"
+  end
+end
+
+class Dimmer < LightSwitch
+  def on_hook
+    puts "Lights! Camera! Action! your're on!"
+  end
+end

data/spec/examples/slot_machine.rb

@@ -0,0 +1,48 @@
+# A valid example
+class SlotMachine
+  include DataMapper::Resource
+
+  property :id, Serial
+  property :power_on, Boolean, :default => false
+
+  is :state_machine, :initial => :off, :column => :mode do
+    state :off,
+      :enter => :power_down,
+      :exit  => :power_up
+    state :idle
+    state :spinning
+    state :report_loss
+    state :report_win
+    state :pay_out
+
+    event :pull_crank do
+      transition :from => :idle,  :to => :spinning
+    end
+
+    event :turn_off do
+      transition :from => :idle,  :to => :off
+    end
+
+    event :turn_on do
+      transition :from => :off,   :to => :idle
+    end
+  end
+
+  def initialize(attributes = {})
+    @log = []
+    super
+  end
+
+  def power_up
+    self.power_on = true
+    @log << [:power_up, Time.now]
+  end
+
+  def power_down
+    self.power_on = false
+    @log << [:power_down, Time.now]
+  end
+
+end
+
+SlotMachine.auto_migrate!

data/spec/examples/traffic_light.rb

@@ -0,0 +1,48 @@
+# A valid example
+class TrafficLight
+  include DataMapper::Resource
+
+  property :id, Serial # see note 1
+
+  is :state_machine, :initial => :green, :column => :color do
+    state :green,  :enter => Proc.new { |o| o.log << "G" }
+    state :yellow, :enter => Proc.new { |o| o.log << "Y" }
+    state :red,    :enter => Proc.new { |o| o.log << "R" }
+
+    event :forward do
+      transition :from => :green,  :to => :yellow
+      transition :from => :yellow, :to => :red
+      transition :from => :red,    :to => :green
+    end
+
+    event :backward do
+      transition :from => :green,  :to => :red
+      transition :from => :yellow, :to => :green
+      transition :from => :red,    :to => :yellow
+    end
+  end
+
+  before :transition!, :before_hook
+  after  :transition!, :after_hook
+
+  def before_hook
+    before_hook_log << attribute_get(:color)
+  end
+
+  def after_hook
+    after_hook_log << attribute_get(:color)
+  end
+
+  def log; @log ||= [] end
+  def before_hook_log; @bh_log ||= [] end
+  def after_hook_log; @ah_log ||= [] end
+
+  attr_reader :init
+  def initialize(*args)
+    (@init ||= []) << :init
+    super
+  end
+
+end
+
+TrafficLight.auto_migrate!

data/spec/integration/inheritance_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+require 'examples/light_switch'
+
+describe 'Inherited state machine' do
+
+  it 'should not explode' do
+    dimmer = Dimmer.new
+    lambda { dimmer.switch! }.should_not raise_error(NoMethodError)
+  end
+
+end

data/spec/integration/invalid_events_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe "InvalidEvents" do
+
+  it "should get InvalidContext when requiring" do
+    lambda {
+      require 'examples/invalid_events'
+    }.should raise_error(DataMapper::Is::StateMachine::InvalidContext)
+  end
+
+end

data/spec/integration/invalid_states_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe "InvalidStates" do
+
+  it "should get InvalidContext when requiring" do
+    lambda {
+      require 'examples/invalid_states'
+    }.should raise_error(DataMapper::Is::StateMachine::InvalidContext)
+  end
+
+end

data/spec/integration/invalid_transitions_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe "InvalidTransitions1" do
+
+  it "should get InvalidContext when requiring" do
+    lambda {
+      require 'examples/invalid_transitions_1'
+    }.should raise_error(DataMapper::Is::StateMachine::InvalidContext)
+  end
+
+end
+
+describe "InvalidTransitions2" do
+
+  it "should get InvalidContext when requiring" do
+    lambda {
+      require 'examples/invalid_transitions_2'
+    }.should raise_error(DataMapper::Is::StateMachine::InvalidContext)
+  end
+
+end