rambling-trie 2.5.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c38f152f6ffdb5b7c3f5abde873ae3024651a52a7697fa4e706d01e28fe504e
-  data.tar.gz: 8cdec337b99995019a24d702b48dce2ee3e9a9e6acde298cd5cfef8086e93bc9
+  metadata.gz: 3a9d76d13a38a54c80ca90236346dcfe280fea62d46d8e9318efc8f2653b6f40
+  data.tar.gz: 0ab262b5f456d0e299fc16614bb0c7103406899b0a88dce3ef69d0d1f403fd3c
 SHA512:
-  metadata.gz: 6bbadda2f93e7efdae19f0db8749e304be56b288d62095a269904c4d6e3b6e2f7723acba618fd4e8e8de416108ca9e6249c7a6c9ce5a70e70036e6ad287cb7e2
-  data.tar.gz: b60a49628ba61bca14d5a92573df83203feb0346d306adbc628ab7dfad54da82574902ee1f4985a365582a6c5a285b788a108ee7e7d2c22b0ce3f06dc5eccf78
+  metadata.gz: 13ccb7f63311ae91544442fe75e1620ecb91ef87501150fa46f454f80b7b4d51cda69ebeb8c82e474173db815e5f536b9cf03cccb3fa8e6233facfbd7f265949
+  data.tar.gz: dfab4eaea2613f6ad5957579089056441d3f01533112fff081504da2be2e18f77267350f6cedd4c61d65d88075cf0e83d22e5124370fac45fa2dadc36b22ddcb

data/Dockerfile

@@ -1,4 +1,5 @@
-FROM ruby:3.3.6
+ARG RUBY_VERSION=3.3.6
+FROM ruby:${RUBY_VERSION}
 
 RUN bundle config --global frozen 1
 

data/Gemfile

@@ -18,6 +18,7 @@ group :test do
 end
 
 group :local do
+  gem 'benchmark', require: false
   gem 'benchmark-ips', require: false
   gem 'flamegraph', require: false
   gem 'flog', require: false
@@ -26,6 +27,7 @@ group :local do
   gem 'guard-rspec', require: false
   gem 'guard-rubocop', require: false
   gem 'guard-yard', require: false
+  gem 'irb', require: false
   gem 'mdl', require: false
   gem 'memory_profiler', require: false
   gem 'pry', require: false

data/README.md

@@ -9,9 +9,6 @@
 [![Documentation Status][inch_ci_badge]][rubydoc]
 [![CodeQL Status][github_action_codeql_badge]][github_action_codeql_link]
 
