rambling-trie 0.9.3 → 1.0.0

data/lib/rambling/trie/missing_node.rb

@@ -1,6 +1,7 @@
 module Rambling
   module Trie
-    # A representation of a missing node in the Trie data structure.
+    # A representation of a missing node in the trie data structure. Returned
+    # when a node is not found.
     class MissingNode < Rambling::Trie::Node
     end
   end

data/lib/rambling/trie/node.rb

@@ -1,11 +1,13 @@
 module Rambling
   module Trie
-    # A representation of a node in the Trie data structure.
+    # A representation of a node in the trie data structure.
     class Node
       extend Rambling::Trie::Forwardable
-      include Rambling::Trie::Compression
+      include Rambling::Trie::Compressable
       include Rambling::Trie::Enumerable
-      include Rambling::Trie::Inspector
+      include Rambling::Trie::Comparable
+      include Rambling::Trie::Stringifyable
+      include Rambling::Trie::Inspectable
 
       delegate [
         :[],
@@ -14,64 +16,58 @@ module Rambling
         :has_key?
       ] => :children_tree
 
-      # Letter or letters corresponding to this node.
-      # @return [Symbol, nil] the corresponding letter(s) or nil.
+      # @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 new letter value.
+      # @return [Symbol, nil] the corresponding letter(s).
       attr_reader :letter
 
-      # Children nodes.
-      # @return [Hash] the children_tree hash, consisting of :letter => node.
+      # Children nodes tree.
+      # @return [Hash] the children_tree hash, consisting of `:letter => node`.
       attr_accessor :children_tree
 
       # Parent node.
-      # @return [Node, nil] the parent node or nil for the root element.
+      # @return [Node, nil] the parent of the current node.
       attr_accessor :parent
 
-      # Creates a new Node.
-      # @param [Node, nil] parent the parent of this node.
+      # Creates a new node.
+      # @param [Node, nil] parent the parent of the current node.
       def initialize parent = nil
         self.parent = parent
         self.children_tree = {}
       end
 
-      # String representation of the current node, if it is a terminal node.
-      # @return [String] the string representation of the current node.
-      # @raise [InvalidOperation] if node is not terminal or is root.
-      def as_word
-        raise InvalidOperation, 'Cannot represent branch as a word' if letter && !terminal?
-        to_s
-      end
-
-      # Children nodes of the current node.
-      # @return [Array] the array of children nodes contained in the current node.
+      # Children nodes.
+      # @return [Array<Node>] the array of children nodes contained in the
+      #   current node.
       def children
         children_tree.values
       end
 
-      # If the current node is the root node.
-      # @return [Boolean] `true` only if the node does not have a parent
+      # 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
 
-      # Flag for terminal nodes.
+      # Indicates if a {Node Node} is terminal or not.
       # @return [Boolean] `true` for terminal nodes, `false` otherwise.
       def terminal?
         !!terminal
       end
 
-      # Force [Node] to be `terminal`
+      # Mark {Node Node} as terminal.
       # @return [Node] the modified node.
       def terminal!
         self.terminal = true
         self
       end
 
-      # String representation of the current node.
-      # @return [String] the string representation of the current node.
-      def to_s
-        parent.to_s << letter.to_s
-      end
-
       def letter= letter
         if letter
           @letter = letter.to_sym
@@ -79,6 +75,20 @@ module Rambling
         end
       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
+
       private
 
       attr_accessor :terminal

data/lib/rambling/trie/raw_node.rb

@@ -1,10 +1,10 @@
 module Rambling
   module Trie
-    # A representation of a node in an uncompressed Trie data structure.
+    # A representation of a node in an uncompressed trie data structure.
     class RawNode < Rambling::Trie::Node
-      # Adds a branch to the current trie node based on the word
-      # @param [String] word the word to add the branch from.
-      # @return [Rambling::Trie::RawNode] the just added branch's root node.
+      # Adds a word to the current raw (uncompressed) trie node.
+      # @param [String] word the word to add to the trie.
+      # @return [RawNode] the added/modified node based on the word added.
       # @note This method clears the contents of the word variable.
       def add word
         if word.empty?
@@ -14,9 +14,10 @@ module Rambling
         end
       end
 
-      # Checks if a path for set of characters exists in the trie.
-      # @param [Array] chars the characters to look for in the trie.
-      # @return [Boolean] `true` if the characters are found, `false` otherwise.
+      # 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 = []
         if chars.empty?
           true
@@ -28,9 +29,9 @@ module Rambling
       end
 
       # Checks if a path for set of characters represents a word in the trie.
-      # @param [Array] chars the characters to look for 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.
+      #   `false` otherwise.
       def word? chars = []
         if chars.empty?
           terminal?
@@ -41,15 +42,16 @@ module Rambling
         end
       end
 
-      # Returns all words that start with the specified characters.
-      # @param [Array] chars the characters to look for in the trie.
-      # @return [Array] all the words contained in the trie that start with the specified characters.
+      # 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.
+      #   {MissingNode MissingNode} when not found.
       def scan chars
         chars.empty? ? self : closest_node(chars)
       end
 
       # Always return `false` for a raw (uncompressed) node.
-      # @return [Boolean] always false for a raw (uncompressed) node.
+      # @return [Boolean] always `false` for a raw (uncompressed) node.
       def compressed?
         false
       end
@@ -75,6 +77,20 @@ module Rambling
 
         child ? child.scan(chars) : Rambling::Trie::MissingNode.new
       end
+
+      def children_match_prefix chars
+        return enum_for :children_match_prefix, chars unless block_given?
+
+        if !chars.empty?
+          letter = chars.slice!(0).to_sym
+          child = children_tree[letter]
+          if child
+            child.match_prefix chars do |word|
+              yield word
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/rambling/trie/readers.rb

@@ -0,0 +1,11 @@
+%w{plain_text}.each do |file|
+  require File.join('rambling', 'trie', 'readers', file)
+end
+
+module Rambling
+  module Trie
+    # Namespace for all readers.
+    module Readers
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Rambling
+  module Trie
+    module Readers
+      # File reader for .txt files.
+      class PlainText
+        # Yields each word read from a .txt file.
+        # @param [String] filepath the full path of the file to load the words
+        #   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 }
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/serializers.rb

@@ -0,0 +1,11 @@
+%w{file marshal yaml zip}.each do |file|
+  require File.join('rambling', 'trie', 'serializers', file)
+end
+
+module Rambling
+  module Trie
+    # Namespace for all serializers.
+    module Serializers
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Rambling
+  module Trie
+    module Serializers
+      # Basic file serializer. Dumps/loads string contents from files.
+      class File
+        # Loads contents from a specified filepath.
+        # @param [String] filepath the filepath to load contents from.
+        # @return [String] all contents of the file.
+        def load filepath
+          ::File.read filepath
+        end
+
+        # Dumps contents into a specified filepath.
+        # @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.
+        def dump contents, filepath
+          ::File.open filepath, 'w+' do |f|
+            f.write contents
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Rambling
+  module Trie
+    module Serializers
+      # Serializer for Ruby marshal format (.marshal) files.
+      class Marshal
+        # Creates a new Marshal serializer.
+        # @param [Serializer] serializer the serializer responsible to write to
+        #   and read from disk.
+        def initialize serializer = nil
+          @serializer = serializer || Rambling::Trie::Serializers::File.new
+        end
+
+        # Loads marshaled object from contents in filepath and deserializes it
+        # into a {Node Node}.
+        # @param [String] filepath the full path of the file to load the
+        #   marshaled object from.
+        # @return [Node] The deserialized {Node Node}.
+        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
+        # @param [String] filepath the full path of the file to dump the
+        #   marshaled object into.
+        # @return [Numeric] number of bytes written to disk.
+        def dump node, filepath
+          serializer.dump ::Marshal.dump(node), filepath
+        end
+
+        private
+
+        attr_reader :serializer
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Rambling
+  module Trie
+    module Serializers
+      # Serializer for Ruby yaml format (.yaml) files.
+      class Yaml
+        # Creates a new Yaml serializer.
+        # @param [Serializer] serializer the serializer responsible to write to
+        #   and read from disk.
+        def initialize serializer = nil
+          @serializer = serializer || Rambling::Trie::Serializers::File.new
+        end
+
+        # Loads serialized object from YAML file in filepath and deserializes
+        # it into a {Node Node}.
+        # @param [String] filepath the full path of the file to load the
+        #   serialized YAML object from.
+        # @return [Node] The deserialized {Node Node}.
+        def load filepath
+          require 'yaml'
+          ::YAML.load serializer.load filepath
+        end
+
+        # Serializes a {Node Node} and dumps it as a YAML object into filepath.
+        # @param [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.
+        def dump node, filepath
+          require 'yaml'
+          serializer.dump ::YAML.dump(node), filepath
+        end
+
+        private
+
+        attr_reader :serializer
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+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 Rambling::Trie::Forwardable
+
+        # Creates a new Zip serializer.
+        # @param [Properties] properties the configuration properties set up so
+        #   far.
+        def initialize properties
+          @properties = properties
+        end
+
+        # Unzip contents from specified filepath and load in contents from
+        # unzipped files.
+        # @param [String] filepath the filepath to load contents from.
+        # @return [String] all contents of the unzipped loaded file.
+        def load filepath
+          require 'zip'
+
+          ::Zip::File.open filepath do |zip|
+            entry = zip.entries.first
+            entry_path = path entry.name
+            entry.extract entry_path
+
+            serializer = serializers.resolve entry.name
+            serializer.load entry_path
+          end
+        end
+
+        # Dumps contents and zips into a specified filepath.
+        # @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.
+        def dump contents, filepath
+          require 'zip'
+
+          ::Zip::File.open filepath, ::Zip::File::CREATE do |zip|
+            filename = ::File.basename filepath, '.zip'
+
+            entry_path = path filename
+            serializer = serializers.resolve filename
+            serializer.dump contents, entry_path
+
+            zip.add filename, entry_path
+          end
+        end
+
+        private
+
+        attr_reader :properties
+
+        delegate [
+          :serializers,
+          :tmp_path
+        ] => :properties
+
+        def path filename
+          require 'securerandom'
+          ::File.join tmp_path, "#{SecureRandom.uuid}-#{filename}"
+        end
+      end
+    end
+  end
+end

data/lib/rambling/trie/stringifyable.rb

@@ -0,0 +1,20 @@
+module Rambling
+  module Trie
+    # Provides the String representation behavior for the trie data structure.
+    module Stringifyable
+      # String representation of the current node, if it is a terminal node.
+      # @return [String] the string representation of the current node.
+      # @raise [InvalidOperation] if node is not terminal or is root.
+      def as_word
+        raise Rambling::Trie::InvalidOperation, 'Cannot represent branch as a word' if letter && !terminal?
+        to_s
+      end
+
+      # String representation of the current node.
+      # @return [String] the string representation of the current node.
+      def to_s
+        parent.to_s << letter.to_s
+      end
+    end
+  end
+end