simple_state_machine 0.5.2 → 0.6.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4cf708bed33ca00037b1fbb2562b2a4c351666d82a4555b84078600b9e90ad03
+  data.tar.gz: 251e24c03f5c59313aec334045670ed024c2720630c188d17bfed1eced1827be
+SHA512:
+  metadata.gz: 482b1ba0a9e91260dfe56153453b636640dcd7c37916fd692e13d8607f59ee141d7161c9db6e9a50cdbb14b21b2895227129edf1c4f35dbcb733caceafeb8beb
+  data.tar.gz: 5c3b05eb49e792a4289e85c5be1f10f9239020a0147e0ab5b617bba58d7fac4b727a47f45564c472e25e4079e8d1fb7d52838f9a8af9dd610a90e2580d6a9132

data/.github/workflows/build.yml

@@ -0,0 +1,46 @@
+name: Build
+on:
+  - push
+  - pull_request
+
+jobs:
+  build:
+    name: Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - "3.0"
+          - "2.7"
+          - "2.6"
+          - "2.5"
+        rails:
+          - "5.2"
+          - "6.0"
+          - "6.1"
+          - main
+        exclude:
+          - ruby: 2.5
+            rails: main
+          - ruby: 2.6
+            rails: main
+          - ruby: 3.0
+            rails: "5.1"
+          - ruby: 3.0
+            rails: "5.2"
+
+    runs-on: 'ubuntu-latest'
+
+    env:
+      BUNDLE_GEMFILE: gemfiles/Gemfile.activerecord-${{ matrix.rails }}.x
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Setup project
+        run: bundle install
+      - name: Run test
+        run: bundle exec rspec spec

data/.gitignore

@@ -1 +1,4 @@
 *.swp
+.bundle
+.ruby-version
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+rvm:
+  - 2.5
+  - 2.7
+  - 3.0
+  - jruby-9.2.16.0
+script: bundle exec rspec spec
+
+gemfile:
+  - gemfiles/Gemfile.activerecord-6.0.x
+  - gemfiles/Gemfile.activerecord-6.1.x
+  - gemfiles/Gemfile.basic
+
+matrix:
+  exclude:
+    - rvm: jruby
+      gemfile: gemfiles/Gemfile.activerecord-4.2.x

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/Gemfile

@@ -2,3 +2,10 @@
 source "http://rubygems.org"
 
 gemspec
