stateful 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 85ae4d99568569f667a41d4b1959cc511f300dea
+  data.tar.gz: af2c257fdfcedf21ea5b760537c9d32c004ac74e
+SHA512:
+  metadata.gz: 8b714fc19974ee231d8baf208c655f835a6c002fa12c984740f0a14a29449a8b3595b7e7297ecf203dc318f077ec49f7ad8c0be396b818d3b915502f5db59255
+  data.tar.gz: 1b6d4c06b40dad7123e6a6f6c946596ca0f1a1665cff1b0e4fd9f7e68012703def03a97c36417584ccfb8e1ac221f48a84233809907e146a6b49dd966bb1d801

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stateful.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 jake hoffner
+
+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,115 @@
+# Stateful
+
+A simple state machine gem. Works with plain ruby objects and Mongoid. This gem aims
+to keep things simple. It supports the following:
+
+- Single state attribute/field per object
+- Simple event model, just use plain ruby methods as your events and use the change_state helper to change the state.
+- Supports virtual/grouped states that can be used to break down top level states into more granular sub-states.
+- Utilizes ActiveSupport::Callbacks
+- Simple hash structure for defining states and their possible transitions. No complicated DSL to learn.
+- ActiveSupport is the only dependency.
+- Very small code footprint.
+- Mongoid support, automatically creates field, validations and scopes for you.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'stateful'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install stateful
+
+## Usage
+
+```ruby
+class Project
+    include Stateful
+
+    attr_reader :published_at
+
+    stateful default: :new,
+             events: [:publish, :unpublish, :approve, :close, :mark_as_duplicate],
+             states: {
+                active: {
+                    new: :published,
+                    published: {
+                        needs_approval: [:approved, :duplicate],
+                        approved: :closed
+                    }
+                },
+                inactive: {
+                    closed: nil,
+                    duplicate: nil
+                }
+             }
+
+    def publish
+        # change the state to needs_approval and fire publish events. The block will only be
+        # called if the state can successfully be changed.
+        change_state(:needs_approval, :publish) do
+            @published_at = Time.now
+        end
+    end
+
+    # use callbacks if you want
+    after_publish do |project|
+        NotificationService.notify_project_published(project)
+    end
+
+    # define other event methods ...
+end
+
+project = Project.new
+project.active? # => true
+project.new? # => true
+project.published? # => false
+```
+
+If you are using with Mongoid a field called state will automatically be created for you.
+
+```ruby
+class Project
+    include Mongoid::Document # must be included first
+    include Stateful
+
+    field :published_at, type: Time
+
+    stateful default: :new,
+             events: [:publish, :unpublish, :approve, :close, :mark_as_duplicate],
+             states: {
+                active: {
+                    new: :published,
+                    published: {
+                        needs_approval: [:approved, :duplicate],
+                        approved: :closed
+                    }
+                },
+                inactive: {
+                    closed: nil,
+                    duplicate: nil
+                }
+             }
+
+
+    # ...
+end
+
+# scopes are automatically created for you
+Project.active.count
+Project.published.count
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/stateful/mongoid.rb

@@ -0,0 +1,27 @@
+module Stateful
+  module Mongoid
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      protected
+
+      def define_state_attribute(options)
+        field :state, type: Symbol, default: options[:default]
+        validates_inclusion_of :state,
+                               in: state_infos.keys,
+                               message: options.has_key?(:message) ? options[:message] : 'invalid state value',
+                               allow_nil: !!options[:allow_nil]
+
+        # configure scopes to query the attribute value
+        state_infos.values.each do |info|
+          states = info.collect_child_states
+          if states.length == 1
+            scope info.name, where(state: states.first)
+          else
+            scope info.name, where(:state.in => states)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stateful/state_info.rb

@@ -0,0 +1,57 @@
+module Stateful
+  class StateInfo
+    attr_reader :parent, :children, :name, :to_transitions
+    def initialize(state_class, parent, name, config)
+      @state_class = state_class
+      if parent
+        @parent = parent
+        parent.children << self
+      end
+
+      @name = name
+      @to_transitions = []
+
+      if config.is_a?(Hash)
+        @groupConfig = config
+        @children = []
+      else
+        @to_transitions = config ? (config.is_a?(Array) ? config : [config]) : []
+      end
+    end
+
+    def is?(state)
+      (@name == state or (parent and parent.is?(state)))
+    end
+
+    def is_group?
+      !!@groupConfig
+    end
+
+    def can_transition_to?(state)
+      state_info = @state_class.state_infos[state]
+      if is_group? or state_info.nil? or state_info.is_group?
+        false
+      else
+        to_transitions.include?(state)
+      end
+    end
+
+    def collect_child_states
+      is_group? ? children.flat_map(&:collect_child_states) : [name]
+    end
+
+    def expand_to_transitions
+      if to_transitions.any?
+        @to_transitions = to_transitions.flat_map do |to|
+          info = @state_class.state_infos[to]
+
+          if info.is_group?
+            info.collect_child_states
+          else
+            [info.name]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stateful/version.rb

@@ -0,0 +1,3 @@
+module Stateful
+  VERSION = "0.0.1"
+end

data/lib/stateful.rb

@@ -0,0 +1,142 @@
+require "stateful/version"
+require "stateful/state_info"
+
+module Stateful
+  extend ActiveSupport::Concern
+  include ActiveSupport::Callbacks
+
+  included do
+    if defined?(Mongoid)
+      require 'mongoid/document'
+      include Stateful::Mongoid if included_modules.include?(::Mongoid::Document)
+    end
+  end
+
+  module ClassMethods
+    def state_infos
+      @state_infos ||= {}
+    end
+
+    def stateful(options)
+      options[:events] ||= []
+
+      define_method 'state_events' do
+        options[:events]
+      end
+
+      define_method 'state_info' do
+        self.class.state_infos[self.state]
+      end
+
+      define_method 'state_valid?' do
+        self.class.state_infos.keys.include?(state)
+      end
+
+      define_method 'change_state' do |new_state, options = {}, &block|
+        return false if new_state == state
+        return false unless state_info.can_transition_to?(new_state)
+
+        # convert shortcut event name to options hash
+        options = {event: options} if options.is_a? Symbol
+        options[:persist_methods] = [:persist_state, :save]
+
+        _change_state(new_state, options, &block)
+      end
+
+      define_method 'change_state!' do |new_state, options = {}, &block|
+        return false if new_state == state
+        raise "transition from #{state} to #{new_state} not allowed" unless state_info.can_transition_to?(new_state)
+
+        # convert shortcut event name to options hash
+        options = {event: options} if options.is_a? Symbol
+        options[:persist_methods] = [:persist_state!, :save!]
+        _change_state(new_state, options, &block)
+      end
+
+      define_method '_change_state' do |new_state, options, &block|
+        # do a little magic and infer the event name from the method name used to call change_state
+        # TODO: decide if this is too magical, for now it has been commented out.
+        #unless options[:event]
+        #  calling_method = caller[1][/`.*'/][1..-2].gsub('!', '').to_sym
+        #  options[:event] = calling_method if state_events.include? calling_method
+        #end
+
+        if block and block.call == false
+          false
+        else
+          callbacks = [:state_change]
+          callbacks << options[:event] if options[:event]
+          run_callbacks *callbacks do
+            self.state = new_state
+            if options[:persist_methods]
+              method = options[:persist_methods].find {|m| respond_to?(m)}
+              __send__(method) if method
+            end
+            if respond_to?(:persist_state)
+              persist_state
+            elsif respond_to?(:save!)
+              save!
+            end
+          end
+          true
+        end
+      end
+
+      private :_change_state
+
+      define_method 'can_transition_to?' do |new_state|
+        state_info.can_transition_to?(new_state)
+      end
+
+      # init and configure state info
+      init_state_info(options[:states])
+      state_infos.values.each do |info|
+        info.expand_to_transitions
+
+        define_method "#{info.name}?" do
+          info.is?(self.state)
+        end
+      end
+
+
+      define_state_attribute(options)
+
+      # define the event callbacks
+      events = ([:state_change] + options[:events])
+      define_callbacks *events
+
+      # define callback helpers
+      events.each do |event|
+        define_singleton_method "before_#{event}" do |method = nil, &block|
+          set_callback(event, :before, method ? method : block)
+        end
+
+        define_singleton_method "after_#{event}" do |method = nil, &block|
+          set_callback(event, :after, method ? method : block)
+        end
+      end
+    end
+
+    protected
+    def define_state_attribute(options)
+      define_method 'state' do
+        instance_variable_get(:@state) || options[:default]
+      end
+
+      define_method 'state=' do |val|
+        instance_variable_set(:@state, val)
+      end
+    end
+
+    private
+
+    def init_state_info(values, parent = nil)
+      values.each do |name, config|
+        info = state_infos[name] = Stateful::StateInfo.new(self, parent, name, config)
+        init_state_info(config, info) if info.is_group?
+      end
+    end
+  end
+end
+
+require 'stateful/mongoid' if defined?(Mongoid)

