sugar_utils 0.5.0 → 0.6.0

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

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

data/spec/spec_helper.rb

@@ -1,10 +1,9 @@
-# encoding : utf-8
 # frozen_string_literal: true
 
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
-require 'sugar_utils'
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'rspec/tabular'
 require 'fakefs/spec_helpers'
+require 'rspec/side_effects'
 require 'etc'
 # HACK: including pp seems to resolve an error with FakeFS and File.read
 # This seems to be related to but not the same as the problem mentioned in the
@@ -16,6 +15,9 @@ require 'pp'
 require 'simplecov'
 SimpleCov.start
 
+require 'sugar_utils'
+MultiJson.use(:ok_json)
+
 SolidAssert.enable_assertions
 
 RSpec.configure do |config|
@@ -48,8 +50,8 @@ RSpec::Matchers.define :have_file_permission do |expected|
   match do |actual|
     next false unless File.exist?(actual)
 
-    @actual   = format('%o', File.stat(actual).mode)
-    @expected = format('%o', expected)
+    @actual   = format('%<mode>o', mode: File.stat(actual).mode)
+    @expected = format('%<mode>o', mode: expected)
     values_match?(@expected, @actual)
   end
 end
@@ -78,7 +80,7 @@ RSpec::Matchers.define :have_mtime do |expected|
   match do |actual|
     next false unless File.exist?(actual)
 
-    @actual   = File.stat(actual).mtime
+    @actual   = File.stat(actual).mtime.to_i
     @expected = expected
     values_match?(@expected, @actual)
   end

data/spec/sugar_utils/file/write_options_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe SugarUtils::File::WriteOptions do
+  subject(:write_options) { described_class.new(filename, options) }
+
+  let(:filename) { nil }
+
+  before do
+    allow(File).to receive(:exist?).with('missing').and_return(false)
+    allow(File).to receive(:exist?).with('found').and_return(true)
+    allow(File::Stat).to receive(:new).with('found').and_return(
+      instance_double(File::Stat, uid: :uid, gid: :gid)
+    )
+  end
+
+  describe '#flush?' do
+    subject { write_options.flush? }
+
+    inputs  :options
+    it_with Hash[],              false
+    it_with Hash[flush: :flush], :flush
+  end
+
+  describe '#perm' do
+    subject { write_options.perm(*args) }
+
+    inputs  :options, :args
+    it_with Hash[],                         [],                0o644
+    it_with Hash[],                         %i[default_value], :default_value
+    it_with Hash[mode: :mode],              [],                :mode
+    it_with Hash[mode: :mode],              %i[default_value], :mode
+    it_with Hash[perm: :perm, mode: :mode], [],                :mode
+    it_with Hash[perm: :perm, mode: :mode], %i[default_value], :mode
+    it_with Hash[perm: :perm],              [],                :perm
+    it_with Hash[perm: :perm],              %i[default_value], :perm
+  end
+
+  describe '#owner' do
+    subject { write_options.owner }
+
+    inputs  :filename, :options
+    it_with nil,       Hash[],              nil
+    it_with 'missing', Hash[],              nil
+    it_with 'found',   Hash[],              :uid
+    it_with nil,       Hash[owner: :owner], :owner
+    it_with 'missing', Hash[owner: :owner], :owner
+    it_with 'found',   Hash[owner: :owner], :owner
+  end
+
+  describe '#group' do
+    subject { write_options.group }
+
+    inputs  :filename, :options
+    it_with nil,       Hash[],              nil
+    it_with 'missing', Hash[],              nil
+    it_with 'found',   Hash[],              :gid
+    it_with nil,       Hash[group: :group], :group
+    it_with 'missing', Hash[group: :group], :group
+    it_with 'found',   Hash[group: :group], :group
+  end
+
+  describe '#slice' do
+    subject { write_options.slice(*args) }
+
+    let(:options) { { key1: :value1, key2: :value2, key3: :value3 } }
+
+    inputs  :args
+    it_with [],                        Hash[]
+    it_with %i[key1],                  Hash[key1: :value1]
+    it_with %i[key2],                  Hash[key2: :value2]
+    it_with %i[key3],                  Hash[key3: :value3]
+    it_with %i[key1 key3],             Hash[key1: :value1, key3: :value3]
+    it_with [%i[key1], nil, %i[key3]], Hash[key1: :value1, key3: :value3]
+  end
+end

