end_state 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fd8b390f8750c3af0948f56fa4e7471f5d4dfce8
-  data.tar.gz: ed30307b64e15e69829f25f61dcd883f3ce42fc2
+  metadata.gz: b964eec779e3cb4ab2214bfaf0da1b048f4e9b43
+  data.tar.gz: c48a186f6bf7229369818e1faf01a46d287dcee3
 SHA512:
-  metadata.gz: d00715edd410e6dcffba526a15a5a5ad9475ce70665363423751a08b0a70912024b8c433126c8e11231b045d7278ee00821f3afb8845f1e3b578aaf56f01cad2
-  data.tar.gz: f4139a6f1fca2ca85e3883885d48106f293d0e7605060863cfd4ca6b7b350f24bfc8d10f6b65786329ebd6338c669e11bd9de2f34bc0f22c359c2eb08f7d3591
+  metadata.gz: aca9ba0ae25ef8eb95c988a157ebe487681225feef8785605c2b7414b01725f5b2b733b3fee830b26d65135ccf75e67bb47db6da411b679984ec46dc815f9bc7
+  data.tar.gz: 8b92ab95a97116056c9aa2331410ebf0ba1a29e641e73345ce5cc9c33ba83cd5e110b4752a5eaab3cf244a7137a39288f01aaf1df670f76dd837fa9eae92ac7a

data/README.md

@@ -26,12 +26,15 @@ Or install it yourself as:
 ## StateMachine
 
 Create a state machine by subclassing `EndState::StateMachine`.
+Transitions can be named by adding an `:as` option.
 
 ```ruby
 class Machine < EndState::StateMachine
-  transition a: :b, as: :go
-  transition b: :c
-  transition [:b, :c] => :a
+  transition parked: :idling, as: :start
+  transition idling: :first_gear, first_gear: :second_gear, second_gear: :third_gear, as: :shift_up
+  transition third_gear: :second_gear, second_gear: :first_gear, as: shift_down
+  transition first_gear: :idling, as: idle
+  transition [:idling, :first_gear] => :parked, as: :park
 end
 ```
 
@@ -46,22 +49,24 @@ class StatefulObject
   end
 end
 
-machine = Machine.new(StatefulObject.new(:a))
-
-machine.transition :b       # => true
-machine.state               # => :b
-machine.b?                  # => true
-machine.transition :c       # => true
-machine.state               # => :c
-machine.can_transition? :b  # => false
-machine.can_transition? :a  # => true
-machine.transition :b       # => false
-machine.transition! :b      # => raises InvalidTransition
-machine.transition :a       # => true
-machine.state               # => :a
-machine.go                  # => true
-machine.state               # => :b
-machine.go!                 # => raises InvalidTransition
+machine = Machine.new(StatefulObject.new(:parked))
+
+machine.transition :idling            # => true
+machine.state                         # => :idling
+machine.idling?                       # => true
+machine.transition :first_gear        # => true
+machine.transition :second_gear       # => true
+machine.transition :third_gear        # => true
+machine.state                         # => :third_gear
+machine.can_transition? :first_gear   # => false
+machine.can_transition? :second_gear  # => true
+machine.transition :first_gear        # => false
+machine.transition! :first_gear       # => raises InvalidTransition
+machine.shift_down                    # => true
+machine.shift_up                      # => true
+machine.state                         # => :third_gear
+machine.park                          # => false
+machine.park!                         # => raises InvalidTransition
 ```
 
 ## Initial State
@@ -82,19 +87,19 @@ the machine to transition to the new state specified from any actual state.
 
 ```ruby
 class Machine < EndState::StateMachine
-  transition a: :b
-  transition b: :c
-  transition any_state: :d
+  transition parked: :idling
+  transition idling: :first_gear
+  transition any_state: :crashed
 end
 
-machine = Machine.new(StatefulObject.new(:a))
-machine.transition :d      # true
-machine.state              # :d
+machine = Machine.new(StatefulObject.new(:parked))
+machine.transition :crashed  # true
+machine.state                # :crashed
 
