rambling-trie 0.9.3 → 1.0.0

data/lib/rambling/trie/compressor.rb

@@ -1,10 +1,10 @@
 module Rambling
   module Trie
-    # Responsible for the compression process of a Trie data structure.
+    # Responsible for the compression process of a trie data structure.
     class Compressor
-      # Compresses a node from a Trie data structure.
-      # @param [RawNode] node the node to compress
-      # @return [CompressedNode] node the compressed version of the node
+      # 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.
       def compress node
         if node.compressable?
           merge_with_child_and_compress node
@@ -18,18 +18,15 @@ module Rambling
       def merge_with_child_and_compress node
         child = node.children.first
 
-        new_node = Rambling::Trie::CompressedNode.new node.parent
-        new_node.letter = node.letter.to_s << child.letter.to_s
-        new_node.terminal! if child.terminal?
+        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
 
         compress new_node
       end
 
       def copy_node_and_compress_children node
-        new_node = Rambling::Trie::CompressedNode.new node.parent
-        new_node.letter = node.letter
-        new_node.terminal! if node.terminal?
+        new_node = new_compressed_node node, node.letter, node.terminal?
 
         node.children.each do |child|
           compressed_child = compress child
@@ -40,6 +37,13 @@ module Rambling
 
         new_node
       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
+      end
     end
   end
 end

data/lib/rambling/trie/configuration.rb

@@ -0,0 +1,11 @@
+%w{properties provider_collection}.each do |file|
+  require File.join('rambling', 'trie', 'configuration', file)
+end
+
+module Rambling
+  module Trie
+    # Namespace for configuration classes.
+    module Configuration
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+module Rambling
+  module Trie
+    module Configuration
+      # Provides configurable properties for Rambling::Trie.
+      class Properties
+        # The configured {Readers Readers}.
+        # @return [ProviderCollection] the mapping of configured {Readers
+        #   Readers}.
+        attr_reader :readers
+
+        # The configured {Serializers Serializers}.
+        # @return [ProviderCollection] the mapping of configured {Serializers
+        #   Serializers}.
+        attr_reader :serializers
+
+        # The configured {Compressor Compressor}.
+        # @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.
+        attr_accessor :root_builder
+
+        attr_accessor :tmp_path
+
+        # Returns a new properties instance.
+        def initialize
+          reset
+        end
+
+        # Resets back to default properties.
+        def reset
+          reset_readers
+          reset_serializers
+
+          self.compressor = Rambling::Trie::Compressor.new
+          self.root_builder = lambda { Rambling::Trie::RawNode.new }
+          self.tmp_path = '/tmp'
+        end
+
+        private
+
+        attr_writer :readers, :serializers
+
+        def reset_readers
+          plain_text_reader = Rambling::Trie::Readers::PlainText.new
+
+          self.readers = Rambling::Trie::Configuration::ProviderCollection.new 'reader', txt: plain_text_reader
+        end
+
+        def reset_serializers
+          marshal_serializer = Rambling::Trie::Serializers::Marshal.new
+          yaml_serializer = Rambling::Trie::Serializers::Yaml.new
+          zip_serializer = Rambling::Trie::Serializers::Zip.new self
+
+          self.serializers = Rambling::Trie::Configuration::ProviderCollection.new 'serializer',
+            marshal: marshal_serializer,
+            yml: yaml_serializer,
+            yaml: yaml_serializer,
+            zip: zip_serializer
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+module Rambling
+  module Trie
+    module Configuration
+      # Collection of configurable providers.
+      class ProviderCollection
+        extend Rambling::Trie::Forwardable
+
+        # The name of this provider collection.
+        # @return [String] the name of this provider collection.
+        attr_reader :name
+
+        # @overload default
+        #   The default provider. Used when a provider cannot be resolved in
+        #   {ProviderCollection#resolve #resolve}.
+        # @overload default=(provider)
+        #   Sets the default provider. Needs to be one of the configured
+        #   providers.
+        #   @param [Object] 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 [Object, nil] the default provider to use when a provider
+        #   cannot be resolved in {ProviderCollection#resolve #resolve}.
+        attr_reader :default
+
+        delegate [
+          :[],
+          :[]=,
+          :keys,
+          :values,
+        ] => :providers
+
+        # Creates a new provider collection.
+        # @param [String] name the name for this provider collection.
+        # @param [Hash] providers the configured providers.
+        # @param [Object] default the configured default provider.
+        def initialize name, providers = {}, default = nil
+          @name = name
+          @configured_providers = providers
+          @configured_default = default || providers.values.first
+
+          reset
+        end
+
+        # Adds a new provider to the provider collection.
+        # @param [Symbol] extension the extension that the provider will
+        #   correspond to.
+        # @param [provider] provider the provider to add to the provider
+        #   collection.
+        def add extension, provider
+          providers[extension] = provider
+        end
+
+        def default= provider
+          if provider_not_in_list? provider
+            raise ArgumentError, "default #{name} should be part of configured #{name}s"
+          end
+
+          @default = provider
+        end
+
+        # List of configured providers.
+        # @return [Hash] the mapping of extensions to their corresponding
+        #   providers.
+        def providers
+          @providers ||= {}
+        end
+
+        # Resolves the provider from a filepath based on the file extension.
+        # @param [String] filepath the filepath to resolve into a provider.
+        # @return [Object] the provider corresponding to the file extension in
+        #   this provider collection. {#default} if not found.
+        def resolve filepath
+          providers[format filepath] || default
+        end
+
+        # Resets the provider collection to the initial values.
+        def reset
+          providers.clear
+          configured_providers.each { |k, v| providers[k] = v }
+          self.default = configured_default
+        end
+
+        private
+
+        attr_reader :configured_providers, :configured_default
+
+        def format filepath
+          format = File.extname filepath
+          format.slice! 0
+          format.to_sym
+        end
+
+        def provider_not_in_list? provider
+          (provider && providers.values.empty?) ||
+            (providers.values.any? && !providers.values.include?(provider))
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/container.rb

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    # Wrapper on top of Trie data structure.
+    # Wrapper on top of trie data structure.
     class Container
       extend Rambling::Trie::Forwardable
       include ::Enumerable
