rambling-trie 2.3.0 → 2.4.0

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

@@ -9,14 +9,13 @@ module Rambling
         # 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.
+        # @return [void]
         def add _
-          raise Rambling::Trie::InvalidOperation,
-            'Cannot add word to compressed trie'
+          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

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

@@ -3,8 +3,7 @@
 module Rambling
   module Trie
     module Nodes
-      # A representation of a missing node in the trie data structure. Returned
-      # when a node is not found.
+      # 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

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

@@ -22,8 +22,7 @@ module Rambling
         attr_reader :letter
 
         # Child nodes tree.
-        # @return [Hash] 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.
@@ -31,7 +30,7 @@ module Rambling
         attr_accessor :parent
 
         # Creates a new node.
-        # @param [Symbol, nil] letter the Node's letter value
+        # @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
@@ -40,8 +39,7 @@ module Rambling
         end
 
         # Child nodes.
-        # @return [Array<Node>] the array of children nodes contained
-        #   in the current node.
+        # @return [Array<Node>] the array of child nodes contained in the current node.
         def children
           children_tree.values
         end
@@ -51,26 +49,25 @@ module Rambling
         def first_child
           return if children_tree.empty?
 
-          children_tree.each_value do |child|
-            return child
-          end
+          # rubocop:disable Lint/UnreachableLoop
+          children_tree.each_value { |child| return child }
+          # rubocop:enable Lint/UnreachableLoop
         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
 
         # Mark {Node Node} as terminal.
-        # @return [Node] the modified node.
+        # @return [self] the modified node.
         def terminal!
           self.terminal = true
           self
@@ -82,8 +79,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?
 
@@ -92,8 +88,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?
 
@@ -112,8 +107,7 @@ module Rambling
 
         # 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.
+        # @return [Enumerator<String>] all the words that match a prefix by chars.
         # @yield [String] each word found.
         def match_prefix chars
           return enum_for :match_prefix, chars unless block_given?
@@ -128,8 +122,7 @@ module Rambling
         # 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.7.0/Hash.html#method-i-5B-5D
-        #   Hash#[]
+        # @see https://ruby-doc.org/core-2.7.0/Hash.html#method-i-5B-5D Hash#[]
         def [] letter
           children_tree[letter]
         end
@@ -137,31 +130,25 @@ module Rambling
         # 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.7.0/Hash.html#method-i-5B-5D
-        #   Hash#[]
+        # @return [Node] the node corresponding to the inserted or updated letter.
+        # @see https://ruby-doc.org/core-2.7.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.
+        # 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.7.0/Hash.html#method-i-has_key-3F
-        #   Hash#key?
+        # @return [Boolean] +true+ if the letter is present, +false+ otherwise.
+        # @see https://ruby-doc.org/core-2.7.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.
+        # 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.7.0/Hash.html#method-i-delete
-        #   Hash#delete
+        # @see https://ruby-doc.org/core-2.7.0/Hash.html#method-i-delete Hash#delete
         def delete letter
           children_tree.delete letter
         end

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

@@ -17,8 +17,8 @@ module Rambling
           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

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

@@ -3,14 +3,18 @@
 module Rambling
   module Trie
     module Readers
-      # File reader for .txt files.
-      class PlainText
-        # Yields each word read from a .txt file.
-        # @param [String] filepath the full path of the file to load the words
-        #   from.
+      # File reader for +.txt+ files.
+      class PlainText < Reader
+        # 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]
         def each_word filepath
-          File.foreach(filepath) { |line| yield line.chomp! }
+          return enum_for :each_word unless block_given?
+
+          ::File.foreach(filepath) { |line| yield line.chomp! }
+
+          self
         end
       end
     end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Readers
+      # Base class for all readers.
+      class Reader
+        # Yields each word read from given file.
+        # @abstract Subclass and override {#each_word} to fit to a particular file format.
+        # @param [String] filepath the full path of the file to load the words from.
+        # @yield [String] Each line read from the file.
+        # @return [self]
+        def each_word filepath
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/readers.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-%w(plain_text).each do |file|
+%w(reader plain_text).each do |file|
   require File.join('rambling', 'trie', 'readers', file)
 end
 

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

@@ -4,7 +4,7 @@ module Rambling
   module Trie
     module Serializers
       # Basic file serializer. Dumps/loads string contents from files.
-      class File
+      class File < Serializer
         # Loads contents from a specified filepath.
         # @param [String] filepath the filepath to load contents from.
         # @return [String] all contents of the file.

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

@@ -3,38 +3,30 @@
 module Rambling
   module Trie
     module Serializers
-      # Serializer for Ruby marshal format (.marshal) files.
-      class Marshal
+      # 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.
+        # @param [Serializer] serializer the serializer responsible to write to and read from disk.
         def initialize serializer = nil
+          super()
           @serializer = serializer || Rambling::Trie::Serializers::File.new
         end
 
