rambling-trie 2.2.1 → 2.3.1

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

@@ -0,0 +1,21 @@
+# 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,13 +3,14 @@
 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.
         def initialize serializer = nil
           @serializer = serializer || Rambling::Trie::Serializers::File.new
+          super()
         end
 
         # Loads marshaled object from contents in filepath and deserializes it
@@ -17,10 +18,10 @@ module Rambling
         # @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.5.0/Marshal.html#method-c-load
+        # @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.5.0/Marshal.html#method-c-load
+        #   {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
@@ -33,7 +34,7 @@ module Rambling
         # @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.5.0/Marshal.html#method-c-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

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,13 +3,14 @@
 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.
         def initialize serializer = nil
           @serializer = serializer || Rambling::Trie::Serializers::File.new
+          super()
         end
 
         # Loads serialized object from YAML file in filepath and deserializes
@@ -17,19 +18,18 @@ module Rambling
         # @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.5.0/libdoc/psych/rdoc/Psych.html#method-c-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(
             serializer.load(filepath),
-            [
+            permitted_classes: [
               Symbol,
               Rambling::Trie::Nodes::Raw,
               Rambling::Trie::Nodes::Compressed,
             ],
-            [],
-            true,
+            aliases: true,
           )
         end
 
@@ -39,7 +39,7 @@ module Rambling
         # @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.5.0/libdoc/psych/rdoc/Psych.html#method-c-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'

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
           @properties = properties
+          super()
         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.2.1'
+    VERSION = '2.3.1'
   end
 end

data/lib/rambling/trie.rb

@@ -10,12 +10,12 @@ 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.
@@ -36,7 +36,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
@@ -45,8 +45,8 @@ module Rambling
       # @yield [Container] the trie just loaded.
       # @see Rambling::Trie::Serializers Serializers.
       # @note Use of
-      #   {https://ruby-doc.org/core-2.5.0/Marshal.html#method-c-load
-      #   Marshal.load} is generally discouraged. Only use the `.marshal`
+      #   {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
@@ -58,19 +58,21 @@ 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
+      # @param [Serializers::Serializer, nil] serializer the object responsible
+      #   for trie serialization.
+      # @return [void]
       #   serializing and dumping the trie into disk.
-      # @see Rambling::Trie::Serializers Serializers.
+      # @see Serializers Serializers.
       def dump trie, filepath, serializer = nil
         serializer ||= serializers.resolve filepath
         serializer.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

data/rambling-trie.gemspec

@@ -1,6 +1,6 @@
 # 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|
@@ -15,6 +15,10 @@ Gem::Specification.new do |gem|
   gem.summary = 'A Ruby implementation of the trie data structure.'
   gem.homepage = 'http://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"
@@ -29,9 +33,9 @@ Gem::Specification.new do |gem|
   gem.license = 'MIT'
   gem.version = Rambling::Trie::VERSION
   gem.platform = Gem::Platform::RUBY
-  gem.required_ruby_version = '>= 2.5', '< 3.1'
+  gem.required_ruby_version = '>= 2.7', '< 4'
 
   gem.add_development_dependency 'rake', '~> 13.0'
-  gem.add_development_dependency 'rspec', '~> 3.9'
-  gem.add_development_dependency 'yard', '~> 0.9.25'
+  gem.add_development_dependency 'rspec', '~> 3.12'
+  gem.add_development_dependency 'yard', '~> 0.9.28'
 end

data/spec/integration/rambling/trie_spec.rb

@@ -8,30 +8,26 @@ describe Rambling::Trie do
 
   context 'when providing words directly' do
     it_behaves_like 'a compressible trie' do
-      let(:trie) { Rambling::Trie.create }
+      let(:trie) { described_class.create }
       let(:words) { %w(a couple of words for our full trie integration test) }
 
-      before do
-        trie.concat words
-      end
+      before { trie.concat words }
     end
   end
 
   context 'when provided with words with unicode characters' do
     it_behaves_like 'a compressible trie' do
-      let(:trie) { Rambling::Trie.create }
+      let(:trie) { described_class.create }
       let(:words) do
         %w(poquísimas palabras para nuestra prueba de integración completa 🙃)
       end
 
-      before do
-        trie.concat words
-      end
+      before { trie.concat words }
     end
   end
 
   context 'when provided with a filepath' do
