rambling-trie 1.0.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ee20334126cebef1f6c2701fe7d612fde28854e3
-  data.tar.gz: 832b58d0d0580d2318350adeafdd1b894b5f7ee4
+SHA256:
+  metadata.gz: 22f6c4caa5644231338f085b6beb904e184db2f50c96a4e29ae31f931c4f60d1
+  data.tar.gz: 5ff102450e6d8eb15990f2a5c14bcb8b280b44c9b1460a2fdb5653bacf838a21
 SHA512:
-  metadata.gz: f2d654657d6cdaf376c84c28855c08ca4d9d21e752badf94e88a36f796dfeff0179abc748bd79cc6d7749b7840f9d0eeb20f7f62957237ec7c4861b016db61a2
-  data.tar.gz: f46b5c920c9871e637706ce3a1a2578aca2e938c824979c5925ebf8f8994e7f5bbc85e1ac4b062da318db310c4642a9650d22fbbf8e516cc35967e9f1e3a7e89
+  metadata.gz: '08b1564034a74f0ac49b67bd449037207d9573e9dad78e5db0b59bdeb0f5b87edd7b046b472eb653f8cca30ded40c2ebe8c024d20aabea294d3bbc0b40e95a02'
+  data.tar.gz: 414644eaa457ffde46cef1135fa211e31a529bb83d4ea27f25ae9810c2480e822729ce7c7907e87db08873a267d3da57a1f427bc4d28a992c6ebbea7a598df54

data/Gemfile

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec
@@ -6,18 +7,20 @@ gemspec
 gem 'rubyzip'
 
 group :development do
-  gem 'ruby-prof'
-  gem 'memory_profiler'
   gem 'benchmark-ips'
   gem 'flamegraph'
+  gem 'memory_profiler'
+  gem 'pry'
+  gem 'ruby-prof'
   gem 'stackprof'
 end
 
 group :test do
+  gem 'coveralls', '~>0.8.21', require: false
   gem 'simplecov', require: false
-  gem 'coveralls', require: false
 end
 
 group :local do
   gem 'guard-rspec'
+  gem 'rubocop', require: false
 end

data/Guardfile

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
 guard 'rspec', cmd: 'rspec', all_on_start: true, all_after_pass: false do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch('spec/spec_helper.rb')  { 'spec' }
 end

data/README.md

@@ -1,6 +1,6 @@
 # Rambling Trie
 
-[![Gem Version][badge_fury_badge]][badge_fury_link] [![Dependency Status][gemnasium_badge]][gemnasium_link] [![Build Status][travis_ci_badge]][travis_ci_link] [![Code Climate][code_climate_badge]][code_climage_link] [![Coverage Status][coveralls_badge]][coveralls_link] [![Documentation Status][inch_ci_badge]][inch_ci_link]
+[![Gem Version][badge_fury_badge]][badge_fury_link] [![Build Status][travis_ci_badge]][travis_ci_link] [![Code Climate][code_climate_badge]][code_climage_link] [![Coverage Status][coveralls_badge]][coveralls_link] [![Documentation Status][inch_ci_badge]][inch_ci_link] [![License][license_badge]][license_link]
 
 The Rambling Trie is a Ruby implementation of the [trie data structure][trie_wiki], which includes compression abilities and is designed to be very fast to traverse.
 
