multiflow 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 27023220462c60ad9bf0cbdee297069da3c6db61
+  data.tar.gz: cfd4c4c3c6b624e4377d375ea56aad5369579035
+SHA512:
+  metadata.gz: 4c7835b010f45c295513917d015e2d5c59789d3e790945a40217894f337139854cd10f7c1ee3a4ece2dae05201a933c41730f5e1c1bd5c1ae6c933baf1ef60c7
+  data.tar.gz: 62c8b45de48b83647a7c402479b052889fa98dfbbd285dbdd3d9733bd2f496affabc42c45ad3fe1d90a3f17076748e916d57dde6b8776d8fdb3a3d979bc8ebb1

data/.gitignore

@@ -0,0 +1,6 @@
+pkg
+doc
+*.gem
+.redcar
+**.swp
+.bundle/

data/CHANGELOG.rdoc

@@ -0,0 +1,38 @@
+= Version 0.5.0.beta
+  * Added a Railtie
+  * Changed up the detection for persistence in Rails
+
+= Version 0.4.2
+  * Some code neatening by pedromenezes - Thanks!
+  * Added simple benchmark which is probably not accurate :)
+  
+= Version 0.4.1
+	* Removed the depreciation warnings - FINALLY :)
+
+= Version 0.4.0
+* Changed the order of the hooks, now runs in the following order:
+	- Exit on previous state
+	- Enter on new state
+	- Save to persistence
+
+= Version 0.3.0
+* Added a non bang method for events (Check README)
+* Added tests to persistence layers (About time!)
+* Changed the way the persistence layers save to model
+* Protected state column is now supported!
+
+= Version 0.2.3
+* Silence depreciation warnings (Fixing irritating issue)
+
+= Version 0.2.2
+* Previous state can be accessed with `_previous_state` instance method after transitioning states
+
+= Version 0.2.1
+* Reverted the writes back to update_attributes
+
+= Version 0.2
+* Added a transition to any event, please look at the tests to understand how it works - Thanks to nu7hatch for the patch!
+* Changed the persistence layers to use write_attribute, instead of update_attribute - Thanks to achirkunov
+
+= Version 0.1.2
+* Fixed Mongoid support - Thanks bmartin for pointing that out

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,46 @@
+PATH
+  remote: .
+  specs:
+    multiflow (1.0.0)
+      activesupport
+
+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)
+    i18n (0.6.0)
+    multi_json (1.3.6)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.2)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.2)
+    sqlite3 (1.3.6)
+    sqlite3-ruby (1.3.3)
+      sqlite3 (>= 1.3.3)
+    tzinfo (0.3.33)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord
+  multiflow!
+  rspec (>= 2.0.0)
+  sqlite3-ruby

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Ryan Oberholzer
+ 
+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,131 @@
+= Stateflow
+
+== PLEASE NOTE!!!
+
+*Version 0.5.x > will only support Rails 3 / ActiveModel persistences. If you are using Rails 2 Please make sure you use the 0.4.x releases. There is a branch dedicated to that.*
+
+This is the basics of the gem. Please check out the examples directory or tests for usage until this README gets fleshed out. Feel free to fork and modify as you please.
+
+== INSTALL
+
+  gem install stateflow
+
+== Usage
+
+As you can see below, Stateflow's API is very similar to AASM, but allows for a more dynamic state transition flow. Stateflow supports persistence/storage with Mongoid, MongoMapper, and ActiveRecord. Request any others or push them to me.
+
+Stateflow defaults to ActiveRecord but you can set the persistence layer with:
+
+  Stateflow.persistence = :mongo_mapper
+OR
+  Stateflow.persistence = :active_record
+OR
+  Stateflow.persistence = :mongoid
+
+Stateflow allows dynamic :to transitions with :decide. The result :decide returns needs to be one of the states listed in the :to array, otherwise it wont allow the transition. Please view the advanced example below for usage.
+
+You can set the default column with the state_column function in the stateflow block. The default state column is "state".
+
+  state_column :state
+  
+== Rails 3
+  Stateflow now automatically tries to detect your persistence from your applications default ORM config. If the ORM you are using does not have a persistence layer it will default to ActiveRecord.
+
+== Basic Example
+
+  require 'rubygems'
+  require 'stateflow'
+
+  # No persistence
+  Stateflow.persistence = :none
+
+  class Stoplight
+    include Stateflow
+
+    stateflow do
+      initial :green
+
+      state :green, :yellow, :red
+
+      event :change_color do
+        transitions :from => :green, :to => :yellow
+        transitions :from => :yellow, :to => :red
+        transitions :from => :red, :to => :green
+      end
+    end
+  end
+
+== Advanced Example
+
+  require 'rubygems'
+  require 'stateflow'
+
+  # No persistence
+  Stateflow.persistence = :none
+
+  class Test
+    include Stateflow
+
+    stateflow do
+
+      initial :love
+
+      state :love do
+        enter lambda { |t| p "Entering love" }
+        exit :exit_love
+      end
+
+      state :hate do
+        enter lambda { |t| p "Entering hate" }
+        exit lambda { |t| p "Exiting hate" }
+      end
+
+      state :mixed do
+        enter lambda { |t| p "Entering mixed" }
+        exit lambda { |t| p "Exiting mixed" }
+      end
+
+      event :b do
+        transitions :from => :love, :to => :hate, :if => :no_ice_cream
+        transitions :from => :hate, :to => :love
+      end
+
+      event :a do
+        transitions :from => :love, :to => [:hate, :mixed], :decide => :likes_ice_cream?
+        transitions :from => [:hate, :mixed], :to => :love
+      end
+    end
+
+    def likes_ice_cream?
+      rand(10) > 5 ? :mixed : :hate
+    end
+
+    def exit_love
+      p "Exiting love"
+    end
+
+    def no_ice_cream
+      rand(4) > 2 ? true : false
+    end
+  end
+
+== Bang event vs non-bang event
+
+Bang events will save the model after call, where the non bang event will just update the state and call the transitions. (ie. model.change! vs model.change)
+
+== Extras
+
+* When transitioning states, the previous state from which you have transitioned to can be accessed via `_previous_state`. See tests for more information.
+
+== 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 future version unintentionally.
+* Commit, do not mess with Rakefile, version, or history.
+  (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 Ryan Oberholzer. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/benchmark/compare_state_machines.rb

@@ -0,0 +1,88 @@
+require 'benchmark'
+require 'active_record'
+require 'stateflow'
+require 'aasm'
+
+# change this if sqlite is unavailable
+dbconfig = {
+  :adapter => 'sqlite3',
+  :database => ':memory:'
+}
+
+ActiveRecord::Base.establish_connection(dbconfig)
+ActiveRecord::Migration.verbose = false
+
+
+class TestMigration < ActiveRecord::Migration
+  STATE_MACHINES = ['stateflow', 'aasm']
+
+  def self.up
+    STATE_MACHINES.each do |name|
+      create_table "#{name}_tests", :force => true do |t|
+        t.column :state, :string
+      end
+    end
+  end
+
+  def self.down
+    STATE_MACHINES.each do |name|
+      drop_table "#{name}_tests"
+    end
+  end
+end
+
+Stateflow.persistence = :active_record
+
+class StateflowTest < ActiveRecord::Base
+  include Stateflow
+
+  stateflow do
+    initial :green
+
+    state :green, :yellow, :red
+
+    event :change_color do
+      transitions :from => :green, :to => :yellow
+      transitions :from => :yellow, :to => :red
+      transitions :from => :red, :to => :green
+    end
+  end
+end
+
+class AasmTest < ActiveRecord::Base
+  include AASM
+
+  aasm_column :state # defaults to aasm_state
+
+  aasm_initial_state :green
+
+  aasm_state :green
+  aasm_state :yellow
+  aasm_state :red
+
+  aasm_event :change_color do
+    transitions :from => :green, :to => :yellow
+    transitions :from => :yellow, :to => :red
+    transitions :from => :red, :to => :green
+  end
+end
+
+n = 1000
+TestMigration.up
+
+Benchmark.bm(7) do |x|
+  x.report('stateflow') do
+    n.times do
+      stateflow = StateflowTest.new
+      3.times { stateflow.change_color! }
+    end
+  end
+  x.report('aasm') do
+    n.times do
+      aasm = AasmTest.new
+      3.times { aasm.change_color! }
+    end
+  end
+end
+
+TestMigration.down

data/examples/robot.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'stateflow'
+
+class Robot
+  include Stateflow
+
+  stateflow do
+    initial :green
+
+    state :green, :yellow, :red
+
+    event :change_color do
+      transitions :from => :green, :to => :yellow
+      transitions :from => :yellow, :to => :red
+      transitions :from => :red, :to => :green
+    end
+  end
+end

data/examples/test.rb

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'stateflow'
+
+class Test
+  include Stateflow
+  
+  stateflow do
+    
+    initial :love
+    
+    state :love do
+      enter lambda { |t| p "Entering love" }
+      exit :exit_love
+    end
+    
+    state :hate do
+      enter lambda { |t| p "Entering hate" }
+      exit lambda { |t| p "Exiting hate" }
+    end
+    
+    state :mixed do
+      enter lambda { |t| p "Entering mixed" }
+      exit lambda { |t| p "Exiting mixed" }
+    end
+    
+    event :b do
+      transitions :from => :love, :to => :hate, :if => :no_ice_cream
+      transitions :from => :hate, :to => :love
+    end
+    
+    event :a do
+      transitions :from => :love, :to => [:hate, :mixed], :decide => :likes_ice_cream?
+      transitions :from => [:hate, :mixed], :to => :love
+    end
+  end
+  
+  def likes_ice_cream?
+    rand(10) > 5 ? :mixeds : :hate
+  end
+  
+  def exit_love
+    p "Exiting love"
+  end
+  
+  def no_ice_cream
+    rand(4) > 2 ? true : false
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'stateflow'

data/lib/multiflow/event.rb

@@ -0,0 +1,38 @@
+module Multiflow
+  class Event
+    attr_accessor :name, :transitions, :machine
+
+    def initialize(name, machine=nil, &transitions)
+      @name = name
+      @machine = machine
+      @transitions = Array.new
+
+      instance_eval(&transitions)
+    end
+
+    def fire(machine, current_state, klass, options)
+      transition = @transitions.select{ |t| t.from.include? current_state.name }.first
+      raise NoTransitionFound.new("No transition found for event #{@name}") if transition.nil?
+
+      return nil unless transition.can_transition?(klass)
+
+      new_state = machine.states[transition.find_to_state(klass)]
+      raise NoStateFound.new("Invalid state #{transition.to.to_s} for transition.") if new_state.nil?
+
+      current_state.execute_action(:exit, klass)
+      new_state.execute_action(:enter, klass)
+
+      new_state
+    end
+
+    private
+    def transitions(args = {})
+      transition = Multiflow::Transition.new(args)
+      @transitions << transition
+    end
+
+    def any
+      @machine.states.keys
+    end
+  end
+end

data/lib/multiflow/exception.rb

@@ -0,0 +1,5 @@
+module Multiflow
+  class NoTransitionFound < Exception; end
+  class NoStateFound < Exception; end
+  class NoEventFound < Exception; end
+end

data/lib/multiflow/machine.rb

@@ -0,0 +1,40 @@
+module Multiflow
+  class Machine
+    attr_accessor :states, :initial_state, :events
+    
+    def initialize(&machine)
+      @states, @events, @create_scopes = Hash.new, Hash.new, true
+      instance_eval(&machine)
+    end
+    
+    def state_column(name = :state)
+      @state_column ||= name
+    end
+    
+    def create_scopes(bool = false)
+      @create_scopes = bool
+    end
+    
+    def create_scopes?
+      @create_scopes
+    end
+
+    private    
+    def initial(name)
+      @initial_state_name = name
+    end
+    
+    def state(*names, &options)
+      names.each do |name|
+        state = Multiflow::State.new(name, &options)
+        @initial_state = state if @states.empty? || @initial_state_name == name
+        @states[name.to_sym] = state
+      end
+    end
+    
+    def event(name, &transitions)
+      event = Multiflow::Event.new(name, self, &transitions)
+      @events[name.to_sym] = event
+    end
+  end
+end

data/lib/multiflow/persistence/active_record.rb

@@ -0,0 +1,35 @@
+module Multiflow
+  module Persistence
+    module ActiveRecord
+      extend ActiveSupport::Concern
+
+      included do
+        before_validation(:ensure_initial_state, :on => :create)
+      end
+
+      module ClassMethods
+        def add_scope(machine, state)
+          scope state.name, -> { where("#{machine.state_column}".to_sym => state.name.to_s) }
+        end
+      end
+
+      def load_from_persistence(machine)
+        send machine.state_column.to_sym
+      end
+
+      def save_to_persistence(machine, new_state, options = {})
+        send("#{machine.state_column}=".to_sym, new_state)
+        save! if options[:save]
+      end
+
+      def ensure_initial_state
+        machines.each do |machine|
+          if send(machine.state_column.to_s).blank?
+            current_state = send("current_#{machine.state_column}")
+            send("#{machine.state_column.to_s}=", current_state.name.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/multiflow/persistence/none.rb

@@ -0,0 +1,21 @@
+module Multiflow
+  module Persistence
+    module None
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def add_scope(machine, state)
+          # do nothing
+        end
+      end
+
+      def load_from_persistence(machine)
+        instance_variable_get :"@state_#{machine.state_column}"
+      end
+
+      def save_to_persistence(machine, new_state, options)
+        instance_variable_set :"@state_#{machine.state_column}", new_state
+      end
+    end
+  end
+end

data/lib/multiflow/persistence.rb

@@ -0,0 +1,29 @@
+module Multiflow
+  module Persistence
+    def self.active
+      persistences = Array.new
+
+      Dir[File.dirname(__FILE__) + '/persistence/*.rb'].each do |file|
+        persistences << File.basename(file, File.extname(file)).underscore.to_sym
+      end
+
+      persistences
+    end
+
+    def self.load!(base)
+      begin
+        base.send :include, "Multiflow::Persistence::#{Multiflow.persistence.to_s.camelize}".constantize
+      rescue NameError
+        puts "[Multiflow] The ORM you are using does not have a Persistence layer. Defaulting to ActiveRecord."
+        puts "[Multiflow] You can overwrite the persistence with Multiflow.persistence = :new_persistence_layer"
+
+        Multiflow.persistence = :active_record
+        base.send :include, "Multiflow::Persistence::ActiveRecord".constantize
+      end
+    end
+
+    Multiflow::Persistence.active.each do |p|
+      autoload p.to_s.camelize.to_sym, "multiflow/persistence/#{p.to_s}"
+    end
+  end
+end

data/lib/multiflow/railtie.rb

@@ -0,0 +1,12 @@
+module Multiflow
+  class Railtie < Rails::Railtie
+    def default_orm
+      generators = config.respond_to?(:app_generators) ? :app_generators : :generators
+      config.send(generators).options[:rails][:orm]
+    end
+
+    initializer "multiflow.set_persistence" do
+      Multiflow.persistence = default_orm if Multiflow.persistence.blank?
+    end
+  end
+end

data/lib/multiflow/state.rb

@@ -0,0 +1,31 @@
+module Multiflow
+  class State
+    attr_accessor :name, :options
+    
+    def initialize(name, &options)
+      @name = name
+      @options = Hash.new
+      
+      instance_eval(&options) if block_given?
+    end
+    
+    def enter(method = nil, &block)
+      @options[:enter] = method.nil? ? block : method
+    end
+    
+    def exit(method = nil, &block)
+      @options[:exit] = method.nil? ? block : method
+    end
+    
+    def execute_action(action, base)
+      action = @options[action.to_sym]
+      
+      case action
+      when Symbol, String
+        base.send(action)
+      when Proc
+        action.call(base)
+      end
+    end
+  end
+end

data/lib/multiflow/transition.rb

@@ -0,0 +1,39 @@
+module Multiflow
+  class IncorrectTransition < Exception; end
+  
+  class Transition
+    attr_reader :from, :to, :if, :decide
+    
+    def initialize(args)
+      @from = [args[:from]].flatten
+      @to = args[:to]
+      @if = args[:if]
+      @decide = args[:decide]
+    end 
+    
+    def can_transition?(base)
+      return true unless @if
+      execute_action(@if, base)
+    end
+    
+    def find_to_state(base)
+      raise IncorrectTransition.new("Array of destinations and no decision") if @to.is_a?(Array) && @decide.nil?
+      return @to unless @to.is_a?(Array)
+      
+      to = execute_action(@decide, base)
+      
+      raise NoStateFound.new("Decision did not return a state that was set in the 'to' argument") unless @to.include?(to)
+      to
+    end
+      
+    private
+    def execute_action(action, base)
+      case action
+      when Symbol, String
+        base.send(action)
+      when Proc
+        action.call(base)
+      end
+    end
+  end
+end