simple_state_machine 0.5.1 → 0.5.2

data/README.rdoc

@@ -5,28 +5,55 @@ 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
+It supports exception rescuing, google chart visualization and mountable state_machines.
 
-Write a method, arguments are allowed:
+== Basic example
+
+    class LampSwitch
+
+      extend SimpleStateMachine
+
+      def initialize
+        self.state = 'off'
+      end
+
+      def push_switch
+        puts "pushed switch"
+      end
+      event :push_switch, :off => :on,
+                          :on  => :off
+
+    end
+
+    lamp = LampSwitch.new
+    lamp.state          # => 'off'
+    lamp.off?           # => true
+    lamp.push_switch    # => 'pushed switch'
+    lamp.state          # => 'on'
+    lamp.on?            # => true
+    lamp.push_switch    # => 'pushed switch'
+    lamp.off?           # => true
+
+
+== Basic usage
+
+Define your event as 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.
+when the method is called. If we want the state to change from :pending to :active we write:
 
   event :activate_account, :pending => :active
 
+That's it!
+You can now call activate_account and the state will automatically change.
+If the state change is not allowed, a SimpleStateMachine::IllegalStateTransitionError is raised.
 
-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
+=== Using ActiveRecord / ActiveModel validations
 When using ActiveRecord / ActiveModel you can add an error to the errors object.
 This will prevent the state from being changed.
   
@@ -36,7 +63,9 @@ This will prevent the state from being changed.
     end
   end
 
-=== Example usage with exceptions
+  activate_account!("INVALID_CODE") # => ActiveRecord::RecordInvalid, "Validation failed: Activation code is invalid"
+
+=== Catching exceptions
 You can rescue exceptions and specify the failure state
 
   def download_data
@@ -45,40 +74,13 @@ You can rescue exceptions and specify the failure state
   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
+  download_data! # catches Service::ConnectionError
+  state          # => "download_failed"
 
-      # define another event
-      # note that implementation of :push_switch_2 is optional
-      event :push_switch_2, :off => :on,
-                            :on  => :off
+=== Catching all from states
+If an event should transition from all states you can use :all
 
-    end
-
-    lamp = LampWithHotelSwitch.new
-    lamp.state          # => 'off'
-    lamp.push_switch_1
-    lamp.state          # => 'on'
-    lamp.push_siwtch_2
-    lamp.state          # => 'off'
+  event :suspend, :all => :suspended
 
 == ActiveRecord Example
 
@@ -92,17 +94,17 @@ To add a state machine with ActiveRecord persistence:
       extend SimpleStateMachine::ActiveRecord
 
       def after_initialize
-        self.ssm_state ||= 'new'
+        self.ssm_state ||= 'pending'
         # 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)
+        #   write_attribute(:ssm_state, "pending") 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
+      event :invite, :pending => :invited
       
       def confirm_invitation activation_code
         if self.activation_code != activation_code
@@ -110,26 +112,49 @@ To add a state machine with ActiveRecord persistence:
         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 event methods
 - invite!
 - confirm_invitation!
-- suspend!
+
 And the following methods to query the state:
+- pending?
 - invited?
 - active?
-- suspended?
 
 If you want to be more verbose you can also use:
 - invite_and_save  (behave like ActiveRecord save)
 - invite_and_save! (is equal to invite! and behaves like save!)
 
+== Mountable Example
+
+You can define your state machine in a seperate class:
+
+    class MyStateMachine < SimpleStateMachine::StateMachineDefinition
+      def initialize(subject)
+        self.lazy_decorator = lambda { SimpleStateMachine::Decorator.new(subject) }
+        add_transition(:invite, :new, :invited)
+        add_transition(:confirm_invitation, :invited, :active)
+      end
+    end
+
+    class User < ActiveRecord::Base
+       
+      extend SimpleStateMachine::Mountable
+      self.state_machine_definition = MyStateMachine.new self
+
+      def after_initialize
+        self.ssm_state ||= 'new'
+      end
+      
+    end
+
+
+== Generating google chart visualizations
+
+If your using rails you get rake tasks for generating a graphiz google chart of the state machine.
 
-This code was just released, we do not claim it to be stable.
 
 == Note on Patches/Pull Requests
  

data/lib/simple_state_machine/active_record.rb

@@ -17,7 +17,7 @@ module SimpleStateMachine::ActiveRecord
       unless @subject.method_defined?(event_name_and_save)
         @subject.send(:define_method, event_name_and_save) do |*args|
           old_state = self.send(self.class.state_machine_definition.state_method)
-          send event_name, *args
+          send "with_managed_state_#{event_name}", *args
           if !self.errors.entries.empty?
             self.send("#{self.class.state_machine_definition.state_method}=", old_state)
             return false
