sugar_utils 0.5.0 → 0.7.0

data/features/support/env.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'aruba/cucumber'
+
+# @see spec/spec_helper.rb
+RSpec::Matchers.define :have_owner do |expected|
+  match do |actual|
+    next false unless File.exist?(actual)
+
+    @actual   = Etc.getpwuid(File.stat(filename).uid).name
+    @expected = expected
+    values_match?(@expected, @actual)
+  end
+end
+
+RSpec::Matchers.define :have_group do |expected|
+  match do |actual|
+    next false unless File.exist?(actual)
+
+    @actual   = Etc.getgrgid(File.stat(actual).gid).name
+    @expected = expected
+    values_match?(@expected, @actual)
+  end
+end
+
+RSpec::Matchers.define :have_mtime do |expected|
+  match do |actual|
+    next false unless File.exist?(actual)
+
+    @actual   = File.stat(actual).mtime.to_i
+    @expected = expected
+    values_match?(@expected, @actual)
+  end
+end

data/features/touch_file.feature

@@ -0,0 +1,28 @@
+Feature: Touch a file
+
+Scenario: Touch a file
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils::File.touch('dir/test')
+    """
+  Then the file named "dir/test" should exist
+
+# TODO: Fix the owner/group setting check
+Scenario: Touch a file and reset its permissions and mtime
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils::File.touch(
+      'dir/test',
+      # owner: 'nobody',
+      # group: 'nogroup',
+      mode:  0o777,
+      mtime: 0
+    )
+    """
+  Then the file named "dir/test" should exist
+    And the file named "dir/test" should have permissions "777"
+    And the file named "dir/test" should have modification time "0"
+    # And the file named "dir/test" should have owner "nobody"
+    # And the file named "dir/test" should have group "nogroup"

data/features/write_file.feature

@@ -0,0 +1,46 @@
+Feature: Write to a file
+
+Scenario: Write a file
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils::File.write('dir/test', 'foobar')
+    """
+  Then the file named "dir/test" should contain exactly:
+    """
+    foobar
+    """
+
+Scenario: Overwrite a file
+  Given a file named "dir/test" with "deadbeef"
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils::File.write('dir/test', 'foobar')
+    """
+  Then the file named "dir/test" should contain exactly:
+    """
+    foobar
+    """
+
+# TODO: Fix the owner/group setting check
+Scenario: Overwrite a file and reset its permissions
+  Given a file named "dir/test" with "deadbeef"
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils::File.write(
+      'dir/test',
+      'foobar',
+      # owner: 'nobody',
+      # group: 'nogroup',
+      mode:  0o777
+    )
+    """
+  Then the file named "dir/test" should contain exactly:
+    """
+    foobar
+    """
+    And the file named "dir/test" should have permissions "777"
+    # And the file named "dir/test" should have owner "nobody"
+    # And the file named "dir/test" should have group "nogroup"

data/features/write_json_file.feature

@@ -0,0 +1,52 @@
+Feature: Write JSON to a file
+
+Scenario: Write a file
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    MultiJson.use(:ok_json)
+
+    puts SugarUtils::File.write_json('dir/test.json', { key: :value })
+    """
+  Then the file named "dir/test.json" should contain exactly:
+    """
+    {"key":"value"}
+    """
+
+Scenario: Overwrite a file
+  Given a file named "dir/test.json" with "deadbeef"
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    MultiJson.use(:ok_json)
+
+    puts SugarUtils::File.write_json('dir/test.json', { key: :value })
+    """
+  Then the file named "dir/test.json" should contain exactly:
+    """
+    {"key":"value"}
+    """
+
+# TODO: Fix the owner/group setting check
+Scenario: Overwrite a file and reset its permissions
+  Given a file named "dir/test.json" with "deadbeef"
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    MultiJson.use(:ok_json)
+
+    puts SugarUtils::File.write_json(
+      'dir/test.json',
+      { key: :value },
+      # owner: 'nobody',
+      # group: 'nogroup',
+      mode:  0o777
+    )
+    """
+  Then the file named "dir/test.json" should contain exactly:
+    """
+    {"key":"value"}
+    """
+    And the file named "dir/test.json" should have permissions "777"
+    # And the file named "dir/test.json" should have owner "nobody"
+    # And the file named "dir/test.json" should have group "nogroup"