data/spec/mongoid_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+require './lib/stateful'
+require 'mongoid'
+
+
+class Kata
+  include Mongoid::Document
+  include Stateful
+
+  stateful default: :draft, events: [:publish, :approve, :retire], states: {
+    :draft => :beta,
+    beta: {
+      :needs_testing => :needs_approval,
+      :needs_approval => :approved
+    },
+    :approved => :retired,
+    :retired => nil
+  }
+end
+
+describe Stateful::Mongoid do
+  let(:kata) {Kata.new}
+
+  it 'should support creating a state field' do
+    Kata.fields.keys.include?('state').should be_true
+  end
+
+  it 'should support validating state values' do
+    kata.state.should == :draft
+    kata.valid?.should be_true
+    kata.state = :invalid
+    kata.valid?.should be_false
+  end
+
+  it 'should support can_transition_to?' do
+    kata.can_transition_to?(:beta).should be_true
+    kata.can_transition_to?(:retired).should be_false
+  end
+
+  it 'should create scopes for each state and virtual state' do
+    Kata.beta.selector.should == {"state" => {"$in" => [:needs_testing, :needs_approval]}}
+    Kata.draft.selector.should == {"state" => :draft}
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+require 'mongoid'
+require 'mongoid/document'
+
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+
+end

data/spec/stateful_spec.rb

