flowchart 0.0.1

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Shuddhashil Ray(rayshuddhashil@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,158 @@
+= FlowChart
+  
+  - Flowchart is a rubygem for State Machine(state-action-transition) workflow.
+  - Flowchart works out of the box both for ActiveRecord and Non-ActiveRecord Models.
+  - It provides an easy DSL to create a state machine flow for your model's object.
+
+== INSTALLATION
+
+  gem install flowchart
+
+  # No other gem dependencies! Tested on Ruby 1.8.7 and Ruby 1.9.3
+
+== SYNTAX & OPTIONS
+
+  flowchart do
+    init_flowstate :init
+
+    flowstate :init do
+      preprocess Proc.new { |o| p "blah blah" }
+      postprocess :some_method
+    end
+
+    flowstate :uploaded do
+        preprocess Proc.new  :do_something
+        postprocess Proc.new  { |o| p "File has been uploaded" }
+    end
+
+    action :upload do
+      transitions :from => :init, :to => :uploaded, :condition => :file_parsable?
+    end
+  end
+
+  # OPTIONS
+    1. By Default flowchart assumes that the model attribute it works on is "process_status. If you want to override it then :
+    flowchart do
+      state_column :some_other_column
+      .....
+    end
+
+    2. Every flowstate can have options preprocess and postprocess blocks. You can mention any instance methods or Procs/lamdas to execute.
+
+    3. In Actions you can mention :condition with evaluate truth or falsity based on which the transition action(:from -> :to) is possible or not is determined. If :condition is not given transition is always evaluated to truth.
+
+    4. In Actions you can also mention :branch, when you have multiple :to states from one single :from state then you can mention a ":branch" condition which you can execute and determine which branch state will be the next! Useful in decision trees.
+
+  # Methods
+
+    1. obj.{state_name}? returns boolean true/false if object is in that that state
+
+    2. obj.{action} returns the transtion to next state on executing the action
+
+    3. obj.{action}! returns the transition to next state on executing the action and save after call
+
+    4. obj.current_state returns the current_state of the object
+
+    5. obj.flowprocessor returns the complete tree of flowchart for the object!
+
+
+
+== Sample Use
+
+  # Example of a Non-ActiveRecord Class using FlowChart in Ruby
+  # in irb console
+
+  class SampleOne
+    include FlowChart
+    attr_accessor :process_status
+
+    flowchart do
+      init_flowstate :init
+
+      flowstate :init do
+        preprocess Proc.new { |o| p "Initializing File" }
+        postprocess :notify_user
+      end
+
+      flowstate :uploaded do
+        preprocess Proc.new  { |o| p "Validating File" }
+        postprocess Proc.new  { |o| p "File has been uploaded in system" }
+      end
+
+      flowstate :open do
+        postprocess :notify_user
+        postprocess Proc.new  { |o| p "File has been closed" }
+      end
+
+      flowstate :closed do
+        preprocess Proc.new  { |o| p "File closed" }
+        postprocess :notify_user
+      end
+
+      action :upload do
+        transitions :from => :init, :to => :uploaded, :condition => :file_parsable?
+      end
+
+      action :process do
+        transitions :from => :uploaded, :to => [:open, :closed], :branch => :choose_branch
+      end
+
+      action :close do
+        transitions :from => [:init,:uploaded,:open], :to => :closed, :condition => :file_close?
+      end
+
+    end
+
+    def choose_branch
+      6 > 5 ? :open : :closed
+    end
+
+    def notify_user
+      p "Notifying User!"
+    end
+
+    def file_parsable?
+      3 > 2 ? true : false
+    end
+
+    def file_close?
+      1 > 0 ? true : false 
+    end
+  end
+
+  t=SampleOne.new
+    #<SampleOne:0x9a3d500>
+
+  t.current_state
+    #<FlowChart::State:0x9a3ff1c @flowstatename=:init, @before_and_after_works={:preprocess=>#<Proc:0x09a41880@(irb):11>, :postprocess=>:notify_user}>
+
+  t.upload
+    "Notifying User!"
+    "Validating File"
+    true
+
+  t.current_state
+    #<FlowChart::State:0x9a3fe18 @flowstatename=:uploaded, @before_and_after_works={:preprocess=>#<Proc:0x09a415ec@(irb):16>, :postprocess=>#<Proc:0x09a414c0@(irb):17>}>
+
+  t.process
+    "File has been uploaded in system"
+
+  t.current_state
+    #<FlowChart::State:0x9a3fd00 @flowstatename=:open, @before_and_after_works={:postprocess=>#<Proc:0x09a41240@(irb):22>}>
+
+  t.closed?
+    false
+
+  t.open?
+    true
+
+  t.close
+    "File closed"
+    true
+
+  t.current_state
+     #<FlowChart::State:0x9a3fbfc @flowstatename=:closed, @before_and_after_works={:preprocess=>#<Proc:0x09a41024@(irb):26>, :postprocess=>:notify_user}>
+
+== Save! in ActiveRecord Model
+
+For any action if you choose to follow it up with a '!' then the model object is saved after action call. Similarly for an action if you choose to not follow it up with a '!' it will only update the attributes for the model object

data/flowchart.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |f|
+  f.name          = 'flowchart'
+  f.version       = '0.0.1'
+  f.date          = %q{2013-09-27}
+  f.summary       = %q{State Machine and State Flow for Ruby}
+  f.description   = %q{Flowchart is a State Machine(state-action-transition) workflow for Non-ActiveRecord and ActiveRecord Model in Ruby or Rails}
+  f.authors       = %q{Shuddhashil Ray}
+  f.email         = %q{rayshuddhashil@gmail.com}
+  f.files         = ["README.rdoc","LICENSE.txt","flowchart.gemspec","lib/flow_chart.rb","lib/flowchart/flow_processor.rb","sample/sample_one.rb"]
+  f.require_paths = ["lib"]
+  f.homepage      = %q{http://github.com/raycoding/flowchart}
+  f.license       = "MIT"
+end

data/lib/flow_chart.rb

@@ -0,0 +1,71 @@
+require 'flowchart/flow_processor'
+module FlowChart
+  def self.included(base)
+    base.extend ClassMethods
+    base.send :include, InstanceMethods
+  end
+
+  module ClassMethods
+    attr_reader :flowprocessor
+    
+    def flowchart(&block)
+      @flowprocessor = FlowChart::FlowProcessor.new(&block)
+      @flowprocessor.flowstates.values.each do |flowstate|
+        flowstate_name = flowstate.flowstatename
+        # Helper Methods to verify is this is the current_state, example object.uploaded? , object.closed? etc 
+        define_method "#{flowstate_name}?" do
+          flowstate_name == current_state.flowstatename
+        end
+      end
+      
+      #Driver Instance Methods for each evet for triggering the action action!
+      @flowprocessor.actions.keys.each do |key|
+        define_method "#{key}" do
+          process_action(key,:save_object=>false)
+        end
+        
+        define_method "#{key}!" do
+          process_action(key,:save_object=>true)
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+    attr_accessor :previous_state
+
+    def flowprocessor
+      self.class.flowprocessor
+    end
+
+    def current_state 
+      if (flowprocessor.state_column.to_sym.nil? or send(flowprocessor.state_column.to_sym).nil? or send(flowprocessor.state_column.to_sym)=="")
+        @current_state ||=  flowprocessor.flowstates[flowprocessor.starting_flowstate.flowstatename]
+      else
+        @current_state ||= flowprocessor.flowstates[send(flowprocessor.state_column.to_sym).to_sym]
+      end
+      @current_state
+    end
+    
+    def set_current_state(new_state, options = {})
+      send("#{flowprocessor.state_column}=".to_sym, new_state.flowstatename.to_s)
+      @current_state = new_state
+      send("#{flowprocessor.state_column.to_s}=".to_sym,"#{current_state.flowstatename.to_s.to_s}") #Updates the instance variable
+      # If asked to save action with bang! and if inherits from ActiveRecord in Rails then do save!
+      ## Important check to support both Non-ActiveRecord Models in Ruby and ActiveRecord Models in Rails
+      if options[:save_object] and !(defined?(ActiveRecord::Base).nil?) and self.class.ancestors.include? ActiveRecord::Base 
+        self.save
+      end
+    end
+    
+    private
+    def process_action(action_name,options_for_action = {})
+      action = flowprocessor.actions[action_name.to_sym]
+      if action.nil?
+        p "Error: #{action_name} not found!"
+        raise FlowChart::InvalidState.new("Error: #{action_name} not found!")
+      end
+      action.process_action!(self,current_state,options_for_action)
+    end
+  end
+end

data/lib/flowchart/flow_processor.rb

@@ -0,0 +1,164 @@
+module FlowChart
+  class InvalidTransition < NoMethodError; end
+  class InvalidState < NoMethodError; end
+  class InvalidAction < NoMethodError; end
+
+  # Driver for States in FlowChart
+  class State
+    attr_accessor :flowstatename, :before_and_after_works
+    
+    def initialize(flowstatename, &flowblock)
+      @flowstatename,@before_and_after_works = flowstatename,Hash.new
+      instance_eval(&flowblock) if block_given?
+    end
+    
+    ## Optional in State flow
+    ##Preprocess Things-To-Do before entering this state => Usecase Notifications
+    ## Takes a proc or instance method as block
+    def preprocess(method = nil, &block)
+      @before_and_after_works[:preprocess] = method.nil? ? block : method
+    end
+
+    ## Optional in State flow
+    #PostProcess Things-To-Do before entering this state => Usecase Notifications
+    ## Takes a proc or instance method as block
+    def postprocess(method = nil, &block)
+      @before_and_after_works[:postprocess] = method.nil? ? block : method
+    end
+    
+    ##Defines how the flow for a State executes with preprocess and postprocess
+    def process_flow(action,base)
+      action = @before_and_after_works[action.to_sym]
+      case action
+      when Symbol, String
+        base.send(action)
+      when Proc
+        action.call(base)
+      end
+    end
+  end
+
+  # Driver for Transition in FlowChart
+  class Transition
+    attr_reader :condition #boolean condition to verify if transition can be done!
+    attr_reader :branch #selection from multiple branch transition based on condition! 
+    attr_reader :from #transit from!
+    attr_reader :to #transit to!
+    
+    def initialize(options)
+      @condition = options[:condition]
+      @branch = options[:branch]
+      @from = [options[:from]].flatten
+      @to = options[:to]
+    end 
+    
+    def get_me_next_state(base)
+      raise InvalidTransition.new("You cannot transit from multiple states without a decision condition!") if @to.is_a?(Array) && @branch.nil?
+      ## If to is a single state then just pass it on!
+      if !@to.is_a?(Array)
+        return @to
+      end
+      ## If to is an Array it means decision has to be made based on branching conditions to choose the to state!
+      to = process_flow(@branch, base)
+      ## If result to state coming from branching condition is not part of the set mentioned in to then next state transit is not possible!
+      raise InvalidState.new("Your decision condition did not lead to transition state mentioned in :to clause!") unless @to.include?(to)
+      to
+    end
+
+    def shall_i_trasit?(base)
+      return true unless @condition ## If no condition has been given then transition is possible!
+      ## If condition has been given then evaluate truth or falsity for transition to be possible!
+      process_flow(@condition, base)
+    end
+      
+    private
+    def process_flow(action,base)
+      case action
+      when Symbol, String
+        base.send(action)
+      when Proc
+        action.call(base)
+      end
+    end
+  end
+
+  # Driver for Actions in FlowChart
+  class Action
+    attr_accessor :name 
+    attr_accessor :transitions
+    attr_accessor :flowprocessor
+    
+    def initialize(name, flowprocessor=nil, &transitions)
+      @name = name
+      @flowprocessor = flowprocessor
+      @transitions = Array.new
+      instance_eval(&transitions)
+    end
+    
+    def process_action!(implementor_class,current_state,options_for_action)
+      transition = @transitions.select{ |t| t.from.include? current_state.flowstatename }.first
+      raise InvalidTransition.new("No transition found for action #{@name}") if transition.nil?
+      return false unless transition.shall_i_trasit?(implementor_class)
+      new_state = implementor_class.flowprocessor.flowstates[transition.get_me_next_state(implementor_class)]
+      raise InvalidState.new("Invalid state #{transition.to.to_s} for transition.") if new_state.nil?
+      current_state.process_flow(:postprocess, implementor_class)
+      implementor_class.previous_state = current_state.flowstatename.to_s
+      new_state.process_flow(:preprocess, implementor_class)
+      implementor_class.set_current_state(new_state,options_for_action)
+      true
+    end
+    
+    private
+    def transitions(args = {})
+      transition = FlowChart::Transition.new(args)
+      @transitions << transition
+    end
+    
+    def any
+      @flowprocessor.flowstates.keys
+    end
+  end
+
+  # Main Driver for FlowChart
+  class FlowProcessor
+    attr_accessor :flowstates
+    attr_accessor :starting_flowstate
+    attr_accessor :actions
+    
+    def initialize(&flowprocessor)
+      @flowstates, @actions = Hash.new, Hash.new
+      begin
+        instance_eval(&flowprocessor)
+      rescue => e
+        p e.to_s
+      end
+    end
+    
+    ## Default state_column is assumed to be process_status if not mentioned
+    # You can override the default state_column by mentioning in your class
+    # state_column :something_else
+    def state_column(name = :process_status)
+      @state_column ||= name
+    end
+
+    private    
+    def init_flowstate(flowstate_name)
+      @starting_flowstate_name = flowstate_name
+    end
+    
+    def flowstate(*flowstatenames, &options)
+      flowstatenames.each do |flowstatename|
+        flowstate = FlowChart::State.new(flowstatename, &options)
+        if @flowstates.empty? || @starting_flowstate_name == flowstatename
+          @starting_flowstate = flowstate
+        end
+        @flowstates[flowstatename.to_sym] = flowstate
+      end
+    end
+    
+    def action(action_name, &transitions)
+      action = FlowChart::Action.new(action_name, self, &transitions)
+      @actions[action_name.to_sym] = action
+    end
+  end
+end

data/sample/sample_one.rb

@@ -0,0 +1,59 @@
+# Example of a Non-ActiveRecord Class using FlowChart in Ruby
+
+class SampleOne
+  include FlowChart
+  attr_accessor :process_status
+
+  flowchart do
+    init_flowstate :init
+
+    flowstate :init do
+      preprocess Proc.new { |o| p "Initializing File" }
+      postprocess :notify_user
+    end
+
+    flowstate :uploaded do
+      preprocess Proc.new  { |o| p "Validating File" }
+      postprocess Proc.new  { |o| p "File has been uploaded in system" }
+    end
+
+    flowstate :open do
+      postprocess :notify_user
+      postprocess Proc.new  { |o| p "File has been closed" }
+    end
+
+    flowstate :closed do
+      preprocess Proc.new  { |o| p "File closed" }
+      postprocess :notify_user
+    end
+
+    action :upload do
+      transitions :from => :init, :to => :uploaded, :condition => :file_parsable?
+    end
+
+    action :process do
+      transitions :from => :uploaded, :to => [:open, :closed], :branch => :choose_branch
+    end
+
+    action :close do
+      transitions :from => [:init,:uploaded,:open], :to => :closed, :condition => :file_close?
+    end
+
+  end
+
+  def choose_branch
+    6 > 5 ? :open : :closed
+  end
+
+  def notify_user
+    p "Notifying User!"
+  end
+
+  def file_parsable?
+    3 > 2 ? true : false
+  end
+
+  def file_close?
+    1 > 0 ? true : false 
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: flowchart
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Shuddhashil Ray
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-09-27 00:00:00 +05:30
+default_executable: 
+dependencies: []
+
+description: Flowchart is a State Machine(state-action-transition) workflow for Non-ActiveRecord and ActiveRecord Model in Ruby or Rails
+email: rayshuddhashil@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- LICENSE.txt
+- flowchart.gemspec
+- lib/flow_chart.rb
+- lib/flowchart/flow_processor.rb
+- sample/sample_one.rb
+has_rdoc: true
+homepage: http://github.com/raycoding/flowchart
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.3
+signing_key: 
+specification_version: 3
+summary: State Machine and State Flow for Ruby
+test_files: []
+