file_overwrite 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6552bc81a8cfaf8164a2f1913c03bdb6d72d6df4138fe912b7336e355f8d495
+  data.tar.gz: 1feabdf441fdb9f6ecb148257c1bb03ac38b653d6ef528f966367b21bedd412a
+SHA512:
+  metadata.gz: 25f57ff0bd31eab7acba8265309a0a47fa230c758396cd1eb04cb398ab30713197c54cdfd80e6ed7d0a1578e9185ffbd3c4e13ec886afaadfc80990cf0570693
+  data.tar.gz: a9db5e53923388d9f0710034806d639d03a44a9a287d7d66f3308f14cc27017421f2f156f108fc94c8f1acdaecf576c8dbb050cb27dd3e4cb694a8906e1df163

data/.gitignore

@@ -0,0 +1,27 @@
+*.[oa]
+*.so
+*.dylib
+*~
+*.nogem
+*nogem.*
+*.bak
+*.org
+*.orig
+*.gem
+*.pyc
+*.yardoc
+/doc/*
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+/node_modules
+/yarn-error.log
+
+.byebug_history

data/ChangeLog

@@ -0,0 +1,5 @@
+-----
+(Version: 0.1)
+2018-09-19  Masa Sakano
+
+ * Initial preliminary commit.

data/Makefile

@@ -0,0 +1,22 @@
+ALL	= 
+
+objs	= 
+
+.SUFFIXES:	.so .o .c .f
+
+#.o.so:
+#	${LD} ${LFLAGS} -o $@ $< ${LINK_LIB}
+
+all: ${ALL}
+
+
+.PHONY: clean test doc
+clean:
+	$(RM) bin/*~
+
+test:
+	rake test
+
+doc:
+	yard doc
+

data/README.en.rdoc

@@ -0,0 +1,237 @@
+
+= FileOverwrite - Controller class to backup a file and overwrite it
+
+== Summary
+
+This class provides a Ruby-oriented scheme to safely overwrite an existing file, leaving a backup file unless specified otherwise.  It writes a temporary file first, which is renamed to the original file in one action.  It accepts a block like some IO class-methods (e.g., each_line) and chaining like String methods (e.g., sub and gsub).
+
+This library realises a simple and secure handling to overwrite a file
+on the spot like "-i" command-line option in Ruby, but inside a Ruby
+script (rather than globally as in "-i" option) and with much more flexibility.
+
+== Install
+
+This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
+or above.
+
+Although it is preferable to set the RUBYLIB environment
+variable to the library directory to this gem, which is
+   /THIS/GEM/LIBRARY/PATH/file_overwrite/lib
+it is not essential.  You can simply require the main library file,
+file_overwrite.rb, from your Ruby script and it should work, except
+some error messages can be less helpful in that case.
+
+== Examples
+
+=== Chaining example (with noop, meaning dryrun)
+
+    f1 = FileOverwrite.new('a.txt', noop: true, verbose: true)
+      # Treat the content as String
+    f1.sub(/abc/, 'xyz').gsub(/(.)ef/){|i| $1}.run!
+    f1.completed?  # => true
+    f1.sizes   # => { :old => 40, :new => 50 }
+    f1.backup  # => 'a.txt.20180915.bak'
+               # However, the file has not been created
+               # and the original file has not been modified, either,
+               # due to the noop option
+ 
+=== IO.read type manipulation (String-based block)
+
+    f2 = FileOverwrite.new('a.txt', suffix: '~')
+    f2.backup  # => 'a.txt~'
+    f2.completed?  # => false
+      # Treat the content as String inside the block
+    f2.read{ |str| "\n" + i + "\n" }.gsub(/a\nb/m, '').run!
+    f2.completed?  # => true
+    FileOverwrite.new('a.txt', suffix: '~').sub(/a/, '').run!
+      # => RuntimeError, because the backup file 'a.txt~' exists.
+    FileOverwrite.new('a.txt', suffix: '~').sub(/a/, '').run!(clobber: true)
+      # => The backup file is overwritten.
+ 
+Note the suffix for the backup file in default consists of the date
+and time of the day up to 1 second precision.  Therefore, if you stick
+to the default, even if you run the same process to the same file with
+some interval (longer than 1 second), the original file will not be overwritten,
+although that also means there will be multiple backup files for
+different versions of the file.
+
+=== File.open type manipulation (IO-based block)
+
+    f3 = FileOverwrite.new('a.txt', backup: '/tmp/b.txt')
+      # Backup file can be explicitly specified.
+    f3.backup  # => '/tmp/b.txt'
+    f3.backup = 'original.txt'
+    f3.backup  # => 'original.txt'
+      # Treat the file as IO inside the block
+    f3.open{ |ior, iow| i + "XYZ" }
+    f3.reset   # The modification is discarded
+    f3.reset?  # => true
+    f3.open{ |ior, iow| i + "XYZ"; raise FileOverwriteError, 'I stop.' }
+               # To discard the modification inside the block
+    f3.reset?  # => true
+    f3.open{ |ior, iow| "\n" + i + "\n" }
+    f3.run!(noop: true, verbose: true)  # Dryrun
+    f3.completed?  # => true
+    f3.backup = 'change.d'  # => FrozenError (the state can not be modified after run!(), including dryrun)
+ 
+=== IO.readlines type manipulation (Array-based block)
+
+    f4 = FileOverwrite.new('a.txt', suffix: nil)
+    f4.backup  # => nil (No backup file is created.)
+    f4.readlines{|ary| ary+["last\n"]}.each{|i| 'XX'+i}.run!
+    # The content of the file is,
+    IO.readlines('a.txt')[-1]   # => "XXlast\n"
+ 
+=== If the file is examined but if the content is not updated?
+
+    f5 = FileOverwrite.new('a.txt', suffix: '.bak')
+    f5.backup  # => 'a.txt.bak'
+    f5.read{|i| i}.run!
+    FileUtils.identical? 'a.txt', 'a.txt.bak'       # => true
+    File.mtime('a.txt') == File.mtime('a.txt.bak')  # => true
+      # To forcibly update the Timestamp, give touch option as true
+      # either in new() or run!(), ie., run!(touch: true)
+
+Note if the input file is not touched at all, the file is never
+*touch*-ed, regardless of the touch option:
+
+    FileOverwrite.new('a.txt', touch: true).run!  # => No operation
+
+== Description
+
+=== Content manipulation
+
+Three types of manipulation for the content of the file to update are allowed: IO, String, and Array.
+
+==== IO-type manipulation
+
+IO-type manipulation includes
+
+* open (or modify)
+
+Two block parameters of IO instances are given (read and write in this order).
+What is output (i.e., IO#print method) with the write-descriptor
+inside the block will be the content of the overwritten file.
+
+This method can *not* be chained.  Once you call the method for manipulation,
+you have to either {FileOverwrite#run!}, or {FileOverwrite#reset} and do the manipulation from
+the beginning.  For convenience, the same method names with the
+trailing '!' are defined ({FileOverwrite#open!} and {FileOverwrite#modify!}), with which {FileOverwrite#run!} will be performed automatically.
+
+==== String-type manipulation
+
+String-type manipulation includes
+
+* read (with block)
+* sub  (with or without block)
+* gsub (with or without block)
+* tr
+* tr_s
+* replace_with (same as String#replace, but can be chained)
+* each_line (with block)
+
+These methods must return String (or its equivalent) that will be written in the updated file.
+Those that take block never return Enumerator (like String#sub).
+
+The biggest advantage is you can chain these methods, before calling
+{FileOverwrite#run!}, as in the examples above.
+
+Note that "each"-something-type methods in this class are the
+short-hands of the following, and expect each iterator returns String:
+    fo.read{ |allstr| 
+      outstr = ''
+      allstr.each_line do |i|
+        # Do whatever
+        outstr << result
+      end
+      outstr
+    }
+
+Just like IO-type methods, they can be called with a trailing '!' to
+perform {FileOverwrite#run!} straightaway.
+
+Note that once you call one of manipulations of this type, the entire
+content of the input file is stored in the memory until {FileOverwrite#run!} is
+called and the object is GC-ed.  For a very large file, IO-type
+manipulation is more appropriate.
+
+==== Array-type manipulation
+
+Similarly, an Array-type manipulation is defined:
+
+* readlines
+
+The "readlines" method must return Array (or its equivalent) that will be
+written in the updated file, where all the elements are simply concatenated.
+
+This method can be concatenated with this method only, and can not be
+combined with manipulations in the other types.
+
+Just like IO-type methods, this can be called with a trailing '!' to
+perform {FileOverwrite#run!} straightaway.
+
+=== Other methods
+
+==== Those related to the state
+
+{FileOverwrite#fresh?}:: True if the process has not begun (the file is not read, yet)
+{FileOverwrite#ready?}:: True if it is ready to output (overwriting the file)
+{FileOverwrite#reset}:: Cancel the current processing and start the text processing from the beginning, as read from the original file.
+{FileOverwrite#chainable?}:: True if the current state is chainable with other methods, namely in the String- or Array-type manipulations.
+{FileOverwrite#completed?}:: True if the overwriting process has been completed, and the instance is frozen.
+{FileOverwrite#state}:: True if completed, nil if {FileOverwrite#fresh?}, or Class (IO, String, Array), depending on which type of manipulation has been in place.
+{FileOverwrite#empty?}:: Synonym of {FileOverwrite#dump}.empty?
+{FileOverwrite#end_with?}:: Synonym of {FileOverwrite#dump}.end_with?
+{FileOverwrite#force_encoding}(enc):: Sets the encoding of the current or to-be-read String (or Array).  The encoding set is not affected even after {FileOverwrite#reset}
+{FileOverwrite#valid_encoding?}:: As in <tt>String#valid_encoding?</tt>  Note this returns nil if {FileOverwrite#completed?}
+
+==== Those related to the parameters
+
+Note none of the write-methods are available once {FileOverwrite#completed?}
+
+{FileOverwrite#backup}:: (read/write) Filename (String) of the backup file.
+{FileOverwrite#dump}:: Dump the String of the original file if {FileOverwrite#fresh?}, the current one to be output if in the middle of process, or that of the written file if {FileOverwrite#completed?}
+{FileOverwrite#encode}:: Converts the internal encoding of the current or to-be-read String (or Array), i.e., the encoding of String passed to the user would be this encoding, providing the conversion goes successfully.
+{FileOverwrite#sizes}:: (read-only) Hash of :old and :new files of the sizes. This is set only after {FileOverwrite#run!}  If both setsize and verbose options are false in {FileOverwrite#run!} (the former is true in default), the file size calculation is suppressed and hence this returns nil.
+{FileOverwrite#verbose}:: (read/write) The default value is set in the constructor, which can be overwritten any time with this method, and for temporarily in {FileOverwrite#run!}
+{FileOverwrite#ext_enc_old}, {FileOverwrite#ext_enc_new}:: (read/write) Character-encoding of the file to read and write, respectively. The former can be overwritten with the {FileOverwrite#force_encoding}(enc) method, too.
+{FileOverwrite#int_enc}:: (read/write) If set, Character-encoding of the String read from the file is (attempted to be) converted into this before user's processing. This can be overwritten with the {FileOverwrite#encode}() method, too.
+
+== Developer's note
+
+The source codes are annotated in the {YARD}[https://yardoc.org/] format.
+You can view it in {RubyGems/file_overwrite}[https://rubygems.org/gems/file_overwrite].
+
+=== Algorithm
+
+(1) It first writes a temporary file according to your manipulation.
+(2) Then when you perform {FileOverwrite#run!}, the following is done in one go:
+    * the original file is backed up to the specified backup file,
+    * the temporary file is renamed to the original file,
+    * if it is instructed to leave no backup file, the backup file is deleted.
+(3) After {FileOverwrite#run!}, the instance of this class is still accessible but frozen.
+
+If {FileOverwrite#run!} or its equivalent is not performed, the temporary file will be
+deleted by GC.
+
+=== Tests
+
+Ruby codes under the directory <tt>test/</tt> are the test scripts.
+You can run them from the top directory as <tt>ruby test/test_****.rb</tt>
+or simply run <tt>make test</tt>.
+
+
+== Known bugs
+
+None.
+
+
+== Copyright
+
+Author::  Masa Sakano < info a_t wisebabel dot com >
+Versions:: The versions of this package follow Semantic Versioning (2.0.0) http://semver.org/
+
+
+LocalWords:  FileOverwrite gsub RUBYLIB rb noop dryrun txt ior iow
+LocalWords:  RuntimeError XYZ FileOverwriteError FrozenError ary
+LocalWords:  readlines FileUtils mtime allstr outstr chainable

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test
+

data/file_overwrite.gemspec

@@ -0,0 +1,45 @@
+# -*- encoding: utf-8 -*-
+
+require 'rake'
+
+Gem::Specification.new do |s|
+  s.name = %q{file_overwrite}
+  s.version = "0.1"
+  # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  # s.bindir = 'bin'
+  s.authors = ["Masa Sakano"]
+  s.date = Time.now.strftime("%Y-%m-%d")
+  s.summary = %q{Class to overwrite an existing file safely}
+  s.description = %q{This class provides a Ruby-oriented scheme to safely overwrite an existing file, leaving a backup file unless specified otherwise.  It writes a temporary file first, which is renamed to the original file in one action.  It accepts a block like some IO class-methods (e.g., each_line) and chaining like String methods (e.g., sub and gsub).}
+  # s.email = %q{abc@example.com}
+  s.extra_rdoc_files = [
+    # "LICENSE",
+     "README.en.rdoc",
+  ]
+  s.license = 'MIT'
+  s.files = FileList['.gitignore','lib/**/*.rb','[A-Z]*','test/**/*.rb', '*.gemspec'].to_a.delete_if{ |f|
+    ret = false
+    arignore = IO.readlines('.gitignore')
+    arignore.map{|i| i.chomp}.each do |suffix|
+      if File.fnmatch(suffix, File.basename(f))
+        ret = true
+        break
+      end
+    end
+    ret
+  }
+  s.files.reject! { |fn| File.symlink? fn }
+  # s.add_runtime_dependency 'rails'
+  # s.add_development_dependency "bourne", [">= 0"]
+  s.homepage = %q{https://www.wisebabel.com}
+  s.rdoc_options = ["--charset=UTF-8"]
+
+  # s.require_paths = ["lib"]	# Default "lib"
+  s.required_ruby_version = '>= 2.0'
+  s.test_files = Dir['test/**/*.rb']
+  s.test_files.reject! { |fn| File.symlink? fn }
+  # s.requirements << 'libmagick, v6.0' # Simply, info to users.
+  # s.rubygems_version = %q{1.3.5}      # This is always set automatically!!
+  s.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs.
+end
+