finite_machine 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f31937c5d49cee8c974c90b8339c1e3aa57f4866
-  data.tar.gz: 5386d3a848f6dd01d05d174d165447366c80ed19
+  metadata.gz: 1b14a2db5bcab11179dbd4cd9abd10826cda11e1
+  data.tar.gz: 1b5046cc5cb28b7cd082bce38088ed34c66d6aba
 SHA512:
-  metadata.gz: d8ca32da8076f07a43c53650ebdb99a22ba4e0fb4f721db972caeed7df91fb70feecde074b022e79798b5318c07ab59fddfadc91ddf131d4a4ea4d32b477e946
-  data.tar.gz: 674cc1ae00eb4fafe21adc37721a2bc92f7a482c2755599dbf1c884bb8e1e7f7591bdcaaf09922e54c2204fd3cd64042f43db5b3c9a939c7a2e0c93321ab940a
+  metadata.gz: 340d0ff2ea70b6f54127e06c2d2d6f7fe44309e44f5c8c10125aee29a363d8587890369cca037a7b09d614396f8758919f7b2cea67cdca8f15ed5e2679c1315a
+  data.tar.gz: 0372935e0396e9863700879fb906330d191d2f013d844eae8af58b4853a94b23a6b547c797779da77aeaf71db5fb38d38031ef4f7134864b2708aa900633f06a

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+0.8.1 (July 5, 2014)
+
+* Add EventsChain to handle internal events logic
+* Add EventBuilder to handle events construction
+
 0.8.0 (June 22, 2014)
 
 * Add silent option for state machine events to allow turning on/off

data/README.md