@@ -25,32 +25,32 @@ module Rambling
       # @return [Node] the root node of this trie.
       attr_reader :root
 
-      # Creates a new Trie.
+      # Creates a new trie.
       # @param [Node] root the root node for the trie
       # @param [Compressor] compressor responsible for compressing the trie
       # @yield [Container] the trie just created.
-      def initialize root = nil, compressor = nil
-        @root = root || default_root
-        @compressor = compressor || default_compressor
+      def initialize root, compressor
+        @root = root
+        @compressor = compressor
 
         yield self if block_given?
       end
 
-      # Adds a branch to the trie based on the word, without changing the passed word.
+      # Adds a word to the trie, without altering the passed word.
       # @param [String] word the word to add the branch from.
       # @return [Node] the just added branch's root node.
       # @raise [InvalidOperation] if the trie is already compressed.
       # @see RawNode#add
       # @see CompressedNode#add
-      # @note Avoids clearing the contents of the word variable.
+      # @note Avoids altering the contents of the word variable.
       def add word
         root.add word.clone
       end
 
-      # Compresses the existing tree using redundant node elimination. Flags
+      # Compresses the existing tree using redundant node elimination. Marks
       # the trie as compressed.
       # @return [Container] self
-      # @note Avoids compressing again if the trie has already been compressed.
+      # @note Only compresses tries that have not already been compressed.
       def compress!
         self.root = compressor.compress root unless root.compressed?
         self
@@ -58,25 +58,61 @@ module Rambling
 
       # Checks if a path for a word or partial word exists in the trie.
       # @param [String] word the word or partial word to look for in the trie.
-      # @return [Boolean] `true` if the word or partial word is found, `false` otherwise.
+      # @return [Boolean] `true` if the word or partial word is found, `false`
+      #   otherwise.
+      # @see RawNode#partial_word?
+      # @see CompressedNode#partial_word?
       def partial_word? word = ''
         root.partial_word? word.chars
       end
 
       # Checks if a whole word exists in the trie.
       # @param [String] word the word to look for in the trie.
-      # @return [Boolean] `true` only if the word is found and the last character corresponds to a terminal node.
+      # @return [Boolean] `true` only if the word is found and the last
+      #   character corresponds to a terminal node, `false` otherwise.
+      # @see RawNode#word?
+      # @see CompressedNode#word?
       def word? word = ''
         root.word? word.chars
       end
 
       # Returns all words that start with the specified characters.
       # @param [String] word the word to look for in the trie.
