rambling-trie 1.0.2 → 2.2.0

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Nodes
+      # A representation of a node in the trie data structure.
+      class Node
+        include Rambling::Trie::Compressible
+        include Rambling::Trie::Enumerable
+        include Rambling::Trie::Comparable
+        include Rambling::Trie::Stringifyable
+        include Rambling::Trie::Inspectable
+
+        # @overload letter
+        #   Letter(s) corresponding to the current node.
+        # @overload letter=(letter)
+        #   Sets the letter(s) corresponding to the current node. Ensures the
+        #   {Node#letter #letter} in the {Node#parent #parent}'s
+        #   {Node#children_tree #children_tree} is updated.
+        #   @param [String, Symbol, nil] letter the letter value.
+        # @return [Symbol, nil] the corresponding letter(s).
+        attr_reader :letter
+
+        # Child nodes tree.
+        # @return [Hash] the children_tree hash, consisting of `:letter =>
+        #   node`.
+        attr_accessor :children_tree
+
+        # Parent node.
+        # @return [Node, nil] the parent of the current node.
+        attr_accessor :parent
+
+        # Creates a new node.
+        # @param [Symbol, nil] letter the Node's letter value
+        # @param [Node, nil] parent the parent of the current node.
+        def initialize letter = nil, parent = nil, children_tree = {}
+          @letter = letter
+          @parent = parent
+          @children_tree = children_tree
+        end
+
+        # Child nodes.
+        # @return [Array<Node>] the array of children nodes contained
+        #   in the current node.
+        def children
+          children_tree.values
+        end
+
+        # First child node.
+        # @return [Node, nil] the first child contained in the current node.
+        def first_child
+          return if children_tree.empty?
+
+          children_tree.each_value do |child|
+            return child
+          end
+        end
+
+        # Indicates if the current node is the root node.
+        # @return [Boolean] `true` if the node does not have a parent, `false`
+        #   otherwise.
+        def root?
+          !parent
+        end
+
+        # Indicates if a {Node Node} is terminal or not.
+        # @return [Boolean] `true` for terminal nodes, `false` otherwise.
+        def terminal?
+          !!terminal
+        end
+
+        # Mark {Node Node} as terminal.
+        # @return [Node] the modified node.
+        def terminal!
+          self.terminal = true
+          self
+        end
+
+        def letter= letter
+          @letter = letter.to_sym if letter
+        end
+
+        # Checks if a path for a set of characters exists in the trie.
+        # @param [Array<String>] chars the characters to look for in the trie.
+        # @return [Boolean] `true` if the characters are found, `false`
+        #   otherwise.
+        def partial_word? chars
+          return true if chars.empty?
+
+          partial_word_chars? chars
+        end
+
+        # Checks if a path for set of characters represents a word in the trie.
+        # @param [Array<String>] chars the characters to look for in the trie.
+        # @return [Boolean] `true` if the characters are found and form a word,
+        #   `false` otherwise.
+        def word? chars = []
+          return terminal? if chars.empty?
+
+          word_chars? chars
+        end
+
+        # Returns the node that starts with the specified characters.
+        # @param [Array<String>] chars the characters to look for in the trie.
+        # @return [Node] the node that matches the specified characters.
+        #   {Missing Missing} when not found.
+        def scan chars
+          return self if chars.empty?
+
+          closest_node chars
+        end
+
+        # Returns all words that match a prefix of any length within chars.
+        # @param [String] chars the chars to base the prefix on.
+        # @return [Enumerator<String>] all the words that match a prefix given
+        #   by chars.
+        # @yield [String] each word found.
+        def match_prefix chars
+          return enum_for :match_prefix, chars unless block_given?
+
+          yield as_word if terminal?
+
+          children_match_prefix chars do |word|
+            yield word
+          end
+        end
+
+        # Get {Node Node} corresponding to a given letter.
+        # @param [Symbol] letter the letter to search for in the node.
+        # @return [Node] the node corresponding to that letter.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-5B-5D
+        #   Hash#[]
+        def [] letter
+          children_tree[letter]
+        end
+
+        # Set the {Node Node} that corresponds to a given letter.
+        # @param [Symbol] letter the letter to insert or update in the node's
+        # @param [Node] node the {Node Node} to assign to that letter.
+        # @return [Node] the node corresponding to the inserted or
+        #   updated letter.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-5B-5D
+        #   Hash#[]
+        def []= letter, node
+          children_tree[letter] = node
+        end
+
+        # Check if a {Node Node}'s children tree contains a given
+        #   letter.
+        # @param [Symbol] letter the letter to search for in the node.
+        # @return [Boolean] `true` if the letter is present, `false` otherwise
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-has_key-3F
+        #   Hash#key?
+        def key? letter
+          children_tree.key? letter
+        end
+
+        # Delete a given letter and its corresponding {Node Node} from
+        #   this {Node Node}'s children tree.
+        # @param [Symbol] letter the letter to delete from the node's children
+        #   tree.
+        # @return [Node] the node corresponding to the deleted letter.
+        # @see https://ruby-doc.org/core-2.5.0/Hash.html#method-i-delete
+        #   Hash#delete
+        def delete letter
+          children_tree.delete letter
+        end
+
+        alias_method :has_key?, :key?
+
+        protected
+
+        def missing
+          Rambling::Trie::Nodes::Missing.new
+        end
+
+        private
+
+        attr_accessor :terminal
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Rambling
+  module Trie
+    module Nodes
+      # A representation of a node in an uncompressed trie data structure.
+      class Raw < Rambling::Trie::Nodes::Node
+        # Adds a word to the current raw (uncompressed) trie node.
+        # @param [Array<Symbol>] chars the char array to add to the trie.
+        # @return [Raw] the added/modified node based on the word added.
+        # @note This method clears the contents of the chars variable.
+        def add chars
+          if chars.empty?
+            terminal!
+          else
+            add_to_children_tree chars
+          end
+        end
+
+        # Always return `false` for a raw (uncompressed) node.
+        # @return [Boolean] always `false` for a raw (uncompressed) node.
+        def compressed?
+          false
+        end
+
+        private
+
+        def add_to_children_tree chars
+          letter = chars.pop
+          child = children_tree[letter] || new_node(letter)
+          child.add chars
+          child
+        end
+
+        def new_node letter
+          node = Rambling::Trie::Nodes::Raw.new letter, self
+          children_tree[letter] = node
+          node
+        end
+
+        def partial_word_chars? chars = []
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+          return false unless child
+
+          child.partial_word? chars
+        end
+
+        def word_chars? chars = []
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+          return false unless child
+
+          child.word? chars
+        end
+
+        def closest_node chars
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+          return missing unless child
+
+          child.scan chars
+        end
+
+        def children_match_prefix chars
+          return enum_for :children_match_prefix, chars unless block_given?
+
+          return if chars.empty?
+
+          letter = chars.shift.to_sym
+          child = children_tree[letter]
+
+          return unless child
+
+          child.match_prefix chars do |word|
+            yield word
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/readers.rb

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

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     module Readers
@@ -8,17 +10,7 @@ module Rambling
         #   from.
         # @yield [String] Each line read from the file.
         def each_word filepath
-          each_line(filepath) { |line| yield line.chomp! }
-        end
-
-        private
-
-        def each_line filepath
-          open(filepath) { |file| file.each_line { |line| yield line } }
-        end
-
-        def open filepath
-          File.open(filepath) { |file| yield file }
+          File.foreach(filepath) { |line| yield line.chomp! }
         end
       end
     end

data/lib/rambling/trie/serializers.rb

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

data/lib/rambling/trie/serializers/file.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     module Serializers

data/lib/rambling/trie/serializers/marshal.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     module Serializers
@@ -11,20 +13,28 @@ module Rambling
         end
 
         # Loads marshaled object from contents in filepath and deserializes it
-        # into a {Node Node}.
+        # into a {Nodes::Node Node}.
         # @param [String] filepath the full path of the file to load the
         #   marshaled object from.
-        # @return [Node] The deserialized {Node Node}.
+        # @return [Nodes::Node] The deserialized {Nodes::Node Node}.
+        # @see https://ruby-doc.org/core-2.5.0/Marshal.html#method-c-load
+        #   Marshal.load
+        # @note Use of
+        #   {https://ruby-doc.org/core-2.5.0/Marshal.html#method-c-load
+        #   Marshal.load} is generally discouraged. Only use this with trusted
+        #   input.
         def load filepath
           ::Marshal.load serializer.load filepath
         end
 
-        # Serializes a {Node Node} and dumps it as a marshaled object into
-        # filepath.
-        # @param [Node] node the node to serialize
+        # Serializes a {Nodes::Node Node} and dumps it as a marshaled object
+        # into filepath.
+        # @param [Nodes::Node] node the node to serialize
         # @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
+        #   Marshal.dump
         def dump node, filepath
           serializer.dump ::Marshal.dump(node), filepath
         end

data/lib/rambling/trie/serializers/yaml.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rambling
   module Trie
     module Serializers
@@ -11,20 +13,34 @@ module Rambling
         end
 
         # Loads serialized object from YAML file in filepath and deserializes
-        # it into a {Node Node}.
+        # it into a {Nodes::Node Node}.
         # @param [String] filepath the full path of the file to load the
         #   serialized YAML object from.
-        # @return [Node] The deserialized {Node Node}.
+        # @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
+        #   Psych.safe_load
         def load filepath
           require 'yaml'
-          ::YAML.load serializer.load filepath
+          ::YAML.safe_load(
+            serializer.load(filepath),
+            [
+              Symbol,
+              Rambling::Trie::Nodes::Raw,
+              Rambling::Trie::Nodes::Compressed,
+            ],
+            [],
+            true,
+          )
         end
 
-        # Serializes a {Node Node} and dumps it as a YAML object into filepath.
-        # @param [Node] node the node to serialize
+        # Serializes a {Nodes::Node Node} and dumps it as a YAML object into
+        # filepath.
+        # @param [Nodes::Node] node the node to serialize
         # @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
+        #   Psych.dump
         def dump node, filepath
           require 'yaml'
           serializer.dump ::YAML.dump(node), filepath

data/lib/rambling/trie/serializers/zip.rb

@@ -1,14 +1,14 @@
+# frozen_string_literal: true
+
 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
-        extend ::Forwardable
-
         # Creates a new Zip serializer.
-        # @param [Properties] properties the configuration properties set up so
-        #   far.
+        # @param [Configuration::Properties] properties the configuration
+        #   properties set up so far.
         def initialize properties
           @properties = properties
         end
@@ -17,6 +17,8 @@ module Rambling
         # unzipped files.
         # @param [String] filepath the filepath to load contents from.
         # @return [String] all contents of the unzipped loaded file.
+        # @see https://github.com/rubyzip/rubyzip#reading-a-zip-file Zip
+        #   reading a file
         def load filepath
           require 'zip'
 
@@ -34,6 +36,8 @@ module Rambling
         # @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.
+        # @see https://github.com/rubyzip/rubyzip#basic-zip-archive-creation
+        #   Zip archive creation
         def dump contents, filepath
           require 'zip'
 
@@ -52,10 +56,13 @@ module Rambling
 
         attr_reader :properties
 
-        delegate [
-          :serializers,
-          :tmp_path
-        ] => :properties
+        def serializers
+          properties.serializers
+        end
+
+        def tmp_path
+          properties.tmp_path
+        end
 
         def path filename
           require 'securerandom'