statelogic 1.1

data/CHANGELOG

@@ -0,0 +1,8 @@
+1.1 - 2009-08-11
+- adds finder methods in the form of find_all_#{state}(*args)
+- adds named scope named after corresponding state
+- no longer redefines existing methods with the same names, issues warnings instead
+- forces state names to underscore notation when used as part of method/scope names
+
+0.1.2 - 2009-01-10
+- Support scoping arbitrary callbacks beyond ActiveRecord's

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [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.rdoc

@@ -0,0 +1,81 @@
+=== Introduction
+Statelogic is a yet another take on state management for your models.
+It's tailored specially for ActiveRecord and is different from other
+frameworks in that it has its main goal in scoping validation rules and
+callbacks depending on the model's state to emphasis _actual_ model state
+consistency over merely formal... whatever...
+
+=== Features
+- State transitions validation.
+- State-scoped validations.
+- State-scoped lifecycle callbacks (before|after_save, etc)
+- ???????
+- PROFIT!!!11
+
+=== Changes in v1.1
+_Please review these carefully as they may be incompatible with your existing code._
+- adds finder methods in the form of +find_all_#{state}(*args)+ (Order.find_all_ready) sugg. by ares
+- adds named scope named after corresponding state (Order.paid) sugg. by ares
+- no longer redefines existing methods with the same names, issues warnings instead
+- forces state names to underscore notation when used as part of method names
+
+=== Installation
+  gem install omg-statelogic --source http://gems.github.com
+
+Installable as a plugin too.
+
+=== Docs
+http://rdoc.info/projects/omg/statelogic
+
+=== Bugs & such
+Please report via Github issue tracking.
+
+=== Example
+    class Order < ActiveRecord::Base
+      ...
+      statelogic :attribute => :state do # +:state+ is the default value, may be omitted
+        # you get methods +unpaid?+ and +was_unpaid?+.
+        # may be more than one initial state.
+        initial_state 'unpaid' do
+          transitions_to 'ready', 'suspended' # won't let you change to wrong states
+        end
+        state 'ready' do # you get +ready?+, +was_ready?+, +Order.ready+ named scope and +Order.find_all_ready+ finder
+          transitions_to 'redeemed', 'suspended'
+          validates_presence_of :txref # scoped validations
+          before_save :prepare_for_plucking # scoped callbacks
+        end
+        state 'redeemed' do # likewise
+          transitions_to 'suspended'
+          validates_presence_of :txref, :redeemed_at, :facility_id # scoped validations
+        end
+        state 'suspended' do # you guess
+          transitions_to 'unpaid', 'ready', 'redeemed'
+          validate do |order|
+            order.errors.add(:txref, :invalid) if order.txref && order.txref !~ /\AREF/
+          end
+        end
+      end
+      ...
+    end
+
+    order = Order.new
+    order.state = 'wtf'
+    order.txref = 'orly'
+    order.valid? # Please note that state transition checks are done during
+                 # the validation step as well, and the error is added to
+                 # the model's +errors+ collection on the state column and
+                 # will appear on your form. Standard ActiveRecord's error
+                 # message +:inclusion+ is used. Override it with Rails i18n
+                 # for something more specific if it's to be displayed to user.
+
+
+=== See also
+* http://github.com/omg/threadpool -- Thread pool implementation
+* http://github.com/omg/peanuts -- Ruby <-> XML mapping
+
+
+Hint: If you feel like generous today you can tip me at http://tipjoy.com/u/pisuka
+
+
+Copyright (c) 2009 Igor Gunko, released under the MIT license
+

data/Rakefile

@@ -0,0 +1,32 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test Statelogic'
+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 Statelogic.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  files =['README.rdoc', 'CHANGELOG', 'MIT-LICENSE', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "Statelogic Documentation"
+  rdoc.rdoc_dir = 'doc/rdoc' # rdoc output folder
+  rdoc.options << '--line-numbers' << '--inline-source'
+end
+
+Rake::GemPackageTask.new(Gem::Specification.load('statelogic.gemspec')) do |p|
+  p.need_tar = true
+  p.need_zip = true
+end
+

data/lib/omg-statelogic.rb

@@ -0,0 +1 @@
+require 'statelogic'

data/lib/statelogic/activerecord.rb

@@ -0,0 +1,119 @@
+require 'statelogic/callbacks_ext' unless ([ActiveRecord::VERSION::MAJOR, ActiveRecord::VERSION::MINOR] <=> [2, 3]) >= 0
+
+module Statelogic
+  module Util
+    def self.debug(msg = nil, &block)
+      ::ActiveRecord::Base.logger.debug(msg, &block) if ::ActiveRecord::Base.logger
+    end
+
+    def self.warn(msg = nil, &block)
+      ::ActiveRecord::Base.logger.warn(msg, &block) if ::ActiveRecord::Base.logger
+    end
+
+    def self.defmethod(cls, name, meta = false, &block)
+      c = meta ? cls.metaclass : cls
+      unless c.method_defined?(name)
+        c.send(:define_method, name, &block)
+        Util.debug { "Statelogic created #{meta ? 'class' : 'instance'} method #{name} on #{cls.name}." }
+      else
+        warn { "Statelogic won't override #{meta ? 'class' : 'instance'} method #{name} already defined on #{cls.name}." }
+        nil
+      end
+    end
+  end
+    
+  module ActiveRecord
+    def self.included(other)
+      other.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      DEFAULT_OPTIONS = {:attribute => :state}.freeze
+
+      class StateScopeHelper
+        MACROS_PATTERN = /\Avalidates_/.freeze
+
+        def initialize(cl, state, config)
+          @class, @state, @config = cl, state, config
+        end
+
+        def validates_transition_to(*states)
+          attr = @config[:attribute]
+          options = states.extract_options!.update(
+            :in => states,
+            :if => [:"#{attr}_changed?", :"was_#{@state}?"]
+          )
+          @class.validates_inclusion_of(attr, options)
+        end
+
+        alias transitions_to validates_transition_to
+
+        def method_missing(method, *args, &block)
+          if method.to_s =~ MACROS_PATTERN || @class.respond_to?("#{method}_callback_chain")
+            options = args.last
+            args.push(options = {}) unless options.is_a?(Hash)
+            options[:if] = Array(options[:if]).unshift(:"#{@state}?")
+            @class.send(method, *args, &block)
+          else
+            super
+          end
+        end
+      end
+
+      class ConfigHelper
+        def initialize(cl, config)
+          @class, @config = cl, config
+        end
+
+        def initial_state(name, options = {}, &block)
+          state(name, options.update(:initial => true), &block)
+        end
+        
+        alias initial initial_state
+
+        def state(name, options = {}, &block)
+          name = name.to_s
+          uname = name.underscore
+          attr = @config[:attribute]
+          attr_was = :"#{attr}_was"
+          find_all_by_attr = "find_all_by_#{attr}"
+
+          Util.defmethod(@class, "#{uname}?") { send(attr) == name }
+          Util.defmethod(@class, "was_#{uname}?") { send(attr_was) == name }
+
+          unless @class.respond_to?(name)
+            @class.send(:named_scope, uname, :conditions => {attr.to_sym => name })
+            Util.debug { "Statelogic has defined named scope #{uname} on #{@class.name}." }
+          else
+            Util.warn { "Statelogic won't override class method #{uname} already defined on #{@class.name}." }
+          end
+
+          Util.defmethod(@class, "find_all_#{uname}", true) {|*args| send(find_all_by_attr, name, *args) }
+
+          StateScopeHelper.new(@class, name, @config).instance_eval(&block) if block_given?
+
+          @config[:states] << name
+          @config[:initial] << name if options[:initial]
+        end
+      end
+
+      def statelogic(options = {}, &block)
+        options = DEFAULT_OPTIONS.merge(options)
+        attr = options[:attribute] = options[:attribute].to_sym
+
+        options[:states], options[:initial] = [], Array(options[:initial])
+
+        ConfigHelper.new(self, options).instance_eval(&block)
+
+        initial = [options[:initial], options[:states]].find(&:present?)
+        validates_inclusion_of attr, :in => initial, :on => :create if initial
+
+        const = attr.to_s.pluralize.upcase
+        const_set(const, options[:states].freeze.each(&:freeze)) unless const_defined?(const)
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Statelogic::ActiveRecord
+

data/lib/statelogic/callbacks_ext.rb

@@ -0,0 +1,7 @@
+# :stopdoc:
+class ActiveSupport::Callbacks::Callback
+  def should_run_callback?(*args)
+    [options[:if]].flatten.compact.all? { |a| evaluate_method(a, *args) } &&
+      ![options[:unless]].flatten.compact.any? { |a| evaluate_method(a, *args) }
+  end
+end

data/lib/statelogic.rb

@@ -0,0 +1 @@
+# undisturbed void

data/rails/init.rb

@@ -0,0 +1,2 @@
+require 'statelogic'
+require 'statelogic/activerecord'

data/shoulda_macros/statelogic.rb

@@ -0,0 +1,13 @@
+class Test::Unit::TestCase
+  def self.should_not_require_attributes(*attributes)
+    get_options!(attributes)
+    klass = described_type
+
+    attributes.each do |attribute|
+      should "not require #{attribute} to be set" do
+        assert_good_value(klass, attribute, nil)
+      end
+    end
+  end
+end
+

data/test/fixtures/orders.yml

@@ -0,0 +1,13 @@
+# Read about fixtures at http://ar.rubyonrails.org/classes/Fixtures.html
+
+unpaid:
+  state: unpaid
+
+ready:
+  state: ready
+
+redeemed:
+  state: redeemed
+
+suspended:
+  state: suspended

data/test/schema.rb

@@ -0,0 +1,8 @@
+ActiveRecord::Schema.define do
+  create_table 'orders', :force => true do |t|
+    t.column 'state', :text
+    t.column 'redeemed_at', :datetime
+    t.column 'txref', :string
+    t.references :facility
+  end
+end

data/test/statelogic_test.rb

@@ -0,0 +1,75 @@
+require 'test_helper'
+
+#ActiveRecord::Base.logger = Logger.new(STDERR)
+
+class OrderTest < ActiveSupport::TestCase
+  include ActiveRecord::TestFixtures
+  self.fixture_path = 'test/fixtures'
+
+  fixtures :orders
+  
+  should_have_class_methods :unpaid,          :ready,          :redeemed,          :suspended
+  should_have_class_methods :find_all_unpaid, :find_all_ready, :find_all_redeemed, :find_all_suspended
+
+  should_have_instance_methods :unpaid?,     :ready?,     :redeemed?,     :suspended?
+  should_have_instance_methods :was_unpaid?, :was_ready?, :was_redeemed?, :was_suspended?
+
+  context 'Finders and scopes' do
+    should 'return adequate shit' do
+      for st in %w(unpaid ready redeemed suspended)
+        assert_same_elements Order.find_all_by_state(st), Order.send(st)
+        assert_same_elements Order.find_all_by_state(st), Order.send("find_all_#{st}")
+      end
+    end
+  end
+  
+  should_validate_presence_of :state, :message => default_error_message(:inclusion)
+
+  context 'A fresh order' do
+    subject { Order.new }
+
+    should_allow_values_for :state, 'unpaid'
+    should_not_allow_values_for :state, 'ready', 'redeemed', 'suspended', 'screwed_up',
+      :message => default_error_message(:inclusion)
+    should_not_require_attributes :txref, :redeemed_at, :facility_id
+  end
+
+  context 'An unpaid order' do
+    subject { orders(:unpaid) }
+
+    should_allow_values_for :state, 'unpaid', 'ready', 'suspended'
+    should_not_allow_values_for :state, 'redeemed', 'screwed_up',
+      :message => default_error_message(:inclusion)
+    should_not_require_attributes :txref, :redeemed_at, :facility_id
+  end
+
+  context 'A ready order' do
+    subject { orders(:ready) }
+
+    should_allow_values_for :state, 'ready', 'redeemed', 'suspended'
+    should_not_allow_values_for :state, 'unpaid', 'screwed_up',
+      :message => default_error_message(:inclusion)
+    should_validate_presence_of :txref
+    should_not_require_attributes :redeemed_at, :facility_id
+  end
+
+  context 'A redeemed order' do
+    subject { orders(:redeemed) }
+
+    should_allow_values_for :state, 'redeemed', 'suspended'
+    should_not_allow_values_for :state, 'unpaid', 'ready', 'screwed_up',
+      :message => default_error_message(:inclusion)
+    should_validate_presence_of :txref, :redeemed_at, :facility_id
+  end
+
+  context 'A suspended order' do
+    subject { orders(:suspended) }
+
+    should_allow_values_for :state, 'suspended', 'redeemed', 'ready', 'unpaid'
+    should_not_allow_values_for :state, 'screwed_up', :message => default_error_message(:inclusion)
+    should_allow_values_for :txref, 'REF12345'
+    should_not_allow_values_for :txref, '12345'
+    should_not_require_attributes :txref, :redeemed_at, :facility_id
+  end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'test/unit'
+require 'active_support'
+require 'active_support/test_case'
+require 'active_record'
+require 'shoulda/active_record'
+require 'active_record/fixtures'
+require 'statelogic/activerecord'
+
+require 'shoulda_macros/statelogic'
+
+#ActiveRecord::TestFixtures.fixture_path = 'test/fixtures'
+
+ActiveRecord::Base.configurations = {
+  'test' => {:adapter => 'sqlite3', :dbfile => ':memory:'}
+}
+ActiveRecord::Base.establish_connection(:test)
+
+load 'schema.rb'

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification 
+name: statelogic
+version: !ruby/object:Gem::Version 
+  version: "1.1"
+platform: ruby
+authors: 
+- Igor Gunko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-11 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.10.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.4
+    version: 
+description: "    Statelogic does kinda this and that... you know.\n"
+email: tekmon@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- CHANGELOG
+- MIT-LICENSE
+files: 
+- README.rdoc
+- CHANGELOG
+- MIT-LICENSE
+- Rakefile
+- lib/statelogic.rb
+- lib/omg-statelogic.rb
+- lib/statelogic/activerecord.rb
+- lib/statelogic/callbacks_ext.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/omg/statelogic
+licenses: []
+
+post_install_message: v1.1 introduces changes that may (or may not) be incompatible for you. Please review them at http://github.com/omg/statelogic
+rdoc_options: 
+- --line-numbers
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Another state machine for ActiveRecord
+test_files: 
+- test/statelogic_test.rb
+- test/test_helper.rb
+- test/schema.rb
+- test/fixtures/orders.yml
+- shoulda_macros/statelogic.rb