mealy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a060d9e9e21e6a51b0116e42b315e0a488b8ea18a6ca8571e3162671123186c
+  data.tar.gz: 00e93453f2f5b13a7d568962c1f604f31ad32099c45b540191e5e93f3bf47b42
+SHA512:
+  metadata.gz: 1c8aec8689484fbeba152dd3a2b8f4c7db439a8635e3a3e18e9e76b0417bf8fea7eb7cf302824443ff5a5fb0f3f5e4ac822a90a7e35e420c725d0924c13d3002
+  data.tar.gz: af39ce4307ff5962c921730392916d89408c582f56a8d22d4823f5eb49552bbba7f3301bdc4fa5a41815c6957153c509bb8fb0f63fb3e5a0023342d360f9797c

data/lib/mealy.rb

@@ -0,0 +1,43 @@
+require_relative 'mealy/dsl'
+require_relative 'mealy/label'
+require_relative 'mealy/runner'
+
+# A Mealy finite state machine.
+#
+# For usage information please read {file:README.md README}.
+module Mealy
+  # Error indicating that there is no transition from the current state with
+  # the token read.
+  class UnexpectedTokenError < StandardError
+    def initialize(state, on)
+      super("FSM error #{self.class} in state #{state.inspect} reading #{on}")
+    end
+  end
+
+  # emit tokens from the DSL blocks
+  # @param token the emitted token
+  def emit(token)
+    return unless @emit_runner
+    @emit_runner.emit(token)
+  end
+
+  # Runs the Mealy machine on the given input. Outputs a stream of tokens by
+  # yielding each emitted token to the given block.
+  # @param enum [Enumerable] the input for the FSM
+  # @return [Enumerator] if no block is given
+  # @yieldparam emit The user token emitted by {#emit}.
+  def run(enum, &block)
+    return to_enum(:run, enum) unless block_given?
+
+    @emit_runner = Runner.new(self)
+    @emit_runner.run(enum, &block)
+    @emit_runner = nil
+  end
+
+  # Runs the Mealy machine on the given input.
+  # @param enum [Enumerable] the input for the FSM
+  # @return the return value of the {Mealy::DSL#finish} block.
+  def execute(enum)
+    Executer.new(self).run(enum)
+  end
+end

data/lib/mealy/dsl.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'label'
+require_relative 'helper_methods'
+
+module Mealy
+  # The class level DSL for defining machines.
+  module DSL
+    # Declares the initial state of the FSM.
+    # @param sym [Symbol] the initial state
+    # @param block user code executed in the instance of the FSM instance on
+    #              start up
+    def initial_state(sym, &block)
+      @start_data = [sym, block]
+    end
+
+    # An FSM transition.
+    # @param from [Array|Symbol] the state or Array of states we transition
+    #             away from
+    # @param to [Symbol] the state we transition to
+    # @param on [Label] only allows this rule to trigger if the read
+    #           token matches ({HelperMethods.Label} is automatically called
+    #           on this)
+    # @param block user code executed when the rule fires
+    # @yieldparam input The read input, that matches the rules {Label}
+    # @yieldparam from The state we are transitioning away from
+    # @yieldparam to  The state we are transitioning to
+    def transition(from:, to:, on: ANY, &block)
+      hash = { HelperMethods.Label(on) => { to: to, block: block } }
+      [* from].each do |origin|
+        @transitions[origin] = @transitions[origin].merge(hash)
+      end
+    end
+
+    # An FSM loop
+    # @param state [Array|Symbol] the state or states we loop on
+    # @param on [Label] only allows this rule to trigger if the read
+    #           token matches ({HelperMethods.Label} is automatically called
+    #           on this)
+    # @param block user code executed on each iteration of the loop
+    def read(state:, on: ANY, &block)
+      [* state].each do |one_state|
+        transition(from: one_state, to: one_state, on: on, &block)
+      end
+    end
+
+    # final FSM state
+    # @param block fires on FSM shutdown
+    def finish(&block)
+      @finish_data = block
+    end
+  end
+
+  # @private
+  # Module.included hook. Resets the state transitions for a class
+  def self.included(klass)
+    klass.class_eval { @transitions = Hash.new { Hash.new({}) } }
+    klass.extend(DSL)
+  end
+end