data/spec/sugar_utils/file_spec.rb

@@ -1,4 +1,3 @@
-# encoding : utf-8
 # frozen_string_literal: true
 
 require 'spec_helper'
@@ -6,7 +5,9 @@ require 'spec_helper'
 describe SugarUtils::File do
   describe '.flock_shared' do
     subject { described_class.flock_shared(file, options) }
+
     let(:file) { instance_double(File) }
+
     before do
       allow(Timeout).to receive(:timeout).with(expected_timeout).and_yield
       expect(file).to receive(:flock).with(::File::LOCK_SH)
@@ -20,7 +21,9 @@ describe SugarUtils::File do
 
   describe '.flock_exclusive' do
     subject { described_class.flock_exclusive(file, options) }
+
     let(:file) { instance_double(File) }
+
     before do
       allow(Timeout).to receive(:timeout).with(expected_timeout).and_yield
       expect(file).to receive(:flock).with(::File::LOCK_EX)
@@ -32,6 +35,65 @@ describe SugarUtils::File do
     side_effects_with Hash[timeout: 5],   5
   end
 
+  describe '.change_access', :fakefs do
+    subject do
+      described_class.change_access(filename, owner, group, permission)
+    end
+
+    let(:filename) { 'filename' }
+
+    context 'when file does not exist' do
+      let(:owner)      { 'nobody' }
+      let(:group)      { 'nogroup' }
+      let(:permission) { 0o777 }
+
+      it { expect_raise_error("Unable to change access on #{filename}") }
+    end
+
+    context 'when file exists' do
+      before { write(filename, 'foobar') }
+
+      context 'with no values specified' do # rubocop:disable RSpec/NestedGroups
+        let(:owner)      { nil }
+        let(:group)      { nil }
+        let(:permission) { nil }
+
+        it { expect_not_to_raise_error }
+        its_side_effects_are do
+          expect(filename).not_to have_owner('nobody')
+          expect(filename).not_to have_group('nogroup')
+          expect(filename).not_to have_file_permission(0o100777)
+        end
+      end
+
+      context 'with all values(Integer) specified' do # rubocop:disable RSpec/NestedGroups
+        let(:owner)      { Etc.getpwnam('nobody').uid }
+        let(:group)      { Etc.getgrnam('nogroup').gid }
+        let(:permission) { 0o777 }
+
+        it { expect_not_to_raise_error }
+        its_side_effects_are do
+          expect(filename).to have_owner('nobody')
+          expect(filename).to have_group('nogroup')
+          expect(filename).to have_file_permission(0o100777)
+        end
+      end
+
+      context 'with all values specified' do # rubocop:disable RSpec/NestedGroups
+        let(:owner)      { 'nobody' }
+        let(:group)      { 'nogroup' }
+        let(:permission) { 0o777 }
+
+        it { expect_not_to_raise_error }
+        its_side_effects_are do
+          expect(filename).to have_owner('nobody')
+          expect(filename).to have_group('nogroup')
+          expect(filename).to have_file_permission(0o100777)
+        end
+      end
+    end
+  end
+
   describe '.read', :fakefs do
     subject { described_class.read('filename', options) }
 
@@ -45,43 +107,49 @@ describe SugarUtils::File do
       it_with          Hash[raise_on_missing: false, value_on_missing: 'hi'], 'hi'
     end
 
-    context 'missing file' do
+    context 'when missing file' do
       it_behaves_like 'handles the missing file error'
     end
 
     context 'with IOError' do
       before { allow(File).to receive(:open).and_raise(IOError) }
+
       it_behaves_like 'handles the missing file error'
     end
 
