microfsm 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7974725af299cb54f56eb1542a52799c2b7530d5e389c66eec09c8a4c02de1b
-  data.tar.gz: a5651e39934546af36c5764f8fab0ba5703e7aac59ffc8d11c84564c066c087b
+  metadata.gz: eb5ea2d5710c8f5a3296cb1eeb0b8b56a18143faf35c55138e13d6abd3702cdc
+  data.tar.gz: 14cc5dfc48e7338d2d7bf5efb54499a24054b2aa89bafffd92f1f8026b091259
 SHA512:
-  metadata.gz: 5338e4e3b5f018c149c8941199f971722ff382222b8fb5b4032f629fb2687b7caf1eda320d3484b5aa1766c644a918caa994aa72b528c4ea54acd97ed8747135
-  data.tar.gz: a89939784e83be8223b391703301167e3f9b4f1098e5a2132837d5c9f93e7b517c1fa88591d165aded7ae0533ce40039b3f4a26ac6fc2f88e9ea59c0399732ab
+  metadata.gz: 933ab09b4dcf57bcb0d3b229c4b125f3408c48f8759ef59cf9aea796e89cd775678bf452aa744c8f27e2768d8e10bab8cc889c3a21ab8153711238ff7a7e7f43
+  data.tar.gz: bff990c82be6edeffd463a1eefd34a0dd1b196b64a59ad93205edbbf15857162ea4b0b027bb8e14ec5c88092788c9996d00bcdf2c9beeeed88c0568cf4462602

data/README.md

@@ -8,7 +8,7 @@
 
 MicroFSM implements a minimal/simple Finite-State Machine (FSM).
 Transitions are triggered by events.
-Actions for a transition can be added as callbacks.
+An action for a transition can be added as a callback.
 
 Finite-State Machine are described elsewhere, e.g. Wikipedia.
 
@@ -68,15 +68,21 @@ fsm.state              #=> :ignored
 
 ## Actions
 
-Adding actions to a transition is trivial:
+Adding an action to a transition is trivial:
 
 ```ruby
-fsm.when(:confirm, new: :confirmed) { |event| count += 1 }
-fsm.when(:confirm, new: :confirmed) { |event| foo(event) }
+fsm.when(:confirm, new: :confirmed) { |event, next_state|
+  count += 1
+  next_state # returning nil will disable the transition
+}
 ```
 
-Two actions/callbacks are triggered in the previous example.
+## Version 1.*
 
+*Actions* have been enhanced:
+
+- next_state: a second parameter has been added
+- a return value is expected (see example above)
 
 ## Miscellaneous
 

data/examples/advanced.rb

@@ -2,19 +2,19 @@ require "microfsm"
 
 # This example can be run with ruby -I lib/ ./examples/advanced.rb
 
-fsm = MicroFSM.new(:pending)
-proc = ->(event) { puts fsm.state.capitalize }
-fsm.when(:confirm, pending: :confirmed, &proc)
-  .when(:ignore, pending: :ignored, &proc)
-  .when(:reset, confirmed: :pending, ignored: :pending, &proc)
+fsm = MicroFSM.new(:idle)
+proc = ->(event, next_state) { puts next_state.capitalize; next_state }
+fsm.when(:confirm, idle: :confirmed, &proc)
+  .when(:ignore, idle: :ignored, &proc)
+  .when(:reset, confirmed: :idle, ignored: :idle, &proc)
 
-puts "Should print Confirmed, Pending and Ignored:"
+puts "Should print Confirmed, Idle and Ignored:"
 fsm.trigger(:confirm)
 fsm.trigger(:ignore)
 fsm.trigger(:reset)
 fsm.trigger(:ignore)
 
-puts "Should print all states: confirmed, ignored, pending"
+puts "Should print all states: confirmed, idle, ignored"
 puts fsm.states.join ", "
 
 puts "Should print all events: confirm, ignore, reset"

data/examples/advanced.rb.bak

@@ -0,0 +1,21 @@
+require "microfsm"
+
+# This example can be run with ruby -I lib/ ./examples/advanced.rb
+
+fsm = MicroFSM.new(:idle)
+proc = ->(event) { puts fsm.state.capitalize }
+fsm.when(:confirm, idle: :confirmed, &proc)
+  .when(:ignore, idle: :ignored, &proc)
+  .when(:reset, confirmed: :idle, ignored: :idle, &proc)
+
+puts "Should print Confirmed, Pending and Ignored:"
+fsm.trigger(:confirm)
+fsm.trigger(:ignore)
+fsm.trigger(:reset)
+fsm.trigger(:ignore)
+
+puts "Should print all states: confirmed, ignored, idle
+puts fsm.states.join ", "
+
+puts "Should print all events: confirm, ignore, reset"
+puts fsm.events.join ", "

