stashify 3.1.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15c432cdab53f9a20369203af0e05bb8157413a622655ae28d4c36131f318a8b
-  data.tar.gz: 5e2d87b9a660825c36d4140fa1a5c30b1a5e10573edc34df7fb6cbcff7e5f802
+  metadata.gz: 035b4f42412c865a6fcabf7944cd6a49169034b974054e20a8eb67ea1f06a4a4
+  data.tar.gz: 4a393454a48b04bc1769fe29a3ea21fe5e4ce501c3443f903e777c7a44b8478e
 SHA512:
-  metadata.gz: 73612ebce48eaf45c396d4277ea4e73a591ffb976589049101dc28c6cd8b4fbbd3ad376852db2a8e5deb0a8864982e10071821da47a2ca19e05b443e0054613a
-  data.tar.gz: a897048fb68343a37408a5bdc43bcf93f629621fea1d21235896f32b0800e643ab791feac51d32b17df73ed2fcc3141652e43fd4bc85deac757abd78c1410080
+  metadata.gz: 3f3f849fff674adea33a49fbd2c9495cda7d21a64690cf09a828800acfaea5e70cd223ba3400a785e7e8f44f8e1daa3fa5047a44a3de9c0bfe936b91a7099c91
+  data.tar.gz: a13e678a94cdf0844d3d537310af37a0f21e9b55075600cfe47ce186cabee8c52c3ff3981459a630ca7163c1e3d7664aa6b36d0390afe1cfd02df3fd8ed04e37

data/.reek.yml

@@ -1,7 +1,4 @@
 detectors:
-  IrresponsibleModule:
-    enabled: false
-
   TooManyStatements:
     exclude:
       - properties
@@ -19,3 +16,7 @@ detectors:
   ControlParameter:
     exclude:
       - Stashify::Directory#initialize
+
+  NilCheck:
+    exclude:
+      - Stashify::File#exists?

data/.rubocop.yml

@@ -2,9 +2,6 @@ AllCops:
   TargetRubyVersion: 2.6
   NewCops: enable
 
-Style/Documentation:
-  Enabled: false
-
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes

data/Gemfile

@@ -18,3 +18,5 @@ gem "guard-rubocop"
 
 gem "byebug"
 gem "stashify-contract"
+
+gem "yard"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stashify (3.1.0)
+    stashify (3.2.1)
 
 GEM
   remote: https://rubygems.org/
@@ -93,6 +93,9 @@ GEM
       rspec (~> 3.0)
     thor (1.2.1)
     unicode-display_width (2.4.2)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   x86_64-linux
@@ -109,6 +112,7 @@ DEPENDENCIES
   rubocop (~> 1.21)
   stashify!
   stashify-contract
+  yard
 
 BUNDLED WITH
    2.2.33

data/README.md