-    context 'file present' do
-      before { write('filename', "foo\x92bar") }
+    context 'when file present' do
+      before { write('filename', 'foobar') }
 
-      context 'and locked' do
+      # rubocop:disable RSpec/NestedGroups
+      context 'when locked' do
         let(:options) { { key: :value } }
+
         before do
           expect(described_class).to receive(:flock_shared)
             .with(kind_of(File), options)
             .and_raise(Timeout::Error)
         end
+
         it { expect_raise_error('Cannot read filename because it is locked') }
       end
 
-      context 'and unlocked' do
+      context 'when unlocked' do
         let(:options) { { key: :value, scrub_encoding: scrub_encoding } }
+
         before do
           expect(described_class).to receive(:flock_shared)
             .with(kind_of(File), options)
+          allow(SugarUtils).to receive(:scrub_encoding)
+            .with('foobar', scrub_encoding)
+            .and_return(:scrubbed_data)
         end
 
         inputs  :scrub_encoding
-        it_with nil,            "foo\x92bar"
-        it_with false,          "foo\x92bar"
-        it_with true,           'foobar'
-        it_with '',             'foobar'
-        it_with 'x',            'fooxbar'
-        it_with 'xxx',          'fooxxxbar'
+        it_with nil,             'foobar'
+        it_with false,           'foobar'
+        it_with :scrub_encoding, :scrubbed_data
       end
+      # rubocop:enable RSpec/NestedGroups
     end
   end
 
@@ -110,109 +178,241 @@ describe SugarUtils::File do
 
     let(:filename) { 'path1/path2/filename' }
 
-    before { subject }
-
-    inputs       :options # rubocop:disable ExtraSpacing, SpaceBeforeFirstArg
-    specify_with([])                     { expect(File.exist?(filename)).to eq(true) }
-    specify_with([{ owner: 'nobody' }])  { expect(filename).to have_owner('nobody') }
-    specify_with([{ group: 'nogroup' }]) { expect(filename).to have_group('nogroup') }
-    specify_with([{ mode: 0o600 }])      { expect(filename).to have_file_permission(0o100600) }
-    specify_with([{ perm: 0o600 }])      { expect(filename).to have_file_permission(0o100600) }
-    specify_with([{ mtime: 0 }])         { expect(filename).to have_mtime(0) }
-    specify_with([{ owner: 'nobody', group: 'nogroup', mode: 0o600, mtime: 0 }]) do
-      expect(filename).to have_owner('nobody')
-      expect(filename).to have_group('nogroup')
-      expect(filename).to have_file_permission(0o100600)
-      expect(filename).to have_mtime(0)
+    context 'without options' do
+      let(:options) { [] }
+
+      it { expect_not_to_raise_error }
+      its_side_effects_are { expect(File.exist?(filename)).to eq(true) }
+    end
+
+    context 'with options, and :mode key' do
+      let(:options) { [{ owner: 'nobody', group: 'nogroup', mode: 0o600, mtime: 0 }] }
+
+      it { expect_not_to_raise_error }
+      its_side_effects_are do
+        expect(filename).to have_owner('nobody')
+        expect(filename).to have_group('nogroup')
+        expect(filename).to have_file_permission(0o100600)
+        expect(filename).to have_mtime(0)
+      end
+    end
+
+    context 'with options, and :perm key' do
+      let(:options) { [{ owner: 'nobody', group: 'nogroup', perm: 0o600, mtime: 0 }] }
+
+      it { expect_not_to_raise_error }
+      its_side_effects_are do
+        expect(filename).to have_owner('nobody')
+        expect(filename).to have_group('nogroup')
+        expect(filename).to have_file_permission(0o100600)
+        expect(filename).to have_mtime(0)
+      end
     end
   end
 
   describe '.write', :fakefs do
     subject { described_class.write(filename, data, options) }
+
     let(:data)      { 'content' }
     let(:filename)  { 'dir1/dir2/filename' }
 
-    context 'SystemCallError' do
+    context 'when SystemCallError' do
       let(:options) { {} }
       let(:exception) { SystemCallError.new(nil) }
