dm-is-state_machine 0.9.6 → 0.9.7

data/History.txt

@@ -1 +1,10 @@
+=== 2008-10-13
 
+* Added functionality and docs
+
+  - Added support to pass a symbol to a transition, which will call the
+    corresponding method.  This means you don't have to put a whole
+    Proc inside the state machine definition if you don't want to.
+  - Added support for the :exit transition.
+  - Created a new example called SlotMachine in /spec/integration
+  - Updated README and TODO.

data/Manifest.txt

@@ -1,6 +1,7 @@
 History.txt
 LICENSE
 Manifest.txt
+README.markdown
 README.txt
 Rakefile
 TODO
@@ -16,10 +17,12 @@ spec/examples/invalid_events.rb
 spec/examples/invalid_states.rb
 spec/examples/invalid_transitions_1.rb
 spec/examples/invalid_transitions_2.rb
+spec/examples/slot_machine.rb
 spec/examples/traffic_light.rb
 spec/integration/invalid_events_spec.rb
 spec/integration/invalid_states_spec.rb
 spec/integration/invalid_transitions_spec.rb
+spec/integration/slot_machine_spec.rb
 spec/integration/traffic_light_spec.rb
 spec/spec.opts
 spec/spec_helper.rb

data/README.markdown

@@ -0,0 +1,102 @@
+# dm-is-state_machine #
+
+DataMapper plugin that adds state machine functionality to your models.
+
+## Why is this plugin useful? ##
+
+Your DataMapper resource might benefit from a state machine if it:
+
+* has different "modes" of operation
+* has discrete behaviors
+* especially if the behaviors are mutually exclusive
+
+And you want a clean, high-level way of describing these modes / behaviors
+and how the resource moves between them.  This plugin allows you to
+declaratively describe the states and transitions involved.
+
+## Installation ##
+
+1. Download dm-more.
+2. Install dm-is-state_machine using the supplied rake files.
+
+## Setting up with Merb ##
+
+Add this line to your init.rb:
+
+    dependency "dm-is-state_machine"
+
+## Example DataMapper resource (i.e. model) ##
+
+    # /app/models/traffic_light.rb
+    class TrafficLight
+      include DataMapper::Resource
+
+      property :id, Serial
+
+      is :state_machine, :initial => :green, :column => :color do
+        state :green
+        state :yellow
+        state :red,    :enter => :red_hook
+        state :broken
+
+        event :forward do
+          transition :from => :green,  :to => :yellow
+          transition :from => :yellow, :to => :red
+          transition :from => :red,    :to => :green
+        end
+      end
+      
+      def red_hook
+        # Do something
+      end
+    end
+
+## What this gives you ##
+
+### Explained in words ###
+
+The above DSL (domain specific language) does these things "behind the scenes":
+
+1. Defines a DataMapper property called 'color'.
+
+2. Makes the current state available by using 'traffic_light.color'.
+
+3. Defines the 'forward!' transition method.  This method triggers the
+   appropriate transition based on the current state and comparing it against
+   the various :from states.  It will raise an error if you attempt to call
+   it with an invalid state (such as :broken, see above).  After the method
+   runs successfully, the state machine will be left in the :to state.  
+    
+### Explained with some code examples ###
+
+    # Somewhere in your controller, perhaps
+    light = TrafficLight.new
+    
+    # Move to the next state
+    light.forward!
+    
+    # Do something based on the current state
+    case light.color
+    when "green"
+      # do something green-related
+    when "yellow"
+      # do something yellow-related
+    when "red"
+      # do something red-related
+    end
+    
+## Specific examples ##
+
+We would also like to hear how *you* are using state machines in your code.
+
+## See also ##
+
+Here are some other projects you might want to look at.  Most of them
+are probably intended for ActiveRecord.  They take different approaches,
+which is pretty interesting.  If you find something you like in these other
+projects, let us know.  Maybe we can incorporate some of your favorite parts.
+That said, I do not want to create a Frankenstein. :)
+
+* http://github.com/pluginaweek/state_machine/tree/master
+* http://github.com/davidlee/stateful/tree/master
+* http://github.com/sbfaulkner/has_states/tree/master

data/README.txt