-      # @return [Array] all the words contained in the trie that start with the specified characters.
+      # @return [Array<String>] all the words contained in the trie that start
+      #   with the specified characters.
+      # @see RawNode#scan
+      # @see CompressedNode#scan
       def scan word = ''
         root.scan(word.chars).to_a
       end
 
+      # 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 [Enumerator<String>] all the words in the given string that
+      #   match a word in the trie.
+      # @yield [String] each word found in phrase.
+      # @see Node#words_within
+      def words_within phrase
+        words_within_root(phrase).to_a
+      end
+
+      # Checks if there are any valid words in a given string.
+      # @param [String] phrase the string to look for matching words in.
+      # @return [Boolean] `true` if any word within phrase is contained in the
+      #   trie, `false` otherwise.
+      # @see Container#words_within
+      def words_within? phrase
+        words_within_root(phrase).any?
+      end
+
+      # Compares two trie data structures.
+      # @param [Container] other the trie to compare against.
+      # @return [Boolean] `true` if the tries are equal, `false` otherwise.
+      def == other
+        root == other.root
+      end
+
       alias_method :include?, :word?
       alias_method :match?, :partial_word?
       alias_method :words, :scan
@@ -87,12 +123,16 @@ module Rambling
       attr_reader :compressor
       attr_writer :root
 
-      def default_root
-        Rambling::Trie::RawNode.new
-      end
+      def words_within_root phrase
+        return enum_for :words_within_root, phrase unless block_given?
 
-      def default_compressor
-        Rambling::Trie::Compressor.new
+        chars = phrase.chars
+        0.upto(chars.length - 1).each do |starting_index|
+          new_phrase = chars.slice starting_index..(chars.length - 1)
+          root.match_prefix new_phrase do |word|
+            yield word
+          end
+        end
       end
     end
   end

data/lib/rambling/trie/enumerable.rb

@@ -1,6 +1,6 @@
 module Rambling
   module Trie
-    # Provides enumerable behavior to the Trie data structure.
+    # Provides enumerable behavior to the trie data structure.
     module Enumerable
       include ::Enumerable
 

data/lib/rambling/trie/forwardable.rb

@@ -1,12 +1,17 @@
 module Rambling
   module Trie
-    # Provides delegation behavior
+    # Provides delegation behavior.
     module Forwardable
-      def delegate delegated_methods_to_delegated_to
-        delegated_methods_to_delegated_to.each do |methods, delegated_to|
+      # Custom delegation behavior due to Ruby 2.4 delegation performance
+      # degradation. See {https://bugs.ruby-lang.org/issues/13111 Bug #13111}.
+      # @param [Hash] methods_to_target a Hash consisting of the methods to be
+      #   delegated and the target to delegate those methods to.
+      # @return [Hash] the `methods_to_target` parameter.
+      def delegate methods_to_target
+        methods_to_target.each do |methods, target|
           methods.each do |method|
             define_method method do |*args|
-              send(delegated_to).send method, *args
+              send(target).send method, *args
             end
           end
         end

data/lib/rambling/trie/inspectable.rb

@@ -0,0 +1,37 @@
+module Rambling
+  module Trie
+    # Provides pretty printing behavior for the trie data structure.
+    module Inspectable
+      # @return [String] a string representation of the current node.
+      def inspect
+        "#<#{class_name} #{attributes}>"
+      end
+
+      private
+
+      def class_name
+        self.class.name
+      end
+
+      def attributes
+        [
+          letter_inspect,
+          terminal_inspect,
+          children_inspect,
+        ].join ', '
+      end
+
+      def letter_inspect
+        "letter: #{letter.inspect}"
+      end
+
+      def terminal_inspect
+        "terminal: #{terminal.inspect}"
+      end
+
+      def children_inspect
+        "children: #{children_tree.keys.inspect}"
+      end
+    end
+  end
+end

data/lib/rambling/trie/invalid_operation.rb

@@ -1,8 +1,9 @@
 module Rambling
   module Trie
-    # Raised when trying to execute an invalid operation on a Trie data structure.
+    # Raised when trying to execute an invalid operation on a trie data
+    # structure.
     class InvalidOperation < Exception
-      # Creates a new InvalidOperation exception.
+      # Creates a new {InvalidOperation InvalidOperation} exception.
       # @param [String, nil] message the exception message.
       def initialize message = nil
         super