simple_state_machine 0.2.2 → 0.3.0

data/README.rdoc

@@ -1,14 +1,11 @@
 = SimpleStateMachine
 
-A Ruby Statemachine that focuses on events instead of states.
+A simple DSL to decorate existing methods with state transition guards.
 
-A state machine should help you:
-- Encapsulate state,
-- Guard state transitions,
-- Make it trivial to add state transitions to any method.
+SimpleStateMachine helps you to encapsulate state and guard state transitions.
+Adding state transitions to a method is trivial.
 
-Instead of using a DSL to define events, we use a different approach.
-We have a very simple DSL to decorate existing methods with logic that guards 
+Instead of using a DSL to define events, SimpleStateMachine decorates existing methods with logic that guards 
 state transitions.
 
 ==== example
@@ -21,40 +18,80 @@ state transitions.
   event :activate_account, :pending => :active
 
 
-This has a couple of advantages:
-- Encapsulate state transitions (no need for :guards),
-- Arguments can be passed to 'events',
-- 'events' can return a value, remember, it's just a method,
-- Validation errors can be set on the model if you are using ActiveRecord / ActiveModel,
-
-To use the code, you need to do 3 things:
-- extend SimpleStateMachine,
-- set the initial state,
-- decorate a method with the event DSL
-
-==== Example usage
-
-  class LampWithHotelSwitch
-
-    extend SimpleStateMachine
-
-    def initialize
-      self.state = :off
+Decorating methods has a couple of advantages:
+- No need for defining extra methods for adding logic
+- Arguments can be passed to events
+- State transitions are encapsulated. No need for :guards
+- Validation errors can be set on the model if you are using ActiveRecord / ActiveModel
+
+== Example
+
+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
+      
+      def push_switch_2
+        puts 'pushed switch 2 #{state}'
+      end
+      event :push_switch_2, :off => :on,
+                            :on  => :off
+      
     end
 
-    def push_switch_1
-      puts 'pushed switch 1 #{state}'
+== 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
+      
+      def after_initialize
+        self.state ||= 'new'
+        # if you get an ActiveRecord::MissingAttributeError
+        # you'll probably need to do (http://bit.ly/35q23b):
+        #   write_attribute(:state, "new") unless read_attribute(: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
+      
     end
-    event :push_switch_1, :off => :on,
-                          :on  => :off
 
-    def push_switch_2
-      puts 'pushed switch 2 #{state}'
-    end
-    event :push_switch_2, :off => :on,
-                          :on  => :off
+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}
 
-  end
 
 This code was just released, we do not claim it to be stable.
 

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.3.0

data/examples/user.rb

@@ -11,9 +11,9 @@ class User < ActiveRecord::Base
 
   def invite
     self.activation_code = Digest::SHA1.hexdigest("salt #{Time.now.to_f}")
-    send_activation_email(self.activation_code)
+    true
   end
-  event :invite, :new => :invited
+  event :invite, :new => :invited, :on_success => :send_activation_email
 
   def confirm_invitation activation_code
     if self.activation_code != activation_code
@@ -22,15 +22,7 @@ class User < ActiveRecord::Base
   end
   event :confirm_invitation, :invited => :active
 
-  #event :log_send_activation_code_failed, :new => :send_activation_code_failed
-  # 
-  # def reset_password(new_password)
-  #   self.password = new_password
-  # end
-  # # do not change state, but ensure that we are in proper state
-  # event :reset_password, :active => :active
-  
-  def send_activation_email(code)
+  def send_activation_email    
     true
   end
 

data/lib/simple_state_machine/active_record.rb

@@ -1,6 +1,6 @@
 module SimpleStateMachine::ActiveRecord
 
-  include SimpleStateMachine::EventMixin
+  include SimpleStateMachine::StateMachineMixin
   
   def state_machine_decorator subject
     Decorator.new subject
@@ -12,16 +12,16 @@ module SimpleStateMachine::ActiveRecord
       super transition
       unless @subject.method_defined?("#{transition.event_name}_and_save")
         @subject.send(:define_method, "#{transition.event_name}_and_save") do |*args|