data/examples/basic.rb

@@ -2,10 +2,10 @@ require "microfsm"
 
 # This example can be run with ruby -I lib/ ./examples/basic.rb
 
-fsm = MicroFSM.new(:pending)
-  .when(:confirm, pending: :confirmed)
-  .when(:ignore, pending: :ignored)
-  .when(:reset, confirmed: :pending, ignored: :pending)
+fsm = MicroFSM.new(:idle)
+  .when(:confirm, idle: :confirmed)
+  .when(:ignore, idle: :ignored)
+  .when(:reset, confirmed: :idle, ignored: :idle)
 
 puts "Should print Confirmed, Reset and Ignored:"
 

data/examples/basic.rb.bak

@@ -0,0 +1,26 @@
+require "microfsm"
+
+# This example can be run with ruby -I lib/ ./examples/basic.rb
+
+fsm = MicroFSM.new(:pending)
+  .when(:confirm, pending: :confirmed)
+  .when(:ignore, pending: :ignored)
+  .when(:reset, confirmed: :pending, ignored: :pending)
+
+puts "Should print Confirmed, Reset and Ignored:"
+
+if fsm.trigger(:confirm)
+  puts "Confirmed"
+end
+
+if fsm.trigger(:ignore)
+  puts "Ignored"
+end
+
+if fsm.trigger(:reset)
+  puts "Reset"
+end
+
+if fsm.trigger(:ignore)
+  puts "Ignored"
+end

data/examples/callbacks.rb

@@ -2,12 +2,13 @@ require "microfsm"
 
 # This example can be run with ruby -I lib/ ./examples/callbacks.rb
 
-fsm = MicroFSM.new(:pending)
-  .when(:confirm, pending: :confirmed) { puts "Confirmed" }
-  .when(:ignore, pending: :ignored) { puts "Ignored" }
-  .when(:reset, confirmed: :pending, ignored: :pending) {
+fsm = MicroFSM.new(:idle)
+  .when(:confirm, idle: :confirmed) { |ev, ns| puts "Confirmed"; ns }
+  .when(:ignore, idle: :ignored) { |ev, ns| puts "Ignored"; ns }
+  .when(:reset, confirmed: :idle, ignored: :idle) do |ev, ns|
     puts "Reset"
-  }
+    ns
+  end
 
 puts "Should print Confirmed, Reset and Ignored:"
 fsm.trigger(:confirm)

data/examples/callbacks.rb.bak

@@ -0,0 +1,16 @@
+require "microfsm"
+
+# This example can be run with ruby -I lib/ ./examples/callbacks.rb
+
+fsm = MicroFSM.new(:idle)
+  .when(:confirm, idle: :confirmed) { puts "Confirmed" }
+  .when(:ignore, idle: :ignored) { puts "Ignored" }
+  .when(:reset, confirmed: :idle, ignored: :idle) {
+    puts "Reset"
+  }
+
+puts "Should print Confirmed, Reset and Ignored:"
+fsm.trigger(:confirm)
+fsm.trigger(:ignore)
+fsm.trigger(:reset)
+fsm.trigger(:ignore)

data/lib/microfsm/version.rb

@@ -1,5 +1,6 @@
 class MicroFSM
-  VERSION = "0.2.1" # 2026-03-31
+  VERSION = "1.0.0" # 2026-04-20
+  # VERSION = "0.2.1" # 2026-03-31
   # VERSION = "0.2.0" # 2026-01-01
   # VERSION = "0.1.11" # 2025-06-19
   # VERSION = "0.1.10" # 2024-10-20

data/lib/microfsm/version.rb.bak

@@ -1,5 +1,6 @@
 class MicroFSM
-  VERSION = "0.2.0" # 2026-01-01
+  VERSION = "0.2.1" # 2026-03-31
+  # VERSION = "0.2.0" # 2026-01-01
   # VERSION = "0.1.11" # 2025-06-19
   # VERSION = "0.1.10" # 2024-10-20
   # VERSION = "0.1.9" # 2024-05-22

data/lib/microfsm.rb

@@ -1,32 +1,44 @@
+require "ricecream"
+
 class MicroFSM
   InvalidEvent = Class.new(NoMethodError)
   InvalidState = Class.new(ArgumentError)
   InvalidTransition = Class.new(ArgumentError)
 
   attr_accessor :state