-    let(:trie) { Rambling::Trie.create filepath }
+    let(:trie) { described_class.create filepath }
     let(:words) { File.readlines(filepath).map(&:chomp) }
 
     context 'with english words' do
@@ -53,33 +49,34 @@ describe Rambling::Trie do
 
     context 'when serialized with Ruby marshal format (default)' do
       it_behaves_like 'a serializable trie' do
-        let(:trie_to_serialize) { Rambling::Trie.create words_filepath }
+        let(:trie_to_serialize) { described_class.create words_filepath }
         let(:format) { :marshal }
       end
     end
 
     context 'when serialized with YAML' do
       it_behaves_like 'a serializable trie' do
-        let(:trie_to_serialize) { Rambling::Trie.create words_filepath }
+        let(:trie_to_serialize) { described_class.create words_filepath }
         let(:format) { :yml }
       end
     end
 
     context 'when serialized with zipped Ruby marshal format' do
+      let!(:original_on_exists_proc) { ::Zip.on_exists_proc }
+      let!(:original_continue_on_exists_proc) { ::Zip.continue_on_exists_proc }
+
       before do
-        @original_on_exists_proc = ::Zip.on_exists_proc
-        @original_continue_on_exists_proc = ::Zip.continue_on_exists_proc
         ::Zip.on_exists_proc = true
         ::Zip.continue_on_exists_proc = true
       end
 
       after do
-        ::Zip.on_exists_proc = @original_on_exists_proc
-        ::Zip.continue_on_exists_proc = @original_continue_on_exists_proc
+        ::Zip.on_exists_proc = original_on_exists_proc
+        ::Zip.continue_on_exists_proc = original_continue_on_exists_proc
       end
 
       it_behaves_like 'a serializable trie' do
-        let(:trie_to_serialize) { Rambling::Trie.create words_filepath }
+        let(:trie_to_serialize) { described_class.create words_filepath }
         let(:format) { 'marshal.zip' }
       end
     end

data/spec/lib/rambling/trie/comparable_spec.rb

@@ -4,93 +4,83 @@ require 'spec_helper'
 
 describe Rambling::Trie::Comparable do
   describe '#==' do
-    let(:node_1) { Rambling::Trie::Nodes::Raw.new }
-    let(:node_2) { Rambling::Trie::Nodes::Raw.new }
+    let(:node_one) { Rambling::Trie::Nodes::Raw.new }
+    let(:node_two) { Rambling::Trie::Nodes::Raw.new }
 
     context 'when the nodes do not have the same letter' do
       before do
-        node_1.letter = :a
-        node_2.letter = :b
+        node_one.letter = :a
+        node_two.letter = :b
       end
 
       it 'returns false' do
-        expect(node_1).not_to eq node_2
+        expect(node_one).not_to eq node_two
       end
     end
 
-    context 'when the nodes have the same letter and no children' do
+    context 'when nodes have same letter, not terminal and no children' do
       before do
-        node_1.letter = :a
-        node_2.letter = :a
+        node_one.letter = :a
+        node_two.letter = :a
       end
 
       it 'returns true' do
-        expect(node_1).to eq node_2
+        expect(node_one).to eq node_two
       end
     end
 
     context 'when the nodes have the same letter and are terminal' do
       before do
-        node_1.letter = :a
-        node_1.terminal!
+        node_one.letter = :a
+        node_one.terminal!
 
-        node_2.letter = :a
-        node_2.terminal!
+        node_two.letter = :a
+        node_two.terminal!
       end
 
       it 'returns true' do
-        expect(node_1).to eq node_2
-      end
-    end
-
-    context 'when the nodes have the same letter and are not terminal' do
-      before do
-        node_1.letter = :a
-        node_2.letter = :a
-      end
-
-      it 'returns true' do
-        expect(node_1).to eq node_2
+        expect(node_one).to eq node_two
       end
     end
 
     context 'when the nodes have the same letter but are not both terminal' do
       before do
-        node_1.letter = :a
-        node_1.terminal!
+        node_one.letter = :a
+        node_one.terminal!
 
-        node_2.letter = :a
+        node_two.letter = :a
       end
+
       it 'returns false' do
-        expect(node_1).not_to eq node_2
+        expect(node_one).not_to eq node_two
       end
     end
 
     context 'when the nodes have the same letter and the same children' do
       before do
