stator 0.0.13

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.ruby-gemset

@@ -0,0 +1 @@
+stator

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p194

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - 2.0.0
+
+gemfile:
+  - gemfiles/ar30.gemfile
+  - gemfiles/ar31.gemfile
+  - gemfiles/ar32.gemfile
+  - gemfiles/ar40.gemfile
+
+matrix:
+  exclude:
+    - rvm: 1.8.7
+      gemfile: gemfiles/ar40.gemfile

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stator.gemspec
+gem 'activerecord', '4.0.0'
+
+gemspec
+
+gem 'rake'
+gem 'activerecord-nulldb-adapter', :require => false, :git => 'git@github.com:nulldb/nulldb.git', :ref => 'ffc7dae4697c6b9fb15bed9edca3acb1f00eb5f0'
+gem 'rspec'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Mike Nelson
+
+MIT License
+
+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,203 @@
+# Stator
+
+Stator is a minimalist's state machine. It's a simple dsl that uses existing ActiveRecord functionality to accomplish common state machine functionality. This is not a full-featured computer-science driven gem, it's a gem that covers the 98% of use cases that I've run into.
+
+```ruby
+gem 'stator', github: 'mnelson/stator', tag: 'v0.0.1'
+```
+
+## Usage
+
+If you've used the state_machine it's a pretty similar dsl. You define your state machine, transitions, states, and your callbacks (if any). One difference is that stator assumes you've set your db column to the initial state.
+
+```ruby
+  class User < ActiveRecord::Base
+    extend Stator::Model
+
+    stator do
+
+      transition :semiactivate do
+        from :unactivated
+        to   :semiactivated
+      end
+
+      transition :activate do
+        from :unactivated, :semiactivated
+        to   :activated
+      end
+
+      transition :deactivate do
+        from any
+        to   :deactivate
+      end
+
+    end
+  end
+```
+
+Then you use like this:
+
+```ruby
+u = User.new
+u.state
+# => 'unactivated'
+u.persisted?
+# => false
+u.semiactivate
+# => true
+u.state
+# => 'semiactivated'
+u.persisted?
+# => true
+```
+
+## Advanced Usage
+
+The intention of stator was to avoid hijacking ActiveRecord or reinvent the wheel. You can conditionally validate, invoke callbacks, etc. via a conditional block - no magic:
+
+```ruby
+class User < ActiveRecord::Base
+  extend Stator::Model
+
+  stator field: :status, track: true do
+
+    transition :activate do
+      from :unactivated
+      to   :activated
+
+      # conditions is a string condition which will ensure the state
+      # was one of the `from` states and is one of the `to` states.
+      conditional do |conditions|
+        validate :validate_user_ip_not_blacklisted, if: conditions
+      end
+
+    end
+
+    # conditions is a string condition which will ensure the state
+    # is one of the ones provided.
+    conditional :unactivated do |conditions|
+      validates :email, presence: true, unless: conditions
+    end
+
+  end
+end
+```
+
+Within a transition, the `conditional` block accepts a `use_previous` option which tells the state checks to use the record's previous_changes rather than the current changes. This is especially useful for after_commit scenarios where the record's changes hash is cleared before the execution begins.
+
+```ruby
+transition :activate do
+  from :unactivated
+  to   :activated
+
+  conditional(use_previous: true) do |conditions|
+    after_commit :send_things, if: conditions
+  end
+```
+
+The instance has some convenience methods which are generated by the state machine:
+
+```ruby
+u = User.new
+u.activated?
+# => false
+u.can_activate?
+# => true
+```
+
+Note that asking if a transition can take place via `can_[transition_name]?` does not invoke validations. It simply determines whether the record is in a state which the transition can take place from.
+
+
+The `track: true` option enables timekeeping of the state transition. It will try to set a field in the format of "state_field_at" before saving the record. For example, in the previous state machine the following would occur:
+
+```ruby
+u = User.new
+u.activate
+
+u.activated_status_at
+  # => (now)
+```
+
+You can have multiple state machines for your model:
+
+```ruby
+
+class User < ActiveRecord::Base
+  extend Stator::Model
+
+  # initial state = asleep
+  stator do
+    # wake up
+  end
+
+  # initial state = incomplete
+  stator namespace: 'homework', field: 'homework_state' do
+    # get it done
+  end
+end
+```
+
+
+If you need to access the state machine directly, you can do so via the class:
+
+```ruby
+User._stator(namespace)
+```
+
+#### Aliasing
+
+It's a really common case to have a set of states evaluated as a single concept. For example, many apps have a concept of "active" users. You generally see something like this:
+
+```ruby
+class User < ActiveRecord::Base
+  ACTIVE_STATES = %w(semiactivated activated)
+
+  scope :active, -> { where(state: ACTIVE_STATES) }
+
+  def active?
+    self.state.in?(ACTIVE_STATES)
+  end
+end
+```
+
+To this point, we're doing ok. But how about defining inactive as well? At this point things start getting a little dirtier since a change to ACTIVE_STATES should impact INACTIVE_STATES. For this reason, stator allows you to define state aliases:
+
+```ruby
+class User < ActiveRecord::Base
+  extend Stator::Model
+
+  stator do
+    # forgoing state definitions...
+
+    state_alias :active do
+      is :semiactivated, :activated
+      opposite :inactive
+    end
+  end
+end
+```
+
+The provided example will define an `active?` and `inactive?` method. If you want to create the constant and/or the scope, just pass them as options to the state_alias method:
+
+```ruby
+# will generate a User::ACTIVE_STATES constant, User.active scope, and User#active? instance method
+state_alias :active, scope: true, constant: true do
+  # ...
+end
+```
+
+Passing `true` for the scope or constant will result in default naming conventions. You can pass your own names if you'd rather:
+
+```ruby
+# will generate a User::THE_ACTIVE_STATES constant, User.the_active_ones scope, and User#active? instance method
+state_alias :active, scope: :the_active_ones, constant: :the_active_states do
+  # ...
+end
+```
+
+The `opposite` method also accepts the scope and constant options, but does not yield to a block since the state definitions are inheritenly tied to the ones described in the parent state_alias block.
+
+#### TODO
+
+* Allow for multiple variations of a transition (shift_down style - :third_gear => :second_gear, :second_gear => :first_gear)
+* Create adapters for different backends (not just ActiveRecord)

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require 'rake'
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/*_spec.rb'
+end
+task :default  => :spec

data/gemfiles/ar30.gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stator.gemspec
+gem 'activerecord', '3.0.20'
+
+gemspec :path => '../'
+
+gem 'rake'
+gem 'activerecord-nulldb-adapter', :require => false
+gem 'rspec'

data/gemfiles/ar31.gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stator.gemspec
+gem 'activerecord', '3.1.12'
+
+gemspec :path => '../'
+
+gem 'rake'
+gem 'activerecord-nulldb-adapter', :require => false
+gem 'rspec'

data/gemfiles/ar32.gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stator.gemspec
+gem 'activerecord', '3.2.13'
+
+gemspec :path => '../'
+
+gem 'rake'
+gem 'activerecord-nulldb-adapter', :require => false
+gem 'rspec'

data/gemfiles/ar40.gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stator.gemspec
+gem 'activerecord', '4.0.0'
+
+gemspec :path => '../'
+
+gem 'rake'
+gem 'activerecord-nulldb-adapter', :require => false, :github => 'nulldb/nulldb', :ref => 'ffc7dae4697c6b9fb15bed9edca3acb1f00eb5f0'
+gem 'rspec'

data/lib/stator/alias.rb

@@ -0,0 +1,81 @@
+module Stator
+  class Alias
+
+    def initialize(machine, name, options = {})
+      @machine    = machine
+      @name       = name
+      @namespace  = @machine.namespace
+      @full_name  = [@namespace, @name].compact.join('_')
+      @states     = []
+      @not        = false
+      @opposite   = nil
+      @constant   = options[:constant]
+      @scope      = options[:scope]
+    end
+
+    def is(*args)
+      @states |= args.map(&:to_s)
+    end
+
+    def is_not(*args)
+      @not = true
+      is(*args)
+    end
+
+    def opposite(*args)
+      @opposite = args
+    end
+
+    def evaluate
+      generate_methods
+
+      if @opposite
+        op = @machine.state_alias(*@opposite)
+
+        op.is(*@states)     if @not
+        op.is_not(*@states) if !@not
+      end
+    end
+
+    protected
+
+    def inferred_constant_name
+      [@full_name.upcase, @machine.field.to_s.pluralize.upcase].join('_')
+    end
+
+    def generate_methods
+
+      not_states = (@machine.states - @states)
+
+      if @scope
+        name = @scope == true ? @full_name : @scope
+        @machine.klass.class_eval <<-EV, __FILE__, __LINE__ + 1
+          scope #{name.inspect}, lambda {
+            where(_stator(#{@namespace.inspect}).field => #{(@not ? not_states : @states).inspect})
+          }
+        EV
+      end
+
+      if @constant
+        name = @constant == true ? inferred_constant_name : @constant.to_s.upcase
+        if @not
+          @machine.klass.class_eval <<-EV, __FILE__, __LINE__ + 1
+            #{name} = #{not_states.inspect}.freeze
+          EV
+        else
+          @machine.klass.class_eval <<-EV, __FILE__, __LINE__ + 1
+            #{name} = #{@states.inspect}.freeze
+          EV
+        end
+      end
+
+      @machine.klass.class_eval <<-EV, __FILE__, __LINE__ + 1
+        def #{@full_name}?
+          integration = _stator(#{@namespace.inspect}).integration(self)
+          #{(@not ? not_states : @states).inspect}.include?(integration.state)
+        end
+      EV
+    end
+
+  end
+end

data/lib/stator/integration.rb

@@ -0,0 +1,82 @@
+module Stator
+  class Integration
+
+    delegate :states,       :to => :@machine
+    delegate :transitions,  :to => :@machine
+    delegate :namespace,    :to => :@machine
+
+    def initialize(machine, record)
+      @machine = machine
+      @record  = record
+    end
+
+
+
+
+    def state=(new_value)
+      @record.send("#{@machine.field}=",  new_value)
+    end
+
+    def state
+      @record.send(@machine.field)
+    end
+
+
+    def state_was(use_previous = false)
+      if use_previous
+        @record.previous_changes[@machine.field.to_s].try(:[], 0)
+      else
+        @record.send("#{@machine.field}_was")
+      end
+    end
+
+
+    def state_changed?
+      @record.send("#{@machine.field}_changed?")
+    end
+
+
+
+    def validate_transition
+      return unless self.state_changed?
+
+      was = self.state_was
+      is  = self.state
+
+      if @record.new_record?
+        unless @machine.matching_transition(::Stator::Transition::ANY, is)
+          @record.errors.add(@machine.field, "is not a valid state")
+        end
+      else
+        unless @machine.matching_transition(was, is)
+          @record.errors.add(@machine.field, "cannot transition to #{is.inspect} from #{was.inspect}")
+        end
+      end
+    end
+
+    def track_transition
+      self.attempt_to_track_state(self.state_was)
+      self.attempt_to_track_state(self.state)
+
+      true
+    end
+
+
+    protected
+
+    def attempt_to_track_state(state_to_track)
+      return unless state_to_track
+
+      field_name = "#{state_to_track}_#{@machine.field}_at"
+
+      return unless @record.respond_to?(field_name)
+      return unless @record.respond_to?("#{field_name}=")
+
+      unless @record.send(field_name)
+        @record.send("#{field_name}=", (Time.zone || Time).now)
+      end
+    end
+
+
+  end
+end

data/lib/stator/machine.rb

@@ -0,0 +1,123 @@
+module Stator
+  class Machine
+
+    attr_reader :initial_state
+    attr_reader :field
+    attr_reader :transition_names
+    attr_reader :transitions
+    attr_reader :states
+    attr_reader :namespace
+
+
+    def initialize(klass, options = {})
+      @class_name    = klass.name
+      @field         = options[:field] || :state
+      @namespace     = options[:namespace] || nil
+
+      # rescue nil since the table may not exist yet.
+      @initial_state = klass.columns_hash[@field.to_s].default rescue nil
+
+      @transitions      = []
+      @aliases          = []
+
+      # pushed out into their own variables for performance reasons (AR integration can use method missing - see the HelperMethods module)
+      @transition_names = []
+      @states           = [@initial_state].compact
+
+      @options       = options
+
+    end
+
+    def integration(record)
+      ::Stator::Integration.new(self, record)
+    end
+
+    def get_transition(name)
+      @transitions.detect{|t| t.name.to_s == name.to_s}
+    end
+
+    def transition(name, &block)
+
+      t = ::Stator::Transition.new(@class_name, name, @namespace)
+      t.instance_eval(&block) if block_given?
+
+      verify_transition_validity(t)
+
+      @transitions      << t
+      @transition_names |= [t.full_name]  unless t.full_name.blank?
+      @states           |= [t.to_state]   unless t.to_state.nil?
+
+      t
+    end
+
+    def state_alias(name, options = {}, &block)
+      a = ::Stator::Alias.new(self, name, options)
+      a.instance_eval(&block) if block_given?
+      @aliases << a
+      a
+    end
+
+    def state(name, &block)
+      transition(nil) do
+        from any
+        to name
+        instance_eval(&block) if block_given?
+      end
+    end
+
+    def conditional(*states, &block)
+      klass.instance_exec("#{states.map(&:to_s).inspect}.include?(self._stator(#{@namespace.inspect}).integration(self).state)", &block)
+    end
+
+    def matching_transition(from, to)
+      @transitions.detect do |transition|
+        transition.valid?(from, to)
+      end
+    end
+
+    def evaluate
+      @transitions.each(&:evaluate)
+      @aliases.each(&:evaluate)
+      generate_methods
+    end
+
+    def klass
+      @class_name.constantize
+    end
+
+    protected
+
+    def verify_transition_validity(transition)
+      verify_state_singularity_of_transition(transition)
+      verify_name_singularity_of_transition(transition)
+    end
+
+    def verify_state_singularity_of_transition(transition)
+      transition.from_states.each do |from|
+        if other = matching_transition(from, transition.to_state)
+          raise "[Stator] another transition already exists which moves #{@class_name} from #{from.inspect} to #{transition.to_state.inspect}"
+        end
+      end
+    end
+
+    def verify_name_singularity_of_transition(transition)
+      if other = @transitions.detect{|other| transition.name && transition.name == other.name }
+        raise "[Stator] another transition already exists with the name of #{transition.name.inspect} in the #{@class_name} class"
+      end
+    end
+
+    def generate_methods
+      self.states.each do |state|
+        method_name = [@namespace, state].compact.join('_')
+        klass.class_eval <<-EV, __FILE__, __LINE__ + 1
+          def #{method_name}?
+            integration = self._stator(#{@namespace.inspect}).integration(self)
+            integration.state == #{state.to_s.inspect}
+          end
+        EV
+      end
+    end
+
+
+  end
+end

data/lib/stator/model.rb

@@ -0,0 +1,71 @@
+module Stator
+  module Model
+
+    def stator(options = {}, &block)
+
+      class_attribute :_stators unless respond_to?(:_stators)
+
+      include InstanceMethods   unless self.included_modules.include?(InstanceMethods)
+      include TrackerMethods    if options[:track] == true
+
+      self._stators ||= {}
+      machine = (self._stators[options[:namespace].to_s] ||= ::Stator::Machine.new(self, options))
+
+      if block_given?
+        machine.instance_eval(&block)
+        machine.evaluate
+      end
+
+      machine
+    end
+
+    def _stator(namespace)
+      self._stators[namespace.to_s]
+    end
+
+    module TrackerMethods
+
+      def self.included(base)
+        base.class_eval do
+          before_save :_stator_track_transition
+        end
+      end
+
+
+      protected
+
+
+      def _stator_track_transition
+
+        self._stators.each do |namespace, machine|
+          machine.integration(self).track_transition
+        end
+
+        true
+      end
+
+    end
+
+    module InstanceMethods
+
+      def self.included(base)
+        base.class_eval do
+          validate :_stator_validate_transition
+        end
+      end
+
+      protected
+
+      def _stator_validate_transition
+        self._stators.each do |namespace, machine|
+          machine.integration(self).validate_transition
+        end
+      end
+
+      def _stator(namespace)
+        self.class._stator(namespace)
+      end
+
+    end
+  end
+end