lernen 0.2.0 → 0.3.0

data/lib/lernen/graph.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  # Graph represents a labelled directed graph.
+  #
+  # This is an intermediate data structure for rendering Mermaid and Graphviz diagrams.
+  class Graph
+    # @rbs!
+    #   type node_shape = :circle | :doublecircle
+    #
+    #   type mermaid_direction = "TD" | "DT" | "LR" | "RL"
+
+    # Node represents a node of graphs.
+    #
+    # @rbs skip
+    Node = Data.define(:label, :shape)
+
+    # @rbs!
+    #   class Node < Data
+    #     attr_reader label: String
+    #     attr_reader shape: node_shape
+    #     def self.[]: (String label, node_shape shape) -> Node
+    #   end
+
+    # Edge represents an edge of graphs.
+    #
+    # @rbs skip
+    Edge = Data.define(:from, :label, :to)
+
+    # @rbs!
+    #   class Edge < Data
+    #     attr_reader from: Integer
+    #     attr_reader label: String
+    #     attr_reader to: Integer
+    #     def self.[]: (Integer from, String label, Integer to) -> Edge
+    #   end
+
+    # SubGraph represents a sub-graph of graphs.
+    #
+    # @rbs skip
+    SubGraph = Data.define(:label, :graph)
+
+    # @rbs!
+    #   class SubGraph < Data
+    #     attr_reader label: String
+    #     attr_reader graph: Graph
+    #     def self.[]: (String label, Graph graph) -> SubGraph
+    #   end
+
+    # Returns the escaped string for Mermaid diagrams.
+    #
+    # See https://mermaid.js.org/syntax/flowchart.html#entity-codes-to-escape-characters.
+    #
+    #: (String label) -> String
+    def self.mermaid_escape(label)
+      label =
+        label.gsub(/[#"]/) do |c|
+          case c
+          in "#"
+            "#35;"
+          in "\""
+            "#quot;"
+          end
+        end
+      "\"#{label}\""
+    end
+
+    # Returns the escaped string for GraphViz DOTs.
+    #
+    # See https://graphviz.org/docs/attr-types/escString/.
+    #
+    #: (String label) -> String
+    def self.dot_escape(label)
+      label =
+        label.gsub(/[\\"]/) do |c|
+          case c
+          in "\\"
+            "\\\\"
+          in "\""
+            "\\\""
+          end
+        end
+      "\"#{label}\""
+    end
+
+    # @rbs @nodes: Hash[Integer, Node]
+    # @rbs @edges: Array[Edge]
+    # @rbs @subgraphs: Array[SubGraph]
+
+    #: (
+    #    Hash[Integer, Node] nodes,
+    #    Array[Edge] edges,
+    #    ?Array[SubGraph] subgraphs
+    #  ) -> void
+    def initialize(nodes, edges, subgraphs = [])
+      @nodes = nodes
+      @edges = edges
+      @subgraphs = subgraphs
+    end
+
+    attr_reader :nodes #: Hash[Integer, Node]
+    attr_reader :edges #: Array[Edge]
+    attr_reader :subgraphs #: Array[SubGraph]
+
+    # Returns a [Mermaid](https://mermaid.js.org) diagram of this graph.
+    #
+    #: (?direction: mermaid_direction) -> String
+    def to_mermaid(direction: "TD")
+      mmd = +""
+
+      mmd << "flowchart #{direction}\n"
+      mmd << to_mermaid_internal
+
+      mmd.freeze
+    end
+
+    # Returns a [GraphViz](https://graphviz.org) DOT diagram of this graph.
+    #
+    #: () -> String
+    def to_dot
+      dot = +""
+
+      dot << "digraph {\n"
+      dot << to_dot_internal
+      dot << "}\n"
+
+      dot.freeze
+    end
+
+    protected
+
+    #: (?String id_prefix) -> String
+    def to_mermaid_internal(id_prefix = "")
+      mmd = +""
+      needs_sep = false
+
+      nodes.each do |id, node|
+        needs_sep = true
+
+        node_def =
+          case node.shape
+          in :circle
+            "((#{Graph.mermaid_escape(node.label)}))"
+          in :doublecircle
+            "(((#{Graph.mermaid_escape(node.label)})))"
+          end
+        mmd << "  #{id_prefix}#{id}#{node_def}\n"
+      end
+      mmd << "\n" if needs_sep
+
+      edges.each do |edge|
+        needs_sep = true
+
+        from = "#{id_prefix}#{edge.from}"
+        to = "#{id_prefix}#{edge.to}"
+        mmd << "  #{from} -- #{Graph.mermaid_escape(edge.label)} --> #{to}\n"
+      end
+
+      subgraphs.each_with_index do |subgraph, index|
+        mmd << "\n" if needs_sep
+        needs_sep = true
+
+        subgraph_id = "#{id_prefix}g#{index}"
+        mmd << "  subgraph #{subgraph_id}[#{Graph.mermaid_escape(subgraph.label)}]\n"
+        subgraph
+          .graph
+          .to_mermaid_internal("#{subgraph_id}_")
+          .lines
+          .each { |line| mmd << (line == "\n" ? line : "  #{line}") }
+        mmd << "  end\n"
+      end
+
+      mmd.freeze
+    end
+
+    #: (?String id_prefix) -> String
+    def to_dot_internal(id_prefix = "")
+      dot = +""
+      needs_sep = false
+
+      nodes.each do |index, node|
+        needs_sep = true
+
+        dot << "  #{id_prefix}#{index} [label=#{Graph.dot_escape(node.label)}, shape=#{node.shape}];\n"
+      end
+      dot << "\n" if needs_sep
+
+      edges.each do |edge|
+        needs_sep = true
+
+        from = "#{id_prefix}#{edge.from}"
+        to = "#{id_prefix}#{edge.to}"
+        dot << "  #{from} -> #{to} [label=#{Graph.dot_escape(edge.label)}];\n"
+      end
+
+      subgraphs.each_with_index do |subgraph, index|
+        dot << "\n" if needs_sep
+        needs_sep = true
+
+        subgraph_id = "#{id_prefix}g#{index}"
+        dot << "  subgraph cluster_#{subgraph_id} {\n"
+        dot << "    label=#{Graph.dot_escape(subgraph.label)};\n"
+        subgraph
+          .graph
+          .to_dot_internal("#{subgraph_id}_")
+          .lines
+          .each { |line| dot << (line == "\n" ? line : "  #{line}") }
+        dot << "  }\n"
+      end
+
+      dot.freeze
+    end
+  end
+end

data/lib/lernen/system/block_sul.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  module System
+    # BlockSUL is a system under learning (SUL) constructed from a block.
+    #
+    # A block is expected to behave like a membership query.
+    #
+    # @rbs generic In  -- Type for input alphabet
+    # @rbs generic Out -- Type for output values
+    class BlockSUL < MooreLikeSUL #[In, Out]
+      # @rbs @block: ^(Array[In]) -> Out
+      # @rbs @word: Array[In]
+
+      #: (?cache: bool) { (Array[In]) -> Out } -> void
+      def initialize(cache: true, &block)
+        super(cache:)
+
+        @block = block
+        @word = []
+      end
+
+      # @rbs override
+      def setup
+        @word = []
+      end
+
+      # @rbs override
+      def step(input)
+        @word << input
+        @block.call(@word)
+      end
+
+      # @rbs override
+      def query_empty
+        @block.call([])
+      end
+    end
+  end
+end

data/lib/lernen/system/moore_like_simulator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  module System
+    # MooreLikeSimulator is a system under learning (SUL) using a Moore-like machine simulation.
+    #
+    # @rbs generic Conf -- Type for a configuration of this automaton
+    # @rbs generic In   -- Type for input alphabet
+    # @rbs generic Out  -- Type for output values
+    class MooreLikeSimulator < MooreLikeSUL #[In, Out]
+      # @rbs @automaton: Automaton::MooreLike[Conf, In, Out]
+      # @rbs @current_conf: Conf | nil
+
+      #: (Automaton::MooreLike[Conf, In, Out] automaton, ?cache: bool) -> void
+      def initialize(automaton, cache: true)
+        super(cache:)
+
+        @automaton = automaton
+        @current_conf = nil
+      end
+
+      # @rbs override
+      def setup
+        @current_conf = @automaton.initial_conf
+      end
+
+      # @rbs override
+      def shutdown
+        @current_conf = nil
+      end
+
+      # @rbs override
+      def step(input)
+        output, @current_conf = @automaton.step(@current_conf, input) # steep:ignore
+        output
+      end
+
+      # @rbs override
+      def query_empty
+        @automaton.run_empty
+      end
+    end
+  end
+end

data/lib/lernen/system/moore_like_sul.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  module System
+    # MooreLikeSUL is a system under learning (SUL) for a system much like Moore machine.
+    #
+    # By contrast to `SUL`, this accepts a query with the empty string additionally.
+    #
+    # Note that this class is *abstract*. You should implement the following method:
+    #
+    # - `#step(input)`
+    # - `#query_empty`
+    #
+    # @rbs generic In  -- Type for input alphabet
+    # @rbs generic Out -- Type for output values
+    class MooreLikeSUL < SUL #[In, Out]
+      #: (?cache: bool) -> void
+      def initialize(cache: true)
+        super
+      end
+
+      # Runs a membership query with the empty input.
+      #
+      # This is an abstract method.
+      #
+      #: () -> Out
+      def query_empty
+        raise TypeError, "abstract method: `query_empty`"
+      end
+    end
+  end
+end

data/lib/lernen/system/sul.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  module System
+    # SUL represents a system under learning.
+    #
+    # It is an abtraction of a system under learning (SUL) which accepts an operation
+    # called "membership query"; it takes an input string (word) and returns a sequence
+    # of outputs corresponding to the input string.
+    #
+    # This SUL assumes the system is much like Mealy machine; that is, a transition puts
+    # an output, and query does not accept the empty string due to no outputs.
+    #
+    # This SUL also implements cache mechanism. The cache mechanism is enabled by the default,
+    # and it can be disabled by specifying `cache: false`.
+    #
+    # On running a SUL, this SUL records the statistics information. We can obtain this
+    # information by `SUL#stats`.
+    #
+    # Note that this class is *abstract*. You should implement the following method:
+    #
+    # - `#step(input)`
+    #
+    # @rbs generic In  -- Type for input alphabet
+    # @rbs generic Out -- Type for output values
+    class SUL
+      # @rbs @cache: Hash[Array[In], Array[Out]] | nil
+      # @rbs @num_cached_queries: Integer
+      # @rbs @num_queries: Integer
+      # @rbs @num_steps: Integer
+
+      #: (?cache: bool) -> void
+      def initialize(cache: true)
+        @cache = cache ? {} : nil
+        @num_cached_queries = 0
+        @num_queries = 0
+        @num_steps = 0
+      end
+
+      # Returns the statistics information as a `Hash` object.
+      #
+      # The result hash contains the following values.
+      #
+      # - `num_cache`: The number of cached queries.
+      # - `num_cached_queries`: The number of queries uses the cache.
+      # - `num_queries`: The number of (non-cached) queries.
+      # - `num_steps`: The total number of steps.
+      #
+      #: () -> Hash[Symbol, Integer]
+      def stats
+        {
+          num_cache: @cache&.size || 0,
+          num_cached_queries: @num_cached_queries,
+          num_queries: @num_queries,
+          num_steps: @num_steps
+        }
+      end
+
+      # Runs a membership query with the given word.
+      #
+      # Note that this method does not accept the empty string due to no outpus.
+      # If you need to call `query` with the empty string, you should use `MooreSUL#query_empty` instead.
+      #
+      #: (Array[In] word) -> Array[Out]
+      def query(word)
+        cached = (cache = @cache) && cache[word]
+        if cached
+          @num_cached_queries += 1
+          return cached
+        end
+
+        if word.empty?
+          raise ArgumentError, "`query` does not accept the empty string. Please use `query_empty` instead."
+        end
+
+        setup
+        outputs = word.map { |input| step(input) }
+        shutdown
+
+        @num_queries += 1
+        @num_steps += word.size
+
+        cache[word.dup] = outputs if cache
+
+        outputs
+      end
+
+      # Runs a membership query with the given word, and returns the last output.
+      #
+      # It is the same as `query(word).last`.
+      #
+      #: (Array[In] word) -> Out
+      def query_last(word) = query(word).last # steep:ignore
+
+      # rubocop:disable Lint/UnusedMethodArgument
+
+      # It is a setup procedure of this SUL.
+      #
+      # Note that it does nothing by default.
+      #
+      #: () -> void
+      def setup
+      end
+
+      # It is a shutdown procedure of this SUL.
+      #
+      # Note that it does nothing by default.
+      #
+      #: () -> void
+      def shutdown
+      end
+
+      # Consumes the given `input` and returns the correspoding output.
+      #
+      # This is an abstract method.
+      #
+      #: (In input) -> Out
+      def step(input)
+        raise TypeError, "abstract method: `step`"
+      end
+
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/lernen/system/transition_system_simulator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  module System
+    # TransitionSystemSimulator is a system under learning (SUL) using a transition system simulation.
+    #
+    # @rbs generic Conf -- Type for a configuration of this automaton
+    # @rbs generic In   -- Type for input alphabet
+    # @rbs generic Out  -- Type for output values
+    class TransitionSystemSimulator < SUL #[In, Out]
+      # @rbs @automaton: Automaton::TransitionSystem[Conf, In, Out]
+      # @rbs @current_conf: Conf | nil
+
+      #: (Automaton::TransitionSystem[Conf, In, Out] automaton, ?cache: bool) -> void
+      def initialize(automaton, cache: true)
+        super(cache:)
+
+        @automaton = automaton
+        @current_conf = nil
+      end
+
+      # @rbs override
+      def setup
+        @current_conf = @automaton.initial_conf
+      end
+
+      # @rbs override
+      def shutdown
+        @current_conf = nil
+      end
+
+      # @rbs override
+      def step(input)
+        output, @current_conf = @automaton.step(@current_conf, input) # steep:ignore
+        output
+      end
+    end
+  end
+end

data/lib/lernen/system.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Lernen
+  # This is a namespace for systems under learning (SULs).
+  #
+  # `SUL` is an implementation of membership (or output) query.
+  #
+  # There are two base abstract classes of SULs: `SUL` and `MooreLikeSUL`
+  # `SUL` is the most base abstract class of SULs and it cannot answer a query
+  # with the empty string. `MooreLikeSUL` is subclass of `SUL` and it can answer
+  # the empty string query.
+  #
+  # In this library, we provide two easy ways to create a SUL. The first way is
+  # `System.from_block`. This method takes a block, and the block is used as
+  # a membership query implementation.
+  #
+  # ```ruby
+  # sul = Lernen::System.from_block do |word|
+  #   word.count("1") % 4 == 3
+  # end
+  # ```
+  #
+  # The another way is `System.from_automaton`. This method takes an automaton
+  # (a transition system), and the result SUL simulates this automaton.
+  #
+  # ```ruby
+  # dfa = Lernen::Automaton::DFA.new(
+  #   0,
+  #   Set[1],
+  #   {
+  #     [0, '0'] => 0,
+  #     [0, '1'] => 1,
+  #     [1, '0'] => 1,
+  #     [1, '1'] => 1,
+  #   }
+  # )
+  #
+  # sul = Lernen::System.from_automaton(dfa)
+  # ```
+  module System
+    # Creates a SUL from the given block as an implementation of a membership query.
+    #
+    #: [In, Out] (?cache: bool) { (Array[In]) -> Out } -> MooreLikeSUL[In, Out]
+    def self.from_block(cache: true, &) = BlockSUL.new(cache:, &)
+
+    # Creates a SUL from the given automaton as an implementation.
+    #
+    # This method chooses a suitable SUL implementation, which is one of `TransitionSystemSimulator`
+    # or `MooreLikeSimulator`, for the given automaton.
+    #
+    #: [In] (Automaton::DFA[In] automaton, ?cache: bool) -> SUL[In, bool]
+    #: [In, Out] (Automaton::Mealy[In, Out] automaton, ?cache: bool) -> SUL[In, Out]
+    #: [In, Out] (Automaton::Moore[In, Out] automaton, ?cache: bool) -> SUL[In, Out]
+    #: [In, Call, Return] (Automaton::VPA[In, Call, Return] automaton, ?cache: bool) -> SUL[In | Call | Return, bool]
+    #: [In, Call, Return] (Automaton::SPA[In, Call, Return] automaton, ?cache: bool) -> SUL[In | Call | Return, bool]
+    def self.from_automaton(automaton, cache: true) =
+      case automaton.type
+      in :dfa | :moore | :vpa | :spa
+        MooreLikeSimulator.new(automaton, cache:)
+      in :mealy
+        TransitionSystemSimulator.new(automaton, cache:)
+      end
+  end
+end
+
+require "lernen/system/sul"
+require "lernen/system/moore_like_sul"
+
+require "lernen/system/block_sul"
+require "lernen/system/transition_system_simulator"
+require "lernen/system/moore_like_simulator"

data/lib/lernen/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Lernen
   # The version string.
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end