flojo 0.5.0

data/MIT_LICENSE

@@ -0,0 +1,11 @@
+LICENSE:
+
+(The MIT License)
+
+Copyright © 2010 Joey Adarkwah
+
+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/Manifest

@@ -0,0 +1,11 @@
+CHANGELOG
+MIT_LICENSE
+README.rdoc
+Rakefile
+flojo.gemspec
+lib/flojo.rb
+test/test_active_record.rb
+test/test_db.sqlite3
+test/test_helper.rb
+test/test_poro.rb
+Manifest

data/README.rdoc

@@ -0,0 +1,109 @@
+= Flojo
+          
+	Flojo is a simple ActiveRecord aware state machine module, but it will also work with any plain old ruby object.  
+	When used within an ActiveRecord subclass, flojo events can automatically save a record after a transition.     
+	
+	After including the module in your class and configuring it with an event _event_, and a state _state_, 
+	you can interact with instances of that class using the dynamically generated methods of the following form:
+	
+	object.wf_event  - Triggers event and invokes any applicable transitions
+	object.wf_event! - Behaves just like object.wf_event but will also persist object.
+	object.wf_state? - Returns true if the current workflow state is _state_.   
+	object.wf_current_state - Returns the objects current state.
+	
+	To avoid method name collisions with your classes, Flojo methods are usually prefixed with "wf_".   
+	
+	See test.rb, test_active_record.rb and test_helper.rb for concrete examples.
+	
+== Install       
+
+	Simply require flojo.rb.  
+	If you are using rails, copy flojo.rb to your project's <b>lib</b> folder.   
+	Alternatively, install the gem with gem install flojo.  
+	
+== Usage  
+
+	require 'flojo' 
+
+	class Baby 
+	  # Include the module
+	  include Flojo
+ 
+	  # configure the states. The first element represents the initial state
+	  workflow_states [:asleep, :crying, :pooping, :chilling, :puking]
+   
+	  # configure your transitions. Using: transition :begin_state, :end_state
+	  event :feed do
+	    transition :crying, :chilling
+	    transition :chilling, :pooping
+	  end
+	
+	  event :rock do
+	    transition :crying, :chilling
+	    transition :chilling, :asleep
+	    transition :asleep, :pooping
+	  end
+  
+	  event :burp do
+	    transition :crying, :chilling
+	    transition :chilling, :puking
+	  end
+  
+	  event :wake do
+	    transition :asleep, :crying
+	  end
+  	    
+	  event :spank do 
+	    # :any is a wildcard state and is only valid as a begin state.
+	    transition :any, :crying
+	  end
+	
+	  # event, enter state and exit state callbacks should take the form wf_on_event, 
+	  wf_on_enter_state and wf_on_exit_state and are only called if they are defined
+	  def wf_on_spank
+	    puts "Never spank a baby! Somebody dial 911!"
+	  end
+	
+	  def wf_on_enter_chilling
+	    puts "drool and fart"
+	  end
+  
+	  def wf_on_exit_asleep
+	    puts "waaaaah waaaaah waaaaaah"
+	  end
+
+	  # called only after an event yields a transition.
+	  def wf_after_transition
+	    puts "Send a tweet baby is alive and kicking"
+	  end 
+	
+	  # called only after an event triggers a save.
+	  def wf_after_save
+	    puts "Send a tweet saying baby was saved"
+	  end
+	  
+	end
+
+ 
+	baby = Baby.new
+	baby.wf_asleep? #Should return true
+
+	baby.wf_wake
+	baby.wf_current_state #Should return :awake          
+
+== ActiveRecord specific details   
+	If you want the current workflow state persisted, your table needs to have a string column named _wf_state_. 
+	If your table has a _wf_last_event_ column, that column will store the most recent event triggered on the object.
+	The module will still work if the wf_state is absent but the workflow state will be transient.
+	When used within an ActiveRecord subclass, the "!" versions of the wf_event methods will -
+	trigger a record save immediately after transition.
+
+	eg:
+	baby.wf_feed  - Will *not* trigger a save. 
+	baby.wf_feed! - *Will* trigger a save.  
+	
+== Copyright
+	
+Copyright (c) 2010 Joey Adarkwah
+	 
+

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('flojo', '0.5.0') do |p|
+  p.description    = "ActiveRecord aware workflow (state machine) module that will also work with any plain old ruby object." 
+  p.summary    = "When used within an ActiveRecord subclass, flojo events can automatically save a record after a transition.     
+	
+	After including the module in your class and configuring it with an event _event_, and a state _state_, you can interact with instances of that class using the dynamically generated methods of the following form:
+	
+	+object.wf_event+  - Triggers event and invokes any applicable transitions
+	+object.wf_event!+ - Behaves just like +object.wf_event+ but will also persist object.
+	+object.wf_state?+ - Returns true if the current workflow state is _state_.   
+	+object.wf_current_state+ - Returns the objects current state."  
+	
+  p.url            = "http://github.com/alternegro/flojo"
+  p.author         = "Joey Adarkwah"
+  p.email          = "alternegro @nospam@ me.com"
+  p.development_dependencies = []
+end

