big_machine 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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,121 @@
+# Big machine [![Build Status](https://secure.travis-ci.org/alaibe/big_machine.png)][travis] [![Dependency Status](https://gemnasium.com/alaibe/big_machine.png)][gemnasium] [![Code Climate](https://codeclimate.com/badge.png)][codeclimate]
+
+[travis]: http://travis-ci.org/alaibe/big_machine
+[gemnasium]: https://gemnasium.com/alaibe/big_machine
+[codeclimate]: https://codeclimate.com/github/alaibe/big_machine
+
+Big machine is a Gem which give state to your object
+
+## Resources
+Bugs
+
+* http://github.com/alaibe/big_machine/issues
+
+Development
+
+* http://github.com/alaibe/big_machine
+
+Testing
+
+* http://travis-ci.org/alaibe/big_machine
+
+Source
+
+* git://github.com/alaibe/big_machine.git
+
+## Install
+
+Add this to your Gemfile
+``` ruby
+  gem 'big_machine'
+```
+
+## Usage
+
+Create your first states
+``` ruby
+  class Draft < BigMachine::State
+    def publish
+      transition_to Online
+    end
+  end
+
+  class Online < BigMachine::State
+  end
+```
+
+Make your object stateful
+``` ruby
+  class Car
+    include BigMachine
+
+    big_machine initial_state: :draft
+  end
+```
+
+Now it's possible to publish your car object:
+``` ruby
+  car = Car.new
+  car.current_state # => Draft
+  car.publish
+  car.current_state # => Online
+```
+
+Of course your object can be an ActiveRecord::Base object. In this case, the object must have a state column. ( if not, see the next section )
+
+## Big machine options
+
+big_machine method can take several options:
+* initial_state is the only one necessary option
+* state_attribute is available only if the object is an active record object
+* workflow if you want to change the normal worklow
+It's possible to call workflow_is method in your different states
+
+###example
+
+``` ruby
+  big_machine initial_state: :dradt, state_attribute: :big_state, workflow: small
+
+  class Draft < BigMachine::State
+
+    def publish
+      return if workflow_is :small
+      
+      transition_to Online
+    end
+
+  end
+```
+
+## Lock module
+
+A state can include lock module, it will lock the state of your object when your enter in it.
+The unlock method should be call to unlock the module
+
+``` ruby
+  class Draft < BigMachine::State
+    include BigMachine::Lock
+
+    def publish
+      transition_to Online
+    end
+
+  end
+
+  class Article
+    include BigMachine
+
+    big_machine initial_state: :dradt
+  end
+
+  article = Article.new
+  article.publish
+  article.current_state # => Draft
+  article.unlock
+  article.publish
+  article.current_state # => Online
+```
+
+## Contributors
+
+*Anthony Laibe

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    = 'BigMachine'
+  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/big_machine.rb

@@ -0,0 +1,63 @@
+require "active_support"
+require "forwardable"
+require "big_machine/state"
+require "big_machine/active_record"
+require "big_machine/transition_methods"
+require "big_machine/lock"
+
+module BigMachine
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :initial_state
+    class_attribute :workflow
+
+    if active_record_model?
+      include BigMachine::ActiveRecord
+    end
+  end
+
+  module ClassMethods
+    def active_record_model? 
+      defined?(::ActiveRecord::Base) && self.ancestors.include?(::ActiveRecord::Base)
+    end
+
+    def big_machine(options)
+      self.initial_state   = options[:initial_state]
+      self.workflow        = options[:workflow]
+      set_initial_state_class
+    end
+
+    def initial_state_class
+      @initial_state_class
+    end
+
+    def set_initial_state_class
+      @initial_state_class = self.initial_state.to_s.camelize.constantize
+      include ::BigMachine::TransitionMethods
+    end
+  end
+
+  def current_state
+    set_current_state(self.class.initial_state_class) unless @current_state
+
+    @current_state
+  end
+
+  def set_current_state(new_state_class)
+    @current_state = new_state_class.new self
+
+    forward_current_state
+  end
+
+  def forward_current_state
+    extend SingleForwardable
+    def_delegators :current_state, *current_state.class.transition_methods
+  end
+
+  def transition_to(next_state_class)
+    current_state.exit
+    set_current_state next_state_class
+  end
+
+end

data/lib/big_machine/active_record.rb

@@ -0,0 +1,32 @@
+module BigMachine
+  module ActiveRecord
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :state_attribute
+      after_initialize :set_current_state_from_db
+    end
+
+    module ClassMethods
+      def big_machine(options = {})
+        super options
+        self.state_attribute = options[:state_attribute] || 'state'
+      end
+    end
+
+    def set_current_state_from_db
+      attribute = send state_attribute
+      set_current_state(attribute.constantize) if attribute
+    end
+
+    def set_current_state(new_state_class)
+      super(new_state_class)
+      send "#{state_attribute}=", new_state_class.name
+    end
+
+    def transition_to(next_state_class)
+      super(next_state_class)
+      save!
+    end
+  end
+end

