finite_machine 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 714f488440a58102f64c2c9911b1d55f3f759df5
-  data.tar.gz: 10005291036b23eee4654d2a81eeab01383126da
+  metadata.gz: e05d3ce7a5a9f3f1c5ad37e5a21e57e1f2df7998
+  data.tar.gz: 7965548668781de5c89c0f2ff45161b8bbea5cb1
 SHA512:
-  metadata.gz: a16908a3c0d0c6fceeb196aac75249f5470593020c29658c4b688bbe7af8aa8a2342b8f42cae065ba19167698204061353b27bc12100508ba4bccfe66dcd58bd
-  data.tar.gz: 6aec10fde3d2e76645458a7b60a6aca87784f8193376944b2c0be40c05c4a7ad5facfe75d98c1b155fb9937da504c0a7903a5558caf3e1fd1edd909cfe0341c0
+  metadata.gz: a49b292b01016ca642ce72b288652037445c2b2f203b546848c4ddc61f5492d4d11abba61fc9421e5f003e33b18521c3ba0254d0c219232968d8e12e4fafa672
+  data.tar.gz: 858af0fa26cf18fd6f2be8f4e4035cdbfc07d3b4e4af6435d49f50cff49af6dd50515797d2a3522c7ffc6d4d98b5572bba045f56cf2286ad0927fe450b0e1351

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+0.6.0 (May 10, 2014)
+
+* Add StateParser to allow for grouping transition under same event name
+* Change Transition to store a map of transition for a given event
+* Add abilility to correctly extract :to state for Transition instance
+* Fix bug #6 with incorrect TransitionEvent payload information
+
 0.5.0 (April 28, 2014)
 
 * Change to allow for machine to be constructed as plain object

data/README.md

