beawesomeinstead-fsm 0.1.0

data/fsm.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |s|
+  s.name = "fsm"
+  s.version = "0.1.0"
+  s.date = "2008-07-11"
+  s.summary = "Finite state machine."
+  s.email = "beawesomeinstead@yahoo.com"
+  s.homepage = "http://github.com/beawesomeinstead/fsm/wikis"
+  s.description = s.summary
+  s.authors = ["beawesomeinstead"]
+  s.has_rdoc = false
+  s.require_paths = ["libraries"]
+  s.files = ["libraries/fsm", "libraries/fsm/active_record.rb", "libraries/fsm/event.rb", "libraries/fsm/state.rb", "libraries/fsm/state_machine.rb", "libraries/fsm/transition.rb", "libraries/fsm.rb", "specifications/integration", "specifications/integration/fsm_spec.rb", "specifications/integration/state_spec.rb", "specifications/spec_helper.rb", "rakefile", "readme", "fsm.gemspec"]
+end

data/libraries/fsm.rb

@@ -0,0 +1,11 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require "activerecord"
+
+%w(state_machine state transition event active_record).map { |x| require "fsm/#{x}" }
+
+ActiveRecord::Base.class_eval do
+  include StateMachine
+  include StateMachine::ORM::ActiveRecord
+end

data/libraries/fsm/active_record.rb

@@ -0,0 +1,78 @@
+module StateMachine #:nodoc:
+  module ORM #:nodoc:
+    module ActiveRecord #:nodoc:
+      def self.included(recipient)
+        recipient.send(:extend, ActMethods)
+        recipient.send(:extend, ClassMethods)
+      end
+
+      module ActMethods #:nodoc:
+        # ==== Parameters
+        # options<Hash>:: An options hash (see below).
+        #
+        # ==== Options (options)
+        # :column<Symbol>:: specifies the column name to use for keeping the state (default: state).
+        # :initial<Symbol>:: specifies an initial state for newly created objects (required).
+        def state_machine(options)
+          raise NoInitialState unless options[:initial]
+
+          write_inheritable_attribute :states, {}
+          write_inheritable_attribute :initial_state, options[:initial]
+          write_inheritable_attribute :transition_table, {}
+          write_inheritable_attribute :event_table, {}
+          write_inheritable_attribute :state_column, options[:column] || "state"
+
+          class_inheritable_reader    :initial_state
+          class_inheritable_reader    :state_column
+          class_inheritable_reader    :transition_table
+          class_inheritable_reader    :event_table
+
+          before_create               :set_initial_state
+          after_create                :run_initial_state_actions
+        end
+      end
+
+      module ClassMethods #:nodoc:
+        # Wraps ActiveRecord::Base.find to conveniently find all records in a given state.
+        # ==== Parameters
+        # number<Symbol>:: This is just :first or :all from ActiveRecord +find+.
+        # state<String, Symbol>:: The state to find.
+        # args:: The rest of the args are passed down to ActiveRecord +find+.
+        def find_in_state(number, state, *args)
+          with_state_scope state do
+            find(number, *args)
+          end
+        end
+
+        # Wraps ActiveRecord::Base.count to conveniently count all records in a given state.
+        # ==== Parameters
+        # state<String, Symbol>:: The state to find.
+        # args:: The rest of the args are passed down to ActiveRecord +find+.
+        def count_in_state(state, *args)
+          with_state_scope state do
+            count(*args)
+          end
+        end
+
+        # Wraps ActiveRecord::Base.calculate to conveniently calculate all records in a given state.
+        # ==== Parameters
+        # state<String, Symbol>:: The state to find.
+        # args:: The rest of the args are passed down to ActiveRecord +calculate+.
+        def calculate_in_state(state, *args)
+          with_state_scope state do
+            calculate(*args)
+          end
+        end
+
+        protected
+          def with_state_scope(state)
+            raise InvalidState unless states.include?(state)
+
+            with_scope :find => {:conditions => ["#{table_name}.#{state_column} = ?", state.to_s]} do
+              yield if block_given?
+            end
+          end
+      end
+    end
+  end
+end

data/libraries/fsm/event.rb

@@ -0,0 +1,31 @@
+module StateMachine #:nodoc:
+  class Event #:nodoc:
+    attr_reader :name, :transitions, :options
+
+    def initialize(name, options, transition_table, &block)
+      @name = name.to_sym
+      @transitions = transition_table[@name] = []
+      instance_eval(&block) if block
+      @options = options
+      @options.freeze
+      @transitions.freeze
+      freeze
+    end
+
+    def next_states(record)
+      @transitions.select { |t| t.from == record.current_state }
+    end
+
+    def fire(record)
+      next_states(record).each do |transition|
+        break true if transition.perform(record)
+      end
+    end
+
+    def transitions(transition_options)
+      Array(transition_options[:from]).each do |s|
+        @transitions << Transition.new(transition_options.merge({:from => s.to_sym}))
+      end
+    end
+  end
+end

data/libraries/fsm/state.rb

@@ -0,0 +1,27 @@
+module StateMachine #:nodoc:
+  class State #:nodoc:
+    attr_reader :name
+
+    def initialize(name, options)
+      @name, @options = name, options
+    end
+
+    def entering(record)
+      enteract = @options[:enter]
+      record.send(:run_transition_action, enteract) if enteract
+    end
+
+    def entered(record)
+      afteractions = @options[:after]
+      return unless afteractions
+      Array(afteractions).each do |afteract|
+        record.send(:run_transition_action, afteract)
+      end
+    end
+
+    def exited(record)
+      exitact  = @options[:exit]
+      record.send(:run_transition_action, exitact) if exitact
+    end
+  end
+end

data/libraries/fsm/state_machine.rb

@@ -0,0 +1,77 @@
+module StateMachine #:nodoc:
+  class InvalidState < Exception; end
+  class NoInitialState < Exception; end
+
+  def self.included(recipient)
+    recipient.send(:extend, ClassMethods)
+    recipient.send(:include, InstanceMethods)
+  end
+
+  module InstanceMethods #:nodoc:
+    def set_initial_state
+      write_attribute(self.class.state_column, self.class.initial_state.to_s)
+    end
+
+    def run_initial_state_actions
+      initial = self.class.read_inheritable_attribute(:states)[self.class.initial_state.to_sym]
+      initial.entering(self)
+      initial.entered(self)
+    end
+
+    # Returns the current state the object is in, as a Ruby symbol.
+    def current_state
+      self.send(self.class.state_column).to_sym
+    end
+
+    # Returns what the next state for a given event would be, as a Ruby symbol.
+    def next_state_for_event(event)
+      ns = next_states_for_event(event)
+      ns.empty? ? nil : ns.first.to
+    end
+
+    def next_states_for_event(event)
+      self.class.read_inheritable_attribute(:transition_table)[event.to_sym].select do |s|
+        s.from == current_state
+      end
+    end
+
+    private
+      def run_transition_action(action)
+        Symbol === action ? self.method(action).call : action.call(self)
+      end
+  end
+
+  module ClassMethods #:nodoc:
+    # Returns an array of all known states.
+    def states
+      read_inheritable_attribute(:states).keys
+    end
+
+    # Define an event. This takes a block which describes all valid transitions for this event.
+    # This creates an instance method used for firing the event. The method created is the name of the event followed
+    # by an exclamation point (!).
+    # ==== Parameters
+    # transitions<Hash>:: takes a hash where <tt>:to</tt> is the state to transition to and <tt>:from</tt> is a state
+    #   (or Array of states) from which this event can be fired.
+    def event(event, options = {}, &block)
+      tt = read_inheritable_attribute(:transition_table)
+
+      et = read_inheritable_attribute(:event_table)
+      e = et[event.to_sym] = Event.new(event, options, tt, &block)
+      define_method("#{event.to_s}!") { e.fire(self) }
+    end
+
+    # Define a state of the system. +state+ can take an optional Proc object which will be executed every time the
+    # system transitions into that state. The proc will be passed the current object.
+    def state(*args)
+      options = args.extract_options!
+
+      args.each do |name|
+        state = State.new(name.to_sym, options)
+        read_inheritable_attribute(:states)[name.to_sym] = state
+
+        define_method("#{state.name}?") { current_state == state.name }
+      end
+    end
+  end
+end

data/libraries/fsm/transition.rb

@@ -0,0 +1,34 @@
+module StateMachine #:nodoc:
+  class Transition #:nodoc:
+    attr_reader :from, :to, :options
+
+    def initialize(options)
+      @from, @to, @guard = options[:from], options[:to], options[:guard]
+      @options = options
+    end
+
+    def guard(object)
+      @guard ? object.send(:run_transition_action, @guard) : true
+    end
+
+    def perform(record)
+      return false unless guard(record)
+      loopback = record.current_state == to
+      states = record.class.read_inheritable_attribute(:states)
+      next_state = states[to]
+      old_state = states[record.current_state]
+
+      next_state.entering(record) unless loopback
+
+      record.update_attribute(record.class.state_column, to.to_s)
+
+      next_state.entered(record) unless loopback
+      old_state.exited(record) unless loopback
+      true
+    end
+
+    def ==(object)
+      @from == object.from && @to == object.to
+    end
+  end
+end

data/rakefile

@@ -0,0 +1,6 @@
+%w(rubygems rake/gempackagetask spec/rake/spectask).each { |x| require x }
+
+Spec::Rake::SpecTask.new("specs") do |t|
+  t.spec_opts << '--format' << 'specdoc' << '--colour'
+  t.spec_files = Dir.glob("specifications/**/*_spec.rb")
+end

data/specifications/integration/fsm_spec.rb

@@ -0,0 +1,4 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
+
+describe StateMachine do
+end

data/specifications/integration/state_spec.rb

@@ -0,0 +1,4 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
+
+describe StateMachine::State do
+end

data/specifications/spec_helper.rb

@@ -0,0 +1,2 @@
+%w(rubygems spec).each { |x| require x }
+require File.join(File.dirname(__FILE__), "..", "libraries", "fsm")

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: beawesomeinstead-fsm
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- beawesomeinstead
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-11 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Finite state machine.
+email: beawesomeinstead@yahoo.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- libraries/fsm
+- libraries/fsm/active_record.rb
+- libraries/fsm/event.rb
+- libraries/fsm/state.rb
+- libraries/fsm/state_machine.rb
+- libraries/fsm/transition.rb
+- libraries/fsm.rb
+- specifications/integration
+- specifications/integration/fsm_spec.rb
+- specifications/integration/state_spec.rb
+- specifications/spec_helper.rb
+- rakefile
+- readme
+- fsm.gemspec
+has_rdoc: false
+homepage: http://github.com/beawesomeinstead/fsm/wikis
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- libraries
+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: Finite state machine.
+test_files: []
+