state_manager 0.2.3

data/lib/state_manager/base.rb

@@ -0,0 +1,169 @@
+module StateManager
+ 
+  class StateNotFound < StandardError; end;
+  class InvalidEvent < StandardError; end;
+  class InvalidTransition < StandardError; end;
+
+  # The base StateManager class is responsible for tracking the current state
+  # of an object as well as managing the transitions between states.
+  class Base < State
+
+    class_attribute :_resource_class
+    class_attribute :_resource_name
+    class_attribute :_state_property
+    self._state_property = :state
+
+    attr_accessor :resource, :context
+
+    def initialize(resource, context={})
+      super(nil, nil)
+      self.resource = resource
+      self.context = context
+
+      transition_to(initial_state.path) unless current_state
+    end
+
+    # Transitions to the state at the specified path. The path can be relative
+    # to any state along the current state's path.
+    def transition_to(path)
+      path = path.to_s
+      state = current_state || self
+      exit_states = []
+
+      # Find the nearest parent state on the path of the current state which
+      # has a sub-state at the given path
+      new_states = state.find_states(path)
+      while(!new_states) do
+        exit_states << state
+        state = state.parent_state
+        raise(StateNotFound, path) unless state
+        new_states = state.find_states(path)
+      end
+
+      # Can only transition to leaf states
+      # TODO: transition to the initial_state of the state?
+      raise(InvalidTransition, path) unless new_states.last.leaf?
+
+      enter_states = new_states - exit_states
+      exit_states = exit_states - new_states
+
+      from_state = current_state
+      to_state = enter_states.last
+
+      # Before Callbacks
+      will_transition(from_state, to_state, current_event)
+      exit_states.each{ |s| s.exit }
+      enter_states.each{ |s| s.enter }
+
+      # Set the state on the underlying resource
+      self.current_state = to_state
+
+      # After Callbacks
+      exit_states.each{ |s| s.exited }
+      enter_states.each{ |s| s.entered }
+      did_transition(from_state, to_state, current_event)
+    end
+
+    def current_state
+      path = read_state
+      find_state(path) if path && !path.empty?
+    end
+
+    def current_state=(value)
+      write_state(value)
+    end
+
+    # Send an event to the current state.
+    #
+    # Unlike the regular send_event method, this method recursively walks the
+    # path of states starting at the current state.
+    def send_event!(name, *args)
+      self.current_event = name
+      state = find_state_for_event(name)
+      raise(InvalidEvent, name) unless state
+      state.send_event name, *args
+      self.current_event = nil
+    end
+
+    def respond_to_event?(name)
+      !!find_state_for_event(name)
+    end
+
+    def find_state_for_event(name)
+      state = current_state
+      while(state) do
+        return state if state.has_event?(name)
+        state = state.parent_state
+      end
+    end
+
+    def state_manager
+      self
+    end
+
+    def to_s
+      "#{current_state.path}" if current_state
+    end
+
+    # Returns true if the underlying object is in the state specified by the
+    # given path. An object is 'in' a state if the state lies at any point of
+    # the current state's path. E.g:
+    #
+    #     state_manager.current_state.path # returns 'outer.inner'
+    #     state_manager.in_state? 'outer' # true
+    #     state_manager.in_state? 'outer.inner' # true
+    #     state_manager.in_state? 'inner' # false
+    #
+    def in_state?(path)
+      self.find_states(current_state.path).include? find_state(path) 
+    end
+
+    # These methods can be overriden by an adapter
+    def write_state(value)
+      resource.send "#{self.class._state_property.to_s}=", value.path
+    end
+
+    def read_state
+      resource.send self.class._state_property
+    end
+
+    def will_transition(from, to, event)
+    end
+
+    def did_transition(from, to, event)
+    end
+
+    # All events the current state will respond to
+    def available_events
+      state = current_state
+      ret = {}
+      while(state) do
+        ret = state.class.specification.events.merge(ret)
+        state = state.parent_state
+      end
+      ret
+    end
+
+    def self.infer_resource_name!
+      return if _resource_name
+      if name =~ /States/
+        self._resource_name = name.demodulize.gsub(/States/, '').underscore
+        create_resource_accessor!(_resource_name)
+      end
+    end
+
+    def self.inherited(base)
+      super(base)
+      base.infer_resource_name!
+    end
+
+    def self.added_to_resource(klass, property, options)
+    end
+
+    protected
+
+    attr_accessor :current_event
+
+  end
+
+end

data/lib/state_manager/core.rb

@@ -0,0 +1,7 @@
+require 'state_manager/state'
+require 'state_manager/base'
+require 'state_manager/helpers'
+require 'state_manager/dsl'
+require 'state_manager/resource'
+require 'state_manager/adapters'
+require 'state_manager/plugins'