@@ -35,7 +35,7 @@ module SimpleStateMachine::ActiveRecord
       unless @subject.method_defined?(event_name_and_save_bang)
         @subject.send(:define_method, event_name_and_save_bang) do |*args|
           old_state = self.send(self.class.state_machine_definition.state_method)
-          send event_name, *args
+          send "with_managed_state_#{event_name}", *args
           if !self.errors.entries.empty?
             self.send("#{self.class.state_machine_definition.state_method}=", old_state)
             raise ActiveRecord::RecordInvalid.new(self)
@@ -47,18 +47,26 @@ module SimpleStateMachine::ActiveRecord
             raise #re raise
           end
         end
-        @subject.send :alias_method, "#{transition.event_name}!", event_name_and_save_bang 
+        @subject.send :alias_method, "#{transition.event_name}!", event_name_and_save_bang
       end
     end
-  
-    private
 
-    def define_state_setter_method; end
+    protected
 
-    def define_state_getter_method; end
+      def alias_event_methods event_name
+        @subject.send(:define_method, "cannot_call_#{event_name}") do |*args|
+          raise "You cannot call #{event_name}. Use #{event_name}! instead"
+        end
+        @subject.send :alias_method, "without_managed_state_#{event_name}", event_name
+        @subject.send :alias_method, event_name, "cannot_call_#{event_name}"
+      end
+
+      def define_state_setter_method; end
+
+      def define_state_getter_method; end
 
   end
-  
+
   def state_machine_definition
     unless @state_machine_definition
       @state_machine_definition = SimpleStateMachine::StateMachineDefinition.new

data/lib/simple_state_machine/simple_state_machine.rb

@@ -1,7 +1,7 @@
 module SimpleStateMachine
 
   require 'cgi'
-  
+
   class IllegalStateTransitionError < ::RuntimeError
   end
 
@@ -26,10 +26,10 @@ module SimpleStateMachine
   include Mountable
 
   ##
-  # Adds state machine methods to the extended class 
+  # Adds state machine methods to the extended class
   module Extendable
 
-    # mark the method as an event and specify how the state should transition 
+    # mark the method as an event and specify how the state should transition
     def event event_name, state_transitions
       state_transitions.each do |froms, to|
         [froms].flatten.each do |from|
@@ -53,7 +53,7 @@ module SimpleStateMachine
     end
   end
   include Inheritable
-  
+
   ##
   # Defines state machine transitions
   class StateMachineDefinition
@@ -67,18 +67,18 @@ module SimpleStateMachine
     def transitions
       @transitions ||= []
     end
-    
+
     def add_transition event_name, from, to
       transition = Transition.new(event_name, from, to)
       transitions << transition
       decorator.decorate(transition)
     end
-     
+
     def state_method
       @state_method ||= :state
-    end      
+    end
 
-    # Human readable format: old_state.event! => new_state 
+    # Human readable format: old_state.event! => new_state
     def to_s
       transitions.map(&:to_s).join("\n")
     end
@@ -94,7 +94,7 @@ module SimpleStateMachine
       "http://chart.googleapis.com/chart?cht=gv&chl=digraph{#{::CGI.escape to_graphiz_dot}}"
     end
   end
-  
+
   ##
   # Defines the state machine used by the instance
   class StateMachine
@@ -145,9 +145,9 @@ module SimpleStateMachine
         illegal_event_callback event_name
       end
     end
-  
+
     private
-      
+
       def state_machine_definition
         @subject.class.state_machine_definition
       end
@@ -164,12 +164,12 @@ module SimpleStateMachine
       def illegal_event_callback event_name
         raise IllegalStateTransitionError.new("You cannot '#{event_name}' when state is '#{@subject.send(state_method)}'")
       end
-  
+
   end
 
   ##
   # Defines transitions for events
-  class Transition 
+  class Transition
     attr_reader :event_name, :from, :to
     def initialize(event_name, from, to)
       @event_name = event_name.to_s
