super_state 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 [name of plugin creator]
+
+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

@@ -0,0 +1,64 @@
+SuperState
+==========
+
+Super Simple state machine for Ruby and Rails
+(designed for ActiveRecord, but hopefully easily extended to any ActiveModel)
+
+Example
+=======
+
+a simple multi-state model
+
+  class MyModel < ActiveRecord::Base
+
+    include SuperState
+
+    super_state :pending, :initial => true
+    super_state :processing
+    super_state :completed
+    super_state :failed
+
+    super_state_group :outstanding, ["pending", "processing"]
+
+    # first part of a two stage transition
+    # eg.
+    #   def process
+    #     start_processing!
+    #       do_the_stuff
+    #     complete_processing!
+    #   end
+    #
+    state_transition :start_processing, :pending => :processing
+
+    # second part of a two stage transition
+    state_transition :complete_processing, :processing => :completed
+
+    # transition direct from pending to complete
+    state_transition :complete, :pending => :completed
+
+    # failed to process
+    state_transition :fail, :processing => :failed
+
+    # back to processing
+    state_transition :restart, :failed => :processing
+  
+  end
+
+we can also take arguments in our transitions
+
+  class Loan < ActiveRecord::Base
+  
+    include SuperState
+    
+    super_state :requested, :initial => true
+    super_state :disbursed
+    
+    state_transition :disburse, :requested => :disbursed do |params|
+      self.disbursed_amount = params[:amount]
+      self.disbursed_date   = params[:disbursed_date]
+    end
+    
+  end
+
+
+Copyright (c) 2010 [Matthew Rudy Jacobs], released under the MIT license

data/Rakefile

@@ -0,0 +1,97 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test SuperState.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the super_slate plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SuperState'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require "rubygems"
+require "rake/gempackagetask"
+require "rake/rdoctask"
+
+require "rake/testtask"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+
+task :default => ["test"]
+
+# This builds the actual gem. For details of what all these options
+# mean, and other ones you can add, check the documentation here:
+#
+#   http://rubygems.org/read/chapter/20
+#
+spec = Gem::Specification.new do |s|
+
+  # Change these as appropriate
+  s.name              = "super_state"
+  s.version           = "0.1.0"
+  s.summary           = "Super Simple State Machine"
+  s.author            = "Matthew Rudy Jacobs"
+  s.email             = "MatthewRudyJacobs@gmail.com"
+  s.homepage          = "http://github.com/matthewrudy/super_state"
+
+  s.has_rdoc          = true
+  s.extra_rdoc_files  = %w(README)
+  s.rdoc_options      = %w(--main README)
+
+  # Add any extra files to include in the gem
+  s.files             = %w(MIT-LICENSE Rakefile README) + Dir.glob("{test,lib}/**/*")
+  s.require_paths     = ["lib"]
+
+  # If you want to depend on other gems, add them here, along with any
+  # relevant versions
+  # s.add_dependency("some_other_gem", "~> 0.1.0")
+
+  # If your tests use any gems, include them here
+  # s.add_development_dependency("mocha") # for example
+end
+
+# This task actually builds the gem. We also regenerate a static
+# .gemspec file, which is useful if something (i.e. GitHub) will
+# be automatically building a gem for this project. If you're not
+# using GitHub, edit as appropriate.
+#
+# To publish your gem online, install the 'gemcutter' gem; Read more 
+# about that here: http://gemcutter.org/pages/gem_docs
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Build the gemspec file #{spec.name}.gemspec"
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, "w") {|f| f << spec.to_ruby }
+end
+
+# If you don't want to generate the .gemspec file, just remove this line. Reasons
+# why you might want to generate a gemspec:
+#  - using bundler with a git source
+#  - building the gem without rake (i.e. gem build blah.gemspec)
+#  - maybe others?
+task :package => :gemspec
+
+desc 'Clear out RDoc and generated packages'
+task :clean => [:clobber_rdoc, :clobber_package] do
+  rm "#{spec.name}.gemspec"
+end

data/lib/super_state.rb

