rambling-trie 2.5.0 → 2.5.1

data/lib/rambling/trie/enumerable.rb

@@ -6,6 +6,9 @@ module Rambling
     module Enumerable
       include ::Enumerable
 
+      # Empty enumerator constant for early each exits.
+      EMPTY_ENUMERATOR = [].to_enum :each
+
       # Returns number of words contained in the trie
       # @see https://ruby-doc.org/3.3.0/Enumerable.html#method-i-count Enumerable#count
       alias_method :size, :count
@@ -18,11 +21,7 @@ module Rambling
 
         yield as_word if terminal?
 
-        children_tree.each_value do |child|
-          child.each do |word|
-            yield word
-          end
-        end
+        children_tree.each_value { |child| child.each { |word| yield word } }
 
         self
       end

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

@@ -4,7 +4,19 @@ module Rambling
   module Trie
     module Nodes
       # A representation of a node in an compressed trie data structure.
+      # :reek:RepeatedConditional { max_ifs: 4 }
       class Compressed < Rambling::Trie::Nodes::Node
+        # Creates a new compressed node.
+        # @param [Symbol, nil] letter the Node's letter value.
+        # @param [Node, nil] parent the parent of the current node.
+        # @param [Hash<Symbol, Node>] children_tree the children tree of the current node.
+        def initialize letter = nil, parent = nil, children_tree = {}
+          super
+
+          # Ensure all children have the current compressed node as the parent
+          children_tree.each_value { |child| child.parent = self }
+        end
+
         # 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.
@@ -14,8 +26,8 @@ module Rambling
           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.
+        # Always return `true` for a compressed node.
+        # @return [Boolean] always `true` for a compressed node.
         def compressed?
           true
         end
@@ -23,13 +35,13 @@ module Rambling
         private
 
         def partial_word_chars? chars
