finite_machine 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 605485a3bc03f37c758232982a53c6a1454f3f75
-  data.tar.gz: ea94531b99ed2901d14a801388ab26e220f0b6df
+  metadata.gz: 5ce0812460235da2deebb8aafc2d542b33392804
+  data.tar.gz: 89bb6ab79f200d7efaf004ffe9704bbbeb86b5c0
 SHA512:
-  metadata.gz: ac08b6ac004a47a21c6ff3c104b470ebb50b083c3f692f6ce5d865ed2b6527cf0e58dce4983bfd08ed2d000ea5b80277895befada19e26e326506b6326d1bf1f
-  data.tar.gz: b00888c384d18a8f1654b11b26e53a6024c8da9127139ee4f6e3f906c1c0a03f7a5f85982f2af28f494b6097d4ddcdce86401f6bf532ead9a7bda2084418c01c
+  metadata.gz: ed665ca255296e317a683106444e9e4ebc8044f927ea9067c92709fe777787de8b26cfa969e5c42bb2089f16c184d69774729fb06cd6c26d93b645dd1d96b133
+  data.tar.gz: 88538af514156c8a5e899b876e747a0716ab4439c271395418364830cc3372bafcbc772383aaeb3cbecf75c07b0e4087961092eec824c42709d1e40656cfd75f

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+0.9.1 (August 10, 2014)
+
+* Add TransitionBuilder to internally build transitions from states
+* Fix #choice to allow for multiple from states
+* Add #current? to Transition to determine if matches from state
+* Add #select_choice_transition to EventsChain to determine matching choice transition
+* Fix #choice to work with same named events
+
 0.9.0 (August 3, 2014)
 
 * Add Definition class to allow to define standalone state machine

data/README.md