data/lib/big_machine/lock.rb

@@ -0,0 +1,26 @@
+module BigMachine
+  module Lock
+    extend ActiveSupport::Concern
+
+    included do
+    end
+
+    def locked?
+      @locked
+    end
+
+    def enter
+      @locked = true
+    end
+
+    def unlock
+      @locked = false
+    end
+
+    def transition_to(state_class)
+      return if @locked
+
+      super
+    end
+  end
+end

data/lib/big_machine/state.rb

@@ -0,0 +1,29 @@
+module BigMachine
+  class State
+
+    attr_reader :stateful
+    
+    def initialize(stateful)
+      @stateful = stateful
+      enter
+    end
+
+    def self.transition_methods
+      public_instance_methods - State.public_instance_methods
+    end
+
+    def transition_to(state_class)
+      @stateful.transition_to(state_class)
+    end
+
+    def workflow_is(name)
+      @stateful.workflow == name
+    end
+
+    def enter
+    end
+
+    def exit
+    end
+  end
+end

data/lib/big_machine/transition_methods.rb

@@ -0,0 +1,9 @@
+module BigMachine
+  module TransitionMethods
+    extend Forwardable
+
+    def self.included(base)
+      def_delegators :current_state, *base.initial_state_class.transition_methods
+    end
+  end
+end

data/lib/big_machine/version.rb

@@ -0,0 +1,3 @@
+module BigMachine
+  VERSION = "1.0.0"
+end

data/lib/tasks/big_machine_tasks.rake

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

data/test/big_machine_test.rb

@@ -0,0 +1,126 @@
+require 'test_helper'
+
+class Draft < BigMachine::State
+  def publish
+    return if workflow_is :small
+
+    transition_to Online
+  end
+
+  def lock
+    transition_to LockState
+  end
+end
+
+class LockState < BigMachine::State
+  include BigMachine::Lock
+  
+  def back_to_draft
+    transition_to Draft
+  end
+end
+
+class Online < BigMachine::State
+  def back_to_draft
+    transition_to Draft
+  end
+end
+
+class DummyMachine
+  include BigMachine
+
+  big_machine initial_state: :draft
+end
+
+class DummyWithWorkflow
+  include BigMachine
+
+  big_machine initial_state: :draft, workflow: :small
+end
+
+class DummyWithActiveRecord < ActiveRecord::Base
+  include BigMachine
+
+  attr_accessor :state
+
+  big_machine initial_state: :draft
+
+  def initialize(state)
+    @state = state
+  end
+
+  def state
+    @state
+  end
+end
+
+class DummyWithActiveRecordAndOtherState < ActiveRecord::Base
+  include BigMachine
+
+  attr_accessor :other_state
+
+  big_machine initial_state: :draft, state_attribute: :other_state
+
+  def other_state
+    'Online'
+  end
+end
+
+class BigMachineTest < ActiveSupport::TestCase
+  setup do
+    @dummy   = DummyMachine.new
+    @dummyAR = DummyWithActiveRecord.new('Online')
+  end
+
+  test "big_machine set initial state" do
+    assert_equal 'Draft', @dummy.current_state.class.name
+  end
+
+  test "big_machine create new state when start transition" do
+    @dummy.publish
+    assert_equal 'Online', @dummy.current_state.class.name
+    @dummy.back_to_draft
+    assert_equal 'Draft', @dummy.current_state.class.name
+  end
+
+  test "big machine must refuse unavailable action" do
+    @dummy.publish
+    assert_raise NoMethodError do
+      @dummy.publish
+    end
+  end
+
+  test "big machine can lock state" do
+    @dummy.lock
+    assert @dummy.locked?
+    @dummy.back_to_draft
+    assert_equal 'LockState', @dummy.current_state.class.name
+    assert @dummy.current_state.locked?
+    @dummy.unlock
+    assert !@dummy.current_state.locked?
+    assert_equal 'LockState', @dummy.current_state.class.name
+    @dummy.back_to_draft
+    assert_equal 'Draft', @dummy.current_state.class.name
+  end
+
+  test "big_machine can have workflow to refuse some action" do
+    @dummyW = DummyWithWorkflow.new
+    @dummyW.publish
+    assert_equal 'Draft', @dummyW.current_state.class.name
+  end
+
+  test "big_machine read state from database" do
+    assert_equal 'Online', @dummyAR.current_state.class.name
+  end
+
+  test "big_machine read state from specify column in database" do
+    @dummyAROS = DummyWithActiveRecordAndOtherState.new
+    assert_equal 'Online', @dummyAROS.current_state.class.name
+  end
+
+  test "big_machine must update attribute when state change" do
+    @dummyAR.back_to_draft
+    assert_equal 'Draft', @dummyAR.current_state.class.name
+    assert_equal 'Draft', @dummyAR.state
+  end
+end