stator 0.0.13

data/lib/stator/transition.rb

@@ -0,0 +1,103 @@
+module Stator
+  class Transition
+
+    ANY = '__any__'
+
+    attr_reader :name
+    attr_reader :full_name
+
+    def initialize(class_name, name, namespace = nil)
+      @class_name = class_name
+      @name       = name
+      @namespace  = namespace
+      @full_name  = [@namespace, @name].compact.join('_') if @name
+      @froms      = []
+      @to         = nil
+      @callbacks  = {}
+    end
+
+    def from(*froms)
+      @froms |= froms.map{|f| f.try(:to_s) } # nils are ok
+    end
+
+    def to(to)
+      @to = to.to_s
+    end
+
+    def to_state
+      @to
+    end
+
+    def from_states
+      @froms
+    end
+
+    def can?(current_state)
+      @froms.include?(current_state) || @froms.include?(ANY) || current_state == ANY
+    end
+
+    def valid?(from, to)
+      can?(from) &&
+      (@to == to || @to == ANY || to == ANY)
+    end
+
+    def conditional(options = {}, &block)
+      klass.instance_exec(conditional_string(options), &block)
+    end
+
+    def any
+      ANY
+    end
+
+    def evaluate
+      generate_methods unless @full_name.blank?
+    end
+
+    protected
+
+    def klass
+      @class_name.constantize
+    end
+
+    def callbacks(kind)
+      @callbacks[kind] || []
+    end
+
+    def conditional_string(options = {})
+      options[:use_previous] ||= false
+      %Q{
+          (
+            #{@froms.inspect}.include?(self._stator(#{@namespace.inspect}).integration(self).state_was(#{options[:use_previous].inspect})) ||
+            #{@froms.inspect}.include?(::Stator::Transition::ANY)
+          ) && (
+            self._stator(#{@namespace.inspect}).integration(self).state == #{@to.inspect} ||
+            #{@to.inspect} == ::Stator::Transition::ANY
+          )
+        }
+    end
+
+    def generate_methods
+      klass.class_eval <<-EV, __FILE__, __LINE__ + 1
+        def #{@full_name}(should_save = true)
+          integration = self._stator(#{@namespace.inspect}).integration(self)
+          integration.state = #{@to.inspect}
+          self.save if should_save
+        end
+
+        def #{@full_name}!
+          integration = self._stator(#{@namespace.inspect}).integration(self)
+          integration.state = #{@to.inspect}
+          self.save!
+        end
+
+        def can_#{@full_name}?
+          machine     = self._stator(#{@namespace.inspect})
+          integration = machine.integration(self)
+          transition  = machine.transitions.detect{|t| t.full_name.to_s == #{@full_name.inspect}.to_s }
+          transition.can?(integration.state)
+        end
+      EV
+    end
+
+  end
+end

data/lib/stator/version.rb

@@ -0,0 +1,8 @@
+module Stator
+  MAJOR       = 0
+  MINOR       = 0
+  PATCH       = 13
+  PRERELEASE  = nil
+
+  VERSION = [MAJOR, MINOR, PATCH, PRERELEASE].compact.join('.')
+end

data/lib/stator.rb

@@ -0,0 +1,11 @@
+require "stator/version"
+
+module Stator
+
+  autoload :Alias,        'stator/alias'
+  autoload :Integration,  'stator/integration'
+  autoload :Machine,      'stator/machine'
+  autoload :Model,        'stator/model'
+  autoload :Transition,   'stator/transition'
+
+end

data/spec/model_spec.rb

@@ -0,0 +1,214 @@
+require 'spec_helper'
+
+describe Stator::Model do
+
+  it 'should set the default state after initialization' do
+    u = User.new
+    u.state.should eql('pending')
+  end
+
+  it 'should see the initial setting of the state as a change with the initial state as the previous value' do
+    u = User.new
+    u.state = 'activated'
+    u.state_was.should eql('pending')
+  end
+
+  it 'should not obstruct normal validations' do
+    u = User.new
+    u.should_not be_valid
+    u.errors[:email].grep(/length/).should_not be_empty
+  end
+
+  it 'should ensure a valid state transition when given a bogus state' do
+    u = User.new
+    u.state = 'anythingelse'
+
+    u.should_not be_valid
+    u.errors[:state].should eql(['is not a valid state'])
+  end
+
+  it 'should allow creation at any state' do
+    u = User.new(:email => 'doug@example.com')
+    u.state = 'hyperactivated'
+
+    u.should be_valid
+  end
+
+  it 'should ensure a valid state transition when given an illegal state based on the current state' do
+    u = User.new
+    u.stub(:new_record?).and_return(false)
+    u.state = 'hyperactivated'
+
+    u.should_not be_valid
+    u.errors[:state].should_not be_empty
+
+  end
+
+  it 'should run conditional validations' do
+    u = User.new
+    u.state = 'semiactivated'
+    u.should_not be_valid
+
+    u.errors[:state].should be_empty
+    u.errors[:email].grep(/format/).should_not be_empty
+  end
+
+  it 'should invoke callbacks' do
+    u = User.new(:activated => true, :email => 'doug@example.com', :name => 'doug')
+    u.activated.should == true
+
+    u.deactivate
+
+    u.activated.should == false
+    u.state.should eql('deactivated')
+    u.activated_state_at.should be_nil
+    u.should be_persisted
+  end
+
+  it 'should blow up if the record is invalid and a bang method is used' do
+    u = User.new(:email => 'doug@other.com', :name => 'doug')
+    lambda{
+      u.activate!
+    }.should raise_error(ActiveRecord::RecordInvalid)
+  end
+
+  it 'should allow for other fields to be used other than state' do
+    a = Animal.new
+    a.should be_valid
+
+    a.birth!
+  end
+
+  it 'should create implicit transitions for state declarations' do
+    a = Animal.new
+    a.should_not be_grown_up
+    a.status = 'grown_up'
+    a.save
+  end
+
+  it 'should allow multiple machines in the same model' do
+    f = Farm.new
+    f.should be_dirty
+    f.should be_house_dirty
+
+    f.cleanup
+
+    f.should_not be_dirty
+    f.should be_house_dirty
+
+    f.house_cleanup
+
+    f.should_not be_house_dirty
+  end
+
+  it 'should allow saving to be skipped' do
+    f = Farm.new
+    f.cleanup(false)
+
+    f.should_not be_persisted
+  end
+
+  it 'should allow no initial state' do
+    f = Factory.new
+    f.state.should be_nil
+
+    f.construct.should be_true
+
+    f.state.should eql('constructed')
+  end
+
+  describe 'helper methods' do
+
+    it 'should answer the question of whether the state is currently the one invoked' do
+      a = Animal.new
+      a.should be_unborn
+      a.should_not be_born
+
+      a.birth
+
+      a.should be_born
+      a.should_not be_unborn
+    end
+
+    it 'should determine if it can validly execute a transition' do
+      a = Animal.new
+      a.can_birth?.should be_true
+
+      a.birth
+
+      a.can_birth?.should be_false
+    end
+
+  end
+
+  describe 'tracker methods' do
+
+    before do
+      Time.zone = 'Eastern Time (US & Canada)'
+    end
+
+    it 'should store when a record changed state for the first time' do
+      a = Animal.new
+      a.unborn_status_at.should be_nil
+      a.born_status_at.should be_nil
+      a.birth
+      a.unborn_status_at.should be_within(1).of(Time.zone.now)
+      a.born_status_at.should be_within(1).of(Time.zone.now)
+    end
+
+  end
+
+  describe 'aliasing' do
+    it 'should allow aliasing within the dsl' do
+      u = User.new(:email => 'doug@example.com')
+      u.should respond_to(:active?)
+      u.should respond_to(:inactive?)
+
+      u.should_not be_active
+
+      u.inactive?
+      u.should be_inactive
+
+      u.activate!
+      u.should be_active
+      u.should_not be_inactive
+
+      u.hyperactivate!
+      u.should be_active
+      u.should_not be_inactive
+
+      User::ACTIVE_STATES.should eql(['activated', 'hyperactivated'])
+      User::INACTIVE_STATES.should eql(['pending', 'deactivated', 'semiactivated'])
+
+      u2 = User.create(:email => 'phil@example.com')
+
+      User.active.to_sql.gsub('  ', ' ').should eq("SELECT users.* FROM users WHERE users.state IN ('activated', 'hyperactivated')")
+      User.inactive.to_sql.gsub('  ', ' ').should eq("SELECT users.* FROM users WHERE users.state IN ('pending', 'deactivated', 'semiactivated')")
+    end
+
+    it 'should namespace aliases just like everything else' do
+      f = Farm.new
+      f.should respond_to(:house_cleaned?)
+
+      f.should_not be_house_cleaned
+      f.house_cleanup!
+
+      f.should be_house_cleaned
+    end
+
+    it 'should allow for explicit constant and scope names to be provided' do
+      User.should respond_to(:luke_warmers)
+      defined?(User::LUKE_WARMERS).should be_true
+      u = User.new
+      u.should respond_to(:luke_warm?)
+    end
+
+    it 'should not create constants or scopes by default' do
+      u = User.new
+      u.should respond_to(:iced_tea?)
+      defined?(User::ICED_TEA_STATES).should be_false
+      User.should_not respond_to(:iced_tea)
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,34 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'active_record'
+require 'nulldb/core'
+require 'active_support/core_ext'
+require 'stator'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  NullDB.configure do |c|
+    c.project_root = File.dirname(__FILE__)
+  end
+
+  ActiveRecord::Base.establish_connection(
+    :adapter => :nulldb,
+    :schema  => 'support/schema.rb'
+  )
+
+  require 'support/models'
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/spec/support/models.rb

@@ -0,0 +1,177 @@
+class User < ActiveRecord::Base
+  extend Stator::Model
+
+
+  # initial state = pending
+  stator do
+
+    transition :activate do
+      from :pending, :semiactivated
+      to :activated
+    end
+
+    transition :deactivate do
+      from any
+      to :deactivated
+
+      conditional do |condition|
+        before_save :set_deactivated, :if => condition
+      end
+    end
+
+    transition :semiactivate do
+      from :pending
+      to :semiactivated
+
+      conditional do |condition|
+        validate :check_email_validity, :if => condition
+      end
+    end
+
+    transition :hyperactivate do
+      from :activated
+      to :hyperactivated
+    end
+
+    conditional :semiactivated, :activated do |condition|
+      validate :check_email_presence, :if => condition
+    end
+
+    state_alias :active, :constant => true, :scope => true do
+      is :activated, :hyperactivated
+      opposite :inactive, :constant => true, :scope => true
+    end
+
+    state_alias :luke_warm, :constant => :luke_warmers, :scope => :luke_warmers do
+      is :semiactivated
+      opposite :iced_tea
+    end
+
+  end
+
+  validate :email_is_right_length
+
+  protected
+
+  def check_email_presence
+    unless self.email.present?
+      self.errors.add(:email, 'needs to be present')
+      return false
+    end
+
+    true
+  end
+
+  def check_email_validity
+    unless self.email.to_s =~ /example\.com$/
+      self.errors.add(:email, 'format needs to be example.com')
+      return false
+    end
+
+    true
+  end
+
+  def email_is_right_length
+    unless self.email.to_s.length == 'four@example.com'.length
+      self.errors.add(:email, 'needs to be the right length')
+      return false
+    end
+
+    true
+  end
+
+  def set_deactivated
+    self.activated = false
+    true
+  end
+
+end
+
+class Animal < ActiveRecord::Base
+  extend Stator::Model
+
+  # initial state = unborn
+  stator :field => :status, :helpers => true, :track => true do
+
+    transition :birth do
+      from :unborn
+      to :born
+    end
+
+    state :grown_up
+
+  end
+end
+
+class Zoo < ActiveRecord::Base
+  extend Stator::Model
+
+  # initial state = closed
+  stator do
+
+    transition :open do
+      from :closed
+      to :opened
+    end
+
+    transition :close do
+      from  :opened
+      to    :closed
+    end
+
+    conditional :opened do |c|
+      validate :validate_lights_are_on, :if => c
+    end
+  end
+
+  protected
+
+  def validate_lights_are_on
+    true
+  end
+end
+
+
+class Farm < ActiveRecord::Base
+  extend Stator::Model
+
+  # initial state = dirty
+  stator do
+    transition :cleanup do
+     from :dirty
+     to :clean
+    end
+  end
+
+
+  # initial state = dirty
+  stator :field => 'house_state', :namespace => 'house' do
+    transition :cleanup do
+      from :dirty
+      to :clean
+    end
+
+    state_alias :cleaned do
+      is_not :dirty
+    end
+  end
+
+end
+
+class Factory < ActiveRecord::Base
+  extend Stator::Model
+
+  # initial state = nil
+  stator do
+    transition :construct do
+      from nil
+      to :constructed
+    end
+
+    transition :destruct do
+      from :constructed
+      to :on_the_ground
+    end
+  end
+
+end

data/spec/support/schema.rb

@@ -0,0 +1,43 @@
+ActiveRecord::Schema.define(:version => 20130628161227) do
+
+  create_table "users", :force => true do |t|
+    t.string   "name"
+    t.string   "email"
+    t.string   "state",                                 :default => 'pending'
+    t.boolean  "activated",                             :default => true
+    t.datetime "created_at",                            :null => false
+    t.datetime "updated_at",                            :null => false
+    t.datetime "semiactivated_state_at"
+    t.datetime "activated_state_at"
+  end
+
+  create_table "animals", :force => true do |t|
+    t.string   "name"
+    t.string   "status",                                :default => 'unborn'
+    t.datetime "created_at",                            :null => false
+    t.datetime "updated_at",                            :null => false
+    t.datetime "unborn_status_at"
+    t.datetime "born_status_at"
+  end
+
+  create_table "zoos", :force => true do |t|
+    t.string   "name"
+    t.string   "state",                                 :default => 'closed'
+    t.datetime "created_at",                            :null => false
+    t.datetime "updated_at",                            :null => false
+  end
+
+  create_table "farms", :force => true do |t|
+    t.string   "name"
+    t.string   "state",                                 :default => 'dirty'
+    t.string   "house_state",                           :default => 'dirty'
+    t.datetime "created_at",                            :null => false
+    t.datetime "updated_at",                            :null => false
+  end
+
+  create_table "factories", :force => true do |t|
+    t.string "name"
+    t.string "state"
+  end
+
+end

data/stator.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stator/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "stator"
+  gem.version       = Stator::VERSION
+  gem.authors       = ["Mike Nelson"]
+  gem.email         = ["mike@mikeonrails.com"]
+  gem.description   = %q{The simplest of ActiveRecord state machines. Intended to be lightweight and minimalistic.}
+  gem.summary       = %q{The simplest of ActiveRecord state machines}
+  gem.homepage      = "http://www.mikeonrails.com"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'activerecord'
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: stator
+version: !ruby/object:Gem::Version
+  version: 0.0.13
+  prerelease: 
+platform: ruby
+authors:
+- Mike Nelson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: The simplest of ActiveRecord state machines. Intended to be lightweight
+  and minimalistic.
+email:
+- mike@mikeonrails.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .ruby-gemset
+- .ruby-version
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- gemfiles/ar30.gemfile
+- gemfiles/ar31.gemfile
+- gemfiles/ar32.gemfile
+- gemfiles/ar40.gemfile
+- lib/stator.rb
+- lib/stator/alias.rb
+- lib/stator/integration.rb
+- lib/stator/machine.rb
+- lib/stator/model.rb
+- lib/stator/transition.rb
+- lib/stator/version.rb
+- spec/model_spec.rb
+- spec/spec_helper.rb
+- spec/support/models.rb
+- spec/support/schema.rb
+- stator.gemspec
+homepage: http://www.mikeonrails.com
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: The simplest of ActiveRecord state machines
+test_files:
+- spec/model_spec.rb
+- spec/spec_helper.rb
+- spec/support/models.rb
+- spec/support/schema.rb