rambling-trie 1.0.2 → 1.0.3

data/lib/rambling/trie/container.rb

@@ -2,31 +2,14 @@ module Rambling
   module Trie
     # Wrapper on top of trie data structure.
     class Container
-      extend ::Forwardable
       include ::Enumerable
 
-      delegate [
-        :[],
-        :as_word,
-        :children,
-        :children_tree,
-        :compressed?,
-        :each,
-        :to_a,
-        :has_key?,
-        :inspect,
-        :letter,
-        :parent,
-        :size,
-        :to_s
-      ] => :root
-
       # The root node of this trie.
-      # @return [Node] the root node of this trie.
+      # @return [Nodes::Node] the root node of this trie.
       attr_reader :root
 
       # Creates a new trie.
-      # @param [Node] root the root node for the trie
+      # @param [Nodes::Node] root the root node for the trie
       # @param [Compressor] compressor responsible for compressing the trie
       # @yield [Container] the trie just created.
       def initialize root, compressor
@@ -36,32 +19,53 @@ module Rambling
         yield self if block_given?
       end
 
-      # Adds a word to the trie, without altering the passed word.
+      # Adds a word to the trie.
       # @param [String] word the word to add the branch from.
-      # @return [Node] the just added branch's root node.
+      # @return [Nodes::Node] the just added branch's root node.
       # @raise [InvalidOperation] if the trie is already compressed.
-      # @see RawNode#add
-      # @see CompressedNode#add
-      # @note Avoids altering the contents of the word variable.
+      # @see Nodes::Raw#add
+      # @see Nodes::Compressed#add
       def add word
-        root.add word.clone
+        root.add char_symbols word
       end
 
-      # Compresses the existing tree using redundant node elimination. Marks
-      # the trie as compressed.
+      # Adds all provided words to the trie.
+      # @param [Array<String>] words the words to add the branch from.
+      # @return [Array<Nodes::Node>] the collection of nodes added.
+      # @raise [InvalidOperation] if the trie is already compressed.
+      # @see Nodes::Raw#add
+      # @see Nodes::Compressed#add
+      def concat words
+        words.map { |word| add word }
+      end
+
+      # Compresses the existing trie using redundant node elimination. Marks
+      # the trie as compressed. Does nothing if the trie has already been
+      # compressed.
       # @return [Container] self
-      # @note Only compresses tries that have not already been compressed.
+      # @note This method replaces the root {Nodes::Raw Raw} node with a
+      #   {Nodes::Compressed Compressed} version of it.
       def compress!
-        self.root = compressor.compress root unless root.compressed?
+        self.root = compress_root unless root.compressed?
         self
       end
 
+      # Compresses the existing trie using redundant node elimination. Returns
+      # a new trie with the compressed root.
+      # @return [Container] A new {Container} with the {Nodes::Compressed
+      #   Compressed} root node or self if the trie has already been
+      #   compressed.
+      def compress
+        return self if root.compressed?
+        Rambling::Trie::Container.new compress_root, compressor
+      end
+
       # Checks if a path for a word or partial word exists in the trie.
       # @param [String] word the word or partial word to look for in the trie.
       # @return [Boolean] `true` if the word or partial word is found, `false`
       #   otherwise.
-      # @see RawNode#partial_word?
-      # @see CompressedNode#partial_word?
+      # @see Nodes::Raw#partial_word?
+      # @see Nodes::Compressed#partial_word?
       def partial_word? word = ''
         root.partial_word? word.chars
       end
@@ -70,8 +74,8 @@ module Rambling
       # @param [String] word the word to look for in the trie.
       # @return [Boolean] `true` only if the word is found and the last
       #   character corresponds to a terminal node, `false` otherwise.
-      # @see RawNode#word?
-      # @see CompressedNode#word?
+      # @see Nodes::Raw#word?
+      # @see Nodes::Compressed#word?
       def word? word = ''
         root.word? word.chars
       end
@@ -80,8 +84,8 @@ module Rambling
       # @param [String] word the word to look for in the trie.
       # @return [Array<String>] all the words contained in the trie that start
       #   with the specified characters.
-      # @see RawNode#scan
-      # @see CompressedNode#scan
+      # @see Nodes::Raw#scan
+      # @see Nodes::Compressed#scan
       def scan word = ''
         root.scan(word.chars).to_a
       end
@@ -92,7 +96,7 @@ module Rambling
       # @return [Enumerator<String>] all the words in the given string that
       #   match a word in the trie.
       # @yield [String] each word found in phrase.
-      # @see Node#words_within
+      # @see Nodes::Node#words_within
       def words_within phrase
         words_within_root(phrase).to_a
       end
@@ -113,10 +117,116 @@ module Rambling
         root == other.root
       end
 