data/lib/state_manager/dsl.rb

@@ -0,0 +1,77 @@
+require 'active_support/core_ext'
+
+module StateManager
+  module DSL
+
+    module State
+      # Specifies a state that is a child of the current state
+      def state(name, klass=nil, &block)
+        # If no base class is specified we look for a class inside the current
+        # state's class which has the same name as the state
+        const_name = name.capitalize
+        klass ||= if const_defined?(const_name)
+          self.const_get(name.capitalize)
+        else
+          Class.new(StateManager::State)
+        end
+        klass = Class.new(klass, &block) if block_given?
+
+        remove_const const_name if const_defined?(const_name)
+        const_set(const_name, klass)
+
+        specification.states[name.to_sym] = klass
+      end
+
+      # Specifies an event on the current state
+      def event(name, options={}, &block)
+        name = name.to_sym
+        event = options.dup
+        event[:name] = name
+        specification.events[name] = event
+        define_method name, &block if block_given?
+      end
+
+      # Helper to simplify creating dsl reader methods for specification
+      # properties
+      module_eval do
+        def self.spec_property(name)
+          class_eval do
+            define_method name do |value|
+              specification.send "#{name}=", value
+            end
+          end
+        end
+      end
+
+      # The initial state
+      def initial_state(value)
+        specification.initial_state = value
+      end
+    end
+
+    module Base
+      def resource_class(value)
+        self._resource_class = value
+      end
+
+      def resource_name(value)
+        self._resource_name = value
+        create_resource_accessor!(_resource_name)
+      end
+
+      def state_property(value)
+        self._state_property = value
+      end
+    end
+    
+  end
+
+  class State
+    extend DSL::State
+  end
+
+  class Base
+    extend DSL::Base
+  end
+
+end

data/lib/state_manager/helpers.rb

@@ -0,0 +1,47 @@
+module StateManager
+  # State helper methods. Examples:
+  #
+  #    @post.event! # send_event! :event
+  #    @post.active? # in_state? :active
+  #    @post.can_event? # respond_to_event? :event
+  #
+  module Helpers
+
+    module Methods
+      def self.define_methods(specification, target_class, property)
+        self.define_methods_helper(specification, target_class, [], property)
+      end
+
+      def self.define_methods_helper(specification, target_class, name_parts, property)
+        sm_proc = Proc.new do
+          self.send "#{property}_manager"
+        end
+
+        specification.events.each do |name, event|
+          target_class.send :define_method, "#{name.to_s}!" do | *args |
+            state_manager = instance_eval &sm_proc
+            state_manager.send_event! name, *args
+          end
+
+          target_class.send :define_method, "can_#{name.to_s}?" do
+            state_manager = instance_eval &sm_proc
+            state_manager.respond_to_event?(name)
+          end
+        end
+
+        specification.states.each do |name, child_class|
+          state_name_parts = name_parts.dup << name
+          method = state_name_parts.join('_')
+          path = state_name_parts.join('.')
+          target_class.send :define_method, "#{method}?" do
+            state_manager = instance_eval &sm_proc
+            state_manager.in_state?(path)
+          end
+
+          define_methods_helper(child_class.specification, target_class, state_name_parts, property)
+        end
+      end
+    end
+
+  end
+end

data/lib/state_manager/plugins/delayed_job.rb

@@ -0,0 +1,54 @@
+if defined?(Delayed)
+
+  module StateManager
+    # Adds support for a :delay property on event definitions. Events with a
+    # delay set will be automatically sent after the delay. If the state is
+    # changed such that the event is no longer available before the delay is
+    # reached, it will be canceled.
+    module DelayedJob
+
+      class DelayedEvent < Struct.new(:path, :event, :state_manager)
+        def perform
+          return unless state_manager.respond_to_event?(event[:name]) &&
+            state_manager.in_state?(path)
+          state_manager.send_event! event[:name]
+        end
+      end
+
+      module State
+
+        def delayed_events
+          self.class.specification.events.reject{|name,event|!event[:delay]}
+        end
+
+        def entered
+          delayed_events.each do |name, event|
+            delay = event[:delay]
+            delayed_event = DelayedEvent.new(path, event, state_manager)
+            Delayed::Job.enqueue delayed_event, :run_at => delay.from_now
+          end
+        end
+
+        def exited
+          # TODO: we currently just have logic inside the job itself which
+          # skips the event if it is no longer relevant. This is not perfect.
+          # Ideally we should cancel events in this method (requiring an
+          # efficient way to do this without looping over all events).
+        end
+      end
+    end
+
+    class State
+      include DelayedJob::State
+
+      def entered
+        super
+      end
+
+      def exited
+        super
+      end
+    end
+  end
+
+end

