can_has_state 0.2.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 thomas morgan
+
+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.md

@@ -0,0 +1,238 @@
+# CanHasState #
+
+
+`can_has_state` is a simplified state machine gem. It relies on ActiveModel and
+should be compatible with any ActiveModel-compatible persistence layer.
+
+Key features:
+
+* Support for multiple state machines
+* Simplified DSL syntax
+* Few added methods avoids clobbering up model's namespace
+* Compatible with ActionPack-style attribute value changes via  
+  `:state_column => 'new_state'`
+* Use any ActiveModel-compatible persistence layer (including your own)
+
+
+
+## DSL ##
+
+### ActiveRecord ###
+
+    class Account < ActiveRecord::Base
+
+      # Choose your state column name. In this case, it's :state.
+      #   It's super easy to have multiple state machines.
+      #
+      state_machine :state do
+
+        # Define each possible state. Add :initial to indicate which state
+        #   will be selected first, if the state hasn't been already set. If 
+        #   not provided, will set :initial to the first defined state.
+        #
+        # :on_enter and :on_exit trigger when this state is entered / exited.
+        #   Symbols are assumed to be instance method names. Inline blocks may
+        #   also be specified. The _deferred variations are discussed below
+        #   under triggers.
+        #
+        state :active, :initial,
+          :from => :inactive,
+          :on_enter => :update_plan_details,
+          :on_enter_deferred => :start_billing,
+          :on_exit_deferred => lambda { |r| r.stop_billing }
+
+        # :from restricts which states can switch to this one. Multiple "from"
+        #   states are allowed, as shown under state :deleted.
+        #
+        # If :from is not present, this state may be entered from any other
+        #   state. To prevent ever moving to a given state (only useful if that
+        #   state is also the initial state), use :from => [] .
+        #
+        state :inactive,
+          :from => [:active]
+
+        # :timestamp automatically sets the current date/time when this state
+        #   is entered. Both *_at and *_on (datetime and date) columns are
+        #   supported.
+        #
+        # :require adds additional restrictions before this state can be
+        #   entered. Like :on_enter/:on_exit, it can be a method name or a
+        #   lambda/Proc. Multiple methods may be provided. Each method must
+        #   return a ruby true value (anything except nil or false) for the
+        #   condition to be satisfied. If any :require is not true, then the
+        #   state transition is blocked.
+        #
+        # :message allows the validation error message to be customized. It is
+        #   used when conditions for either :from or :require fail. The default
+        #   message is used in the example below. %{from} and %{to} parameters
+        #   are optional, and will be the from and to states, respectively.
+        #
+        state :deleted,
+          :from => [:active, :inactive],
+          :timestamp => :deleted_at,
+          :on_enter_deferred => [:delete_record, :delete_payment_info],
+          :require => lambda {|r| !r.active_services? },
+          :message => "has invalid transition from %{from} to %{to}"
+
+        # Custom triggers are called for certain "from" => "to" state
+        #   combinations. They are especially useful for DRYing up triggers
+        #   that apply in multiple situations. They can also be used to apply
+        #   triggers only in narrower situations than :on_enter/:on_exit above.
+
+        # This triggers *only* on :inactive => :active. It will not trigger on
+        #   nil => :active (setting initial state) [see notes on triggers and
+        #   initial state below].
+        #
+        on :inactive => :active, :trigger => :send_welcome_back_message
+
+        # Multiple triggers can be specified on either side of the transition
+        #   or for the trigger actions:
+        #
+        on [:active, :inactive] => :deleted, :trigger => [:do_one, :do_two]
+        on :active => [:inactive, :deleted], :trigger => lambda {|r| r.act }
+
+        # If :deferred is included, and it's true, then this trigger will
+        #   happen post-save, instead of pre-validation. Default pre-validation
+        #   triggers are recommended for changing other attributes. Post-save
+        #   triggers are useful for logging or cascading changes to association
+        #   models. Deferred trigger actions are run within the same database
+        #   transaction (for ActiveRecord and other ActiveModel children that
+        #   implement this).
+        #
+        # Last, wildcards are supported. Note that the ruby parser requires a
+        #   space after the asterisk for wildcards on the left side:
+        #   works:    :* =>:whatever
+        #   doesn't:  :*=>:whatever
+        #
+        # Utilize ActiveModel::Dirty's change history support to know what has
+        #   changed:
+        #   from = state_was   # (specifically, <state_column>_was)
+        #   to   = state
+        #
+        on :* => :*, :trigger => :log_state_change, :deferred=>true
+        on :* => :deleted, :trigger => :same_as_on_enter
+
+      end
+
+      # If you want to set states via ActionController/ActionView, you'll
+      #   probably want something like this.
+      attr_accessible :state, :as=>:admin
+
+    end
+
+
+### Just ActiveModel ###
+
+    class Account
+      include ActiveModel::Dirty
+      include ActiveModel::Validations
+      include ActiveModel::Validations::Callbacks
+      include CanHasState::Machine
+
+      state_machine :account_state do
+        state :active, :initial,
+          :from => :inactive
+        state :inactive,
+          :from => :active
+        state :deleted,
+          :from => [:active, :inactive],
+          :timestamp => :deleted_at
+      end
+
+    end
+
+
+
+## Managing states ##
+
+States are set directly via the relevant state column--no added methods.
+
+    @account = Account.new
+    @account.save!
+    @account.state
+    # => 'active'
+
+    @account.state = 'deleted'
+    @account.valid?
+    # => true
+    @account.save!
+
+    @account.state = 'active'
+    @account.valid?
+    # => false
+
+
+With multiple state machines on a single model, this also eliminates any name
+collisions.
+
+    class Account < ActiveRecord::Base
+
+      # column is :state
+      state_machine :state do
+        state :active,
+          :from => :inactive,
+          :require => lambda{|r| r.payment_status=='current'}
+        state :inactive,
+          :from => :active
+        state :deleted,
+          :from => [:active, :inactive]
+      end
+
+      # column is :payment_status
+      state_machine :payment_status do
+        state :pending, :initial
+        state :current
+        state :overdue
+      end
+    end
+
+    @account = Account.new
+    @account.save!
+    @account.state
+    # => 'active'
+    @account.payment_status
+    # => 'pending'
+
+    @account.state = 'inactive'
+    @account.payment_status = 'overdue'
+    @account.save!
+
+
+You can also check a potential state change using the method  
+`"allow_#{state_machine_column_name}?(potential_state)"`.
+
+    @account.allow_state? :active
+    # => false
+    @account.allow_payment_status? :pending
+    # => true
+
+
+If you really want event-changing methods, it's just as straight-forward to
+write them as normal methods instead of attempting to cram them into a DSL.
+
+    def delete!
+      self.state = 'deleted'
+      save!
+    end
+
+When `save!` is called, the state changes will be validated and all triggers
+will be called.
+
+
+
+## Notes on triggers and initial state ##
+
+`can_has_state` relies on the `ActiveModel::Dirty` module to detect when a state
+attribute has changed. In general, this shouldn't matter much to you.
+
+However, triggers involving initial values can be tricky. If your database
+schema sets the default value to the initial value, `:on_enter` and custom
+triggers will *not* be called because nothing has changed. On the other hand,
+if the state column defaults to a null value, then the triggers will be called
+because the initial state value changed from nil to the initial state.
+
+
+
+## Compatibility ##
+
+Tested with Ruby 1.9 and ActiveSupport and ActiveModel 3.2.8.

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'CanHasState'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/can_has_state/definition.rb