-        # Loads marshaled object from contents in filepath and deserializes it
-        # into a {Nodes::Node Node}.
-        # @param [String] filepath the full path of the file to load the
-        #   marshaled object from.
+        # Loads marshaled object from contents in filepath and deserializes it into a {Nodes::Node Node}.
+        # @param [String] filepath the full path of the file to load the marshaled object from.
         # @return [Nodes::Node] The deserialized {Nodes::Node Node}.
-        # @see https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load
-        #   Marshal.load
-        # @note Use of
-        #   {https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load
-        #   Marshal.load} is generally discouraged. Only use this with trusted
-        #   input.
+        # @see https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load Marshal.load
+        # @note Use of {https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load Marshal.load} is generally
+        #   discouraged. Only use this with trusted input.
         def load filepath
           ::Marshal.load serializer.load filepath
         end
 
-        # Serializes a {Nodes::Node Node} and dumps it as a marshaled object
-        # into filepath.
+        # Serializes a {Nodes::Node Node} and dumps it as a marshaled object into filepath.
         # @param [Nodes::Node] node the node to serialize
-        # @param [String] filepath the full path of the file to dump the
-        #   marshaled object into.
+        # @param [String] filepath the full path of the file to dump the marshaled object into.
         # @return [Numeric] number of bytes written to disk.
-        # @see https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-dump
-        #   Marshal.dump
+        # @see https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-dump Marshal.dump
         def dump node, filepath
           serializer.dump ::Marshal.dump(node), filepath
         end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Serializers
+      # Base class for all serializers.
+      class Serializer
+        # Loads contents from a specified filepath.
+        # @abstract Subclass and override {#load} to parse the desired format.
+        # @param [String] filepath the filepath to load contents from.
+        # @return [TContents] parsed contents from given file.
+        def load filepath
+          raise NotImplementedError
+        end
+
+        # Dumps contents into a specified filepath.
+        # @abstract Subclass and override {#dump} to output the desired format.
+        # @param [TContents] contents the contents to dump into given file.
+        # @param [String] filepath the filepath to dump the contents to.
+        # @return [Numeric] number of bytes written to disk.
+        def dump contents, filepath
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

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

@@ -3,22 +3,19 @@
 module Rambling
   module Trie
     module Serializers
-      # Serializer for Ruby yaml format (.yaml) files.
-      class Yaml
+      # 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.
+        # @param [Serializer] serializer the serializer responsible to write to and read from disk.
         def initialize serializer = nil
+          super()
           @serializer = serializer || Rambling::Trie::Serializers::File.new
         end
 
-        # Loads serialized object from YAML file in filepath and deserializes
-        # it into a {Nodes::Node Node}.
-        # @param [String] filepath the full path of the file to load the
-        #   serialized YAML object from.
+        # Loads serialized object from YAML file in filepath and deserializes it into a {Nodes::Node Node}.
+        # @param [String] filepath the full path of the file to load the serialized YAML object from.
         # @return [Nodes::Node] The deserialized {Nodes::Node Node}.
-        # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/psych/rdoc/Psych.html#method-c-safe_load
-        #   Psych.safe_load
+        # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/psych/rdoc/Psych.html#method-c-safe_load Psych.safe_load
         def load filepath
           require 'yaml'
           ::YAML.safe_load(
@@ -32,14 +29,11 @@ module Rambling
           )
         end
 
-        # Serializes a {Nodes::Node Node} and dumps it as a YAML object into
-        # filepath.
+        # Serializes a {Nodes::Node Node} and dumps it as a YAML object into filepath.
         # @param [Nodes::Node] node the node to serialize
-        # @param [String] filepath the full path of the file to dump the YAML
-        #   object into.
+        # @param [String] filepath the full path of the file to dump the YAML object into.
         # @return [Numeric] number of bytes written to disk.
-        # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/psych/rdoc/Psych.html#method-c-dump
-        #   Psych.dump
+        # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/psych/rdoc/Psych.html#method-c-dump Psych.dump
         def dump node, filepath
           require 'yaml'
           serializer.dump ::YAML.dump(node), filepath

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

@@ -3,20 +3,22 @@
 module Rambling
   module Trie
     module Serializers
-      # Zip file serializer. Dumps/loads contents from zip files. Automatically
-      # detects if zip file contains `.marshal` or `.yml` file
-      class Zip
+      # 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
         #   properties set up so far.
         def initialize properties
+          super()
           @properties = properties
         end
 
         # Unzip contents from specified filepath and load in contents from
         # unzipped files.
         # @param [String] filepath the filepath to load contents from.
-        # @return [String] all contents of the unzipped loaded file.
+        # @return [TContents] all contents of the unzipped loaded file.
         # @see https://github.com/rubyzip/rubyzip#reading-a-zip-file Zip
         #   reading a file
         def load filepath
@@ -35,7 +37,7 @@ module Rambling
         # Dumps contents and zips into a specified filepath.
         # @param [String] contents the contents to dump.
         # @param [String] filepath the filepath to dump the contents to.