+
       before { allow(File).to receive(:open).and_raise(exception) }
+
       it { expect_raise_error("Unable to write #{filename} with #{exception}") }
     end
 
-    context 'IOError' do
+    context 'when IOError' do
       let(:options) { {} }
       let(:exception) { IOError.new(nil) }
+
       before { allow(File).to receive(:open).and_raise(exception) }
+
       it { expect_raise_error("Unable to write #{filename} with #{exception}") }
     end
 
-    context 'locked' do
+    context 'when locked' do
       let(:options) { {} }
+
       before do
         expect(described_class).to receive(:flock_exclusive)
           .with(kind_of(File), options)
           .and_raise(Timeout::Error)
       end
+
       it { expect_raise_error("Unable to write #{filename} because it is locked") }
     end
 
-    context 'unlocked' do
-      shared_examples_for 'file is written' do
-        before do
-          expect(described_class).to receive(:flock_exclusive)
-            .with(kind_of(File), options)
+    shared_examples_for 'file is correctly written' do
+      before do
+        expect(described_class).to receive(:flock_exclusive)
+          .with(kind_of(File), options)
+      end
+
+      # rubocop:disable RSpec/NestedGroups
+      context 'without options' do
+        let(:options) { {} }
+
+        it { expect_not_to_raise_error }
+        its_side_effects_are do
+          expect(filename).to have_content(data)
+          expect(filename).to have_file_permission(0o100644)
         end
+      end
 
-        context 'default options' do
-          let(:options) { {} }
-          before { subject }
-          specify { expect(filename).to have_content(data) }
-          specify { expect(filename).to have_file_permission(0o100644) }
+      context 'with options' do
+        let(:options) do
+          { flush: true, owner: 'nobody', group: 'nogroup', mode_or_perm_key => 0o600 }
         end
 
-        context 'with deprecated options' do
-          let(:options) { { mode: 0o600 } }
-          before { subject }
-          specify { expect(filename).to have_content(data) }
-          specify { expect(filename).to have_file_permission(0o100600) }
+        before do
+          # rubocop:disable RSpec/AnyInstance
+          expect_any_instance_of(File).to receive(:flush)
+          expect_any_instance_of(File).to receive(:fsync)
+          # rubocop:enable RSpec/AnyInstance
         end
 
-        context 'without deprecated options' do
-          let(:options) do
-            { flush: true, owner: 'nobody', group: 'nogroup', mode: 'w', perm: 0o600 }
+        context 'with mode key' do
+          let(:mode_or_perm_key) { :mode }
+
+          it { expect_not_to_raise_error }
+          its_side_effects_are do
+            expect(filename).to have_content(data)
+            expect(filename).to have_owner('nobody')
+            expect(filename).to have_group('nogroup')
+            expect(filename).to have_file_permission(0o100600)
           end
-          before do
-            expect_any_instance_of(File).to receive(:flush)
-            expect_any_instance_of(File).to receive(:fsync)
-            subject
+        end
+
+        context 'with perm key' do
+          let(:mode_or_perm_key) { :perm }
+
+          it { expect_not_to_raise_error }
+          its_side_effects_are do
+            expect(filename).to have_content(data)
+            expect(filename).to have_owner('nobody')
+            expect(filename).to have_group('nogroup')
+            expect(filename).to have_file_permission(0o100600)
           end
-          specify { expect(filename).to have_content(data) }
-          specify { expect(filename).to have_owner('nobody') }
-          specify { expect(filename).to have_group('nogroup') }
-          specify { expect(filename).to have_file_permission(0o100600) }
         end
       end
