micro_state_machine 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+  - "2.1.0"
+  - jruby
+  # - rbx # takes too long to build.
+# script: bundle exec rake

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+gem "activesupport", ">= 2.3.5" # For HashWithIndifferentAccess
+
+group :development do
+  gem "minitest", ">= 0"
+  gem "rdoc"
+  gem "bundler", "~> 1.0"
+  gem "jeweler", "~> 2.0.1"
+  gem "simplecov", ">= 0"
+  # gem 'debugger'
+end

data/Gemfile.lock

@@ -0,0 +1,69 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.2.17)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    addressable (2.3.5)
+    builder (3.2.2)
+    descendants_tracker (0.0.3)
+    docile (1.1.3)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    git (1.2.6)
+    github_api (0.11.3)
+      addressable (~> 2.3)
+      descendants_tracker (~> 0.0.1)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 1.2)
+      multi_json (>= 1.7.5, < 2.0)
+      nokogiri (~> 1.6.0)
+      oauth2
+    hashie (2.0.5)
+    highline (1.6.20)
+    i18n (0.6.9)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+    json (1.8.1)
+    jwt (0.1.11)
+      multi_json (>= 1.5)
+    mini_portile (0.5.2)
+    minitest (5.3.0)
+    multi_json (1.8.4)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    nokogiri (1.6.1)
+      mini_portile (~> 0.5.0)
+    oauth2 (0.9.3)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 0.1.8)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    rack (1.5.2)
+    rake (10.1.1)
+    rdoc (4.1.1)
+      json (~> 1.4)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (>= 2.3.5)
+  bundler (~> 1.0)
+  jeweler (~> 2.0.1)
+  minitest
+  rdoc
+  simplecov

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Steven Soroka
+
+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,93 @@
+micro\_state\_machine
+-------------------
+
+[![Build Status](https://travis-ci.org/ssoroka/micro_state_machine.png?branch=master)](https://travis-ci.org/ssoroka/micro_state_machine)
+
+A small state machine! You don't need all that other crap. What's not included here is as important as what's included.
+
+### Features Included:
+
+- default state
+- customizable state field
+- before and after transition events
+- "state?" current state query methods dynamically defined
+- "state!" transition method to switch states
+- exceptions thrown on invalid state transitions
+- super-simple syntax
+
+### Features NOT included:
+
+
+- Transition Guards. (small pull-requests may be accepted).
+- Multiple state machines per object.
+
+# Usage Example
+
+Rails Example:
+
+    include MicroStateMachine
+
+    # first state declared is automatically the default state for new objects
+    state :new
+    state :running, from: %w(new paused deferred)
+    state :paused, from: %w(running)
+    state :deferred, from: %w(new running paused deferred)
+    state :completed, from: %w(new running paused deferred)
+    state :closed, from: %w(new running paused deferred)
+
+
+Ruby Object Example:
+
+    include MicroStateMachine
+
+    # first state declared is automatically the default state for new objects
+    state :new
+    state :running, from: %w(new paused deferred)
+    state :paused, from: %w(running)
+    state :deferred, from: %w(new running paused deferred)
+    state :completed, from: %w(new running paused deferred)
+    state :closed, from: %w(new running paused deferred)
+
+    def initialize
+      set_initial_state
+    end
+
+Event Transitions:
+
+    after_state_change do |from_state, to_state|
+      state_histories.create!(from_state: from_state, to_state: to_state, user: current_user)
+      pause_users_other_tasks if to_state.to_s == 'running'
+    end
+
+    on_enter_state :running do
+      self.started_at = Time.now.utc
+    end
+
+    on_exit_state :running do
+      running_time = (Time.now.utc - started_at).round
+      time_logs.create!(task: self, user: current_user, seconds: running_time)
+    end
+
+To change the name of the state column:
+
+    def state_column
+      'something_other_than_state'
+    end
+
+
+Contributing to micro\_state\_machine
+-----------------------------------
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+Copyright
+---------
+
+Copyright (c) 2014 Steven Soroka. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = "micro_state_machine"
+  gem.homepage = "http://github.com/ssoroka/micro_state_machine"
+  gem.license = "MIT"
+  gem.summary = %Q{A small state machine!}
+  gem.description = %Q{A small state machine! You don't need all that other crap. What's not included here is as important as what's included.}
+  gem.email = "ssoroka78@gmail.com"
+  gem.authors = ["Steven Soroka"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Code coverage detail"
+task :simplecov do
+  ENV['COVERAGE'] = "true"
+  Rake::Task['test'].execute
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "micro_state_machine #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/micro_state_machine.rb

@@ -0,0 +1,122 @@
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/class/attribute'
+
+module MicroStateMachine
+  class InvalidState < StandardError
+    def initialize(old_state, new_state)
+      super("Cannot transition from #{old_state} to #{new_state}")
+    end
+  end
+
+  def self.included(klass)
+    klass.class_attribute :_on_enter_state, :_on_exit_state, :_initial_state, :_after_state_change, :_states
+    klass.send(:extend, ClassMethods)
+    if klass.respond_to?(:after_initialize)
+      klass.instance_eval do
+        after_initialize(:set_initial_state)
+      end
+    end
+  end
+
+  module ClassMethods
+    # override this to change the default state column name
+    def state_column
+      'state'
+    end
+
+    # used to define the possible states the "machine" could be in.
+    # defines convenience {state}! and {state}? methods
+    # worth noting that transition_from_{from_state}_to_{state} could be used to implement guards.
+    def state(state, options = {})
+      self._initial_state ||= state
+      self._after_state_change ||= []
+      self._on_enter_state ||= HashWithIndifferentAccess.new
+      self._on_exit_state ||= HashWithIndifferentAccess.new
+      self._states ||= {}
+      _states[state] = options
+      from = options[:from] || _states.keys
+
+      from.each do |from_state|
+        define_method("#{state}!") do
+          transition_to(state)
+        end
+
+        define_method("#{state}?") do
+          is?(state)
+        end
+
+        define_method("transition_from_#{from_state}_to_#{state}") do
+          on_exit_state = self.class._on_exit_state
+          on_enter_state = self.class._on_enter_state
+          if on_exit_state[from_state]
+            on_exit_state[from_state].each do |blk|
+              instance_eval &blk
+            end
+          end
+          send("#{state_column}=", state)
+          if on_enter_state[state]
+            on_enter_state[state].each do |blk|
+              instance_eval &blk
+            end
+          end
+        end
+      end
+    end
+
+    def on_enter_state(state, &block)
+      h = _on_enter_state
+      h[state] ||= []
+      h[state].push block
+      self._on_enter_state = h
+    end
+
+    def on_exit_state(state, &block)
+      h = _on_exit_state
+      h[state] ||= []
+      h[state].push block
+      self._on_exit_state = h
+    end
+
+    def after_state_change(*args, &block)
+      _after_state_change.push block
+    end
+  end
+
+  # Instance Methods
+
+  def state_column
+    self.class.state_column
+  end
+
+  def get_state
+    send(state_column)
+  end
+
+  def set_initial_state
+    current_value = send(state_column)
+    if current_value.nil?
+      send("#{state_column}=", self.class._initial_state)
+    end
+  end
+
+  def is?(state)
+    get_state.to_s == state.to_s
+  end
+
+  def can_transition_to?(new_state)
+    states = self.class._states
+    options = HashWithIndifferentAccess.new(states)[new_state]
+    options.blank? || options[:from].include?(get_state)
+  end
+
+  def transition_to(new_state)
+    old_state = get_state
+    transition_method_name = "transition_from_#{old_state}_to_#{new_state}"
+    raise InvalidState.new(old_state, new_state) unless respond_to?(transition_method_name)
+    send(transition_method_name)
+    self.class._after_state_change.each do |blk|
+      instance_exec(old_state, new_state, &blk)
+    end
+    self
+  end
+end

data/micro_state_machine.gemspec

@@ -0,0 +1,66 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "micro_state_machine"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Steven Soroka"]
+  s.date = "2014-02-27"
+  s.description = "A small state machine! You don't need all that other crap. What's not included here is as important as what's included."
+  s.email = "ssoroka78@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".travis.yml",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/micro_state_machine.rb",
+    "micro_state_machine.gemspec",
+    "test/helper.rb",
+    "test/test_micro_state_machine.rb"
+  ]
+  s.homepage = "http://github.com/ssoroka/micro_state_machine"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.23"
+  s.summary = "A small state machine!"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.3.5"])
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 2.3.5"])
+      s.add_dependency(%q<minitest>, [">= 0"])
+      s.add_dependency(%q<rdoc>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 2.3.5"])
+    s.add_dependency(%q<minitest>, [">= 0"])
+    s.add_dependency(%q<rdoc>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,27 @@
+require 'simplecov'
+
+SimpleCov.configure do
+  filters.clear
+  load_profile 'test_frameworks'
+end
+
+SimpleCov.start do
+  add_filter "/(.rbenv|.rvm)/"
+  add_filter 'vendor'
+end
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts "#{e.message}\nRun `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'minitest/autorun'
+require 'minitest/spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'micro_state_machine'
+
+Minitest.autorun

data/test/test_micro_state_machine.rb

@@ -0,0 +1,135 @@
+require 'helper'
+require 'micro_state_machine'
+
+class TestModel
+  attr_accessor :state
+
+  include MicroStateMachine
+
+  def initialize
+    set_initial_state
+  end
+end
+
+class TestKanbanTask < TestModel
+  state 'new'
+  state 'wip', from: %w(new)
+  state 'review', from: %w(new wip)
+  state 'accepted', from: %w(review)
+  state 'archived', from: %w(accepted)
+end
+
+describe MicroStateMachine do
+  it "state defaults to first state" do
+    TestKanbanTask.new.state.must_equal 'new'
+  end
+
+  it 'allows overriding the state column in the class definition' do
+    override_test_class = Class.new(TestKanbanTask) do
+      def state_column
+        :foo_state
+      end
+      def foo_state
+        'review'
+      end
+    end
+    assert !override_test_class.new.new?
+    assert override_test_class.new.review?
+  end
+
+  it 'allows overriding the state column on the instance' do
+    task = TestKanbanTask.new
+    # alter the meta class to include "fish" column
+    task.define_singleton_method :fish_state do
+      'wip'
+    end
+
+    # define a method on the instance
+    task.define_singleton_method :state_column do
+      'fish_state'
+    end
+
+    task.get_state.must_equal 'wip'
+    assert task.wip?
+  end
+
+  it 'fires on_enter_state and on_exit_state hooks on changing state' do
+    enter_hit = false
+    exit_hit = false
+    hook_class = Class.new(TestKanbanTask) do
+      on_enter_state :wip do
+        enter_hit = true
+      end
+      on_exit_state :wip do
+        exit_hit = true
+      end
+    end
+
+    assert !enter_hit
+    assert !exit_hit
+
+    obj = hook_class.new
+    obj.get_state.must_equal 'new'
+
+    obj.wip!
+    assert enter_hit
+    assert !exit_hit
+
+    obj.review!
+    assert exit_hit
+  end
+
+  it 'fires after_state_change hooks after changing state' do
+    from_state = nil
+    to_state = nil
+
+    hook_class = Class.new(TestKanbanTask) do
+      after_state_change do |_from_state, _to_state|
+        from_state = _from_state
+        to_state = _to_state
+      end
+    end
+
+    obj = hook_class.new
+    obj.get_state.must_equal 'new'
+
+    obj.wip!
+    from_state.must_equal 'new'
+    to_state.must_equal 'wip'
+
+    obj.review!
+    from_state.must_equal 'wip'
+    to_state.must_equal 'review'
+
+    assert_raises MicroStateMachine::InvalidState do
+      obj.wip!
+    end
+
+    # make sure it's unchanged:
+    from_state.must_equal 'wip'
+    to_state.must_equal 'review'
+  end
+
+  it 'throws an InvalidState error when transitioning to an invalid state' do
+    assert_raises MicroStateMachine::InvalidState do
+      TestKanbanTask.new.accepted!
+    end
+  end
+
+  it 'can transition through all states' do
+    task = TestKanbanTask.new
+    task.wip!
+    assert task.wip?
+
+    task.review!
+    assert task.review?
+
+    task.accepted!
+    assert task.accepted?
+
+    task.archived!
+    assert task.archived?
+    assert task.is?(:archived)
+    assert task.is?('archived')
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: micro_state_machine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Steven Soroka
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.5
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A small state machine! You don't need all that other crap. What's not
+  included here is as important as what's included.
+email: ssoroka78@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- .document
+- .travis.yml
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/micro_state_machine.rb
+- micro_state_machine.gemspec
+- test/helper.rb
+- test/test_micro_state_machine.rb
+homepage: http://github.com/ssoroka/micro_state_machine
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3232762694017464134
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A small state machine!
+test_files: []