simple_state_machine 0.6.0.pre → 0.6.0

data/Changelog.rdoc

@@ -0,0 +1,16 @@
+== 0.6.0
+=== Enhancements
+- Define decorated methods as #{event_name}_with_managed_state instead of with_managed_state_#{event_name} [Petrik]
+- Added raised_error method to access caught Errors [Petrik]
+- Added support for a default error state [Marek de Heus]
+- Removed transaction support, you can still add it manually, see active_record_spec.rb [Marek de Heus]
+- Allow catching errors for subclasses of the error [Petrik]
+- Added gem install instructions [Marek de Heus]
+- Added define_event method to simplify mountable state machine definitions [Petrik]
+- Added end_states method so we can check the state machine correctness [Petrik]
+- Added begin_states method so we can check the state machine correctness [Petrik]
+
+=== Bugfixes
+- Fixed bug in Inspector, from state can now be a Error class [Marek de Heus]
+- Make sure from and end states are uniq [Petrik]
+- fixed typos (graphiz -> graphviz) (redmar-master) [rjk]

data/README.rdoc

@@ -19,9 +19,21 @@ Or add it to your Gemfile:
   gem 'simple_state_machine'
 
 
-== Basic usage
+== Usage
 
-Define your event as a method, arguments are allowed:
+Define an event and specify how the state should transition. 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.
+
+=== Methods with arguments
+
+If you want to pass arguments and call other methods before the state transition, define your
+event as a method.
 
   def activate_account(activation_code)
     # call other methods, no need to add these in callbacks
@@ -29,13 +41,10 @@ Define your event as a method, arguments are allowed:
   end
 
 Now mark the method as an event and specify how the state should transition 
-when the method is called. If we want the state to change from :pending to :active we write:
+when the method is called. 
 
   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.
 
 
 == Basic example
@@ -48,9 +57,6 @@ If the state change is not allowed, a SimpleStateMachine::IllegalStateTransition
        self.state = 'off'
      end
 
-     def push_switch
-       puts "pushed switch"
-     end
      event :push_switch, :off => :on,
                          :on  => :off
 
@@ -59,14 +65,16 @@ If the state change is not allowed, a SimpleStateMachine::IllegalStateTransition
   lamp = LampSwitch.new
   lamp.state          # => 'off'
   lamp.off?           # => true
-  lamp.push_switch    # => 'pushed switch'
+  lamp.push_switch    #
   lamp.state          # => 'on'
   lamp.on?            # => true
-  lamp.push_switch    # => 'pushed switch'
+  lamp.push_switch    #
   lamp.off?           # => true
 
 
-== ActiveRecord Example
+== ActiveRecord
+
+=== Example
 
 To add a state machine to an ActiveRecord class, you will have to:
 - extend SimpleStateMachine::ActiveRecord,
@@ -85,42 +93,58 @@ To add a state machine to an ActiveRecord class, you will have to:
         self.activation_code = Digest::SHA1.hexdigest("salt #{Time.now.to_f}")
       end
       event :invite, :pending => :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
 
-This generates the following event methods
+    user = User.new
+    user.pending?         # => true
+    user.invite           # => true
+    user.invited?         # => true
+    user.activation_code  # => 'SOMEDIGEST'
+
+For the invite method this generates the following event methods
 - 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?
-- invited?
-- active?
 
 If you want to be more verbose you can also use:
 - invite_and_save  (alias for invite)
 - invite_and_save! (alias for invite!)
 
 
-== ActiveRecord Mountable Example
+=== 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.
+
+If we add an activate_account method to User
+
+    class User  < ActiveRecord::Base
+      ...
+      def activate_account(activation_code)
+        if activation_code_invalid?(activation_code)
+          errors.add(:activation_code, 'Invalid')
+        end
+      end
+      event :activate_account, :invited => :confirmed
+      ...
+    end
+
+    user.confirm_invitation!('INVALID') # => raises ActiveRecord::RecordInvalid,
+                                        #           "Validation failed: Activation code is invalid"
+    user.confirmed?                     # => false
+    user.confirm_invitation!('VALID')
+    user.confirmed?                     # => true
+
+== Mountable StateMachines
 
 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)
+    event :invite,             :new     => :invited
+    event :confirm_invitation, :invited => :active
 
     def decorator_class
-      SimpleStateMachine::Decorator
+      SimpleStateMachine::Decorator::Default
     end
   end
 
@@ -136,49 +160,53 @@ If you like to separate your state machine from your model class, you can do so
   end
 
 
-== 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
+== Transitions
 
-  activate_account!("INVALID_CODE") # => ActiveRecord::RecordInvalid, "Validation failed: Activation code is invalid"
+=== Catching all from states
+If an event should transition from all other defined states, you can use :all as from state:
 
-This will prevent the state from being changed.
+  event :suspend, :all => :suspended
 
 
-== Catching exceptions
+=== Catching exceptions
 
 You can let the state machine handle exceptions by specifying the failure state for an Error:
 
   def download_data
-    Service.download_data
+    raise Service::ConnectionError
   end
-  event :download_data, :pending => :downloaded,
-        Service::ConnectionError => :download_failed
+  event :download_data, 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
+=== Default error state
+
+To automatically change all states to a default error state use default_error_state:
+  
+  state_machine_definition.default_error_state = :failed
+
+== Transactions
+
+If you want to run events in transactions run them in a transaction block:
 