+
+group :test do
+  gem "rspec", "~> 3.0"
+  gem "activerecord", ">= 5.2.0"
+  gem "sqlite3", :platform => [:ruby, :mswin, :mingw]
+  gem "activerecord-jdbcsqlite3-adapter", :platform => :jruby
+end

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,119 +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!
-- 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  (behave 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
@@ -166,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/examples/conversation.rb

@@ -2,19 +2,19 @@
 #
 # class Conversation
 #   include AASM
-# 
+#
 #   aasm_column :current_state # defaults to aasm_state
-# 
+#
 #   aasm_initial_state :unread
-# 
+#
 #   aasm_state :unread
 #   aasm_state :read
 #   aasm_state :closed
-# 
+#
 #   aasm_event :view do
 #     transitions :to => :read, :from => [:unread]
 #   end
-# 
+#
 #   aasm_event :close do
 #     transitions :to => :closed, :from => [:read, :unread]
 #   end

data/examples/lamp.rb

@@ -1,21 +1,21 @@
 class Lamp
-      
+
   extend SimpleStateMachine
 
   def initialize
     self.state = 'off'
   end
-  
+
   def push_button1
     puts "click1: #{state}"
   end
-  event :push_button1, :off => :on, 
+  event :push_button1, :off => :on,
                        :on  => :off
-  
+
   def push_button2
     puts "click2: #{state}"
   end
   event :push_button2, :off => :on,
                        :on  => :off
 
-end
+end

data/examples/relationship.rb

@@ -2,23 +2,23 @@
 #
 # class Relationship
 #   include AASM
-# 
+#
 #   aasm_column :status
-# 
+#
 #   aasm_initial_state Proc.new { |relationship| relationship.strictly_for_fun? ? :intimate : :dating }
-# 
+#
 #   aasm_state :dating,   :enter => :make_happy,        :exit => :make_depressed
 #   aasm_state :intimate, :enter => :make_very_happy,   :exit => :never_speak_again
 #   aasm_state :married,  :enter => :give_up_intimacy,  :exit => :buy_exotic_car_and_wear_a_combover
-# 
+#
 #   aasm_event :get_intimate do
 #     transitions :to => :intimate, :from => [:dating], :guard => :drunk?
 #   end
-# 
+#
 #   aasm_event :get_married do
 #     transitions :to => :married, :from => [:dating, :intimate], :guard => :willing_to_give_up_manhood?
 #   end
-# 
+#
 #   def strictly_for_fun?; end
 #   def drunk?; end
 #   def willing_to_give_up_manhood?; end
@@ -32,7 +32,7 @@
 
 class Relationship
   extend SimpleStateMachine
-  
+
   def initialize
     self.state = relationship.strictly_for_fun? ? get_intimate : start_dating
   end
@@ -84,4 +84,4 @@ class Relationship
   def never_speak_again; end
   def give_up_intimacy; end
   def buy_exotic_car_and_wear_a_combover; end
-end
+end

data/examples/traffic_light.rb

@@ -1,7 +1,7 @@
 class TrafficLight
-  
+
   extend SimpleStateMachine
-  
+
   def initialize
     self.state = 'green'
   end
@@ -14,4 +14,4 @@ class TrafficLight
   event :change_state, :green  => :orange,
                        :orange => :red,
                        :red    => :green
-end
+end

data/examples/user.rb

@@ -1,12 +1,16 @@
 require 'digest/sha1'
 class User < ActiveRecord::Base
-  
+
   validates_presence_of :name
-  
+
   extend SimpleStateMachine::ActiveRecord
 
+  after_initialize :after_initialize
   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 +27,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/gemfiles/Gemfile.activerecord-5.2.x

@@ -0,0 +1,9 @@
+# A sample Gemfile
+source "http://rubygems.org"
+
+group :test do
+  gem "rspec"
+  gem "activerecord", "~>5.2.0"
+  gem "sqlite3", :platform => [:ruby, :mswin, :mingw]
+  gem "activerecord-jdbcsqlite3-adapter", :platform => :jruby
+end

data/gemfiles/Gemfile.activerecord-6.0.x

@@ -0,0 +1,9 @@
+# A sample Gemfile
+source "http://rubygems.org"
+
+group :test do
+  gem "rspec"
+  gem "activerecord", "~>6.0.0"
+  gem "sqlite3", :platform => [:ruby, :mswin, :mingw]
+  gem "activerecord-jdbcsqlite3-adapter", :platform => :jruby
+end

data/gemfiles/Gemfile.activerecord-6.1.x

@@ -0,0 +1,8 @@
+# A sample Gemfile
+source "http://rubygems.org"
+
+group :test do
+  gem "rspec"
+  gem "activerecord", "~>6.1.0"
+  gem "sqlite3", :platform => [:ruby, :mswin, :mingw]
+end

data/gemfiles/Gemfile.activerecord-main.x

@@ -0,0 +1,9 @@
+# A sample Gemfile
+source "http://rubygems.org"
+
+group :test do
+  gem "rspec"
+  gem "activerecord", git: "https://github.com/rails/rails.git", branch: "main"
+  gem "sqlite3", :platform => [:ruby, :mswin, :mingw]
+  gem "activerecord-jdbcsqlite3-adapter", :platform => :jruby
+end

data/gemfiles/Gemfile.basic

@@ -0,0 +1,6 @@
+# A sample Gemfile
+source "http://rubygems.org"
+
+group :test do
+  gem "rspec"
+end