state_shifter 0.8.1 → 1.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 560af59d82afed84d4b51b47e7c5f2487acc86f4
+  data.tar.gz: 0f6b9926727a1543f9c11a0f1b50ffd6dcb7bafb
+SHA512:
+  metadata.gz: 440824ce9be500d3ea26b8373916d020aad8c423a418fc6b491338e1681a8fcb11e46cffb2e8c27e85b2aef4b50624476131fb259392bb14ed2b2b7768e43e2d
+  data.tar.gz: dafc299c8726b62b3f55d832cec3eb9be8f38f475330727dd6ac960147a00ece293a7ef5f511282d96b1fff5135816fe5ba73c12fe4740701e894e3815650a06

data/Gemfile

@@ -1,19 +1,17 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem 'activerecord', '~> 3.2.x'
-  gem 'sqlite3'
-  gem 'rspec-nc'
-  gem "rspec", "~> 2.9.0"
+  gem 'activerecord', '~> 4.0.9'
+  gem 'sqlite3', '~> 1.3.10'
+  gem "rspec"
   gem "yard", "~> 0.7"
-  gem 'redcarpet' 
-  gem "rdoc", "~> 3.12"
-  gem "bundler", "~> 1.1.0"
+  gem 'redcarpet', '>= 3.2.3'
+  gem "rdoc", "~> 4.0"
+  gem "bundler"
   gem "jeweler", "~> 1.8.4"
   gem "simplecov", ">= 0"
+  gem 'pry'
+  gem 'ruby-graphviz'
+  gem 'json', ">= 1.8.2"
+  gem 'i18n', '>= 0.6.6'
 end

data/Gemfile.lock

@@ -1,64 +1,110 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activemodel (3.2.8)
-      activesupport (= 3.2.8)
-      builder (~> 3.0.0)
-    activerecord (3.2.8)
-      activemodel (= 3.2.8)
-      activesupport (= 3.2.8)
-      arel (~> 3.0.2)
-      tzinfo (~> 0.3.29)
-    activesupport (3.2.8)
-      i18n (~> 0.6)
-      multi_json (~> 1.0)
-    arel (3.0.2)
-    builder (3.0.0)
-    diff-lcs (1.1.3)
-    git (1.2.5)
-    i18n (0.6.0)
-    jeweler (1.8.4)
+    activemodel (4.0.13)
+      activesupport (= 4.0.13)
+      builder (~> 3.1.0)
+    activerecord (4.0.13)
+      activemodel (= 4.0.13)
+      activerecord-deprecated_finders (~> 1.0.2)
+      activesupport (= 4.0.13)
+      arel (~> 4.0.0)
+    activerecord-deprecated_finders (1.0.4)
+    activesupport (4.0.13)
+      i18n (~> 0.6, >= 0.6.9)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    addressable (2.3.8)
+    arel (4.0.2)
+    builder (3.1.4)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    faraday (0.8.9)
+      multipart-post (~> 1.2.0)
+    git (1.2.9.1)
+    github_api (0.10.1)
+      addressable
+      faraday (~> 0.8.1)
+      hashie (>= 1.2)
+      multi_json (~> 1.4)
+      nokogiri (~> 1.5.2)
+      oauth2
+    hashie (3.4.1)
+    highline (1.7.1)
+    i18n (0.7.0)
+    jeweler (1.8.8)
+      builder
       bundler (~> 1.0)
       git (>= 1.2.5)
+      github_api (= 0.10.1)
+      highline (>= 1.6.15)
+      nokogiri (= 1.5.10)
       rake
       rdoc