-machine = Machine.new(StatefulObject.new(:a))
-machine.transition :b      # true
-machine.transition :d      # true
-machine.state              # :d
+machine = Machine.new(StatefulObject.new(:parked))
+machine.transition :idling   # true
+machine.transition :crashed  # true
+machine.state                # :crashed
 ```
 
 ## Guards

data/lib/end_state/errors.rb

@@ -4,4 +4,5 @@ module EndState
   class InvalidTransition < Error; end
   class GuardFailed < Error; end
   class ConcluderFailed < Error; end
+  class EventConflict < Error; end
 end

data/lib/end_state/state_machine.rb

@@ -35,17 +35,20 @@ module EndState
     end
 
     def self.transition(state_map)
-      initial_states = Array(state_map.keys.first)
-      final_state = state_map.values.first
-      transition_alias = state_map[:as] if state_map.keys.length > 1
-      transition = Transition.new(final_state)
-      initial_states.each do |state|
-        transitions[{ state.to_sym => final_state.to_sym }] = transition
-      end
-      unless transition_alias.nil?
-        events[transition_alias.to_sym] = initial_states.map { |s| { s.to_sym => final_state.to_sym } }
+      transition_alias = state_map.delete(:as)
+      transition_alias = transition_alias.to_sym unless transition_alias.nil?
+
+      state_map.each do |start_states, end_state|
+        transition = Transition.new(end_state)
+
+        Array(start_states).each do |start_state|
+          state_mapping = StateMapping[start_state.to_sym => end_state.to_sym]
+          transitions[state_mapping] = transition
+          __sm_add_event(transition_alias, state_mapping) unless transition_alias.nil?
+        end
+
+        yield transition if block_given?
       end
-      yield transition if block_given?
     end
 
     def self.transitions
@@ -66,11 +69,11 @@ module EndState
     end
 
     def self.start_states
-      transitions.keys.map { |state_map| state_map.keys.first }.uniq
+      transitions.keys.map(&:start_state).uniq
     end
 
     def self.end_states
-      transitions.keys.map { |state_map| state_map.values.first }.uniq
+      transitions.keys.map(&:end_state).uniq
     end
 
     def object
@@ -143,11 +146,12 @@ module EndState
     end
 
     def __sm_state_for_event(event, mode)
-      transitions = self.class.events[event]
-      return false unless transitions
-      start_states = transitions.map { |t| t.keys.first }
-      return __sm_invalid_event(event, mode) unless start_states.include?(state.to_sym) || start_states.include?(:any_state)
-      transitions.first.values.first
+      state_mappings = self.class.events[event]
+      return false unless state_mappings
+      state_mappings.each do |state_mapping|
+        return state_mapping.end_state if state_mapping.matches_start_state?(state.to_sym)
+      end
+      return __sm_invalid_event(event, mode)
     end
 
     def __sm_invalid_event(event, mode)
@@ -179,5 +183,20 @@ module EndState
       return false unless mode == :hard
       fail ConcluderFailed, "The transition to #{state} was rolled back: #{failure_messages.join(', ')}"
     end
+
+    def self.__sm_add_event(event, state_mapping)
+      events[event] ||= []
+      conflicting_mapping = events[event].find{ |sm| sm.conflicts?(state_mapping) }
+      if conflicting_mapping
+        message =
+          "Attempting to define :#{event} as transitioning from " \
+          ":#{state_mapping.start_state} => :#{state_mapping.end_state} when " \
+          ":#{conflicting_mapping.start_state} => :#{conflicting_mapping.end_state} already exists. " \
+          "You cannot define multiple transitions from a single state with the same event name."
+
+        fail EventConflict, message
+      end
+      events[event] << state_mapping
+    end
   end
 end

data/lib/end_state/state_mapping.rb

@@ -0,0 +1,25 @@
+module EndState
+  class StateMapping < Hash
+    def start_state
+      keys.first
+    end
+
+    def end_state
+      values.first
+    end
+
+    def any_start_state?
+      start_state == :any_state
+    end
+
+    def matches_start_state?(state)
+      start_state == state || any_start_state?
+    end
+
+    def conflicts?(state_mapping)
+      start_state == state_mapping.start_state ||
+      any_start_state? ||
+      state_mapping.any_start_state?
+    end
+  end
+end

data/lib/end_state/version.rb

@@ -1,3 +1,3 @@
 module EndState
-  VERSION = '0.11.0'
+  VERSION = '0.12.0'
 end

data/lib/end_state.rb

@@ -6,8 +6,10 @@ require 'end_state/guard'
 require 'end_state/concluder'
 require 'end_state/concluders'
 require 'end_state/transition'
+require 'end_state/state_mapping'
 require 'end_state/action'
 require 'end_state/state_machine'
+
 begin
   require 'graphviz'
   require 'end_state/graph'

data/spec/end_state/state_machine_spec.rb

@@ -14,26 +14,102 @@ module EndState
     end
 
     describe '.transition' do
-      let(:state_map) { { a: :b } }
-      let(:yielded) { OpenStruct.new(transition: nil) }
-      before { StateMachine.transition(state_map) { |transition| yielded.transition = transition } }
+      let(:options) { { a: :b } }
 
-      it 'yields a transition for the supplied end state' do
-        expect(yielded.transition.state).to eq :b
+      before do
+        @transitions = []
+        StateMachine.transition(options) { |transition| @transitions << transition }
       end
 
       it 'does not require a block' do
-        expect { StateMachine.transition(b: :c) }.not_to raise_error
+        expect { StateMachine.transition(options) }.not_to raise_error
+      end
+
+      context 'single transition' do
+        it 'yields a transition for the supplied end state' do
+          expect(@transitions.count).to eq 1
+          expect(@transitions[0].state).to eq :b
+        end
+
+        it 'adds the transition to the state machine' do
+          expect(StateMachine.transitions[a: :b]).to eq @transitions[0]
+        end
+
+        context 'with as' do
+          let(:options) { { a: :b, as: :go } }
+
+          it 'creates an alias' do
+            expect(StateMachine.events[:go]).to eq [{ a: :b }]
+          end
+
+          context 'another single transition with as' do
+            before { StateMachine.transition({c: :d, as: :go}) }
+
+            it 'appends to the event' do
+              expect(StateMachine.events[:go]).to eq [{ a: :b }, { c: :d }]
+            end
+          end
+
+          context 'another single transition with as that conflicts' do
+            it 'raises an error' do
+              expect{ StateMachine.transition({a: :c, as: :go}) }.to raise_error EventConflict,
+                'Attempting to define :go as transitioning from :a => :c when :a => :b already exists. ' \
+                'You cannot define multiple transitions from a single state with the same event name.'
+            end
+          end
+
+          context 'another single transition with as that conflicts' do
+            it 'raises an error' do
+              expect{ StateMachine.transition({any_state: :c, as: :go}) }.to raise_error EventConflict,
+                'Attempting to define :go as transitioning from :any_state => :c when :a => :b already exists. ' \
+                'You cannot define multiple transitions from a single state with the same event name.'
+            end
+          end
+        end
       end
 
-      it 'adds the transition to the state machine' do
-        expect(StateMachine.transitions[state_map]).to eq yielded.transition
+      context 'multiple start states' do
+        let(:options) { { [:a, :b] => :c } }
+
+        it 'yields each transition for the supplied end state' do
+          expect(@transitions.count).to eq 1
+          expect(@transitions[0].state).to eq :c
+        end
+
+        it 'adds the transitions to the state machine' do
+          expect(StateMachine.transitions[a: :c]).to eq @transitions[0]
+          expect(StateMachine.transitions[b: :c]).to eq @transitions[0]
+        end
+
+        context 'with as' do
+          let(:options) { { [:a, :b] => :c, as: :go } }
+
+          it 'creates an alias' do
+            expect(StateMachine.events[:go]).to eq [{ a: :c }, { b: :c }]
+          end
+        end
       end
 
-      context 'when the :as option is used' do
-        it 'creates an alias' do
-          StateMachine.transition(state_map.merge(as: :go))
-          expect(StateMachine.events[:go]).to eq [{ a: :b }]
+      context 'multiple transitions' do
+        let(:options) { { a: :b, c: :d } }
+
+        it 'yields each transition for the supplied end state' do
+          expect(@transitions.count).to eq 2
+          expect(@transitions[0].state).to eq :b
+          expect(@transitions[1].state).to eq :d
+        end
+
+        it 'adds the transitions to the state machine' do
+          expect(StateMachine.transitions[a: :b]).to eq @transitions[0]
+          expect(StateMachine.transitions[c: :d]).to eq @transitions[1]
+        end
+
+        context 'with as' do
+          let(:options) { { a: :b, c: :d, as: :go } }
+
+          it 'creates an alias' do
+            expect(StateMachine.events[:go]).to eq [{ a: :b }, { c: :d }]
+          end
         end
       end
     end
@@ -172,59 +248,123 @@ module EndState
 
     describe '#{event}' do
       let(:object) { OpenStruct.new(state: :a) }
-      before do
-        StateMachine.transition a: :b, as: :go do |t|
-          t.blocked 'Invalid event!'
+
+      context 'single transition' do
+        before do
+          StateMachine.transition a: :b, as: :go do |t|
+            t.blocked 'Invalid event!'
+          end
         end
-      end
 
-      it 'transitions the state' do
-        machine.go
-        expect(machine.state).to eq :b
-      end
+        it 'transitions the state' do
+          machine.go
+          expect(machine.state).to eq :b
+        end
 
-      it 'accepts params' do
-        allow(machine).to receive(:transition)
-        machine.go foo: 'bar', bar: 'foo'
-        expect(machine).to have_received(:transition).with(:b, { foo: 'bar', bar: 'foo' }, :soft)
-      end
+        it 'accepts params' do
+          allow(machine).to receive(:transition)
+          machine.go foo: 'bar', bar: 'foo'
+          expect(machine).to have_received(:transition).with(:b, { foo: 'bar', bar: 'foo' }, :soft)
+        end
 
-      it 'defaults params to {}' do
-        allow(machine).to receive(:transition)
-        machine.go
-        expect(machine).to have_received(:transition).with(:b, {}, :soft)
+        it 'defaults params to {}' do
+          allow(machine).to receive(:transition)
+          machine.go
+          expect(machine).to have_received(:transition).with(:b, {}, :soft)
+        end
+
+        context 'when the intial state is :c' do
+          let(:object) { OpenStruct.new(state: :c) }
+
+          it 'blocks invalid events' do
+            machine.go
+            expect(machine.state).to eq :c
+          end
+
+          it 'adds a failure message specified by blocked' do
+            machine.go
+            expect(machine.failure_messages).to eq ['Invalid event!']
+          end
+
+          context 'and all transitions are forced to run in :hard mode' do
+            before { machine.class.treat_all_transitions_as_hard! }
+
+            it 'raises an InvalidTransition error' do
+              expect { machine.go }.to raise_error(InvalidTransition)
+            end
+          end
+        end
+
+        context 'when using any_state with an event' do
+          before do
+            StateMachine.transition any_state: :end, as: :jump_to_end
+          end
+
+          it 'transitions the state to :end' do
+            machine.jump_to_end
+            expect(machine.state).to eq :end
+          end
+        end
       end
 
-      context 'when the intial state is :c' do
-        let(:object) { OpenStruct.new(state: :c) }
+      context 'multiple start states' do
+        before do
+          StateMachine.transition [:a, :b] => :c, as: :go do |t|
+            t.blocked 'Invalid event!'
+          end
+        end
 
-        it 'blocks invalid events' do
-          machine.go
-          expect(machine.state).to eq :c
+        context 'initial state is :a' do
+          let(:object) { OpenStruct.new(state: :a) }
+
+          it 'transitions the state' do
+            machine.go
+            expect(machine.state).to eq :c
+          end
         end
 
-        it 'adds a failure message specified by blocked' do
-          machine.go
-          expect(machine.failure_messages).to eq ['Invalid event!']
+        context 'initial state is :b' do
+          let(:object) { OpenStruct.new(state: :b) }
+
+          it 'transitions the state' do
+            machine.go
+            expect(machine.state).to eq :c
+          end
         end
 
-        context 'and all transitions are forced to run in :hard mode' do
-          before { machine.class.treat_all_transitions_as_hard! }
+        context 'initial state is :d' do
+          let(:object) { OpenStruct.new(state: :b) }
 
-          it 'raises an InvalidTransition error' do
-            expect { machine.go }.to raise_error(InvalidTransition)
+          it 'transitions the state' do
+            machine.go
+            expect(machine.state).to eq :c
           end
         end
       end
 
-      context 'when using any_state with an event' do
+      context 'multiple transitions' do
         before do
-          StateMachine.transition any_state: :end, as: :jump_to_end
+          StateMachine.transition a: :b, c: :d, as: :go do |t|
+            t.blocked 'Invalid event!'
+          end
         end
 
-        it 'transitions the state to :end' do
-          machine.jump_to_end
-          expect(machine.state).to eq :end
+        context 'initial state is :a' do
+          let(:object) { OpenStruct.new(state: :a) }
+
+          it 'transitions the state' do
+            machine.go
+            expect(machine.state).to eq :b
+          end
+        end
+
+        context 'initial state is :b' do
+          let(:object) { OpenStruct.new(state: :c) }
+
+          it 'transitions the state' do
+            machine.go
+            expect(machine.state).to eq :d
+          end
         end
       end
     end

data/spec/end_state/state_mapping_spec.rb

@@ -0,0 +1,94 @@
+require 'spec_helper'
+require 'ostruct'
+
+module EndState
+  describe StateMapping do
+    describe 'simple example' do
+      let(:subject) { StateMapping[a: :b] }
+
+      context '#start_state' do
+        it 'returns the first key' do
+          expect(subject.start_state).to eq :a
+        end
+      end
+
+      context '#end_state' do
+        it 'returns the first value' do
+          expect(subject.end_state).to eq :b
+        end
+      end
+
+      context '#any_start_state?' do
+        context 'start_state is :any_state' do
+          let(:subject) { StateMapping[any_state: :b] }
+          it 'returns true' do
+            expect(subject.any_start_state?).to eq true
+          end
+        end
+
+        context 'start_state is anything else' do
+          it 'returns false' do
+            expect(subject.any_start_state?).to eq false
+          end
+        end
+      end
+
+      context '#matches_start_state?' do
+        context 'same start_state' do
+          it 'returns true' do
+            expect(subject.matches_start_state?(:a)).to eq true
+          end
+        end
+
+        context 'different start_state' do
+          it 'returns false' do
+            expect(subject.matches_start_state?(:b)).to eq false
+          end
+        end
+
+        context 'object has a start_state of :any_state' do
+          let(:subject) { StateMapping[any_state: :c] }
+
+          it 'returns true' do
+            expect(subject.matches_start_state?(:b)).to eq true
+          end
+        end
+      end
+
+      context '#conflicts?' do
+        context 'same start_state' do
+          let(:other) { StateMapping[a: :c] }
+
+          it 'returns true' do
+            expect(subject.conflicts?(other)).to eq true
+          end
+        end
+
+        context 'different start_state' do
+          let(:other) { StateMapping[c: :d] }
+
+          it 'returns false' do
+            expect(subject.conflicts?(other)).to eq false
+          end
+        end
+
+        context 'argument has a start_state of :any_state' do
+          let(:other) { StateMapping[any_state: :c] }
+
+          it 'returns true' do
+            expect(subject.conflicts?(other)).to eq true
+          end
+        end
+
+        context 'object has a start_state of :any_state' do
+          let(:subject) { StateMapping[any_state: :c] }
+          let(:other) { StateMapping[a: :c] }
+
+          it 'returns true' do
+            expect(subject.conflicts?(other)).to eq true
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: end_state
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - alexpeachey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-21 00:00:00.000000000 Z
+date: 2014-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -95,6 +95,7 @@ files:
 - lib/end_state/guard.rb
 - lib/end_state/messages.rb
 - lib/end_state/state_machine.rb
+- lib/end_state/state_mapping.rb
 - lib/end_state/transition.rb
 - lib/end_state/version.rb
 - lib/end_state_matchers.rb
@@ -104,6 +105,7 @@ files:
 - spec/end_state/concluders/persistence_spec.rb
 - spec/end_state/guard_spec.rb
 - spec/end_state/state_machine_spec.rb
+- spec/end_state/state_mapping_spec.rb
 - spec/end_state/transition_spec.rb
 - spec/end_state_spec.rb
 - spec/spec_helper.rb
@@ -137,6 +139,7 @@ test_files:
 - spec/end_state/concluders/persistence_spec.rb
 - spec/end_state/guard_spec.rb
 - spec/end_state/state_machine_spec.rb
+- spec/end_state/state_mapping_spec.rb
 - spec/end_state/transition_spec.rb
 - spec/end_state_spec.rb
 - spec/spec_helper.rb