+  attr_accessor :timed
+  attr_accessor :previous_utc
+  attr_accessor :current_utc
 
   def initialize(initial_state)
     @state = initial_state
+    @timed = false
     @transitions_for = {}
-    @callbacks_for = {}
+    @callback_for = {}
   end
 
   def when(event, transitions, &block)
     @transitions_for[event] ||= {}
-    @callbacks_for[event] ||= {}
+    @callback_for[event] ||= {}
+    @timed = true if block
 
     transitions.each do |from, to|
       nto = @transitions_for[event][from]
       raise InvalidTransition if nto && nto != to
 
       @transitions_for[event][from] = to
-      @callbacks_for[event][from] ||= []
-      @callbacks_for[event][from] << block if block
+      @callback_for[event][from] = block if block
+      @current_utc = Time.now.utc if block
     end
     self
   end
 
   def trigger(event)
+    if @timed
+      @previous_utc = @current_utc
+      @current_utc = Time.now.utc
+    end
+
     trigger?(event) and transit(event)
   end
 
@@ -56,10 +68,10 @@ class MicroFSM
   private
 
   def transit(event)
-    callbacks = @callbacks_for[event][@state]
-    @state = @transitions_for[event][@state]
-    callbacks.each { |callback| callback.call(event) }
-    true
+    callback = @callback_for[event][@state]
+    next_state = @transitions_for[event][@state]
+    next_state = callback.call(event, next_state) if callback
+    @state = next_state if next_state
   end
 
   def msg(event)

data/lib/microfsm.rb.bak

@@ -0,0 +1,80 @@
+require "ricecream"
+
+class MicroFSM
+  InvalidEvent = Class.new(NoMethodError)
+  InvalidState = Class.new(ArgumentError)
+  InvalidTransition = Class.new(ArgumentError)
+
+  attr_accessor :state
+  attr_accessor :timed
+  attr_accessor :previous_utc
+  attr_accessor :current_utc
+
+  def initialize(initial_state)
+    @state = initial_state
+    @timed = false
+    @transitions_for = {}
+    @callback_for = {}
+  end
+
+  def when(event, transitions, &block)
+    @transitions_for[event] ||= {}
+    @callback_for[event] ||= {}
+    @timed = true if block
+
+    transitions.each do |from, to|
+      nto = @transitions_for[event][from]
+      raise InvalidTransition if nto && nto != to
+
+      @transitions_for[event][from] = to
+      @callback_for[event][from] ||= []
+      @callback_for[event][from] << block if block
+    end
+    self
+  end
+
+  def trigger(event)
+    if @timed
+      @previous_utc = @current_utc
+      @current_utc = Time.now.utc
+    end
+
+    trigger?(event) and transit(event)
+  end
+
+  def trigger!(event)
+    trigger(event) or
+      raise InvalidState.new(msg(event))
+  end
+
+  def trigger?(event)
+    raise InvalidEvent.new(msg(event)) unless @transitions_for.has_key?(event)
+
+    @transitions_for[event].has_key?(state)
+  end
+
+  def events
+    @transitions_for.keys.sort
+  end
+
+  def triggerable_events
+    events.select { |event| trigger?(event) }.sort
+  end
+
+  def states
+    @transitions_for.values.map(&:to_a).flatten.uniq.sort
+  end
+
+  private
+
+  def transit(event)
+    callback = @callback_for[event][@state]
+    @state = @transitions_for[event][@state]
+    callback.each { |callback| callback.call(event) }
+    true
+  end
+
+  def msg(event)
+    "State: #{@state}; Event: #{event}"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microfsm
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Dittmar Krall
@@ -38,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: MicroFSM implements a minimal/simple Finite-State Machine (FSM). Transitions
-  are triggered by events. Actions for a transition can be added as callbacks.
+  are triggered by events. An action for a transition can be added as a callback.
 email: dittmar.krall@matiq.com
 executables: []
 extensions: []
@@ -49,9 +49,13 @@ files:
 - MIT-LICENSE
 - README.md
 - examples/advanced.rb
+- examples/advanced.rb.bak
 - examples/basic.rb
+- examples/basic.rb.bak
 - examples/callbacks.rb
+- examples/callbacks.rb.bak
 - lib/microfsm.rb
+- lib/microfsm.rb.bak
 - lib/microfsm/version.rb
 - lib/microfsm/version.rb.bak
 homepage: https://github.com/matique/microfsm
@@ -72,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Minimal Finite State Machine.
 test_files: []