-    json (1.7.5)
-    multi_json (1.3.6)
-    rake (0.9.2.2)
-    rdoc (3.12)
-      json (~> 1.4)
-    redcarpet (2.1.1)
-    rspec (2.9.0)
-      rspec-core (~> 2.9.0)
-      rspec-expectations (~> 2.9.0)
-      rspec-mocks (~> 2.9.0)
-    rspec-core (2.9.0)
-    rspec-expectations (2.9.1)
-      diff-lcs (~> 1.1.3)
-    rspec-mocks (2.9.0)
-    rspec-nc (0.0.4)
-      rspec (~> 2.9)
-      terminal-notifier (~> 1.4.2)
-    simplecov (0.6.4)
+    json (1.8.2)
+    jwt (1.4.1)
+    method_source (0.8.2)
+    minitest (4.7.5)
+    multi_json (1.11.0)
+    multi_xml (0.5.5)
+    multipart-post (1.2.0)
+    nokogiri (1.5.10)
+    oauth2 (1.0.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rack (1.6.0)
+    rake (10.4.2)
+    rdoc (4.2.0)
+    redcarpet (3.2.3)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    ruby-graphviz (1.2.1)
+    simplecov (0.9.2)
+      docile (~> 1.1.0)
       multi_json (~> 1.0)
-      simplecov-html (~> 0.5.3)
-    simplecov-html (0.5.3)
-    sqlite3 (1.3.6)
-    terminal-notifier (1.4.2)
-    tzinfo (0.3.33)
-    yard (0.8.2.1)
+      simplecov-html (~> 0.9.0)
+    simplecov-html (0.9.0)
+    slop (3.6.0)
+    sqlite3 (1.3.10)
+    thread_safe (0.3.5)
+    tzinfo (0.3.43)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activerecord (~> 3.2.x)
-  bundler (~> 1.1.0)
+  activerecord (~> 4.0.9)
+  bundler
+  i18n (>= 0.6.6)
   jeweler (~> 1.8.4)
-  rdoc (~> 3.12)
-  redcarpet
-  rspec (~> 2.9.0)
-  rspec-nc
+  json (>= 1.8.2)
+  pry
+  rdoc (~> 4.0)
+  redcarpet (>= 3.2.3)
+  rspec
+  ruby-graphviz
   simplecov
-  sqlite3
+  sqlite3 (~> 1.3.10)
   yard (~> 0.7)

data/README.md

@@ -1,11 +1,172 @@
 state\_shifter
 ==============
 
-Description goes here.
+This gem makes it easy to incorporate state machine behavior in a Ruby class.
+
+Features include:
+
+* on\_entry and on\_transition handlees
+* ActiveRecord integration
+* event guards and easy event handlers
+* graphViz visualization creator
+* flexible machine syntax
+
+Usage
+-----
+
+An example of state machine definition possible with this gem:
+
+```ruby
+class Simple
+  include StateShifter::Definition
+
+  state_machine do
+
+    # first state to be defined is the initial one
+    state :new do
+      event :submit => :awaiting_review
+    end
+
+    state :awaiting_review do
+      event :review => :being_reviewed
+    end
+
+    state :being_reviewed do
+      event :accept => :accepted, :if => :cool_article?
+      event :reject => :rejected, :if => :bad_article?
+    end
+
+    state :accepted
+    state :rejected
+
+  end
+
+  def cool_article?
+    true
+  end
+
+  def bad_article?
+    false
+  end
+
+end
+```
+
+Basically, you need to have a ```state_machine``` block with a collection of states and events. The initial state is the first one on the definition, and events are in the form of ```event :event_name => :next_state_name```. Events can have guards, and also refer back to the same state, in which case you simple omit the ```next_state_name``` - mostly to have "touch-and-go" events that just execute a method specified in the ```:call``` option passed to it, and remain in the same state. The next example shows relevant usage of it.
+
+```ruby
+class Advanced
+  include StateShifter::Definition
+
+  ###
+
+  state_machine do
+
+    state :initialized do
+
+      event :start_date_changed, :call => :handle_start_date_changed
+      event :forced_start => :running
+      event :start_date_reached => :running, :if => :start_date_reached?
+      event :abort_initialized_contest => :finalized
+    end
+
+    state :running do
+
+      on_entry do |previous_state, trigger_event|
+        running_entry previous_state, trigger_event
+      end
+
+      event :abort_running_contest => :notify_stakeholders
+      event :deadline_reached => :notify_organizers, :if => :entries_deadline_reached?
+      event :spots_filled  => :notify_organizers, :if => :spots_filled?
+      event :deadline_reached_without_approvals  => :notify_pending_users, :if => :entries_deadline_reached_without_approvals?
+      event :deadline_reached_without_entries => :finalized, :if => :entries_deadline_reached_without_entries?
+    end
+
+    state :notify_organizers do
+      on_entry :send_notification_to_organizers
+      event :organizers_notified => :awaiting_organizer_reply
+    end
+
+    state :awaiting_organizer_reply do
+      event :organizer_confirmation_missing => :notify_stakeholders, :if => :organizer_confirmation_deadline_reached?
+      event :organizer_confirmation_received => :notify_approved_users
+      event :organizer_has_more_tickets  => :running
+    end
+
+    state :notify_stakeholders do
+      on_entry :send_notification, :stakeholders, :organizers
+      event :stakeholders_notified => :cancelled
+    end
+
+    state :cancelled
+
+    state :notify_pending_users do
+      on_entry :send_notification, :pending_users
+      event :pending_users_notified => :finalized
+    end
+
+    state :notify_approved_users do
+      on_entry :send_notification_to_approved_users
+      event :approved_users_notified => :send_list_to_organizers
+     end
+
+    state :send_list_to_organizers do
+      on_entry :send_guestlist_to_organizers
+      event :list_sent_to_organizers => :awaiting_attendance
+    end
+
+    state :awaiting_attendance do
+      event :remind_to_fill_in_report => :create_report_filling_requests
+    end
+
+    state :create_report_filling_requests do
+      on_entry :send_report_filling_requests
+      event :finalize => :finalized
+    end
+
+    state :finalized
+
+    on_transition do |from,to,trigger_event, duration|
+      benchmark from, to, trigger_event, duration
+    end
+  end
+
+  ###
+
+  def send_notification to
+    #
+  end
+
+  def entries_deadline_reached?
+    true
+  end
+
+  def running_entry previous_state, trigger_event
+    #
+  end
+
+  def benchmark from, to, trigger_event, duration
+    #
+  end
+
+end
+```
+
+Plagiarism alert
+----------------
+
+This gem draws _heavy_ inspiration from both [pluginaweek's state_machine](https://github.com/pluginaweek/state_machine) and [mdh's ssm](https://github.com/mdh/ssm) gems. I liked both of them, but the DSL syntax was not 100% to my liking. Kudos to them.
+
+Future
+------
+
+I want to add "mountable" state machines as per ssm's gem, to have a clear separation which would ease testing, but haven't had the chance yet.
+
 
 Contributing to state\_shifter
 ------------------------------
- 
+
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
 * Fork the project.
@@ -19,4 +180,3 @@ Copyright
 
 Copyright (c) 2012 Bruno Antunes. See LICENSE.txt for
 further details.
-

data/VERSION

@@ -1 +1 @@
-0.8.1
+1.0.3

data/examples/advanced.rb

@@ -1,16 +1,22 @@
 class Advanced
   include StateShifter::Definition
 
-  ### 
+  ###
 
   state_machine do
 
     state :initialized do
-
       event :start_date_changed, :call => :handle_start_date_changed
       event :forced_start => :running
       event :start_date_reached => :running, :if => :start_date_reached?
       event :abort_initialized_contest => :finalized
+      event :event_associated => :preparing
+    end
+
+    state :preparing do
+      on_entry :prepare
+
+      event :all_done => :running
     end
 
     state :running do
@@ -19,7 +25,7 @@ class Advanced
         running_entry previous_state, trigger_event
       end
 
-      event :abort_running_contest => :notify_stakeholders 
+      event :abort_running_contest => :notify_stakeholders
       event :changed_properties
       event :keep_users_engaged
       event :deadline_reached => :notify_organizers, :if => :entries_deadline_reached?
@@ -30,6 +36,7 @@ class Advanced
 
     state :notify_organizers do
       on_entry :send_notification_to_organizers
+
       event :organizers_notified => :awaiting_organizer_reply
     end
 
@@ -42,6 +49,7 @@ class Advanced
 
     state :notify_stakeholders do
       on_entry :send_notification, :stakeholders, :organizers
+
       event :stakeholders_notified => :cancelled
     end
 
@@ -80,6 +88,10 @@ class Advanced
 
   ###
 
+  def prepare
+    all_done!
+  end
+
   def send_notification to
     #
   end

data/examples/review.rb

@@ -1,18 +1,21 @@
 class Review < ActiveRecord::Base
   include StateShifter::Definition
 
-  state_machine do 
+  state_machine do
 
     # first state to be defined is the initial one
     state :new do
+      tags :reviewable
       event :submit => :awaiting_review
     end
 
     state :awaiting_review do
+      tags :reviewable, :processing
       event :review => :being_reviewed
     end
 
     state :being_reviewed do
+      tags :reviewable, :processing
       event :accept => :accepted, :if => :cool_article?
       event :reject => :rejected, :if => :bad_article?
     end

data/lib/state_shifter/definition/active_record_integration_methods.rb

@@ -2,7 +2,21 @@ module StateShifter
   module Definition
     module ActiveRecordIntegrationMethods
 
-      class ::StateShifter::Definition::StatePersistenceAttributeNotPresent < RuntimeError; end 
+      class ::StateShifter::Definition::StatePersistenceAttributeNotPresent < RuntimeError; end
+
+      def self.include_state_scopes(base)
+        base.state_machine_definition.states.each do |name, definition|
+          base.class_eval do
+            scope name, -> { where(persist_attr_name => name) } unless respond_to?(name)
+          end
+        end
+
+        base.state_machine_definition.state_tags.each do |name, states|
+          base.class_eval do
+            scope name, -> { where(persist_attr_name => states) } unless respond_to?(name)
+          end
+        end
+      end
 
       def check_attr_presence
         raise StatePersistenceAttributeNotPresent unless self.attribute_names.include? self.class.persist_attr_name.to_s

data/lib/state_shifter/definition/class_methods.rb

@@ -2,86 +2,106 @@ module StateShifter
   module Definition
     module ClassMethods
 
-      attr_accessor :state_machine_definition, :persist_attr_name
+      attr_accessor :state_machine_definition, :persist_attr_name, :_include_state_scopes
 
       def persist_attribute attr_name
-        raise ::StateShifter::PersistenceAttributeAlreadyDefined if @persist_attr_name
+        raise PersistenceAttributeAlreadyDefined if @persist_attr_name
         @persist_attr_name = attr_name.to_sym
       end
 
       def state_machine &definition
         @persist_attr_name ||= :current_state
         @state_machine_definition = Contents.new(&definition)
-        
-        @state_machine_definition.states.each do |state_name, state_definition|
-          
-          module_eval do
 
-            define_method "_next_states" do |from_state, *options|
-              options = options.first || {}
-              next_states_hash   = {}
-              check_guards  = options.has_key?(:check_guards)
+        @state_machine_definition.states.each { |name, definition| _load_state(name, definition) }
+        @state_machine_definition.state_tags.each { |tag, states|  _load_tag(tag, states) }
+        ActiveRecordIntegrationMethods.include_state_scopes(self) if _include_state_scopes
+      end
 
-              state_machine_definition.get(:state, from_state).events.each do |event_name, event_def|
-                if event_def.has_guards? && check_guards
-                  next if self.send(:check_guards, event_name).is_a?(Array)
-                end
+      private
+
+      def _load_state(state_name, state_definition)
+        module_eval do
+
+          define_method "_next_states" do |from_state, *options|
+            options = options.first || {}
+            next_states_hash   = {}
+            check_guards  = options.has_key?(:check_guards)
 
-                next_states_hash.merge!( event_def.to.nil? ? { from_state.to_sym => event_name } : { event_def.to => event_def.name } )
+            state_machine_definition.get(:state, from_state).events.each do |event_name, event_def|
+              if event_def.has_guards? && check_guards
+                next if self.send(:check_guards, event_name).is_a?(Array)
               end
 
-              next_states_hash.keys.uniq.sort
+              next_states_hash.merge!( event_def.to.nil? ? { from_state.to_sym => event_name } : { event_def.to => event_def.name } )
             end
 
-            define_method "#{state_name}?" do
-              current_state == state_name
-            end
+            next_states_hash.keys.uniq.sort
+          end
 
-            state_machine_definition.events.each do |event_name, event_definition|
+          define_method "#{state_name}?" do
+            current_state.to_sym == state_name
+          end
 
-              define_method "can_#{event_name}?" do
-              
-                this_event = state_machine_definition.get(:event, event_name)
-                
-                current_state.to_sym == this_event.from.to_sym && !check_guards(event_name).is_a?(Array) 
-              
-              end
+          state_machine_definition.events.each do |event_name, event_definition|
 
-              define_method "#{event_name}!" do
+            define_method "can_#{event_name}?" do
 
-                self.send event_name.to_sym, true
-              
-              end
+              this_event = state_machine_definition.get(:event, event_name)
 
-              define_method "#{event_name}" do |bang=false|
+              current_state.to_sym == this_event.from.to_sym && !check_guards(event_name).is_a?(Array)
 
-                if current_state != event_definition.from
-                  if bang  
-                    halt("you cannot transition from #{current_state} via #{event_name}")
-                  else
-                    return false
-                  end
-                end
-                
-                if (failed_guards = check_guards(event_name)).is_a?(Array)
-                  if bang
-                    failed_guards.delete_at(0)
-                    raise ::StateShifter::GuardNotSatisfied, "#{failed_guards.join}"
-                  else 
-                    return false
-                  end
+            end
+
+            define_method "#{event_name}!" do
+
+              self.send event_name.to_sym, true
+
+            end
+
+            define_method "#{event_name}" do |bang=false|
+
+              if current_state.to_sym != event_definition.from.to_sym
+                if bang
+                  halt("you cannot transition from #{current_state} via #{event_name}")
+                else
+                  return false
                 end
+              end
 
-                transition :to => ( event_definition.to.nil? ? current_state : event_definition.to ), :trigger => ( bang ? "#{event_name}!" : event_name )
-               
+              if (failed_guards = check_guards(event_name)).is_a?(Array)
+                if bang
+                  failed_guards.delete_at(0)
+                  raise GuardNotSatisfied, "#{failed_guards.join}"
+                else
+                  return false
+                end
               end
 
+              transition :to => ( event_definition.to.nil? ? current_state : event_definition.to ), :trigger => ( bang ? "#{event_name}!" : event_name )
+
             end
 
           end
+
         end
-      end
 
+        def _load_tag(tag, states)
+          module_eval do
+
+            define_singleton_method "#{tag}_states" do
+              states
+            end
+
+            define_method "#{tag}?" do
+              states.map(&:to_s).include? current_state.to_s
+            end
+
+          end
+
+        end
+
+      end
     end
   end
 end