+  user.transaction { user.invite }
 
-== Generating state diagrams
+== Tools
+
+===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
 
+A Googlechart example:
+http://tinyurl.com/79xztr6
+
 
 == Note on Patches/Pull Requests
 

data/lib/simple_state_machine.rb

@@ -1,4 +1,13 @@
 require 'simple_state_machine/simple_state_machine'
-require 'simple_state_machine/active_record'
+require 'simple_state_machine/state_machine'
+require 'simple_state_machine/tools/graphviz'
+require 'simple_state_machine/tools/inspector'
+require 'simple_state_machine/state_machine_definition'
+require 'simple_state_machine/transition'
+require 'simple_state_machine/decorator/default'
+# if defined?(ActiveRecord)
+  require 'simple_state_machine/active_record'
+  require 'simple_state_machine/decorator/active_record'
+# end
 require "simple_state_machine/railtie" if defined?(Rails::Railtie)
 

data/lib/simple_state_machine/active_record.rb

@@ -4,84 +4,10 @@ module SimpleStateMachine::ActiveRecord
   include SimpleStateMachine::Extendable
   include SimpleStateMachine::Inheritable
 
-  class Decorator < SimpleStateMachine::Decorator
-
-    # decorates subject with:
-    # * {event_name}_and_save
-    # * {event_name}_and_save!
-    # * {event_name}!
-    # * {event_name}
-    def decorate transition
-      super transition
-      event_name = transition.event_name.to_s
-      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)
-            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
-      end
-
-      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
-      end
-
-      def decorate_ar_method
-      end
-
-      def alias_event_methods event_name
-        @subject.send :alias_method, "without_managed_state_#{event_name}", 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
-      @state_machine_definition.decorator_class = Decorator
+      @state_machine_definition.decorator_class = SimpleStateMachine::Decorator::ActiveRecord
       @state_machine_definition.subject = self
     end
     @state_machine_definition

data/lib/simple_state_machine/decorator/active_record.rb

@@ -0,0 +1,74 @@
+module SimpleStateMachine
+  module Decorator
+    class ActiveRecord < SimpleStateMachine::Decorator::Default
+
+      # decorates subject with:
+      # * {event_name}_and_save
+      # * {event_name}_and_save!
+      # * {event_name}!
+      # * {event_name}
+      def decorate transition
+        super transition
+        event_name = transition.event_name.to_s
+        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 "#{event_name}_with_managed_state", *args
+              if !self.errors.entries.empty?
+                self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+              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
+        end
+
+        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 "#{event_name}_with_managed_state", *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
+        end
+
+        def alias_event_methods event_name
+          @subject.send :alias_method, "#{event_name}_without_managed_state", event_name
+        end
+
+        def define_state_setter_method; end
+
+        def define_state_getter_method; end
+
+    end
+  end
+end

data/lib/simple_state_machine/decorator/default.rb

@@ -0,0 +1,91 @@
+module SimpleStateMachine
+  module Decorator
+    ##
+    # Decorates @subject with methods to access the state machine
+    class Default
+
+      attr_writer :subject
+      def initialize(subject)
+        @subject = subject
+      end
+
+      def decorate transition
+        define_state_machine_method
+        define_state_getter_method
+        define_state_setter_method
+
+        define_state_helper_method(transition.from)
+        define_state_helper_method(transition.to)
+        define_event_method(transition.event_name)
+        decorate_event_method(transition.event_name)
+      end
+
+      private
+
+        def define_state_machine_method
+          unless any_method_defined?("state_machine")
+            @subject.send(:define_method, "state_machine") do
+              @state_machine ||= StateMachine.new(self)
+            end
+          end
+        end
+
+        def define_state_helper_method state
+          unless any_method_defined?("#{state.to_s}?")
+            @subject.send(:define_method, "#{state.to_s}?") do
+              self.send(self.class.state_machine_definition.state_method) == state.to_s
+            end
+          end
+        end
+
+        def define_event_method event_name
+          unless any_method_defined?("#{event_name}")
+            @subject.send(:define_method, "#{event_name}") {}
+          end
+        end
+
+        def decorate_event_method event_name
+          # TODO put in transaction for activeRecord?
+          unless @subject.method_defined?("#{event_name}_with_managed_state")
+            @subject.send(:define_method, "#{event_name}_with_managed_state") do |*args|
+              return state_machine.transition(event_name) do
+                send("#{event_name}_without_managed_state", *args)
+              end
+            end
+            alias_event_methods event_name
+          end
+        end
+
+        def define_state_setter_method
+          unless any_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 any_method_defined?(state_method)
+            @subject.send(:attr_reader, state_method)
+          end
+        end
+
+        def any_method_defined?(method)
+          @subject.method_defined?(method) ||
+          @subject.protected_method_defined?(method) ||
+          @subject.private_method_defined?(method)
+        end
+
+      protected
+
+        def alias_event_methods event_name
+          @subject.send :alias_method, "#{event_name}_without_managed_state", event_name
+          @subject.send :alias_method, event_name, "#{event_name}_with_managed_state"
+        end
+
+        def state_method
+          @subject.state_machine_definition.state_method
+        end
+    end
+  end
+end