@@ -0,0 +1,240 @@
+module SuperState
+  
+  def self.included(klass)
+    klass.class_eval do
+      cattr_accessor :initial_super_state
+      cattr_accessor :__super_states
+      cattr_accessor :super_state_groups
+      self.__super_states     = StateArray.new.all_states!
+      self.super_state_groups = StateGroups.new
+      
+      extend ClassMethods
+      include InstanceMethods
+      
+      # the initial_state only takes effect when we say record.valid?
+      before_validation :set_initial_super_state, :on => :create
+    end
+  end
+  
+  # states should be stored as strings in all cases
+  # (if it needs to be a sym, we should explicitly ask it to be)
+  def self.canonicalise(value)
+    if value
+      if value.is_a?(Array)
+        value.map{|v| self.canonicalise(v)}
+      else
+        value.to_s
+      end
+    end
+  end
+  
+  # I want to know the states are the same
+  class StateArray < Array
+    
+    def initialize(array=nil)
+      super(SuperState.canonicalise(Array(array)))
+    end
+    
+    def <<(value)
+      super(SuperState.canonicalise(value))
+    end
+    
+    def include?(value)
+      super(SuperState.canonicalise(value))
+    end
+    
+    def for_select
+      self.map do |value|
+        [value.humanize, value]
+      end
+    end
+    
+    def all_states!
+      @all_states = true
+      self
+    end
+    
+    def all_states?
+      @all_states
+    end
+    
+  end
+  
+  class StateGroups < ActiveSupport::OrderedHash
+    
+    def []=(key, value)
+      super(SuperState.canonicalise(key), SuperState.canonicalise(value))
+    end
+    
+    def [](key)
+      super(SuperState.canonicalise(key))
+    end
+    
+    def keys
+      StateArray.new(super)
+    end
+  
+  end
+  
+  module InstanceMethods
+    
+    def current_super_state
+      self[self.class.super_state_column] || SuperState.canonicalise(self.class.initial_super_state)
+    end
+    
+    def set_initial_super_state
+      set_super_state(self.class.initial_super_state)
+    end
+    
+    def set_super_state(state_name, set_timestamps=true)
+      self[self.class.super_state_column] = SuperState.canonicalise(state_name)
+      
+      if set_timestamps && self.respond_to?("#{state_name}_at=")
+        self.send("#{state_name}_at=", Time.now)
+      end
+      
+      self.current_super_state
+    end
+    
+    def human_super_state
+      self.current_super_state.humanize
+    end
+    
+  end
+  
+  class BadState < ArgumentError ; end
+  
+  module ClassMethods
+    
+    def super_states_for_select(options={})
+      rtn = []
+      if options[:include_all]
+        rtn << ["<All>", "all"]
+      end
+      if options[:include_groups]
+        rtn += self.super_state_groups.keys.for_select
+      end
+      rtn += self.super_states.for_select
+      
+      rtn
+    end
+    
+    def super_state(state_name, options={})
+      if options[:initial] || self.initial_super_state.nil?
+        self.initial_super_state = state_name
+      end
+      define_state_methods(state_name)
+      self.__super_states << state_name
+    end
+    
+    # a wrapper around state based scopes
+    # to avoid malicious arguments;
+    #   Loan.in_state(:disbursed) => Loan.disbursed
+    #   Loan.in_state("active")   => Loan.active
+    #   Loan.in_state("all")      => Loan.scoped
+    #   Loan.in_state("")         => Loan.scoped
+    #   Loan.in_state("something_evil") => Exception!
+    def in_state(state_name)
+      if state_array = self.super_states(state_name)
+        self.scope_by_super_state(state_array)
+      else
+        raise BadState, "you are trying to scope by something other than a super state (or super state group)"
+      end
+    end
+    
+    # self.super_states        => ["first", "second", "third"]
+    # self.super_states("")    => ["first", "second", "third"]
+    # self.super_states("all") => ["first", "second", "third"]
+    #
+    # self.super_states("first") => ["first"]
+    #
+    # self.super_states("final") => ["second", "third"]
+    #
+    def super_states(state_name=nil)
+      if state_name.blank? || state_name == "all"
+        self.__super_states
+      elsif self.__super_states.include?(state_name)
+        StateArray.new(state_name)
+      elsif self.super_state_groups.include?(state_name)
+        self.super_state_groups[state_name]
+      end
+    end
+    
+    def scope_by_super_state(state_names)
+      if state_names.is_a?(StateArray) && state_names.all_states?
+        self.scoped
+      else
+        self.where(self.super_state_column => SuperState.canonicalise(state_names))
+      end
+    end
+    
+    # super_state_group(:active, [:approved, :requested, :disbursed])
+    def super_state_group(group_name, group_states)
+      define_state_methods(group_name, group_states)
+      self.super_state_groups[group_name] = group_states
+    end
+    
+    # state_transition :complete, :processing => :completed
+    def state_transition(transition_name, state_hash, &transition_block)
+      state_hash = state_hash.stringify_keys
+      
+      define_state_transition_method(transition_name,       state_hash, :save,  &transition_block)
+      define_state_transition_method("#{transition_name}!", state_hash, :save!, &transition_block)
+    end
+    
+    # internal methods
+    
+    def super_state_column
+      :status
+    end
+    
+    def define_state_methods(method_name, state_names=nil)
+      state_names ||= method_name
+      
+      # Loan.completed # scope
+      self.scope method_name, self.scope_by_super_state(state_names)
+      
+      # pretty much;
+      #   def record.completed?
+      #     record.status == "completed"
+      #   end
+      define_method("#{method_name}?") do
+        StateArray.new(state_names).include?(self.current_super_state)
+      end
+    end
+    
+    def define_state_transition_method(method_name, state_hash, save_method, &transition_block)
+      
+      # pretty much;
+      #   def record.complete!
+      #     if record.pending?
+      #       record.status = "completed"
+      #       record.save!
+      #     else
+      #       raise SuperState::BadState
+      #     end
+      #   end
+      define_method(method_name) do |*args|
+        if to_state = state_hash[self.current_super_state]
+
+          state_before = self.current_super_state
+          self.set_super_state(to_state)
+
+          if transition_block
+            params = args.shift || {}
+            self.instance_exec(params, &transition_block)
+          end
+
+          unless rtn = self.send(save_method)
+            self.set_super_state(state_before, false) #roll it back on failure
+          end
+          rtn
+        else
+          raise SuperState::BadState, "#{method_name} can only be called from states #{state_hash.keys.inspect}"
+        end
+      end
+      
+    end
+    
+  end
+end

data/test/super_state_test.rb

@@ -0,0 +1,12 @@
+require 'test_helper'
+
+class SuperStateTest < ActiveSupport::TestCase
+  
+  test "abstract the tests" do
+    puts "this has been abstracted from a live project"
+    puts "as such the tests have not yet been abstracted"
+    puts "give me some time to do this"
+    flunk "abstract the tests"
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'test/unit'
+require 'active_support'

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: super_state
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Matthew Rudy Jacobs
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-17 00:00:00 +08:00
+default_executable: 
+dependencies: []
+
+description: 
+email: MatthewRudyJacobs@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- MIT-LICENSE
+- Rakefile
+- README
+- test/super_state_test.rb
+- test/test_helper.rb
+- lib/super_state.rb
+has_rdoc: true
+homepage: http://github.com/matthewrudy/super_state
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+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.3.7
+signing_key: 
+specification_version: 3
+summary: Super Simple State Machine
+test_files: []
+