-[![Code Climate Grade][code_climate_grade_badge]][code_climate_link]
-[![Code Climate Issue Count][code_climate_issues_badge]][code_climate_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.
 
@@ -21,10 +18,10 @@ and is designed to be very fast to traverse.
 
 You will need:
 
-* Ruby 3.1.0 or up
+* Ruby 3.2.0 or up
 * RubyGems
 
-See [RVM][rvm], [rbenv][rbenv] or [chruby][chruby] for more information on how to manage Ruby versions.
+See [asdf][asdf], [RVM][rvm], [rbenv][rbenv] or [chruby][chruby] for more information on how to manage Ruby versions.
 
 ### Installation
 
@@ -77,9 +74,8 @@ trie
 ```
 
 If you want to use a custom file format, you will need to provide a custom `Reader` that defines an `#each_word` method
-that yields each word contained in the file. Look at the [`PlainText` reader][rambling_trie_plain_text_reader] class for
-an example, and at the [Configuration section][rambling_trie_configuration] to see how to add your own custom file
-readers.
+that yields each word contained in the file. Look at the [`PlainText` reader](./lib/rambling/trie/readers/plain_text.rb)
+class for an example, and at the [Configuration section](#configuration) to see how to add your own custom file readers.
 
 ### Operations
 
@@ -182,7 +178,7 @@ trie.all? { |word| word.include? 'x' }
 
 ### Serialization
 
-Starting from version 1.0.0, you can store a full trie instance on disk and retrieve/use it later on. Loading a trie
+Starting from version `1.0.0`, you can store a full trie instance on disk and retrieve/use it later on. Loading a trie
 from disk takes less time, less cpu and less memory than loading every word into the trie every time. This is
 particularly useful for production applications, when you have word lists that you know are going to be static, or that
 change with little frequency.
@@ -206,22 +202,29 @@ Currently, these formats are supported to store tries on disk:
 
 * Ruby's [binary (Marshal)][marshal] format
 * [YAML][yaml]
+* Zip version of any other format ([optional `rubyzip` dependency](#optional-rubyzip-dependency))
+
+> When dumping into or loading from disk, the format is determined automatically based on the file extension, so `.yml`
+> or `.yaml` files will be handled through `YAML` and `.marshal` files through `Marshal`.
+
+##### Optional `rubyzip` dependency
 
-> When dumping into or loading from disk, the format is determined
-> automatically based on the file extension, so `.yml` or `.yaml` files will be
-> handled through `YAML` and `.marshal` files through `Marshal`.
+Compressed versions of all other [supported formats](#supported-formats) are available via the [`rubyzip`][rubyzip] gem.
+This is an optional dependency.
 
-Optionally, you can use a `.zip` version of the supported formats. In order to do so, you'll have to install
-the [`rubyzip`][rubyzip] gem:
+> ⚠️ Rambling Trie `2.6.0` and above support `rubyzip` `3.x` only.
+> For `rubyzip` `2.x` support, use Rambling Trie `2.5.1` and below.
 
 ```shell
 gem install rubyzip
+# or gem install rubyzip --version '<3` for 2.x
 ```
 
 Or, include it in your `Gemfile` and bundle it:
 
 ```ruby
 gem 'rubyzip'
+# or gem 'rubyzip', '<3' for 2.x
 ```
 
 Then, you can load contents form a `.zip` file like this:
@@ -274,12 +277,14 @@ want edge documentation, you can go the [GitHub project RubyDoc.info page][rubyd
 
 The Rambling Trie has been tested with the following Ruby versions:
 
+* 4.0.x
+* 3.4.x
 * 3.3.x
 * 3.2.x
-* 3.1.x
 
 **No longer supported**:
 
+* 3.1.x (EOL'ed)
 * 3.0.x (EOL'ed)
 * 2.7.x (EOL'ed)
 * 2.6.x (EOL'ed)
@@ -292,9 +297,14 @@ The Rambling Trie has been tested with the following Ruby versions:
 * 1.9.x (EOL'ed)
 * 1.8.x (EOL'ed)
 
+## Compatible RBS and Steep versions
+
+Type signatures for `Rambling::Trie` are included in the [`sig` directory](./sig)! The current version (`2.7.0`) was
+checked with RBS `3.10.4` and Steep `1.10.0`.
+
 ## Contributing to Rambling Trie
 
-Take a look at the [contributing guide][rambling_trie_contributing_guide] to get started, or fire a question
+Take a look at the [contributing guide](./CONTRIBUTING.md) to get started, or fire a question
 to [@gonzedge][github_user_gonzedge].
 
 ## License and copyright
@@ -316,7 +326,8 @@ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEM
 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-[badge_fury_badge]: https://badge.fury.io/rb/rambling-trie.svg?version=2.5.1
+[asdf]: https://asdf-vm.com/
+[badge_fury_badge]: https://badge.fury.io/rb/rambling-trie.svg?version=2.7.0
 [badge_fury_link]: https://badge.fury.io/rb/rambling-trie
 [chruby]: https://github.com/postmodern/chruby
 [code_climate_grade_badge]: https://codeclimate.com/github/gonzedge/rambling-trie/badges/gpa.svg
@@ -337,9 +348,6 @@ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
 [license_link]: https://opensource.org/licenses/mit-license.php
 [marshal]: https://ruby-doc.org/3.3.0/Marshal.html
-[rambling_trie_configuration]: https://github.com/gonzedge/rambling-trie#configuration
-[rambling_trie_contributing_guide]: https://github.com/gonzedge/rambling-trie/blob/main/CONTRIBUTING.md
-[rambling_trie_plain_text_reader]: https://github.com/gonzedge/rambling-trie/blob/main/lib/rambling/trie/readers/plain_text.rb
 [rbenv]: https://github.com/sstephenson/rbenv
 [rubydoc]: http://rubydoc.info/gems/rambling-trie
 [rubydoc_github]: http://rubydoc.info/github/gonzedge/rambling-trie

data/Steepfile

@@ -13,9 +13,13 @@ target :lib do
   # check 'Rakefile'
   # check 'Steepfile'
 
-  # library 'rubyzip'
+  collection_config 'rbs_collection.yaml'
+
+  library 'rubyzip'
+  library 'rake'
   library 'yaml'
   library 'securerandom'
+  library 'tmpdir'
 
   # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
   # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting

data/lib/rambling/trie/comparable.rb

@@ -6,11 +6,13 @@ module Rambling
     module Comparable
       # Compares two nodes.
       # @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.
+      # @return [Boolean] `true` if the nodes' {Nodes::Node#letter #letter},
+      #   {Nodes::Node#terminal? #terminal?}, {Nodes::Node#value #value}, and
+      #   {Nodes::Node#children_tree #children_tree} are all equal, `false` otherwise.
       def == other
         letter == other.letter &&
           terminal? == other.terminal? &&
+          value == other.value &&
           children_tree == other.children_tree
       end
     end

data/lib/rambling/trie/compressible.rb

@@ -7,7 +7,7 @@ module Rambling
       # 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?) && 1 == children_tree.size
+        !root? && !terminal? && children_tree.one?
       end
     end
   end

data/lib/rambling/trie/compressor.rb

@@ -26,7 +26,7 @@ module Rambling
       # @param [Nodes::Node] node the node to compress.
       # @return [Nodes::Compressed] node the compressed version of the node.
       def compress_only_child_and_merge node
-        compressed_child = compress(node.first_child) # : Nodes::Compressed
+        compressed_child = compress(node.first_child) || raise(InvalidOperation, 'got nil while compressing only child')
         merge node, compressed_child
       end
 
@@ -34,21 +34,33 @@ module Rambling
         letter = node.letter.to_s << other.letter.to_s
 
         compressed = Rambling::Trie::Nodes::Compressed.new letter.to_sym, node.parent, other.children_tree
-        compressed.terminal! if other.terminal?
+        if other.terminal?
+          compressed.terminal!
+          value = other.value
+          compressed.value = value unless value.nil?
+        end
         compressed
       end
 
       def compress_children_and_copy node
         children_tree = compress_children(node.children_tree)
         compressed = Rambling::Trie::Nodes::Compressed.new node.letter, node.parent, children_tree
-        compressed.terminal! if node.terminal?
+        if node.terminal?
+          compressed.terminal!
+          value = node.value
+          compressed.value = value unless value.nil?
+        end
         compressed
       end
 
       def compress_children tree
+        # @type var new_tree: Hash[Symbol, Nodes::Node]
         new_tree = {}
 
-        tree.each { |letter, child| new_tree[letter] = compress child }
+        tree.each do |letter, child|
+          compressed_child = compress(child) || raise(InvalidOperation, "got nil while compressing #{letter}")
+          new_tree[letter] = compressed_child
+        end
 
         new_tree
       end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'tmpdir'
+
 module Rambling
   module Trie
     module Configuration
@@ -39,7 +41,7 @@ module Rambling
 
           @compressor = Rambling::Trie::Compressor.new
           @root_builder = -> { Rambling::Trie::Nodes::Raw.new }
-          @tmp_path = '/tmp'
+          @tmp_path = Dir.tmpdir
         end
 
         private

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

@@ -17,7 +17,6 @@ module Rambling
         #   providers.
         #   @param [TProvider] provider the provider to use as default.
         #   @raise [ArgumentError] when the given provider is not in the provider collection.
-        #   @note If no providers have been configured, `nil` will be assigned.
         # @return [TProvider, nil] the default provider to use when a provider cannot be resolved in
         #   {ProviderCollection#resolve #resolve}.
         attr_reader :default
@@ -25,7 +24,8 @@ module Rambling
         # Creates a new provider collection.
         # @param [Symbol] name the name for this provider collection.
         # @param [Hash<Symbol, TProvider>] providers the configured providers.
-        # @param [TProvider, nil] default the configured default provider.
+        # @param [TProvider, nil] default the configured default provider. When +nil+ (or no providers
+        #   are given), falls back to the first configured provider, or +nil+ if none exist.
         def initialize name, providers = {}, default = nil
           @name = name
           @configured_providers = providers
@@ -74,9 +74,9 @@ module Rambling
           self.default = configured_default
         end
 
-        # Get provider corresponding to a given format.
-        # @return [Array<Symbol>] the provider corresponding to that format.
-        # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-5B-5D
+        # List the formats of configured providers.
+        # @return [Array<Symbol>] the formats of all configured providers.
+        # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-keys
         #   Hash#keys
         def formats
           providers.keys
@@ -84,7 +84,7 @@ module Rambling
 
         # Get provider corresponding to a given format.
         # @param [Symbol] format the format to search for in the collection.
-        # @return [TProvider] the provider corresponding to that format.
+        # @return [TProvider, nil] the provider corresponding to that format, or +nil+ if not found.
         # @see https://ruby-doc.org/3.3.0/Hash.html#method-i-5B-5D Hash#[]
         def [] format
           providers[format]
@@ -109,7 +109,7 @@ module Rambling
         def contains? provider
           return true if provider.nil?
 
-          providers.any? && provider_instances.include?(provider || raise)
+          provider_instances.include?(provider || raise)
         end
 
         alias_method :provider_instances, :values

data/lib/rambling/trie/container.rb

@@ -22,23 +22,37 @@ module Rambling
       end
 
       # Adds a word to the trie.
-      # @param [String] word the word to add the branch from.
+      # @param [String] word the word to add to the trie.
+      # @param [Object, nil] value the value to associate with the word.
       # @return [Nodes::Node] the just added branch's root node.
       # @raise [InvalidOperation] if the trie is already compressed.
       # @see Nodes::Raw#add
       # @see Nodes::Compressed#add
-      def add word
-        root.add reversed_char_symbols word
+      def add word, value = nil
+        root.add reversed_char_symbols(word), value
       end
 
       # Adds all provided words to the trie.
-      # @param [Array<String>] words the words to add the branch from.
+      # @param [Array<String>] words the words to add to the trie.
+      # @param [Array<Object>, nil] values the values to associate with each word, in the same order.
       # @return [Array<Nodes::Node>] the collection of nodes added.
       # @raise [InvalidOperation] if the trie is already compressed.
+      # @raise [ArgumentError] if words and values are given but differ in size.
       # @see Nodes::Raw#add
       # @see Nodes::Compressed#add
-      def concat words
-        words.map { |word| add word }
+      def concat words, values = nil
+        if values
+          words_size = words.size
+          values_size = values.size
+          unless words_size == values_size
+            raise ArgumentError,
+              "words and values must have the same size (words: #{words_size}, values: #{values_size})"
+          end
+
+          words.each_with_index.map { |word, index| add(word, values[index]) }
+        else
+          words.map { |word| add word }
+        end
       end
 
       # Compresses the existing trie using redundant node elimination.
@@ -52,10 +66,18 @@ module Rambling
       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.
+      # @return [Container] A new {Container} with the {Nodes::Compressed Compressed} root node.
+      # @deprecated Calling {#compress} on an already-compressed trie is deprecated and will raise
+      #   {InvalidOperation} in the next major version. Use {#compressed?} to guard if needed.
       def compress
-        return self if root.compressed?
+        if root.compressed?
+          warn <<~WARN.chomp.tr("\n", ' ')
+            [DEPRECATED] Calling `compress` on an already-compressed trie is deprecated
+            and will raise `InvalidOperation` in the next major version.
+            Called from #{caller_locations(1, 1)&.first}
+          WARN
+          return Rambling::Trie::Container.new root, compressor
+        end
 
         Rambling::Trie::Container.new compress_root, compressor
       end
@@ -69,7 +91,7 @@ module Rambling
       end
 
       # Adds all provided words to the trie.
-      # @param [Array<String>] words the words to add the branch from.
+      # @param [String] words the words to add to the trie.
       # @return [Array<Nodes::Node>] the collection of nodes added.
       # @raise [InvalidOperation] if the trie is already compressed.
       # @see #concat
@@ -99,7 +121,6 @@ module Rambling
       # Returns all words within a string that match a word contained in the trie.
       # @param [String] phrase the string to look for matching words in.
       # @return [Array<String>] all the words in the given string that match a word in the trie.
-      # @yield [String] each word found in phrase.
       def words_within phrase
         words_within_root(phrase).to_a
       end
@@ -126,6 +147,8 @@ module Rambling
         return enum_for :each unless block_given?
 
         root.each { |word| yield word }
+
+        self
       end
 
       # @return [String] a string representation of the container.
@@ -177,8 +200,8 @@ module Rambling
         root.key? letter
       end
 
-      # Size of the Root {Nodes::Node Node}'s children tree.
-      # @return [Integer] the number of letters in the root node.
+      # Number of words contained in the trie.
+      # @return [Integer] the number of words stored in the trie.
       def size
         root.size
       end
@@ -199,21 +222,23 @@ module Rambling
         return enum_for :words_within_root, phrase unless block_given?
 
         chars = phrase.chars
-        size = chars.length
-        # rubocop:disable Style/CommentedKeyword
-        0.upto(size - 1).each do |starting_index|
-          new_phrase = chars.slice starting_index, size # : Array[String]
+        chars.each_index do |starting_index|
+          new_phrase = chars[starting_index..] || raise
           root.match_prefix(new_phrase) { |word| yield word }
-        end # : Enumerator[String, void]
-        # rubocop:enable Style/CommentedKeyword
+        end
+
+        self
       end
 
       def compress_root
-        compressor.compress root # : Nodes::Compressed
+        compressor.compress(root) || raise
       end
 
       def reversed_char_symbols word
-        word.reverse.chars.map(&:to_sym).to_a
+        # @type var chars: Array[String]
+        chars = word.chars
+        chars.reverse!
+        chars.map(&:to_sym)
       end
     end
   end

data/lib/rambling/trie/enumerable.rb

@@ -6,9 +6,6 @@ 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
@@ -25,6 +22,14 @@ module Rambling
 
         self
       end
+
+      # Returns a new empty enumerator for early-exit returns.
+      # A method rather than a constant to prevent shared mutable state.
+      def empty_enum
+        # @type var empty_array: Array[String]
+        empty_array = []
+        empty_array.each
+      end
     end
   end
 end

data/lib/rambling/trie/inspectable.rb

@@ -18,15 +18,20 @@ module Rambling
       def attributes
         [
           letter_inspect,
+          value_inspect,
           terminal_inspect,
           children_inspect,
-        ].join ', '
+        ].compact.join ', '
       end
 
       def letter_inspect
         "letter: #{letter.inspect}"
       end
 
+      def value_inspect
+        value && "value: #{value.inspect}"
+      end
+
       def terminal_inspect
         "terminal: #{terminal.inspect}"
       end

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

@@ -3,7 +3,7 @@
 module Rambling
   module Trie
     module Nodes
-      # A representation of a node in an compressed trie data structure.
+      # A representation of a node in a compressed trie data structure.
       # :reek:RepeatedConditional { max_ifs: 4 }
       class Compressed < Rambling::Trie::Nodes::Node
         # Creates a new compressed node.
@@ -19,10 +19,10 @@ module Rambling
 
         # 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.
-        # @raise [InvalidOperation] if the trie is already compressed.
-        # @return [void]
-        def add _
+        # @param [Array<Symbol>] _word the word chars to add to the trie.
+        # @param [Object, nil] _value the value to associate with the word.
+        # @raise [InvalidOperation] always.
+        def add _word, _value = nil
           raise Rambling::Trie::InvalidOperation, 'Cannot add word to compressed trie'
         end
 
@@ -42,12 +42,12 @@ module Rambling
 
           if chars.size >= child_letter.size
             letter = (chars.shift(child_letter.size) || raise).join
-            return child.partial_word? chars if child_letter == letter
-          end
+            return false unless child_letter == letter
 
-          letter = chars.join
-          child_letter = child_letter.slice 0, letter.size
-          child_letter == letter
+            child.partial_word? chars
+          else
+            child_letter.start_with? chars.join
+          end
         end
 
         def word_chars? chars
@@ -75,29 +75,37 @@ module Rambling
 
           child_letter = child.letter.to_s
 
-          if chars.size >= child_letter.size
-            letter = (chars.shift(child_letter.size) || raise).join
-            return child.scan chars if child_letter == letter
+          if chars.size < child_letter.size
+            return child_letter.start_with?(chars.join) ? child : missing
           end
 
-          letter = chars.join
-          child_letter = child_letter.slice 0, letter.size
+          letter = (chars.shift(child_letter.size) || raise).join
+          return missing unless child_letter == letter
 
-          child_letter == letter ? child : missing
+          child.scan chars
         end
 
         def children_match_prefix chars
           return enum_for :children_match_prefix, chars unless block_given?
 
-          return EMPTY_ENUMERATOR if chars.empty?
+          return empty_enum if chars.empty?
 
           child = children_tree[(chars.first || raise).to_sym]
-          return EMPTY_ENUMERATOR unless child
+          return empty_enum unless child
 
+          match_child_prefix(child, chars) { |word| yield word }
+        end
+
+        def match_child_prefix child, chars
           child_letter = child.letter.to_s
+
+          # stop early if we already know that the remaining characters in the
+          # given phrase do not even cover the current node's compressed key
+          return empty_enum if chars.size < child_letter.size
+
           letter = (chars.shift(child_letter.size) || raise).join
 
-          return EMPTY_ENUMERATOR unless child_letter == letter
+          return empty_enum unless child_letter == letter
 
           child.match_prefix(chars) { |word| yield word }
         end

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

@@ -5,6 +5,23 @@ module Rambling
     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
+        def partial_word? _
+          false
+        end
+
+        private
+
+        def word_chars? _
+          false
+        end
+
+        def closest_node _
+          self
+        end
+
+        def children_match_prefix chars
+          enum_for :children_match_prefix, chars unless block_given?
+        end
       end
     end
   end