sugar_utils 0.5.0 → 0.6.0

data/features/read_json_file.feature

@@ -0,0 +1,43 @@
+Feature: Read a file
+
+Scenario: Read a missing file with a default value
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    MultiJson.use(:ok_json)
+
+    puts SugarUtils::File.read_json('test.json', raise_on_missing: false)
+    """
+  Then the output should contain "{}"
+
+Scenario: Read an existing file
+  Given a file named "test.json" with:
+    """
+    {"key":"value"}
+    """
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    MultiJson.use(:ok_json)
+
+    puts SugarUtils::File.read_json('test.json')
+    """
+  Then the output should contain:
+    """
+    {"key"=>"value"}
+    """
+
+Scenario: Read an existing file and scurb encoding errors
+  Given a file named "test.json" with "test"
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    MultiJson.use(:ok_json)
+
+    File.write('test.json', %({\"key\":\"foo\\x92bar\\x93\"}))
+    puts SugarUtils::File.read_json('test.json', scrub_encoding: true)
+    """
+  Then the output should contain:
+    """
+    {"key"=>"foobar"}
+    """

data/features/scrub_encoding.feature

@@ -0,0 +1,25 @@
+Feature: Ensure the specified value is an integer
+
+Scenario: Pass through string without encoding errors
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils.scrub_encoding('foobar')
+    """
+  Then the output should contain "foobar"
+
+Scenario: Erase encoding errors in the string
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils.scrub_encoding(%(foo\\x92bar\\x93))
+    """
+  Then the output should contain "foobar"
+
+Scenario: Replace encoding errors in the string
+  When I run the following Ruby code:
+    """ruby
+    require 'sugar_utils'
+    puts SugarUtils.scrub_encoding(%(foo\\x92bar\\x93), 'xxx')
+    """
+  Then the output should contain "fooxxxbarxxx"

data/features/step_definitions/steps.rb

@@ -0,0 +1,36 @@
+When('I run the following Ruby code:') do |code|
+  run_command_and_stop %(ruby -e "#{code}")
+end
+
+# Copying the pattern for this step from the default Aruba step for checking
+# the permissions of a file.
+# @see lib/aruba/cucumber/file.rb
+Then(/^the (?:file|directory)(?: named)? "([^"]*)" should( not)? have owner "([^"]*)"$/) do |path, negated, owner|
+  if negated
+    expect(path).not_to have_owner(owner)
+  else
+    expect(path).to have_owner(owner)
+  end
+end
+
+# Copying the pattern for this step from the default Aruba step for checking
+# the permissions of a file.
+# @see lib/aruba/cucumber/file.rb
+Then(/^the (?:file|directory)(?: named)? "([^"]*)" should( not)? have group "([^"]*)"$/) do |path, negated, group|
+  if negated
+    expect(path).not_to have_group(group)
+  else
+    expect(path).to have_group(group)
+  end
+end
+
+# Copying the pattern for this step from the default Aruba step for checking
+# the permissions of a file.
+# @see lib/aruba/cucumber/file.rb
+Then(/^the (?:file|directory)(?: named)? "([^"]*)" should( not)? have modification time "([^"]*)"$/) do |path, negated, modification_time|
+  if negated
+    expect(expand_path(path)).not_to have_mtime(modification_time.to_i)
+  else
+    expect(expand_path(path)).to have_mtime(modification_time.to_i)
+  end
+end

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

@@ -1,19 +1,20 @@
-# encoding : utf-8
 # frozen_string_literal: true
 
 require 'sugar_utils/version'
 require 'sugar_utils/file'
 
+# @api
 module SugarUtils
-  # @param [Object] value
+  # @param value [Object]
   #
   # @return [Boolean]
   def self.ensure_boolean(value)
     return false if value.respond_to?(:to_s) && value.to_s.casecmp('false').zero?
+
     value ? true : false
   end
 
-  # @param [String, Float, Integer] value
+  # @param value [String, Float, Integer]
   #
   # @raise [ArgumentError] if the value is a string which cannot be converted
   # @raise [TypeError] if value is type which cannot be converted
@@ -22,6 +23,33 @@ module SugarUtils
   def self.ensure_integer(value)
     return value      if value.is_a?(Integer)
     return value.to_i if value.is_a?(Float)
+
     Float(value).to_i
   end
+
+  # @overload scrub_encoding(data)
+  #   Scrub the string's encoding, and replace any bad characters with ''.
+  #   @param data [String]
+  # @overload scrub_encoding(data, replacement_character)
+  #   Scrub the string's encoding, and replace any bad characters with the
+  #   specified character.
+  #   @param data [String]
+  #   @param replacement_character [String]
+  #
+  # @return [String]
+  def self.scrub_encoding(data, replacement_character = nil)
+    replacement_character = '' unless replacement_character.is_a?(String)
+
+    # If the Ruby version being used supports String#scrub, then just use it.
+    return data.scrub(replacement_character) if data.respond_to?(:scrub)
+
+    # Otherwise, fall back to String#encode.
+    data.encode(
+      data.encoding,
+      'binary',
+      invalid: :replace,
+      undef:   :replace, # rubocop:disable Layout/AlignHash
+      replace: replacement_character
+    )
+  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 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 MethodLength, 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 MethodLength, 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 MethodLength, 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 MethodLength
       return if Gem::Deprecate.skip
 
       klass  = is_a?(Module)
@@ -216,7 +355,7 @@ 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