-        node_1.letter = :t
-        add_words node_1, %w(hese hree hings)
+        node_one.letter = :t
+        add_words node_one, %w(hese hree hings)
 
-        node_2.letter = :t
-        add_words node_2, %w(hese hree hings)
+        node_two.letter = :t
+        add_words node_two, %w(hese hree hings)
       end
 
       it 'returns true' do
-        expect(node_1).to eq node_2
+        expect(node_one).to eq node_two
       end
     end
 
     context 'when the nodes have the same letter but different children' do
       before do
-        node_1.letter = :t
-        add_words node_1, %w(hese wo)
+        node_one.letter = :t
+        add_words node_one, %w(hese wo)
 
-        node_2.letter = :t
-        add_words node_2, %w(hese hree hings)
+        node_two.letter = :t
+        add_words node_two, %w(hese hree hings)
       end
 
       it 'returns false' do
-        expect(node_1).not_to eq node_2
+        expect(node_one).not_to eq node_two
       end
     end
   end

data/spec/lib/rambling/trie/compressor_spec.rb

@@ -3,7 +3,7 @@
 require 'spec_helper'
 
 describe Rambling::Trie::Compressor do
-  let(:compressor) { Rambling::Trie::Compressor.new }
+  let(:compressor) { described_class.new }
 
   describe '#compress' do
     let(:node) { Rambling::Trie::Nodes::Raw.new }
@@ -16,9 +16,7 @@ describe Rambling::Trie::Compressor do
     end
 
     context 'with at least one word' do
-      before do
-        add_words node, %w(all the words)
-      end
+      before { add_words node, %w(all the words) }
 
       it 'keeps the node letter nil' do
         compressed = compressor.compress node
@@ -28,25 +26,25 @@ describe Rambling::Trie::Compressor do
     end
 
     context 'with a single word' do
-      before do
-        add_word node, 'all'
-      end
+      before { add_word node, 'all' }
 
+      # rubocop:disable RSpec/ExampleLength, RSpec/MultipleExpectations
       it 'compresses into a single node without children' do
         compressed = compressor.compress node
+        compressed_node_a = compressed[:a]
 
-        expect(compressed[:a].letter).to eq :all
-        expect(compressed[:a].children.size).to eq 0
-        expect(compressed[:a]).to be_terminal
-        expect(compressed[:a]).to be_compressed
+        expect(compressed_node_a.letter).to eq :all
+        expect(compressed_node_a.children.size).to eq 0
+        expect(compressed_node_a).to be_terminal
+        expect(compressed_node_a).to be_compressed
       end
+      # rubocop:enable RSpec/ExampleLength, RSpec/MultipleExpectations
     end
 
     context 'with two words' do
-      before do
-        add_words node, %w(all ask)
-      end
+      before { add_words node, %w(all ask) }
 
+      # rubocop:disable RSpec/ExampleLength, RSpec/MultipleExpectations
       it 'compresses into corresponding three nodes' do
         compressed = compressor.compress node
 
@@ -65,8 +63,10 @@ describe Rambling::Trie::Compressor do
         expect(compressed[:a][:l]).to be_compressed
         expect(compressed[:a][:s]).to be_compressed
       end
+      # rubocop:enable RSpec/ExampleLength, RSpec/MultipleExpectations
     end
 
+    # rubocop:disable RSpec/ExampleLength, RSpec/MultipleExpectations
     it 'reassigns the parent nodes correctly' do
       add_words node, %w(repay rest repaint)
       compressed = compressor.compress node
@@ -91,7 +91,9 @@ describe Rambling::Trie::Compressor do
       expect(compressed[:r][:p][:i].parent).to eq compressed[:r][:p]
       expect(compressed[:r][:p][:i].children.size).to eq 0
     end
+    # rubocop:enable RSpec/ExampleLength, RSpec/MultipleExpectations
 
+    # rubocop:disable RSpec/ExampleLength, RSpec/MultipleExpectations
     it 'does not compress terminal nodes' do
       add_words node, %w(you your yours)
       compressed = compressor.compress node
@@ -104,5 +106,6 @@ describe Rambling::Trie::Compressor do
       expect(compressed[:y][:r][:s].letter).to eq :s
       expect(compressed[:y][:r][:s]).to be_compressed
     end
+    # rubocop:enable RSpec/ExampleLength, RSpec/MultipleExpectations
   end
 end