@@ -194,7 +194,7 @@ module SimpleStateMachine
     def to_graphiz_dot
       %("#{from}"->"#{to}"[label=#{event_name}])
     end
-      
+
 
     private
 
@@ -256,8 +256,7 @@ module SimpleStateMachine
               send("without_managed_state_#{event_name}", *args)
             end
           end
-          @subject.send :alias_method, "without_managed_state_#{event_name}", event_name
-          @subject.send :alias_method, event_name, "with_managed_state_#{event_name}"
+          alias_event_methods event_name
         end
       end
 
@@ -274,7 +273,7 @@ module SimpleStateMachine
           @subject.send(:attr_reader, state_method)
         end
       end
-      
+
       def any_method_defined?(method)
         @subject.method_defined?(method) ||
         @subject.protected_method_defined?(method) ||
@@ -283,6 +282,11 @@ module SimpleStateMachine
 
     protected
 
+      def alias_event_methods event_name
+        @subject.send :alias_method, "without_managed_state_#{event_name}", event_name
+        @subject.send :alias_method, event_name, "with_managed_state_#{event_name}"
+      end
+
       def state_method
         @subject.state_machine_definition.state_method
       end

data/lib/simple_state_machine/version.rb

@@ -1,3 +1,3 @@
 module SimpleStateMachine
-  VERSION = "0.5.1"
+  VERSION = "0.5.2"
 end

data/spec/active_record_spec.rb

@@ -12,7 +12,7 @@ ActiveRecord::Base.establish_connection(:adapter  => "sqlite3",
                                         :database => ":memory:")
 
 def setup_db
-  ActiveRecord::Schema.define(:version => 1) do    
+  ActiveRecord::Schema.define(:version => 1) do
     create_table :users do |t|
       t.column :id,               :integer
       t.column :name,             :string
@@ -38,7 +38,7 @@ class Ticket < ActiveRecord::Base
   extend SimpleStateMachine::ActiveRecord
 
   state_machine_definition.state_method = :ssm_state
- 
+
   def after_initialize
     self.ssm_state ||= 'open'
   end
@@ -47,21 +47,21 @@ class Ticket < ActiveRecord::Base
 end
 
 describe ActiveRecord do
-  
+
   before do
     setup_db
   end
-  
+
   after do
     teardown_db
   end
-  
+
   it "has a default state" do
     User.new.should be_new
   end
-  
+
   # TODO needs nesting/grouping, seems to have some duplication
- 
+
   describe "event_and_save" do
     it "persists transitions" do
       user = User.create!(:name => 'name')
@@ -88,9 +88,9 @@ describe ActiveRecord do
 
     it "raises an error if an invalid state_transition is called" do
       user = User.create!(:name => 'name')
-      expect { 
-        user.confirm_invitation_and_save 'abc' 
-      }.to raise_error(SimpleStateMachine::IllegalStateTransitionError, 
+      expect {
+        user.confirm_invitation_and_save 'abc'
+      }.to raise_error(SimpleStateMachine::IllegalStateTransitionError,
                        "You cannot 'confirm_invitation' when state is 'new'")
     end
 
@@ -133,9 +133,9 @@ describe ActiveRecord do
 
     it "raises an error if an invalid state_transition is called" do
       user = User.create!(:name => 'name')
-      expect { 
-        user.confirm_invitation_and_save! 'abc' 
-      }.to raise_error(SimpleStateMachine::IllegalStateTransitionError, 
+      expect {
+        user.confirm_invitation_and_save! 'abc'
+      }.to raise_error(SimpleStateMachine::IllegalStateTransitionError,
                        "You cannot 'confirm_invitation' when state is 'new'")
     end
 
@@ -143,9 +143,9 @@ describe ActiveRecord do
       user = User.new
       user.should be_new
       user.should_not be_valid
-      expect { 
-        user.invite_and_save! 
-      }.to raise_error(ActiveRecord::RecordInvalid, 
+      expect {
+        user.invite_and_save!
+      }.to raise_error(ActiveRecord::RecordInvalid,
                        "Validation failed: Name can't be blank")
       user.should be_new
     end
@@ -154,9 +154,9 @@ describe ActiveRecord do
       user = User.create!(:name => 'name')
       user.invite_and_save!
       user.should be_invited
-      expect { 
-        user.confirm_invitation_and_save!('x') 
-      }.to raise_error(ActiveRecord::RecordInvalid, 
+      expect {
+        user.confirm_invitation_and_save!('x')
+      }.to raise_error(ActiveRecord::RecordInvalid,
                        "Validation failed: Activation code is invalid")
       user.should be_invited
     end
@@ -165,19 +165,9 @@ describe ActiveRecord do
 
   describe "event" do
 
-    it "does not persist transitions" do
+    it "raises an error" do
       user = User.create!(:name => 'name')
-      user.invite.should == true
-      User.find(user.id).should_not be_invited
-      User.find(user.id).activation_code.should be_nil
-    end
-
-    it "returns false and keeps state if record is invalid" do    
-      user = User.new
-      user.should be_new
-      user.should_not be_valid
-      user.invite.should == false
-      user.should be_new
+      expect { user.invite }.to raise_error(RuntimeError, "You cannot call invite. Use invite! instead")
     end
 
   end
@@ -202,11 +192,11 @@ describe ActiveRecord do
   end
 
   describe 'custom state method' do
-    
+
     it "persists transitions" do
       ticket = Ticket.create!
       ticket.should be_open
-      ticket.close.should == true
+      ticket.close!.should == true
       ticket.should be_closed
     end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: simple_state_machine
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 15
   prerelease: 
   segments: 
   - 0
   - 5
-  - 1
-  version: 0.5.1
+  - 2
+  version: 0.5.2
 platform: ruby
 authors: 
 - Marek de Heus