data/flojo.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{flojo}
+  s.version = "0.5.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Joey Adarkwah"]
+  s.date = %q{2010-12-07}
+  s.description = %q{ActiveRecord aware workflow (state machine) module that will also work with any plain old ruby object.}
+  s.email = %q{alternegro @nospam@ me.com}
+  s.extra_rdoc_files = ["CHANGELOG", "README.rdoc", "lib/flojo.rb"]
+  s.files = ["CHANGELOG", "MIT_LICENSE", "README.rdoc", "Rakefile", "flojo.gemspec", "lib/flojo.rb", "test/test_active_record.rb", "test/test_db.sqlite3", "test/test_helper.rb", "test/test_poro.rb", "Manifest"]
+  s.homepage = %q{http://github.com/alternegro/flojo}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Flojo", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{flojo}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{When used within an ActiveRecord subclass, flojo events can automatically save a record after a transition.       After including the module in your class and configuring it with an event _event_, and a state _state_, you can interact with instances of that class using the dynamically generated methods of the following form:  +object.wf_event+  - Triggers event and invokes any applicable transitions +object.wf_event!+ - Behaves just like +object.wf_event+ but will also persist object. +object.wf_state?+ - Returns true if the current workflow state is _state_.    +object.wf_current_state+ - Returns the objects current state.}
+  s.test_files = ["test/test_active_record.rb", "test/test_helper.rb", "test/test_poro.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/flojo.rb

@@ -0,0 +1,91 @@
+module Flojo 
+  def Flojo.included(host)
+    
+  	host.class_eval do          
+  	  attr_writer :wf_current_state 
+  	  attr_accessor :_wf_current_event_transition_map, :wf_previous_state
+  	  protected :wf_current_state=, :_set_workflow_state 
+      
+      def wf_current_state
+        wf_current_state = @wf_current_state.nil? ? wf_initial_state : @wf_current_state 
+      end    
+      
+      def wf_initial_state
+        st = self.respond_to?(:wf_state) ? (wf_state || self.class.wf_states[0]) : self.class.wf_states[0] 
+        st.to_sym
+      end
+        	  
+  	  def self.workflow_states(s)
+        @workflow_states = s.uniq
+	      self.synthesize_state_query_methods
+      end
+	    
+      def self.wf_states
+        @workflow_states
+      end                           
+
+      def self.synthesize_state_query_methods
+	      @workflow_states.each {|st| define_method("wf_#{st}?") { st.eql?(wf_current_state)}}
+	    end  
+	    
+	    def self.valid_state(*states)
+	      states.each {|st| return false if !@workflow_states.include?(st) && (st != :any)}                                               
+        return true
+      end 
+            
+  	end
+      
+    host.class_eval("def self.transition(start_state, end_state); raise 'Invalid Transition State' unless self.valid_state(start_state, end_state); @wf_current_event_transition_map[start_state]=end_state; end")
+	      
+    host.class_eval do
+      def self.event(e, &actions)	  
+        event_token = "wf_#{e}" 
+        map_token = "#{event_token}_transition_map"   
+
+        #setup a transition map class instance variable and corresponding accessors for each event. 
+        self.class_eval("@#{map_token}={}") 
+        self.class_eval("def self.#{map_token}; return @#{map_token}; end")    
+        self.class_eval("def self.wf_current_event_transition_map=(cem); @wf_current_event_transition_map=cem; end" )                                                
+        self.class_eval("@wf_current_event_transition_map = @#{map_token}={}")
+        self.class_eval("def self.wf_current_event_transition_map; @wf_current_event_transition_map; end" ) 
+        self.class_eval("def self.wf_current_event_transition_map=(cem); @wf_current_event_transition_map=cem; end" )
+                      
+        #instance event_methods  
+        self.class_eval("def #{event_token}; self._wf_current_event_transition_map=self.class.#{map_token}; _set_workflow_state \"#{e}\"; end\n")
+        self.class_eval("def #{event_token}!; #{event_token}; _wf_after_transition_save!; wf_after_save if self.class.method_defined? :wf_after_save; end\n" )
+                
+        #Calls transitions in event block
+        actions.call
+      end
+    end
+		
+  end
+  
+  private  
+  
+  def _set_workflow_state(event=nil)
+    self.wf_previous_state = self.wf_current_state 
+    self.wf_last_event = event if self.respond_to?(:wf_last_event)
+    
+    state = self._wf_current_event_transition_map[self.wf_current_state] || self._wf_current_event_transition_map[:any]   
+    
+    if (state != self.wf_current_state) && (!state.nil?)
+      self.wf_current_state=state
+       
+      eval("wf_on_#{event}") if event && (self.class.method_defined? "wf_on_#{event}")             
+      eval("wf_on_exit_#{wf_current_state}") if self.class.method_defined? "wf_on_exit_#{wf_current_state}" 
+      eval("wf_on_enter_#{state}") if self.class.method_defined? "wf_on_enter_#{state}"  
+       
+      wf_after_transition if self.class.method_defined? :wf_after_transition
+    end
+  end   
+                                                                                   
+  def _wf_after_transition_save! 
+    self.wf_state = self.wf_current_state if self.respond_to?(:wf_state=)
+    save! if self.respond_to?(:save!)
+  end  
+  
+end
+
+
+

data/test/test_active_record.rb

@@ -0,0 +1,115 @@
+require 'rubygems'
+require 'active_record'  
+require 'test/unit'    
+require 'flojo' 
+require 'test_helper'
+
+ActiveRecord::Base.establish_connection(
+  :adapter => "sqlite3",
+  :database => "test/test_db.sqlite3"
+)
+
+class Counter < ActiveRecord::Base 
+  include Flojo
+  
+  workflow_states [:one, :two, :three, :four]
+
+  event :up do
+    transition :one, :two
+	  transition :two, :three
+	  transition :three, :four
+  end
+	
+  event :reset do
+    transition :two, :one
+    transition :three, :one
+    transition :four, :one
+  end
+  
+  event :down do
+    transition :one, :three
+	  transition :two, :one
+	  transition :three, :two
+  end
+  
+  def wf_on_enter_one
+    "on_enter_one"
+  end
+	
+  def wf_on_exit_one
+    "on_exit_one"
+  end	
+  
+  def wf_on_down
+  	"on_down"
+  end
+  
+  def wf_on_up
+  	"on_up"
+  end  
+  
+  def wf_after_transition
+    "wf_after_transition"
+  end 
+  
+  def wf_after_save
+    "wf_after_save"
+  end
+
+end     
+
+
+class TestWorkflow < Test::Unit::TestCase  
+  include CommonTests
+  def setup 
+    Counter.delete_all    
+    @b = Baby.new
+    @c = Counter.new 
+    @c.name = "First"
+    @c.save          
+  end   
+  
+  def teardown
+    Counter.delete_all
+  end 
+  
+  def test_stored_counter   
+    stored_counter = Counter.first
+    assert_equal(:one, stored_counter.wf_current_state, "Initial state must be :one")   
+    
+    stored_counter.wf_up!
+    assert_equal(:two, stored_counter.wf_current_state, "Current state must be :two")   
+    
+    stored_counter.reload           
+    assert_equal("two", stored_counter.wf_state, "Stored state must be two")
+    assert_equal(:two, stored_counter.wf_current_state, "Current state must be :two")
+    
+    stored_counter.wf_state = "three"  
+    stored_counter.save!
+    
+    assert_equal("three", stored_counter.wf_state, "Stored state must be three") 
+     
+    stored_counter = Counter.first
+    assert_equal(:three, stored_counter.wf_current_state, "Current state must be :three")
+  end    
+  
+  def test_new_counter 
+    new_counter = Counter.new   
+    assert_equal(nil, new_counter.wf_state, "Stored state must be nil")
+    assert_equal(:one, new_counter.wf_current_state, "Initial state must be :one")  
+    assert_equal(1, Counter.count)
+    
+    new_counter.wf_up!
+    assert_equal(2, Counter.count)
+    assert_equal("up", new_counter.wf_last_event)  
+    
+    new_counter = Counter.last          
+    assert_equal("two", new_counter.wf_state, "Stored state must be nil")
+    assert_equal(:two, new_counter.wf_current_state, "Initial state must be :two")  
+    assert_equal("up", new_counter.wf_last_event)
+    new_counter.wf_down
+    assert_equal("down", new_counter.wf_last_event)  
+  
+  end
+  
+end   

data/test/test_helper.rb

@@ -0,0 +1,124 @@
+module CommonTests
+  def test_events	
+    assert_equal(:one, @c.wf_current_state, "Initial state must be :one")     
+    assert_equal(@c.wf_up!, "wf_after_save", "Last method called should be wf_after_save hook")  
+    assert_equal(:one, @c.wf_previous_state) 
+    assert_equal(:two, @c.wf_current_state) 
+    
+    @c.wf_down!
+    
+    assert_equal(:one, @c.wf_current_state)
+    
+    assert_respond_to(@c, :wf_up!)
+    assert_respond_to(@c, :wf_down!)
+    assert_respond_to(@c, :wf_reset!)
+    
+    @c.wf_up #to :two
+    @c.wf_up #to :three
+    
+    @c.wf_up #to :four
+    
+    @c.wf_up #to :four
+    
+    assert_nil(@c.wf_up, "No transition expected") 
+    
+    @c.wf_up! #to :four
+
+    assert_nil(@c.wf_up, "No transition expected")
+ 
+ 	  assert(@c.wf_four?, "Should still be at :four")
+    
+  end 
+ 
+  def test_states
+    assert_equal(Counter.wf_states, [:one, :two, :three, :four]) 
+    assert_equal(Baby.wf_states, [:asleep, :crying, :pooping, :chilling, :puking] )
+    assert_respond_to(@c, :wf_one?)
+    assert_respond_to(@c, :wf_two?)
+    assert_respond_to(@c, :wf_three?)
+    assert_respond_to(@c, :wf_four?)
+    
+    #states are mutually exclusive and there is always one state
+    assert(@c.wf_one? || @c.wf_two? || @c.wf_three? || @c.wf_four?)
+    assert(!(@c.wf_one? && @c.wf_two? && @c.wf_three? && @c.wf_four?))
+    
+    @c.wf_up! #to :two
+    assert(@c.wf_two?)
+    assert(!(@c.wf_one? || @c.wf_three? || @c.wf_four?))
+    
+  end   
+  
+  def test_wildcard
+    assert_equal(@b.wf_current_state, :asleep)
+    assert(@b.wf_asleep?, "Initial state is asleep")
+    @b.wf_spank; assert(@b.wf_crying?, "Spanking must always lead to crying")
+    @b.wf_feed; assert(@b.wf_chilling?, "Feed must move from crying to chilling")
+    @b.wf_burp; assert(@b.wf_puking?, "Burp must move from chilling to puking")
+    @b.wf_spank; assert(@b.wf_crying?, "Spanking must always lead to crying")  
+    @b.wf_rock; assert(@b.wf_chilling?, "Rock must move from crying to chilling") 
+    @b.wf_spank; assert(@b.wf_crying?, "Spanking must always lead to crying")
+  end                    
+  
+  def test_inheritance
+    oc = OtherCounter.new
+    assert(oc.wf_a?) 
+    oc.wf_up; assert(oc.wf_b?, "State must be :b after wf_up")
+  end 
+end
+
+class Baby
+  include Flojo
+  
+  workflow_states [:asleep, :crying, :pooping, :chilling, :puking]
+
+  event :feed do
+    transition :crying, :chilling
+    transition :chilling, :pooping
+  end
+	
+  event :rock do
+    transition :crying, :chilling
+	transition :chilling, :asleep
+	transition :asleep, :pooping
+  end
+  
+  event :burp do
+  	transition :crying, :chilling
+  	transition :chilling, :puking
+  end
+  
+  event :wake do
+  	transition :asleep, :crying
+  end
+  	    
+  event :spank do
+    transition :any, :crying
+  end
+	
+  #enter and exit event handlers should take the form on_enter_xxx, on_exit_xxx where xxx is the state
+  def wf_on_enter_asleep
+    puts "I peed all over the bed"
+  end
+	
+  def wf_on_enter_chilling
+    puts "drool and fart"
+  end	
+  
+  def wf_on_exit_asleep
+    puts "waaaaah waaaaah waaaaaah"
+  end 
+   
+end
+
+
+class OtherCounter < Baby 
+  include Flojo   
+  
+  workflow_states [:a, :b, :c, :d]
+
+  event :up do
+    transition :a, :b
+	  transition :b, :c
+	  transition :c, :d
+  end
+end

data/test/test_poro.rb

@@ -0,0 +1,67 @@
+require 'flojo' 
+require 'test/unit' 
+require 'test_helper'
+
+class Counter
+  include Flojo
+  
+  workflow_states [:one, :two, :three, :four]
+
+  event :up do
+    transition :one, :two
+	  transition :two, :three
+	  transition :three, :four
+  end
+	
+  event :reset do
+    transition :two, :one
+    transition :three, :one
+    transition :four, :one
+  end
+  
+  event :down do
+    transition :one, :three
+	  transition :two, :one
+	  transition :three, :two
+  end
+	
+  #enter and exit event handlers should take the form on_enter_xxx, on_exit_xxx where xxx is the state
+  def wf_on_enter_one
+    "on_enter_one"
+  end
+	
+  def wf_on_exit_one
+    "on_exit_one"
+  end	
+  
+  def wf_on_down
+  	"on_down"
+  end
+  
+  def wf_on_up
+  	"on_up"
+  end
+  
+  
+  def wf_after_transition
+    "wf_after_transition"
+  end 
+  
+  def wf_after_save
+    "wf_after_save"
+  end
+  
+   
+end 
+
+
+class TestState < Test::Unit::TestCase 
+  include CommonTests 
+  
+  def setup  
+    @c = Counter.new  
+    @b = Baby.new 
+  end 
+
+end    
+

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: flojo
+version: !ruby/object:Gem::Version 
+  hash: 11
+  prerelease: false
+  segments: 
+  - 0
+  - 5
+  - 0
+  version: 0.5.0
+platform: ruby
+authors: 
+- Joey Adarkwah
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-07 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: ActiveRecord aware workflow (state machine) module that will also work with any plain old ruby object.
+email: alternegro @nospam@ me.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- README.rdoc
+- lib/flojo.rb
+files: 
+- CHANGELOG
+- MIT_LICENSE
+- README.rdoc
+- Rakefile
+- flojo.gemspec
+- lib/flojo.rb
+- test/test_active_record.rb
+- test/test_db.sqlite3
+- test/test_helper.rb
+- test/test_poro.rb
+- Manifest
+has_rdoc: true
+homepage: http://github.com/alternegro/flojo
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Flojo
+- --main
+- README.rdoc
+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: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: flojo
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: "When used within an ActiveRecord subclass, flojo events can automatically save a record after a transition.       After including the module in your class and configuring it with an event _event_, and a state _state_, you can interact with instances of that class using the dynamically generated methods of the following form:  +object.wf_event+  - Triggers event and invokes any applicable transitions +object.wf_event!+ - Behaves just like +object.wf_event+ but will also persist object. +object.wf_state?+ - Returns true if the current workflow state is _state_.    +object.wf_current_state+ - Returns the objects current state."
+test_files: 
+- test/test_active_record.rb
+- test/test_helper.rb
+- test/test_poro.rb