@@ -81,7 +81,8 @@ Or install it yourself as:
 * [6. Errors](#6-errors)
     * [6.1 Using target](#61-using-target)
 * [7. Integration](#7-integration)
-    * [7.1 ActiveRecord](#71-activerecord)
+    * [7.1 Plain Ruby Objects](#71-plain-ruby-objects)
+    * [7.2 ActiveRecord](#72-activerecord)
 * [8. Tips](#7-tips)
 
 ## 1 Usage
@@ -988,12 +989,14 @@ end
 
 ## 7 Integration
 
-Since **FiniteMachine** is an object in its own right it leaves integration with other systems up to you. In contrast to other Ruby libraries, it does not extend from models (i.e. ActiveRecord) to transform them into a state machine or require mixing into exisiting classes.
+Since **FiniteMachine** is an object in its own right, it leaves integration with other systems up to you. In contrast to other Ruby libraries, it does not extend from models (i.e. ActiveRecord) to transform them into a state machine or require mixing into exisiting classes.
+
+### 7.1 Plain Ruby Objects
+
+In order to use **FiniteMachine** with an object, you need to define a method that will construct the state machine. You can implement the state machine using the `define` DSL or create a seperate object that can be instantiated. To complete integration you will need to specify `target` context to allow state machine to communicate with the other methods inside the class like so:
 
 ```ruby
 class Car
-  attr_accessor :reverse_lights
-
   def turn_reverse_lights_off
     @reverse_lights = false
   end
@@ -1002,6 +1005,10 @@ class Car
     @reverse_lights = true
   end
 
+  def reverse_lights_on?
+    @reverse_lights || false
+  end
+
   def gears
     context = self
     @gears ||= FiniteMachine.define do
@@ -1034,7 +1041,21 @@ class Car
 end
 ```
 
-### 7.1 ActiveRecord
+Having written the class, you can use it as follows:
+
+```ruby
+car = Car.new
+car.gears.current      # => :neutral
+car.reverse_lights_on? # => false
+
+car.gears.start        # => "shifted from neutral to one"
+
+car.gears.back         # => "shifted from one to reverse"
+car.gears.current      # => :reverse
+car.reverse_lights_on? # => true
+```
+
+### 7.2 ActiveRecord
 
 In order to integrate **FiniteMachine** with ActiveRecord use the `target` helper to reference the current class and call ActiveRecord methods inside the callbacks to persist the state.
 
@@ -1042,8 +1063,9 @@ In order to integrate **FiniteMachine** with ActiveRecord use the `target` helpe
 class Account < ActiveRecord::Base
   validates :state, presence: true
 
-  def initialize
-    self.state = :unapproved
+  def initialize(attrs = {})
+    super
+    @manage.restore!(state) if state
   end
 
   def manage
@@ -1051,7 +1073,7 @@ class Account < ActiveRecord::Base
     @manage ||= FiniteMachine.define do
       target context
 
-      initial context.state
+      initial :unapproved
 
       events {
         event :enqueue, :unapproved => :pending
@@ -1060,7 +1082,7 @@ class Account < ActiveRecord::Base
 
       callbacks {
         on_enter_state do |event|
-          state = event.to
+          self.state = event.to
           save
         end
       }

data/lib/finite_machine.rb

@@ -3,6 +3,7 @@
 require "logger"
 require "thread"
 require "sync"
+require "forwardable"
 
 require "finite_machine/version"
 require "finite_machine/threadable"
@@ -15,7 +16,9 @@ require "finite_machine/async_proxy"
 require "finite_machine/async_call"
 require "finite_machine/hook_event"
 require "finite_machine/event"
+require "finite_machine/event_builder"
 require "finite_machine/event_queue"
+require "finite_machine/events_chain"
 require "finite_machine/hooks"
 require "finite_machine/logger"
 require "finite_machine/transition"

data/lib/finite_machine/event_builder.rb

@@ -0,0 +1,80 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for building event methods
+  class EventBuilder
+    include Threadable
+    include Safety
+
+    # The current state machine
+    attr_threadsafe :machine
+
+    # Initialize an EventBuilder
+    #
+    # @param [FiniteMachine::StateMachine] machine
+    #
+    # @api private
+    def initialize(machine)
+      @machine = machine
+    end
+
+    # Build state machine events
+    #
+    # @param [FiniteMachine::Transition] transition
+    #   the transition for which event is build
+    #
+    # @return [FiniteMachine::Transition]
+    #
+    # @api private
+    def call(transition)
+      name = transition.name
+      detect_event_conflict!(name)
+      if machine.singleton_class.send(:method_defined?, name)
+        machine.events_chain.insert(name, transition)
+      else
+        define_event_transition(name, transition)
+        define_event_bang(name)
+      end
+      transition
+    end
+
+    private
+
+    # Define transition event
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @param [FiniteMachine::Transition] transition
+    #   the transition this event is associated with
+    #
+    # @return [nil]
+    #
+    # @api private
+    def define_event_transition(name, transition)
+      silent = transition.silent
+      _event = FiniteMachine::Event.new(machine, name: name, silent: silent)
+      _event << transition
+      machine.events_chain.add(name, _event)
+
+      machine.send(:define_singleton_method, name) do |*args, &block|
+        _event.call(*args, &block)
+      end
+    end
+
+    # Define event that skips validations
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @return [nil]
+    #
+    # @api private
+    def define_event_bang(name)
+      machine.send(:define_singleton_method, "#{name}!") do
+        transitions   = machine.transitions[name]
+        machine.state = transitions.values[0]
+      end
+    end
+  end # EventBuilder
+end # FiniteMachine

data/lib/finite_machine/events_chain.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for storing chain of events
+  class EventsChain
+    include Threadable
+    extend Forwardable
+
+    # The current state machine
+    attr_threadsafe :machine
+
+    # The chain of events
+    attr_threadsafe :chain
+
+    def_delegators :@chain, :[], :empty?
+
+    # Initialize a EventsChain
+    #
+    # @param [FiniteMachine::StateMachine] machine
+    #   the state machine
+    #
+    # @api public
+    def initialize(machine)
+      @machine = machine
+      @chain   = {}
+    end
+
+    # Insert transition under given event name
+    #
+    # @param [Symbol] name
+    #  the event name
+    #
+    # @param [FiniteMachine::Transition]
+    #
+    # @return [nil]
+    #
+    # @api public
+    def insert(name, transition)
+      return false unless chain[name]
+      chain[name] << transition
+    end
+
+    # Add event under name
+    #
+    # @return [nil]
+    #
+    # @api public
+    def add(name, event)
+      chain[name] = event
+    end
+
+    # Check if event is valid and transition can be performed
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def valid_event?(event, *args, &block)
+      chain[event].next_transition.valid?(*args, &block)
+    end
+
+    # Select transition that passes constraints condition
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @return [FiniteMachine::Transition]
+    #
+    # @api public
+    def select_transition(name, *args)
+      chain[name].find_transition(*args)
+    end
+
+    # Check if any of the transition constraints passes
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def check_choice_conditions(name, *args, &block)
+      chain[name].state_transitions.any? do |trans|
+        trans.check_conditions(*args, &block)
+      end
+    end
+
+    # Reset chain
+    #
+    # @return [self]
+    #
+    # @api public
+    def clear
+      @chain.clear
+      self
+    end
+
+    # Return string representation of this chain
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_s
+      chain.to_s
+    end
+
+    # Inspect chain content
+    #
+    # @example
+    #   events_chain.inspect
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      "<##{self.class} @chain=#{chain.inspect}>"
+    end
+  end # EventsChain
+end # FiniteMachine

data/lib/finite_machine/state_machine.rb

@@ -1,7 +1,5 @@
 # encoding: utf-8
 
-require 'forwardable'
-
 module FiniteMachine
   # Base class for state machine
   class StateMachine
@@ -47,6 +45,8 @@ module FiniteMachine
 
     def_delegator :@events_dsl, :event
 
+    def_delegators :@events_chain, :check_choice_conditions, :select_transition
+
     # Initialize state machine
     #
     # @api private
@@ -58,7 +58,7 @@ module FiniteMachine
       @errors        = ErrorsDSL.new(self)
       @observer      = Observer.new(self)
       @transitions   = Hash.new { |hash, name| hash[name] = Hash.new }
-      @events_chain  = {}
+      @events_chain  = EventsChain.new(self)
       @env           = Environment.new(target: self)
       @dsl           = DSL.new(self, attributes)
 
@@ -177,7 +177,7 @@ module FiniteMachine
       event       = args.shift
       valid_state = transitions[event].key?(current)
       valid_state ||= transitions[event].key?(ANY_STATE)
-      valid_state &&= events_chain[event].next_transition.valid?(*args, &block)
+      valid_state &&= events_chain.valid_event?(event, *args, &block)
     end
 
     # Checks if event cannot be triggered

data/lib/finite_machine/transition.rb

@@ -4,7 +4,6 @@ module FiniteMachine
   # Class describing a transition associated with a given event
   class Transition
     include Threadable
-    include Safety
 
     attr_threadsafe :name
 
@@ -67,8 +66,9 @@ module FiniteMachine
       _transition = new(machine, attrs)
       _transition.update_transitions
       _transition.define_state_methods
-      _transition.define_event
-      _transition
+
+      builder = EventBuilder.new(machine)
+      builder.call(_transition)
     end
 
     # Decide :to state from available transitions for this event
@@ -77,8 +77,8 @@ module FiniteMachine
     #
     # @api public
     def to_state(*args)
-      if machine.transitions[name][from_state].is_a? Array
-        found_trans = machine.events_chain[name].find_transition(*args)
+      if transition_choice?
+        found_trans = machine.select_transition(name, *args)
         found_trans.map[from_state]
       else
         machine.transitions[name][from_state]
@@ -116,6 +116,15 @@ module FiniteMachine
       map[state] == state || (map[ANY_STATE] == state && from_state == 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)
+    end
+
     # Check if transition can be performed according to constraints
     #
     # @param [Array] args
@@ -126,10 +135,8 @@ module FiniteMachine
     #
     # @api public
     def valid?(*args, &block)
-      if machine.transitions[name][from_state].is_a? Array
-        machine.events_chain[name].state_transitions.any? do |trans|
-          trans.check_conditions(*args, &block)
-        end
+      if transition_choice?
+        machine.check_choice_conditions(name, *args, &block)
       else
         check_conditions(*args, &block)
       end
@@ -169,39 +176,16 @@ module FiniteMachine
       end
     end
 
-    # Define event on the machine
+    # Set state on the machine
     #
     # @api private
-    def define_event
-      detect_event_conflict!(name)
-      if machine.singleton_class.send(:method_defined?, name)
-        machine.events_chain[name] << self
+    def update_state(*args)
+      if transition_choice?
+        found_trans   = machine.select_transition(name, *args)
+        machine.state = found_trans.to_states.first
       else
-        define_event_transition(name)
-        define_event_bang(name)
-      end
-    end
-
-    # Define transition event
-    #
-    # @api private
-    def define_event_transition(name)
-      _event = FiniteMachine::Event.new(machine, name: name, silent: silent)
-      _event << self
-      machine.events_chain[name] = _event
-
-      machine.send(:define_singleton_method, name) do |*args, &block|
-        _event.call(*args, &block)
-      end
-    end
-
-    # Define event that skips validations
-    #
-    # @api private
-    def define_event_bang(name)
-      machine.send(:define_singleton_method, "#{name}!") do
         transitions   = machine.transitions[name]
-        machine.state = transitions.values[0]
+        machine.state = transitions[machine.state] || transitions[ANY_STATE] || name
       end
     end
 
@@ -213,14 +197,8 @@ module FiniteMachine
     def call(*args)
       sync_exclusive do
         return if cancelled
-        transitions     = machine.transitions[name]
         self.from_state = machine.state
-        if machine.transitions[name][from_state].is_a? Array
-          found_trans   = machine.events_chain[name].find_transition(*args)
-          machine.state = found_trans.to_states.first
-        else
-          machine.state   = transitions[machine.state] || transitions[ANY_STATE] || name
-        end
+        update_state(*args)
         machine.initial_state = machine.state if from_state == DEFAULT_STATE
       end
     end

data/lib/finite_machine/version.rb

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

data/spec/unit/event/inspect_spec.rb

@@ -14,4 +14,8 @@ describe FiniteMachine::Event, '#inspect' do
     event << transition
     expect(event.inspect).to eq("<#FiniteMachine::Event @name=test, @transitions=[#{transition.inspect}]>")
   end
+
+  it "prints event name" do
+    expect(event.to_s).to eq('test')
+  end
 end

data/spec/unit/events_chain/check_choice_conditions_spec.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::EventsChain, '#clear' do
+  let(:object)  { described_class }
+
+  let(:machine) { double(:machine) }
+
+  subject(:chain) { object.new(machine) }
+
+  it "clears chain events" do
+    event = double(:event)
+    chain.add(:validated, event)
+    expect(chain.empty?).to be_false
+
+    chain.clear
+    expect(chain.empty?).to be_true
+  end
+end

data/spec/unit/events_chain/clear_spec.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::EventsChain, '#insert' do
+  let(:object)  { described_class }
+
+  let(:machine) { double(:machine) }
+
+  let(:transition) { double(:transition) }
+
+  subject(:chain) { object.new(machine) }
+
+  it "inserts transition" do
+    event = double(:event)
+    chain.add(:validated, event)
+    expect(chain[:validated]).to eq(event)
+
+    expect(event).to receive(:<<).with(transition)
+    chain.insert(:validated, transition)
+  end
+
+  it "fails to insert transition" do
+    expect(chain.insert(:validated, transition)).to be_false
+  end
+end

data/spec/unit/events_chain/insert_spec.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::EventsChain, '#insert' do
+  let(:object)  { described_class }
+
+  let(:machine) { double(:machine) }
+
+  let(:transition) { double(:transition) }
+
+  subject(:chain) { object.new(machine) }
+
+  it "inserts transition" do
+    event = double(:event)
+    chain.add(:validated, event)
+    expect(chain[:validated]).to eq(event)
+
+    expect(event).to receive(:<<).with(transition)
+    chain.insert(:validated, transition)
+  end
+
+  it "fails to insert transition" do
+    expect(chain.insert(:validated, transition)).to be_false
+  end
+end

data/spec/unit/events_chain/inspect_spec.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::EventsChain, '#insert' do
+  let(:object)  { described_class }
+
+  let(:machine) { double(:machine) }
+
+  subject(:chain) { object.new(machine) }
+
+  it "inspects empty chain" do
+    expect(chain.inspect).to eq("<#FiniteMachine::EventsChain @chain={}>")
+  end
+
+  it "inspect chain" do
+    event = double(:event)
+    chain.add(:validated, event)
+    expect(chain.inspect).to eq("<#FiniteMachine::EventsChain @chain=#{{validated: event}}>")
+  end
+
+  it "prints chain" do
+    event = double(:event)
+    chain.add(:validated, event)
+    expect(chain.to_s).to eq("#{{validated: event}}")
+  end
+end

data/spec/unit/events_chain/select_transition_spec.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::EventsChain, '#select_transition' do
+  let(:object)  { described_class }
+
+  let(:machine) { double(:machine) }
+
+  let(:transition) { double(:transition) }
+
+  subject(:chain) { object.new(machine) }
+
+  it "selects transition" do
+    event = double(:event)
+    args = double(:args)
+    chain.add(:validated, event)
+    expect(chain[:validated]).to eq(event)
+
+    expect(event).to receive(:find_transition).with(args)
+    chain.select_transition(:validated, args)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finite_machine
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-22 00:00:00.000000000 Z
+date: 2014-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -54,7 +54,9 @@ files:
 - lib/finite_machine/choice_merger.rb
 - lib/finite_machine/dsl.rb
 - lib/finite_machine/event.rb
+- lib/finite_machine/event_builder.rb
 - lib/finite_machine/event_queue.rb
+- lib/finite_machine/events_chain.rb
 - lib/finite_machine/hook_event.rb
 - lib/finite_machine/hooks.rb
 - lib/finite_machine/listener.rb
@@ -80,6 +82,11 @@ files:
 - spec/unit/event/inspect_spec.rb
 - spec/unit/event/next_transition_spec.rb
 - spec/unit/event_queue_spec.rb
+- spec/unit/events_chain/check_choice_conditions_spec.rb
+- spec/unit/events_chain/clear_spec.rb
+- spec/unit/events_chain/insert_spec.rb
+- spec/unit/events_chain/inspect_spec.rb
+- spec/unit/events_chain/select_transition_spec.rb
 - spec/unit/events_spec.rb
 - spec/unit/finished_spec.rb
 - spec/unit/handlers_spec.rb
@@ -138,6 +145,11 @@ test_files:
 - spec/unit/event/inspect_spec.rb
 - spec/unit/event/next_transition_spec.rb
 - spec/unit/event_queue_spec.rb
+- spec/unit/events_chain/check_choice_conditions_spec.rb
+- spec/unit/events_chain/clear_spec.rb
+- spec/unit/events_chain/insert_spec.rb
+- spec/unit/events_chain/inspect_spec.rb
+- spec/unit/events_chain/select_transition_spec.rb
 - spec/unit/events_spec.rb
 - spec/unit/finished_spec.rb
 - spec/unit/handlers_spec.rb