Introduce names for FiniteMachine instances

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## [v0.14.1] - unreleased
+
+### Added
+* Add ability to name a FiniteMachine instance
+
 ## [v0.14.0] - 2020-09-12
 
 ### Added
@@ -312,6 +317,7 @@
 
 * Initial release
 
+[v0.14.1]: https://github.com/piotrmurach/finite_machine/compare/v0.14.0...v0.14.1
 [v0.14.0]: https://github.com/piotrmurach/finite_machine/compare/v0.13.0...v0.14.0
 [v0.13.0]: https://github.com/piotrmurach/finite_machine/compare/v0.12.1...v0.13.0
 [v0.12.1]: https://github.com/piotrmurach/finite_machine/compare/v0.12.0...v0.12.1

README.md

@@ -710,14 +710,26 @@ 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
+  ...
+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 then the first 8 characters from a randomly generated UUID string are used as a 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(machine_name, event_name, from, to, *args)
+      message = ["Transition: @machine=#{machine_name} @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.split("-")[0] }
 
       env.target = args.pop unless args.empty?
       env.aliases << options[:alias_target] if options[:alias_target]
@@ -356,7 +358,7 @@ def transition!(event_name, *data, &block)
       block.call(from_state, to_state) if block
 
       if log_transitions
-        Logger.report_transition(event_name, from_state, to_state, *data)
+        Logger.report_transition(@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(/Transition: @machine=TrafficLights @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(/Transition: @machine=TrafficLights @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("Transition: @machine=TrafficLights @event=go red -> green")
   end
 end