@@ -1,16 +1,18 @@
 # Stashify
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/stashify`. To experiment with that code, run `bin/console` for an interactive prompt.
+Stashify is a common abstraction to interact with several different storage mediums in a uniform way. Provided in this gem is an implementation of the local filesystem, but other gems provide other implementations.
 
-TODO: Delete this and the text above, and describe your gem
+* [Google Cloud Storage](https://github.com/Lambda-Null/stashify-google-cloud-storage)
+* [AWS S3](https://github.com/Lambda-Null/stashify-aws-s3)
+* [Azure Blob Storage](https://github.com/Lambda-Null/stashify-microsoft-azure-storage-blob)
+
+The uniform nature of these implementations allows results from one be passed to others. This not only affords you flexibility in your implementation and testing, but a simple way of transferring information from one storage provider to another.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-```ruby
-gem 'stashify'
-```
+	gem 'stashify'
 
 And then execute:
 
@@ -22,7 +24,91 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Provided in this gem is an implementation of local storage. Here is an example of how to use that implementation:
+
+	> require "stashify/file/local"
+	=> true
+	> file = Stashify::File::Local.new(path: "/tmp/foo")
+	=> #<Stashify::File::Local:0x000055a2a62f53c0 @contents="", @name="foo", @path="/tmp/foo">
+	> file.contents
+	=> "1\n"
+	> file.delete
+	=> true
+	> file.write("100")
+	=> 3
+	> file.contents
+	=> "100"
+	> file.delete
+	=> 1
+	> file.exists?
+	=> false
+	> require "stashify/directory/local"
+	> dir = Stashify::Directory::Local.new(path: "/tmp")
+	> file2 = dir.find("bar")
+	=> #<Stashify::File::Local:0x000055a2a62ff000 @contents="", @name="bar", @path="/tmp/bar">
+	> file2.contents
+	=> "2\n"
+	> dir.exists?(file.name)
+	=> false
+	> dir.write(Stashify::File.new(name: "foo", contents: "1"))
+	> dir.exists?("foo")
+	=> true
+	> dir.find("foo").contents
+	=> "1"
+	> dir.exists?("bar")
+	=> true
+	> dir.delete("bar")
+	=> 1
+	> dir.exists?("bar")
+	=> false
+	> subdir = dir.find("foobar")
+	=> 
+	#<Stashify::Directory::Local:0x000055a2a5ffb660
+	...
+	> subdir.files.map(&:name)
+	=> ["baz"]
+	> subfile = subdir.files.first
+	=> 
+	#<Stashify::File::Local:0x000055a2a62937b0
+	...
+	> subfile.name
+	=> "baz"
+	> subfile.contents
+	=> "3\n"
+
+To interact with `Stashify::File` implementations is through `exists?`, `contents`, `write` and `delete`. To interact with `Stashify::Directory` implementations, use the methods `exists?`, `find`, `write`, `delete` and `files`. Regardless of the implementation of `Stashify::Directory`, `find` will return and `write` will take implementations of `Stashify::File`.
+
+This consistency allows a lot of portability. For instance, pulling in a couple [other](https://github.com/Lambda-Null/stashify-google-cloud-storage) [gems](https://github.com/Lambda-Null/stashify-aws-s3) allows you to do cool things like this:
+
+	> require "stashify/directory/local"
+	=> true
+	> dir = Stashify::Directory::Local.new(path: "/tmp/foobar")
+	=> 
+	#<Stashify::Directory::Local:0x0000564d9e8f9f48
+	...
+	> dir.files.map(&:name)
+	=> ["baz"]
+	> require "stashify/directory/google/cloud/storage"
+	=> true
+	> gdir = Stashify::Directory::Google::Cloud::Storage.new(bucket: bucket, path
+	: "")
+	=> 
+	#<Stashify::Directory::Google::Cloud::Storage:0x0000564d9ee87140
+	...
+	> gdir.write(dir)
+	> gdir.files.map(&:name)
+	=> ["foobar"]
+	> require "stashify/directory/aws/s3"
+	=> true
+	> adir = Stashify::Directory::AWS::S3.new(bucket: bucket, path: "")
+	=> 
+	#<Stashify::Directory::AWS::S3:0x0000564da0851580
+	...
+	> adir.write(gdir)
+	> adir.files.map(&:name)
+	=> ["baz"]
+
+As you can see in the above examples, `Stashify::File` and `Stashify::Directory` can be created directly to define in-memory objects. This helps avoid the need to do silly things like write files to disk in order to get them to the desired destination.
 
 ## Development
 
@@ -34,6 +120,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/stashify. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/stashify/blob/master/CODE_OF_CONDUCT.md).
 
+If you wish to create an implementation for a new provider, the gem [stashify-contract](https://github.com/Lambda-Null/stashify-contract) provides shared examples which verifies the consistency which maintains portability. To have your gem included in the list above, it must implement these examples in the way documented in that gem.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/stashify/directory/local.rb

@@ -5,7 +5,13 @@ require "stashify/directory"
 
 module Stashify
   class Directory
+    # An implementation for interacting with local directories. The
+    # constructor needs no information on top of what is included
+    # {Stashify::Directory#initialize}, although it's important to
+    # note that setting the files parameter will not do anything.
     class Local < Stashify::Directory
+      # Mostly uses the default implementaiton, but needs to create
+      # the directory first so it has a valid destination.
       def write_directory(directory)
         FileUtils.mkdir(path_of(directory.name))
         super
@@ -21,7 +27,7 @@ module Stashify
 
       def files
         Dir.entries(path).grep_v(/^[.][.]?$/).map do |file_name|
-          find(::File.basename(file_name))
+          find(file_name)
         end
       end
 

data/lib/stashify/directory.rb

@@ -1,9 +1,44 @@
 # frozen_string_literal: true
 
 module Stashify
+  # A common abstraction for interacting with directories. All methods
+  # that need to interact with directories are assumed to adhere to
+  # the public methods defined here. Specifically, the methods
+  # {#find}, {#write}, {#delete}, and {#files} are guaranteed to exist
+  # and behave in a way that is consistent across all gems. Unless
+  # called out separately, documentation for those methods here will
+  # hold true of any implementations of this class.
   class Directory
-    attr_reader :name, :files, :path
+    # Provides the files and subdirectories of this directory. In the
+    # base class, this is implemented as an attribute which defaults
+    # to an empty list, but most implementations will override this
+    # with a method. In most implementations, the performance cost of
+    # reading all of thie names in a directory to construct these
+    # objects is high enough that we only want to pay it if it's
+    # actually needed.
+    #
+    # @return [Array<Stashify::File and Stashify::Directory>] Returns
+    #   an Enumerable of Stashify::File and Stashify::Directory
+    #   objects.
+    attr_reader :files
 
+    # The name of the directory. It is everything that follows the
+    # final "/" in the {#path}. This is always guaranteed to be
+    # populated.
+    attr_reader :name
+
+    # The full path to the directory this represents. Anything after the
+    # final "/" will also be returned from {#name}. This is not
+    # necessarily guaranteed to be populated, but usually will be.
+    attr_reader :path
+
+    # Basic information associated with a directory that is necessary
+    # to enable memory-based interactions.
+    #
+    # @param name [String not containing a "/"] The name of the file. Either this or path must be defined.
+    # @param path [String] The path of the file, will populate name with everything following the final "/".
+    # @param files An array of Stashify::File and Stashify::Directory
+    #   objects representing the contents of this directory.
     def initialize(name: nil, path: nil, files: [])
       raise StandardError, "name or path must be defined" unless name || path
 
@@ -12,6 +47,19 @@ module Stashify
       @files = files
     end
 
+    # Look up the item in this directory represented by the provided
+    # name.
+    #
+    # For those looking to implement this method, it's typically more
+    # effective to override {#directory?}, {#directory}, {#exists?}
+    # and {#file}. Unless there are performance concerns with calling
+    # those, the default implementation will work pretty well.
+    #
+    # @param name [String with no "/"] The name of the desired item in
+    #   this directory.
+    #
+    # @return Either a Stashify::File or Stashify::Directory object,
+    #   depending on what that name represents.
     def find(name)
       if directory?(name)
         directory(name)
@@ -20,23 +68,59 @@ module Stashify
       end
     end
 
-    def write(file)
-      if file.is_a?(Stashify::Directory)
-        write_directory(file)
+    # Write the provided item into the directory. If the item is a
+    # directory itself, then all of the contents will be copied.
+    #
+    # For those looking to implement this method, it's typically
+    # easier to implement {#write_file} and {#write_directory}. This
+    # helps you avoid having to know what type of object you're
+    # dealing with.
+    #
+    # @param item Either a Stashify::File or Stashify::Directory
+    #   object. Note that these can be any implementation of these
+    #   base classes, it's not limited to the classes from the same
+    #   provider.
+    def write(item)
+      if item.is_a?(Stashify::Directory)
+        write_directory(item)
       else
-        write_file(file)
+        write_file(item)
       end
     end
 
+    # Writes the provided directory. Typically you will want to
+    # interact with this functionality through {#write} rather than
+    # directly, as it protects you from errors related to accidentally
+    # passing a Stashify::File value in. It is primarily implemented
+    # separately to give a more specific hook for various
+    # implementations.
+    #
+    # The default implementation might work for you, as it iterates
+    # through {#files} and writes them to the new subdirectory.
     def write_directory(directory)
       subdir = self.directory(directory.name)
       directory.files.each { |file| subdir.write(file) }
     end
 
+    # Writes the provided file. Typically you will want to interact
+    # with this functionality through {#write} rather than directly,
+    # as it protects you from errors related to accidentally passing a
+    # Stashify::Directory value in. It is primarily implemented
+    # separately to give a more specific hook for various
+    # implementations.
     def write_file(file)
       file(file.name).write(file.contents)
     end
 
+    # Delete provided name from the directory. If the item is a
+    # directory itself, then all of the contents will be copied.
+    #
+    # For those looking to implement this method, it's typically
+    # easier to implement {#directory?}, {#delete_directory} and
+    # {#delete_file}. The primary reason to override this method would
+    # be for performance reasons.
+    #
+    # @param name [String] Name of the item to be deleted.
     def delete(name)
       if directory?(name)
         delete_directory(name)
@@ -45,27 +129,48 @@ module Stashify
       end
     end
 
+    # Deletes the provided directory name. Typically you will want to
+    # interact with this functionality through {#delete} rather than
+    # directly, as it protects you from errors related to accidentally
+    # asking to delete a file as a directory.
     def delete_directory(name)
       subdir = directory(name)
       subdir.files.each { |file| subdir.delete(file.name) }
     end
 
+    # Deletes the provided file name. Typically you will want to
+    # interact with this functionality through {#delete} rather than
+    # directly, as it protects you from errors related to accidentally
+    # asking to delete a directory as a file.
     def delete_file(name)
       file(name).delete
     end
 
+    # Two directories are equal if their files are equal. This is
+    # distinct from being the same directory, which is served by the
+    # {#eql?} method.
     def ==(other)
       files == other.files
     end
 
+    # This answers if the two directories are the same, which is
+    # usually more specific than you want. If you wish to determine if
+    # all of the files are equal, consider {#==} instead..
     def eql?(other)
       self.class == other.class && name == other.name && path == other.path
     end
 
-    private
+    # @return [Stashify::File] Return an object representing a single
+    #   file in this directory.
+    def file(name)
+      Stashify::File.new(path: path_of(name))
+    end
 
-    def path_of(*name)
-      ::File.join(path, *name)
+    # The full path to the item in this directory provided by the
+    # names. Any number of names can be provided, allowing arbitrarily
+    # deep paths to be constructed below this directory.
+    def path_of(*names)
+      ::File.join(path, *names)
     end
   end
 end

data/lib/stashify/file/local.rb

@@ -4,6 +4,10 @@ require "stashify/file"
 
 module Stashify
   class File
+    # An implementation for interacting with local files. The
+    # constructor needs no information on top of what is included
+    # {Stashify::File#initialize}, although it's important to note
+    # that setting the contents parameter will not do anything.
     class Local < Stashify::File
       def contents
         ::File.read(path)

data/lib/stashify/file.rb

@@ -3,10 +3,38 @@
 require "stashify"
 
 module Stashify
+  # A common abstraction for interacting with files. All methods that
+  # need to interact with files are assumed to adhere to the methods
+  # defined here. Specifically the methods {#write}, {#delete},
+  # {#contents} and {#exists?} are guaranteed to exist and behave in a
+  # way that is consistent across all gems. Unless called out
+  # separately, documentation for those methods here will hold true of
+  # any implementations of this class.
   class File
-    attr_reader :name, :path, :contents
+    # Provides the contents of this file. In the base class, this is
+    # implemented as an attribute, but most implementations will
+    # override this with a method. In most implementations, the
+    # performance cost of reading the file is high enough that we only
+    # want to pay it if it's actually needed.
+    attr_reader :contents
 
-    def initialize(name: nil, path: nil, contents: "")
+    # The name of the file is the actual filename in a directory. In
+    # other words, it is everything that follows the final "/" in the
+    # {#path}. This is always guaranteed to be populated.
+    attr_reader :name
+
+    # The full path to the file this represents. Anything after the
+    # final "/" will also be returned from {#name}. This is not
+    # necessarily guaranteed to be populated, but usually will be.
+    attr_reader :path
+
+    # Basic information associated with a file that is necessary to
+    # enable memory-based interactions.
+    #
+    # @param name [String not containing a "/"] The name of the file. Either this or path must be defined.
+    # @param path [String] The path of the file, will populate name with everything following the final "/".
+    # @param contents [String] The contents of the file, if nil this object will mimic a missing file.
+    def initialize(name: nil, path: nil, contents: nil)
       raise StandardError, "name or path must be defined" unless name || path
       raise Stashify::InvalidFile, "Name '#{name}' contains a /" if name && name =~ %r{/}
 
@@ -15,14 +43,51 @@ module Stashify
       @contents = contents
     end
 
+    # Persists the provided contents into {#path}. If that file does
+    # not exist, it creates it in the process. Otherwise it updates
+    # the existing file.
+    #
+    # In general, if {#exists?} returns false before this is called it
+    # will return true after this is called.
+    #
+    # @note For the base implementation, it will assign something to
+    #   @contents. The value of this instance variable should not be
+    #   relied upon outside of the base implementation though, every
+    #   other implementation so far overrides to an action more
+    #   appropriate to its storage medium.
+    #
+    # @param contents [String] A String describing the contents of the file.
+    # @return No guarantees are made as to the return value of this method,
+    #   it will largely depend on the implementation of the implementing class.
     def write(contents)
       @contents = contents
     end
 
+    # Deletes the underlying file.
+    #
+    # In general, if {#exists?} returns true prior to this method
+    # being called, it will no longer return true after this method is
+    # called.
+    #
+    # @return No guarantees are made as to the return value of this method,
+    #   it will largely depend on the implementation of the implementing class.
     def delete
       @contents = nil
     end
 
+    # Answers if the file exists. In general, it will always return
+    # true after {#write} is called and always return false after
+    # {#delete} is called.
+    #
+    # @note The base class checks if {#contents} returns nil, but this
+    #   is extremely unlikely for other implementations.
+    def exists?
+      !contents.nil?
+    end
+
+    # Two files are considered equal if they have the same name and
+    # contents. This means that equality holds between files in two
+    # separate directories.
     def ==(other)
       name == other.name && contents == other.contents
     end

data/lib/stashify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stashify
-  VERSION = "3.1.0"
+  VERSION = "3.2.1"
 end

data/lib/stashify.rb

@@ -3,5 +3,7 @@
 require_relative "stashify/version"
 
 module Stashify
+  # Error raised when the filename given is invalid. This most likely
+  # means the name parameter contains a "/".
   class InvalidFile < StandardError; end
 end

data/stashify.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/stashify/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "stashify"
+  spec.version = Stashify::VERSION
+  spec.authors = ["Lambda Null"]
+  spec.email = ["lambda.null.42@gmail.com"]
+
+  spec.summary = "Common abstraction for storing files"
+  spec.description = "Provides an abstraction to various services (local filesystem, S3, etc)"
+  spec.homepage = "https://github.com/Lambda-Null/stashify"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stashify
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.1
 platform: ruby
 authors:
 - Lambda Null
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-01 00:00:00.000000000 Z
+date: 2023-04-04 00:00:00.000000000 Z
 dependencies: []
 description: Provides an abstraction to various services (local filesystem, S3, etc)
 email:
@@ -35,9 +35,9 @@ files:
 - lib/stashify/directory/local.rb
 - lib/stashify/file.rb
 - lib/stashify/file/local.rb
-- lib/stashify/local.rb
 - lib/stashify/version.rb
 - sig/stashify.rbs
+- stashify.gemspec
 homepage: https://github.com/Lambda-Null/stashify
 licenses:
 - MIT

data/lib/stashify/local.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Stashify
-  class Local
-    def initialize(path)
-      @path = path
-    end
-  end
-end