-          child = children_tree[chars.first.to_sym]
+          child = children_tree[(chars.first || raise).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
+            letter = (chars.shift(child_letter.size) || raise).join
             return child.partial_word? chars if child_letter == letter
           end
 
@@ -39,7 +51,7 @@ module Rambling
         end
 
         def word_chars? chars
-          letter = chars.slice! 0
+          letter = chars.shift || raise
           letter_sym = letter.to_sym
 
           child = children_tree[letter_sym]
@@ -50,7 +62,7 @@ module Rambling
 
             break if chars.empty?
 
-            letter << chars.slice!(0)
+            letter << (chars.shift || raise)
             letter_sym = letter.to_sym
           end
 
@@ -58,13 +70,13 @@ module Rambling
         end
 
         def closest_node chars
-          child = children_tree[chars.first.to_sym]
+          child = children_tree[(chars.first || raise).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
+            letter = (chars.shift(child_letter.size) || raise).join
             return child.scan chars if child_letter == letter
           end
 
@@ -77,19 +89,17 @@ module Rambling
         def children_match_prefix chars
           return enum_for :children_match_prefix, chars unless block_given?
 
-          return if chars.empty?
+          return EMPTY_ENUMERATOR if chars.empty?
 
-          child = children_tree[chars.first.to_sym]
-          return unless child
+          child = children_tree[(chars.first || raise).to_sym]
+          return EMPTY_ENUMERATOR unless child
 
           child_letter = child.letter.to_s
-          letter = chars.slice!(0, child_letter.size).join
+          letter = (chars.shift(child_letter.size) || raise).join
 
-          return unless child_letter == letter
+          return EMPTY_ENUMERATOR unless child_letter == letter
 
-          child.match_prefix chars do |word|
-            yield word
-          end
+          child.match_prefix(chars) { |word| yield word }
         end
       end
     end

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

@@ -4,6 +4,8 @@ module Rambling
   module Trie
     module Nodes
       # A representation of a node in the trie data structure.
+      # :reek:MissingSafeMethod { exclude: [ terminal! ] }
+      # :reek:RepeatedConditional { max_ifs: 3 }
       class Node
         include Rambling::Trie::Compressible
         include Rambling::Trie::Enumerable
@@ -22,7 +24,7 @@ module Rambling
         attr_reader :letter
 
         # Child nodes tree.
-        # @return [Hash<Symbol, Node>] the children tree hash, consisting of +:letter => node+.
+        # @return [Hash<Symbol, Node>] the children tree hash, consisting of `:letter => node`.
         attr_accessor :children_tree
 
         # Parent node.
@@ -32,6 +34,7 @@ module Rambling
         # Creates a new node.
         # @param [Symbol, nil] letter the Node's letter value.
         # @param [Node, nil] parent the parent of the current node.
+        # @param [Hash<Symbol, Node>] children_tree the children tree of the current node.
         def initialize letter = nil, parent = nil, children_tree = {}
           @letter = letter
           @parent = parent
@@ -52,16 +55,18 @@ module Rambling
           # rubocop:disable Lint/UnreachableLoop
           children_tree.each_value { |child| return child }
           # rubocop:enable Lint/UnreachableLoop
+
+          nil
         end
 
         # Indicates if the current node is the root node.
-        # @return [Boolean] +true+ if the node does not have a parent, +false+ otherwise.
+        # @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.
+        # @return [Boolean] `true` for terminal nodes, `false` otherwise.
         def terminal?
           !!terminal
         end
@@ -79,7 +84,7 @@ module Rambling
 
         # 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.
+        # @return [Boolean] `true` if the characters are found, `false` otherwise.
         def partial_word? chars
           return true if chars.empty?
 
@@ -88,7 +93,7 @@ module Rambling
 
         # 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.
+        # @return [Boolean] `true` if the characters are found and form a word, `false` otherwise.
         def word? chars = []
           return terminal? if chars.empty?
 
@@ -106,7 +111,7 @@ module Rambling
         end
 
         # Returns all words that match a prefix of any length within chars.
-        # @param [String] chars the chars to base the prefix on.
+        # @param [Array[String]] chars the chars to base the prefix on.
         # @return [Enumerator<String>] all the words that match a prefix by chars.
         # @yield [String] each word found.
         def match_prefix chars
@@ -138,7 +143,7 @@ module Rambling
 
         # 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.
+        # @return [Boolean] `true` if the letter is present, `false` otherwise.
         # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-has_key-3F Hash#key?
         def key? letter
           children_tree.key? letter
@@ -147,7 +152,7 @@ module Rambling
         # 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.
+        # @return [Node, nil] the node corresponding to the deleted letter.
         # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-delete Hash#delete
         def delete letter
           children_tree.delete letter
@@ -164,6 +169,24 @@ module Rambling
         private
 
         attr_accessor :terminal
+
+        # abstract methods
+
+        def children_match_prefix chars
+          raise NotImplementedError
+        end
+
+        def partial_word_chars? chars
+          raise NotImplementedError
+        end
+
+        def word_chars? chars
+          raise NotImplementedError
+        end
+
+        def closest_node chars
+          raise NotImplementedError
+        end
       end
     end
   end

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

@@ -4,22 +4,23 @@ module Rambling
   module Trie
     module Nodes
       # A representation of a node in an uncompressed trie data structure.
+      # :reek:RepeatedConditional { max_ifs: 4 }
       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.
+        # @param [Array<Symbol>] reversed_chars the char array to add to the trie, in reverse order.
+        # @return [Node] 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?
+        def add reversed_chars
+          if reversed_chars.empty?
             terminal! unless root?
             self
           else
-            add_to_children_tree chars
+            add_to_children_tree reversed_chars
           end
         end
 
-        # Always return +false+ for a raw (uncompressed) node.
-        # @return [Boolean] always +false+ for a raw (uncompressed) node.
+        # Always return `false` for a raw (uncompressed) node.
+        # @return [Boolean] always `false` for a raw (uncompressed) node.
         def compressed?
           false
         end
@@ -27,7 +28,7 @@ module Rambling
         private
 
         def add_to_children_tree chars
-          letter = chars.pop
+          letter = chars.pop || raise
           child = children_tree[letter] || new_node(letter)
           child.add chars
           child
@@ -40,7 +41,7 @@ module Rambling
         end
 
         def partial_word_chars? chars = []
-          letter = chars.shift.to_sym
+          letter = (chars.shift || raise).to_sym
           child = children_tree[letter]
           return false unless child
 
@@ -48,7 +49,7 @@ module Rambling
         end
 
         def word_chars? chars = []
-          letter = chars.shift.to_sym
+          letter = (chars.shift || raise).to_sym
           child = children_tree[letter]
           return false unless child
 
@@ -56,7 +57,7 @@ module Rambling
         end
 
         def closest_node chars
-          letter = chars.shift.to_sym
+          letter = (chars.shift || raise).to_sym
           child = children_tree[letter]
           return missing unless child
 
@@ -66,16 +67,12 @@ module Rambling
         def children_match_prefix chars
           return enum_for :children_match_prefix, chars unless block_given?
 
-          return if chars.empty?
+          return EMPTY_ENUMERATOR if chars.empty?
 
-          letter = chars.shift.to_sym
-          child = children_tree[letter]
-
-          return unless child
+          child = children_tree[(chars.shift || raise).to_sym]
+          return EMPTY_ENUMERATOR unless child
 
-          child.match_prefix chars do |word|
-            yield word
-          end
+          child.match_prefix(chars) { |word| yield word }
         end
       end
     end

data/lib/rambling/trie/nodes.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-%w(node missing compressed raw).each do |file|
-  require File.join('rambling', 'trie', 'nodes', file)
-end
+path = File.join 'rambling', 'trie', 'nodes'
+%w(node missing compressed raw).each { |file| require File.join(path, file) }
 
 module Rambling
   module Trie

data/lib/rambling/trie/readers/plain_text.rb

@@ -3,9 +3,9 @@
 module Rambling
   module Trie
     module Readers
-      # File reader for +.txt+ files.
+      # File reader for `.txt` files.
       class PlainText < Reader
-        # Yields each word read from a +.txt+ file.
+        # Yields each word read from a `.txt` file.
         # @param [String] filepath the full path of the file to load the words from.
         # @yield [String] Each line read from the file.
         # @return [self]

data/lib/rambling/trie/readers.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-%w(reader plain_text).each do |file|
-  require File.join('rambling', 'trie', 'readers', file)
-end
+path = File.join 'rambling', 'trie', 'readers'
+%w(reader plain_text).each { |file| require File.join(path, file) }
 
 module Rambling
   module Trie

data/lib/rambling/trie/serializers/marshal.rb

@@ -3,7 +3,7 @@
 module Rambling
   module Trie
     module Serializers
-      # Serializer for Ruby marshal format (+.marshal+) files.
+      # Serializer for Ruby marshal format (`.marshal`) files.
       class Marshal < Serializer
         # Creates a new Marshal serializer.
         # @param [Serializer] serializer the serializer responsible to write to and read from disk.

data/lib/rambling/trie/serializers/yaml.rb

@@ -3,7 +3,7 @@
 module Rambling
   module Trie
     module Serializers
-      # Serializer for Ruby yaml format (+.yaml+, or +.yml+) files.
+      # Serializer for Ruby yaml format (`.yaml`, or `.yml`) files.
       class Yaml < Serializer
         # Creates a new Yaml serializer.
         # @param [Serializer] serializer the serializer responsible to write to and read from disk.

data/lib/rambling/trie/serializers/zip.rb

@@ -3,9 +3,9 @@
 module Rambling
   module Trie
     module Serializers
-      # Zip file serializer. Dumps/loads contents from +.zip+ files.
-      # Automatically detects if zip file contains a +.marshal+ or +.yml+ file,
-      # or any other registered +:format => serializer+ combo.
+      # Zip file serializer. Dumps/loads contents from `.zip` files.
+      # Automatically detects if zip file contains a `.marshal` or `.yml` file,
+      # or any other registered `:format => serializer` combo.
       class Zip < Serializer
         # Creates a new Zip serializer.
         # @param [Configuration::Properties] properties the configuration
@@ -26,12 +26,15 @@ module Rambling
 
           ::Zip::File.open filepath do |zip|
             entry = zip.entries.first
-            return nil if entry.nil?
+            raise unless entry
 
-            entry_path = path entry.name
+            entry_name = entry.name
+            entry_path = path entry_name
             entry.extract entry_path
 
-            serializer = serializers.resolve entry.name
+            serializer = serializers.resolve entry_name
+            raise unless serializer
+
             serializer.load entry_path
           end
         end
@@ -50,6 +53,9 @@ module Rambling
 
             entry_path = path filename
             serializer = serializers.resolve filename
+
+            raise unless serializer
+
             serializer.dump contents, entry_path
 
             zip.add filename, entry_path

data/lib/rambling/trie/serializers.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-%w(serializer file marshal yaml zip).each do |file|
-  require File.join('rambling', 'trie', 'serializers', file)
-end
+path = File.join 'rambling', 'trie', 'serializers'
+%w(serializer file marshal yaml zip).each { |file| require File.join(path, file) }
 
 module Rambling
   module Trie

data/lib/rambling/trie/stringifyable.rb

@@ -2,7 +2,7 @@
 
 module Rambling
   module Trie
-    # Provides the +String+ representation behavior for the trie data structure.
+    # Provides the `String` representation behavior for the trie data structure.
     module Stringifyable
       # String representation of the current node, if it is a terminal node.
       # @return [String] the string representation of the current node.

data/lib/rambling/trie/version.rb

@@ -3,6 +3,6 @@
 module Rambling
   module Trie
     # Current version of the rambling-trie.
-    VERSION = '2.5.0'
+    VERSION = '2.5.1'
   end
 end

data/lib/rambling/trie.rb

@@ -1,18 +1,17 @@
 # frozen_string_literal: true
 
+path = File.join 'rambling', 'trie'
 %w(
   comparable compressible compressor configuration container enumerable inspectable invalid_operation
   readers serializers stringifyable nodes version
-).each do |file|
-  require File.join('rambling', 'trie', file)
-end
+).each { |file| require File.join(path, file) }
 
 # General namespace for all Rambling gems.
 module Rambling
-  # Entry point for +rambling-trie+ API.
+  # Entry point for `rambling-trie` API.
   module Trie
     class << self
-      # Creates a new +Rambling::Trie+. Entry point for the +rambling-trie+ API.
+      # Creates a new `Rambling::Trie`. Entry point for the `rambling-trie` API.
       # @param [String, nil] filepath the file to load the words from.
       # @param [Readers::Reader, nil] reader the file parser to get each word.
       # @return [Container] the trie just created.
@@ -26,9 +25,7 @@ module Rambling
           if filepath
             reader ||= readers.resolve filepath
             # noinspection RubyMismatchedArgumentType,RubyNilAnalysis
-            reader.each_word filepath do |word|
-              container << word
-            end
+            (reader || raise).each_word(filepath) { |word| container << word }
           end
 
           yield container if block_given?
@@ -37,7 +34,7 @@ module Rambling
 
       # Loads an existing trie from disk into memory. By default, it will
       # deduce the correct way to deserialize based on the file extension.
-      # Available formats are +yml+, +marshal+, and +zip+ versions of all the
+      # Available formats are `yml`, `marshal`, and `zip` versions of all the
       # previous formats. You can also define your own.
       # @param [String] filepath the file to load the words from.
       # @param [Serializer, nil] serializer the object responsible of loading the trie from disk.
@@ -45,10 +42,10 @@ module Rambling
       # @yield [Container] the trie just loaded.
       # @see Rambling::Trie::Serializers Serializers.
       # @note Use of #   {https://ruby-doc.org/3.3.0/Marshal.html#method-c-load Marshal.load} is generally
-      #   discouraged. Only use the +.marshal+ format with trusted input.
+      #   discouraged. Only use the `.marshal` format with trusted input.
       def load filepath, serializer = nil
         serializer ||= serializers.resolve filepath
-        root = serializer.load filepath
+        root = (serializer || raise).load filepath
         Rambling::Trie::Container.new root, compressor do |container|
           yield container if block_given?
         end
@@ -56,7 +53,7 @@ module Rambling
 
       # Dumps an existing trie from memory into disk. By default, it will
       # deduce the correct way to serialize based on the file extension.
-      # Available formats are +yml+, +marshal+, and +zip+ versions of all the
+      # Available formats are `yml`, `marshal`, and `zip` versions of all the
       # previous formats. You can also define your own.
       # @param [Container] trie the trie to dump into disk.
       # @param [String] filepath the file to dump to serialized trie into.
@@ -66,10 +63,10 @@ module Rambling
       def dump trie, filepath, serializer = nil
         serializer ||= serializers.resolve filepath
         # noinspection RubyNilAnalysis
-        serializer.dump trie.root, filepath
+        (serializer || raise).dump trie.root, filepath
       end
 
-      # Provides configuration properties for the +Rambling::Trie+ gem.
+      # Provides configuration properties for the `Rambling::Trie` gem.
       # @return [Configuration::Properties] the configured properties of the gem.
       # @yield [Configuration::Properties] the configured properties of the gem.
       def config

data/rambling-trie.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |gem|
   }
 
   executables = `git ls-files -- bin/*`.split "\n"
