Introduce names for FiniteMachine instances

Author: Robin Randhawa

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## [v0.14.1] - 2021-08-08
+
+### Added
+* Add ability to name a FiniteMachine
+
 ## [v0.14.0] - 2020-09-12
 
 ### Added

README.md

@@ -710,14 +710,31 @@ fm.stop # callbacks are fired
 
 ### 3.7 Logging transitions
 
-To help debug your state machine, **FiniteMachine** provides `:log_transitions` option.
+To help debug your state machine, **FiniteMachine** provides a `:log_transitions` option.
 
 ```ruby
 FiniteMachine.new(log_transitions: true) do
   ...
 end
 ```
 
+A FiniteMachine instance can optionally be given a name:
+
+```ruby
+fm = FiniteMachine.new(name: 'TrafficLights', log_transitions: true) do
+  initial :green
+
+  event :slow,  :green  => :yellow
+  event :stop,  :yellow => :red
+  event :ready, :red    => :yellow
+  event :go,    :yellow => :green
+end
+```
+
+The name will then appear in transition logs which helps disambiguate events relevant to different state machines.
+
+Note that if no name is specified a UUID is automatically generated and used as the default name.
+
 ### 3.8 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.

lib/finite_machine/logger.rb

@@ -30,8 +30,8 @@ def format_error(error)
       message.join
     end
 
-    def report_transition(name, from, to, *args)
-      message = ["Transition: @event=#{name} "]
+    def report_transition(fsm_name, event_name, from, to, *args)
+      message = ["StateMachine: #{fsm_name} Transition: @event=#{event_name} "]
       unless args.empty?
         message << "@with=[#{args.join(',')}] "
       end

lib/finite_machine/state_machine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "forwardable"
+require "securerandom"
 
 require_relative "catchable"
 require_relative "dsl"
@@ -95,6 +96,7 @@ def initialize(*args, &block)
       @events_map    = EventsMap.new
       @env           = Env.new(self, [])
       @dsl           = DSL.new(self, options)
+      @name          = options.fetch(:name, SecureRandom.uuid)
 
       env.target = args.pop unless args.empty?
       env.aliases << options[:alias_target] if options[:alias_target]
@@ -352,11 +354,12 @@ def trigger(event_name, *data, &block)
     def transition!(event_name, *data, &block)
       from_state = current
       to_state   = events_map.move_to(event_name, from_state, *data)
+      fsm_name = @name
 
       block.call(from_state, to_state) if block
 
       if log_transitions
-        Logger.report_transition(event_name, from_state, to_state, *data)
+        Logger.report_transition(fsm_name, event_name, from_state, to_state, *data)
       end
 
       try_trigger(event_name) { transition_to!(to_state) }

spec/unit/log_transitions_spec.rb

@@ -6,7 +6,7 @@
   after  { FiniteMachine.logger = ::Logger.new($stderr) }
 
   it "logs transitions" do
-    fsm = FiniteMachine.new log_transitions: true do
+    fsm = FiniteMachine.new name: 'TrafficLights', log_transitions: true do
       initial :green
 
       event :slow, :green  => :yellow
@@ -15,10 +15,10 @@
 
     fsm.slow
     output.rewind
-    expect(output.read).to match(/Transition: @event=slow green -> yellow/)
+    expect(output.read).to match(/StateMachine: TrafficLights Transition: @event=slow green -> yellow/)
 
     fsm.stop(1, 2)
     output.rewind
-    expect(output.read).to match(/Transition: @event=stop @with=\[1,2\] yellow -> red/)
+    expect(output.read).to match(/StateMachine: TrafficLights Transition: @event=stop @with=\[1,2\] yellow -> red/)
   end
 end

spec/unit/logger_spec.rb

@@ -29,8 +29,8 @@
   end
 
   it "reports transition" do
-    logger.report_transition(:go, :red, :green)
+    logger.report_transition('TrafficLights', :go, :red, :green)
 
-    expect(log).to have_received(:info).with("Transition: @event=go red -> green")
+    expect(log).to have_received(:info).with("StateMachine: TrafficLights Transition: @event=go red -> green")
   end
 end