@@ -55,15 +55,18 @@ Or install it yourself as:
     * [2.1 Performing transitions](#21-performing-transitions)
     * [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)
-    * [2.6 Silent transitions](#26-silent-transitions)
+    * [2.4 Multiple from states](#24-multiple-from-states)
+    * [2.5 From :any state](#25-from-any-state)
+    * [2.6 Grouping states under single event](#26-grouping-states-under-single-event)
+    * [2.7 Silent transitions](#27-silent-transitions)
 * [3. Conditional transitions](#3-conditional-transitions)
     * [3.1 Using a Proc](#31-using-a-proc)
     * [3.2 Using a Symbol](#32-using-a-symbol)
     * [3.3 Using a String](#33-using-a-string)
     * [3.4 Combining transition conditions](#34-combining-transition-conditions)
 * [4. Choice pseudostates](#4-choice-pseudostates)
+  * [4.1 Dynamic choice conditions](#41-dynamic-choice-conditions)
+  * [4.2 Multiple from states](#42-multiple-from-states)
 * [5. Callbacks](#5-callbacks)
     * [5.1 on_enter](#51-on_enter)
     * [5.2 on_transition](#52-on_transition)
@@ -436,7 +439,7 @@ In order to fire the event transition asynchronously use the `async` scope like
 fm.async.ready  # => executes in separate Thread
 ```
 
-### 2.4 Single event with multiple from states
+### 2.4 Multiple from states
 
 If an event transitions from multiple states to the same state then all the states can be grouped into an array.
 Alternatively, you can create separate events under the same name for each transition that needs combining.
@@ -455,7 +458,29 @@ fm = FiniteMachine.define do
 end
 ```
 
-### 2.5 Grouping states under single event
+### 2.5 From :any state
+
+The **FiniteMachine** offers few ways to transition out of any state. This is parrticularly useful when the machine already defines many states.
+
+You can pass `:any` for the name of the state, for instance:
+
+```ruby
+event :run, from: :any, to: :green
+
+or
+
+event :run, :any => :green
+```
+
+Alternatively, you can skip the `:any` state definition and just specify `to` state:
+
+```ruby
+event :run, to: :green
+```
+
+All the above `run` event definitions will always transition the state machine into `:green` state.
+
+### 2.6 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:
 
@@ -483,7 +508,7 @@ fm = FiniteMachine.define do
   }
 ```
 
-### 2.6 Silent transitions
+### 2.7 Silent transitions
 
 The **FiniteMachine** allows to selectively silence events and thus prevent any callbacks from firing. Using the `silent` option passed to event definition like so:
 
@@ -655,6 +680,8 @@ fsm.next
 fsm.current # => :red
 ```
 
+### 4.1 Dynamic choice conditions
+
 Just as with event conditions you can make conditional logic dynamic and dependent on parameters passed in:
 
 ```ruby
@@ -677,6 +704,38 @@ fsm.current # => :yellow
 
 If more than one of the conditions evaluates to true, a first matching one is chosen. If none of the conditions evaluate to true, then the `default` state is matched. However if default state is not present and non of the conditions match, no transition is performed. To avoid such situation always specify `default` choice.
 
+### 4.2 Multiple from states
+
+Similarly to event definitions, you can specify the event to transition from a group of states:
+
+```ruby
+FiniteMachine.define do
+  initial :red
+
+  events {
+    event :next, from: [:yellow, :red] do
+      choice :pink, if: -> { false }
+      choice :green
+    end
+  }
+end
+```
+
+or from any state using the `:any` state name like so:
+
+```ruby
+FiniteMachine.define do
+  initial :red
+
+  events {
+    event :next, from: :any do
+      choice :pink, if: -> { false }
+      choice :green
+    end
+  }
+end
+```
+
 ## 5 Callbacks
 
 You can watch state machine events and the information they provide by registering a callback. The following 5 types of callbacks are available in **FiniteMachine**:

data/lib/finite_machine.rb

@@ -22,6 +22,7 @@ require "finite_machine/events_chain"
 require "finite_machine/hooks"
 require "finite_machine/logger"
 require "finite_machine/transition"
+require "finite_machine/transition_builder"
 require "finite_machine/transition_event"
 require "finite_machine/dsl"
 require "finite_machine/definition"

data/lib/finite_machine/choice_merger.rb

@@ -36,8 +36,8 @@ module FiniteMachine
     def choice(to, attrs = {})
       opts = options.dup
       opts.merge!(attrs)
-      opts.merge!(parsed_states: { options[:from] => to })
-      Transition.create(context.machine, opts)
+      transition_builder = TransitionBuilder.new(context.machine, opts)
+      transition_builder.call(options[:from] => to)
     end
     alias_method :default, :choice
   end # ChoiceMerger

data/lib/finite_machine/dsl.rb

@@ -226,14 +226,12 @@ module FiniteMachine
     def event(name, attrs = {}, &block)
       sync_exclusive do
         attributes = attrs.merge!(name: name)
-        FiniteMachine::StateParser.new(attrs).parse_states do |from, to|
-          if block_given?
-            merger = ChoiceMerger.new(self, attributes)
-            merger.instance_eval(&block)
-          else
-            attributes.merge!(parsed_states: { from => to })
-            Transition.create(machine, attributes)
-          end
+        if block_given?
+          merger = ChoiceMerger.new(self, attributes)
+          merger.instance_eval(&block)
+        else
+          transition_builder = TransitionBuilder.new(machine, attributes)
+          transition_builder.call(attrs)
         end
       end
     end

data/lib/finite_machine/event.rb

@@ -56,10 +56,8 @@ module FiniteMachine
     # @api private
     def next_transition
       sync_shared do
-        state_transitions.find do |transition|
-          transition.from_state == machine.current ||
-            transition.from_state == ANY_STATE
-        end || state_transitions.first
+        state_transitions.find { |transition| transition.current? } ||
+        state_transitions.first
       end
     end
 
@@ -72,7 +70,9 @@ module FiniteMachine
     # @api private
     def find_transition(*args)
       sync_shared do
-        state_transitions.find { |trans| trans.check_conditions(*args) }
+        state_transitions.find do |trans|
+          trans.current? && trans.check_conditions(*args)
+        end
       end
     end
 
@@ -89,11 +89,11 @@ module FiniteMachine
     # @api public
     def call(*args, &block)
       sync_exclusive do
-        _transition = next_transition
+        event_transition = next_transition
         if silent
-          _transition.call(*args, &block)
+          event_transition.call(*args, &block)
         else
-          machine.send(:transition, _transition, *args, &block)
+          machine.send(:transition, event_transition, *args, &block)
         end
       end
     end

data/lib/finite_machine/events_chain.rb

@@ -70,6 +70,18 @@ module FiniteMachine
       chain[name].find_transition(*args)
     end
 
+    # Examine choice transitions to find one matching condition
+    #
+    # @return [FiniteMachine::Transition]
+    #   The choice transition that matches
+    #
+    # @api public
+    def select_choice_transition(name, *args, &block)
+      chain[name].state_transitions.find do |trans|
+        trans.check_conditions(*args, &block)
+      end
+    end
+
     # Check if any of the transition constraints passes
     #
     # @param [Symbol] name

data/lib/finite_machine/state_machine.rb

@@ -45,7 +45,8 @@ module FiniteMachine
 
     def_delegator :@events_dsl, :event
 
-    def_delegators :@events_chain, :check_choice_conditions, :select_transition
+    def_delegators :@events_chain, :check_choice_conditions, :select_transition,
+                   :select_choice_transition
 
     # Initialize state machine
     #

data/lib/finite_machine/transition.rb

@@ -78,7 +78,7 @@ module FiniteMachine
     # @api public
     def to_state(*args)
       if transition_choice?
-        found_trans = machine.select_transition(name, *args)
+        found_trans = machine.select_choice_transition(name, *args)
         found_trans.map[from_state]
       else
         machine.transitions[name][from_state]
@@ -116,13 +116,29 @@ module FiniteMachine
       map[state] == state || (map[ANY_STATE] == state && from_state == state)
     end
 
+    # Check if from matches current state
+    #
+    # @example
+    #   transition.current? # => true
+    #
+    # @return [Boolean]
+    #   Return true if match is found, false otherwise.
+    #
+    # @api public
+    def current?
+      [machine.current, ANY_STATE].any? { |state| state == from_state }
+    end
+
     # Check if this transition has branching choice or not
     #
     # @return [Boolean]
     #
     # @api public
     def transition_choice?
-      machine.transitions[name][from_state].is_a?(Array)
+      matching = machine.transitions[name]
+      [matching[from_state], matching[ANY_STATE]].any? do |match|
+        match.is_a?(Array)
+      end
     end
 
     # Check if transition can be performed according to constraints

data/lib/finite_machine/transition_builder.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class reponsible for building transition out of parsed states
+  class TransitionBuilder
+    include Threadable
+
+    # The current state machine
+    attr_threadsafe :machine
+
+    attr_threadsafe :attributes
+
+    # Initialize a TransitionBuilder
+    #
+    # @example
+    #   TransitionBuilder.new(machine, {})
+    #
+    # @api public
+    def initialize(machine, attributes = {})
+      @machine = machine
+      @attributes = attributes
+    end
+
+    # Creates transitions for the states
+    #
+    # @example
+    #   transition_parser.call([:green, :yellow] => :red)
+    #
+    # @param [Hash[Symbol]] states
+    #   The states to extract
+    #
+    # @return [nil]
+    #
+    # @api public
+    def call(states)
+      FiniteMachine::StateParser.new(states).parse_states do |from, to|
+        attributes.merge!(parsed_states: { from => to })
+        Transition.create(machine, attributes)
+      end
+    end
+  end # TransitionBuilder
+end # FiniteMachine

data/lib/finite_machine/version.rb

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

data/spec/unit/choice_spec.rb

@@ -134,4 +134,54 @@ describe FiniteMachine, '#choice' do
     fsm.next
     expect(fsm.current).to eq(:company_form)
   end
+
+  it "allows to transition from multiple states to choice pseudostate" do
+    fsm = FiniteMachine.define do
+      initial :red
+
+      event :go, from: [:yellow, :red] do
+        choice :pink, if: -> { false }
+        choice :green
+      end
+    end
+    expect(fsm.current).to eq(:red)
+    fsm.go
+    expect(fsm.current).to eq(:green)
+    fsm.restore!(:yellow)
+    expect(fsm.current).to eq(:yellow)
+    fsm.go
+    expect(fsm.current).to eq(:green)
+  end
+
+  it "allows to transition from any state to choice pseudo state" do
+    fsm = FiniteMachine.define do
+      initial :red
+
+      event :go, from: :any do
+        choice :pink, if: -> { false }
+        choice :green
+      end
+    end
+    expect(fsm.current).to eq(:red)
+    fsm.go
+    expect(fsm.current).to eq(:green)
+  end
+
+  it "groups correctly events under the same name" do
+    fsm = FiniteMachine.define do
+      initial :red
+
+      event :next, from: :yellow, to: :green
+
+      event :next, from: :red do
+        choice :pink, if: -> { false }
+        choice :yellow
+      end
+    end
+    expect(fsm.current).to eq(:red)
+    fsm.next
+    expect(fsm.current).to eq(:yellow)
+    fsm.next
+    expect(fsm.current).to eq(:green)
+  end
 end

data/spec/unit/event/next_transition_spec.rb

@@ -8,11 +8,11 @@ describe FiniteMachine::Event, '#next_transition' do
   subject(:event) { object.new(machine, name: :test) }
 
   describe "matches transition by name" do
-    let(:machine) { double(:machine, current: :b) }
+    let(:machine) { double(:machine) }
 
     it "finds matching transition" do
-      transition_a = double(:transition_a, from_state: :a)
-      transition_b = double(:transition_b, from_state: :b)
+      transition_a = double(:transition_a, current?: false)
+      transition_b = double(:transition_b, current?: true)
       event << transition_a
       event << transition_b
 
@@ -20,25 +20,12 @@ describe FiniteMachine::Event, '#next_transition' do
     end
   end
 
-  describe "matches :any transition" do
-    let(:machine) { double(:machine, current: :any) }
-
-    it "finds matching transition" do
-      transition_a   = double(:transition_a, from_state: :a)
-      transition_any = double(:transition_any, from_state: :any)
-      event << transition_a
-      event << transition_any
-
-      expect(event.next_transition).to eq(transition_any)
-    end
-  end
-
   describe "fails to find" do
-    let(:machine) { double(:machine, current: :c) }
+    let(:machine) { double(:machine) }
 
     it "choses first available transition" do
-      transition_a = double(:transition_a, from_state: :a)
-      transition_b = double(:transition_b, from_state: :b)
+      transition_a = double(:transition_a, current?: false)
+      transition_b = double(:transition_b, current?: false)
       event << transition_a
       event << transition_b
 

data/spec/unit/events_spec.rb

@@ -111,6 +111,29 @@ describe FiniteMachine, 'events' do
     expect(fsm.current).to eql(:green)
   end
 
+  it "permits event from any state for hash syntax" do
+    fsm = FiniteMachine.define do
+      initial :red
+
+      events {
+        event :start, :red    => :yellow
+        event :run,   :yellow => :green
+        event :stop,  :green  => :red
+        event :go,    :any    => :green
+      }
+    end
+
+    expect(fsm.current).to eql(:red)
+
+    fsm.go
+    expect(fsm.current).to eql(:green)
+    fsm.stop
+    fsm.start
+    expect(fsm.current).to eql(:yellow)
+    fsm.go
+    expect(fsm.current).to eql(:green)
+  end
+
   it "permits event from any state without 'from'" do
     fsm = FiniteMachine.define do
       initial :green

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finite_machine
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-03 00:00:00.000000000 Z
+date: 2014-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -70,6 +70,7 @@ files:
 - lib/finite_machine/thread_context.rb
 - lib/finite_machine/threadable.rb
 - lib/finite_machine/transition.rb
+- lib/finite_machine/transition_builder.rb
 - lib/finite_machine/transition_event.rb
 - lib/finite_machine/version.rb
 - spec/spec_helper.rb