-        # @return [Numeric] number of bytes written to disk.
+        # @return [TContents] number of bytes written to disk.
         # @see https://github.com/rubyzip/rubyzip#basic-zip-archive-creation
         #   Zip archive creation
         def dump contents, filepath
@@ -50,6 +52,8 @@ module Rambling
 
             zip.add filename, entry_path
           end
+
+          ::File.size filepath
         end
 
         private

data/lib/rambling/trie/serializers.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-%w(file marshal yaml zip).each do |file|
+%w(serializer file marshal yaml zip).each do |file|
   require File.join('rambling', 'trie', 'serializers', file)
 end
 

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.3.0'
+    VERSION = '2.4.0'
   end
 end

data/lib/rambling/trie.rb

@@ -1,21 +1,20 @@
 # frozen_string_literal: true
 
 %w(
-  comparable compressible compressor configuration container enumerable
-  inspectable invalid_operation readers serializers stringifyable nodes
-  version
+  comparable compressible compressor configuration container enumerable inspectable invalid_operation
+  readers serializers stringifyable nodes version
 ).each do |file|
   require File.join('rambling', 'trie', file)
 end
 
 # 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 [Reader, nil] reader the file parser to get each word.
+      # @param [Readers::Reader, nil] reader the file parser to get each word.
       # @return [Container] the trie just created.
       # @yield [Container] the trie just created.
       # @see Rambling::Trie::Readers Readers.
@@ -23,8 +22,10 @@ module Rambling
         root = root_builder.call
 
         Rambling::Trie::Container.new root, compressor do |container|
+          # noinspection RubyMismatchedArgumentType
           if filepath
             reader ||= readers.resolve filepath
+            # noinspection RubyMismatchedArgumentType,RubyNilAnalysis
             reader.each_word filepath do |word|
               container << word
             end
@@ -36,18 +37,15 @@ 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
+      # @param [Serializer, nil] serializer the object responsible of loading the trie from disk.
       # @return [Container] the trie just loaded.
       # @yield [Container] the trie just loaded.
       # @see Rambling::Trie::Serializers Serializers.
-      # @note Use of
-      #   {https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load
-      #   Marshal.load} is generally discouraged. Only use the `.marshal`
-      #   format with trusted input.
+      # @note Use of #   {https://ruby-doc.org/core-2.7.0/Marshal.html#method-c-load Marshal.load} is generally
+      #   discouraged. Only use the +.marshal+ format with trusted input.
       def load filepath, serializer = nil
         serializer ||= serializers.resolve filepath
         root = serializer.load filepath
@@ -58,23 +56,22 @@ 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.
-      # @param [Serializer, nil] serializer the object responsible of
-      #   serializing and dumping the trie into disk.
-      # @see Rambling::Trie::Serializers Serializers.
+      # @param [Serializers::Serializer, nil] serializer the object responsible for trie serialization.
+      # @return [void]
+      # @see Serializers Serializers.
       def dump trie, filepath, serializer = nil
         serializer ||= serializers.resolve filepath
+        # noinspection RubyNilAnalysis
         serializer.dump trie.root, filepath
       end
 
-      # 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.
+      # 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
         yield properties if block_given?
         properties

data/rambling-trie.gemspec

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'rambling/trie/version'
 
 Gem::Specification.new do |gem|
   gem.authors = ['Edgar Gonzalez', 'Lilibeth De La Cruz']
-  gem.email = ['edggonzalezg@gmail.com', 'lilibethdlc@gmail.com']
+  gem.email = %w(edggonzalezg@gmail.com lilibethdlc@gmail.com)
 
   gem.description = <<~DESCRIPTION.gsub(%r{\s+}, ' ')
     The Rambling Trie is a Ruby implementation of the trie data structure, which
@@ -13,8 +13,12 @@ Gem::Specification.new do |gem|
   DESCRIPTION
 
   gem.summary = 'A Ruby implementation of the trie data structure.'
-  gem.homepage = 'http://github.com/gonzedge/rambling-trie'
+  gem.homepage = 'https://github.com/gonzedge/rambling-trie'
   gem.date = Time.now.strftime '%Y-%m-%d'
+  gem.metadata = {
+    'changelog_uri' => 'https://github.com/gonzedge/rambling-trie/blob/master/CHANGELOG.md',
+    'documentation_uri' => 'https://www.rubydoc.info/gems/rambling-trie',
+  }
 
   executables = `git ls-files -- bin/*`.split "\n"
   files = `git ls-files -- {lib,*file,*.gemspec,LICENSE*,README*}`.split "\n"
@@ -31,7 +35,7 @@ Gem::Specification.new do |gem|
   gem.platform = Gem::Platform::RUBY
   gem.required_ruby_version = '>= 2.7', '< 4'
 
-  gem.add_development_dependency 'rake', '~> 13.0'
+  gem.add_development_dependency 'rake', '~> 13.1'
   gem.add_development_dependency 'rspec', '~> 3.12'
-  gem.add_development_dependency 'yard', '~> 0.9.28'
+  gem.add_development_dependency 'yard', '~> 0.9.34'
 end