finite_machine 0.11.2 → 0.14.0

data/lib/finite_machine.rb

@@ -1,33 +1,12 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 require "logger"
-require "thread"
-require "sync"
-require "forwardable"
-
-require "finite_machine/version"
-require "finite_machine/threadable"
-require "finite_machine/safety"
-require "finite_machine/callable"
-require "finite_machine/catchable"
-require "finite_machine/choice_merger"
-require "finite_machine/async_proxy"
-require "finite_machine/async_call"
-require "finite_machine/hook_event"
-require "finite_machine/env"
-require "finite_machine/event_queue"
-require "finite_machine/events_chain"
-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"
-require "finite_machine/state_machine"
-require "finite_machine/subscribers"
-require "finite_machine/observer"
-require "finite_machine/listener"
-require "finite_machine/two_phase_lock"
+
+require_relative "finite_machine/const"
+require_relative "finite_machine/logger"
+require_relative "finite_machine/definition"
+require_relative "finite_machine/state_machine"
+require_relative "finite_machine/version"
 
 module FiniteMachine
   # Default state name
@@ -36,22 +15,19 @@ module FiniteMachine
   # Initial default event name
   DEFAULT_EVENT_NAME = :init
 
-  # Describe any state transition
-  ANY_STATE = :any
+  # Describe any transition state
+  ANY_STATE = Const.new(:any)
 
   # Describe any event name
-  ANY_EVENT = :any_event
-
-  # Returned when transition has successfully performed
-  SUCCEEDED = 1
-
-  # Returned when transition is cancelled in callback
-  CANCELLED = 2
+  ANY_EVENT = Const.new(:any_event)
 
   # When transition between states is invalid
   TransitionError = Class.new(::StandardError)
 
-  # Raised when transitining to invalid state
+  # When failed to process callback
+  CallbackError = Class.new(::StandardError)
+
+  # Raised when transitioning to invalid state
   InvalidStateError = Class.new(::ArgumentError)
 
   InvalidEventError = Class.new(::NoMethodError)
@@ -66,30 +42,44 @@ module FiniteMachine
   MissingInitialStateError = Class.new(::StandardError)
 
   # Raised when event queue is already dead
-  EventQueueDeadError = Class.new(::StandardError)
+  MessageQueueDeadError = Class.new(::StandardError)
 
   # Raised when argument is already defined
   AlreadyDefinedError = Class.new(::ArgumentError)
 
-  class << self
+  module ClassMethods
     attr_accessor :logger
 
-    # TODO: this should instantiate system not the state machine
-    # and then delegate calls to StateMachine instance etc...
+    # Initialize an instance of finite machine
     #
     # @example
-    #   FiniteMachine.define do
+    #   FiniteMachine.new do
     #     ...
     #   end
     #
     # @return [FiniteMachine::StateMachine]
     #
     # @api public
-    def define(*args, &block)
+    def new(*args, &block)
       StateMachine.new(*args, &block)
     end
-    alias_method :new, :define
+
+    # A factory method for creating reusable FiniteMachine definitions
+    #
+    # @example
+    #   TrafficLights = FiniteMachine.define
+    #   lights_fm_a = TrafficLights.new
+    #   lights_fm_b = TrafficLights.new
+    #
+    # @return [Class]
+    #
+    # @api public
+    def define(&block)
+      Class.new(Definition, &block)
+    end
   end
+
+  extend ClassMethods
 end # FiniteMachine
 
 FiniteMachine.logger = Logger.new(STDERR)

data/lib/finite_machine/async_call.rb

@@ -1,14 +1,13 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module FiniteMachine
-  # An asynchronouse call representation
+  # An immutable asynchronouse call representation that wraps
+  # the {Callable} object
   #
-  # Used internally by {EventQueue} to schedule events
+  # Used internally by {MessageQueue} to dispatch events
   #
   # @api private
   class AsyncCall