data/lib/sugar_utils/file/write_options.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SugarUtils
+  module File
+    # @api private
+    class WriteOptions
+      # @parma filename [String]
+      # @param options [Hash]
+      def initialize(filename, options)
+        @filename = filename
+        @options  = options
+
+        return unless filename && ::File.exist?(filename)
+
+        file_stat       = ::File::Stat.new(filename)
+        @existing_owner = file_stat.uid
+        @existing_group = file_stat.gid
+      end
+
+      # @return [Boolean]
+      def flush?
+        @options[:flush] || false
+      end
+
+      # @overload perm
+      #   The default permission is 0o644
+      # @overload perm(default_value)
+      #   @param default_value [nil, Integer]
+      #   Override the default_value including allowing nil.
+      #
+      # @return [Integer]
+      def perm(default_value = 0o644)
+        # NOTE: We are using the variable name 'perm' because that is the name
+        # of the argument used by File.open.
+        @options[:mode] || @options[:perm] || default_value
+      end
+
+      # @return [String, Integer]
+      def owner
+        @options[:owner] || @existing_owner
+      end
+
+      # @return [String, Intekuuger]
+      def group
+        @options[:group] || @existing_group
+      end
+
+      # @param keys [Array]
+      # @return [Hash]
+      def slice(*args)
+        keys = args.flatten.compact
+        @options.select { |k| keys.include?(k) }
+      end
+    end
+  end
+end

data/lib/sugar_utils/file.rb

@@ -1,17 +1,20 @@
-# encoding : utf-8
 # frozen_string_literal: true
 
 require 'solid_assert'
 require 'fileutils'
 require 'multi_json'
 require 'timeout'
+require 'tempfile'
+
+require 'sugar_utils/file/write_options'
 
 module SugarUtils
-  module File
+  # @api
+  module File # rubocop:disable Metrics/ModuleLength
     class Error < StandardError; end
 
-    # @param [File] file
-    # @param [Hash] options
+    # @param file [File]
+    # @param options [Hash]
     # @option options [Integer] :timeout (10)
     #
     # @raise [Timeout::Error]
@@ -22,8 +25,8 @@ module SugarUtils
       Timeout.timeout(timeout) { file.flock(::File::LOCK_SH) }
     end
 
-    # @param [File] file
-    # @param [Hash] options
+    # @param file [File]
+    # @param options [Hash]
     # @option options [Integer] :timeout (10)
     #
     # @raise [Timeout::Error]
@@ -34,8 +37,34 @@ module SugarUtils
       Timeout.timeout(timeout) { file.flock(::File::LOCK_EX) }
     end
 
-    # @param [String] filename
-    # @param [Hash] options
+    # Change all of the access values for the specified file including:
+    # * owner
+    # * group
+    # * permissions
+    #
+    # @note Although the are all required, nil can be passed to any of them and
+    # those nils will be skipped. Hopefully, this will avoid conditions in the
+    # calling code because the optional parameters will just be passed in and
+    # skipped when they are missing.
+    #
+    # @param filename [String]
+    # @param owner [nil, Integer, String]
+    # @param group [nil, Integer, String]
+    # @param permission [nil, Integer]
+    #
+    # @raise [SugarUtils::File::Error]
+    #
+    # @return [void]
+    def self.change_access(filename, owner, group, permission)
+      FileUtils.chown(owner, group, filename)
+      FileUtils.chmod(permission, filename) if permission
+      nil
+    rescue SystemCallError, IOError
+      raise(Error, "Unable to change access on #{filename}")
+    end
+
+    # @param filename [String]
+    # @param options [Hash]
     # @option options [Integer] :timeout (10)
     # @option options [Boolean] :raise_on_missing (true)
     # @option options [String] :value_on_missing ('') which specifies the
@@ -46,7 +75,7 @@ module SugarUtils
     # @raise [SugarUtils::File::Error]
     #
     # @return [String]
