anthonyw-simple_state 0.1.1 → 0.1.2

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "simple_state"
+    gem.platform    = Gem::Platform::RUBY
+    gem.summary     = 'A *very simple* state machine implementation.'
+    gem.description = gem.summary
+    gem.email       = "anthony@ninecraft.com"
+    gem.homepage    = "http://github.com/anthonyw/simple_state"
+    gem.authors     = ["Anthony Williams"]
+
+    gem.extra_rdoc_files = %w(README.markdown LICENSE)
+
+    gem.files = %w(LICENSE README.markdown Rakefile VERSION.yml) +
+                Dir.glob("{lib,spec}/**/*")
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install " \
+       "technicalpickles-jeweler -s http://gems.github.com"
+end
+
+# rDoc =======================================================================
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'simple_state'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# rSpec & rcov ===============================================================
+
+desc "Run all examples (or a specific spec with TASK=xxxx)"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_opts  = ["-c -f s"]
+  t.spec_files = begin
+    if ENV["TASK"]
+      ENV["TASK"].split(',').map { |task| "spec/**/#{task}_spec.rb" }
+    else
+      FileList['spec/**/*_spec.rb']
+    end
+  end
+end
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('spec:rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ['-c -f s']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+task :default => :spec

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 2

data/lib/simple_state/builder.rb

@@ -0,0 +1,117 @@
+module SimpleState
+  ##
+  # Responsible for taking a state machine block and building the methods.
+  #
+  # The builder is run whenever you call +state_machine+ on a class and does
+  # a number of things.
+  #
+  #   * Firstly, it adds a :state reader if one is not defined, and a
+  #     _private_ :state writer.
+  #
+  #   * It adds a +states+ method to the class, used for easily accessing
+  #     the list of states for the class, and the events belonging to each
+  #     state (and the state that the event transitions to).
+  #
+  #   * Four internal methods +initial_state+, +initial_state=+,
+  #     +_determine_new_state+ and +_valid_transition+ which are used
+  #     internally by SimpleState for aiding the transition from one state to
+  #     another.
+  #
+  class Builder
+    def initialize(klass)
+      @klass = klass
+    end
+
+    ##
+    # Trigger for building the state machine methods.
+    #
+    def build(&blk)
+      @klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        include ::SimpleState::Mixins
+      RUBY
+
+      instance_eval(&blk)
+    end
+
+    ##
+    # Defines a new state.
+    #
+    # @param [Symbol] name
+    #   The name of the state.
+    # @param [Block] &blk
+    #   An optional block for defining transitions for the state. If no block
+    #   is given, the state will be an end-point.
+    #
+    def state(name, &blk)
+      @klass.states[name] = []
+      @klass.initial_state ||= name
+
+      @klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}?                # def prepared?
+          self.state == :#{name}    #   self.state == :prepared
+        end                         # end
+      RUBY
+
+      # Define transitions for this state.
+      StateBuilder.new(@klass, name).build(&blk) if blk
+    end
+
+    ##
+    # Responsible for building events for a given state.
+    #
+    class StateBuilder
+      def initialize(klass, state)
+        @klass, @state = klass, state
+      end
+
+      ##
+      # Specialises a state by defining events.
+      #
+      # @param [Block]  &blk
+      #   An block for defining transitions for the state.
+      #
+      def build(&blk)
+        instance_eval(&blk)
+      end
+
+      ##
+      # Defines an event and transition.
+      #
+      # @param [Symbol] event_name A name for this event.
+      # @param [Hash]   opts       An options hash for customising the event.
+      #
+      def event(event, opts = {})
+        unless opts[:transitions_to].kind_of?(Symbol)
+          raise ArgumentError, 'You must declare a :transitions_to state ' \
+                               'when defining events'
+        end
+
+        # Keep track of valid transitions for this state.
+        @klass.states[@state].push([event, opts[:transitions_to]])
+
+        unless @klass.method_defined?(:"#{event}!")
+          # Example:
+          #
+          # def process!
+          #   if self.class._valid_transition?(self.state, :process)
+          #     self.state =
+          #       self.class._determine_new_state(self.state, :process)
+          #   else
+          #     false
+          #   end
+          # end
+          @klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{event}!
+              if self.class._valid_transition?(self.state, :#{event})
+                self.state =
+                  self.class._determine_new_state(self.state, :#{event})
+              else
+                false
+              end
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/simple_state/mixins.rb

@@ -0,0 +1,65 @@
+module SimpleState
+  module Mixins
+    def self.included(klass)
+      klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        attr_reader :state unless method_defined?(:state)
+        @@states = {}
+        @@initial_state = nil
+
+        unless method_defined?(:state=)
+          attr_writer :state
+          private :state=
+        end
+
+        extend  Singleton
+        include Instance
+      RUBY
+    end
+
+    ##
+    # Defines singleton methods which are mixed in to a class when
+    # state_machine is called.
+    #
+    module Singleton
+      # @api private
+      def states
+        class_variable_get(:@@states)
+      end
+
+      # @api public
+      def initial_state=(state)
+        class_variable_set(:@@initial_state, state)
+      end
+
+      # @api public
+      def initial_state
+        class_variable_get(:@@initial_state)
+      end
+
+      # @api private
+      def _determine_new_state(current, to)
+        states[current] && (t = states[current].assoc(to)) && t.last
+      end
+
+      # @api private
+      def _valid_transition?(current, to)
+        states[current] and not states[current].assoc(to).nil?
+      end
+    end
+
+    ##
+    # Defines instance methods which are mixed in to a class when
+    # state_machine is called.
+    #
+    module Instance
+      ##
+      # Set the initial value for the state machine after calling the original
+      # initialize method.
+      #
+      def initialize(*args, &blk)
+        super
+        self.state = self.class.initial_state
+      end
+    end # Instance
+  end # Mixins
+end # SimpleState

data/lib/simple_state.rb

@@ -0,0 +1,14 @@
+module SimpleState
+  class Error < StandardError; end
+  class ArgumentError < Error; end
+
+  ##
+  # Sets up a state machine on the current class.
+  #
+  def state_machine(&blk)
+    Builder.new(self).build(&blk)
+  end
+end
+
+require 'simple_state/builder'
+require 'simple_state/mixins'

data/spec/builder_spec.rb

@@ -0,0 +1,71 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+# Basic State Machine ========================================================
+
+describe SimpleState::Builder do
+  before(:each) do
+    @c = state_class do
+      state :prepared
+      state :processed
+    end
+  end
+
+  it 'should add a private state writer' do
+    @c.private_methods.map { |m| m.to_sym }.should include(:state=)
+  end
+
+  it 'should add a state reader' do
+    @c.methods.map { |m| m.to_sym }.should include(:state)
+  end
+
+  describe 'when defining states with no events' do
+    it 'should create a predicate' do
+      methods = @c.methods.map { |m| m.to_sym }
+      methods.should include(:prepared?)
+      methods.should include(:processed?)
+    end
+
+    it 'should add the state to register' do
+      @c.class.states.keys.should include(:prepared)
+      @c.class.states.keys.should include(:processed)
+    end
+  end
+end
+
+# State Machine with Events ==================================================
+
+describe 'when defining a state with an event' do
+  before(:each) do
+    @evented_state = state_class do
+      state :prepared do
+        event :process,           :transitions_to => :processed
+        event :processing_failed, :transitions_to => :failed
+      end
+
+      state :processed
+    end
+  end
+
+  it 'should add a bang method for the transition' do
+    @evented_state.methods.map { |m| m.to_sym }.should \
+      include(:process!)
+    @evented_state.methods.map { |m| m.to_sym }.should \
+      include(:processing_failed!)
+  end
+
+  it 'should add the state to register' do
+    @evented_state.class.states.keys.should include(:prepared)
+    @evented_state.class.states.keys.should include(:processed)
+  end
+
+  it 'should raise an argument error if no :transitions_to is provided' do
+    lambda {
+      Class.new do
+        extend SimpleState
+        state_machine do
+          state(:prepared) { event :process }
+        end
+      end
+    }.should raise_error(SimpleState::ArgumentError)
+  end
+end

data/spec/event_methods_spec.rb

@@ -0,0 +1,199 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+# Event Validation ===========================================================
+
+describe 'Generated event methods when the transition is valid' do
+  before(:each) do
+    @c = state_class do
+      state :begin do
+        event :go, :transitions_to => :state_one
+      end
+
+      state :state_one
+    end
+  end
+
+  it 'should return the new state' do
+    @c.go!.should == :state_one
+  end
+
+  it 'should transition the instance to the new state' do
+    @c.go!
+    @c.should be_state_one
+  end
+end
+
+describe 'Generated event methods when the transition is not valid' do
+  before(:each) do
+    @c = state_class do
+      state :begin do
+        event :go, :transitions_to => :state_one
+      end
+
+      state :state_one do
+        event :go_again, :transitions_to => :state_two
+      end
+
+      state :state_two
+    end
+  end
+
+  it 'should return false' do
+    @c.go_again!.should be_false
+  end
+
+  it "should not change the instance's state" do
+    @c.go_again!
+    @c.should be_begin
+  end
+end
+
+
+# Multiple Paths Definition ==================================================
+
+describe 'Generated event methods when mulitple states share the same event' do
+  before(:each) do
+    @path = state_class do
+      state :begin do
+        event :s1, :transitions_to => :state_one
+        event :s2, :transitions_to => :state_two
+      end
+
+      state :state_one do
+        event :go, :transitions_to => :state_three
+      end
+
+      state :state_two do
+        event :go, :transitions_to => :state_four
+      end
+
+      state :state_three
+      state :state_four
+    end
+  end
+
+  it 'should transition to state_three if currently in state_one' do
+    @path.s1!
+    @path.go!
+    @path.should be_state_three
+  end
+
+  it 'should transition to state_four if current in state_two' do
+    @path.s2!
+    @path.go!
+    @path.should be_state_four
+  end
+end
+
+
+# Test full workflow =========================================================
+# This tests all the possible transition permutations of a state machine.
+
+describe 'Generated event methods (integration)' do
+  before(:each) do
+    @c = state_class do
+      state :prepared do
+        event :requires_decompress, :transitions_to => :requires_decompress
+        event :invalid_extension,   :transitions_to => :halted
+        event :processed,           :transitions_to => :processed
+        event :processing_failed,   :transitions_to => :halted
+      end
+
+      state :processed do
+        event :stored,              :transitions_to => :stored
+        event :store_failed,        :transitions_to => :halted
+      end
+
+      state :requires_decompress do
+        event :decompressed,        :transitions_to => :complete
+        event :decompress_failed,   :transitions_to => :halted
+      end
+
+      state :stored do
+        event :cleaned,             :transitions_to => :complete
+      end
+
+      state :halted do
+        event :cleaned,             :transitions_to => :failed
+      end
+
+      state :failed
+      state :complete
+    end
+  end
+
+  it 'should successfully change the state to complete via the ' \
+           'intermediate states' do
+
+    # begin -> processed -> stored -> complete
+
+    @c.should be_prepared
+
+    @c.processed!.should == :processed
+    @c.should be_processed
+
+    @c.stored!.should    == :stored
+    @c.should be_stored
+
+    @c.cleaned!.should   == :complete
+    @c.should be_complete
+  end
+
+  it 'should successfully change the state to complete via successful ' \
+     'decompress' do
+
+    # begin -> requires_decompress -> complete
+
+    @c.requires_decompress!.should == :requires_decompress
+    @c.should be_requires_decompress
+
+    @c.decompressed!.should == :complete
+    @c.should be_complete
+  end
+
+  it 'should successfully change the state to failed via failed decompress' do
+    # begins -> requires_decompress -> halted -> failed
+
+    @c.requires_decompress!.should == :requires_decompress
+    @c.should be_requires_decompress
+
+    @c.decompress_failed!.should == :halted
+    @c.should be_halted
+
+    @c.cleaned!.should == :failed
+    @c.should be_failed
+  end
+
+  it 'should successfully change the state to failed via invalid extension' do
+    # begins -> halted -> failed
+
+    @c.invalid_extension!.should == :halted
+    @c.should be_halted
+
+    @c.cleaned!.should == :failed
+    @c.should be_failed
+  end
+
+  it 'should successfully change the state to failed via failed processing' do
+    # begins -> halted -> failed
+
+    @c.processing_failed!.should == :halted
+    @c.should be_halted
+
+    @c.cleaned!.should == :failed
+    @c.should be_failed
+  end
+
+  it 'should successfully change the state to failed via failed storage' do
+    # begins -> processed -> halted -> failed
+
+    @c.processed!.should == :processed
+    @c.should be_processed
+
+    @c.store_failed!.should == :halted
+    @c.should be_halted
+
+    @c.cleaned!.should == :failed
+    @c.should be_failed
+  end
+end

data/spec/mixins_spec.rb

@@ -0,0 +1,47 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+describe SimpleState::Mixins::Instance do
+  describe '#initialize' do
+    it 'should set the initial state' do
+      c = state_class do
+        state :begin
+        state :finish
+      end
+
+      c.state.should == :begin
+    end
+
+    it 'should call the original #initialize' do
+      parent = Class.new do
+        attr_reader :called
+
+        def initialize
+          @called = true
+        end
+      end
+
+      child = Class.new(parent) do
+        extend SimpleState
+        state_machine do
+          state :begin
+        end
+      end
+
+      child.new.called.should be_true
+      child.new.state.should == :begin
+    end
+
+    it 'should have separate state machines for each class' do
+      class_one = state_class do
+        state :one
+      end
+
+      class_two = state_class do
+        state :two
+      end
+
+      class_one.class.states.keys.should == [:one]
+      class_two.class.states.keys.should == [:two]
+    end
+  end
+end

data/spec/predicate_methods_spec.rb

@@ -0,0 +1,20 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+describe SimpleState, 'generated predicate methods' do
+  before(:each) do
+    @predicate_test = state_class do
+      state :state_one
+      state :state_two
+      state :state_three
+    end
+  end
+
+  it 'should return true if the current state matches the predicate' do
+    @predicate_test.should be_state_one
+  end
+
+  it 'should return false if the current state does not match the predicate' do
+    @predicate_test.should_not be_state_two
+    @predicate_test.should_not be_state_three
+  end
+end

data/spec/simple_state_spec.rb

@@ -0,0 +1,10 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+describe "SimpleState" do
+  it "should add a state_machine method to the class" do
+    Class.new { extend SimpleState }.methods.map do |m|
+      # Ruby 1.9 compat.
+      m.to_sym
+    end.should include(:state_machine)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'spec'
+
+# $LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'simple_state'
+
+##
+# Creates an anonymous class which uses SimpleState.
+#
+def state_class(&blk)
+  Class.new do
+    extend SimpleState
+    state_machine(&blk)
+  end.new
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: anthonyw-simple_state
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Anthony Williams
@@ -23,8 +23,20 @@ extra_rdoc_files:
 - README.markdown
 - LICENSE
 files: 
-- README.markdown
 - LICENSE
+- README.markdown
+- Rakefile
+- VERSION.yml
+- lib/simple_state
+- lib/simple_state/builder.rb
+- lib/simple_state/mixins.rb
+- lib/simple_state.rb
+- spec/builder_spec.rb
+- spec/event_methods_spec.rb
+- spec/mixins_spec.rb
+- spec/predicate_methods_spec.rb
+- spec/simple_state_spec.rb
+- spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/anthonyw/simple_state
 post_install_message: