rambling-trie-opal 2.1.1

data/lib/rambling/trie/comparable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Provides the comparable behavior for the trie data structure.
+    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.
+      def == other
+        letter == other.letter &&
+          terminal? == other.terminal? &&
+          children_tree == other.children_tree
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Responsible for the compression process of a trie data structure.
+    class Compressor
+      # 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.compressible?
+          compress_child_and_merge node
+        else
+          compress_children_and_copy node
+        end
+      end
+
+      private
+
+      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
+
+        new_compressed_node(
+          letter.to_sym,
+          node.parent,
+          other.children_tree,
+          other.terminal?,
+        )
+      end
+
+      def compress_children_and_copy node
+        new_compressed_node(
+          node.letter,
+          node.parent,
+          compress_children(node.children_tree),
+          node.terminal?,
+        )
+      end
+
+      def compress_children tree
+        new_tree = {}
+
+        tree.each do |letter, child|
+          compressed_child = compress child
+          new_tree[letter] = compressed_child
+        end
+
+        new_tree
+      end
+
+      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
+end

data/lib/rambling/trie/configuration.rb

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

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+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 {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.
+        def initialize
+          reset
+        end
+
+        # Resets back to default properties.
+        def reset
+          reset_readers
+          reset_serializers
+
+          @compressor = Rambling::Trie::Compressor.new
+          @root_builder = -> { Rambling::Trie::Nodes::Raw.new }
+          @tmp_path = '/tmp'
+        end
+
+        private
+
+        attr_writer :readers, :serializers
+
+        def reset_readers
+          plain_text_reader = Rambling::Trie::Readers::PlainText.new
+
+          @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
+
+          @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,122 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Configuration
+      # Collection of configurable providers.
+      class ProviderCollection
+        # 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
+
+        # 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
+          unless contains? 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[file_format filepath] || default
+        end
+
+        # Resets the provider collection to the initial values.
+        def reset
+          providers.clear
+          configured_providers.each { |k, v| self[k] = v }
+          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/core-2.5.0/Hash.html#method-i-5B-5D
+        #   Hash#keys
+        def formats
+          providers.keys
+        end
+
+        # Get provider corresponding to a given format.
+        # @param [Symbol] format the format to search for in the collection.
+        # @return [Object] the provider corresponding to that format.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-5B-5D
+        #   Hash#[]
+        def [] format
+          providers[format]
+        end
+
+        private
+
+        attr_reader :configured_providers, :configured_default
+
+        def []= format, instance
+          providers[format] = instance
+        end
+
+        def values
+          providers.values
+        end
+
+        def file_format filepath
+          format = File.extname filepath
+          format.slice! 0
+          format.to_sym
+        end
+
+        def contains? provider
+          provider.nil? ||
+            (providers.any? && provider_instances.include?(provider))
+        end
+
+        alias_method :provider_instances, :values
+      end
+    end
+  end
+end

data/lib/rambling/trie/container.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    # Wrapper on top of trie data structure.
+    class Container
+      include ::Enumerable
+
+      # The root node of this trie.
+      # @return [Nodes::Node] the root node of this trie.
+      attr_reader :root
+
+      # Creates a new trie.
+      # @param [Nodes::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, compressor
+        @root = root
+        @compressor = compressor
+
+        yield self if block_given?
+      end
+
+      # Adds a word to the trie.
+      # @param [String] word the word to add the branch from.
+      # @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 char_symbols word
+      end
+
+      # Adds all provided words to the trie.
+      # @param [Array<String>] words the words to add the branch from.
+      # @return [Array<Nodes::Node>] the collection of nodes added.
+      # @raise [InvalidOperation] if the trie is already compressed.
+      # @see Nodes::Raw#add
+      # @see Nodes::Compressed#add
+      def concat words
+        words.map { |word| add word }
+      end
+
+      # Compresses the existing trie using redundant node elimination. Marks
+      # the trie as compressed. Does nothing if the trie has already been
+      # compressed.
+      # @return [Container] self
+      # @note This method replaces the root {Nodes::Raw Raw} node with a
+      #   {Nodes::Compressed Compressed} version of it.
+      def compress!
+        self.root = compress_root unless root.compressed?
+        self
+      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.
+      def compress
+        return self if root.compressed?
+        Rambling::Trie::Container.new compress_root, compressor
+      end
+
+      # 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.
+      # @see Nodes::Raw#partial_word?
+      # @see Nodes::Compressed#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, `false` otherwise.
+      # @see Nodes::Raw#word?
+      # @see Nodes::Compressed#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<String>] all the words contained in the trie that start
+      #   with the specified characters.
+      # @see Nodes::Raw#scan
+      # @see Nodes::Compressed#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 Nodes::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
+
+      # Iterates over the words contained in the trie.
+      # @yield [String] the words contained in this trie node.
+      def each
+        return enum_for :each unless block_given?
+
+        root.each do |word|
+          yield word
+        end
+      end
+
+      # @return [String] a string representation of the container.
+      def inspect
+        "#<#{self.class.name} root: #{root.inspect}>"
+      end
+
+      # Get {Nodes::Node Node} corresponding to a given letter.
+      # @param [Symbol] letter the letter to search for in the root node.
+      # @return [Nodes::Node] the node corresponding to that letter.
+      # @see Nodes::Node#[]
+      def [] letter
+        root[letter]
+      end
+
+      # Root node's child nodes.
+      # @return [Array<Nodes::Node>] the array of children nodes contained in
+      #   the root node.
+      # @see Nodes::Node#children
+      def children
+        root.children
+      end
+
+      # Root node's children tree.
+      # @return [Array<Nodes::Node>] the array of children nodes contained in
+      #   the root node.
+      # @see Nodes::Node#children_tree
+      def children_tree
+        root.children_tree
+      end
+
+      # Indicates if the root {Nodes::Node Node} can be
+      # compressed or not.
+      # @return [Boolean] `true` for non-{Nodes::Node#terminal? terminal}
+      #    nodes with one child, `false` otherwise.
+      def compressed?
+        root.compressed?
+      end
+
+      # Array of words contained in the root {Nodes::Node Node}.
+      # @return [Array<String>] all words contained in this trie.
+      # @see https://ruby-doc.org/core-2.5.0/Enumerable.html#method-i-to_a
+      #   Enumerable#to_a
+      def to_a
+        root.to_a
+      end
+
+      # Check if a letter is part of the root {Nodes::Node}'s children tree.
+      # @param [Symbol] letter the letter to search for in the root node.
+      # @return [Boolean] whether the letter is contained or not.
+      # @see Nodes::Node#key?
+      def key? letter
+        root.key? letter
+      end
+
+      # Size of the Root {Nodes::Node Node}'s children tree.
+      # @return [Integer] the number of letters in the root node.
+      def size
+        root.size
+      end
+
+      alias_method :include?, :word?
+      alias_method :match?, :partial_word?
+      alias_method :words, :scan
+      alias_method :<<, :add
+      alias_method :has_key?, :key?
+      alias_method :has_letter?, :key?
+
+      private
+
+      attr_reader :compressor
+      attr_writer :root
+
+      def words_within_root phrase
+        return enum_for :words_within_root, phrase unless block_given?
+
+        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
+
+      def compress_root
+        compressor.compress root
+      end
+
+      def char_symbols word
+        symbols = []
+        word.reverse.each_char { |c| symbols << c.to_sym }
+        symbols
+      end
+    end
+  end
+end