+      # 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?
+
+        root.each do |word|
+          yield word
+        end
+      end
+
+      # @return [String] a string representation of the container.
+      def inspect
+        "#<#{self.class.name} root: #{root.inspect}>"
+      end
+
+      # Get {Nodes::Node Node} corresponding to a given letter.
+      # @param [Symbol] letter the letter to search for in the root node.
+      # @return [Nodes::Node] the node corresponding to that letter.
+      # @see Nodes::Node#[]
+      def [] letter
+        root[letter]
+      end
+
+      # Root node's child nodes.
+      # @return [Array<Nodes::Node>] the array of children nodes contained in
+      #   the root node.
+      # @see Nodes::Node#children
+      def children
+        root.children
+      end
+
+      # Root node's children tree.
+      # @return [Array<Nodes::Node>] the array of children nodes contained in
+      #   the root node.
+      # @see Nodes::Node#children_tree
+      def children_tree
+        root.children_tree
+      end
+
+      # Indicates if the root {Nodes::Node Node} can be
+      # compressed or not.
+      # @return [Boolean] `true` for non-{Nodes::Node#terminal? terminal}
+      #    nodes with one child, `false` otherwise.
+      def compressed?
+        root.compressed?
+      end
+
+      # Array of words contained in the root {Nodes::Node Node}.
+      # @return [Array<String>] all words contained in this trie.
+      # @see https://ruby-doc.org/core-2.5.0/Enumerable.html#method-i-to_a
+      #   Enumerable#to_a
+      def to_a
+        root.to_a
+      end
+
+      # Check if a letter is part of the root {Nodes::Node}'s children tree.
+      # @param [Symbol] letter the letter to search for in the root node.
+      # @return [Boolean] whether the letter is contained or not.
+      # @see Nodes::Node#has_key?
+      def has_key? letter
+        root.has_key? letter
+      end
+
+      # Size of the Root {Nodes::Node Node}'s children tree.
+      # @return [Integer] the number of letters in the root node.
+      def size
+        root.size
+      end
+
+      # String representation of the current node, if it is a terminal node.
+      # @return [String] the string representation of the current node.
+      # @raise [InvalidOperation] if node is not terminal or is root.
+      # @deprecated This will always raise an {InvalidOperation} exception.
+      def as_word
+        warn '[DEPRECATION WARNING] `#as_word` is deprecated. Please use `#root#as_word` instead.'
+        root.as_word
+      end
+
+      # Root {Nodes::Node Node}'s letter.
+      # @return [Symbol] the root node's letter
+      # @see Nodes::Node#letter
+      # @deprecated This will always return `nil`.
+      def letter
+        warn '[DEPRECATION WARNING] `#letter` is deprecated. Please use `#root#letter` instead.'
+        root.letter
+      end
+
+      # Root {Nodes::Node Node}'s parent.
+      # @return [Symbol] the root node's parent
+      # @see Nodes::Node#parent
+      # @deprecated This will always return `nil`.
+      def parent
+        warn '[DEPRECATION WARNING] `#parent` is deprecated. Please use `#root#parent` instead.'
+        root.parent
+      end
+
+      # String representation of root {Nodes::Node Node}.
+      # @return [String] the root node's string representation.
+      # @see Stringifyable#to_s
+      # @deprecated This will always return an empty string (`''`).
+      def to_s
+        warn '[DEPRECATION WARNING] `#to_s` is deprecated. Please use `#root#to_s` instead.'
+        root.to_s
+      end
+
       alias_method :include?, :word?
       alias_method :match?, :partial_word?
       alias_method :words, :scan
       alias_method :<<, :add
+      alias_method :has_letter?, :has_key?
 
       private
 
@@ -134,6 +244,16 @@ module Rambling
           end
         end
       end
+
+      def compress_root
+        compressor.compress root
+      end
+
+      def char_symbols word
+        symbols = []
+        word.reverse.each_char { |c| symbols << c.to_sym }
+        symbols
+      end
     end
   end
 end

data/lib/rambling/trie/enumerable.rb

@@ -4,9 +4,9 @@ module Rambling
     module Enumerable
       include ::Enumerable
 
-      # Returns number of words contained in the trie. See
-      # {https://ruby-doc.org/core-2.4.0/Enumerable.html#method-i-count
-      # 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.
@@ -16,7 +16,7 @@ module Rambling
 
         yield as_word if terminal?
 
-        children.each do |child|
+        children_tree.each_value do |child|
           child.each do |word|
             yield word
           end

data/lib/rambling/trie/nodes.rb

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

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

@@ -0,0 +1,115 @@
+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] word 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 word
+          raise Rambling::Trie::InvalidOperation, 'Cannot add word to compressed trie'
+        end
+
+        # Checks if a path for set a 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
+          chars.empty? || has_partial_word?(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
+          chars.empty? ? terminal? : has_word?(chars)
+        end
+
+        # Always return `true` for a compressed node.
+        # @return [Boolean] always `true` for a compressed node.
+        def compressed?
+          true
+        end
+
+        private
+
+        def has_partial_word? chars
+          recursive_get(:partial_word?, chars) || false
+        end
+
+        def has_word? chars
+          current_key = nil
+
+          while !chars.empty?
+            if current_key
+              current_key << chars.slice!(0)
+            else
+              current_key = chars.slice!(0)
+            end
+
+            child = children_tree[current_key.to_sym]
+            return child.word? chars if child
+          end
+
+          false
+        end
+
+        def closest_node chars
+          recursive_get(:scan, chars) || Rambling::Trie::Nodes::Missing.new
+        end
+
+        def children_match_prefix chars
+          return enum_for :children_match_prefix, chars unless block_given?
+
+          current_key = nil
+
+          while !chars.empty?
+            if current_key
+              current_key << chars.slice!(0)
+            else
+              current_key = chars.slice!(0)
+            end
+
+            child = children_tree[current_key.to_sym]
+
+            next unless child
+
+            child.match_prefix chars do |word|
+              yield word
+            end
+          end
+        end
+
+        def recursive_get method, chars
+          current_length = 0
+          current_key = current_key chars.slice!(0)
+
+          begin
+            current_length += 1
+
+            if current_key && (current_key.length == current_length || chars.empty?)
+              return children_tree[current_key.to_sym].send method, chars
+            end
+          end while current_key && current_key[current_length] == chars.slice!(0)
+        end
+
+        def current_key letter
+          current_key = nil
+
+          children_tree.each_key do |letters|
+            letters_string = letters.to_s
+
+            if letters_string.start_with? letter
+              current_key = letters_string
+              break
+            end
+          end
+
+          current_key
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+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,151 @@
+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
+
+        # 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#has_key?
+        def has_key? letter
+          children_tree.has_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
+
+        private
+
+        attr_accessor :terminal
+      end
+    end
+  end
+end