rambling-trie-opal 2.1.1

data/lib/rambling/trie/enumerable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Provides enumerable behavior to the trie data structure.
+    module Enumerable
+      include ::Enumerable
+
+      # Returns number of words contained in the trie
+      # @see https://ruby-doc.org/core-2.5.0/Enumerable.html#method-i-count
+      #   Enumerable#count
+      alias_method :size, :count
+
+      # Iterates over the words contained in the trie.
+      # @yield [String] the words contained in this trie node.
+      def each
+        return enum_for :each unless block_given?
+
+        yield as_word if terminal?
+
+        children_tree.each_value do |child|
+          child.each do |word|
+            yield word
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/inspectable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Provides pretty printing behavior for the trie data structure.
+    module Inspectable
+      # @return [String] a string representation of the current node.
+      def inspect
+        "#<#{class_name} #{attributes}>"
+      end
+
+      private
+
+      def class_name
+        self.class.name
+      end
+
+      def attributes
+        [
+          letter_inspect,
+          terminal_inspect,
+          children_inspect,
+        ].join ', '
+      end
+
+      def letter_inspect
+        "letter: #{letter.inspect}"
+      end
+
+      def terminal_inspect
+        "terminal: #{terminal.inspect}"
+      end
+
+      def children_inspect
+        "children: #{children_tree.keys.inspect}"
+      end
+    end
+  end
+end

data/lib/rambling/trie/invalid_operation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Raised when trying to execute an invalid operation on a trie data
+    # structure.
+    class InvalidOperation < RuntimeError
+      # Creates a new {InvalidOperation InvalidOperation} exception.
+      # @param [String, nil] message the exception message.
+      def initialize message = nil
+        super
+      end
+    end
+  end
+end

data/lib/rambling/trie/nodes.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# %w(node missing compressed raw).each do |file|
+#   require File.join('rambling', 'trie', 'nodes', file)
+# end
+
+require 'rambling/trie/nodes/node'
+require 'rambling/trie/nodes/compressed'
+require 'rambling/trie/nodes/missing'
+require 'rambling/trie/nodes/raw'
+
+module Rambling
+  module Trie
+    # Namespace for all nodes.
+    module Nodes
+    end
+  end
+end

data/lib/rambling/trie/nodes/compressed.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Nodes
+      # A representation of a node in an compressed trie data structure.
+      class Compressed < Rambling::Trie::Nodes::Node
+        # Always raises {Rambling::Trie::InvalidOperation InvalidOperation} when
+        # trying to add a word to the current compressed trie node
+        # @param [String] _ the word to add to the trie.
+        # @raise [InvalidOperation] if the trie is already compressed.
+        # @return [nil] this never returns as it always raises an exception.
+        def add _
+          raise Rambling::Trie::InvalidOperation,
+            'Cannot add word to compressed trie'
+        end
+
+        # Always return `true` for a compressed node.
+        # @return [Boolean] always `true` for a compressed node.
+        def compressed?
+          true
+        end
+
+        private
+
+        def partial_word_chars? chars
+          child = children_tree[chars.first.to_sym]
+          return false unless child
+
+          child_letter = child.letter.to_s
+
+          if chars.size >= child_letter.size
+            letter = chars.slice!(0, child_letter.size).join
+            return child.partial_word? chars if child_letter == letter
+          end
+
+          letter = chars.join
+          child_letter = child_letter.slice 0, letter.size
+          child_letter == letter
+        end
+
+        def word_chars? chars
+          letter = chars.slice! 0
+          letter_sym = letter.to_sym
+
+          child = children_tree[letter_sym]
+          return false unless child
+
+          loop do
+            return child.word? chars if letter_sym == child.letter
+
+            break if chars.empty?
+
+            letter << chars.slice!(0)
+            letter_sym = letter.to_sym
+          end
+
+          false
+        end
+
+        def closest_node chars
+          child = children_tree[chars.first.to_sym]
+          return missing unless child
+
+          child_letter = child.letter.to_s
+
+          if chars.size >= child_letter.size
+            letter = chars.slice!(0, child_letter.size).join
+            return child.scan chars if child_letter == letter
+          end
+
+          letter = chars.join
+          child_letter = child_letter.slice 0, letter.size
+
+          child_letter == letter ? child : missing
+        end
+
+        def children_match_prefix chars
+          return enum_for :children_match_prefix, chars unless block_given?
+
+          return if chars.empty?
+
+          child = children_tree[chars.first.to_sym]
+          return unless child
+
+          child_letter = child.letter.to_s
+          letter = chars.slice!(0, child_letter.size).join
+
+          return unless child_letter == letter
+
+          child.match_prefix chars do |word|
+            yield word
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/nodes/missing.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Nodes
+      # A representation of a missing node in the trie data structure. Returned
+      # when a node is not found.
+      class Missing < Rambling::Trie::Nodes::Node
+      end
+    end
+  end
+end

