composable_state_machine 1.0.2

data/spec/lib/composable_state_machine/machine_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe ComposableStateMachine::Machine do
+
+  describe '#initialization' do
+    it 'can set the initial state' do
+      model = double(callback_runner: proc {})
+      machine = described_class.new(model, state: :test_state)
+
+      machine.should be_kind_of ComposableStateMachine::MachineWithExternalState
+      machine.state.should eq :test_state
+    end
+
+    it 'delegates to MachineWithExternalState hooking up #state updates' do
+      model = ComposableStateMachine.model(
+          initial_state: :first, transitions: {next: {first: :second}})
+      machine = described_class.new(model)
+
+      machine.state.should eq :first
+      machine.trigger(:next).should eq :second
+      machine.state.should eq :second
+    end
+  end
+
+end

data/spec/lib/composable_state_machine/machine_with_external_state_spec.rb

@@ -0,0 +1,97 @@
+require 'spec_helper'
+
+describe ComposableStateMachine::MachineWithExternalState do
+
+  let(:transitions) do
+    ComposableStateMachine::Transitions.new(
+        {
+            hire: {candidate: :hired},
+            leave: {hired: :departed},
+            fire: {hired: :fired},
+        }
+    )
+  end
+
+  let(:model) do
+    ComposableStateMachine::Model.new(
+        initial_state: :candidate,
+        transitions: transitions
+    )
+  end
+
+  let(:model_with_behavior) do
+    ComposableStateMachine::Model.new(
+        initial_state: :candidate,
+        transitions: transitions,
+        behaviors: ComposableStateMachine::Behaviors.new(
+            {
+                enter: {hired: proc {}}
+            }
+        )
+    )
+  end
+
+  before do
+    @state = nil
+    @state_reader = lambda { @state }
+    @state_writer = lambda { |new_state| @state = new_state }
+  end
+
+  describe '#initialization' do
+    it 'sets the state to the initial state of the model by default' do
+      described_class.new(model, @state_reader, @state_writer)
+
+      @state.should eq :candidate
+    end
+
+    it 'can set the initial state' do
+      described_class.new(model, @state_reader, @state_writer, state: :hired)
+
+      @state.should eq :hired
+    end
+
+    it 'can specify the callback runner' do
+      runner = double(run_state_machine_callback: nil)
+      machine = described_class.new(model_with_behavior, @state_reader, @state_writer,
+                                    callback_runner: runner, state: :candidate)
+
+      runner.should_receive(:run_state_machine_callback).with(an_instance_of(Proc), :candidate, :hire, :hired)
+
+      machine.trigger(:hire)
+    end
+  end
+
+  describe 'main API' do
+    subject { described_class.new(model, @state_reader, @state_writer) }
+
+    describe '#trigger' do
+      it 'transitions via the model' do
+        model.should_receive(:transition).with(
+            :candidate, :hire, [], ComposableStateMachine::DefaultCallbackRunner).
+            and_call_original
+
+        subject.trigger(:hire).should eq :hired
+      end
+
+      it 'updates the state when a transition is made' do
+        subject.trigger(:hire)
+
+        @state.should eq :hired
+      end
+
+      it 'does not update the state when a transition is not made' do
+        subject.trigger(:hire)
+
+        subject.trigger(:hire).should be_nil
+        @state.should eq :hired
+      end
+    end
+
+    describe '#==' do
+      it 'compares equality based on the state' do
+        subject.should == :candidate
+      end
+    end
+  end
+
+end

