finite_machine 0.11.2 → 0.14.0

data/lib/finite_machine/safety.rb

@@ -1,7 +1,9 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
+require_relative "hook_event"
 
 module FiniteMachine
-  # Module for responsible for safety checks against known methods
+  # Module responsible for safety checks against known methods
   module Safety
     EVENT_CONFLICT_MESSAGE = \
       "You tried to define an event named \"%{name}\", however this would " \
@@ -33,11 +35,11 @@ module FiniteMachine
     # @api public
     def detect_event_conflict!(event_name, method_name = event_name)
       if method_already_implemented?(method_name)
-        fail FiniteMachine::AlreadyDefinedError, EVENT_CONFLICT_MESSAGE % {
+        raise FiniteMachine::AlreadyDefinedError, EVENT_CONFLICT_MESSAGE % {
           name: event_name,
           type: :instance,
           method: method_name,
-          source: 'FiniteMachine'
+          source: "FiniteMachine"
         }
       end
     end
@@ -55,12 +57,12 @@ module FiniteMachine
     def ensure_valid_callback_name!(event_type, name)
       message = if wrong_event_name?(name, event_type)
         EVENT_CALLBACK_CONFLICT_MESSAGE % {
-          type: "on_#{event_type.to_s}",
+          type: "on_#{event_type}",
           name: name
         }
       elsif wrong_state_name?(name, event_type)
         STATE_CALLBACK_CONFLICT_MESSAGE % {
-          type: "on_#{event_type.to_s}",
+          type: "on_#{event_type}",
           name: name
         }
       elsif !callback_names.include?(name)
@@ -71,7 +73,7 @@ module FiniteMachine
       else
         nil
       end
-      message && fail_invalid_callback_error(message)
+      message && raise_invalid_callback_error(message)
     end
 
     private
@@ -87,8 +89,8 @@ module FiniteMachine
     # @api private
     def wrong_event_name?(name, event_type)
       machine.states.include?(name) &&
-      !machine.event_names.include?(name) &&
-      event_type < HookEvent::Anyaction
+        !machine.events.include?(name) &&
+        event_type < HookEvent::Anyaction
     end
 
     # Check if state name exists
@@ -101,14 +103,14 @@ module FiniteMachine
     #
     # @api private
     def wrong_state_name?(name, event_type)
-      machine.event_names.include?(name) &&
-      !machine.states.include?(name) &&
-      event_type < HookEvent::Anystate
+      machine.events.include?(name) &&
+        !machine.states.include?(name) &&
+        event_type < HookEvent::Anystate
     end
 
-    def fail_invalid_callback_error(message)
+    def raise_invalid_callback_error(message)
       exception = InvalidCallbackNameError
-      machine.catch_error(exception) || fail(exception, message)
+      machine.catch_error(exception) || raise(exception, message)
     end
 
     # Check if method is already implemented inside StateMachine

data/lib/finite_machine/state_definition.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module FiniteMachine
   # A class responsible for defining state query methods on state machine
@@ -8,15 +8,13 @@ module FiniteMachine
   #
   # @api private
   class StateDefinition
-    include Threadable
-
     # Initialize a StateDefinition
     #
     # @param [StateMachine] machine
     #
     # @api public
     def initialize(machine)
-      self.machine = machine
+      @machine = machine
     end
 
     # Define query methods for states
@@ -34,7 +32,7 @@ module FiniteMachine
     private
 
     # The current state machine
-    attr_threadsafe :machine
+    attr_reader :machine
 
     # Define helper state mehods for the transition states
     #

data/lib/finite_machine/state_machine.rb

@@ -1,4 +1,15 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "catchable"
+require_relative "dsl"
+require_relative "env"
+require_relative "events_map"
+require_relative "hook_event"
+require_relative "observer"
+require_relative "threadable"
+require_relative "subscribers"
 
 module FiniteMachine
   # Base class for state machine
@@ -7,11 +18,18 @@ module FiniteMachine
     include Catchable
     extend Forwardable
 
+    # Current state
+    #
+    # @return [Symbol]
+    #
+    # @api private
+    attr_threadsafe :state
+
     # Initial state, defaults to :none
     attr_threadsafe :initial_state
 
-    # Final state, defaults to :none
-    attr_threadsafe :final_state
+    # Final state, defaults to nil
+    attr_threadsafe :terminal_states
 
     # The prefix used to name events.
     attr_threadsafe :namespace
@@ -20,21 +38,14 @@ module FiniteMachine
     attr_threadsafe :env
 
     # The state machine event definitions
-    attr_threadsafe :events_chain
-
-    # Errors DSL
-    #
-    # @return [ErrorsDSL]
-    #
-    # @api private
-    attr_threadsafe :errors_dsl
+    attr_threadsafe :events_map
 
-    # Events DSL
+    # Machine dsl
     #
-    # @return [EventsDSL]
+    # @return [DSL]
     #
     # @api private
-    attr_threadsafe :events_dsl
+    attr_threadsafe :dsl
 
     # The state machine observer
     #
@@ -43,13 +54,6 @@ module FiniteMachine
     # @api private
     attr_threadsafe :observer
 
-    # Current state
-    #
-    # @return [Symbol]
-    #
-    # @api private
-    attr_threadsafe :state
-
     # The state machine subscribers
     #
     # @return [Subscribers]
@@ -57,73 +61,81 @@ module FiniteMachine
     # @api private
     attr_threadsafe :subscribers
 
-    # The queue for asynchronoous events
-    #
-    # @return [EventQueue]
-    #
-    # @api private
-    attr_threadsafe :event_queue
-
     # Allow or not logging of transitions
     attr_threadsafe :log_transitions
 
-    def_delegators :@dsl, :initial, :terminal, :target, :trigger_init,
+    def_delegators :dsl, :initial, :terminal, :event, :trigger_init,
                    :alias_target
 
-    def_delegator :events_dsl, :event
-
     # Initialize state machine
     #
+    # @example
+    #   fsm = FiniteMachine::StateMachine.new(target_alias: :car) do
+    #     initial :red
+    #
+    #     event :go, :red => :green
+    #
+    #     on_transition do |event|
+    #       car.state = event.to
+    #     end
+    #   end
+    #
+    # @param [Hash] options
+    #   the options to create state machine with
+    # @option options [String] :alias_target
+    #   the alias for target object
+    #
     # @api private
     def initialize(*args, &block)
-      attributes     = args.last.is_a?(Hash) ? args.pop : {}
-
-      @event_queue   = EventQueue.new
+      options = args.last.is_a?(::Hash) ? args.pop : {}
       @initial_state = DEFAULT_STATE
-      @async_proxy   = AsyncProxy.new(self)
+      @auto_methods  = options.fetch(:auto_methods, true)
       @subscribers   = Subscribers.new
       @observer      = Observer.new(self)
-      @events_chain  = EventsChain.new
+      @events_map    = EventsMap.new
       @env           = Env.new(self, [])
-      @events_dsl    = EventsDSL.new(self)
-      @errors_dsl    = ErrorsDSL.new(self)
-      @dsl           = DSL.new(self, attributes)
+      @dsl           = DSL.new(self, options)
 
-      @dsl.call(&block) if block_given?
+      env.target = args.pop unless args.empty?
+      env.aliases << options[:alias_target] if options[:alias_target]
+      dsl.call(&block) if block_given?
       trigger_init
     end
 
-    # Subscribe observer for event notifications
+    # Check if event methods should be auto generated
     #
-    # @example
-    #   machine.subscribe(Observer.new(machine))
+    # @return [Boolean]
     #
     # @api public
-    def subscribe(*observers)
-      sync_exclusive { subscribers.subscribe(*observers) }
+    def auto_methods?
+      @auto_methods
     end
 
-    # Help to mark the event as synchronous
+    # Attach state machine to an object
+    #
+    # This allows state machine to initiate events in the context
+    # of a particular object
     #
     # @example
-    #   fsm.sync.go
+    #   FiniteMachine.define(target: object) do
+    #     ...
+    #   end
     #
-    # @return [self]
+    # @return [Object|FiniteMachine::StateMachine]
     #
     # @api public
-    alias_method :sync, :method_missing
+    def target
+      env.target
+    end
 
-    # Explicitly invoke event on proxy or delegate to proxy
+    # Subscribe observer for event notifications
     #
-    # @return [AsyncProxy]
+    # @example
+    #   machine.subscribe(Observer.new(machine))
     #
     # @api public
-    def async(method_name = nil, *args, &block)
-      if method_name
-        @async_proxy.method_missing method_name, *args, &block
-      else
-        @async_proxy
-      end
+    def subscribe(*observers)
+      sync_exclusive { subscribers.subscribe(*observers) }
     end
 
     # Get current state
@@ -132,7 +144,7 @@ module FiniteMachine
     #
     # @api public
     def current
-      state
+      sync_shared { state }
     end
 
     # Check if current state matches provided state
@@ -162,19 +174,19 @@ module FiniteMachine
     #
     # @api public
     def states
-      sync_shared { events_chain.states }
+      sync_shared { events_map.states }
     end
 
     # Retireve all event names
     #
     # @example
-    #   fsm.event_names # => [:init, :start, :stop]
+    #   fsm.events # => [:init, :start, :stop]
     #
     # @return [Array[Symbol]]
     #
     # @api public
-    def event_names
-      sync_shared { events_chain.events }
+    def events
+      events_map.events
     end
 
     # Checks if event can be triggered
@@ -183,7 +195,7 @@ module FiniteMachine
     #   fsm.can?(:go) # => true
     #
     # @example
-    #   fsm.can?(:go, 'Piotr')  # checks condition with parameter 'Piotr'
+    #   fsm.can?(:go, "Piotr")  # checks condition with parameter "Piotr"
     #
     # @param [String] event
     #
@@ -191,8 +203,8 @@ module FiniteMachine
     #
     # @api public
     def can?(*args)
-      event_name  = args.shift
-      events_chain.can_perform?(event_name, current, *args)
+      event_name = args.shift
+      events_map.can_perform?(event_name, current, *args)
     end
 
     # Checks if event cannot be triggered
@@ -215,7 +227,7 @@ module FiniteMachine
     #
     # @api public
     def terminated?
-      is?(final_state)
+      is?(terminal_states)
     end
 
     # Restore this machine to a known state
@@ -238,7 +250,7 @@ module FiniteMachine
     #
     # @api private
     def valid_state?(event_name)
-      current_states = events_chain.states_for(event_name)
+      current_states = events_map.states_for(event_name)
       current_states.any? { |state| state == current || state == ANY_STATE }
     end
 
@@ -273,7 +285,7 @@ module FiniteMachine
       else
         exception = InvalidStateError
         catch_error(exception) ||
-          fail(exception, "inappropriate current state '#{current}'")
+          raise(exception, "inappropriate current state '#{current}'")
 
         false
       end
@@ -290,9 +302,9 @@ module FiniteMachine
     #
     # @api public
     def trigger!(event_name, *data, &block)
-      sync_exclusive do
-        from = current # Save away current state
+      from = current # Save away current state
 
+      sync_exclusive do
         notify HookEvent::Before, event_name, from, *data
 
         status = try_trigger(event_name) do
@@ -313,6 +325,9 @@ module FiniteMachine
 
         status
       end
+    rescue Exception => err
+      self.state = from # rollback transition
+      raise err
     end
 
     # Trigger transition event without raising any errors
@@ -325,7 +340,7 @@ module FiniteMachine
     # @api public
     def trigger(event_name, *data, &block)
       trigger!(event_name, *data, &block)
-    rescue InvalidStateError, TransitionError
+    rescue InvalidStateError, TransitionError, CallbackError
       false
     end
 
@@ -336,7 +351,7 @@ module FiniteMachine
     # @api private
     def transition!(event_name, *data, &block)
       from_state = current
-      to_state   = events_chain.move_to(event_name, from_state, *data)
+      to_state   = events_map.move_to(event_name, from_state, *data)
 
       block.call(from_state, to_state) if block
 
@@ -376,9 +391,11 @@ module FiniteMachine
     # @api public
     def inspect
       sync_shared do
-        "<##{self.class}:0x#{object_id.to_s(16)} @states=#{states}, " \
-        "@events=#{event_names}, " \
-        "@transitions=#{events_chain.state_transitions}>"
+        "<##{self.class}:0x#{object_id.to_s(16)} " \
+        "@current=#{current.inspect} " \
+        "@states=#{states} " \
+        "@events=#{events} " \
+        "@transitions=#{events_map.state_transitions}>"
       end
     end
 
@@ -393,7 +410,7 @@ module FiniteMachine
     #
     # @api private
     def raise_transition_error(error)
-      fail TransitionError, Logger.format_error(error)
+      raise TransitionError, Logger.format_error(error)
     end
 
     # Forward the message to observer or self

data/lib/finite_machine/state_parser.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module FiniteMachine
   # A class responsible for converting transition arguments to states
@@ -7,148 +7,120 @@ module FiniteMachine
   #
   # @api private
   class StateParser
-    include Threadable
+    NON_STATE_KEYS = %i[name if unless silent].freeze
 
-    attr_threadsafe :attrs
+    STATE_KEYS = %i[from to].freeze
 
-    BLACKLIST = [:name, :if, :unless, :silent].freeze
-
-    # Initialize a StateParser
+    # Extract states from user defined attributes
     #
     # @example
-    #   StateParpser.new({from: [:green, :blue], to: :red})
-    #
-    # @param [Hash] attrs
-    #
-    # @api public
-    def initialize(attrs)
-      @attrs = ensure_only_states!(attrs)
-      freeze
-    end
-
-    # Extract states from attributes
+    #   StateParser.parse({from: [:green, :blue], to: :red})
+    #   # => {green: :red, green: :blue}
     #
     # @param [Proc] block
     #
-    # @example
-    #   StateParpser.new(attr).parase_states
-    #
     # @yield [Hash[Symbol]] the resolved states
     #
     # @return [Hash[Symbol]] the resolved states
     #
     # @api public
-    def parse(&block)
-      states = extract_states
+    def self.parse(attributes, &block)
+      attrs  = ensure_only_states!(attributes)
+      states = extract_states(attrs)
       block ? states.each(&block) : states
     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
+    # Extract only states from attributes
     #
-    # @return [Boolean]
+    # @return [Hash[Symbol]]
     #
-    # @api public
-    def contains_from_to_keys?
-      [:from, :to].any? { |key| attrs.keys.include?(key) }
+    # @api private
+    def self.ensure_only_states!(attrs)
+      attributes = attrs.dup
+      NON_STATE_KEYS.each { |key| attributes.delete(key) }
+      raise_not_enough_transitions unless attributes.any?
+      attributes
     end
+    private_class_method :ensure_only_states!
 
-    # Return parser attributes
+    # Perform extraction of states from user supplied definitions
     #
-    # @return [String]
+    # @return [Hash[Symbol]] the resolved states
     #
-    # @api public
-    def to_s
-      attrs.to_s
+    # @api private
+    def self.extract_states(attrs)
+      if contains_from_to_keys?(attrs)
+        convert_from_to_attributes_to_states_hash(attrs)
+      else
+        convert_attributes_to_states_hash(attrs)
+      end
     end
+    private_class_method :extract_states
 
-    # Return string representation
+    # Check if attributes contain :from or :to key
     #
-    # @return [String]
+    # @example
+    #   StateParser.contains_from_to_keys?({from: :green, to: :red})
+    #   # => true
     #
-    # @api public
-    def inspect
-      attributes = @attrs.map { |k, v| "#{k}:#{v}" }.join(', ')
-      "<##{self.class} @attrs=#{attributes}>"
-    end
-
-    private
-
-    # Extract only states from attributes
+    # @example
+    #   StateParser.contains_from_to_keys?({:green => :red})
+    #   # => false
     #
-    # @return [Hash[Symbol]]
+    # @return [Boolean]
     #
-    # @api private
-    def ensure_only_states!(attrs)
-      attributes = attrs.dup
-      BLACKLIST.each { |key| attributes.delete(key) }
-      raise_not_enough_transitions unless attributes.any?
-      attributes
+    # @api public
+    def self.contains_from_to_keys?(attrs)
+      STATE_KEYS.any? { |key| attrs.keys.include?(key) }
     end
+    private_class_method :contains_from_to_keys?
 
     # 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|
+    def self.convert_from_to_attributes_to_states_hash(attrs)
+      Array(attrs[:from] || ANY_STATE).each_with_object({}) do |state, hash|
         hash[state] = attrs[:to] || state
-        hash
       end
     end
+    private_class_method :convert_from_to_attributes_to_states_hash
 
     # Convert collapsed attributes to states hash
     #
     # @example
-    #   parser = StateParser.new([:green, :red] => :yellow)
-    #   parser.parse # => {green: :yellow, red: :yellow}
+    #   StateParser.convert_attributes_to_states_hash([:green, :red] => :yellow)
+    #   # => {green: :yellow, red: :yellow}
+    #
+    # @param [Hash] attrs
+    #   the attributes to convert to a simple hash
     #
     # @return [Hash[Symbol]]
     #
     # @api private
-    def convert_attributes_to_states_hash
-      attrs.reduce({}) do |hash, (k, v)|
+    def self.convert_attributes_to_states_hash(attrs)
+      attrs.each_with_object({}) do |(k, v), hash|
         if k.respond_to?(:to_ary)
           k.each { |el| hash[el] = v }
         else
           hash[k] = v
         end
-        hash
-      end
-    end
-
-    # Perform extraction of states from user supplied definitions
-    #
-    # @return [Hash[Symbol]] the resolved states
-    #
-    # @api private
-    def extract_states
-      if contains_from_to_keys?
-        convert_from_to_attributes_to_states_hash
-      else
-        convert_attributes_to_states_hash
       end
     end
+    private_class_method :convert_attributes_to_states_hash
 
     # Raise error when not enough transitions are provided
     #
     # @raise [NotEnoughTransitionsError]
-    #   if the event has not enough transition arguments
+    #   if the event has no transitions
     #
     # @return [nil]
     #
     # @api private
-    def raise_not_enough_transitions
-      fail NotEnoughTransitionsError, "please provide state transitions for" \
-           " '#{attrs.inspect}'"
+    def self.raise_not_enough_transitions
+      raise NotEnoughTransitionsError, "please provide state transitions"
     end
+    private_class_method :raise_not_enough_transitions
   end # StateParser
 end # FiniteMachine