simple_state_machine 0.3.2 → 0.3.3

data/README.rdoc

@@ -2,27 +2,42 @@
 
 A simple DSL to decorate existing methods with state transition guards.
 
-SimpleStateMachine helps you to encapsulate state and guard state transitions.
+Instead of using a DSL to define events, SimpleStateMachine decorates methods 
+to help you encapsulate state and guard state transitions.
 
-Instead of using a DSL to define events, SimpleStateMachine decorates existing methods with logic that guards 
-state transitions.
+== Example usage
 
-==== example
+Write 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.
+
+  event :activate_account, :pending => :active
+
+
+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
+When using ActiveRecord / ActiveModel you can add an error to the errors object.
+This will prevent the state from being changed.
+  
   def activate_account(activation_code)
     if activation_code_invalid?(activation_code)
       errors.add(:activation_code, 'Invalid')
     end
   end
-  event :activate_account, :pending => :active
 
 
-Decorating methods has a couple of advantages:
-- No need for defining callbacks or other methods to add logic
-- Arguments can be passed to events
-- Validation errors can be set on the model if you are using ActiveRecord / ActiveModel
-
-== Example
+== More complete implementation
 
 To add a state machine:
 - extend SimpleStateMachine
@@ -43,9 +58,8 @@ To add a state machine:
       event :push_switch_1, :off => :on,
                             :on  => :off
       
-      def push_switch_2
-        puts 'pushed switch 2 #{state}'
-      end
+      # define another event
+      # note that implementation of :push_switch_2 is optional
       event :push_switch_2, :off => :on,
                             :on  => :off
       

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.3.3

data/lib/simple_state_machine/active_record.rb

@@ -10,10 +10,12 @@ module SimpleStateMachine::ActiveRecord
 
     def decorate transition
       super transition
-      unless @subject.method_defined?("#{transition.event_name}_and_save")
-        @subject.send(:define_method, "#{transition.event_name}_and_save") do |*args|
+      event_name = transition.event_name.to_s
+      event_name_and_save = "#{event_name}_and_save"
+      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 "#{transition.event_name}", *args
+          send event_name, *args
           if !self.errors.entries.empty?
             self.send("#{self.class.state_machine_definition.state_method}=", old_state)
             return false
@@ -27,10 +29,11 @@ module SimpleStateMachine::ActiveRecord
           end
         end
       end
-      unless @subject.method_defined?("#{transition.event_name}_and_save!")
-        @subject.send(:define_method, "#{transition.event_name}_and_save!") do |*args|
+      event_name_and_save_bang = "#{event_name_and_save}!"
+      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 "#{transition.event_name}", *args
+          send event_name, *args
           if !self.errors.entries.empty?
             self.send("#{self.class.state_machine_definition.state_method}=", old_state)
             raise ActiveRecord::RecordInvalid.new(self)
@@ -42,7 +45,7 @@ module SimpleStateMachine::ActiveRecord
             raise #re raise
           end
         end
-        @subject.send :alias_method, "#{transition.event_name}!", "#{transition.event_name}_and_save!"
+        @subject.send :alias_method, "#{transition.event_name}!", event_name_and_save_bang 
       end
     end
   

data/lib/simple_state_machine/simple_state_machine.rb

@@ -1,4 +1,8 @@
 module SimpleStateMachine
+  
+  class Error < ::RuntimeError
+  end
+
   ##
   # Adds state machine methods to extended class 
   module StateMachineMixin
@@ -103,7 +107,7 @@ module SimpleStateMachine
 
       def illegal_event_callback event_name
         # override with your own implementation, like setting errors in your model
-        raise "You cannot '#{event_name}' when state is '#{@subject.state}'"
+        raise Error.new("You cannot '#{event_name}' when state is '#{@subject.state}'")
       end
   
   end

data/simple_state_machine.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{simple_state_machine}
-  s.version = "0.3.2"
+  s.version = "0.3.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Marek de Heus", "Petrik de Heus"]
-  s.date = %q{2010-08-30}
+  s.date = %q{2010-09-03}
   s.description = %q{A simple DSL to decorate existing methods with logic that guards state transitions.}
   s.email = ["FIX@example.com"]
   s.extra_rdoc_files = [

data/spec/active_record_spec.rb

@@ -5,6 +5,7 @@ gem 'activerecord', '~> 2.3.5'
 require 'active_record'
 require 'examples/user'
 
+ActiveRecord::Base.logger = Logger.new STDOUT
 ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :dbfile => ":memory:")
 
 def setup_db