-    include Threadable
-
     # Create asynchronous call instance
     #
     # @param [Object] context
@@ -19,15 +18,12 @@ module FiniteMachine
     # @example
     #   AsyncCall.new(context, Callable.new(:method), :a, :b)
     #
-    # @return [self]
-    #
     # @api public
     def initialize(context, callable, *args, &block)
       @context   = context
       @callable  = callable
       @arguments = args.dup
       @block     = block
-      @mutex     = Mutex.new
       freeze
     end
 
@@ -37,19 +33,7 @@ module FiniteMachine
     #
     # @api private
     def dispatch
-      @mutex.synchronize do
-        callable.call(context, *arguments, &block)
-      end
+      @callable.call(@context, *@arguments, &@block)
     end
-
-    protected
-
-    attr_threadsafe :context
-
-    attr_threadsafe :callable
-
-    attr_threadsafe :arguments
-
-    attr_threadsafe :block
   end # AsyncCall
 end # FiniteMachine

data/lib/finite_machine/callable.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module FiniteMachine
   # A generic interface for executing strings, symbol methods or procs.
@@ -20,7 +20,7 @@ module FiniteMachine
     #
     # @api public
     def invert
-      lambda { |*args, &block|  !call(*args, &block) }
+      ->(*args, &block) { !call(*args, &block) }
     end
 
     # Execute action
@@ -34,10 +34,10 @@ module FiniteMachine
         target.public_send(object.to_sym, *args, &block)
       when String
         string = args.empty? ? "-> { #{object} }" : "-> { #{object}(*#{args}) }"
-        value  = eval string
+        value  = eval(string)
         target.instance_exec(&value)
       when ::Proc
-        object.arity.zero? ?  object.call : object.call(target, *args)
+        object.arity.zero? ? object.call : object.call(target, *args)
       else
         raise ArgumentError, "Unknown callable #{object}"
       end

data/lib/finite_machine/catchable.rb

@@ -1,9 +1,11 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module FiniteMachine
   # A mixin to allow for specifying error handlers
   module Catchable
-
+    # Extends object with error handling methods
+    #
+    # @api private
     def self.included(base)
       base.module_eval do
         attr_threadsafe :error_handlers, default: []
@@ -31,7 +33,7 @@ module FiniteMachine
         if block_given?
           options[:with] = block
         else
-          raise ArgumentError, 'Need to provide error handler.'
+          raise ArgumentError, "Need to provide error handler."
         end
       end
       evaluate_exceptions(exceptions, options)
@@ -69,7 +71,7 @@ module FiniteMachine
     #
     # @api private
     def extract_const(class_name)
-      class_name.split('::').reduce(FiniteMachine) do |constant, part|
+      class_name.split("::").reduce(FiniteMachine) do |constant, part|
         constant.const_get(part)
       end
     end
@@ -83,9 +85,9 @@ module FiniteMachine
         target.method(handler)
       when Proc
         if handler.arity.zero?
-          proc { instance_exec(&handler) }
+          -> { instance_exec(&handler) }
         else
-          proc { |_exception| instance_exec(_exception, &handler) }
+          ->(exception) { instance_exec(exception, &handler) }
         end
       end
     end
@@ -99,16 +101,24 @@ module FiniteMachine
     # @api private
     def evaluate_exceptions(exceptions, options)
       exceptions.each do |exception|
-        key = if exception.is_a?(Class) && exception <= Exception
-          exception.name
-        elsif exception.is_a?(String)
-          exception
-        else
-          raise ArgumentError, "#{exception} isn't an Exception"
-        end
-
+        key = extract_exception_name(exception)
         error_handlers << [key, options[:with]]
       end
     end
+
+    # Extract exception name
+    #
+    # @param [Class,Exception,String] exception
+    #
+    # @api private
+    def extract_exception_name(exception)
+      if exception.is_a?(Class) && exception <= Exception
+        exception.name
+      elsif exception.is_a?(String)
+        exception
+      else
+        raise ArgumentError, "#{exception} isn't an Exception"
+      end
+    end
   end # Catchable
 end # FiniteMachine

