control 0.9.0 → 0.9.1

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/README.md

@@ -0,0 +1,87 @@
+Workflow engine
+
+[![Build Status](https://secure.travis-ci.org/zeto/control.png)](http://travis-ci.org/zeto/control)
+
+Premises
+<ul>
+<li>ActiveRecord</li>
+<li>Each state is a separate object.</li>
+</ul>
+
+Features
+<ul>
+<li>State can be as rich in functionality was wanted.</li>
+<li>No data is ever lost. History is always saved. </li>
+<li>It is possible to track every single transition done in the workflow.</li>
+<li>Advancing a state is as easy as creating a state object and calling "save".</li>
+<li>Can transition to same state.</li>
+<li>Minimal code to define workflow and states.</li>
+</ul>
+
+Simple example for a Bulb with two states:
+
+<pre><code>
+class Bulb &lt; ActiveRecord::Base
+  include Control::Workflow
+  
+  has_many :ons
+  has_many :offs
+end
+
+class On &lt; ActiveRecord::Base
+  include Control::State
+	
+  belongs_to :bulb
+end
+
+class Off &lt; ActiveRecord::Base
+  include Control::State
+
+  belongs_to :bulb
+  next_states :on # optional, to constrain possible next states, can also specify :none to make a state final
+end
+
+def example
+  my_bulb = Bulb.new
+  
+  my_on = On.new do |o|
+    o.bulb = my_bulb
+  end
+  
+  my_off = Off.new do |o|
+    o.bulb = my_bulb
+  end
+  
+  # Check possible states for my bulb. (On, Off)
+  my_bulb.states
+  
+  # Transitions the bulb to the "On" state
+  my_on.save
+  
+  # Transitions the bulb to the "Off" state
+  my_off.save
+  
+  # Every transition is recorded. (On -> Off)
+  my_bulb.transitions
+  
+  # Bulb knows which state is current. (Off)
+  my_bulb.current_state
+end
+</code></pre>
+
+Installing:
+
+1. Add control gem to gemfile.
+<pre><code>gem 'control'</code></pre>
+or
+<pre><code>gem 'control', :git => 'git://github.com/zeto/control.git' # Edge</code></pre>
+
+2. Generate tables (run rake db:migrate after)
+<pre><code>$ rails generate control_install</pre></code>
+
+Testing the gem:
+<pre><code>
+$ bundle
+$ rake
+</pre></code>
+

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rake'
+require 'rake/testtask'
+
+task :default => [:test_units]
+
+desc "Run tests"
+Rake::TestTask.new("test_units") do |t|
+  t.pattern = 'test/lib/control/*_test.rb'
+  t.verbose = true
+  t.warning = false
+end
+
+
+desc "Open an irb session"
+task :console do
+  sh "irb -rubygems -I lib -r control.rb"
+end
+

data/control.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name        = 'control'
+  s.version     = '0.9.1'
+  s.date        = '2012-08-07'
+  s.summary     = "Workflow State Machine"
+  s.description = "State Machine integrated with ActiveRecord"
+  s.authors     = ["Jose Goncalves"]
+  s.email       = 'zetoeu@gmail.com'
+  s.homepage    = 'http://rubygems.org/gems/control'
+  s.files = Dir["**/*"] - Dir["*.gem"] - ["Gemfile.lock"]
+
+  s.require_paths = ["lib"]  
+  s.add_dependency('activerecord','>= 3.0.0')
+  s.add_dependency('activesupport','>= 3.0.0')
+  s.add_development_dependency "sqlite3-ruby"
+  s.add_development_dependency "turn"
+  s.add_development_dependency "debugger"
+  s.add_development_dependency "rake"
+end

data/db/migrate/create_transitions.rb

@@ -0,0 +1,18 @@
+class CreateTransitions < ActiveRecord::Migration
+  def self.up
+    create_table(:transitions) do |t|
+      t.string  :workflow_class
+      t.integer :workflow_id
+      t.string :from_class
+      t.integer :from_id
+      t.string :to_class
+      t.integer :to_id
+      t.timestamps  
+    end      
+  end
+
+  def self.down
+    drop_table :transitions
+  end  
+  
+end

data/db/schema.rb

@@ -0,0 +1,14 @@
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+ActiveRecord::Schema.define(:version => 1) do
+
+  create_table :transitions do |t|
+    t.string  :workflow
+    t.integer :workflow_id
+    t.string :from
+    t.integer :from_id
+    t.string :to
+    t.integer :to_id
+    t.timestamps
+  end
+
+end

data/lib/control/errors.rb

@@ -0,0 +1,19 @@
+module Control
+  class ControlError < StandardError
+  end
+  
+  # Raised when the current state does not allow the transition, defined with next_states
+  class InvalidTransition < ControlError
+  end
+  
+  class WorkflowDisabled < ControlError
+  end
+  
+  # Raised when the state does not reference any workflow with 'belongs_to'
+  class NoAssociationToWorkflow < ControlError
+  end
+  
+  # Raised when the workflow is in a final state and is therefore blocked for any new transition
+  class FinalState < ControlError
+  end  
+end

data/lib/control/state.rb

@@ -0,0 +1,135 @@
+module Control
+  module State
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send :before_save, :validate_transition
+      base.send :after_save, :save_transition
+    end
+  
+    module ClassMethods
+      # Getter/setter for possible next_states
+      # 
+      # @param states state classes in underscore format. Can also use :none to mark state as final
+      # @return [Array<State>] called with no parameters, an array is returned with next possible states
+      def next_states(*states)
+        if states.any?
+          if states.include? :none
+            @final = true
+          else
+            @next_states = states.map{|s| s.to_s.classify}.compact
+          end
+        else
+          if @final                                         # state is final, there are no possible next states
+            Array.new
+          else                                              # state is not final, carry on
+            if @next_states                                 # possible next states were previously declared in class
+              @next_states.map { |s| Kernel.qualified_const_get(s) }
+            else                                            # all states connected to the workflow are valid, no constrains
+              workflow_class.states
+            end
+          end
+        end
+      end           
+      
+      # Checks if class is a state
+      # @return [Boolean] 
+      def is_state?
+        true
+      end
+      
+      # Gets the workflow class associated with the state
+      # @return [Class] workflow class object
+      def workflow_class
+        unless @workflow_class
+          reflect_on_all_associations.each do |a|
+            klass = Kernel.qualified_const_get(a.name.to_s.classify)
+            @workflow_class = klass if klass.respond_to?(:is_workflow?) && klass.is_workflow?
+          end
+        end
+        @workflow_class
+      end
+
+      # Checks if a state is final. There can be no transitions.
+      # @return [Boolean]
+      def final?
+        !!@final
+      end
+    end 
+    
+    # Gets the workflow associated with state
+    # @return workflow object
+    def workflow
+      send self.class.workflow_class.to_s.underscore if self.class.workflow_class
+    end
+    
+    # Get previous state
+    # @return previous state object
+    def previous
+      transition = workflow.transitions.where(:to_class => self.class, :to_id => self.id).first
+      transition.from if transition
+    end
+    
+    # Get the next state
+    # @return next state object
+    def next
+      transition = workflow.transitions.where(:from_class => self.class, :from_id => self.id).first
+      transition.to if transition
+    end
+    
+    private
+    
+    # Validate requirements for transition. Will raise Exceptions if invalid
+    #   - State must be associated with a workflow 
+    #   - Associated workflow must be enabled
+    #   - Either the first state is being saved, or the state being saved is defined in next_states
+    #   - No transition can occur if the state is declared as final
+    def validate_transition
+      raise Control::NoAssociationToWorkflow unless is_part_of_workflow?
+      raise Control::WorkflowDisabled unless workflow.enabled
+      raise Control::InvalidTransition unless workflow_initial_state_or_valid_next_state
+      raise Control::FinalState if current_state_is_final?
+    end
+    
+    # Checks if current state is declared as final
+    # @return [Boolean]
+    def current_state_is_final?
+      workflow.current_state && workflow.current_state.class.final?
+    end
+
+    # Checks if state is part of workflow. Defined with activerecord decorators.
+    # @return [Boolean]
+    def is_part_of_workflow?
+      !!workflow
+    end
+    
+    # Checks if state being saved is defined in next_states of current workflow state.
+    # @return [Boolean]
+    def next_state_is_valid
+      workflow.current_state && ((workflow.current_state.class.next_states && (workflow.current_state.class.next_states.any? && (workflow.current_state.class.next_states.include? self.class))) || workflow.current_state.class.next_states.blank?)
+    end
+    
+    # Checks if state is the first being saved or complies with defined next states
+    # @return [Boolean]
+    def workflow_initial_state_or_valid_next_state
+      !workflow.current_state || next_state_is_valid
+    end
+
+    # Save a transition object
+    # Runs after any successfully saved state, connects the previous and now current state
+    def save_transition
+      transition = Control::Transition.new do |t|
+        t.workflow_class = workflow.class.name
+        t.workflow_id = workflow.id
+        if workflow.current_state
+          t.from_class = workflow.current_state.class.name
+          t.from_id = workflow.current_state.id
+        end
+        t.to_class = self.class.name
+        t.to_id = id
+      end
+      transition.save!             
+    end 
+    
+  end
+end

data/lib/control/transition.rb

@@ -0,0 +1,53 @@
+module Control
+  class Transition < ActiveRecord::Base
+    validates :workflow_class, :presence => true
+    validates :workflow_id, :presence => true
+    validates :to_class, :presence => true
+    validates :to_id, :presence => true
+    validates :from_id, :presence => true, :if => "!from_class.nil?"
+    validate :validate_classes
+    validate :validate_objects
+
+    private    
+
+    # Validate if classes are declared
+    def validate_classes
+      Kernel.qualified_const_get(from_class) unless from_class.blank? rescue errors.add(:from_class,'invalid from')
+      Kernel.qualified_const_get(to_class) rescue errors.add(:to_class,'invalid to')
+      Kernel.qualified_const_get(workflow_class) rescue errors.add(:workflow_class,'invalid workflow')
+    end
+    
+    # Validate if state and workflow objects exist
+    def validate_objects
+    	from rescue errors.add(:workflow,'invalid from')
+    	to rescue errors.add(:to,'invalid to')
+    	workflow rescue errors.add(:workflow,'invalid workflow')
+    end
+
+    public
+    
+    # Pretty print a transition
+    # @return [String] transition description: Workflow, from and to states, date
+    def to_s
+      "Workflow: #{workflow_class} || #{created_at} #{from_class} -> #{to_class}"
+    end
+    
+    # Get workflow
+    # @return workflow object
+    def workflow
+      Kernel.qualified_const_get(workflow_class).find(workflow_id)
+    end
+    
+    # Get destination state for transition
+    # @return state object
+    def to
+      Kernel.qualified_const_get(to_class).find(to_id)
+    end
+    
+    # Get source state for transition
+    # @return state object
+    def from
+      Kernel.qualified_const_get(from_class).find(from_id) unless from_class.blank?
+    end
+  end  
+end

data/lib/control/workflow.rb

@@ -0,0 +1,52 @@
+module Control
+  module Workflow    
+    
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    
+    module ClassMethods
+      # Checks if class is a workflow
+      def is_workflow?
+        true
+      end
+      
+      # Get all state classes associated to this workflow
+      # @return [Array<Class>]
+      def states
+        reflect_on_all_associations.each.map do |a|
+          klass = Kernel.qualified_const_get(a.class_name.to_s.classify)
+          if klass.respond_to?(:is_state?) and klass.is_state?
+            klass
+          end
+        end
+      end
+    end
+    
+    # Checks if workflow is enabled
+    # @return [Boolean]
+    def enabled
+      true
+    end
+
+    # Get all state classes associated to this workflow
+    # @return [Array<Class>]
+    def states
+      self.class.states
+    end
+
+    # Get all transitions.
+    # @return [Array<Transition>]
+    def transitions
+      Control::Transition.where(:workflow_class => self.class.name, :workflow_id => self.id)
+    end
+    
+    alias :history :transitions
+    
+    # Get workflow current state
+    # @return the state object
+    def current_state
+      transitions.last.to if transitions.last
+    end 
+  end
+end

data/lib/generators/control_install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Installs control by coping and executing the Transition migration
+
+Example:
+    rails generate control_install
+
+    This will create:
+        db/migrate/%Y%m%d%H%M%Screate_transitions.rb

data/lib/generators/control_install/control_install_generator.rb

@@ -0,0 +1,22 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class ControlInstallGenerator < Rails::Generators::Base
+
+  include Rails::Generators::Migration
+  source_root File.expand_path('../../../../', __FILE__)
+  
+  def self.next_migration_number(path)
+    Time.now.utc.strftime("%Y%m%d%H%M%S")
+  end  
+  
+  def migration
+    unless transitions_table_exists? # SOURCE -> DESTINATION
+      migration_template "db/migrate/create_transitions.rb", "db/migrate/create_transitions.rb"
+    end
+  end  
+  
+  def transitions_table_exists?
+    ActiveRecord::Base.connection.table_exists?(:transitions)
+  end  
+end