@@ -55,6 +55,7 @@ Or install it yourself as:
     * [2.2 Forcing transitions](#22-forcing-transitions)
     * [2.3 Asynchronous transitions](#23-asynchronous-transitions)
     * [2.4 Single event with multiple from states](#24-single-event-with-multiple-from-states)
+    * [2.5 Grouping states under single event](#25-grouping-states-under-single-event)
 * [3. Conditional transitions](#3-conditional-transitions)
     * [3.1 Using a Proc](#31-using-a-proc)
     * [3.2 Using a Symbol](#32-using-a-symbol)
@@ -381,7 +382,7 @@ fm.async.ready  # => executes in separate Thread
 ### 2.4 Single event with multiple from states
 
 If an event transitions from multiple states to the same state then all the states can be grouped into an array.
-Altenatively, you can create separte events under the same name for each transition that needs combining.
+Alternatively, you can create separate events under the same name for each transition that needs combining.
 
 ```ruby
 fm = FiniteMachine.define do
@@ -397,6 +398,21 @@ fm = FiniteMachine.define do
 end
 ```
 
+### 2.5 Grouping states under single event
+
+Another way to specify state transitions under single event name is to group all your state transitions into a single hash like so:
+
+```ruby
+fm = FiniteMachine.define do
+  initial :initial
+
+  events {
+    event :bump, :initial => :low,
+                 :low     => :medium,
+                 :medium  => :high
+  }
+```
+
 ## 3 Conditional transitions
 
 Each event takes an optional `:if` and `:unless` options which act as a predicate for the transition. The `:if` and `:unless` can take a symbol, a string, a Proc or an array. Use `:if` option when you want to specify when the transition **should** happen. If you want to specify when the transition **should not** happen then use `:unless` option.

data/lib/finite_machine.rb

@@ -20,6 +20,7 @@ require "finite_machine/transition_event"
 require "finite_machine/dsl"
 require "finite_machine/state_machine"
 require "finite_machine/subscribers"
+require "finite_machine/state_parser"
 require "finite_machine/observer"
 require "finite_machine/listener"
 

data/lib/finite_machine/state_machine.rb

@@ -219,15 +219,14 @@ module FiniteMachine
       return CANCELLED unless _transition.conditions.all? do |condition|
                                 condition.call(env.target, *args)
                               end
-      return NOTRANSITION if state == _transition.to
+      return NOTRANSITION if _transition.different?(state)
 
       sync_exclusive do
         notify :exitstate, _transition, *args
-        notify :enteraction, _transition, *args
 
         begin
           _transition.call
-
+          notify :enteraction, _transition, *args
           notify :transitionstate, _transition, *args
           notify :transitionaction, _transition, *args
         rescue Exception => e

data/lib/finite_machine/state_parser.rb

@@ -0,0 +1,129 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for converting transition arguments to states
+  class StateParser
+    include Threadable
+
+    attr_threadsafe :attrs
+
+    # Initialize a StateParser
+    #
+    # @example
+    #   StateParpser.new({from: [:green, :blue], to: :red})
+    #
+    # @param [Hash] attrs
+    #
+    # @api public
+    def initialize(attrs)
+      @attrs = ensure_only_states!(attrs)
+    end
+
+    # Extract states from attributes
+    #
+    # @example
+    #   StateParpser.new(attr).parase_states
+    #
+    # @return [Hash[Symbol]] states
+    #
+    # @api public
+    def parse_states
+      if contains_from_to_keys?
+        convert_from_to_attributes_to_states_hash
+      else
+        convert_attributes_to_states_hash
+      end
+    end
+
+    # Check if attributes contain :from or :to key
+    #
+    # @example
+    #   parser = StateParser.new({from: :green, to: :red})
+    #   parser.contains_from_to_keys?   # => true
+    #
+    # @example
+    #   parser = StateParser.new({:green => :red})
+    #   parser.contains_from_to_keys?   # => false
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def contains_from_to_keys?
+      [:from, :to].any? { |key| attrs.keys.include?(key) }
+    end
+
+    # Return parser attributes
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_s
+      attrs.to_s
+    end
+
+    # Return string representation
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      attributes = @attrs.map { |k, v| "#{k}:#{v}" }.join(', ')
+      "<##{self.class} @attrs=#{attributes}>"
+    end
+
+    private
+
+    # Extract only states from attributes
+    #
+    # @return [Hash[Symbol]]
+    #
+    # @api private
+    def ensure_only_states!(attrs)
+      _attrs = attrs.dup
+      [:name, :if, :unless].each { |key| _attrs.delete(key) }
+      raise_not_enough_transitions unless _attrs.any?
+      _attrs
+    end
+
+    # Convert attrbiutes with :from, :to keys to states hash
+    #
+    # @return [Hash[Symbol]]
+    #
+    # @api private
+    def convert_from_to_attributes_to_states_hash
+      Array(attrs[:from] || ANY_STATE).reduce({}) do |hash, state|
+        hash[state] = attrs[:to] || state
+        hash
+      end
+    end
+
+    # Convert collapsed attributes to states hash
+    #
+    # @return [Hash[Symbol]]
+    #
+    # @api private
+    def convert_attributes_to_states_hash
+      attrs.reduce({}) do |hash, (k, v)|
+        if k.respond_to?(:to_ary)
+          k.each { |el| hash[el] = v }
+        else
+          hash[k] = v
+        end
+        hash
+      end
+    end
+
+    # Raise error when not enough transitions are provided
+    #
+    # @raise [NotEnoughTransitionsError]
+    #   if the event has not enough transition arguments
+    #
+    # @return [nil]
+    #
+    # @api private
+    def raise_not_enough_transitions
+      fail NotEnoughTransitionsError, "please provide state transitions for" \
+           " '#{attrs.inspect}'"
+    end
+  end # StateParser
+end # FiniteMachine

data/lib/finite_machine/transition.rb

@@ -8,10 +8,10 @@ module FiniteMachine
     attr_threadsafe :name
 
     # State transitioning from
-    attr_threadsafe :from
+    attr_threadsafe :from_states
 
     # State transitioning to
-    attr_threadsafe :to
+    attr_threadsafe :to_states
 
     # Predicates before transitioning
     attr_threadsafe :conditions
@@ -25,6 +25,9 @@ module FiniteMachine
     # Check if transition should be cancelled
     attr_threadsafe :cancelled
 
+    # All states for this transition event
+    attr_threadsafe :map
+
     # Initialize a Transition
     #
     # @param [StateMachine] machine
@@ -32,14 +35,25 @@ module FiniteMachine
     #
     # @api public
     def initialize(machine, attrs = {})
-      @machine    = machine
-      @name       = attrs.fetch(:name, DEFAULT_STATE)
-      @from, @to  = *parse_states(attrs)
-      @from_state = @from.first
-      @if         = Array(attrs.fetch(:if, []))
-      @unless     = Array(attrs.fetch(:unless, []))
-      @conditions = make_conditions
-      @cancelled  = false
+      @machine     = machine
+      @name        = attrs.fetch(:name, DEFAULT_STATE)
+      @map         = FiniteMachine::StateParser.new(attrs).parse_states
+      @from_states = @map.keys
+      @to_states   = @map.values
+      @from_state  = @from_states.first
+      @if          = Array(attrs.fetch(:if, []))
+      @unless      = Array(attrs.fetch(:unless, []))
+      @conditions  = make_conditions
+      @cancelled   = false
+    end
+
+    # Decide :to state from available transitions for this event
+    #
+    # @return [Symbol]
+    #
+    # @api public
+    def to_state
+      machine.transitions[name][from_state]
     end
 
     # Reduce conditions
@@ -50,21 +64,16 @@ module FiniteMachine
         @unless.map { |c| Callable.new(c).invert }
     end
 
-    # Extract states from attributes
+    # Check if moved to different state
     #
-    # @param [Hash] attrs
+    # @param [Symbol] state
+    #   the current state name
     #
-    # @api private
-    def parse_states(attrs)
-      _attrs = attrs.dup
-      [:name, :if, :unless].each { |key| _attrs.delete(key) }
-      raise_not_enough_transitions(attrs) unless _attrs.any?
-
-      if [:from, :to].any? { |key| attrs.keys.include?(key) }
-        [Array(_attrs[:from] || ANY_STATE), _attrs[:to]]
-      else
-        [(keys = _attrs.keys).flatten, _attrs[keys.first]]
-      end
+    # @return [Boolean]
+    #
+    # @api public
+    def different?(state)
+      map[state] == state || map[ANY_STATE] == state
     end
 
     # Add transition to the machine
@@ -73,8 +82,8 @@ module FiniteMachine
     #
     # @api private
     def define
-      from.each do |from|
-        machine.transitions[name][from] = to || from
+      from_states.each do |from|
+        machine.transitions[name][from] = map[from] || ANY_STATE
       end
     end
 
@@ -82,7 +91,7 @@ module FiniteMachine
     #
     # @api private
     def define_state_methods
-      from.concat([to]).each { |state| define_state_method(state) }
+      from_states.concat(to_states).each { |state| define_state_method(state) }
     end
 
     # Define state helper method
@@ -160,24 +169,8 @@ module FiniteMachine
     #
     # @api public
     def inspect
-      "<#{self.class} name: #{@name}, transitions: #{@from} => #{@to}, when: #{@conditions}>"
-    end
-
-    private
-
-    # Raise error when not enough transitions are provided
-    #
-    # @param [Hash] attrs
-    #
-    # @raise [NotEnoughTransitionsError]
-    #   if the event has not enough transition arguments
-    #
-    # @return [nil]
-    #
-    # @api private
-    def raise_not_enough_transitions(attrs)
-      fail NotEnoughTransitionsError, "please provide state transitions for" \
-           " '#{attrs.inspect}'"
+      transitions = @map.map { |from, to| "#{from} -> #{to}" }.join(', ')
+      "<##{self.class} @name=#{@name}, @transitions=#{transitions}, @when=#{@conditions}>"
     end
   end # Transition
 end # FiniteMachine

data/lib/finite_machine/transition_event.rb

@@ -12,14 +12,16 @@ module FiniteMachine
 
     # Build a transition event
     #
+    # @param [FiniteMachine::Transition] transition
+    #
     # @return [self]
     #
     # @api private
     def self.build(transition)
       instance = new
-      instance.from = transition.from_state
-      instance.to   = transition.to
       instance.name = transition.name
+      instance.from = transition.from_state
+      instance.to   = transition.to_state
       instance
     end
   end # TransitionEvent

data/lib/finite_machine/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module FiniteMachine
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/spec/unit/callbacks_spec.rb

@@ -608,7 +608,7 @@ describe FiniteMachine, 'callbacks' do
       }
 
       callbacks {
-        on_enter :slow do |event|
+        on_exit :green do |event|
           FiniteMachine::CANCELLED
         end
       }
@@ -620,4 +620,92 @@ describe FiniteMachine, 'callbacks' do
   end
 
   xit "groups callbacks"
+
+  it "groups states from separate events with the same name" do
+    callbacks = []
+    fsm = FiniteMachine.define do
+      initial :initial
+
+      events {
+        event :bump, :initial => :low
+        event :bump, :low     => :medium
+        event :bump, :medium  => :high
+      }
+
+      callbacks {
+        on_enter_state do |event|
+          callbacks << "enter_state_#{event.name}_#{event.from}_#{event.to}"
+        end
+        on_enter_event do |event|
+          callbacks << "enter_event_#{event.name}_#{event.from}_#{event.to}"
+        end
+      }
+    end
+    expect(fsm.current).to eq(:initial)
+    fsm.bump
+    expect(callbacks).to eq([
+      'enter_event_bump_initial_low',
+      'enter_state_bump_initial_low'
+    ])
+    fsm.bump
+    expect(callbacks).to eq([
+      'enter_event_bump_initial_low',
+      'enter_state_bump_initial_low',
+      'enter_event_bump_low_medium',
+      'enter_state_bump_low_medium'
+    ])
+    fsm.bump
+    expect(callbacks).to eq([
+      'enter_event_bump_initial_low',
+      'enter_state_bump_initial_low',
+      'enter_event_bump_low_medium',
+      'enter_state_bump_low_medium',
+      'enter_event_bump_medium_high',
+      'enter_state_bump_medium_high'
+    ])
+  end
+
+  it "groups states under event name" do
+    callbacks = []
+    fsm = FiniteMachine.define do
+      initial :initial
+
+      events {
+        event :bump, :initial => :low,
+                     :low     => :medium,
+                     :medium  => :high
+      }
+
+      callbacks {
+        on_enter_state do |event|
+          callbacks << "enter_state_#{event.name}_#{event.from}_#{event.to}"
+        end
+        on_enter_event do |event|
+          callbacks << "enter_event_#{event.name}_#{event.from}_#{event.to}"
+        end
+      }
+    end
+    expect(fsm.current).to eq(:initial)
+    fsm.bump
+    expect(callbacks).to eq([
+      'enter_event_bump_initial_low',
+      'enter_state_bump_initial_low'
+    ])
+    fsm.bump
+    expect(callbacks).to eq([
+      'enter_event_bump_initial_low',
+      'enter_state_bump_initial_low',
+      'enter_event_bump_low_medium',
+      'enter_state_bump_low_medium'
+    ])
+    fsm.bump
+    expect(callbacks).to eq([
+      'enter_event_bump_initial_low',
+      'enter_state_bump_initial_low',
+      'enter_event_bump_low_medium',
+      'enter_state_bump_low_medium',
+      'enter_event_bump_medium_high',
+      'enter_state_bump_medium_high'
+    ])
+  end
 end

data/spec/unit/events_spec.rb

@@ -247,9 +247,7 @@ describe FiniteMachine, 'events' do
     end
 
     expect(fsm.current).to eql(:green)
-
     expect(fsm.can?(:stop)).to be_true
-
     fsm.stop
     expect(fsm.current).to eql(:yellow)
     fsm.stop
@@ -262,6 +260,26 @@ describe FiniteMachine, 'events' do
     expect(fsm.current).to eql(:yellow)
   end
 
+  it "groups transitions under one event name" do
+    fsm = FiniteMachine.define do
+      initial :initial
+
+      events {
+        event :bump, :initial => :low,
+                     :low     => :medium,
+                     :medium  => :high
+      }
+    end
+
+    expect(fsm.current).to eq(:initial)
+    fsm.bump
+    expect(fsm.current).to eq(:low)
+    fsm.bump
+    expect(fsm.current).to eq(:medium)
+    fsm.bump
+    expect(fsm.current).to eq(:high)
+  end
+
   it "returns values for events" do
     fsm = FiniteMachine.define do
       initial :neutral

data/spec/unit/inspect_spec.rb

@@ -8,10 +8,10 @@ describe FiniteMachine::Transition, 'inspect' do
   subject(:transition) { described_class.new(machine, attrs) }
 
   context 'when inspecting' do
-    let(:attrs) { {name: :start, :foo => :bar } }
+    let(:attrs) { {name: :start, :foo => :bar, :baz => :daz} }
 
     it "displays name and transitions" do
-      expect(transition.inspect).to eql("<FiniteMachine::Transition name: start, transitions: [:foo] => bar, when: []>")
+      expect(transition.inspect).to eql("<#FiniteMachine::Transition @name=start, @transitions=foo -> bar, baz -> daz, @when=[]>")
     end
   end
 

data/spec/unit/state_parser/inspect_spec.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::StateParser, "#inspect" do
+  let(:object) { described_class }
+
+  subject(:parser) { object.new(attrs) }
+
+  describe '#inspect' do
+    let(:attrs) { { green: :yellow } }
+
+    it "inspects parser" do
+      expect(parser.inspect).to eq("<#FiniteMachine::StateParser @attrs=green:yellow>")
+    end
+  end
+
+  describe '#to_s' do
+    let(:attrs) { { green: :yellow } }
+
+    it "prints parser attributes" do
+      expect(parser.to_s).to eq(attrs.to_s)
+    end
+  end
+end

data/spec/unit/state_parser/parse_states_spec.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::StateParser, '#inspect' do
+  let(:object) { described_class }
+
+  subject(:parser) { object.new(attrs) }
+
+  context 'when no attributes' do
+    let(:attrs) { { } }
+
+    it "raises error for no transitions" do
+      expect {
+        parser.parse_states
+      }.to raise_error(FiniteMachine::NotEnoughTransitionsError)
+    end
+  end
+
+  context 'when :from and :to keys' do
+    let(:attrs) { { from: :green, to: :yellow }}
+
+    it "removes :from and :to keys" do
+      expect(parser.parse_states).to eq({green: :yellow})
+    end
+  end
+
+  context 'when only :from key' do
+    let(:attrs) { { from: :green }}
+
+    it "adds to state as copy of from" do
+      expect(parser.parse_states).to eq({green: :green})
+    end
+  end
+
+  context 'when only :to key' do
+    let(:attrs) { { to: :green }}
+
+    it "inserts :any from state" do
+      expect(parser.parse_states).to eq({any: :green})
+    end
+  end
+
+  context 'when attribuets as hash' do
+    let(:attrs) { { green: :yellow } }
+
+    it "copies attributes over" do
+      expect(parser.parse_states).to eq({green: :yellow})
+    end
+  end
+
+  context 'when array of from states' do
+    let(:attrs) { { [:green] => :yellow } }
+
+    it "extracts states" do
+      expect(parser.parse_states).to eq({green: :yellow})
+    end
+  end
+end

data/spec/unit/transition/parse_states_spec.rb

@@ -16,12 +16,22 @@ describe FiniteMachine::Transition, 'parse_states' do
     end
   end
 
+  context 'with :to key only' do
+    let(:attrs) { { to: :red } }
+
+    it "groups states" do
+      expect(transition.from_states).to eq([:any])
+      expect(transition.to_states).to eq([:red])
+      expect(transition.map).to eql({any: :red})
+    end
+  end
+
   context 'with :from, :to keys' do
     let(:attrs) { {from: [:green, :yellow], to: :red} }
 
     it "groups states" do
-      expect(transition.from).to eql(attrs[:from])
-      expect(transition.to).to eql(attrs[:to])
+      expect(transition.from_states).to match_array(attrs[:from])
+      expect(transition.to_states).to match_array([:red, :red])
     end
   end
 
@@ -29,17 +39,21 @@ describe FiniteMachine::Transition, 'parse_states' do
     let(:attrs) { {[:green, :yellow] => :red} }
 
     it "groups states" do
-      expect(transition.from).to eql([:green, :yellow])
-      expect(transition.to).to eql(:red)
+      expect(transition.from_states).to match_array([:green, :yellow])
+      expect(transition.to_states).to eql([:red, :red])
     end
   end
 
   context 'when hash of states' do
-    let(:attrs) { { :green => :red, :yellow => :red} }
+    let(:attrs) {
+      { :initial => :low,
+        :low     => :medium,
+        :medium  => :high }
+     }
 
     it "groups states" do
-      expect(transition.from).to eql([:green, :yellow])
-      expect(transition.to).to eql(:red)
+      expect(transition.from_states).to match_array([:initial, :low, :medium])
+      expect(transition.to_states).to eql([:low, :medium, :high])
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finite_machine
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-28 00:00:00.000000000 Z
+date: 2014-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -59,6 +59,7 @@ files:
 - lib/finite_machine/logger.rb
 - lib/finite_machine/observer.rb
 - lib/finite_machine/state_machine.rb
+- lib/finite_machine/state_parser.rb
 - lib/finite_machine/subscribers.rb
 - lib/finite_machine/thread_context.rb
 - lib/finite_machine/threadable.rb
@@ -80,6 +81,8 @@ files:
 - spec/unit/inspect_spec.rb
 - spec/unit/is_spec.rb
 - spec/unit/logger_spec.rb
+- spec/unit/state_parser/inspect_spec.rb
+- spec/unit/state_parser/parse_states_spec.rb
 - spec/unit/states_spec.rb
 - spec/unit/subscribers_spec.rb
 - spec/unit/target_spec.rb
@@ -127,6 +130,8 @@ test_files:
 - spec/unit/inspect_spec.rb
 - spec/unit/is_spec.rb
 - spec/unit/logger_spec.rb
+- spec/unit/state_parser/inspect_spec.rb
+- spec/unit/state_parser/parse_states_spec.rb
 - spec/unit/states_spec.rb
 - spec/unit/subscribers_spec.rb
 - spec/unit/target_spec.rb