folder_stash 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d57c9ab806041af992961e83a9472a27836b63f0d46b42adfc9e2e04b35d860
+  data.tar.gz: 10d1be204348138ab0027ffedd519d0ab3cdd56a0733732ddb6d9f4bfef590fc
+SHA512:
+  metadata.gz: 3f2810d1dd64f6e67dd7e5afa513bc0b71d2b00dfd306f028e2ad1ac598aea49b2906fdc0c9b342cc3e9a6fe3ccd87f85c9a87354f2eee850d95fb33f0a5e6fe
+  data.tar.gz: a9cb901842fc1052f09e620961cc95cee8314c9f2e7f1984bb9282698859cc49352f06769f1d8596ad5f19604ecfe6f45d8452443aa2f1dae8556edc068f66d2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Martin Stein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR 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.

data/README.rdoc

@@ -0,0 +1,66 @@
+= folder_stash
+
+The <tt>folder_stash</tt> gem will store files in a directory with a user
+definable number of nested subdirectories in a given path and a maximum number
+of items allowed per subdirectory.
+
+New nested subdirectories will be created on demand as a given subdirectory
+reaches the specified limit of items. All created subdirectories will have
+randomized base names.
+
+<tt>folder_stash</tt> uses a symlink (<tt>.current_store_path</tt>) to the
+currently available directory. By default the symlink will be in the top level
+storage directory, but it can optionally be placed in any directory.
+
+== Installation
+
+  gem install folder_stash
+
+== Usage
+
+The basic usage is to create a new instance of FileUsher with the directory in
+which files are to be stored in; the top level storage directory.
+
+  require 'folder_stash'
+  
+  # create a new FileUsher instance with defaults (2 levels of subdirectories,
+  # 10000 items per subdirectory)
+  usher = FolderStash::FileUsher.new('~/storage_dir')
+  
+FileUsher will try to locate the <tt>.current_store_path</tt> symlink, either in
+the top level directory, or, if any other location for the link passed as the
+<tt>link_location</tt> option passed to the
+initializer[rdoc-ref:FolderStash::FileUsher.new]. 
+
+If the symlink does not exist, it will create a new branch (nested path) with
+the number of nested subdirectories given in the <tt>nesting_levels</tt> option
+passed to the initializer[rdoc-ref:FolderStash::FileUsher.new] and create the
+symlink which will point to the terminal (most deeply nested) subdirectory.
+
+  storage_directory
+  ├── .current_store_path -> ~/storage_dir/a1bd81a073a78025/2d9dfcd7a6c329b4
+  └── a1bd81a073a78025
+      └── 2d9dfcd7a6c329b4
+
+If the symlink exists, FileUsher will use the existing subdirectory hierarchy.
+
+Files can be copied or moved to the directory the symlink currently points to
+using the {#copy}[rdoc-ref:FolderStash::FileUsher#copy] and
+{#move}[rdoc-ref:FolderStash::FileUsher#move] methods respectively, which both
+will return the path the file was stored to.
+
+  usher.copy('~/image1.jpg')
+  # => "storage_dir/a1bd81a073a78025/2d9dfcd7a6c329b4/image1.jpg"
+  
+  usher.move('~/image2.jpg')
+  # => "storage_dir/a1bd81a073a78025/2d9dfcd7a6c329b4/image2.jpg"
+
+The path returned will by default start with the top level storage directory. It
+is possible to return the relative path or absolute path by passing the values
++:relative+ or +:absolute+ as the +pathtype+ option:
+
+  usher.copy('~/image3.jpg', :pathtype => :relative)
+  # => "path/to/storage_dir/a1bd81a073a78025/2d9dfcd7a6c329b4/image3.jpg"
+  
+  usher.copy('~/image4.jpg', :pathtype => :absolute)
+  # => "/path/to/storage_dir/a1bd81a073a78025/2d9dfcd7a6c329b4/image4.jpg"

data/lib/folder_stash/errors/branch_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FolderStash
+  module Errors
+    # Error that is raises when attempting to create a branch in a folder that
+    # can not be branched (typically the terminal).
+    class BranchError < StandardError
+      # Directory for the folder where the branch was attempted.
+      attr_reader :dir
+
+      def initialize(msg = nil, dir: nil)
+        @dir = dir
+        msg ||= "Can not branch in #{dir} because it is a tree terminal."
+        super msg
+      end
+    end
+  end
+end

data/lib/folder_stash/errors/no_directory_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FolderStash
+  module Errors
+    # Error that is raised if a directory does not exist.
+    class NoDirectoryError < StandardError
+      # Path for the directory that does not exist.
+      attr_reader :dir
+
+      def initialize(msg = nil, dir: nil)
+        @dir = dir
+        msg ||= "The directory #{dir} does not exist or is not a directory"
+        super msg
+      end
+    end
+  end
+end

data/lib/folder_stash/errors/tree_limit_exceeded_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FolderStash
+  module Errors
+    # Error that is raised when the number of items in a tree has exceeded the
+    # maximum number allowed in a tree.
+    class TreeLimitExceededError < StandardError
+      # Number of subdirectories in a given path (branch) of the tree.
+      attr_reader :subdirs
+
+      # Number of items allowed in a subdirectory.
+      attr_reader :subdir_limit
+
+      # Total number of items allowed in a tree.
+      attr_reader :tree_limit
+
+      def initialize(msg = nil, tree: nil)
+        @subdirs = tree.path_length
+        @subdir_limit = tree.folder_limit
+        @tree_limit = tree.tree_limit
+        msg ||= 'The storage tree has reached the limit of allowed items:'\
+                " #{subdir_limit} items in #{subdirs} subdirectories"\
+                " (#{tree_limit} allowd items in total)."
+        super msg
+      end
+    end
+  end
+end

data/lib/folder_stash/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'errors/branch_error'
+require_relative 'errors/no_directory_error'
+require_relative 'errors/tree_limit_exceeded_error'
+
+module FolderStash
+  # Contains error classes.
+  module Errors
+  end
+end

data/lib/folder_stash/file_usher.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module FolderStash
+  # FileUsher stores files in a directory tree with a defined maximum number of
+  # #items per directory.
+  #
+  # It will create new subdirectories to store files in if a subdirectory has
+  # reached the maximum number of items.
+  class FileUsher
+    CURRENT_STORE_PATH = '.current_store_path'
+
+    # The working directory where all subdirectories and files are stored.
+    attr_reader :directory
+
+    # An instance of FolderTree.
+    attr_reader :tree
+
+    # Returns a new instance.
+    #
+    # ===== Arguments
+    #
+    # * +dir+ (_String_) - path for the #directory.
+    #
+    # ===== Options
+    #
+    # * <tt>nesting_levels</tt> - the number of subdirectories below #directory
+    #   in the path of files that are stored (_default_: +2+).
+    # * <tt>folder_limit</tt> - the maximum number of items allowed per
+    #   directory (_default_: +10000+).
+    # * <tt>link_location</tt> - the directory where the #current_directory
+    #   symlink is stored. When not specified, the symlink will be in #directory
+    #
+    # Setting <tt>nesting_levels</tt> to +nil+ will also set the
+    # <tt>folder_limit</tt>. Conversely, setting <tt>folder_limit</tt> to +nil+
+    # also set <tt>nesting_levels</tt> to +nil+.
+    def initialize(dir, **opts)
+      raise Errors::NoDirectoryError, dir: dir unless File.directory? dir
+
+      @options = { nesting_levels: 2, folder_limit: 10_000 }.update(opts)
+      @directory = dir
+      @current_directory = File.join @options.fetch(:link_location, directory),
+                                     CURRENT_STORE_PATH
+
+      @tree = init_existing || init_new(nesting_levels)
+      link_target
+    end
+
+    # Copies +file+ to linked path.
+    def copy(file, pathtype: :tree)
+      path = store_path(file)
+      File.open(path, 'wb') { |f| f.write(File.new(file).read) }
+      file_path path, pathtype
+    end
+
+    # Returns the full path (_String_) to the current directory symlink.
+    def current_directory
+      File.expand_path @current_directory
+    end
+
+    # Returns the full directory path for #current_folder
+    def current_path
+      current_folder.path
+    end
+
+    # The number of items allowed in any directory in a nested directory path.
+    #
+    # Will be +nil+ if #nesting_levels is +nil+.
+    def folder_limit
+      return unless @options.fetch :nesting_levels
+
+      @options.fetch :folder_limit
+    end
+
+    # Returns the directory path the #current_directory symlink points to.
+    def linked_path
+      File.readlink current_directory
+    end
+
+    # Moves +file+ to the #linked_path.
+    def move(file, pathtype: :tree)
+      path = store_path(file)
+      FileUtils.mv File.expand_path(file), store_path(file)
+      file_path path, pathtype
+    end
+
+    # The number of nested subdirectories.
+    def nesting_levels
+      return unless @options.fetch :folder_limit
+
+      tree&.path_length || @options.fetch(:nesting_levels)
+    end
+
+    private
+
+    # Returns the next available folder in #tree. Will raise OutOfStorageError
+    # if none is available.
+    def available_folder
+      folder = tree.available_folder
+      raise Errors::TreeLimitExceededError, tree: tree unless folder
+
+      folder
+    end
+
+    # Returns +true+ if the current directory symlink exists in #directory.
+    def current_directory?
+      File.exist? current_directory
+    end
+
+    # Returns a Folder that is currently the FolderTree#terminal.
+    def current_folder
+      tree.terminal
+    end
+
+    # Returns the path for +path+ as +:absolute+, +:relative+, or only the
+    # nested subdirectories in the +:tree+.
+    def file_path(path, pathtype)
+      treepath = tree.branch_path.append(File.basename(path))
+      case pathtype
+      when :absolute
+        File.realpath path
+      when :relative
+        treepath[0] = directory
+        treepath.join('/')
+      when :tree
+        treepath.join('/')
+      end
+    end
+
+    # Creates the folder #tree in an existing directory with #current_directory
+    # symlink.
+    def init_existing
+      return unless current_directory?
+
+      FolderTree.for_path linked_path, root: directory, limit: folder_limit
+    end
+
+    # Creates the folder #tree for a new direcrory without #current_directory
+    # symlink.
+    def init_new(levels)
+      FolderTree.empty directory, levels: levels, limit: folder_limit
+    end
+
+    # Creates the current_directory symlink, pointing to the #current_path.
+    def link_target
+      return if current_directory? && linked_path == current_path
+
+      FileUtils.ln_s File.expand_path(current_path), current_directory
+    end
+
+    # Returns the next available path (_String_) for a file to be stored under.
+    def store_path(file)
+      update_link if folder_limit && current_folder.count >= folder_limit
+      File.join current_directory, File.basename(file)
+    end
+
+    # Creates new subdirectories points the #current_directory symlink to the
+    # new #current_folder.
+    def update_link
+      tree.new_branch_in available_folder
+      FileUtils.rm current_directory
+      link_target
+    end
+  end
+end

data/lib/folder_stash/folder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module FolderStash
+  # A Folder represents a directory in the filesystem.
+  class Folder
+    # Basename for the folder.
+    attr_reader :basename
+
+    # Absolute path for the folder.
+    attr_reader :path
+
+    # Returns a new instance.
+    #
+    # ===== Arguments
+    #
+    # * +path+ (String) - path to the directory for the folder.
+    def initialize(path)
+      @path = File.expand_path path
+      @basename = File.basename path
+    end
+
+    def self.folders_for_path_segment(root, segment)
+      root_folder = Folder.new root
+      segment.inject([root_folder]) do |dirs, dir|
+        path = File.join dirs.last.path, dir
+        dirs << Folder.new(path)
+      end
+    end
+
+    # Returns the number of visible files in the folder.
+    def count
+      entries.count
+    end
+
+    # Creates the directory path in the immediate parent.
+    def create
+      FileUtils.mkdir path unless exist?
+    end
+
+    # Creates the directory #path with all parents.
+    def create!
+      FileUtils.mkdir_p path unless exist?
+    end
+
+    # Returns +true+ if the directory #path exists.
+    def exist?
+      File.exist? path
+    end
+
+    # Returns a list of entries (files or folders) in the folder.
+    #
+    # ===== Options
+    #
+    # * <tt>include_hidden</tt>
+    #   * +true+ - list visible and hidden entries.
+    #   * +false+ (_default_) - list only visible entries.
+    def entries(include_hidden: false)
+      children = Dir.children path
+      return children if include_hidden == true
+
+      children.reject { |entry| entry.start_with? '.' }
+    end
+  end
+end

data/lib/folder_stash/folder_tree.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module FolderStash
+  # A FolderTree represents a nested directory path.
+  class FolderTree
+    # An array with instances of Folder, one for each directory in a nested
+    # directory path from the #root to the #terminal.
+    attr_accessor :folders
+
+    # The maximum number of itmes that may be stored in any folder in #folders.
+    attr_reader :folder_limit
+
+    # The number of items (directories) in a nested directory path, from the
+    # #root to the #terminal.
+    attr_reader :path_length
+
+    attr_reader :tree_limit
+
+    # Returns a new instance.
+    #
+    # ===== Arguments
+    #
+    # * +folders+ (String) - Array of Folder instances.
+    # * +levels+ (Integer) - Number of nested subdirectories in a path.
+    # * +limit+ (Integer) - Number of items allowed in any folder in the
+    #   tree's directory path.
+    def initialize(folders, levels, limit)
+      @folders = folders
+      @path_length = levels
+      @folder_limit = limit
+      @tree_limit = folder_limit ? folder_limit**(path_length + 1) : nil
+    end
+
+    def self.empty(root, levels:, limit:)
+      folders = [Folder.new(root)]
+      tree = new(folders, levels, limit)
+      tree.new_branch_in tree.root, levels
+      tree
+    end
+
+    def self.for_path(path, root:, limit:)
+      path_items = path_segment path, root
+      folders = Folder.folders_for_path_segment root, path_items
+      new folders, path_items.count, limit
+    end
+
+    def self.path_segment(terminal, root)
+      File.expand_path(terminal).split('/') - File.expand_path(root).split('/')
+    end
+
+    # Returns the number of folder in the nested path currently available.
+    def actual_path_length
+      folders.count
+    end
+
+    # Returns the next available folder, searching upstream from the terminal
+    # folder to the #root.
+    #
+    # Returns #root if root is the only folder.
+    def available_folder
+      return root if flat?
+
+      folders.reverse.find { |folder| folder.count < folder_limit }
+    end
+
+    def branch_path
+      folders.map(&:basename)
+    end
+
+    def flat?
+      actual_path_length == 1 && path_length.nil?
+    end
+
+    # Returns the number (integer) of levels of folders nested in +folder+.
+    def levels_below(folder)
+      return if flat?
+
+      path_length - folders.index(folder)
+    end
+
+    # Creates a new branch of folders in +folder+ and updates #folders to the
+    # new branch.
+    #
+    # Returns an array with the full path for the terminal folder in the branch
+    # created.
+    def new_branch_in(folder, levels = nil)
+      return if flat?
+
+      raise Errors::BranchError, dir: folder.path if folder == terminal
+
+      raise TreeLimitExceededError, tree: self if folder.count >= folder_limit
+
+      levels ||= levels_below folder
+      new_branch = new_paths_in folder, levels
+      @folders = folders[0..folders.index(folder)].concat new_branch
+      folders.last.create!
+    end
+
+    # Returns the root folder.
+    def root
+      folders.first
+    end
+
+    # Returns the terminal (most deeply nested) folder.
+    #
+    # Returns +nil+ if the tree has not been fully initialized with a branch.
+    def terminal
+      return root if flat?
+
+      return if actual_path_length < path_length
+
+      folders.last
+    end
+
+    private
+
+    # If the file <tt>path/name</tt> exists, randomize the name until a new
+    # random is found that does not exist.
+    #
+    # Returns the new unique path name.
+    #
+    # This only needs to be called for the first new directory to be created,
+    # all others will be created in empty directories and therefroe always be
+    # unique.
+    def ensure_unique_node(path, name)
+      name = SecureRandom.hex(8) while File.exist? File.join(path, name)
+      Folder.new File.join(path, name)
+    end
+
+    # Returns an array of new Folder instances.
+    def new_paths_in(folder, count)
+      first_node = ensure_unique_node(folder.path, SecureRandom.hex(8))
+      remainder = count - 1
+      remainder.times.inject([first_node]) do |nodes|
+        path = File.join nodes.last.path, SecureRandom.hex(8)
+        nodes << Folder.new(path)
+      end
+    end
+  end
+end

data/lib/folder_stash.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+
+require_relative 'folder_stash/errors'
+require_relative 'folder_stash/file_usher'
+require_relative 'folder_stash/folder'
+require_relative 'folder_stash/folder_tree'
+
+# Module that contains the FileUsher, FolderTree, and FolderTree classes.
+module FolderStash
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: folder_stash
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Martin Stein
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-08-15 00:00:00.000000000 Z
+dependencies: []
+description: |
+  The <tt>folder_stash</tt> gem will store files in a directory with a user
+  definable number of nested subdirectories in a given path and a maximum
+  number of items allowed per subdirectory.
+
+  New nested subdirectories will be created on demand as a given subdirectory
+  reaches the specified limit of items. All created subdirectories will have
+  randomized base names.
+email: loveablelobster@fastmail.fm
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.rdoc
+- lib/folder_stash.rb
+- lib/folder_stash/errors.rb
+- lib/folder_stash/errors/branch_error.rb
+- lib/folder_stash/errors/no_directory_error.rb
+- lib/folder_stash/errors/tree_limit_exceeded_error.rb
+- lib/folder_stash/file_usher.rb
+- lib/folder_stash/folder.rb
+- lib/folder_stash/folder_tree.rb
+homepage: https://github.com/loveablelobster/folder_stash
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Keeps the number of files per directory within a limit by autogenerating
+  subdirectories.
+test_files: []