kotoshu 0.3.0

data/lib/kotoshu/core/trie/builder.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Core
+    module Trie
+      # Builder class for constructing Trie objects.
+      # Provides a fluent interface for building tries from various sources.
+      class Builder
+        def initialize
+          @trie = Trie.new
+        end
+
+        # Add a single word to the trie.
+        #
+        # @param word [String] The word to add
+        # @param payload [Object] Optional payload
+        # @return [Builder] Self for chaining
+        def add_word(word, payload = nil)
+          @trie.insert(word, payload)
+          self
+        end
+        alias << add_word
+
+        # Add multiple words to the trie.
+        #
+        # @param words [Array<String>] Array of words to add
+        # @return [Builder] Self for chaining
+        def add_words(words)
+          words.each { |word| add_word(word) }
+          self
+        end
+
+        # Build a trie from a hash (word => payload mapping).
+        #
+        # @param hash [Hash] Hash of words to payloads
+        # @return [Builder] Self for chaining
+        def from_hash(hash)
+          hash.each { |word, payload| add_word(word, payload) }
+          self
+        end
+
+        # Build a trie from an array of words.
+        #
+        # @param array [Array<String>] Array of words
+        # @return [Builder] Self for chaining
+        def from_array(array)
+          add_words(array)
+          self
+        end
+
+        # Build a trie from a file (one word per line).
+        #
+        # @param path [String] Path to the file
+        # @return [Builder] Self for chaining
+        def from_file(path)
+          File.foreach(path, chomp: true) do |line|
+            next if line.empty? || line.start_with?("#")
+
+            add_word(line)
+          end
+          self
+        end
+
+        # Build a trie from a string (newline-separated words).
+        #
+        # @param text [String] String containing words
+        # @return [Builder] Self for chaining
+        def from_string(text)
+          text.each_line do |line|
+            word = line.strip
+            next if word.empty? || word.start_with?("#")
+
+            add_word(word)
+          end
+          self
+        end
+
+        # Get the built trie.
+        #
+        # @return [Trie] The constructed trie
+        def build
+          @trie.freeze
+        end
+
+        # Build a trie from a file path (class method).
+        #
+        # @param path [String] Path to the file
+        # @return [Trie] The constructed trie
+        def self.from_file(path)
+          new.from_file(path).build
+        end
+
+        # Build a trie from an array of words (class method).
+        #
+        # @param words [Array<String>] Array of words
+        # @return [Trie] The constructed trie
+        def self.from_array(words)
+          new.from_array(words).build
+        end
+
+        # Build a trie from a hash (class method).
+        #
+        # @param hash [Hash] Hash of words to payloads
+        # @return [Trie] The constructed trie
+        def self.from_hash(hash)
+          new.from_hash(hash).build
+        end
+
+        # Build a trie from a string (class method).
+        #
+        # @param text [String] String containing words
+        # @return [Trie] The constructed trie
+        def self.from_string(text)
+          new.from_string(text).build
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/core/trie/node.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Core
+    module Trie
+      # Node in the Trie data structure.
+      # Each node represents a character and its children.
+      class Node
+        attr_reader :character, :children, :terminal, :payload
+
+        def initialize(character = "")
+          @character = character
+          @children = {}
+          @terminal = false
+          @payload = nil
+        end
+
+        # Add a child node for the given character.
+        #
+        # @param character [String] The character to add
+        # @return [Node] The new or existing child node
+        def add_child(character)
+          @children[character] ||= Node.new(character)
+        end
+
+        # Get child node for the given character.
+        #
+        # @param character [String] The character to look up
+        # @return [Node, nil] The child node or nil if not found
+        def child(character)
+          @children[character]
+        end
+
+        # Check if this node has a child for the given character.
+        #
+        # @param character [String] The character to check
+        # @return [Boolean] True if child exists
+        def has_child?(character)
+          @children.key?(character)
+        end
+
+        # Mark this node as terminal (end of a word).
+        #
+        # @param payload [Object] Optional payload to store at this node
+        def mark_terminal(payload = nil)
+          @terminal = true
+          @payload = payload
+        end
+
+        # Check if this node is terminal.
+        #
+        # @return [Boolean] True if this is the end of a word
+        def terminal?
+          @terminal
+        end
+
+        # Get all children of this node.
+        #
+        # @return [Hash] Hash of character to node mappings
+        def all_children
+          @children
+        end
+
+        # Check if this node has any children.
+        #
+        # @return [Boolean] True if there are children
+        def has_children?
+          !@children.empty?
+        end
+
+        # Get the number of children.
+        #
+        # @return [Integer] Number of child nodes
+        def child_count
+          @children.size
+        end
+
+        # Convert node to string representation.
+        #
+        # @return [String] String representation
+        def to_s
+          "Node('#{@character}', terminal: #{@terminal}, children: #{@children.keys})"
+        end
+
+        # Inspect the node.
+        #
+        # @return [String] Inspection string
+        def inspect
+          to_s
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/core/trie/trie.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Core
+    module Trie
+      # Trie (prefix tree) data structure for efficient word storage and lookup.
+      # Supports prefix matching, word validation, and traversal.
+      class Trie
+        attr_reader :root, :size
+
+        def initialize
+          @root = Node.new
+          @size = 0
+        end
+
+        # Insert a word into the trie.
+        #
+        # @param word [String] The word to insert
+        # @param payload [Object] Optional payload to store with the word
+        # @return [Trie] Self for chaining
+        def insert(word, payload = nil)
+          node = @root
+          word.each_char do |char|
+            node = node.add_child(char)
+          end
+
+          # Only increment size if this is a new word
+          @size += 1 unless node.terminal?
+          node.mark_terminal(payload)
+
+          self
+        end
+
+        # Check if a word exists in the trie.
+        #
+        # @param word [String] The word to look up
+        # @return [Boolean] True if the word exists
+        def lookup(word)
+          node = find_node(word)
+          !node.nil? && node.terminal?
+        end
+        alias has_word? lookup
+        alias contains? lookup
+
+        # Check if any words in the trie start with the given prefix.
+        #
+        # @param prefix [String] The prefix to check
+        # @return [Boolean] True if any words have this prefix
+        def has_prefix?(prefix)
+          !find_node(prefix).nil?
+        end
+
+        # Get the node for a given word/prefix.
+        #
+        # @param word [String] The word or prefix to find
+        # @return [Node, nil] The node or nil if not found
+        def find_node(word)
+          node = @root
+          word.each_char do |char|
+            return nil unless node.has_child?(char)
+
+            node = node.child(char)
+          end
+          node
+        end
+
+        # Get all words with the given prefix.
+        #
+        # @param prefix [String] The prefix to match
+        # @return [Array<String>] Array of words with the prefix
+        def words_with_prefix(prefix)
+          start_node = find_node(prefix)
+          return [] if start_node.nil?
+
+          words = []
+          collect_words(start_node, prefix, words)
+          words
+        end
+
+        # Get all words in the trie.
+        #
+        # @return [Array<String>] Array of all words
+        def all_words
+          words = []
+          collect_words(@root, "", words)
+          words
+        end
+
+        # Count words with the given prefix.
+        #
+        # @param prefix [String] The prefix to count
+        # @return [Integer] Number of words with the prefix
+        def count_prefix(prefix)
+          words_with_prefix(prefix).size
+        end
+
+        # Get suggestions for a word based on prefix matching.
+        # Returns words that share the longest common prefix.
+        #
+        # @param word [String] The word to get suggestions for
+        # @param max_results [Integer] Maximum number of results
+        # @return [Array<String>] Array of suggested words
+        def suggestions(word, max_results: 10)
+          # Find the longest matching prefix
+          node = @root
+          i = 0
+
+          while i < word.length && node.has_child?(word[i])
+            node = node.child(word[i])
+            i += 1
+          end
+
+          # Collect all completions from this point
+          words = []
+          collect_words_limited(node, word[0...i], words, max_results)
+          words
+        end
+
+        # Iterate over all words in the trie.
+        #
+        # @yield [word, payload] Each word and its optional payload
+        # @return [Enumerator] Enumerator if no block given
+        def each_word
+          return enum_for(:each_word) unless block_given?
+
+          traverse(@root, "") do |word, node|
+            yield word, node.payload if node.terminal?
+          end
+
+          self
+        end
+
+        # Traverse the trie with a visitor.
+        #
+        # @yield [prefix, node] Each prefix and node visited
+        # @return [Trie] Self for chaining
+        def traverse(node = @root, prefix = "", &block)
+          return enum_for(:traverse, node, prefix) unless block_given?
+
+          yield prefix, node
+
+          node.all_children.each_value do |child|
+            traverse(child, prefix + child.character, &block)
+          end
+
+          self
+        end
+
+        # Check if the trie is empty.
+        #
+        # @return [Boolean] True if trie has no words
+        def empty?
+          @size.zero?
+        end
+
+        # Clear all words from the trie.
+        #
+        # @return [Trie] Self for chaining
+        def clear
+          @root = Node.new
+          @size = 0
+          self
+        end
+
+        # Merge another trie into this one.
+        #
+        # @param other [Trie] The trie to merge
+        # @return [Trie] Self for chaining
+        def merge!(other)
+          other.each_word do |word, payload|
+            insert(word, payload)
+          end
+          self
+        end
+
+        # Create a new trie with common words from two tries.
+        #
+        # @param other [Trie] The other trie
+        # @return [Trie] New trie with common words
+        def &(other)
+          result = Trie.new
+          each_word do |word, _payload|
+            result.insert(word) if other.lookup(word)
+          end
+          result
+        end
+
+        # Create a new trie with words from either trie.
+        #
+        # @param other [Trie] The other trie
+        # @return [Trie] New trie with all words
+        def |(other)
+          result = Trie.new
+          each_word { |word, payload| result.insert(word, payload) }
+          other.each_word { |word, payload| result.insert(word, payload) }
+          result
+        end
+
+        # Convert trie to string representation.
+        #
+        # @return [String] String representation
+        def to_s
+          "Trie(size: #{@size})"
+        end
+
+        # Inspect the trie.
+        #
+        # @return [String] Inspection string
+        def inspect
+          to_s
+        end
+
+        private
+
+        # Collect all words from a given node.
+        #
+        # @param node [Node] The starting node
+        # @param prefix [String] The current prefix
+        # @param words [Array] Array to collect words into
+        def collect_words(node, prefix, words)
+          words << prefix if node.terminal?
+
+          node.all_children.each do |char, child|
+            collect_words(child, prefix + char, words)
+          end
+        end
+
+        # Collect words with a limit.
+        #
+        # @param node [Node] The starting node
+        # @param prefix [String] The current prefix
+        # @param words [Array] Array to collect words into
+        # @param limit [Integer] Maximum number of words to collect
+        def collect_words_limited(node, prefix, words, limit)
+          return if words.size >= limit
+
+          words << prefix if node.terminal?
+
+          return if words.size >= limit
+
+          node.all_children.each_value do |child|
+            collect_words_limited(child, prefix + child.character, words, limit)
+            break if words.size >= limit
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/core.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  # Core domain models and infrastructure.
+  #
+  # This module contains the fundamental domain models for the spell checker:
+  # - IndexedDictionary: Fast word lookup with multiple indexes
+  # - Trie: Prefix tree data structure for efficient string operations
+  # - Models: Value objects and result types
+  #
+  # @example Creating an indexed dictionary
+  #   dict = Kotoshu::Core::IndexedDictionary.new(%w[hello world test])
+  #   dict.include?("hello")  # => true
+  #
+  # @example Creating a trie
+  #   trie = Kotoshu::Core::Trie::Trie.new
+  #   trie.insert("hello")
+  #   trie.lookup("hello")  # => true
+  module Core
+  end
+end
+
+# Require core submodules
+require_relative "core/exceptions"
+require_relative "core/indexed_dictionary"
+require_relative "core/trie/trie"
+require_relative "core/trie/builder"
+require_relative "core/trie/node"