data/lib/finite_machine/choice_merger.rb

@@ -1,44 +1,44 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
+require_relative "transition_builder"
 
 module FiniteMachine
   # A class responsible for merging choice options
   class ChoiceMerger
-    include Threadable
-
-    # The context where choice is executed
-    attr_threadsafe :machine
-
-    # The options passed in to the machine
-    attr_threadsafe :options
-
     # Initialize a ChoiceMerger
     #
+    # @param [StateMachine] machine
+    # @param [String] name
+    # @param [Hash] transitions
+    #   the transitions and attributes
+    #
     # @api private
-    def initialize(machine, options)
-      self.machine = machine
-      self.options = options
+    def initialize(machine, name, transitions = {})
+      @machine     = machine
+      @name        = name
+      @transitions = transitions
     end
 
     # Create choice transition
     #
     # @example
-    #   event from: :green do
+    #   event :stop, from: :green do
     #     choice :yellow
     #   end
     #
     # @param [Symbol] to
     #   the to state
-    # @param [Hash] attrs
+    # @param [Hash] conditions
+    #   the conditions associated with this choice
     #
     # @return [FiniteMachine::Transition]
     #
     # @api public
-    def choice(to, attrs = {})
-      opts = options.dup
-      opts.merge!(attrs)
-      transition_builder = TransitionBuilder.new(machine, opts)
-      transition_builder.call(options[:from] => to)
+    def choice(to, conditions = {})
+      transition_builder = TransitionBuilder.new(@machine, @name,
+                                                 @transitions.merge(conditions))
+      transition_builder.call(@transitions[:from] => to)
     end
-    alias_method :default, :choice
+    alias default choice
   end # ChoiceMerger
 end # FiniteMachine

data/lib/finite_machine/const.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FiniteMachine
+  class Const
+    def initialize(name)
+      @name = name.to_s
+      freeze
+    end
+
+    def to_s
+      @name
+    end
+    alias to_str to_s
+    alias inspect to_s
+  end # Const
+end # FiniteMachine

data/lib/finite_machine/definition.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module FiniteMachine
   # A class responsible for defining standalone state machine
@@ -38,7 +38,7 @@ module FiniteMachine
     # @api public
     def self.new(*args)
       context = self
-      FiniteMachine.define(*args) do
+      FiniteMachine.new(*args) do
         context.deferreds.each { |d| d.call(self) }
       end
     end
@@ -49,7 +49,7 @@ module FiniteMachine
     def self.inherited(subclass)
       super
 
-      self.deferreds.each { |d| subclass.add_deferred(d) }
+      deferreds.each { |d| subclass.add_deferred(d) }
     end
 
     # Delay lookup of DSL method

data/lib/finite_machine/dsl.rb

@@ -1,59 +1,98 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
+require_relative "choice_merger"
+require_relative "safety"
+require_relative "transition_builder"
 
 module FiniteMachine
   # A generic DSL for describing the state machine
   class GenericDSL
-    include Threadable
-
-    class << self
-      # @api private
-      attr_accessor :top_level
+    # Initialize a generic DSL
+    #
+    # @api public
+    def initialize(machine, attrs)
+      @machine = machine
+      @attrs   = attrs
     end
 
-    attr_threadsafe :machine
-
-    attr_threadsafe :attrs
+    # Expose any state constant
+    # @api public
+    def any_state
+      ANY_STATE
+    end
 
-    # Initialize a generic DSL
-    #
+    # Expose any event constant
     # @api public
-    def initialize(machine, attrs = {})
-      self.attrs = attrs
-      self.machine = machine
+    def any_event
+      ANY_EVENT
     end
 
     # Delegate attributes to machine instance
     #
     # @api private
     def method_missing(method_name, *args, &block)
