stashify 3.2.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8498e1f869ce0f940cbf5e1f1eb65d77fb0692b1df9446b86547a070dcaa6ae
-  data.tar.gz: f27dc8f8accaa1ec01c6aee2705cc3919205d168d82b8fab5b81aa452f90e24a
+  metadata.gz: 035b4f42412c865a6fcabf7944cd6a49169034b974054e20a8eb67ea1f06a4a4
+  data.tar.gz: 4a393454a48b04bc1769fe29a3ea21fe5e4ce501c3443f903e777c7a44b8478e
 SHA512:
-  metadata.gz: d8123084aca3264108000f72216018ca1c6e4a7a6a99bdd82f4f7f4082515bc1fe9ce0d7f268a2bba73e5165e21de903e6c973965728e00dbc7fd4ae0d94a610
-  data.tar.gz: 6f42c931c5dd653fe30a252ff513c3d66ded53c43df31d7aae877eafca20c87e0c2e01d90d0f1df0cab16d2fe85c75eccf5976cec2e61113252f6df06f555f35
+  metadata.gz: 3f3f849fff674adea33a49fbd2c9495cda7d21a64690cf09a828800acfaea5e70cd223ba3400a785e7e8f44f8e1daa3fa5047a44a3de9c0bfe936b91a7099c91
+  data.tar.gz: a13e678a94cdf0844d3d537310af37a0f21e9b55075600cfe47ce186cabee8c52c3ff3981459a630ca7163c1e3d7664aa6b36d0390afe1cfd02df3fd8ed04e37

data/.reek.yml

@@ -1,7 +1,4 @@
 detectors:
-  IrresponsibleModule:
-    enabled: false
-
   TooManyStatements:
     exclude:
       - properties

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.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stashify (3.2.0)
+    stashify (3.2.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -108,6 +108,8 @@ This consistency allows a lot of portability. For instance, pulling in a couple
 	> 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
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

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,29 +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
 
+    # @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,18 +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.2.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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stashify
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.2.1
 platform: ruby
 authors:
 - Lambda Null
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-03 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,7 +35,6 @@ 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

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