data/lib/state_manager/plugins.rb

@@ -0,0 +1,4 @@
+# Load each available plugin
+Dir["#{File.dirname(__FILE__)}/plugins/*.rb"].sort.each do |path|
+  require "state_manager/plugins/#{File.basename(path)}"
+end

data/lib/state_manager/resource.rb

@@ -0,0 +1,83 @@
+module StateManager
+  module Resource
+
+    def self.extended(base)
+      base.instance_eval do
+        class_attribute :state_managers
+        self.state_managers = {}
+
+        attr_accessor :state_managers
+      end
+
+      base.send :include, InstanceMethods
+    end
+
+    def state_manager(property=:state, klass=nil, options={}, &block)
+      default_options = {:helpers => true}
+      options = default_options.merge(options)
+
+      klass ||= begin
+        "#{self.name}States".constantize
+      rescue NameError
+        nil
+      end
+      klass ||= StateManager::Base
+
+      # Create a subclass of the specified state manager and mixin an adapter
+      # if a matching one is found
+      this = self
+      adapter = Adapters.match(self)
+      resource_name = self.name.demodulize.underscore
+      
+      klass = Class.new(klass) do
+        state_property property
+        resource_class this
+        resource_name resource_name
+        include adapter.const_get('ManagerMethods') if adapter
+        class_eval &block if block_given?
+      end
+      include adapter.const_get('ResourceMethods') if adapter
+
+      # Callbacks
+      state_manager_added(property, klass, options) if respond_to? :state_manager_added
+      klass.added_to_resource(self, property, options)
+
+      # Define the subclass as a constant. We do this for multiple reasons, one
+      # of which is to allow it to be serialized to YAML for delayed_job
+      const_name = "#{property.to_s.camelize}States"
+      remove_const const_name if const_defined?(const_name)
+      const_set(const_name, klass)
+
+      # Create an accessor for the state manager on this resource
+      state_managers[property] = klass
+      property_name = "#{property.to_s}_manager"
+      define_method property_name do
+        self.state_managers ||= {}
+        state_manager = state_managers[property]
+        unless state_manager
+          state_manager = klass.new(self)
+          state_managers[property] = state_manager
+        end
+        state_manager
+      end
+
+      # Define the helper methods on the resource
+      Helpers::Methods.define_methods(klass.specification, self, property) if options[:helpers]
+    end
+
+    module InstanceMethods
+      # Ensures that all properties with state managers are in valid states
+      def validate_states!
+        self.state_managers ||= {}
+        self.class.state_managers.each do |name, klass|
+          # Simply ensuring that all of the state managers have been
+          # instantiated will make the corresponding states valid
+          unless state_managers[name]
+            state_managers[name] = klass.new(self)
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/state_manager/state.rb

@@ -0,0 +1,146 @@
+require 'active_support/core_ext'
+
+module StateManager
+  class State
+
+    # Represents the static specification of this state. This consists of all
+    # child states and events. During initialization, the specification will
+    # be read and the child states and events will be initialized.
+    class Specification
+      attr_accessor :states, :events, :initial_state
+
+      def initialize
+        self.states = {}
+        self.events = {}
+      end
+
+      def initialize_copy(source)
+        self.states = source.states.dup
+        self.events = source.events.dup
+      end
+    end
+
+    class_attribute :specification
+    self.specification = Specification.new
+
+    def self.inherited(child)
+      # Give all sublcasses a clone of this states specification. Subclasses can
+      # add events and states to their specification without affecting the
+      # parent
+      child.specification = specification.clone
+    end
+
+    attr_reader :name, :states, :parent_state
+
+    def initialize(name, parent_state)
+      self.name = name
+      self.parent_state = parent_state
+      self.states = self.class.specification.states.inject({}) do |states, (name, klazz)|
+        states[name] = klazz.new(name, self)
+        states
+      end
+    end
+
+    # String representing the path of the current state, e.g.:
+    # 'parentState.childState'
+    def path
+      path = name.to_s
+      path = "#{parent_state.path}.#{path}" if parent_state && parent_state.name
+      path
+    end
+
+    def enter
+    end
+
+    def exit
+    end
+
+    def entered
+    end
+
+    def exited
+    end
+
+    def to_s
+      "#{path}"
+    end
+
+    def to_sym
+      path.to_sym
+    end
+
+    def state_manager
+      parent_state.state_manager
+    end
+
+    # Get the resource stored on the state manager
+    def resource
+      state_manager.resource
+    end
+
+    def transition_to(*args)
+      state_manager.transition_to(*args)
+    end
+
+    def has_event?(name)
+      name = name.to_sym
+      !!self.class.specification.events[name]
+    end
+
+    def send_event(name, *args)
+      name = name.to_sym
+      event = self.class.specification.events[name]
+      send(name, *args) if respond_to?(name)
+      transition_to(event[:transitions_to]) if event[:transitions_to]
+    end
+
+    # Find all the states along the path
+    def find_states(path)
+      state = self
+      parts = path.split('.')
+      ret = [state]
+      parts.each do |name|
+        state = state.states[name.to_sym]
+        ret << state
+        return unless state
+      end
+      ret
+    end
+
+    # Returns the state at the given path
+    def find_state(path)
+      states = find_states(path)
+      states && states.last
+    end
+
+    def leaf?
+      states.empty?
+    end
+
+    # If an initial state is not explicitly specified, we choose the first leaf
+    # state
+    def initial_state
+      if state = self.class.specification.initial_state
+        find_state(state.to_s)
+      elsif leaf?
+        self
+      else
+        states.values.first.initial_state
+      end
+    end
+
+    def self.create_resource_accessor!(name)
+      unless method_defined?(name)
+        define_method name do
+          resource
+        end
+      end
+      specification.states.values.each {|s|s.create_resource_accessor!(name)}
+    end
+
+    protected
+    
+    attr_writer :name, :states, :parent_state
+
+  end
+end