data/spec/lib/composable_state_machine/model_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe ComposableStateMachine::Model do
+
+  let(:transition_map) do
+    {
+        heat: {
+            cold: :warm,
+            warm: :hot,
+            hot: :hot,
+        },
+        cool: {
+            cold: :cold,
+            warm: :cold,
+            hot: :warm
+        }
+    }
+  end
+  let(:transitions) { ComposableStateMachine::Transitions.new(transition_map) }
+  let(:behaviors) { double(call: nil) }
+
+  subject do
+    described_class.new(initial_state: :cold,
+                        transitions: transitions, behaviors: behaviors)
+  end
+
+  describe '#initial_state' do
+    it 'stores the initial state of the model' do
+      subject.initial_state.should eq :cold
+    end
+  end
+
+  describe '#transition' do
+
+    it 'forwards to transitions' do
+      transitions.should_receive(:transition).with(:cold, :heat)
+
+      subject.transition(:cold, :heat)
+    end
+
+    it 'executes :enter behaviors with the new state and the event to behaviors' do
+      behaviors.should_receive(:call).with(
+          ComposableStateMachine::DefaultCallbackRunner,
+          :enter, :warm, :cold, :heat, :warm)
+
+      subject.transition(:cold, :heat).should eq :warm
+    end
+
+    it 'yields the new state on state change' do
+      expect do |b|
+        subject.transition(:cold, :heat, &b)
+      end.to yield_with_args(:warm)
+    end
+
+    it 'does not execute :enter behaviors when the state does not transition' do
+      behaviors.should_not_receive(:call)
+
+      subject.transition(:cold, :cool).should eq :cold
+    end
+
+    it 'does not yield if there is no state change' do
+      expect do |b|
+        subject.transition(:cold, :cool, &b)
+      end.not_to yield_control
+    end
+
+    it 'can send optional event arguments and callback runner' do
+      runner = double
+
+      behaviors.should_receive(:call).with(runner, :enter, :warm, :cold, :heat, :warm, 1, 2, 3)
+
+      subject.transition(:cold, :heat, [1, 2, 3], runner).should eq :warm
+    end
+  end
+
+end

data/spec/lib/composable_state_machine/transitions_spec.rb

@@ -0,0 +1,77 @@
+require 'spec_helper'
+
+describe ComposableStateMachine::Transitions do
+
+  let(:transition_map) do
+    {
+        add: {
+            nil => :created
+        },
+        update: {
+            created: :updated,
+            updated: :updated,
+        },
+        remove: {
+            created: :removed,
+            updated: :removed,
+        }
+    }
+  end
+
+  subject { described_class.new(transition_map) }
+
+  describe '#events' do
+    it 'returns all events' do
+      subject.events == [:add, :update, :remove]
+    end
+  end
+
+  describe '#states' do
+    it 'returns all states' do
+      subject.states =~ [nil, :created, :updated, :removed]
+    end
+  end
+
+  describe '#on' do
+    it 'adds to the transition map' do
+      subject.
+          on(:remove, nil => :error).
+          on(:restore, :removed => :updated)
+
+      subject.events.should eq [:add, :update, :remove, :restore]
+      subject.states =~ [nil, :created, :updated, :removed, :error]
+
+      subject.transition(nil, :add).should eq :created
+      subject.transition(nil, :remove).should eq :error
+      subject.transition(:removed, :restore).should eq :updated
+    end
+
+    it 'raises InvalidTransition on transitions to nil' do
+      expect do
+        subject.on(:expunge, created: nil)
+      end.to raise_error ComposableStateMachine::InvalidTransition
+    end
+  end
+
+  describe '#transition' do
+    it 'raises InvalidEvent for unknown events' do
+      expect do
+        subject.transition(:updated, :unknown)
+      end.to raise_error ComposableStateMachine::InvalidEvent
+    end
+
+    it 'returns the state to transition to when possible' do
+      subject.transition(nil, :add).should eq :created
+      subject.transition(:created, :update).should eq :updated
+      subject.transition(:updated, :update).should eq :updated
+      subject.transition(:created, :remove).should eq :removed
+      subject.transition(:updated, :remove).should eq :removed
+    end
+
+    it 'returns nil if no transition is possible' do
+      subject.transition(nil, :remove).should be_nil
+      subject.transition(:created, :add).should be_nil
+    end
+  end
+
+end

