omg-statelogic 1.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1.2 - 2008-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,74 @@
+=== 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 in order to facilitate
+enforcing _real_ model data consistency instead of merely formal.
+
+=== Features
+- State transitions validation.
+- State-scoped validations.
+- State-scoped lifecycle callbacks (before|after_save, etc)
+- ???????
+- PROFIT!!!11
+
+=== 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?+
+          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/xmlnuts -- 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,24 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+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

data/lib/omg-statelogic.rb

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

data/lib/statelogic/activerecord.rb

@@ -0,0 +1,87 @@
+require 'statelogic/callbacks_ext'
+
+module Statelogic
+  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
+
+        def state(name, options = {}, &block)
+          attr = @config[:attribute]
+          attr_was = :"#{attr}_was"
+          @class.class_eval do
+            define_method("#{name}?") { send(attr) == name }
+            define_method("was_#{name}?") { send(attr_was) == name }
+          end
+
+          StateScopeHelper.new(@class, name, @config).instance_eval(&block)
+
+          @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]
+        validates_inclusion_of attr, :in => initial, :on => :create unless initial.blank?
+
+        const = attr.to_s.pluralize.upcase
+        const_set(const, options[:states].freeze.each(&:freeze)) unless const_defined?(const)
+      end
+    end
+  end
+end
+
+# :stopdoc:
+class ActiveRecord::Base
+  include Statelogic::ActiveRecord
+end

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,12 @@
+class Test::Unit::TestCase
+  def self.should_not_require_attributes(*attributes)
+    get_options!(attributes)
+    klass = model_class
+
+    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,86 @@
+require 'test_helper'
+
+class Order < ActiveRecord::Base
+  statelogic do
+    initial_state 'unpaid' do
+      transitions_to 'ready', 'suspended'
+    end
+    state 'ready' do
+      transitions_to 'redeemed', 'suspended'
+      validates_presence_of :txref
+    end
+    state 'redeemed' do
+      transitions_to 'suspended'
+      validates_presence_of :txref, :redeemed_at, :facility_id
+    end
+    state 'suspended' do
+      transitions_to 'unpaid', 'ready', 'redeemed'
+      validate do |order|
+        order.errors.add(:txref, :invalid) if order.txref && order.txref !~ /\AREF/
+      end
+    end
+  end
+end
+
+class OrderTest < ActiveSupport::TestCase
+  fixtures :orders
+
+  should_require_attributes :state, :message => default_error_message(:inclusion)
+
+  context 'A fresh order' do
+    setup do
+      @order = Order.new
+    end
+
+    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
+    setup do
+      @order = orders(:unpaid)
+    end
+
+    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
+    setup do
+      @order = orders(:ready)
+    end
+
+    should_allow_values_for :state, 'ready', 'redeemed', 'suspended'
+    should_not_allow_values_for :state, 'unpaid', 'screwed_up',
+      :message => default_error_message(:inclusion)
+    should_require_attributes :txref
+    should_not_require_attributes :redeemed_at, :facility_id
+  end
+
+  context 'A redeemed order' do
+    setup do
+      @order = orders(:redeemed)
+    end
+
+    should_allow_values_for :state, 'redeemed', 'suspended'
+    should_not_allow_values_for :state, 'unpaid', 'ready', 'screwed_up',
+      :message => default_error_message(:inclusion)
+    should_require_attributes :txref, :redeemed_at, :facility_id
+  end
+
+  context 'A suspended order' do
+    setup do
+      @order = orders(:suspended)
+    end
+
+    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'
+
+ActiveSupport::TestCase.fixture_path = 'test/fixtures'
+
+ActiveRecord::Base.configurations = {
+  'test' => {:adapter => 'sqlite3', :dbfile => ':memory:'}
+}
+ActiveRecord::Base.establish_connection(:test)
+
+load 'schema.rb'

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification 
+name: omg-statelogic
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Igor Gunko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-21 00:00:00 -07: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.2.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.0.6
+    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.
+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
+post_install_message: 
+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.2.0
+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