@@ -0,0 +1,158 @@
+require 'spec_helper'
+require './lib/stateful'
+
+class Kata
+  include Stateful
+
+  attr_accessor :approved_by, :ready_score, :published_at, :state_changes
+
+  def initialize
+    @ready_score = 0
+    @state_changes = 0
+  end
+
+  stateful  default: :draft,
+            events: [:publish, :unpublish, :approve, :retire],
+            states: {
+                :draft => :beta,
+                published: {
+                    beta: {
+                        :needs_feedback => [:draft, :needs_approval],
+                        :needs_approval => [:draft, :approved]
+                    },
+                    :approved => :retired
+                },
+                :retired => nil
+            }
+
+
+  after_state_change do |doc|
+    doc.state_changes += 1
+  end
+
+  def vote(ready)
+    @ready_score += ready ? 1 : -1
+
+    # votes only affect state when in beta
+    if beta?
+      if enough_votes_for_approval? and needs_feedback?
+        change_state(:needs_approval)
+      elsif not enough_votes_for_approval? and needs_approval?
+        change_state(:needs_feedback)
+      end
+    end
+  end
+
+  def publish
+    change_state(enough_votes_for_approval? ? :needs_approval : :needs_feedback) do
+      @published_at = Time.now
+    end
+  end
+
+  def unpublish
+    change_state(:draft)
+  end
+
+  def approve(approved_by)
+    change_state(:approved) do
+      @approved_by = approved_by
+    end
+  end
+
+  def retire
+    change_state(:retire)
+  end
+
+  def enough_votes_for_approval?
+    ready_score >= 10
+  end
+end
+
+describe Kata do
+  let(:kata) {Kata.new}
+
+  it 'should support state_infos' do
+    Kata.state_infos.should_not be_nil
+  end
+
+  it 'should support default state' do
+    kata.state.should == :draft
+  end
+
+  it 'should support state_info' do
+    kata.state_info.should_not be_nil
+    kata.state_info.name.should == :draft
+  end
+
+  it 'should support simple boolean helper methods' do
+    kata.draft?.should be_true
+    kata.published?.should be_false
+  end
+
+  context 'change_state' do
+    it 'should raise error when an invalid transition state is provided' do
+      expect{kata.change_state(:retired)}.to raise_error
+    end
+
+    it 'should raise error when a group state is provided' do
+      expect{kata.change_state(:beta)}.to raise_error
+    end
+
+    it 'should return false when state is the same' do
+      kata.change_state(:draft).should be_false
+    end
+
+    it 'should support state_valid?' do
+      kata.state_valid?.should be_true
+    end
+
+    it 'should change the state when a proper state is provided' do
+      kata.change_state(:needs_feedback).should be_true
+      kata.state.should == :needs_feedback
+      kata.change_state(:needs_approval).should be_true
+      kata.state.should == :needs_approval
+      kata.change_state(:draft).should be_true
+      kata.state.should == :draft
+      kata.change_state(:needs_approval).should be_true
+      kata.change_state(:approved).should be_true
+      kata.state.should == :approved
+    end
+
+    it 'should support calling passed blocks when state is valid' do
+      kata.published_at.should be_nil
+      kata.publish
+      kata.published_at.should_not be_nil
+    end
+
+    it 'should support ingoring passed blocked when state is not valid' do
+      kata.approve('test')
+      kata.approved?.should be_false
+      kata.approved_by.should be_nil
+    end
+
+    it 'should support after callbacks methods' do
+      kata.publish
+      kata.state_changes.should == 1
+    end
+  end
+
+  describe Stateful::StateInfo do
+    it 'should support is?' do
+      Kata.state_infos[:draft].is?(:draft).should be_true
+      Kata.state_infos[:needs_feedback].is?(:published).should be_true
+      Kata.state_infos[:needs_feedback].is?(:beta).should be_true
+      Kata.state_infos[:approved].is?(:published).should be_true
+      Kata.state_infos[:approved].is?(:beta).should be_false
+      Kata.state_infos[:retired].is?(:beta).should be_false
+    end
+
+    it 'should support expanded to transitions' do
+      Kata.state_infos[:draft].to_transitions.should == [:needs_feedback, :needs_approval]
+      Kata.state_infos[:needs_approval].to_transitions.should == [:draft, :approved]
+
+      Kata.state_infos[:retired].to_transitions.should be_empty
+
+      p Kata.instance_methods
+    end
+  end
+end

data/stateful.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stateful/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "stateful"
+  spec.version       = Stateful::VERSION
+  spec.authors       = ["jake hoffner"]
+  spec.email         = ["jake@codewars.com"]
+  spec.description   = %q{A simple state machine gem}
+  spec.summary       = %q{A simple state machine gem. Works with plain ruby objects and Mongoid. This gem aims
+to keep things simple.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activesupport'
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "mongoid", "~> 3.0"
+
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: stateful
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- jake hoffner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A simple state machine gem
+email:
+- jake@codewars.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/stateful.rb
+- lib/stateful/mongoid.rb
+- lib/stateful/state_info.rb
+- lib/stateful/version.rb
+- spec/mongoid_spec.rb
+- spec/spec_helper.rb
+- spec/stateful_spec.rb
+- stateful.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A simple state machine gem. Works with plain ruby objects and Mongoid. This
+  gem aims to keep things simple.
+test_files:
+- spec/mongoid_spec.rb
+- spec/spec_helper.rb
+- spec/stateful_spec.rb