data/spec/lib/composable_state_machine_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe ComposableStateMachine do
+
+  let(:options) do
+    {
+        initial_state: :foo,
+        transitions: ComposableStateMachine::Transitions.new({}),
+        behaviors: ComposableStateMachine::Behaviors.new({}),
+        callback_runner: proc {}
+    }
+  end
+
+  describe '.model' do
+    it 'creates a model' do
+      ComposableStateMachine::Model.should_receive(:new).with(options).and_call_original
+
+      result = described_class.model(options)
+      result.should be_kind_of(ComposableStateMachine::Model)
+    end
+
+    it 'creates a Transitions object if necessary' do
+      options[:transitions] = {}
+
+      ComposableStateMachine::Model.should_receive(:new) do |options|
+        options[:transitions].should be_kind_of(ComposableStateMachine::Transitions)
+      end
+
+      described_class.model(options)
+    end
+
+    it 'creates a Behaviors object if necessary' do
+      options[:behaviors] = {}
+
+      ComposableStateMachine::Model.should_receive(:new) do |options|
+        options[:behaviors].should be_kind_of(ComposableStateMachine::Behaviors)
+      end
+
+      described_class.model(options)
+    end
+  end
+
+  describe '.machine' do
+    it 'creates a machine from a model' do
+      model = described_class.model(options)
+
+      ComposableStateMachine::Machine.should_receive(:new).with(model, initial_state: :bar).and_call_original
+
+      result = described_class.machine(model, initial_state: :bar)
+      result.should be_kind_of(ComposableStateMachine::Machine)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require 'simplecov'
+SimpleCov.start
+SimpleCov.minimum_coverage 100
+
+if ENV['TRAVIS']
+  require 'coveralls'
+  Coveralls.wear!
+end
+
+require 'pp'
+
+require 'composable_state_machine'
+
+Dir['spec/support/**/*.rb'].each { |f| require File.expand_path(f) }

data/spec/support/delegation.rb