@@ -0,0 +1,125 @@
+module CanHasState
+  class Definition
+
+    attr_reader :column, :states, :initial_state, :triggers
+
+    def initialize(column_name, &block)
+      @column = column_name.to_sym
+      @states = {}
+      @triggers = []
+      instance_eval &block
+      @initial_state ||= @states.keys.first
+    end
+
+
+    def extend_machine(&block)
+      instance_eval &block
+    end
+
+
+    def state(state_name, *args)
+      options = args.extract_options!
+      state_name = state_name.to_s
+
+      if args.include? :initial
+        @initial_state = state_name
+      end
+
+      # TODO: turn even guards into types of triggers ... then support :guard as a trigger param
+      guards = []
+      message = "has invalid transition from %{from} to %{to}"
+      # TODO: differentiate messages for :from errors vs. :guard errors
+
+      options.each do |key, val|
+        case key
+        when :from
+          from_vals = Array(val).map(&:to_s)
+          from_vals << nil # for new records
+          guards << Proc.new{|r| from_vals.include? r.send("#{column}_was").try(:to_s)}
+        when :guard, :require
+          guards += Array(val)
+        when :message
+          message = val
+        when :timestamp
+          @triggers << {:from=>["*"], :to=>[state_name], :trigger=>[Proc.new{|r| r.send("#{val}=", Time.current)}]}
+        when :on_enter
+          @triggers << {:from=>["*"], :to=>[state_name], :trigger=>Array(val), :type=>:on_enter}
+        when :on_enter_deferred
+          @triggers << {:from=>["*"], :to=>[state_name], :trigger=>Array(val), :type=>:on_enter, :deferred=>true}
+        when :on_exit
+          @triggers << {:from=>[state_name], :to=>["*"], :trigger=>Array(val), :type=>:on_exit}
+        when :on_exit_deferred
+          @triggers << {:from=>[state_name], :to=>["*"], :trigger=>Array(val), :type=>:on_exit, :deferred=>true}
+        end
+      end
+
+      @states[state_name] = {:guards=>guards, :message=>message}
+    end
+
+
+    def on(pairs)
+      trigger  = pairs.delete :trigger
+      deferred = pairs.delete :deferred
+      pairs.each do |from, to|
+        @triggers << {:from=>Array(from).map(&:to_s), :to=>Array(to).map(&:to_s), 
+                      :trigger=>Array(trigger), :type=>:trigger, :deferred=>!!deferred}
+      end
+    end
+
+
+
+    def known?(to)
+       @states.keys.include? to
+    end
+
+    def allow?(record, to)
+      return false unless known?(to)
+      states[to][:guards].all? do |g|
+        case g
+        when Proc
+          g.call record
+        when Symbol, String
+          record.send g
+        else
+          raise ArgumentError, "Expecing Symbol or Proc for :guard, got #{g.class} : #{g}"
+        end
+      end
+    end
+
+    def message(to)
+      states[to][:message]
+    end
+
+
+    def trigger(record, from, to, deferred=false)
+      # Rails.logger.debug "Checking triggers for transition #{from} to #{to} (deferred:#{deferred.inspect})"
+      @triggers.select do |trigger|
+        deferred ? trigger[:deferred] : !trigger[:deferred]
+      end.select do |trigger|
+        (trigger[:from].include?("*") || trigger[:from].include?(from)) &&
+            (trigger[:to].include?("*") || trigger[:to].include?(to))
+      # end.each do |trigger|
+      #   Rails.logger.debug "  Matched trigger: #{trigger[:from].inspect} -- #{trigger[:to].inspect}"
+      end.each do |trigger|
+        call_triggers record, trigger
+      end
+    end
+
+
+    private
+
+    def call_triggers(record, trigger)
+      trigger[:trigger].each do |m|
+        case m
+        when Proc
+          m.call record
+        when Symbol, String
+          record.send m
+        else
+          raise ArgumentError, "Expecing Symbol or Proc for #{trigger[:type].inspect}, got #{m.class} : #{m}"
+        end
+      end
+    end
+
+  end
+end