data/lib/rambling/trie/nodes/node.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Nodes
+      # A representation of a node in the trie data structure.
+      class Node
+        include Rambling::Trie::Compressible
+        include Rambling::Trie::Enumerable
+        include Rambling::Trie::Comparable
+        include Rambling::Trie::Stringifyable
+        include Rambling::Trie::Inspectable
+
+        # @overload letter
+        #   Letter(s) corresponding to the current node.
+        # @overload letter=(letter)
+        #   Sets the letter(s) corresponding to the current node. Ensures the
+        #   {Node#letter #letter} in the {Node#parent #parent}'s
+        #   {Node#children_tree #children_tree} is updated.
+        #   @param [String, Symbol, nil] letter the letter value.
+        # @return [Symbol, nil] the corresponding letter(s).
+        attr_reader :letter
+
+        # Child nodes tree.
+        # @return [Hash] the children_tree hash, consisting of `:letter =>
+        #   node`.
+        attr_accessor :children_tree
+
+        # Parent node.
+        # @return [Node, nil] the parent of the current node.
+        attr_accessor :parent
+
+        # Creates a new node.
+        # @param [Symbol, nil] letter the Node's letter value
+        # @param [Node, nil] parent the parent of the current node.
+        def initialize letter = nil, parent = nil, children_tree = {}
+          @letter = letter
+          @parent = parent
+          @children_tree = children_tree
+        end
+
+        # Child nodes.
+        # @return [Array<Node>] the array of children nodes contained
+        #   in the current node.
+        def children
+          children_tree.values
+        end
+
+        # First child node.
+        # @return [Node, nil] the first child contained in the current node.
+        def first_child
+          return if children_tree.empty?
+
+          children_tree.each_value do |child|
+            return child
+          end
+        end
+
+        # Indicates if the current node is the root node.
+        # @return [Boolean] `true` if the node does not have a parent, `false`
+        #   otherwise.
+        def root?
+          !parent
+        end
+
+        # Indicates if a {Node Node} is terminal or not.
+        # @return [Boolean] `true` for terminal nodes, `false` otherwise.
+        def terminal?
+          !!terminal
+        end
+
+        # Mark {Node Node} as terminal.
+        # @return [Node] the modified node.
+        def terminal!
+          self.terminal = true
+          self
+        end
+
+        def letter= letter
+          @letter = letter.to_sym if letter
+        end
+
+        # Checks if a path for a set of characters exists in the trie.
+        # @param [Array<String>] chars the characters to look for in the trie.
+        # @return [Boolean] `true` if the characters are found, `false`
+        #   otherwise.
+        def partial_word? chars
+          return true if chars.empty?
+
+          partial_word_chars? chars
+        end
+
+        # Checks if a path for set of characters represents a word in the trie.
+        # @param [Array<String>] chars the characters to look for in the trie.
+        # @return [Boolean] `true` if the characters are found and form a word,
+        #   `false` otherwise.
+        def word? chars = []
+          return terminal? if chars.empty?
+
+          word_chars? chars
+        end
+
+        # Returns the node that starts with the specified characters.
+        # @param [Array<String>] chars the characters to look for in the trie.
+        # @return [Node] the node that matches the specified characters.
+        #   {Missing Missing} when not found.
+        def scan chars
+          return self if chars.empty?
+
+          closest_node chars
+        end
+
+        # Returns all words that match a prefix of any length within chars.
+        # @param [String] chars the chars to base the prefix on.
+        # @return [Enumerator<String>] all the words that match a prefix given
+        #   by chars.
+        # @yield [String] each word found.
+        def match_prefix chars
+          return enum_for :match_prefix, chars unless block_given?
+
+          yield as_word if terminal?
+
+          children_match_prefix chars do |word|
+            yield word
+          end
+        end
+
+        # Get {Node Node} corresponding to a given letter.
+        # @param [Symbol] letter the letter to search for in the node.
+        # @return [Node] the node corresponding to that letter.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-5B-5D
+        #   Hash#[]
+        def [] letter
+          children_tree[letter]
+        end
+
+        # Set the {Node Node} that corresponds to a given letter.
+        # @param [Symbol] letter the letter to insert or update in the node's
+        # @param [Node] node the {Node Node} to assign to that letter.
+        # @return [Node] the node corresponding to the inserted or
+        #   updated letter.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-5B-5D
+        #   Hash#[]
+        def []= letter, node
+          children_tree[letter] = node
+        end
+
+        # Check if a {Node Node}'s children tree contains a given
+        #   letter.
+        # @param [Symbol] letter the letter to search for in the node.
+        # @return [Boolean] `true` if the letter is present, `false` otherwise
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-has_key-3F
+        #   Hash#key?
+        def key? letter
+          children_tree.key? letter
+        end
+
+        # Delete a given letter and its corresponding {Node Node} from
+        #   this {Node Node}'s children tree.
+        # @param [Symbol] letter the letter to delete from the node's children
+        #   tree.
+        # @return [Node] the node corresponding to the deleted letter.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-delete
+        #   Hash#delete
+        def delete letter
+          children_tree.delete letter
+        end
+
+        alias_method :has_key?, :key?
+
+        protected
+
+        def missing
+          Rambling::Trie::Nodes::Missing.new
+        end
+
+        private
+
+        attr_accessor :terminal
+      end
+    end
+  end
+end