@@ -1,12 +1,5 @@
-= dm-state-machine
+= dm-is-state_machine
 
-DataMapper plugin that adds state machine functionality.
+== DESCRIPTION:
 
-== Installation
-
-Download dm-more and install dm-is-state_machine. Require it in your app.
-
-== Getting started
-
-Please refer to the integration specs in spec/integration, which refer to
-spec/examples.
+See README.markdown

data/Rakefile

@@ -12,7 +12,7 @@ GEM_NAME = "dm-is-state_machine"
 GEM_VERSION = DataMapper::Is::StateMachine::VERSION
 GEM_DEPENDENCIES = [["dm-core", GEM_VERSION]]
 GEM_CLEAN = ["log", "pkg"]
-GEM_EXTRAS = { :has_rdoc => true, :extra_rdoc_files => %w[ README.txt LICENSE TODO ] }
+GEM_EXTRAS = { :has_rdoc => true, :extra_rdoc_files => %w[ README.txt README.markdown LICENSE TODO ] }
 
 PROJECT_NAME = "datamapper"
 PROJECT_URL  = "http://github.com/sam/dm-more/tree/master/dm-is-state_machine"

data/TODO

@@ -1,11 +1,52 @@
 TODO
 ====
 
-* Should skipping to a new state automatically trigger :enter Proc?
-* Add loopback checking (i.e. when transitioning from a state back to itself)
-* Add support for callbacks
-* Consider using DataMapper's Enum type.
+* Take a look at using DataMapper's Enum type.
+  - Does the Enum type support for all databases?  (SQLite?)
+
+
+* I am not real happy with spec/unit/dsl:
+  - The specs are brittle.
+  - The specs don't actually test much.
+
+  However, the integration specs are pretty thorough.  Maybe each
+  serves their own purpose.
+
+
+API QUESTIONS
+=============
+
+* Some people are asking for convenience methods.
+
+  For example, instead of:
+    light = TrafficLight.new
+    light.color == "yellow"
+
+  We could possibly offer:
+    light.yellow?
+
+  Advantages:
+    - More compact syntax.
+
+  Disadvantages:
+    - Namespace pollution
+    - Possible namespace collision if you have more than one state machine
+      in your model.
+
+
+* Should skipping to a new state automatically trigger the :enter event?
+
+
+* Should we add loopback checking?
+
+  In other words, if there is a transition defined from one state back to
+  the same state, should the :enter and :exit events fire?
+
+
+* Should we add support for DataMapper callbacks? (e.g. after saving)
+
+
+SOMEDAY / MAYBE
+===============
+
 * Consider trying out a nested state machine.
-* Not real happy with spec/unit/dsl:
-  - specs are brittle
-  - specs don't actually test much

data/lib/dm-is-state_machine.rb

@@ -3,7 +3,7 @@ require 'rubygems'
 require 'pathname'
 
 # Add all external dependencies for the plugin here
-gem 'dm-core', '=0.9.6'
+gem 'dm-core', '~>0.9.7'
 require 'dm-core'
 
 # Require plugin-files

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

@@ -3,12 +3,29 @@ module DataMapper
     module StateMachine
       module Data
 
-        # Represents one state machine
+        # This Machine class represents one state machine.
+        #
+        # A model (i.e. a DataMapper resource) can have more than one Machine.
         class Machine
 
-          attr_reader :column, :initial
+          # The property of the DM resource that will hold this Machine's
+          # state.
+          #
+          # TODO: change :column to :property
+          attr_accessor :column
+
+          # The initial value of this Machine's state
+          attr_accessor :initial
+
+          # The current value of this Machine's state
+          #
+          # This is the "primary control" of this Machine's state.  All
+          # other methods key off the value of @current_state_name.
           attr_accessor :current_state_name
-          attr_accessor :events, :states
+
+          attr_accessor :events
+
+          attr_accessor :states
 
           def initialize(column, initial)
             @column, @initial   = column, initial
@@ -27,14 +44,18 @@ module DataMapper
                t[:from].to_s == @current_state_name.to_s
             end
             unless transition
-              raise InvalidEvent, "Event (#{event_name.inspect}) does " +
-              "not exist for current state (#{@current_state_name.inspect})"
+              raise InvalidEvent, "Event (#{event_name.inspect}) does not" +
+              "exist for current state (#{@current_state_name.inspect})"
             end