data/lib/state_manager.rb

@@ -0,0 +1 @@
+require 'state_manager/core'

data/state_manager.gemspec

@@ -0,0 +1,102 @@
+# 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 = "state_manager"
+  s.version = "0.2.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gordon Hempton"]
+  s.date = "2012-06-06"
+  s.description = "Finite state machine implementation that keeps logic separate from model classes and supports sub-states."
+  s.email = "ghempton@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/state_manager.rb",
+    "lib/state_manager/adapters.rb",
+    "lib/state_manager/adapters/active_record.rb",
+    "lib/state_manager/adapters/base.rb",
+    "lib/state_manager/base.rb",
+    "lib/state_manager/core.rb",
+    "lib/state_manager/dsl.rb",
+    "lib/state_manager/helpers.rb",
+    "lib/state_manager/plugins.rb",
+    "lib/state_manager/plugins/delayed_job.rb",
+    "lib/state_manager/resource.rb",
+    "lib/state_manager/state.rb",
+    "state_manager.gemspec",
+    "test/adapters/active_record_test.rb",
+    "test/basic_test.rb",
+    "test/definition_test.rb",
+    "test/helper.rb",
+    "test/helpers_test.rb",
+    "test/plugins/delayed_job_test.rb",
+    "test/transitions_test.rb"
+  ]
+  s.homepage = "http://github.com/ghempton/statemanager"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.15"
+  s.summary = "%Q{Finite state machine implementation.}"
+
+  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>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<pry>, [">= 0"])
+      s.add_development_dependency(%q<pry-doc>, [">= 0"])
+      s.add_development_dependency(%q<pry-remote>, [">= 0"])
+      s.add_development_dependency(%q<pry-nav>, [">= 0"])
+      s.add_development_dependency(%q<pry-stack_explorer>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
+      s.add_development_dependency(%q<delayed_job_active_record>, [">= 0"])
+      s.add_development_dependency(%q<activerecord>, [">= 0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 0"])
+      s.add_development_dependency(%q<timecop>, [">= 0"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 0"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<pry>, [">= 0"])
+      s.add_dependency(%q<pry-doc>, [">= 0"])
+      s.add_dependency(%q<pry-remote>, [">= 0"])
+      s.add_dependency(%q<pry-nav>, [">= 0"])
+      s.add_dependency(%q<pry-stack_explorer>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+      s.add_dependency(%q<delayed_job_active_record>, [">= 0"])
+      s.add_dependency(%q<activerecord>, [">= 0"])
+      s.add_dependency(%q<sqlite3>, [">= 0"])
+      s.add_dependency(%q<timecop>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 0"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<pry>, [">= 0"])
+    s.add_dependency(%q<pry-doc>, [">= 0"])
+    s.add_dependency(%q<pry-remote>, [">= 0"])
+    s.add_dependency(%q<pry-nav>, [">= 0"])
+    s.add_dependency(%q<pry-stack_explorer>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+    s.add_dependency(%q<delayed_job_active_record>, [">= 0"])
+    s.add_dependency(%q<activerecord>, [">= 0"])
+    s.add_dependency(%q<sqlite3>, [">= 0"])
+    s.add_dependency(%q<timecop>, [">= 0"])
+  end
+end
+