folder_stash¶ ↑

The folder_stash 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.

folder_stash uses a symlink (.current_store_path) 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.

gem install folder_stash

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 .current_store_path symlink, either in the top level directory, or, if any other location for the link passed as the link_location option passed to the initializer.

If the symlink does not exist, it will create a new branch (nested path) with the number of nested subdirectories given in the nesting_levels option passed to the initializer 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 and #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"