@@ -68,6 +69,15 @@ describe ActiveRecord do
       User.find(user.id).activation_code.should_not be_nil
     end
 
+    it "persist transitions even when state is attr_protected" do
+      user_class = Class.new(User)
+      user_class.instance_eval { attr_protected :state }
+      user = user_class.create!(:name => 'name', :state => 'x')
+      user.should be_new
+      user.invite_and_save
+      user.reload.should be_invited
+    end
+
     it "persists transitions when using send and a symbol" do
       user = User.create!(:name => 'name')
       user.send(:invite_and_save).should == true
@@ -78,7 +88,7 @@ describe ActiveRecord do
     it "raises an error if an invalid state_transition is called" do
       user = User.create!(:name => 'name')
       l = lambda { user.confirm_invitation_and_save 'abc' }
-      l.should raise_error(RuntimeError, "You cannot 'confirm_invitation' when state is 'new'")
+      l.should raise_error(SimpleStateMachine::Error, "You cannot 'confirm_invitation' when state is 'new'")
     end
 
     it "returns false and keeps state if record is invalid" do
@@ -109,10 +119,19 @@ describe ActiveRecord do
       User.find(user.id).activation_code.should_not be_nil
     end
 
+    it "persist transitions even when state is attr_protected" do
+      user_class = Class.new(User)
+      user_class.instance_eval { attr_protected :state }
+      user = user_class.create!(:name => 'name', :state => 'x')
+      user.should be_new
+      user.invite_and_save!
+      user.reload.should be_invited
+    end
+
     it "raises an error if an invalid state_transition is called" do
       user = User.create!(:name => 'name')
       l = lambda { user.confirm_invitation_and_save! 'abc' }
-      l.should raise_error(RuntimeError, "You cannot 'confirm_invitation' when state is 'new'")
+      l.should raise_error(SimpleStateMachine::Error, "You cannot 'confirm_invitation' when state is 'new'")
     end
 
     it "raises a RecordInvalid and keeps state if record is invalid" do

data/spec/decorator_spec.rb

@@ -27,12 +27,12 @@ end
 describe SimpleStateMachine::Decorator do
 
   it "defines state_helper_methods for all states" do
-    TrafficLight.new.green?.should == true
+    TrafficLight.new.green?.should  == true
     TrafficLight.new.orange?.should == false
-    TrafficLight.new.red?.should == false
+    TrafficLight.new.red?.should    == false
   end
   
-  it "does not define an state_helper_method if it already exists" do
+  it "does not define a state_helper_method if it already exists" do
     l = lambda { WithPredefinedStateHelperMethods.new.unread? }
     l.should raise_error(RuntimeError, 'blah')
   end
@@ -41,4 +41,4 @@ describe SimpleStateMachine::Decorator do
     WithoutEventMethods.new.view
   end
 
-end
+end

data/spec/simple_state_machine_spec.rb

@@ -15,7 +15,11 @@ class SimpleExample
 end
 
 describe SimpleStateMachine do
-  
+ 
+  it "has an error that extends RuntimeError" do
+    SimpleStateMachine::Error.superclass.should == RuntimeError
+  end
+
   it "has a default state" do
     SimpleExample.new.state.should == 'state1'
   end
@@ -40,7 +44,7 @@ describe SimpleStateMachine do
 
     it "raise an error if an invalid state_transition is called" do
       example = SimpleExample.new
-      lambda { example.event2 }.should raise_error(RuntimeError, "You cannot 'event2' when state is 'state1'")
+      lambda { example.event2 }.should raise_error(SimpleStateMachine::Error, "You cannot 'event2' when state is 'state1'")
     end
 
     it "return nil" do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: simple_state_machine
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 3
-  - 2
-  version: 0.3.2
+  - 3
+  version: 0.3.3
 platform: ruby
 authors: 
 - Marek de Heus
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-30 00:00:00 +02:00
+date: 2010-09-03 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency