simple_state_machine 0.5.3 → 0.6.0.pre

data/README.rdoc

@@ -5,34 +5,18 @@ 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.
 
-It supports exception rescuing, google chart visualization and mountable state_machines.
+It supports exception rescuing, google chart visualization and mountable state machines.
 
-== Basic example
 
-    class LampSwitch
+== Installation
 
-      extend SimpleStateMachine
+Use gem install:
 
-      def initialize
-        self.state = 'off'
-      end
+  gem install simple_state_machine
 
-      def push_switch
-        puts "pushed switch"
-      end
-      event :push_switch, :off => :on,
-                          :on  => :off
-
-    end
+Or add it to your Gemfile:
 
-    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
+  gem 'simple_state_machine'
 
 
 == Basic usage
@@ -53,59 +37,55 @@ 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.
 
-=== 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.
-  
-  def activate_account(activation_code)
-    if activation_code_invalid?(activation_code)
-      errors.add(:activation_code, 'Invalid')
-    end
-  end
 
-  activate_account!("INVALID_CODE") # => ActiveRecord::RecordInvalid, "Validation failed: Activation code is invalid"
+== Basic example
 
-=== Catching exceptions
-You can rescue exceptions and specify the failure state
+  class LampSwitch
 
-  def download_data
-    Service.download_data
-  end
-  event :download_data, :pending => :downloaded,
-        Service::ConnectionError => :download_failed
+     extend SimpleStateMachine
 
-  download_data # catches Service::ConnectionError
-  state         # => "download_failed"
+     def initialize
+       self.state = 'off'
+     end
 
-=== Catching all from states
-If an event should transition from all states you can use :all
+     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
 
-  event :suspend, :all => :suspended
 
 == ActiveRecord Example
 
-To add a state machine with ActiveRecord persistence:
+To add a state machine to an ActiveRecord class, you will have to:
 - 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.ssm_state ||= 'pending'
-        # if you get an ActiveRecord::MissingAttributeError
-        # you'll probably need to do (http://bit.ly/35q23b):
-        #   write_attribute(:ssm_state, "pending") unless read_attribute(:ssm_state)
-      end
-      
+        self.state ||= 'pending'
+       end
+
       def invite
         self.activation_code = Digest::SHA1.hexdigest("salt #{Time.now.to_f}")
-        #send_activation_email
       end
       event :invite, :pending => :invited
-      
+
       def confirm_invitation activation_code
         if self.activation_code != activation_code
           errors.add 'activation_code', 'is invalid'
@@ -115,9 +95,10 @@ To add a state machine with ActiveRecord persistence:
     end
 
 This generates the following event methods
-- invite
-- invite!
-- confirm_invitation!
+- invite              (behaves like ActiveRecord save )
+- invite!             (behaves like ActiveRecord save!)
+- confirm_invitation  (behaves like ActiveRecord save )
+- confirm_invitation! (behaves like ActiveRecord save!)
 
 And the following methods to query the state:
 - pending?
@@ -125,40 +106,82 @@ And the following methods to query the state:
 - active?
 
 If you want to be more verbose you can also use:
-- invite_and_save  (is equal to invite  and behaves like ActiveRecord save)
-- invite_and_save! (is equal to invite! and behaves like save!)
+- invite_and_save  (alias for invite)
+- invite_and_save! (alias for invite!)
 
-== Mountable Example
 
-You can define your state machine in a seperate class:
+== ActiveRecord Mountable Example
 
-    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
+If you like to separate your state machine from your model class, you can do so as following:
+
+  class MyStateMachine < SimpleStateMachine::StateMachineDefinition
+
+    event(:invite,             :new     => :invited)
+    event(:confirm_invitation, :invited => :active)
+
+    def decorator_class
+      SimpleStateMachine::Decorator
     end
+  end
 
-    class User < ActiveRecord::Base
-       
-      extend SimpleStateMachine::Mountable
-      self.state_machine_definition = MyStateMachine.new self
+  class User < ActiveRecord::Base
 
-      def after_initialize
-        self.ssm_state ||= 'new'
-      end
-      
+    extend SimpleStateMachine::Mountable
+    mount_state_machine MyStateMachine
+
+    def after_initialize
+      self.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.
+== Using ActiveRecord / ActiveModel validations
+
+When using ActiveRecord / ActiveModel you can add an error to the errors object:
+
+  def activate_account(activation_code)
+    if activation_code_invalid?(activation_code)
+      errors.add(:activation_code, 'Invalid')
+    end
+  end
+
+  activate_account!("INVALID_CODE") # => ActiveRecord::RecordInvalid, "Validation failed: Activation code is invalid"
+
+This will prevent the state from being changed.
+
+
+== Catching exceptions
+
+You can let the state machine handle exceptions by specifying the failure state for an Error:
+
+  def download_data
+    Service.download_data
+  end
+  event :download_data, :pending => :downloaded,
+        Service::ConnectionError => :download_failed
+
+  download_data               # catches Service::ConnectionError
+  state                       # => "download_failed"
+  state_machine.raised_error  # the raised error
+
+== Catching all from states
+If an event should transition from all other defined states, you can use :all as from state:
+
+  event :suspend, :all => :suspended
+
+
+== Generating state diagrams
+
+When using Rails/ActiveRecord you can generate a state diagram of the state machine via the
+built in rake tasks.
+For details run:
+  
+  rake -T ssm
 
 
 == Note on Patches/Pull Requests
- 
+
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
@@ -167,6 +190,7 @@ If your using rails you get rake tasks for generating a graphiz google chart of
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
+
 == Copyright
 
 Copyright (c) 2010 Marek & Petrik. See LICENSE for details.

data/examples/user.rb

@@ -1,12 +1,15 @@
 require 'digest/sha1'
 class User < ActiveRecord::Base
-  
+
   validates_presence_of :name
-  
+
   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(:ssm_state, "pending") unless read_attribute(:ssm_state)
   end
 
   def invite
@@ -23,13 +26,13 @@ class User < ActiveRecord::Base
   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)
     true
   end

data/lib/simple_state_machine/active_record.rb

@@ -14,46 +14,59 @@ module SimpleStateMachine::ActiveRecord
     def decorate transition
       super transition
       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 "with_managed_state_#{event_name}", *args
-          if !self.errors.entries.empty?
-            self.send("#{self.class.state_machine_definition.state_method}=", old_state)
-            return false
-          else
-            if save
-              return true
-            else
+      decorate_save  event_name
+      decorate_save! event_name
+    end
+
+    protected
+
+      def decorate_save event_name
+        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|
+            result    = false
+            old_state = self.send(self.class.state_machine_definition.state_method)
+            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
+            else
+              if save
+                result = true
+              else
+                self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+              end
             end
+            return result
           end
+          @subject.send :alias_method, "#{event_name}", event_name_and_save
         end
-        @subject.send :alias_method, "#{transition.event_name}", event_name_and_save
       end
-      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 "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)
-          end
-          begin
-            save!
-          rescue ActiveRecord::RecordInvalid
-            self.send("#{self.class.state_machine_definition.state_method}=", old_state)
-            raise #re raise
+
+      def decorate_save! event_name
+        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|
+            result = nil
+            old_state = self.send(self.class.state_machine_definition.state_method)
+            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)
+            end
+            begin
+              result = save!
+            rescue ActiveRecord::RecordInvalid
+              self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+              raise #re raise
+            end
+            return result
           end
+          @subject.send :alias_method, "#{event_name}!", event_name_and_save_bang
         end
-        @subject.send :alias_method, "#{transition.event_name}!", event_name_and_save_bang
       end
-    end
 
-    protected
+      def decorate_ar_method
+      end
 
       def alias_event_methods event_name
         @subject.send :alias_method, "without_managed_state_#{event_name}", event_name
@@ -68,7 +81,8 @@ module SimpleStateMachine::ActiveRecord
   def state_machine_definition
     unless @state_machine_definition
       @state_machine_definition = SimpleStateMachine::StateMachineDefinition.new
-      @state_machine_definition.lazy_decorator = lambda { Decorator.new(self) }
+      @state_machine_definition.decorator_class = Decorator
+      @state_machine_definition.subject = self
     end
     @state_machine_definition
   end

data/lib/simple_state_machine/railtie.rb

@@ -4,7 +4,7 @@ require 'rails'
 module SimpleStateMachine
   class Railtie < Rails::Railtie
     rake_tasks do
-      load "tasks/graphiz.rake"
+      load "tasks/graphviz.rake"
     end
   end
 end

data/lib/simple_state_machine/simple_state_machine.rb

@@ -11,7 +11,7 @@ module SimpleStateMachine
     def state_machine_definition
       unless @state_machine_definition
         @state_machine_definition = StateMachineDefinition.new
-        @state_machine_definition.lazy_decorator = lambda { Decorator.new(self) }
+        @state_machine_definition.subject = self
       end
       @state_machine_definition
     end
@@ -22,6 +22,12 @@ module SimpleStateMachine
         state_machine_definition.decorator.decorate(transition)
       end
     end
+
+    def mount_state_machine mountable_class
+      self.state_machine_definition = mountable_class.new
+      self.state_machine_definition.subject = self
+      self.state_machine_definition.add_events
+    end
   end
   include Mountable
 
@@ -31,11 +37,7 @@ module SimpleStateMachine
 
     # 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|
-          state_machine_definition.add_transition(event_name, from, to)
-        end
-      end
+      state_machine_definition.define_event event_name, state_transitions
     end
 
   end
@@ -58,16 +60,33 @@ module SimpleStateMachine
   # Defines state machine transitions
   class StateMachineDefinition
 
-    attr_writer :state_method, :decorator, :lazy_decorator
+    attr_writer :default_error_state, :state_method, :subject, :decorator,
+                :decorator_class
 
     def decorator
-      @decorator ||= @lazy_decorator.call
+      @decorator ||= decorator_class.new(@subject)
+    end
+
+    def decorator_class
+      @decorator_class ||= Decorator
+    end
+
+    def default_error_state
+      @default_error_state && @default_error_state.to_s
     end
 
     def transitions
       @transitions ||= []
     end
 
+    def define_event event_name, state_transitions
+      state_transitions.each do |froms, to|
+        [froms].flatten.each do |from|
+          add_transition(event_name, from, to)
+        end
+      end
+    end
+
     def add_transition event_name, from, to
       transition = Transition.new(event_name, from, to)
       transitions << transition
@@ -83,21 +102,88 @@ module SimpleStateMachine
       transitions.map(&:to_s).join("\n")
     end
 
-    # Graphiz dot format for rendering as a directional graph
-    def to_graphiz_dot
-      transitions.map { |t| t.to_graphiz_dot }.join(";")
+    module Graphviz
+      # Graphviz dot format for rendering as a directional graph
+      def to_graphviz_dot
+        transitions.map { |t| t.to_graphviz_dot }.sort.join(";")
+      end
+
+      # Generates a url that renders states and events as a directional graph.
+      # See http://code.google.com/apis/chart/docs/gallery/graphviz.html
+      def google_chart_url
+        "http://chart.googleapis.com/chart?cht=gv&chl=digraph{#{::CGI.escape to_graphviz_dot}}"
+      end
     end
+    include Graphviz
+
+    module Inspector
+      def begin_states
+        from_states - to_states
+      end
+
+      def end_states
+        to_states - from_states
+      end
+
+      def states
+        (to_states + from_states).uniq
+      end
+
+      private
+
+        def from_states
+          to_uniq_sym(sample_transitions.map(&:from))
+        end
 
-    # Generates a url that renders states and events as a directional graph.
-    # See http://code.google.com/apis/chart/docs/gallery/graphviz.html
-    def google_chart_url
-      "http://chart.googleapis.com/chart?cht=gv&chl=digraph{#{::CGI.escape to_graphiz_dot}}"
+        def to_states
+          to_uniq_sym(sample_transitions.map(&:to))
+        end
+
+        def to_uniq_sym(array)
+          array.map { |state| state.is_a?(String) ? state.to_sym : state }.uniq
+        end
+
+        def sample_transitions
+          (@subject || sample_subject).state_machine_definition.send :transitions
+        end
+
+        def sample_subject
+          self_class = self.class
+          sample = Class.new do
+            extend SimpleStateMachine::Mountable
+            mount_state_machine self_class
+          end
+          sample
+        end
     end
+    include Inspector
+
+    module Mountable
+      def event event_name, state_transitions
+        events << [event_name, state_transitions]
+      end
+
+      def events
+        @events ||= []
+      end
+
+      module InstanceMethods
+        def add_events
+          self.class.events.each do |event_name, state_transitions|
+            define_event event_name, state_transitions
+          end
+        end
+      end
+    end
+    extend Mountable
+    include Mountable::InstanceMethods
+
   end
 
   ##
   # Defines the state machine used by the instance
   class StateMachine
+    attr_reader :raised_error
 
     def initialize(subject)
       @subject = subject
@@ -116,13 +202,20 @@ module SimpleStateMachine
     end
 
     # Transitions to the next state if next_state exists.
+    # When an error occurs, it uses the error to determine next state.
+    # If no next state can be determined it transitions to the default error
+    # state if defined, otherwise the error is re-raised.
     # Calls illegal_event_callback event_name if no next_state is found
     def transition(event_name)
+      clear_raised_error
       if to = next_state(event_name)
         begin
           result = yield
         rescue => e
-          if error_state = error_state(event_name, e)
+          error_state = error_state(event_name, e) ||
+            state_machine_definition.default_error_state
+          if error_state
+            @raised_error = e
             @subject.send("#{state_method}=", error_state)
             return result
           else
@@ -148,6 +241,10 @@ module SimpleStateMachine
 
     private
 
+      def clear_raised_error
+        @raised_error = nil
+      end
+
       def state_machine_definition
         @subject.class.state_machine_definition
       end
@@ -184,18 +281,17 @@ module SimpleStateMachine
 
     # returns true if it's a error transition for event_name and error
     def is_error_transition_for?(event_name, error)
-      is_same_event?(event_name) && error.class == from
+      is_same_event?(event_name) && from.is_a?(Class) && error.is_a?(from)
     end
 
     def to_s
       "#{from}.#{event_name}! => #{to}"
     end
 
-    def to_graphiz_dot
+    def to_graphviz_dot
       %("#{from}"->"#{to}"[label=#{event_name}])
     end
 
-
     private
 
       def is_same_event?(event_name)
@@ -214,12 +310,13 @@ module SimpleStateMachine
     attr_writer :subject
     def initialize(subject)
       @subject = subject
+    end
+
+    def decorate transition
       define_state_machine_method
       define_state_getter_method
       define_state_setter_method
-    end
 
-    def decorate transition
       define_state_helper_method(transition.from)
       define_state_helper_method(transition.to)
       define_event_method(transition.event_name)
@@ -229,8 +326,10 @@ module SimpleStateMachine
     private
 
       def define_state_machine_method
-        @subject.send(:define_method, "state_machine") do
-          @state_machine ||= StateMachine.new(self)
+        unless any_method_defined?("state_machine")
+          @subject.send(:define_method, "state_machine") do
+            @state_machine ||= StateMachine.new(self)
+          end
         end
       end
 

data/lib/simple_state_machine/version.rb

@@ -1,3 +1,3 @@
 module SimpleStateMachine
-  VERSION = "0.5.3"
+  VERSION = "0.6.0.pre"
 end

data/lib/tasks/graphviz.rake

@@ -0,0 +1,21 @@
+namespace :ssm do
+  namespace :graph do
+    desc 'Generate a url for a google chart. You must specify class=ClassName'
+    task :url => :environment do
+      if clazz = ENV['class']
+        puts clazz.constantize.state_machine_definition.google_chart_url
+      else
+        puts "Missing argument: class. Please specify class=ClassName"
+      end
+    end
+
+    desc 'Opens the google chart in your browser. You must specify class=ClassNAME'
+    task :open => :environment do
+      if clazz = ENV['class']
+        `open '#{::CGI.unescape(clazz.constantize.state_machine_definition.google_chart_url)}'`
+      else
+        puts "Missing argument: class. Please specify class=ClassName"
+      end
+    end
+  end
+end

data/simple_state_machine.gemspec

@@ -27,5 +27,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rspec"
   s.add_development_dependency "activerecord", "~>2.3.5"
   s.add_development_dependency "sqlite3-ruby"
+  s.add_development_dependency "ruby-debug"
 end
 

data/spec/active_record_spec.rb

@@ -111,6 +111,24 @@ describe ActiveRecord do
       user.errors.entries.should == [['activation_code', 'is invalid']]
     end
 
+    it "rollsback if an exception is raised" do
+      user_class = Class.new(User)
+      user_class.instance_eval do
+        define_method :without_managed_state_invite do
+          User.create!(:name => 'name2') #this shouldn't be persisted
+          User.create! #this should raise an error
+        end
+      end
+      user_class.count.should == 0
+      user = user_class.create!(:name => 'name')
+      expect {
+        user.transaction { user.invite_and_save }
+      }.to raise_error(ActiveRecord::RecordInvalid,
+                       "Validation failed: Name can't be blank")
+      user_class.count.should == 1
+      user_class.first.name.should == 'name'
+      user_class.first.should be_new
+    end
   end
 
   describe "event_and_save!" do
@@ -161,6 +179,25 @@ describe ActiveRecord do
       user.should be_invited
     end
 
+    it "rollsback if an exception is raised" do
+      user_class = Class.new(User)
+      user_class.instance_eval do
+        define_method :without_managed_state_invite do
+          User.create!(:name => 'name2') #this shouldn't be persisted
+          User.create! #this should raise an error
+        end
+      end
+      user_class.count.should == 0
+      user = user_class.create!(:name => 'name')
+      expect {
+        user.transaction { user.invite_and_save! }
+      }.to raise_error(ActiveRecord::RecordInvalid,
+                       "Validation failed: Name can't be blank")
+      user_class.count.should == 1
+      user_class.first.name.should == 'name'
+      user_class.first.should be_new
+    end
+
   end
 
   describe "event" do

data/spec/mountable_spec.rb

@@ -3,14 +3,19 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 describe "Mountable" do
   before do
     mountable_class = Class.new(SimpleStateMachine::StateMachineDefinition) do
-      def initialize(subject)
-        self.lazy_decorator = lambda { SimpleStateMachine::Decorator.new(subject) }
-        add_transition(:event, :state1, :state2)
+      event(:event, :state1 => :state2)
+
+      def decorator_class
+        SimpleStateMachine::Decorator
       end
     end
     klass = Class.new do
+      attr_accessor :event_called
       extend SimpleStateMachine::Mountable
-      self.state_machine_definition = mountable_class.new self
+      mount_state_machine mountable_class
+      def without_managed_state_event
+        @event_called = true
+      end
     end
     @instance = klass.new
     @instance.state = 'state1'
@@ -21,4 +26,9 @@ describe "Mountable" do
     @instance.should_not be_state2
   end
 
+  it "calls existing methods" do
+    @instance.event
+    @instance.should be_state2
+    @instance.event_called.should == true
+  end
 end

data/spec/simple_state_machine_spec.rb

@@ -2,7 +2,7 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 require 'cgi'
 
 describe SimpleStateMachine do
- 
+
   it "has an error that extends RuntimeError" do
     SimpleStateMachine::IllegalStateTransitionError.superclass.should == RuntimeError
   end
@@ -18,109 +18,138 @@ describe SimpleStateMachine do
       end
     end
 
-    it "changes state if event has multiple transitions" do
+    it "returns what the decorated method returns" do
       klass = Class.new(@klass)
       klass.instance_eval do
-        event :event, :state1 => :state2, :state2 => :state3
+        event :event1,  :state1 => :state2
+        define_method :event2 do
+          'event2'
+        end
+        event :event2, :state2 => :state3
       end
       example = klass.new
-      example.should be_state1
-      example.event
-      example.should be_state2
-      example.event
-      example.should be_state3
+      example.event1.should == nil
+      example.event2.should == 'event2'
     end
 
-    it "changes state if event has multiple froms" do
+    it "calls existing methods" do
       klass = Class.new(@klass)
       klass.instance_eval do
-        event :event, [:state1, :state2] => :state3
+        attr_accessor :event_called
+        define_method :event do
+          @event_called = true
+        end
+        event :event, :state1 => :state2
       end
       example = klass.new
       example.event
-      example.should be_state3
-      example = klass.new 'state2'
-      example.should be_state2
-      example.event
-      example.should be_state3
+      example.event_called.should == true
     end
 
-    it "changes state if event has all as from" do
-      klass = Class.new(@klass)
-      klass.instance_eval do
-        event :other_event, :state1 => :state2
-        event :event, :all => :state3
+    context "given an event has multiple transitions" do
+      it "changes state for all transitions" do
+        klass = Class.new(@klass)
+        klass.instance_eval do
+          event :event, :state1 => :state2, :state2 => :state3
+        end
+        example = klass.new
+        example.should be_state1
+        example.event
+        example.should be_state2
+        example.event
+        example.should be_state3
       end
-      example = klass.new
-      example.event
-      example.should be_state3
-      example = klass.new 'state2'
-      example.should be_state2
-      example.event
-      example.should be_state3
     end
 
-    it "changes state when state is a symbol instead of a string" do
-      klass = Class.new(@klass)
-      klass.instance_eval do
-        event :event, :state1 => :state2
-      end  
-      example = klass.new :state1
-      example.state.should == :state1
-      example.send(:event)
-      example.should be_state2
+    context "given an event has multiple from states" do
+      it "changes state for all from states" do
+        klass = Class.new(@klass)
+        klass.instance_eval do
+          event :event, [:state1, :state2] => :state3
+        end
+        example = klass.new
+        example.event
+        example.should be_state3
+        example = klass.new 'state2'
+        example.should be_state2
+        example.event
+        example.should be_state3
+      end
     end
 
-    it "changes state to error_state when error can be caught" do
-      class_with_error = Class.new(@klass)
-      class_with_error.instance_eval do
-        define_method :raise_error do
-          raise RuntimeError.new
+    context "given an event has :all as from state" do
+      it "changes state from all states" do
+        klass = Class.new(@klass)
+        klass.instance_eval do
+          event :other_event, :state1 => :state2
+          event :event, :all => :state3
         end
-        event :raise_error, :state1 => :state2, RuntimeError => :failed
+        example = klass.new
+        example.event
+        example.should be_state3
+        example = klass.new 'state2'
+        example.should be_state2
+        example.event
+        example.should be_state3
       end
-      example = class_with_error.new
-      example.should be_state1
-      example.raise_error
-      example.should be_failed
     end
-    
-    it "raises an error if an invalid state_transition is called" do
-      klass = Class.new(@klass)
-      klass.instance_eval do
-        event :event,  :state1 => :state2
-        event :event2, :state2 => :state3
-      end  
-      example = klass.new
-      lambda { example.event2 }.should raise_error(SimpleStateMachine::IllegalStateTransitionError, "You cannot 'event2' when state is 'state1'")
+
+    context "given state is a symbol instead of a string" do
+      it "changes state" do
+        klass = Class.new(@klass)
+        klass.instance_eval do
+          event :event, :state1 => :state2
+        end
+        example = klass.new :state1
+        example.state.should == :state1
+        example.send(:event)
+        example.should be_state2
+      end
     end
 
-    it "returns what the decorated method returns" do
-      klass = Class.new(@klass)
-      klass.instance_eval do
-        event :event1,  :state1 => :state2
-        define_method :event2 do
-          'event2'
+    context "given an RuntimeError begin state" do
+      it "changes state to error_state when error can be caught" do
+        class_with_error = Class.new(@klass)
+        class_with_error.instance_eval do
+          define_method :raise_error do
+            raise RuntimeError.new
+          end
+          event :raise_error, :state1 => :state2, RuntimeError => :failed
         end
-        event :event2, :state2 => :state3
-      end  
-      example = klass.new
-      example.event1.should == nil
-      example.event2.should == 'event2'
+        example = class_with_error.new
+        example.should be_state1
+        example.raise_error
+        example.should be_failed
+      end
+
+      it "changes state to error_state when error superclass can be caught" do
+        error_subclass   = Class.new(RuntimeError)
+        class_with_error = Class.new(@klass)
+        class_with_error.instance_eval do
+          define_method :raise_error do
+            raise error_subclass.new
+          end
+          event :raise_error, :state1 => :state2, RuntimeError => :failed
+        end
+        example = class_with_error.new
+        example.should be_state1
+        example.raise_error
+        example.should be_failed
+      end
     end
 
-    it "calls existing methods" do
-      klass = Class.new(@klass)
-      klass.instance_eval do
-        attr_accessor :event_called
-        define_method :event do
-          @event_called = true
+    context "given an invalid state_transition is called" do
+      it "raises an IllegalStateTransitionError" do
+        klass = Class.new(@klass)
+        klass.instance_eval do
+          event :event,  :state1 => :state2
+          event :event2, :state2 => :state3
         end
-        event :event, :state1 => :state2
-      end  
-      example = klass.new
-      example.event
-      example.event_called.should == true
+        example = klass.new
+        lambda { example.event2 }.should raise_error(
+            SimpleStateMachine::IllegalStateTransitionError,
+            "You cannot 'event2' when state is 'state1'")
+      end
     end
 
   end

data/spec/state_machine_definition_spec.rb

@@ -8,7 +8,7 @@ describe SimpleStateMachine::StateMachineDefinition do
       def initialize(state = 'state1')
         @state = state
       end
-      event :event1, :state1 => :state2, :state2 => :state3      
+      event :event1, :state1 => :state2, :state2 => :state3
     end
     @smd = @klass.state_machine_definition
   end
@@ -53,13 +53,103 @@ describe SimpleStateMachine::StateMachineDefinition do
       subject.event2
       subject.should be_state3
     end
-    
+
     it "raise an error if an invalid state_transition is called" do
       lambda { subject.event2 }.should raise_error(SimpleStateMachine::IllegalStateTransitionError, "You cannot 'event2' when state is 'state1'")
     end
 
   end
 
+  describe '#default_error_state' do
+    subject do
+      klass = Class.new do
+        attr_reader :state
+        extend SimpleStateMachine
+        state_machine_definition.default_error_state = :failed
+
+        def initialize(state = 'state1')
+          @state = state
+        end
+
+        def event1
+          raise "Some error during event"
+        end
+        event :event1, :state1 => :state2
+      end
+      klass.new
+    end
+
+    it "is set when an error occurs during an event" do
+      subject.state.should == 'state1'
+      subject.event1
+      subject.state.should == 'failed'
+    end
+  end
+
+  describe "#begin_states" do
+    before do
+      @klass = Class.new(SimpleStateMachine::StateMachineDefinition) do
+        def add_events
+          define_event(:event_a, :state1      => :state2)
+          define_event(:event_b, :state2      => :state3)
+          define_event(:event_c, :state1      => :state3)
+          define_event(:event_c, RuntimeError => :state3)
+        end
+
+        def decorator_class
+          SimpleStateMachine::Decorator
+        end
+      end
+    end
+
+    it "returns all 'from' states that aren't 'to' states" do
+      @klass.new.begin_states.should == [:state1, RuntimeError]
+    end
+  end
+
+  describe "#end_states" do
+    before do
+      @klass = Class.new(SimpleStateMachine::StateMachineDefinition) do
+        def add_events
+          define_event(:event_a, :state1 => :state2)
+          define_event(:event_b, :state2 => :state3)
+          define_event(:event_c, :state1 => :state3)
+        end
+
+        def decorator_class
+          SimpleStateMachine::Decorator
+        end
+
+      end
+    end
+
+    it "returns all 'to' states that aren't 'from' states" do
+      @klass.new.end_states.should == [:state3]
+    end
+  end
+
+  describe "#states" do
+    before do
+      @klass = Class.new(SimpleStateMachine::StateMachineDefinition) do
+        def add_events
+          define_event(:event_a, :state1 => :state2)
+          define_event(:event_b, :state2 => :state3)
+          define_event(:event_c, :state1 => :state3)
+        end
+
+        def decorator_class
+          SimpleStateMachine::Decorator
+        end
+
+      end
+    end
+
+    it "returns all states" do
+      @klass.new.states.map(&:to_s).sort.should == %w{state1 state2 state3}
+    end
+  end
+
+
   describe "#transitions" do
     it "has a list of transitions" do
       @smd.transitions.should be_a(Array)
@@ -73,16 +163,15 @@ describe SimpleStateMachine::StateMachineDefinition do
     end
   end
 
-  describe "#to_graphiz_dot" do
-    it "converts to graphiz dot format" do
-      @smd.to_graphiz_dot.should ==  %("state1"->"state2"[label=event1];"state2"->"state3"[label=event1])
+  describe "#to_graphviz_dot" do
+    it "converts to graphviz dot format" do
+      @smd.to_graphviz_dot.should ==  %("state1"->"state2"[label=event1];"state2"->"state3"[label=event1])
     end
   end
 
   describe "#google_chart_url" do
     it "shows the state and event dependencies as a Google chart" do
-      puts "http://chart.googleapis.com/chart?cht=gv&chl=digraph{#{::CGI.escape @smd.to_graphiz_dot}}"
-      @smd.google_chart_url.should == "http://chart.googleapis.com/chart?cht=gv&chl=digraph{#{::CGI.escape @smd.to_graphiz_dot}}"
+      @smd.google_chart_url.should == "http://chart.googleapis.com/chart?cht=gv&chl=digraph{#{::CGI.escape @smd.to_graphviz_dot}}"
     end
   end
 end

data/spec/state_machine_spec.rb

@@ -22,5 +22,39 @@ describe SimpleStateMachine::StateMachine do
     end
   end
 
+  describe "#raised_error" do
+    context "given an error can be caught" do
+      let(:class_with_error) do
+        Class.new do
+          extend SimpleStateMachine
+          def initialize(state = 'state1'); @state = state; end
+          def raise_error
+            raise "Something went wrong"
+          end
+          event :raise_error, :state1 => :state2,
+                RuntimeError => :failed
+          event :retry,  :failed => :success
+        end
+      end
+
+      it "the raised error is accessible" do
+        example = class_with_error.new
+        example.raise_error
+        raised_error = example.state_machine.raised_error
+        raised_error.should be_a(RuntimeError)
+        raised_error.message.should == "Something went wrong"
+      end
+
+      it "the raised error is set to nil on the next transition" do
+        example = class_with_error.new
+        example.raise_error
+        example.state_machine.raised_error.should be
+        example.retry
+        example.state_machine.raised_error.should_not be
+      end
+
+    end
+  end
+
 end
 

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: simple_state_machine
 version: !ruby/object:Gem::Version 
-  hash: 13
-  prerelease: 
+  hash: 961916020
+  prerelease: 6
   segments: 
   - 0
-  - 5
-  - 3
-  version: 0.5.3
+  - 6
+  - 0
+  - pre
+  version: 0.6.0.pre
 platform: ruby
 authors: 
 - Marek de Heus
@@ -16,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-06 00:00:00 +01:00
+date: 2011-07-06 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -91,6 +92,20 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
 description: Simple State Machine is a state machine that focuses on events instead of states
 email: 
 - FIX@example.com
@@ -120,8 +135,7 @@ files:
 - lib/simple_state_machine/railtie.rb
 - lib/simple_state_machine/simple_state_machine.rb
 - lib/simple_state_machine/version.rb
-- lib/tasks/graphiz.rake
-- rails/graphiz.rake
+- lib/tasks/graphviz.rake
 - simple_state_machine.gemspec
 - spec/active_record_spec.rb
 - spec/decorator_spec.rb
@@ -152,12 +166,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      hash: 3
+      hash: 25
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: 

data/lib/tasks/graphiz.rake

@@ -1,13 +0,0 @@
-namespace :ssm do
-  namespace :graph do
-    desc 'Generate a url for a google chart for [class]'
-    task :url => :environment do
-      puts ENV['class'].constantize.state_machine_definition.google_chart_url
-    end
-
-    desc 'Opens the google chart in the browser for [class]'
-    task :open => :environment do
-      `open '#{::CGI.unescape(ENV['class'].constantize.state_machine_definition.google_chart_url)}'`
-    end
-  end
-end

data/rails/graphiz.rake

@@ -1,16 +0,0 @@
-namespace :ssm do
-
-  namespace :graph do
-    
-    desc 'url'
-    task 'url' do |t|
-    end
-
-    desc 'image'
-    task 'image' do |t|
-    end
-
-  end
-
-end
-