-          old_state = state
+          old_state = self.send(self.class.state_machine_definition.state_method)
           send "#{transition.event_name}", *args
           if !self.errors.entries.empty?
-            self.state = old_state
+            self.send("#{self.class.state_machine_definition.state_method}=", old_state)
             return false
           else
             if save
               return true
             else
-              self.state = old_state
+              self.send("#{self.class.state_machine_definition.state_method}=", old_state)
               return false
             end
           end
@@ -29,19 +29,20 @@ module SimpleStateMachine::ActiveRecord
       end
       unless @subject.method_defined?("#{transition.event_name}_and_save!")
         @subject.send(:define_method, "#{transition.event_name}_and_save!") do |*args|
-          old_state = state
+          old_state = self.send(self.class.state_machine_definition.state_method)
           send "#{transition.event_name}", *args
           if !self.errors.entries.empty?
-            self.state = old_state
+            self.send("#{self.class.state_machine_definition.state_method}=", old_state)
             raise ActiveRecord::RecordInvalid.new(self)
           end
           begin
             save!
           rescue ActiveRecord::RecordInvalid
-            self.state = old_state
-            raise
+            self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+            raise #re raise
           end
         end
+        @subject.send :alias_method, "#{transition.event_name}!", "#{transition.event_name}_and_save!"
       end
     end
   

data/lib/simple_state_machine/simple_state_machine.rb

@@ -1,6 +1,7 @@
 module SimpleStateMachine
-  
-  module EventMixin
+  ##
+  # Adds state machine methods to extended class 
+  module StateMachineMixin
 
     def event event_name, state_transitions
       state_transitions.each do |from, to|
@@ -30,10 +31,14 @@ module SimpleStateMachine
     end
   end
 
-  include EventMixin
+  include StateMachineMixin
   
+  ##
+  # Defines state machine transitions
   class StateMachineDefinition
 
+    attr_writer :state_method
+
     def transitions
       @transitions ||= []
     end
@@ -43,9 +48,14 @@ module SimpleStateMachine
       transitions << transition
       transition
     end
-
+    
+    def state_method
+      @state_method ||= :state
+    end      
   end
   
+  ##
+  # The state machine used by the instance
   class StateMachine
 
     def initialize(subject)
@@ -53,7 +63,7 @@ module SimpleStateMachine
     end
   
     def next_state(event_name)
-      transition = transitions.select{|t| t.event_name.to_s == event_name.to_s && @subject.state.to_s == t.from.to_s}.first
+      transition = transitions.select{|t| t.event_name.to_s == event_name.to_s && @subject.send(state_method).to_s == t.from.to_s}.first
       transition ? transition.to : nil
     end
   
@@ -63,13 +73,13 @@ module SimpleStateMachine
         # TODO refactor out to AR module
         if defined?(::ActiveRecord) && @subject.is_a?(::ActiveRecord::Base)
           if @subject.errors.entries.empty?
-            @subject.state = to
+            @subject.send("#{state_method}=", to)
             return true
           else
             return false
           end
         else
-          @subject.state = to
+          @subject.send("#{state_method}=", to)
           return result
         end
       else
@@ -78,9 +88,17 @@ module SimpleStateMachine
     end
   
     private
-    
+      
+      def state_machine_definition
+        @subject.class.state_machine_definition
+      end
+
       def transitions
-        @subject.class.state_machine_definition.transitions
+        state_machine_definition.transitions
+      end
+
+      def state_method
+        state_machine_definition.state_method
       end
 
       def illegal_event_callback event_name
@@ -93,6 +111,8 @@ module SimpleStateMachine
   class Transition < Struct.new(:event_name, :from, :to)
   end
 
+  ##
+  # Decorates the extended class with methods to access the state machine
   class Decorator
 
     def initialize(subject)
@@ -120,7 +140,7 @@ module SimpleStateMachine
       def define_state_helper_method state
         unless @subject.method_defined?("#{state.to_s}?")
           @subject.send(:define_method, "#{state.to_s}?") do
-            self.state == state.to_s
+            self.send(self.class.state_machine_definition.state_method) == state.to_s
           end
         end
       end
@@ -145,21 +165,24 @@ module SimpleStateMachine
       end
 
       def define_state_setter_method
-        unless @subject.method_defined?('state=')
-          @subject.send(:define_method, 'state=') do |new_state|
-            @state = new_state.to_s
+        unless @subject.method_defined?("#{state_method}=")
+          @subject.send(:define_method, "#{state_method}=") do |new_state|
+            instance_variable_set(:"@#{self.class.state_machine_definition.state_method}", new_state)
           end
         end
       end
 
       def define_state_getter_method
-        unless @subject.method_defined?('state')
-          @subject.send(:define_method, 'state') do
-            @state
-          end
+        unless @subject.method_defined?(state_method)
+          @subject.send(:attr_reader, state_method)
         end
       end
 
+    protected
+
+      def state_method
+        @subject.state_machine_definition.state_method
+      end
   end
 
 end

data/simple_state_machine.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{simple_state_machine}
-  s.version = "0.2.2"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Marek de Heus", "Petrik de Heus"]
@@ -14,8 +14,7 @@ Gem::Specification.new do |s|
   s.email = ["FIX@example.com"]
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc",
-     "TODO"
+     "README.rdoc"
   ]
   s.files = [
     "LICENSE",

data/spec/active_record_spec.rb

@@ -18,6 +18,12 @@ def setup_db
       t.column :updated_at, :datetime
     end
   end
+  ActiveRecord::Schema.define(:version => 1) do    
+    create_table :tickets do |t|
+      t.column :id, :integer
+      t.column :ssm_state, :string
+    end
+  end
 end
 
 def teardown_db
@@ -26,7 +32,19 @@ def teardown_db
   end
 end
 
-describe User do
+class Ticket < ActiveRecord::Base
+  extend SimpleStateMachine::ActiveRecord
+
+  state_machine_definition.state_method = :ssm_state
+ 
+  def after_initialize
+    self.ssm_state ||= 'open'
+  end
+
+  event :close, :open => :closed
+end
+
+describe ActiveRecord do
   
   before do
     setup_db
@@ -42,7 +60,7 @@ describe User do
   
   # TODO needs nesting/grouping, seems to have some duplication
  
-  describe "and_save" do
+  describe "event_and_save" do
     it "persists transitions" do
       user = User.create!(:name => 'name')
       user.invite_and_save.should == true
@@ -82,7 +100,7 @@ describe User do
 
   end
 
-  describe "and_save!" do
+  describe "event_and_save!" do
 
     it "persists transitions" do
       user = User.create!(:name => 'name')
@@ -117,4 +135,41 @@ describe User do
 
   end
 
+  describe "event!" do
+
+    it "persists transitions" do
+      user = User.create!(:name => 'name')
+      user.invite!.should == true
+      User.find(user.id).should be_invited
+      User.find(user.id).activation_code.should_not be_nil
+    end
+
+    it "raises a RecordInvalid and keeps state if record is invalid" do
+      user = User.new
+      user.should be_new
+      user.should_not be_valid
+      l = lambda { user.invite! }
+      l.should raise_error(ActiveRecord::RecordInvalid, "Validation failed: Name can't be blank")
+      user.should be_new
+    end
+
+  end
+
+  describe 'custom state method' do
+    
+    it "persists transitions" do
+      ticket = Ticket.create!
+      ticket.should be_open
+      ticket.close.should == true
+      ticket.should be_closed
+    end
+
+    it "persists transitions with !" do
+      ticket = Ticket.create!
+      ticket.should be_open
+      ticket.close!
+      ticket.should be_closed
+    end
+
+  end
 end

metadata

@@ -5,9 +5,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 2
-  version: 0.2.2
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Marek de Heus
@@ -45,7 +45,6 @@ extensions: []
 extra_rdoc_files: 
 - LICENSE
 - README.rdoc
-- TODO
 files: 
 - LICENSE
 - README.rdoc
@@ -66,7 +65,6 @@ files:
 - spec/simple_state_machine_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
-- TODO
 has_rdoc: true
 homepage: http://github.com/p8/simple_state_machine
 licenses: []

data/TODO

@@ -1,4 +0,0 @@
-- allow other state methods
-- alias ..._and_save with ...!
-- Document after_initialize bug
-