-  files = `git ls-files -- {lib,*file,*.gemspec,LICENSE*,README*}`.split "\n"
+  files = `git ls-files -- {lib,sig,*file,*.gemspec,LICENSE*,README*}`.split "\n"
 
   gem.executables = executables.map { |f| File.basename f }
   gem.files = files

data/sig/lib/rambling/trie/comparable.rbs

@@ -0,0 +1,17 @@
+module Rambling
+  module Trie
+    module Comparable
+      def ==: (Nodes::Node) -> bool
+
+      private
+
+      # abstract methods
+
+      def letter: -> Symbol
+
+      def terminal?: -> bool
+
+      def children_tree: -> Hash[Symbol, Nodes::Node]
+    end
+  end
+end

data/sig/lib/rambling/trie/compressible.rbs

@@ -0,0 +1,17 @@
+module Rambling
+  module Trie
+    module Compressible
+      def compressible?: -> bool
+
+      private
+
+      # abstract methods
+
+      def root?: -> bool
+
+      def terminal?: -> bool
+
+      def children_tree: -> Hash[Symbol, Nodes::Node]
+    end
+  end
+end

data/sig/lib/rambling/trie/compressor.rbs

@@ -0,0 +1,17 @@
+module Rambling
+  module Trie
+    class Compressor
+      def compress: (Nodes::Node?) -> Nodes::Compressed?
+
+      private
+
+      def compress_only_child_and_merge: (Nodes::Node) -> Nodes::Compressed
+
+      def merge: (Nodes::Node, Nodes::Node) -> Nodes::Compressed
+
+      def compress_children_and_copy: (Nodes::Node) -> Nodes::Compressed
+
+      def compress_children: (Hash[Symbol, Nodes::Node]) -> Hash[Symbol, Nodes::Node]
+    end
+  end
+end

data/sig/lib/rambling/trie/configuration/properties.rbs

@@ -0,0 +1,28 @@
+module Rambling
+  module Trie
+    module Configuration
+      class Properties
+        attr_reader readers: ProviderCollection[Readers::Reader]
+        attr_reader serializers: ProviderCollection[Serializers::Serializer[Nodes::Node]]
+        attr_accessor compressor: Compressor
+        attr_accessor root_builder: ^() -> Nodes::Node
+        attr_accessor tmp_path: String
+
+        def initialize: -> void
+
+        def reset: -> void
+
+        private
+
+        attr_writer readers: ProviderCollection[Readers::Reader]
+        attr_writer serializers: ProviderCollection[Serializers::Serializer[Nodes::Node]]
+
+        def reset_readers: -> void
+
+        def default_reader_providers: -> Hash[Symbol, Readers::Reader]
+
+        def reset_serializers: -> void
+      end
+    end
+  end
+end