+
+            # == Run :exit hook (if present) ==
+            resource.run_hook_if_present current_state.options[:exit]
+
+            # == Change the current_state ==
             @current_state_name = transition[:to]
 
-            # ===== Call :enter Proc if present =====
-            return unless enter_proc = current_state.options[:enter]
-            enter_proc.call(resource)
+            # == Run :enter hook (if present) ==
+            resource.run_hook_if_present current_state.options[:enter]
           end
 
           # Return the current state

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

@@ -49,6 +49,17 @@ module DataMapper
             send(:"#{column}=", machine.current_state_name)
           end
 
+          # Possible alternative to the above:
+          # (class_eval is typically faster than define_method)
+          #
+          # self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          #   def #{name}!
+          #     machine.current_state_name = self.send(:"#{column}")
+          #     machine.fire_event(name, self)
+          #     self.send(:"#{column}="), machine.current_state_name
+          #   end
+          # RUBY
+
           yield if block_given?
 
           # ===== Teardown context =====

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

@@ -39,13 +39,14 @@ module DataMapper
         @is_state_machine = { :machine => machine }
 
         # ===== Define callbacks =====
-        before :save do
-          if self.new_record?
-            # ...
-          else
-            # ...
-          end
-        end
+        # TODO: define callbacks
+        # before :save do
+        #   if self.new_record?
+        #     # ...
+        #   else
+        #     # ...
+        #   end
+        # end
 
         before :destroy do
           # Do we need to do anything here?
@@ -63,12 +64,12 @@ module DataMapper
       protected
 
       def push_state_machine_context(label)
-        ((@is_state_machine ||= {})[:context] ||= []) << label
+        @is_state_machine ||= {}
+        @is_state_machine[:context] ||= []
+        @is_state_machine[:context] << label
 
-        # Less DRY, though more readable to some
-        # @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
@@ -84,13 +85,22 @@ module DataMapper
 
         def initialize(*args)
           super
-          # ===== Call :enter Proc if present =====
+          # ===== Run :enter hook if present =====
           return unless is_sm = self.class.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)
-          return unless enter_proc = initial_state.options[:enter]
-          enter_proc.call(self)
+          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
+            self.send(hook)
+          end
         end
 
       end # InstanceMethods

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

@@ -1,7 +1,7 @@
 module DataMapper
   module Is
     module StateMachine
-      VERSION = "0.9.6"
+      VERSION = "0.9.7"
     end
   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
+    @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

@@ -1,4 +1,4 @@
-# A valid example of a resource with a state machine.
+# A valid example
 class TrafficLight
   include DataMapper::Resource
 

data/spec/integration/slot_machine_spec.rb

@@ -0,0 +1,91 @@
+require 'pathname'
+require Pathname(__FILE__).dirname.expand_path.parent + 'spec_helper'
+require Pathname(__FILE__).dirname.expand_path.parent + 'examples/slot_machine'
+
+describe SlotMachine do
+
+  before(:each) do
+    @sm = SlotMachine.new
+  end
+
+  it "should have an 'id' column" do
+    @sm.attributes.should have_key(:id)
+  end
+
+  it "should have a 'mode' column" do
+    @sm.attributes.should have_key(:mode)
+  end
+
+  it "should have a 'power_on' column" do
+    @sm.attributes.should have_key(:power_on)
+  end
+
+  it "should not have a 'state' column" do
+    @sm.attributes.should_not have_key(:state)
+  end
+
+  it "should start in the off state" do
+    @sm.mode.should == "off"
+  end
+
+  it "should start with power_on == false" do
+    @sm.power_on.should == false
+  end
+
+  describe "in :off mode" do
+
+    before(:each) do
+      @sm.mode = :off
+      @sm.power_on = false
+    end
+
+    it "should allow the mode to be set" do
+      @sm.mode = :idle
+      @sm.save
+      @sm.mode.should == "idle"
+    end
+
+    it "turn_on! should work from off mode" do
+      @sm.turn_on!
+      @sm.mode.should == "idle"
+      @sm.power_on.should == true
+    end
+
+    it "turn_on! should not work twice in a row" do
+      @sm.turn_on!
+      lambda {
+        @sm.turn_on!
+      }.should raise_error(DataMapper::Is::StateMachine::InvalidEvent)
+    end
+
+  end
+
+  describe "in :idle mode" do
+
+    before(:each) do
+      @sm.mode = :idle
+      @sm.power_on = true
+    end
+
+    it "turn_on! should raise error" do
+      lambda {
+        @sm.turn_on!
+      }.should raise_error(DataMapper::Is::StateMachine::InvalidEvent)
+    end
+
+    it "turn_off! should work" do
+      @sm.turn_off!
+      @sm.mode.should == "off"
+      @sm.power_on.should == false
+    end
+
+    it "turn_off! should not work twice in a row" do
+      @sm.turn_off!
+      lambda {
+        @sm.turn_off!
+      }.should raise_error(DataMapper::Is::StateMachine::InvalidEvent)
+    end
+
+  end
+
+end

data/spec/integration/traffic_light_spec.rb

@@ -9,15 +9,15 @@ describe TrafficLight do
   end
 
   it "should have an 'id' column" do
-    @t.attributes.should include(:id)
+    @t.attributes.should have_key(:id)
   end
 
   it "should have a 'color' column" do
-    @t.attributes.should include(:color)
+    @t.attributes.should have_key(:color)
   end
 
   it "should not have a 'state' column" do
-    @t.attributes.should_not include(:state)
+    @t.attributes.should_not have_key(:state)
   end
 
   it "should start off in the green state" do

data/spec/spec_helper.rb

@@ -10,7 +10,7 @@ def load_driver(name, default_uri)
   lib = "do_#{name}"
 
   begin
-    gem lib, '>=0.9.5'
+    gem lib, '~>0.9.7'
     require lib
     DataMapper.setup(name, ENV["#{name.to_s.upcase}_SPEC_URI"] || default_uri)
     DataMapper::Repository.adapters[:default] = DataMapper::Repository.adapters[name]

data/spec/unit/data/machine_spec.rb

@@ -87,11 +87,17 @@ describe DataMapper::Is::StateMachine::Data::Machine do
       @machine.find_event(:turn_on).should == @turn_on
     end
 
-    it "#fire_event should work" do
-      @machine.fire_event(:turn_on, nil)
+    it "#fire_event should change state" do
+      resource = mock("resource")
+      resource.should_receive(:run_hook_if_present).exactly(2).times.with(nil)
+      @machine.fire_event(:turn_on, resource)
       @machine.current_state.should == @on_state
       @machine.current_state_name.should == :on
     end
+
   end
 
+  # TODO: spec fire_event where :run_hook_if_present fires two times,
+  # but with :enter the first and :exit the second.
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dm-is-state_machine
 version: !ruby/object:Gem::Version 
-  version: 0.9.6
+  version: 0.9.7
 platform: ruby
 authors: 
 - David James
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-12 00:00:00 -06:00
+date: 2008-11-18 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        version: 0.9.6
+        version: 0.9.7
     version: 
 - !ruby/object:Gem::Dependency 
   name: hoe
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.7.0
+        version: 1.8.2
     version: 
 description: DataMapper plugin for creating state machines
 email: 
@@ -41,12 +41,14 @@ extensions: []
 
 extra_rdoc_files: 
 - README.txt
+- README.markdown
 - LICENSE
 - TODO
 files: 
 - History.txt
 - LICENSE
 - Manifest.txt
+- README.markdown
 - README.txt
 - Rakefile
 - TODO
@@ -62,10 +64,12 @@ files:
 - spec/examples/invalid_states.rb
 - spec/examples/invalid_transitions_1.rb
 - spec/examples/invalid_transitions_2.rb
+- spec/examples/slot_machine.rb
 - spec/examples/traffic_light.rb
 - spec/integration/invalid_events_spec.rb
 - spec/integration/invalid_states_spec.rb
 - spec/integration/invalid_transitions_spec.rb
+- spec/integration/slot_machine_spec.rb
 - spec/integration/traffic_light_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -98,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: datamapper
-rubygems_version: 1.2.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
 summary: DataMapper plugin for creating state machines