-      if machine.respond_to?(method_name)
-        machine.send(method_name, *args, &block)
+      if @machine.respond_to?(method_name)
+        @machine.send(method_name, *args, &block)
       else
         super
       end
     end
 
+    # Check if message can be handled by this DSL
+    #
+    # @api private
+    def respond_to_missing?(method_name, include_private = false)
+      @machine.respond_to?(method_name) || super
+    end
+
+    # Configure state machine properties
+    #
+    # @api private
     def call(&block)
-      sync_exclusive { instance_eval(&block) }
-      # top_level.instance_eval(&block)
+      instance_eval(&block)
     end
   end # GenericDSL
 
   # A class responsible for adding state machine specific dsl
   class DSL < GenericDSL
-    attr_threadsafe :defer
-
-    attr_threadsafe :initial_event
+    include Safety
 
     # Initialize top level DSL
     #
     # @api public
-    def initialize(machine, attrs = {})
+    def initialize(machine, attrs)
       super(machine, attrs)
-      machine.state = FiniteMachine::DEFAULT_STATE
-      self.defer    = true
 
-      initialize_attrs
+      @machine.state = FiniteMachine::DEFAULT_STATE
+      @defer_initial = true
+      @silent_initial = true
+
+      initial(@attrs[:initial])   if @attrs[:initial]
+      terminal(@attrs[:terminal]) if @attrs[:terminal]
+      log_transitions(@attrs.fetch(:log_transitions, false))
+    end
+
+    # Add aliases for the target object
+    #
+    # @example
+    #   FiniteMachine.define do
+    #     target_alias :engine
+    #
+    #     on_transition do |event|
+    #       engine.state = event.to
+    #     end
+    #   end
+    #
+    # @param [Array<Symbol>] aliases
+    #   the names for target alias
+    #
+    # @api public
+    def alias_target(*aliases)
+      aliases.each do |alias_name|
+        next if env.aliases.include?(alias_name)
+
+        env.aliases << alias_name
+      end
     end
 
     # Define initial state
@@ -89,9 +128,9 @@ module FiniteMachine
     # @api public
     def initial(value, options = {})
       state = (value && !value.is_a?(Hash)) ? value : raise_missing_state
-      name, self.defer, silent = *parse_initial(options)
-      self.initial_event = name
-      event(name, FiniteMachine::DEFAULT_STATE => state, silent: silent)
+      name, @defer_initial, @silent_initial = *parse_initial(options)
+      @initial_event = name
+      event(name, FiniteMachine::DEFAULT_STATE => state, silent: @silent_initial)
     end
 
     # Trigger initial event
@@ -100,51 +139,8 @@ module FiniteMachine
     #
     # @api private
     def trigger_init
-      public_send(:"#{initial_event}") unless defer
-    end
-
-    # Attach state machine to an object
-    #
-    # This allows state machine to initiate events in the context
-    # of a particular object
-    #
-    # @example
-    #   FiniteMachine.define do
-    #     target :red
-    #   end
-    #
-    # @param [Object] object
-    #
-    # @return [FiniteMachine::StateMachine]
-    #
-    # @api public
-    def target(object = nil)
-      if object.nil?
-        env.target
-      else
-        env.target = object
-      end
-    end
-
-    # Use alternative name for target
-    #
-    # @example
-    #   target_alias: :car
-    #
-    #   callbacks {
-    #     on_transition do |event|
-    #       car.state = event.to
-    #     end
-    #   }
-    #
-    # @param [Symbol] alias_name
-    #   the name to alias target to
-    #
-    # @return [FiniteMachine::StateMachine]
-    #
-    # @api public
-    def alias_target(alias_name)
-      env.aliases << alias_name.to_sym
+      method = @silent_initial ? :transition : :trigger
+      @machine.public_send(method, :"#{@initial_event}") unless @defer_initial
     end
 
     # Define terminal state