@@ -0,0 +1,196 @@
+class Module
+  # Provides a +delegate+ class method to easily expose contained objects'
+  # public methods as your own.
+  #
+  # The macro receives one or more method names (specified as symbols or
+  # strings) and the name of the target object via the <tt>:to</tt> option
+  # (also a symbol or string).
+  #
+  # Delegation is particularly useful with Active Record associations:
+  #
+  #   class Greeter < ActiveRecord::Base
+  #     def hello
+  #       'hello'
+  #     end
+  #
+  #     def goodbye
+  #       'goodbye'
+  #     end
+  #   end
+  #
+  #   class Foo < ActiveRecord::Base
+  #     belongs_to :greeter
+  #     delegate :hello, to: :greeter
+  #   end
+  #
+  #   Foo.new.hello   # => "hello"
+  #   Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for #<Foo:0x1af30c>
+  #
+  # Multiple delegates to the same target are allowed:
+  #
+  #   class Foo < ActiveRecord::Base
+  #     belongs_to :greeter
+  #     delegate :hello, :goodbye, to: :greeter
+  #   end
+  #
+  #   Foo.new.goodbye # => "goodbye"
+  #
+  # Methods can be delegated to instance variables, class variables, or constants
+  # by providing them as a symbols:
+  #
+  #   class Foo
+  #     CONSTANT_ARRAY = [0,1,2,3]
+  #     @@class_array  = [4,5,6,7]
+  #
+  #     def initialize
+  #       @instance_array = [8,9,10,11]
+  #     end
+  #     delegate :sum, to: :CONSTANT_ARRAY
+  #     delegate :min, to: :@@class_array
+  #     delegate :max, to: :@instance_array
+  #   end
+  #
+  #   Foo.new.sum # => 6
+  #   Foo.new.min # => 4
+  #   Foo.new.max # => 11
+  #
+  # It's also possible to delegate a method to the class by using +:class+:
+  #
+  #   class Foo
+  #     def self.hello
+  #       "world"
+  #     end
+  #
+  #     delegate :hello, to: :class
+  #   end
+  #
+  #   Foo.new.hello # => "world"
+  #
+  # Delegates can optionally be prefixed using the <tt>:prefix</tt> option. If the value
+  # is <tt>true</tt>, the delegate methods are prefixed with the name of the object being
+  # delegated to.
+  #
+  #   Person = Struct.new(:name, :address)
+  #
+  #   class Invoice < Struct.new(:client)
+  #     delegate :name, :address, to: :client, prefix: true
+  #   end
+  #
+  #   john_doe = Person.new('John Doe', 'Vimmersvej 13')
+  #   invoice = Invoice.new(john_doe)
+  #   invoice.client_name    # => "John Doe"
+  #   invoice.client_address # => "Vimmersvej 13"
+  #
+  # It is also possible to supply a custom prefix.
+  #
+  #   class Invoice < Struct.new(:client)
+  #     delegate :name, :address, to: :client, prefix: :customer
+  #   end
+  #
+  #   invoice = Invoice.new(john_doe)
+  #   invoice.customer_name    # => 'John Doe'
+  #   invoice.customer_address # => 'Vimmersvej 13'
+  #
+  # If the target is +nil+ and does not respond to the delegated method a
+  # +NoMethodError+ is raised, as with any other value. Sometimes, however, it
+  # makes sense to be robust to that situation and that is the purpose of the
+  # <tt>:allow_nil</tt> option: If the target is not +nil+, or it is and
+  # responds to the method, everything works as usual. But if it is +nil+ and
+  # does not respond to the delegated method, +nil+ is returned.
+  #
+  #   class User < ActiveRecord::Base
+  #     has_one :profile
+  #     delegate :age, to: :profile
+  #   end
+  #
+  #   User.new.age # raises NoMethodError: undefined method `age'
+  #
+  # But if not having a profile yet is fine and should not be an error
+  # condition:
+  #
+  #   class User < ActiveRecord::Base
+  #     has_one :profile
+  #     delegate :age, to: :profile, allow_nil: true
+  #   end
+  #
+  #   User.new.age # nil
+  #
+  # Note that if the target is not +nil+ then the call is attempted regardless of the
+  # <tt>:allow_nil</tt> option, and thus an exception is still raised if said object
+  # does not respond to the method:
+  #
+  #   class Foo
+  #     def initialize(bar)
+  #       @bar = bar
+  #     end
+  #
+  #     delegate :name, to: :@bar, allow_nil: true
+  #   end
+  #
+  #   Foo.new("Bar").name # raises NoMethodError: undefined method `name'
+  #
+  def delegate(*methods)
+    options = methods.pop
+    unless options.is_a?(Hash) && to = options[:to]
+      raise ArgumentError, 'Delegation needs a target. Supply an options hash with a :to key as the last argument (e.g. delegate :hello, to: :greeter).'
+    end
+
+    prefix, allow_nil = options.values_at(:prefix, :allow_nil)
+
+    if prefix == true && to =~ /^[^a-z_]/
+      raise ArgumentError, 'Can only automatically set the delegation prefix when delegating to a method.'
+    end
+
+    method_prefix = \
+      if prefix
+        "#{prefix == true ? to : prefix}_"
+      else
+        ''
+      end
+
+    file, line = caller.first.split(':', 2)
+    line = line.to_i
+
+    to = to.to_s
+    to = 'self.class' if to == 'class'
+
+    methods.each do |method|
+      # Attribute writer methods only accept one argument. Makes sure []=
+      # methods still accept two arguments.
+      definition = (method =~ /[^\]]=$/) ? 'arg' : '*args, &block'
+
+      # The following generated methods call the target exactly once, storing
+      # the returned value in a dummy variable.
+      #
+      # Reason is twofold: On one hand doing less calls is in general better.
+      # On the other hand it could be that the target has side-effects,
+      # whereas conceptualy, from the user point of view, the delegator should
+      # be doing one call.
+      if allow_nil
+        module_eval(<<-EOS, file, line - 3)
+          def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
+            _ = #{to}                                         #   _ = client
+            if !_.nil? || nil.respond_to?(:#{method})         #   if !_.nil? || nil.respond_to?(:name)
+              _.#{method}(#{definition})                      #     _.name(*args, &block)
+            end                                               #   end
+          end                                                 # end
+        EOS
+      else
+        exception = %(raise "#{self}##{method_prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
+
+        module_eval(<<-EOS, file, line - 2)
+          def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
+            _ = #{to}                                         #   _ = client
+            _.#{method}(#{definition})                        #   _.name(*args, &block)
+          rescue NoMethodError                                # rescue NoMethodError
+            if _.nil?                                         #   if _.nil?
+              #{exception}                                    #     # add helpful message to the exception
+            else                                              #   else
+              raise                                           #     raise
+            end                                               #   end
+          end                                                 # end
+        EOS
+      end
+    end
+  end
+end