simple_state_machine 0.5.3 → 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03d0976fcf4c2dccd328f82cb00f8b5050f2cc052b578ae98d0227aca37afb5b
+  data.tar.gz: 193ae0211b9f82a386317032a2fe3ee245d263801cfab69981c3c6d9cfbe2053
+SHA512:
+  metadata.gz: 4e31fd218c64886a4e5fba9334d4b5b71c9bdcbc1fd3216df488a3edc25d6d9a846336887c700623c84b401fc89a6a4afdaa02a0a7ad0d7e3e9456c6bcfdba2e
+  data.tar.gz: 4659c64c0b4422967418ca9289ce97e259defd2c4bcbd621e51e37422b2d036b2c8bede71b8b59c97a81137aa076a11403d47c6de2231314272b611b0d7cc08a

data/Changelog.rdoc

@@ -0,0 +1,23 @@
+== 0.6.1
+- Run against latest rubies and activerecord
+- Remove old rubygems version requirement
+- Remove some trailing whitespace [Petrik]
+- Use `expect` instead if old `should` notation [Petrik]
+- Drop support for Ruby 1.9 [Petrik]
+
+== 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

@@ -1,43 +1,29 @@
 = SimpleStateMachine
 
+{<img src="https://github.com/mdh/ssm/actions/workflows/build.yml/badge.svg" />}[https://github.com/mdh/ssm/actions?query=workflow%3A.github%2Fworkflows%2Fbuild.yml+branch%3Amaster++]
+
 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.
-
-== Basic example
-
-    class LampSwitch
-
-      extend SimpleStateMachine
+It supports exception rescuing, google chart visualization and mountable state machines.
 
-      def initialize
-        self.state = 'off'
-      end
+== Usage
 
-      def push_switch
-        puts "pushed switch"
-      end
-      event :push_switch, :off => :on,
-                          :on  => :off
+Define an event and specify how the state should transition. If we want the state to change
+from *pending* to *active* we write:
 
-    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 :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 usage
+=== Methods with arguments
 
-Define your event as a method, arguments are allowed:
+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
@@ -45,120 +31,187 @@ 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.
 
-=== 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
+
+     extend SimpleStateMachine
+
+     def initialize
+       self.state = 'off'
+     end
+
+     event :push_switch, :off => :on,
+                         :on  => :off
 
-  def download_data
-    Service.download_data
   end
-  event :download_data, :pending => :downloaded,
-        Service::ConnectionError => :download_failed
 
-  download_data # catches Service::ConnectionError
-  state         # => "download_failed"
+  lamp = LampSwitch.new
+  lamp.state          # => 'off'
+  lamp.off?           # => true
+  lamp.push_switch    #
+  lamp.state          # => 'on'
+  lamp.on?            # => true
+  lamp.push_switch    #
+  lamp.off?           # => true
 
-=== Catching all from states
-If an event should transition from all states you can use :all
 
-  event :suspend, :all => :suspended
+== ActiveRecord
 
-== ActiveRecord Example
+For ActiveRecord methods are decorated with state transition guards _and_ persistence.
+Methods marked as events behave like ActiveRecord *save* and *save!*.
 
-To add a state machine with ActiveRecord persistence:
-- extend SimpleStateMachine::ActiveRecord,
-- set the initial state in after_initialize,
-- turn methods into events
+=== Example
+
+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)
+      after_initialize do
+        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'
-        end
-      end
-      event :confirm_invitation, :invited => :active
     end
 
-This generates the following event methods
-- invite
-- invite!
-- confirm_invitation!
+    user = User.new
+    user.pending?         # => true
+    user.invite           # => true
+    user.invited?         # => true
+    user.activation_code  # => 'SOMEDIGEST'
 
-And the following methods to query the state:
-- pending?
-- invited?
-- active?
+For the invite method this generates the following event methods
+* *invite*              (behaves like ActiveRecord save )
+* *invite!*             (behaves like ActiveRecord save!)
 
 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:
+=== 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 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)
+    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
 
-    class User < ActiveRecord::Base
-       
-      extend SimpleStateMachine::Mountable
-      self.state_machine_definition = MyStateMachine.new self
+    user.confirm_invitation!('INVALID') # => raises ActiveRecord::RecordInvalid,
+                                        #           "Validation failed: Activation code is invalid"
+    user.confirmed?                     # => false
+    user.confirm_invitation!('VALID')
+    user.confirmed?                     # => true
 
-      def after_initialize
-        self.ssm_state ||= 'new'
-      end
-      
+== 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
+
+    def decorator_class
+      SimpleStateMachine::Decorator::Default
+    end
+  end
+
+  class User < ActiveRecord::Base
+
+    extend SimpleStateMachine::Mountable
+    mount_state_machine MyStateMachine
+
+    after_initialize do
+      self.state ||= 'new'
     end
 
+  end
+
 
-== Generating google chart visualizations
+== Transitions
 
-If your using rails you get rake tasks for generating a graphiz google chart of the state machine.
+=== Catching all from states
+If an event should transition from all other defined states, you can use the *:all* state:
+
+  event :suspend, :all => :suspended
+
+
+=== Catching exceptions
+
+You can let the state machine handle exceptions by specifying the failure state for an Error:
+
+  def download_data
+    raise Service::ConnectionError, "Uhoh"
+  end
+  event :download_data, Service::ConnectionError => :download_failed
 
+  download_data               # catches Service::ConnectionError
+  state                       # => "download_failed"
+  state_machine.raised_error  # "Uhoh"
+
+
+=== Default error state
+
+To automatically catch all exceptions 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! }
+
+== 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
+
+== Installation
+
+Use gem install:
+
+  gem install simple_state_machine
+
+Or add it to your Gemfile:
+
+  gem 'simple_state_machine'
 
 == 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 +220,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/lib/simple_state_machine/active_record.rb

@@ -4,71 +4,11 @@ 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
-      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
-              self.send("#{self.class.state_machine_definition.state_method}=", old_state)
-              return false
-            end
-          end
-        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
-          end
-        end
-        @subject.send :alias_method, "#{transition.event_name}!", event_name_and_save_bang
-      end
-    end
-
-    protected
-
-      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.lazy_decorator = lambda { Decorator.new(self) }
+      @state_machine_definition.decorator_class = SimpleStateMachine::Decorator::ActiveRecord
+      @state_machine_definition.subject = self
     end
     @state_machine_definition
   end

data/lib/simple_state_machine/decorator/active_record.rb

@@ -0,0 +1,68 @@
+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|
+              old_state = self.send(self.class.state_machine_definition.state_method)
+              send "#{event_name}_with_managed_state", *args
+              if self.errors.entries.empty? && save
+                true
+              else
+                self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+                false
+              end
+            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|
+              old_state = self.send(self.class.state_machine_definition.state_method)
+              send "#{event_name}_with_managed_state", *args
+              if self.errors.entries.empty?
+                begin
+                  save!
+                rescue ::ActiveRecord::RecordInvalid
+                  self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+                  raise #re raise
+                end
+              else
+                self.send("#{self.class.state_machine_definition.state_method}=", old_state)
+                raise ::ActiveRecord::RecordInvalid.new(self)
+              end
+            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

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