data/lib/mealy/helper_methods.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'label'
+
+module Mealy
+  # Various helper methods
+  module HelperMethods
+    # Converts types to Labels. {Mealy::DSL#transition} calls this to convert
+    # anything to a {Label}.
+    # @return [Label]
+    def self.Label(convertee)
+      if convertee.kind_of?(Label) then convertee
+      else Label.new(convertee)
+      end
+    end
+  end
+end

data/lib/mealy/label.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Mealy
+  # FSM state transition arrow labels. In effect we match the input tokens
+  # against the labels to decide which transition to take.
+  class Label
+    # @param label Something that can be tested with input tokens
+    def initialize(label)
+      @label = label
+    end
+
+    # @param input Something that can match label
+    def match?(input)
+      @label === input
+    end
+  end
+
+  # Singleton for a Label that matches anything. See {ANY}.
+  class AnyLabel < Label
+    include Singleton
+
+    def initialize
+    end
+
+    private :initialize
+
+    # ignores any input and matches.
+    def match?(*_)
+      true
+    end
+  end
+
+  # Wildcard for machine input tokens that match anything.
+  ANY = AnyLabel.instance
+end

data/lib/mealy/runner.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Mealy
+  # @api private
+  #
+  # An object on which {#run} behaves like Mealy{Mealy#execute}. The internal state
+  # is tracked by this instance, the user state is in {Mealy}.
+  class Executer
+    # @param mealy [Mealy] mealy instance
+    def initialize(mealy)
+      @mealy = mealy
+      @state = nil
+    end
+
+    # same as calling {Mealy#execute}
+    def run(enum)
+      start
+
+      enum.each { |c| run_for_token(c) }
+
+      finish
+    end
+
+    private
+
+    def start
+      @state, block = start_data
+      user_action(block)
+    end
+
+    def run_for_token(token)
+      params = lookup_transition_for(token)
+      block = params[:block]
+      from = @state
+      to = params[:to]
+      @state = to
+      user_action(block, token, from, to)
+    end
+
+    def finish
+      user_action(finish_data)
+    end
+
+    def lookup_transition_for(char)
+      on_not_found = -> { raise UnexpectedTokenError.new(@state, char) }
+      _, params = transitions[@state].find(on_not_found) do |key, _|
+        key.match?(char)
+      end
+      params
+    end
+
+    def user_action(user_action_block, *args)
+      return if user_action_block.nil?
+
+      @mealy.instance_exec(*args, &user_action_block)
+    end
+
+    %i[start_data transitions finish_data].each do |sym|
+      define_method(sym) do
+        @mealy.class.instance_variable_get(:"@#{sym}")
+      end
+    end
+  end
+
+  # @api private
+  #
+  # Extends {Executer} with emitting capabilities.
+  class Runner < Executer
+    # emit tokens from the DSL blocks
+    # @param emit the emitted token
+    def emit(emit)
+      @emit_block.call(emit)
+    end
+
+    # same as calling {Mealy#run}
+    def run(enum, &emit_block)
+      @emit_block = emit_block
+
+      super
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: mealy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Sonkoly
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-09-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: simplecov
+  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: |
+  An easy on the eye DSL to define Mealy FSMs. Can be used for lexers, stream
+  transformers etc.
+email: sonkoly.pal@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mealy.rb
+- lib/mealy/dsl.rb
+- lib/mealy/helper_methods.rb
+- lib/mealy/label.rb
+- lib/mealy/runner.rb
+homepage: http://github.com/phaul/mealy
+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: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: A ruby DSL to create mealy state machines.
+test_files: []