+      # rubocop:enable RSpec/NestedGroups
+    end
+
+    context 'when file does not exist' do
+      it_behaves_like 'file is correctly written'
+    end
+
+    context 'when file exists' do
+      before { write(filename, 'foobar', 0o777) }
+
+      it_behaves_like 'file is correctly written'
+    end
+  end
+
+  describe '.atomic_write', :fakefs do
+    subject { described_class.atomic_write(filename, data, options) }
+
+    let(:data)      { 'content' }
+    let(:filename)  { 'dir1/dir2/filename' }
+
+    context 'when SystemCallError' do
+      let(:options) { {} }
+      let(:exception) { SystemCallError.new(nil) }
+
+      before { allow(File).to receive(:open).and_raise(exception) }
+
+      it { expect_raise_error("Unable to write #{filename} with #{exception}") }
+    end
+
+    context 'when IOError' do
+      let(:options) { {} }
+      let(:exception) { IOError.new(nil) }
 
-      context 'and not exist' do
-        it_behaves_like 'file is written'
+      before { allow(File).to receive(:open).and_raise(exception) }
+
+      it { expect_raise_error("Unable to write #{filename} with #{exception}") }
+    end
+
+    context 'when locked' do
+      let(:options) { {} }
+
+      before do
+        expect(described_class).to receive(:flock_exclusive)
+          .with(kind_of(File), options)
+          .and_raise(Timeout::Error)
       end
 
-      context 'and exists' do
-        before { write(filename, 'foobar', 0o777) }
-        context 'not locked' do
-          it_behaves_like 'file is written'
+      it { expect_raise_error("Unable to write #{filename} because it is locked") }
+    end
+
+    shared_examples_for 'file is correctly written' do
+      before do
+        expect(described_class).to receive(:flock_exclusive)
+          .with(kind_of(File), options)
+      end
+
+      # rubocop:disable RSpec/NestedGroups
+      context 'without options' do
+        let(:options) { {} }
+
+        it { expect_not_to_raise_error }
+        its_side_effects_are do
+          expect(filename).to have_content(data)
+          expect(filename).to have_file_permission(0o100644)
+        end
+      end
 
-          context 'with append mode' do
-            let(:options) { { mode: 'a+' } }
-            before do
-              expect(described_class).to receive(:flock_exclusive)
-                .with(kind_of(File), options)
-              subject
-            end
-            specify { expect(filename).to have_content("foobar#{data}") }
+      context 'with options' do
+        let(:options) do
+          { flush: true, owner: 'nobody', group: 'nogroup', mode_or_perm_key => 0o600 }
+        end
+
+        before do
+          # rubocop:disable RSpec/AnyInstance
+          expect_any_instance_of(File).to receive(:flush)
+          expect_any_instance_of(File).to receive(:fsync)
+          # rubocop:enable RSpec/AnyInstance
+        end
+
+        context 'with mode key' do
+          let(:mode_or_perm_key) { :mode }
+
+          it { expect_not_to_raise_error }
+          its_side_effects_are do
+            expect(filename).to have_content(data)
+            expect(filename).to have_owner('nobody')
+            expect(filename).to have_group('nogroup')
+            expect(filename).to have_file_permission(0o100600)
+          end
+        end
+
+        context 'with perm key' do
+          let(:mode_or_perm_key) { :perm }
+
+          it { expect_not_to_raise_error }
+          its_side_effects_are do
+            expect(filename).to have_content(data)
+            expect(filename).to have_owner('nobody')
+            expect(filename).to have_group('nogroup')
+            expect(filename).to have_file_permission(0o100600)
           end
         end
       end
+      # rubocop:enable RSpec/NestedGroups
+    end
+
+    context 'when file does not exist' do
+      it_behaves_like 'file is correctly written'
+    end
+
+    context 'when file exists' do
+      before { write(filename, 'foobar', 0o777) }
+
+      it_behaves_like 'file is correctly written'
     end
   end
 
@@ -220,30 +420,142 @@ describe SugarUtils::File do
     subject { described_class.write_json(:filename, data, :options) }
 
     let(:data) { { 'key' => 'value' } }
+
     before do