@@ -10,7 +10,7 @@ The Rambling Trie is a Ruby implementation of the [trie data structure][trie_wik
 
 You will need:
 
-* Ruby 2.1.0 or up
+* Ruby 2.5.0 or up
 * RubyGems
 
 See [RVM][rvm], [rbenv][rbenv] or [chruby][chruby] for more information on how to manage Ruby versions.
@@ -75,6 +75,12 @@ trie.add 'word'
 trie << 'word'
 ```
 
+Or if you have multiple words to add, you can use `#concat`:
+
+``` ruby
+trie.concat %w(a collection of words)
+```
+
 And to find out if a word already exists in the trie, use `#word?` or its alias `#include?`:
 
 ``` ruby
@@ -121,13 +127,20 @@ trie.compress!
 This will reduce the size of the trie by using redundant node elimination (redundant nodes are the only-child non-terminal nodes).
 
 > _**Note**: The `#compress!` method acts over the trie instance it belongs to
-> and is destructive. Also, adding words after compression (with `#add` or
+> and replaces the root `Node`. Also, adding words after compression (with `#add` or
 > `#<<`) is not supported._
 
-You can find out if a trie instance is compressed by calling the `#compressed?` method:
+If you want, you can also create a new compressed trie and leave the existing one intact. Just use `#compress` instead:
+
+``` ruby
+compressed_trie = trie.compress
+```
+
+You can find out if a trie instance is compressed by calling the `#compressed?` method. From the `#compress` example:
 
 ``` ruby
-trie.compressed?
+trie.compressed? # => false
+compressed_trie.compressed? # => true
 ```
 
 ### Enumeration
@@ -229,14 +242,17 @@ You can find further API documentation on the autogenerated [rambling-trie gem R
 
 The Rambling Trie has been tested with the following Ruby versions:
 
-* 2.4.x
-* 2.3.x
-* 2.2.x
+* 2.7.x
+* 2.6.x
+* 2.5.x
 
 **No longer supported**:
 
-* 2.1.x (might still work, but is not officially supported)
-* 2.0.x (might still work, but is not officially supported)
+* 2.4.x (EOL'ed)
+* 2.3.x (EOL'ed)
+* 2.2.x
+* 2.1.x
+* 2.0.x
 * 1.9.x
 * 1.8.x
 
@@ -268,7 +284,9 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 [github_user_gonzedge]: https://github.com/gonzedge
 [inch_ci_badge]: https://inch-ci.org/github/gonzedge/rambling-trie.svg?branch=master
 [inch_ci_link]: https://inch-ci.org/github/gonzedge/rambling-trie
-[marshal]: https://ruby-doc.org/core-2.4.0/Marshal.html
+[license_badge]: https://badges.frapsoft.com/os/mit/mit.svg?v=103
+[license_link]: https://opensource.org/licenses/mit-license.php
+[marshal]: https://ruby-doc.org/core-2.5.0/Marshal.html
 [rambling_trie_configuration]: https://github.com/gonzedge/rambling-trie#configuration
 [rambling_trie_contributing_guide]: https://github.com/gonzedge/rambling-trie/blob/master/CONTRIBUTING.md
 [rambling_trie_plain_text_reader]: https://github.com/gonzedge/rambling-trie/blob/master/lib/rambling/trie/readers/plain_text.rb
@@ -280,4 +298,4 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 [travis_ci_badge]: https://travis-ci.org/gonzedge/rambling-trie.svg
 [travis_ci_link]: https://travis-ci.org/gonzedge/rambling-trie
 [trie_wiki]: https://en.wikipedia.org/wiki/Trie
-[yaml]: https://ruby-doc.org/stdlib-2.4.0/libdoc/yaml/rdoc/YAML.html
+[yaml]: https://ruby-doc.org/stdlib-2.5.0/libdoc/yaml/rdoc/YAML.html

data/Rakefile

@@ -1,7 +1,15 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+require 'rambling-trie'
 require_relative 'tasks/performance'
+require_relative 'tasks/serialization'
+require_relative 'tasks/ips'
 
 RSpec::Core::RakeTask.new :spec
+RuboCop::RakeTask.new :rubocop
 
 task default: :spec

data/lib/rambling-trie.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'rambling/trie'

data/lib/rambling/trie.rb

@@ -1,10 +1,10 @@
-require 'forwardable'
+# frozen_string_literal: true
 
-%w{
-  comparable compressable compressor configuration container enumerable
-  inspectable invalid_operation readers serializers stringifyable node
-  missing_node compressed_node raw_node version
-}.each do |file|
+%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
 
@@ -13,23 +13,16 @@ module Rambling
   # Entry point for rambling-trie API.
   module Trie
     class << self
-      extend ::Forwardable
-
-      delegate [
-        :readers,
-        :serializers,
-        :compressor,
-        :root_builder
-      ] => :properties
-
       # 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. See
-      #   {Rambling::Trie::Readers Readers}.
+      # @param [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.
       def create filepath = nil, reader = nil
-        Rambling::Trie::Container.new root_builder.call, compressor do |container|
+        root = root_builder.call
+
+        Rambling::Trie::Container.new root, compressor do |container|
           if filepath
             reader ||= readers.resolve filepath
             reader.each_word filepath do |word|
@@ -41,12 +34,20 @@ module Rambling
         end
       end
 
-      # Loads an existing trie from disk into memory.
+      # 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
+      # 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. See {Rambling::Trie::Serializers Serializers}.
+      # @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.5.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
@@ -55,20 +56,25 @@ module Rambling
         end
       end
 
-      # Dumps an existing trie from memory into disk.
+      # 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
+      # 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}.
+      #   serializing and dumping the trie into disk.
+      # @see Rambling::Trie::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.
-      # @return [Properties] the configured properties of the gem.
-      # @yield [Properties] the configured properties of the 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
@@ -79,6 +85,22 @@ module Rambling
       def properties
         @properties ||= Rambling::Trie::Configuration::Properties.new
       end
+
+      def readers
+        properties.readers
+      end
+
+      def serializers
+        properties.serializers
+      end
+
+      def compressor
+        properties.compressor
+      end
+
+      def root_builder
+        properties.root_builder
+      end
     end
   end
 end

data/lib/rambling/trie/comparable.rb

@@ -1,11 +1,14 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     # Provides the comparable behavior for the trie data structure.
     module Comparable
       # Compares two nodes.
-      # @param [Node] other the node to compare against.
-      # @return [Boolean] `true` if the nodes' {Node#letter #letter} and
-      #   {Node#children_tree #children_tree} are equal, `false` otherwise.
+      # @param [Nodes::Node] other the node to compare against.
+      # @return [Boolean] `true` if the nodes' {Nodes::Node#letter #letter} and
+      #   {Nodes::Node#children_tree #children_tree} are equal, `false`
+      #   otherwise.
       def == other
         letter == other.letter &&
           terminal? == other.terminal? &&

data/lib/rambling/trie/compressible.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Provides the compressible behavior for the trie data structure.
+    module Compressible
+      # Indicates if the current {Rambling::Trie::Nodes::Node Node} can be
+      # compressed or not.
+      # @return [Boolean] `true` for non-{Nodes::Node#terminal? terminal} nodes
+      #   with one child, `false` otherwise.
+      def compressible?
+        !(root? || terminal?) && children_tree.size == 1
+      end
+    end
+  end
+end

data/lib/rambling/trie/compressor.rb

@@ -1,48 +1,63 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     # Responsible for the compression process of a trie data structure.
     class Compressor
-      # Compresses a {Node Node} from a trie data structure.
-      # @param [RawNode] node the node to compress.
-      # @return [CompressedNode] node the compressed version of the node.
+      # Compresses a {Nodes::Node Node} from a trie data structure.
+      # @param [Nodes::Raw] node the node to compress.
+      # @return [Nodes::Compressed] node the compressed version of the node.
       def compress node
-        if node.compressable?
-          merge_with_child_and_compress node
+        if node.compressible?
+          compress_child_and_merge node
         else
-          copy_node_and_compress_children node
+          compress_children_and_copy node
         end
       end
 
       private
 
-      def merge_with_child_and_compress node
-        child = node.children.first
+      def compress_child_and_merge node
+        merge node, compress(node.first_child)
+      end
+
+      def merge node, other
+        letter = node.letter.to_s << other.letter.to_s
 
-        letter = node.letter.to_s << child.letter.to_s
-        new_node = new_compressed_node node, letter, child.terminal?
-        new_node.children_tree = child.children_tree
+        new_compressed_node(
+          letter.to_sym,
+          node.parent,
+          other.children_tree,
+          other.terminal?,
+        )
+      end
 
-        compress new_node
+      def compress_children_and_copy node
+        new_compressed_node(
+          node.letter,
+          node.parent,
+          compress_children(node.children_tree),
+          node.terminal?,
+        )
       end
 
-      def copy_node_and_compress_children node
-        new_node = new_compressed_node node, node.letter, node.terminal?
+      def compress_children tree
+        new_tree = {}
 
-        node.children.each do |child|
+        tree.each do |letter, child|
           compressed_child = compress child
-
-          compressed_child.parent = new_node
-          new_node[compressed_child.letter] = compressed_child
+          new_tree[letter] = compressed_child
         end
 
-        new_node
+        new_tree
       end
 
-      def new_compressed_node node, letter, terminal
-        new_node = Rambling::Trie::CompressedNode.new node.parent
-        new_node.letter = letter
-        new_node.terminal! if terminal
-        new_node
+      def new_compressed_node letter, parent, tree, terminal
+        node = Rambling::Trie::Nodes::Compressed.new letter, parent, tree
+        node.terminal! if terminal
+
+        tree.each_value { |child| child.parent = node }
+        node
       end
     end
   end

data/lib/rambling/trie/configuration.rb

@@ -1,4 +1,6 @@
-%w{properties provider_collection}.each do |file|
+# frozen_string_literal: true
+
+%w(properties provider_collection).each do |file|
   require File.join('rambling', 'trie', 'configuration', file)
 end
 

data/lib/rambling/trie/configuration/properties.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     module Configuration
@@ -17,11 +19,13 @@ module Rambling
         # @return [Compressor] the configured compressor.
         attr_accessor :compressor
 
-        # The configured root_builder, which should return a {Node Node} when
-        # called.
-        # @return [Proc<Node>] the configured root_builder.
+        # The configured root_builder, which should return a {Nodes::Node Node}
+        #   when called.
+        # @return [Proc<Nodes::Node>] the configured root_builder.
         attr_accessor :root_builder
 
+        # The configured tmp_path, which will be used for throwaway files.
+        # @return [String] the configured tmp_path.
         attr_accessor :tmp_path
 
         # Returns a new properties instance.
@@ -34,9 +38,9 @@ module Rambling
           reset_readers
           reset_serializers
 
-          self.compressor = Rambling::Trie::Compressor.new
-          self.root_builder = lambda { Rambling::Trie::RawNode.new }
-          self.tmp_path = '/tmp'
+          @compressor = Rambling::Trie::Compressor.new
+          @root_builder = -> { Rambling::Trie::Nodes::Raw.new }
+          @tmp_path = '/tmp'
         end
 
         private
@@ -46,7 +50,10 @@ module Rambling
         def reset_readers
           plain_text_reader = Rambling::Trie::Readers::PlainText.new
 
-          self.readers = Rambling::Trie::Configuration::ProviderCollection.new 'reader', txt: plain_text_reader
+          @readers = Rambling::Trie::Configuration::ProviderCollection.new(
+            :reader,
+            txt: plain_text_reader,
+          )
         end
 
         def reset_serializers
@@ -54,11 +61,13 @@ module Rambling
           yaml_serializer = Rambling::Trie::Serializers::Yaml.new
           zip_serializer = Rambling::Trie::Serializers::Zip.new self
 
-          self.serializers = Rambling::Trie::Configuration::ProviderCollection.new 'serializer',
+          @serializers = Rambling::Trie::Configuration::ProviderCollection.new(
+            :serializer,
             marshal: marshal_serializer,
             yml: yaml_serializer,
             yaml: yaml_serializer,
-            zip: zip_serializer
+            zip: zip_serializer,
+          )
         end
       end
     end