-    def self.read(filename, options = {}) # rubocop:disable MethodLength, AbcSize, CyclomaticComplexity, PerceivedComplexity
+    def self.read(filename, options = {}) # rubocop:disable Metrics/MethodLength
       options[:value_on_missing] ||= ''
       options[:raise_on_missing] = true if options[:raise_on_missing].nil?
 
@@ -58,32 +87,17 @@ module SugarUtils
 
       return result unless options[:scrub_encoding]
 
-      replacement_character =
-        if options[:scrub_encoding].is_a?(String)
-          options[:scrub_encoding]
-        else
-          ''
-        end
-      if result.respond_to?(:scrub)
-        result.scrub(replacement_character)
-      else
-        result.encode(
-          result.encoding,
-          'binary',
-          invalid: :replace,
-          undef:   :replace,
-          replace: replacement_character
-        )
-      end
+      SugarUtils.scrub_encoding(result, options[:scrub_encoding])
     rescue SystemCallError, IOError
       raise(Error, "Cannot read #{filename}") if options[:raise_on_missing]
+
       options[:value_on_missing]
     rescue Timeout::Error
       raise(Error, "Cannot read #{filename} because it is locked")
     end
 
-    # @param [String] filename
-    # @param [Hash] options
+    # @param filename [String]
+    # @param options [Hash]
     # @option options [Integer] :timeout (10)
     # @option options [Boolean] :raise_on_missing (true)
     #
@@ -101,62 +115,57 @@ module SugarUtils
       raise(Error, "Cannot parse #{filename}")
     end
 
-    # @param [String] filename
-    # @param [Hash] options
+    # Touch the specified file.
+    #
+    # @param filename [String]
+    # @param options [Hash]
     # @option options [String, Integer] :owner
     # @option options [String, Integer] :group
-    # @option options [Integer] :mode @deprecated
+    # @option options [Integer] :mode
     # @option options [Integer] :perm
     # @option options [Integer] :mtime
     #
     # @return [void]
     def self.touch(filename, options = {})
-      owner         = options[:owner]
-      group         = options[:group]
-      perm          = options[:perm]
-      touch_options = options.select { |k| %i[mtime].include?(k) }
-
-      if options[:mode].is_a?(Integer)
-        perm = options[:mode]
-        deprecate_option(:touch, :mode, :perm, 2018, 7)
-      end
+      write_options = WriteOptions.new(filename, options)
 
       FileUtils.mkdir_p(::File.dirname(filename))
-      FileUtils.touch(filename, touch_options)
-      FileUtils.chown(owner, group, filename)
-      FileUtils.chmod(perm, filename) if perm
+      FileUtils.touch(filename, **write_options.slice(:mtime))
+      change_access(
+        filename,
+        write_options.owner,
+        write_options.group,
+        write_options.perm(nil)
+      )
     end
 
-    # @param [String] filename
-    # @param [#to_s] data
-    # @param [Hash] options
+    # Write to an existing file, overwriting it, or create the file if it does
+    # not exist.
+    #
+    # @note Either option :mode or :perm can be used to specific the permissions
+    # on the file being written to. This aliasing is used because both these
+    # names are used in the standard library, File.open uses :perm and FileUtils
+    # uses :mode. The user can choose whichever alias makes their code most
+    # readable.
+    #
+    # @param filename [String]
+    # @param data [#to_s]
+    # @param options [Hash]
     # @option options [Integer] :timeout (10)
     # @option options [Boolean] :flush (false)
     # @option options [String, Integer] :owner
     # @option options [String, Integer] :group
-    # @option options [String] :mode (w+)
+    # @option options [Integer] :mode (0o644)
     # @option options [Integer] :perm (0o644)
     #
     # @raise [SugarUtils::File::Error]
     #
     # @return [void]
-    def self.write(filename, data, options = {}) # rubocop:disable MethodLength, AbcSize, CyclomaticComplexity
-      flush = options[:flush] || false
-      owner = options[:owner]
-      group = options[:group]
-      perm  = options[:perm] || 0o644
-      mode  = 'w+'
-
-      if options[:mode].is_a?(Integer)
-        perm = options[:mode]
-
-        deprecate_option(:write, :mode, ' with an integer value; use perm instead', 2018, 7)
-      elsif !options[:mode].nil?
-        mode = options[:mode]
-      end
+    def self.write(filename, data, options = {}) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      write_options = WriteOptions.new(filename, options)
 
       FileUtils.mkdir_p(::File.dirname(filename))
-      ::File.open(filename, mode, perm) do |file|
+      ::File.open(filename, 'w+', write_options.perm) do |file|
         flock_exclusive(file, options)
 
         file.puts(data.to_s)
@@ -165,33 +174,163 @@ module SugarUtils
         # are often reading it immediately and if the OS is buffering, it is
         # possible we might read it before it is been physically written to
         # disk. We are not worried about speed here, so this should be OKAY.
-        if flush
+        if write_options.flush?
           file.flush
           file.fsync
         end
+      end
+
+      change_access(
+        filename,
+        write_options.owner,
+        write_options.group,
+        write_options.perm
+      )
+    rescue Timeout::Error
+      raise(Error, "Unable to write #{filename} because it is locked")
+    rescue SystemCallError, IOError => e
+      raise(Error, "Unable to write #{filename} with #{e}")
+    end
 
-        # Ensure that the permissions are correct if the file already existed.
-        file.chmod(perm)
+    # Atomically write to an existing file, overwriting it, or create the file
+    # if it does not exist.
+    #
+    # @note Either option :mode or :perm can be used to specific the permissions
+    # on the file being written to. This aliasing is used because both these
+    # names are used in the standard library, File.open uses :perm and FileUtils
+    # uses :mode. The user can choose whichever alias makes their code most
+    # readable.
+    #
+    # @param filename [String]
+    # @param data [#to_s]
+    # @param options [Hash]
+    # @option options [Integer] :timeout (10)
+    # @option options [Boolean] :flush (false)
+    # @option options [String, Integer] :owner
+    # @option options [String, Integer] :group
+    # @option options [Integer] :mode (0o644)
+    # @option options [Integer] :perm (0o644)
+    #
+    # @raise [SugarUtils::File::Error]
+    #
+    # @return [void]
+    def self.atomic_write(filename, data, options = {}) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      write_options = WriteOptions.new(filename, options)
+
+      # @note This method is similar to the atomic_write which is implemented in
+      # ActiveSupport. We re-implemented the method because of the following:
+      # * we needed the method, but wanted to avoid pulling in the entire
+      #   ActiveSupport gem.
+      # * we wnated to keep the behaviour and interface consistent with the other
+      #   SugarUtils write methods
+      #
+      # @see https://apidock.com/rails/File/atomic_write/class
+      FileUtils.mkdir_p(::File.dirname(filename))
+      Tempfile.open(::File.basename(filename, '.*'), ::File.dirname(filename)) do |temp_file|
+        temp_file.puts(data.to_s)
+        # Flush and fsync to be 100% sure we write this data out now because we
+        # are often reading it immediately and if the OS is buffering, it is
+        # possible we might read it before it is been physically written to
+        # disk. We are not worried about speed here, so this should be OKAY.
+        if write_options.flush?
+          temp_file.flush
+          temp_file.fsync
+        end
+        temp_file.close
+
+        ::File.open(filename, 'w+', write_options.perm) do |file|
+          flock_exclusive(file, options)
+          FileUtils.move(temp_file.path, filename)
+        end
       end
-      FileUtils.chown(owner, group, filename)
+
+      change_access(
+        filename,
+        write_options.owner,
+        write_options.group,
+        write_options.perm
+      )
     rescue Timeout::Error
       raise(Error, "Unable to write #{filename} because it is locked")
-    rescue SystemCallError, IOError => boom
-      raise(Error, "Unable to write #{filename} with #{boom}")
+    rescue SystemCallError, IOError => e
+      raise(Error, "Unable to write #{filename} with #{e}")
     end
 