data/lib/can_has_state/machine.rb

@@ -0,0 +1,104 @@
+module CanHasState
+  module Machine
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      def state_machine(column, &block)
+        d = Definition.new(column, &block)
+
+        define_method "allow_#{column}?" do |to|
+          state_machine_allow?(column.to_sym, to.to_s)
+        end
+
+        self.state_machines += [[column.to_sym, d]]
+      end
+
+      def extend_state_machine(column, &block)
+        sm = state_machines.detect{|(col, stm)| col == column}
+        raise("Unknown state machine #{column}") unless sm
+        sm[1].extend_machine &block
+      end
+
+    end
+
+    included do
+      unless method_defined? :state_machines
+        class_attribute :state_machines, :instance_writer=>false
+        self.state_machines = []
+      end
+      before_validation :can_has_initial_states
+      before_validation :can_has_state_triggers
+      validate :can_has_valid_state_machines
+      after_save :can_has_deferred_state_triggers
+    end
+
+
+    private
+
+    def can_has_initial_states
+      state_machines.each do |(column, sm)|
+        if send(column).blank?
+          send("#{column}=", sm.initial_state)
+        end
+      end
+    end
+
+    def can_has_state_triggers
+      # skip triggers if any state machine isn't valid
+      return if can_has_state_errors.any?
+
+      @triggers_called ||= {}
+      state_machines.each do |(column, sm)|
+        from, to = send("#{column}_was"), send(column)
+        next if from == to
+
+        # skip triggers if they've already been called for this from/to transition
+        next if @triggers_called[column] == [from, to]
+
+        sm.trigger(self, from, to)
+
+        # record that triggers were called
+        @triggers_called[column] = [from, to]
+      end
+    end
+
+    def can_has_deferred_state_triggers
+      state_machines.each do |(column, sm)|
+        # clear record of called triggers
+        @triggers_called[column] = nil
+        
+        from, to = send("#{column}_was"), send(column)
+        next if from == to
+        sm.trigger(self, from, to, :deferred)
+      end
+    end
+
+    def can_has_state_errors
+      err = []
+      state_machines.each do |(column, sm)|
+        from, to = send("#{column}_was"), send(column)
+        next if from == to
+        if !sm.known?(to)
+          err << [column, "is not a known state"]
+        elsif !sm.allow?(self, to) #state_machine_allow?(column, to)
+          err << [column, sm.message(to) % {:from=>from, :to=>to}]
+        end
+      end
+      err
+    end
+
+    def can_has_valid_state_machines
+      can_has_state_errors.each do |(column, msg)|
+        errors.add column, msg
+      end
+    end
+
+    def state_machine_allow?(column, to)
+      sm = state_machines.detect{|(col, stm)| col == column}
+      raise("Unknown state machine #{column}") unless sm
+      sm[1].allow?(self, to)
+    end
+
+  end
+end

data/lib/can_has_state/railtie.rb

@@ -0,0 +1,11 @@
+module CanHasState
+  class Railtie < Rails::Railtie
+
+    initializer "can_has_state" do |app|
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.send :include, CanHasState::Machine
+      end
+    end
+
+  end
+end

data/lib/can_has_state/version.rb

@@ -0,0 +1,3 @@
+module CanHasState
+  VERSION = "0.2.0"
+end

data/lib/can_has_state.rb

@@ -0,0 +1,7 @@
+require 'active_support'
+require 'active_model'
+
+require 'can_has_state/definition'
+require 'can_has_state/machine'
+
+require 'can_has_state/railtie' if defined?(Rails)

data/lib/tasks/can_has_state_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :can_has_state do
+#   # Task goes here
+# end

data/test/can_has_state_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class CanHasStateTest < ActiveSupport::TestCase
+  test "truth" do
+    assert_kind_of Module, CanHasState
+  end
+end