microfsm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f8380343e775bb2c143ccb457454ab729544226984831170d68d674faa5b674f
+  data.tar.gz: 3b9cc48b46baac3f500309345312302ce79069b568043979efc220a1adf98ae2
+SHA512:
+  metadata.gz: 9ff4030bcdeb6a31ae300a1ec575aa252fb9f08267e8482eb361bd26884eb2b307bf30d397bfdd6e6a57bfb70f72900f593bf53f579e029dcbad5802d92ee561
+  data.tar.gz: fe18e71eca3810d8e0a2b862fc37cb580854b11162116fd27c78933654cb46b93494ea95431dfd9bdfcedf0e0b0423c9340e58fbf1166c792a02c79792dc0028

data/.rubocop.yml

@@ -0,0 +1,19 @@
+inherit_from:
+  - ~/configs/.rubocop.yml
+
+AllCops:
+  Include:
+    - 'lib/**/*.rb'
+
+  Exclude:
+    - 'bin/**/*'
+    - 'test/**/*'
+  SuggestExtensions: false
+
+Layout/AccessModifierIndentation:
+  Enabled: false
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false

data/.ruby-gemset

@@ -0,0 +1 @@
+rails-6.1

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.7.2

data/.watchr

@@ -0,0 +1,57 @@
+HH = '#' * 22  unless defined?(HH)
+H = '#' * 5    unless defined?(H)
+
+def usage
+  puts <<-EOS
+  Ctrl-\\ or ctrl-4   Running all tests
+  Ctrl-C             Exit
+  EOS
+end
+
+def run(cmd)
+  puts "#{HH} #{Time.now} #{HH}"
+  puts "#{H} #{cmd}"
+  system "/usr/bin/time --format '#{HH} Elapsed time %E' #{cmd}"
+end
+
+def run_it(type, file)
+  case type
+  when 'test';  run %Q(ruby -I"lib:test" -r rubygems #{file})
+  else;         puts "#{H} unknown type: #{type}, file: #{file}"
+  end
+end
+
+def run_all_tests
+  puts "\n#{HH} Running all tests #{HH}\n"
+  %w[test].each { |dir| run "rake #{dir}"  if  File.exist?(dir) }
+end
+
+def run_matching_files(base)
+  base = base.split('_').first
+  %w[test spec].each { |type|
+    files = Dir["#{type}/**/*.rb"].select { |file| file =~ /#{base}_.*\.rb/ }
+    run_it type, files.join(' ')  unless files.empty?
+  }
+end
+
+%w[test spec].each { |type|
+  watch("#{type}/#{type}_helper\.rb") { run_all_tests }
+  watch("#{type}/.*/*_#{type}\.rb")   { |match| run_it type, match[0] }
+  watch("#{type}/data/(.*)\.rb") { |match|
+    m1 = match[1]
+    run_matching_files("#{type}/#{m1}/#{m1}_#{type}.rb")
+  }
+}
+%w[rb erb haml slim].each { |type|
+#  watch("app/.*/(.*)\.#{type}") { |match|
+  watch(".*/(.*)\.#{type}") { |match|
+p [11, match]
+    run_matching_files(match[1])
+  }
+}
+
+# Ctrl-\ or ctrl-4
+    Signal.trap('QUIT') { run_all_tests }
+# Ctrl-C
+    Signal.trap('INT')  { abort("Interrupted\n") }
+usage

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'observr'
+  gem 'rubocop', require: false
+  gem 'simplecov', require: false
+end

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    microfsm (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    docile (1.3.5)
+    minitest (5.14.3)
+    observr (1.0.5)
+    parallel (1.20.1)
+    parser (3.0.0.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    regexp_parser (2.0.3)
+    rexml (3.2.4)
+    rubocop (1.8.1)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.4.1)
+      parser (>= 2.7.1.5)
+    ruby-progressbar (1.11.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
+    unicode-display_width (2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  microfsm!
+  minitest
+  observr
+  rake
+  rubocop
+  simplecov
+
+BUNDLED WITH
+   2.1.4

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2021 Dittmar Krall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# MicroFSM
+
+MicroFSM implements a minimal/simple Finite-State Machine (FSM).
+Transitions are triggered by events.
+Actions for a transition can be added as callbacks.
+
+Finite-State Machine are described elsewhere, e.g. Wikipedia.
+
+Several FSM implementations are available for Ruby.
+Please feel free to use any of them if they fit better to your work.
+
+The MicroFSM code consists of less than 70 locs.
+No magic, no niceties, just an implementation using Ruby hashes.
+
+Check the examples directory for more information.
+
+
+## Installation
+
+~~~~
+# Gemfile
+gem "wysiwyg-rails"
+
+$ bundle install.
+
+# or manually
+
+$ [sudo] gem install microfsm
+~~~~
+
+## Usage
+
+~~~~
+require 'microfsm'
+
+fsm = MicroFSM.new(:new) # Initial state.
+
+# Define the possible transitions for each event.
+fsm.when(:confirm, :new => :confirmed)
+fsm.when(:ignore, :new => :ignored)
+fsm.when(:reset, :confirmed => :new, :ignored => :new)
+
+fsm.trigger(:confirm)  #=> true
+fsm.state              #=> :confirmed
+
+fsm.trigger(:ignore)   #=> false
+fsm.state              #=> :confirmed
+
+fsm.trigger(:reset)    #=> true
+fsm.state              #=> :new
+
+fsm.trigger(:ignore)   #=> true
+fsm.state              #=> :ignored
+~~~~
+
+You can also ask if an event will trigger a change in state. Following
+the example above:
+
+~~~~
+fsm.state              #=> :ignored
+
+fsm.trigger?(:ignore)  #=> false
+fsm.trigger?(:reset)   #=> true
+
+# And the state is preserved, because you were only asking.
+fsm.state              #=> :ignored
+~~~~
+
+
+Finally, you can list possible events or states:
+
+~~~~
+# All possible events
+fsm.events #=> [:confirm, :ignore, :reset]
+
+# All events triggerable from the current state
+fsm.triggerable_events #=> [:confirm, :ignore]
+
+# All possible states
+fsm.states #=> [:new, :confirmed, :ignored]
+~~~~
+
+Check the examples directory for more information.
+
+## Links
+
+- [Wikipedia](https://en.wikipedia.org/wiki/Finite-state_machine)
+- [micromachine](https://github.com/soveran/micromachine)

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'test'
+  t.pattern = 'test/*_test.rb'
+end
+
+desc 'Default: run unit tests.'
+task :default => :test

data/examples/advanced.rb

@@ -0,0 +1,21 @@
+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)
+
+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, pending"
+puts fsm.states.join ", "
+
+puts "Should print all events: confirm, ignore, reset"
+puts fsm.events.join ", "

data/examples/basic.rb

@@ -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

@@ -0,0 +1,16 @@
+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) {
+          puts "Reset"
+        }
+
+puts "Should print Confirmed, Reset and Ignored:"
+fsm.trigger(:confirm)
+fsm.trigger(:ignore)
+fsm.trigger(:reset)
+fsm.trigger(:ignore)

data/lib/microfsm.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class MicroFSM
+  InvalidEvent = Class.new(NoMethodError)
+  InvalidState = Class.new(ArgumentError)
+  InvalidTransition = Class.new(ArgumentError)
+
+  attr_reader :state
+
+  def initialize(initial_state)
+    @state = initial_state
+    @transitions_for = {}
+    @callbacks_for = {}
+  end
+
+  def when(event, transitions, &block)
+    @transitions_for[event] ||= {}
+    @callbacks_for[event] ||= {}
+
+    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_given?
+    end
+    self
+  end
+
+  def trigger(event)
+    trigger?(event) and transit(event)
+  end
+
+  def trigger!(event)
+    trigger(event) or
+      raise InvalidState.new("Event '#{event}' not valid from state '#{@state}'")
+  end
+
+  def trigger?(event)
+    raise InvalidEvent 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)
+    callbacks = @callbacks_for[event][@state]
+    @state = @transitions_for[event][@state]
+    callbacks.each { |callback| callback.call(event) }
+    true
+  end
+end

data/lib/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class MicroFSM
+  VERSION = '0.0.1'     # 2021-01-24
+end

data/microfsm.gemspec

@@ -0,0 +1,20 @@
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'version'
+
+Gem::Specification.new do |s|
+  s.name = "microfsm"
+  s.version = MicroFSM::VERSION
+  s.summary = %{Minimal Finite State Machine.}
+#  s.description = %Q{There are many finite state machine implementations for Ruby, and they all provide a nice DSL for declaring events, exceptions, callbacks, and all kinds of niceties in general.\n\nBut if all you want is a finite state machine, look no further: this has less than 50 lines of code and provides everything a finite state machine must have, and nothing more.}
+  s.authors  = ['Dittmar Krall']
+  s.email    = 'dittmar.krall@matique.de'
+  s.homepage = 'http://www.matique.de'
+  s.license = "MIT"
+
+  s.files = `git ls-files`.split("\n")
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'rake'
+
+  s.add_development_dependency 'minitest'
+end

data/test/callbacks_test.rb

@@ -0,0 +1,35 @@
+require 'test_helper'
+
+describe MicroFSM do
+  let (:fsm) {
+    MicroFSM.new(:pending)
+            .when(:confirm, pending: :confirmed) { @state = "Confirmed" }
+            .when(:reset, confirmed: :pending) { @state = "Pending" }
+  }
+
+  def test_executes_callbacks_during_transition
+    fsm.trigger(:confirm)
+    assert_equal "Confirmed", @state
+
+    fsm.trigger(:reset)
+    assert_equal "Pending", @state
+  end
+
+  def test_two_callbacks_during_transition
+    fsm.when(:confirm, pending: :confirmed) { @state2 = "Confirmed2" }
+
+    fsm.trigger(:confirm)
+    assert_equal "Confirmed", @state
+    assert_equal "Confirmed2", @state2
+  end
+
+  def test_passing_the_event_name_to_the_callbacks
+    event_name = nil
+    fsm.when(:confirm, pending: :confirmed) do |event|
+      event_name = event
+    end
+
+    fsm.trigger(:confirm)
+    assert_equal :confirm, event_name
+  end
+end

data/test/introspection_test.rb

@@ -0,0 +1,22 @@
+require 'test_helper'
+
+describe MicroFSM do
+  let (:fsm) {
+    MicroFSM.new(:pending)
+            .when(:confirm, pending: :confirmed)
+            .when(:ignore, pending: :ignored)
+            .when(:reset, confirmed: :pending, ignored: :pending)
+  }
+
+  def test_returns_an_array_with_the_defined_events
+    assert_equal %i[confirm ignore reset], fsm.events
+  end
+
+  def test_list_the_available_events_for_the_current_state
+    assert_equal %i[confirm ignore], fsm.triggerable_events
+  end
+
+  def test_returns_an_array_with_the_defined_states
+    assert_equal %i[confirmed ignored pending], fsm.states
+  end
+end

data/test/microfsm_test.rb

@@ -0,0 +1,65 @@
+require 'test_helper'
+
+describe MicroFSM do
+  let (:fsm) {
+    MicroFSM.new(:pending)
+            .when(:confirm, pending: :confirmed)
+            .when(:ignore, pending: :ignored)
+            .when(:reset, confirmed: :pending, ignored: :pending)
+  }
+
+  def test_class
+    assert_kind_of MicroFSM, fsm
+  end
+
+  def test_defines_initial_state
+    assert_equal :pending, fsm.state
+  end
+
+  def test_changes_the_state
+    assert fsm.trigger?(:confirm)
+    assert fsm.trigger(:confirm)
+    assert_equal :confirmed, fsm.state
+  end
+
+  def test_preserves_the_state_if_transition_is_not_possible
+    refute fsm.trigger?(:reset)
+    refute fsm.trigger(:reset)
+    assert_equal :pending, fsm.state
+  end
+
+  def test_multiple_transitions
+    fsm.trigger(:confirm)
+    assert_equal :confirmed, fsm.state
+
+    fsm.trigger(:reset)
+    assert_equal :pending, fsm.state
+
+    fsm.trigger(:ignore)
+    assert_equal :ignored, fsm.state
+
+    fsm.trigger(:reset)
+    assert_equal :pending, fsm.state
+  end
+
+  def test_raises_an_error_if_an_invalid_event_is_triggered
+    assert_raises(MicroFSM::InvalidEvent) do
+      fsm.trigger(:random_event)
+    end
+  end
+
+  def test_raises_error_if_trigger_from_incompatible_state
+    assert_raises(MicroFSM::InvalidState) do
+      fsm.trigger!(:reset)
+    end
+  end
+
+  def test_raises_an_error_if_a_transition_is_overwritten
+    fsm = MicroFSM.new(:init)
+
+    fsm.when(:trigger, init: :started)
+    assert_raises(MicroFSM::InvalidTransition) do
+      fsm.when(:trigger, init: :wrong)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+if ENV['COVERAGE']
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter 'test'
+    command_name 'Minitest'
+  end
+end
+
+require 'minitest/autorun'
+
+require 'microfsm'

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: microfsm
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dittmar Krall
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-01-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: dittmar.krall@matique.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".watchr"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- examples/advanced.rb
+- examples/basic.rb
+- examples/callbacks.rb
+- lib/microfsm.rb
+- lib/version.rb
+- microfsm.gemspec
+- test/callbacks_test.rb
+- test/introspection_test.rb
+- test/microfsm_test.rb
+- test/test_helper.rb
+homepage: http://www.matique.de
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key: 
+specification_version: 4
+summary: Minimal Finite State Machine.
+test_files: []