data/lib/rambling/trie/nodes/raw.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Nodes
+      # A representation of a node in an uncompressed trie data structure.
+      class Raw < Rambling::Trie::Nodes::Node
+        # Adds a word to the current raw (uncompressed) trie node.
+        # @param [Array<Symbol>] chars the char array to add to the trie.
+        # @return [Raw] the added/modified node based on the word added.
+        # @note This method clears the contents of the chars variable.
+        def add chars
+          if chars.empty?
+            terminal!
+          else
+            add_to_children_tree chars
+          end
+        end
+
+        # Always return `false` for a raw (uncompressed) node.
+        # @return [Boolean] always `false` for a raw (uncompressed) node.
+        def compressed?
+          false
+        end
+
+        private
+
+        def add_to_children_tree chars
+          letter = chars.pop
+          child = children_tree[letter] || new_node(letter)
+          child.add chars
+          child
+        end
+
+        def new_node letter
+          node = Rambling::Trie::Nodes::Raw.new letter, self
+          children_tree[letter] = node
+          node
+        end
+
+        def partial_word_chars? chars = []
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+          return false unless child
+
+          child.partial_word? chars
+        end
+
+        def word_chars? chars = []
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+          return false unless child
+
+          child.word? chars
+        end
+
+        def closest_node chars
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+          return missing unless child
+
+          child.scan chars
+        end
+
+        def children_match_prefix chars
+          return enum_for :children_match_prefix, chars unless block_given?
+
+          return if chars.empty?
+
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+
+          return unless child
+
+          child.match_prefix chars do |word|
+            yield word
+          end
+        end
+      end
+    end
+  end
+end