-    # @param [String] filename
-    # @param [#to_json] data
-    # @param [Hash] options
+    # Write the data parameter as JSON to the filename path.
+    #
+    # @note Either option :mode or :perm can be used to specific the permissions
+    # on the file being written to. This aliasing is used because both these
+    # names are used in the standard library, File.open uses :perm and FileUtils
+    # uses :mode. The user can choose whichever alias makes their code most
+    # readable.
+    #
+    # @param filename [String]
+    # @param data [#to_json]
+    # @param options [Hash]
     # @option options [Integer] :timeout (10)
     # @option options [Boolean] :flush (false)
-    # @option options [Integer] :perm (0644)
+    # @option options [String, Integer] :owner
+    # @option options [String, Integer] :group
+    # @option options [Integer] :mode (0o644)
+    # @option options [Integer] :perm (0o644)
     #
     # @raise [SugarUtils::File::Error]
     #
     # @return [void]
     def self.write_json(filename, data, options = {})
-      write(filename, MultiJson.dump(data, pretty: true), options)
+      atomic_write(filename, MultiJson.dump(data, pretty: true), options)
+    end
+
+    # Append to an existing file, or create the file if it does not exist.
+    #
+    # @note Either option :mode or :perm can be used to specific the permissions
+    # on the file being written to. This aliasing is used because both these
+    # names are used in the standard library, File.open uses :perm and FileUtils
+    # uses :mode. The user can choose whichever alias makes their code most
+    # readable.
+    #
+    # @param filename [String]
+    # @param data [#to_s]
+    # @param options [Hash]
+    # @option options [Integer] :timeout (10)
+    # @option options [Boolean] :flush (false)
+    # @option options [String, Integer] :owner
+    # @option options [String, Integer] :group
+    # @option options [Integer] :mode (0o644)
+    # @option options [Integer] :perm (0o644)
+    #
+    # @raise [SugarUtils::File::Error]
+    #
+    # @return [void]
+    def self.append(filename, data, options = {}) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      write_options = WriteOptions.new(filename, options)
+
+      FileUtils.mkdir_p(::File.dirname(filename))
+      ::File.open(filename, 'a', write_options.perm) do |file|
+        flock_exclusive(file, options)
+
+        file.puts(data.to_s)
+
+        # Flush and fsync to be 100% sure we write this data out now because we
+        # are often reading it immediately and if the OS is buffering, it is
+        # possible we might read it before it is been physically written to
+        # disk. We are not worried about speed here, so this should be OKAY.
+        if write_options.flush?
+          file.flush
+          file.fsync
+        end
+      end
+
+      change_access(
+        filename,
+        write_options.owner,
+        write_options.group,
+        write_options.perm
+      )
+    rescue Timeout::Error
+      raise(Error, "Unable to write #{filename} because it is locked")
+    rescue SystemCallError, IOError => e
+      raise(Error, "Unable to write #{filename} with #{e}")
     end
 
     ############################################################################
@@ -199,7 +338,7 @@ module SugarUtils
     # Following the same pattern as the existing stdlib method deprecation
     # module.
     # @see http://ruby-doc.org/stdlib-2.0.0/libdoc/rubygems/rdoc/Gem/Deprecate.html
-    def self.deprecate_option(_method, option_name, option_repl, year, month) # rubocop:disable MethodLength, AbcSize
+    def self.deprecate_option(_method, option_name, option_repl, year, month) # rubocop:disable Metrics/MethodLength
       return if Gem::Deprecate.skip
 
       klass  = is_a?(Module)
@@ -216,13 +355,17 @@ module SugarUtils
         "NOTE: #{target}#{method} option :#{option_name} is deprecated",
         case option_repl
         when :none
-          ' with no replacement' 
+          ' with no replacement'
         when String
           option_repl
         else
           "; use :#{option_repl} instead"
         end,
-        format('. It will be removed on or after %4d-%02d-01.', year, month),
+        format(
+          '. It will be removed on or after %<year>4d-%<month>02d-01.',
+          year:  year,
+          month: month
+        ),
         "\n#{target}#{method} called from #{location_of_external_caller}"
       ]
       warn("#{msg.join}.")

data/lib/sugar_utils/version.rb

@@ -1,6 +1,5 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
 module SugarUtils
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end