-      expect(described_class).to receive(:write).with(
+      expect(described_class).to receive(:atomic_write).with(
         :filename, MultiJson.dump(data, pretty: true), :options
       )
     end
 
-    specify { subject }
+    it_has_side_effects
+  end
+
+  describe '.append', :fakefs do
+    subject { described_class.append(filename, data, options) }
+
+    let(:data)      { 'content' }
+    let(:filename)  { 'dir1/dir2/filename' }
+
+    context 'when SystemCallError' do
+      let(:options) { {} }
+      let(:exception) { SystemCallError.new(nil) }
+
+      before { allow(File).to receive(:open).and_raise(exception) }
+
+      it { expect_raise_error("Unable to write #{filename} with #{exception}") }
+    end
+
+    context 'when IOError' do
+      let(:options) { {} }
+      let(:exception) { IOError.new(nil) }
+
+      before { allow(File).to receive(:open).and_raise(exception) }
+
+      it { expect_raise_error("Unable to write #{filename} with #{exception}") }
+    end
+
+    context 'when locked' do
+      let(:options) { {} }
+
+      before do
+        expect(described_class).to receive(:flock_exclusive)
+          .with(kind_of(File), options)
+          .and_raise(Timeout::Error)
+      end
+
+      it { expect_raise_error("Unable to write #{filename} because it is locked") }
+    end
+
+    shared_examples_for 'file is correctly appended' do
+      before do
+        expect(described_class).to receive(:flock_exclusive)
+          .with(kind_of(File), options)
+      end
+
+      # rubocop:disable RSpec/NestedGroups
+      context 'without options' do
+        let(:options) { {} }
+
+        it { expect_not_to_raise_error }
+        its_side_effects_are do
+          expect(filename).to have_content(expected_file_data)
+          expect(filename).to have_file_permission(0o100644)
+        end
+      end
+
+      context 'with options' do
+        let(:options) do
+          { flush: true, owner: 'nobody', group: 'nogroup', mode_or_perm_key => 0o600 }
+        end
+
+        before do
+          # rubocop:disable RSpec/AnyInstance
+          expect_any_instance_of(File).to receive(:flush)
+          expect_any_instance_of(File).to receive(:fsync)
+          # rubocop:enable RSpec/AnyInstance
+        end
+
+        context 'with mode key' do
+          let(:mode_or_perm_key) { :mode }
+
+          it { expect_not_to_raise_error }
+          its_side_effects_are do
+            expect(filename).to have_content(expected_file_data)
+            expect(filename).to have_owner('nobody')
+            expect(filename).to have_group('nogroup')
+            expect(filename).to have_file_permission(0o100600)
+          end
+        end
+
+        context 'with perm key' do
+          let(:mode_or_perm_key) { :perm }
+
+          it { expect_not_to_raise_error }
+          its_side_effects_are do
+            expect(filename).to have_content(expected_file_data)
+            expect(filename).to have_owner('nobody')
+            expect(filename).to have_group('nogroup')
+            expect(filename).to have_file_permission(0o100600)
+          end
+        end
+      end
+      # rubocop:enable RSpec/NestedGroups
+    end
+
+    context 'when file does not exist' do
+      let(:expected_file_data) { data }
+
+      it_behaves_like 'file is correctly appended'
+    end
+
+    context 'when file exists' do
+      let(:expected_file_data) { "foobar#{data}" }
+
+      before { write(filename, 'foobar', 0o777) }
+
+      it_behaves_like 'file is correctly appended'
+    end
   end
 
   ##############################################################################
 
-  # @param [String] message
+  # @param message [String]
   def expect_raise_error(message)
     expect { subject }.to raise_error(described_class::Error, message)
   end
 
+  def expect_not_to_raise_error
+    expect { subject }.not_to raise_error
+  end
+
   # @overload write(filename, content)
-  #   @param [String] filename
-  #   @param [String] content
+  #   @param filename [String]
+  #   @param content [String]
   #
   # @overload write(filename, content, perm)
-  #   @param [String] filename
-  #   @param [String] content
-  #   @param [Integer] perm
+  #   @param filename [String]
+  #   @param content [String]
+  #   @param perm [Integer]
   #
   # @return [void]
   def write(filename, content, perm = nil)