@@ -156,42 +152,47 @@ module FiniteMachine
     #
     # @api public
     def terminal(*values)
-      self.final_state = values
+      self.terminal_states = values
     end
 
-    # Define state machine events
+    # Create event and associate transition
     #
     # @example
-    #   events do
-    #     event :start, :red => :green
-    #   end
+    #   event :go, :green => :yellow
+    #   event :go, :green => :yellow, if: :lights_on?
     #
-    # @return [FiniteMachine::StateMachine]
+    # @param [Symbol] name
+    #   the event name
+    # @param [Hash] transitions
+    #   the event transitions and conditions
+    #
+    # @return [Transition]
     #
     # @api public
-    def events(&block)
-      events_dsl.call(&block)
+    def event(name, transitions = {}, &block)
+      detect_event_conflict!(name) if machine.auto_methods?
+
+      if block_given?
+        merger = ChoiceMerger.new(machine, name, transitions)
+        merger.instance_eval(&block)
+      else
+        transition_builder = TransitionBuilder.new(machine, name, transitions)
+        transition_builder.call(transitions)
+      end
     end
 
-    # Define state machine callbacks
+    # Add error handler
     #
-    # @example
-    #   callbacks do
-    #     on_enter :green do |event| ... end
-    #   end
+    # @param [Array] exceptions
     #
-    # @return [FiniteMachine::Observer]
+    # @example
+    #   handle InvalidStateError, with: :log_errors
     #
-    # @api public
-    def callbacks(&block)
-      observer.call(&block)
-    end
-
-    # Error handler that throws exception when machine is in illegal state
+    # @return [Array[Exception]]
     #
     # @api public
-    def handlers(&block)
-      errors_dsl.call(&block)
+    def handle(*exceptions, &block)
+      @machine.handle(*exceptions, &block)
     end
 
     # Decide whether to log transitions
@@ -203,16 +204,6 @@ module FiniteMachine
 
     private
 
-    # Initialize state machine properties based off attributes
-    #
-    # @api private
-    def initialize_attrs
-      attrs[:initial]  && initial(attrs[:initial])
-      attrs[:target]   && target(attrs[:target])
-      attrs[:terminal] && terminal(attrs[:terminal])
-      log_transitions(attrs.fetch(:log_transitions, false))
-    end
-
     # Parse initial options
     #
     # @param [Hash] options
@@ -236,52 +227,8 @@ module FiniteMachine
     #
     # @api private
     def raise_missing_state
-      fail MissingInitialStateError,
-           'Provide state to transition :to for the initial event'
+      raise MissingInitialStateError,
+            "Provide state to transition :to for the initial event"
     end
   end # DSL
-
-  # A DSL for describing events
-  class EventsDSL < GenericDSL
-    include Safety
-    # Create event and associate transition
-    #
-    # @example
-    #   event :go, :green => :yellow
-    #   event :go, :green => :yellow, if: :lights_on?
-    #
-    # @return [Transition]
-    #
-    # @api public
-    def event(name, attrs = {}, &block)
-      sync_exclusive do
-        detect_event_conflict!(name)
-        attributes = attrs.merge!(name: name)
-        if block_given?
-          merger = ChoiceMerger.new(machine, attributes)
-          merger.instance_eval(&block)
-        else
-          transition_builder = TransitionBuilder.new(machine, attributes)
-          transition_builder.call(attrs)
-        end
-      end
-    end
-  end # EventsDSL
-
-  # A DSL for describing error conditions
-  class ErrorsDSL < GenericDSL
-    # Add error handler
-    #
-    # @param [Array] exceptions
-    #
-    # @example
-    #   handle InvalidStateError, with: :log_errors
-    #
-    # @return [Array[Exception]]
-    #
-    # @api public
-    def handle(*exceptions, &block)
-      machine.handle(*exceptions, &block)
-    end
-  end # ErrorsDSL
 end # FiniteMachine