file_overwrite 0.1 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6552bc81a8cfaf8164a2f1913c03bdb6d72d6df4138fe912b7336e355f8d495
-  data.tar.gz: 1feabdf441fdb9f6ecb148257c1bb03ac38b653d6ef528f966367b21bedd412a
+  metadata.gz: 6db0d19a4e47ac84f622ac13f773b5eebe35187dd988e45e378ff60ad5062f48
+  data.tar.gz: 506a41b185811a8ac654141785e7b0022e54f9fcec30b6a59fd6b5fc3d432324
 SHA512:
-  metadata.gz: 25f57ff0bd31eab7acba8265309a0a47fa230c758396cd1eb04cb398ab30713197c54cdfd80e6ed7d0a1578e9185ffbd3c4e13ec886afaadfc80990cf0570693
-  data.tar.gz: a9db5e53923388d9f0710034806d639d03a44a9a287d7d66f3308f14cc27017421f2f156f108fc94c8f1acdaecf576c8dbb050cb27dd3e4cb694a8906e1df163
+  metadata.gz: dbc80fba6539d7257e7c8bf8ce48ba56191d0083de67dddc1b5c8b678e7ed5dab0ea8459946310a78e9732181ca184107d90ee43855a7d40af4bb06762b0018a
+  data.tar.gz: b4a8bfc7e2c31ba80000f937ed04c77a5e1374aeeae3a4ed102073ff74f5c467cf054597807b7149957910275c365b0104cd95cd07d39a72d9bd521cda02770a

data/ChangeLog

@@ -1,4 +1,19 @@
 -----
+(Version: 1.0)
+2018-10-13  Masa Sakano
+  * Major upgrade. sub and gsub now accept local-scope variables like $1.
+  
+  * A bug in dump is fixed.
+  * Added alias save, the methods path and `last_match`, class methods modify! (open!), read, `each_line`.
+  * Added `.github/README.md`
+  * Major update in README
+  * Tests added accordingly.
+
+-----
+2018-10-12  Masa Sakano
+
+ * mv lib/file_overwrite/file_overwrite.rb lib/file_overwrite.rb
+-----
 (Version: 0.1)
 2018-09-19  Masa Sakano
 

data/Makefile

@@ -18,5 +18,5 @@ test:
 	rake test
 
 doc:
-	yard doc
+	yard doc; ruby -r rdoc -e 'puts RDoc::Markup::ToMarkdown.new.convert File.read("README.en.rdoc")' > .github/README.md; ls -lF doc/file.README.en.html .github/README.md
 

data/README.en.rdoc

@@ -1,14 +1,23 @@
 
-= FileOverwrite - Controller class to backup a file and overwrite it
+= FileOverwrite - Controller class to overwrite a file with/without a backup file
 
 == 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 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 or Array class-methods (e.g., +each_line+ and +readlines+) and
+chaining like String methods (e.g., +read+, +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.
 
+The master of this README file, as well as the document for all the methods, is found in
+{RubyGems/file_overwrite}[https://rubygems.org/gems/file_overwrite] where all
+the hyperlinks are active.
+
 == Install
 
 This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
@@ -23,18 +32,70 @@ some error messages can be less helpful in that case.
 
 == Examples
 
+=== Basic examples (short-hand versions)
+
+The following six examples perform the identical operations.
+
+    f1 = FileOverwrite.new('a.txt'); f1.open{|ior, iow| iow.print ior.read.upcase}.save!
+    f2 = FileOverwrite.open!('b.txt'){|ior, iow| iow.print ior.read.upcase}
+    f3 = FileOverwrite.read!('c.txt'){|s| s.upcase}
+    f4 = FileOverwrite.read('d.txt').sub!(/.*/m){$&.upcase}
+    f5 = FileOverwrite.each_line!('e.txt'){|s| s.upcase}
+    f6 = FileOverwrite.readlines!('f.txt'){|a| a.map{|i| i.upcase}}
+
+    f6.path    # => "f.txt"
+    f6.backup  # => "f.txt.20180915.bak"
+    f6.sizes   # => { :old => 40, :new => 40 }
+ 
+The first example (f1) is the basic form of the use of this class.  You create a class instance by the
+constructor, perform a manipulataion(s) to modify the content, and *save* it,
+which means *run* the overwriting operation of the original file.  Until you
+*run*, the original file unchanges, while any modifications are stored either in
+the memory or a temporary file, either of which would be garbage-collected if
+the process is not *run* in the end. A backup file is automatically
+created, unless explicity suppressed, whose filename or suffix is either
+automatically chosen or specified explicitly by the caller. 
+Any parts of the operations are chainable or separatable, as you like.
+
+In this example, the main manipuration of modification is *IO-type*, or
+File.open-type.  You are responsible to manually read the content of the
+existing file and write the updated content.  This is the least memory-heavy
+manipulation and so is most suitable when the original file is huge.
+
+The second example (f2) is just a short hand of it.
+
+The third and fourth examples (f3 and f4) are *String-type*, or IO.read-like.
+You handle the entire content of the file as a single String.  The fourth
+example demonstrates an example of chaining manipulations.
+
+The fifth example (f5) is another *String-type* manipulation.  You manipulate
+the content of the file line by line as a String in the iterator (aka block), as in +IO.each_line+.
+Although technically {FileOverwrite#read} is all you need for the String-type
+manipulation, given you can do any manipulation you like, including
+String#sub and the equivalent one to {FileOverwrite#each_line}, in the block, a
+few more String-type manipulations are defined for convenience (see below).
+
+The sixth example (f6) is *Array-type* manipulation.  You get the entire
+content of the file as an Array, each element of which corresponds to a line in
+the file just as +IO.readlines+. You manipulate it and return an Array, which
+will be then joined and output to the original file to overwrite it when you save.
+
+Any methods with the name ending with a bang sign '!' implies it automatically
++run!+ (or +save!+) the final overwriting process, as soon as the manipulation
+of content modification finishes.
+
 === 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.sub(/abc/, 'xyz').gsub(/(.)ef/){$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: '~')
@@ -99,36 +160,41 @@ Note if the input file is not touched at all, the file is never
 
 == Description
 
+Output is via +FileUtils#fu_output_message+ and in practice messages are output to STDERR.
+
 === 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
+The only IO-type manipulation is
 
-* open (or modify)
+* +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
+you have to either {FileOverwrite#run!}, or {FileOverwrite#reset} and do 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.
 
+The class method {FileOverwrite.open!} (or {FileOverwrite.modify!}) is also available
+to skip the constructor and perform {FileOverwrite.run!} (or +save!+) straightaway.
+
 ==== 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)
+* +read+ (with block; like IO.read)
+* +sub+  (with or without block)
+* +gsub+ (with or without block; nb., as an extension from String#gsub the maximum number of matches can be specified with the optional argument max.)
+* +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).
@@ -155,21 +221,26 @@ 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.
 
+For +read+ (+read!+) and +each_line+ (+each_line!+), the class methods of the same names are is available to skip the constructor.
+
 ==== Array-type manipulation
 
 Similarly, an Array-type manipulation is defined:
 
-* readlines
+* +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.
+The block for the +readlines+ method must return either Array (or its
+equivalent) or String.  If an Array returned, another +readlines+ method can be
+called again (or chained), and in the end the elements are simply concatnated
+when they are written in the updated file.  If a String is returned, any
+subsequent methods of manipulation must be String-type manipulations before
+{FileOverwrite#run!}.
 
 Just like IO-type methods, this can be called with a trailing '!' to
 perform {FileOverwrite#run!} straightaway.
 
+The class method {FileOverwrite.readlines} (and +readlines!+) is available to skip the constructor.
+
 === Other methods
 
 ==== Those related to the state
@@ -196,6 +267,7 @@ Note none of the write-methods are available once {FileOverwrite#completed?}
 {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.
+{FileOverwrite#last_match}:: (read/write) To read (and write if need be) Regexp.last_match after {FileOverwrite#sub} or {FileOverwrite#gsub}.  If a block is given to them, +Regexp.last_match+ in the caller's scope reflects the result.  However, if a block is not given, it does not, and hence this method is the only way to access the last match. See Section "Known bugs" for detail.
 
 == Developer's note
 
@@ -204,12 +276,13 @@ You can view it in {RubyGems/file_overwrite}[https://rubygems.org/gems/file_over
 
 === 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.
+1. The manipulated results are held either in the memory or in a temporary file if IO-based manipulation.
+2. Then when you perform {FileOverwrite#run!}, the following is done in one go:
+   1. the manipulated results are output to a temporary file if not done so, yet (String- or Array-based manipulations),
+   2. the original file is backed up to the specified backup file,
+   3. the temporary file is renamed to the original file,
+   4. 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.
@@ -223,7 +296,12 @@ or simply run <tt>make test</tt>.
 
 == Known bugs
 
-None.
+1. After every execution of {FileOverwrite#sub} and {FileOverwrite#gsub},
+   if a block is given to them, +Regexp.last_match+ (or +$~+) in the caller's scope
+   reflects the result.  However, if a block is not given, it does not, and they
+   retain the values before calling {FileOverwrite#sub} etc in the local scope.
+   The value of MatchData of the last match in such cases is accessible via
+   {FileOverwrite#last_match}.
 
 
 == Copyright
@@ -231,7 +309,3 @@ None.
 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/file_overwrite.gemspec

@@ -4,7 +4,7 @@ require 'rake'
 
 Gem::Specification.new do |s|
   s.name = %q{file_overwrite}
-  s.version = "0.1"
+  s.version = "1.0"
   # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   # s.bindir = 'bin'
   s.authors = ["Masa Sakano"]

data/lib/{file_overwrite/file_overwrite.rb → file_overwrite.rb}

@@ -105,14 +105,26 @@ class FileOverwrite
   #   @return [Encoding]
   attr_accessor :int_enc
 
+  # last_match from {#sub} ({#sub!}) and {#gsub}
+  #
+  # This values is false when uninitialised.
+  # To set this value is for user's convenience only, and
+  # has no effect on processing or any of the methods.
+  # Every time a user runs {#sub} or {#gsub}, this value is reset.
+  #
+  # @!attribute [rw] last_match
+  #   @return [MatchData]
+  attr_accessor :last_match
+
   # @param fname [String] Input filename
   # @param backup: [String, NilClass] File name to which the original file is backed up.  If non-Nil, suffix is ignored.
   # @param suffix: [String, TrueClass, FalseClass, NilClass] Suffix of the backup file.  True for Def, or false if no backup.
   # @param noop: [Boolean] no-operationor dryrun
   # @param verbose: [Boolean, NilClass] the same as $VERBOSE or the command-line option -W, i.e., the verbosity is (true > false > nil).  Forced to be true if $DEBUG
   # @param clobber: [Boolean] raise Exception if false(Def) and fname exists and suffix is non-null.
-  # @param touch: [Boolean] if true (non-Def), when the file content does not change, the timestamp is updated, unless aboslutely no action is taken for the file.
-  def initialize(fname, backup: nil, suffix: true, noop: false, verbose: $VERBOSE, clobber: false, touch: false)
+  # @param touch: [Boolean] if true (non-Def), even when the file content does not change, the timestamp is updated, as long as the file is attempted to be save (#{run!} or #{save})
+  # @param last_match: [MatchData, NilClass, FalseClass] To pass Regexp.last_match in Caller's scope.
+  def initialize(fname, backup: nil, suffix: true, noop: false, verbose: $VERBOSE, clobber: false, touch: false, last_match: false)
     @fname = fname
     @backup = backup
     @suffix = (backup ? true : suffix)
@@ -120,6 +132,7 @@ class FileOverwrite
     @verbose = $DEBUG || verbose
     @clobber = clobber
     @touch   = touch
+    @last_match = last_match
 
     @ext_enc_old = nil
     @ext_enc_new = nil
@@ -144,7 +157,7 @@ class FileOverwrite
   # (so you can tell what the backup filename would be if the suffix was set).
   #
   # @param suffix [String, TrueClass, FalseClass, NilClass] Suffix of the backup file.  True for Def, or false if no backup.
-  # @param backupfile: [String, NilClass] Explicilty specify the backup filename.
+  # @param backupfile: [String, NilClass] Explicilty specify the backup filename, when suffix is nil. (For internal use)
   # @return [String, NilClass]
   def backup(suffix=nil, backupfile: nil)
     return backup_from_suffix(suffix)  if suffix   # non-nil suffix explicitly given
@@ -187,7 +200,7 @@ class FileOverwrite
   def dump
     return @outstr.dup   if @outstr
     return join_outary() if @outary
-    return File.read(@iotmp.path) if @is_edit_finished
+    return File.read(@iotmp.path) if @is_edit_finished && !completed?
     File.read(@fname)
   end
 
@@ -266,6 +279,16 @@ class FileOverwrite
   alias_method :reset?, :fresh? if ! self.method_defined?(:reset?)
 
 
+  # Returns the (duplicate of the) filename to be (or to have been) updated.
+  #
+  # To destructively modify this value would affect nothing in the parent object.
+  #
+  # @return [String]
+  def path
+    @fname.dup
+  end
+
+
   # Returns true if the instance is ready to run (to execute overwriting the file).
   def ready?
     !fresh? && !completed?
@@ -314,7 +337,7 @@ class FileOverwrite
 
   # String#valid_encoding?()
   #
-  # returns nil if the process has been already completed.
+  # @note returns nil if the process has been already completed.
   #
   # @return [Boolean, NilClass]
   def valid_encoding?()
@@ -422,7 +445,9 @@ class FileOverwrite
 
     return self
   end
-  alias_method :run, :run! if ! self.method_defined?(:run)
+  alias_method :run,   :run! if ! self.method_defined?(:run)
+  alias_method :save,  :run! if ! self.method_defined?(:save)
+  alias_method :save!, :run! if ! self.method_defined?(:save!)
 
 
   ########################################################
@@ -459,13 +484,18 @@ class FileOverwrite
     raise ArgumentError, 'Block must be given.' if !block_given?
     normalize_status(:@is_edit_finished)
 
-    kwd_def = {}
-    kwd_def[:ext_enc] = @ext_enc_old if @ext_enc_old
-    kwd_def[:int_enc] = @int_enc     if @int_enc
-    kwd = kwd_def.merge kwd
+    kwd_open = {}
+    kwd_open[:external_encoding] = @ext_enc_old if @ext_enc_old
+    kwd_open[:internal_encoding] = @int_enc     if @int_enc
+    kwd_open[:external_encoding] = (kwd[:ext_enc] || kwd_open[:external_encoding])
+    kwd_open[:internal_encoding] = (kwd[:int_enc] || kwd_open[:internal_encoding])
+    [:mode, :flags, :encoding, :textmode, :binmode, :autoclose].each do |es|
+      # Method list from https://ruby-doc.org/core-2.5.1/IO.html#method-c-new
+      kwd_open[es] = kwd[es] if kwd.key?(es)
+    end
 
     begin
-      File.open(@fname, **kwd) { |ioin|
+      File.open(@fname, **kwd_open) { |ioin|
         @iotmp = tempfile_io
         yield(ioin, @iotmp)
       }
@@ -577,14 +607,15 @@ class FileOverwrite
 
   # Handler to process the entire string of the file (or current content)
   #
-  # If block is not given, just sets the state as String
+  # If block is not given, just sets the processing-state as String.
   #
-  # Else, File.read(infile) is given to the block.
-  # Then, the returned value is held as a String, hence this method can be chained.
+  # Else, IO.read(infile) is given to the block.  No other options, such as length,
+  # as in IO.read are accepted.  Then, the returned value is held as a String,
+  # while self is returned; hence this method can be chained.
   # If the block returns nil (or Boolean), {FileOverwriteError} is raised.
-  # Make sure to return a String (whether an empty string or "true")
+  # Make sure for the block to return a String.
   #
-  # Note this method does not take arguments as in IO.read
+  # Note this method does not take arguments as in IO.read .
   #
   # @param **kwd [Hash] ext_enc, int_enc
   # @return [self]
@@ -599,7 +630,8 @@ class FileOverwrite
     end
       
     @outstr = yield(@outstr) if block_given?
-    raise FileOverwriteError, 'ERROR: The returned value from the block in read() can not be nil or Boolean.' if !@outstr || true == @outstr
+    raise FileOverwriteError, 'ERROR: The returned value from the block in read() has to be String.' if !defined?(@outstr.gsub)
+    warn "WARNING: Empty string returned from a block in #{__method__}" if !@verbose.nil? && @outstr.empty?
     self
   end
 
@@ -614,7 +646,7 @@ class FileOverwrite
   end
 
 
-  # Similar to {String#replace} but the original is not modified
+  # Replaces the file content with the given argument like {String#replace}
   #
   # This method can be chained.
   #
@@ -641,18 +673,22 @@ class FileOverwrite
   # This method can be chained.
   # This method never returns an Enumerator.
   #
-  # WARNING: Do not use the local variables like $1, $2, $', and Regexp.last_match
-  # inside the block supplied.  They would NOT be interpreted in the context of
-  # this method, but that in the caller, which is most likely not to be what you want.
-  #
-  # Instead, this method supplies the MatchData of the match as the second block parameter 
-  # in addition to the matched string as in String#sub.
+  # @note Algorithm
+  #   To realise the local-scope variables like $~, $1, and Regexp.last_match to
+  #   be usable inside the block as in String#sub, it overwrites them when a block
+  #   is given (See the linked article for the phylosophy of how to do it).
+  #   Once a block is read, those variables remain as updated values even after the block
+  #   in the caller's scope, in the same way as String#sub.  However, when a block is not given,
+  #   those variables are *NOT* updated, which is different from String#sub.
+  #   You can retrieve the MatchData by this method via {#last_match} after {#sub}
+  #   is called, if need be.
   #
   # @param *rest [Array<Regexp,String>]
   # @param max: [Integer] the number of the maximum matches.  If it is not 1, {#gsub} is called, instead.  See {#gsub} for detail.
   # @param **kwd [Hash] ext_enc, int_enc
   # @return [self]
   # @yield the same as String#sub
+  # @see https://stackoverflow.com/questions/52359278/how-to-pass-regexp-last-match-to-a-block-in-ruby/52385870#52385870
   def sub(*rest, max: 1, **kwd, &bloc)
     return self if sub_gsub_args_only(*rest, max: max, **kwd)
 
@@ -664,16 +700,20 @@ class FileOverwrite
       return gsub(*rest, max: max, **kwd, &bloc)
     end
 
-    begin
-      m = rest[0].match(@outstr)
-      # Returning nil, Integer etc is accepted in the block of sub/gsub
-      @outstr = m.pre_match + yield(m[0], m).to_s + m.post_match if m
-      # Not to break the specification of sub(), but just to extend.
-      return self
-    rescue NoMethodError => err
-      warn_for_sub_gsub(err)
-      raise
+    @last_match = rest[0].match(@outstr)
+    return self if !@last_match
+
+    # Sets $~ (Regexp.last_match) in the given block.
+    # @see https://stackoverflow.com/questions/52359278/how-to-pass-regexp-last-match-to-a-block-in-ruby/52385870#52385870
+    bloc.binding.tap do |b|
+      b.local_variable_set(:_, $~)
+      b.eval("$~=_")
     end
+
+    # The first (and only) argument for the block is $& .
+    # Returning nil, Integer etc is accepted in the block of sub/gsub
+    @outstr = @last_match.pre_match + yield(@last_match[0]).to_s + @last_match.post_match
+    return self
   end
 
 
@@ -693,26 +733,33 @@ class FileOverwrite
   # This method can be chained.
   # This method never returns an Enumerator.
   #
-  # This method supplies the MatchData of the match as the second block parameter 
-  # in addition to the matched string as in String#sub.
-  #
   # Being different from the standard Srrint#gsub, this method accepts
   # the optional parameter max, which specifies the maximum number of times
   # of the matches and is valid ONLY WHEN a block is given.
   #
+  # @note Algorithm
+  #   See {#sub} for the basic algorithm.
+  #   This method emulates String#gsub as much as possible (duck-typing).
+  #   In String#gsub, the variable $~ after the method has the last matched characters
+  #   as the matched string and the original string before the last matched characters
+  #   as pre_match.  For example,
+  #     'abc'.gsub(/./){$1.upcase}
+  #   returns
+  #     'ABC'
+  #   and leaves
+  #     $& == 'c'
+  #     Regexp.pre_match == 'ab'
+  #   It is the same in this method.
+  #
   # @note Disclaimer
   #   When a block is not given but arguments only (and not expecting Enumerator to return),
   #   this method simply calls String#gsub .  However, when only 1 argument
   #   and a block is given, this method must iterate on its own, which is implemented.
   #   I am not 100% confident if this method works in the completely same way
-  #   as String#gsub in every single situation (except the local variables like $1, $2, etc
-  #   are not on the {#gsub} context; see {#sub}), given the regular expression
-  #   has so many possibilities; I have made the best effort and so far
-  #   I have not found any cases where this method breaks.
+  #   as String#gsub in every single situation, given the regular expression
+  #   has so many possibilities; so far I have not found any cases where this method breaks.
   #   This method is more inefficient and slower than the original String#gsub
-  #   as this method scans/matches the string twice as many times as String#gsub
-  #   (which is unavoidable to implement it properly, I think), and the implementation
-  #   is in pure Ruby.
+  #   as the iteration is implemented in pure Ruby.
   #
   # @param *rest [Array<Regexp,String>]
   # @param max: [Integer] the number of the maximum matches.  0 means no limit (as in String#gsub).  Valid only if a block is given.
@@ -720,6 +767,7 @@ class FileOverwrite
   # @return [self]
   # @yield the same as String#gsub
   # @see #sub
+  # @see https://stackoverflow.com/questions/52359278/how-to-pass-regexp-last-match-to-a-block-in-ruby/52385870#52385870
   def gsub(*rest, max: 0, **kwd, &bloc)
     return sub(*rest, max: 1, **kwd, &bloc) if 1 == max  # Note: Error message would be labelled as 'sub'
     return self if sub_gsub_args_only(*rest, max: max, **kwd)
@@ -730,39 +778,45 @@ class FileOverwrite
 
     max = 5.0/0 if max.to_i <= 0
 
-    scans = @outstr.scan(rest[0])
+    regbase_str = rest[0].to_s
+    regex = Regexp.new( sprintf('(%s)', regbase_str) ) # to guarantee the entire string is picked up by String#scan
+    scans = @outstr.scan(regex)
     return self if scans.empty?  # no matches
 
     scans.map!{|i| [i].flatten}  # Originally, it can be a double array.
-    regbase_str = rest[0].to_s
     prematch = ''
     ret = ''
     imatch = 0  # Number of matches
-    begin
-      scans.each do |ea_sc|
-        str_matched = ea_sc[0]
-        imatch += 1
-        pre_size = prematch.size
-        pos_end_p1 = @outstr.index(str_matched, pre_size) # End+1
-        str_between = @outstr[pre_size...pos_end_p1]
-        prematch << str_between
-        ret      << str_between
-        regex = Regexp.new( sprintf('(?<=\A%s)%s', Regexp.quote(prematch), regbase_str) )
-        #regex = rest[0] if prematch.empty?  # The first run
-        m = regex.match(@outstr)
-        prematch << str_matched
-        # Not to break the specification of sub(), but just to extend.
-        ret << yield(m[0], m).to_s
-        break if imatch >= max
+    scans.each do |ea_sc|
+      str_matched = ea_sc[0]
+      imatch += 1
+      pre_size = prematch.size
+      pos_end_p1 = @outstr.index(str_matched, pre_size) # End+1
+      str_between = @outstr[pre_size...pos_end_p1]
+      prematch << str_between
+      ret      << str_between
+      regex = Regexp.new( sprintf('(?<=\A%s)%s', Regexp.quote(prematch), regbase_str) )
+      #regex = rest[0] if prematch.empty?  # The first run
+      @last_match = regex.match(@outstr)
+      prematch << str_matched
+
+      # Sets $~ (Regexp.last_match) in the given block.
+      # @see https://stackoverflow.com/questions/52359278/how-to-pass-regexp-last-match-to-a-block-in-ruby/52385870#52385870
+      bloc.binding.tap do |b|
+        b.local_variable_set(:_, $~)
+        b.eval("$~=_")
       end
-      ret << Regexp.last_match.post_match  # Guaranteed to be non-nil.
 
-      @outstr = ret
-      return self
-    rescue NoMethodError => err
-      warn_for_sub_gsub(err)
-      raise
+      # The first (and only) argument for the block is $& .
+      # Returning nil, Integer etc is accepted in the block of sub/gsub
+      ret << yield(@last_match[0]).to_s
+
+      break if imatch >= max
     end
+    ret << Regexp.last_match.post_match  # Guaranteed to be non-nil.
+
+    @outstr = ret
+    return self
   end
 
 
@@ -820,6 +874,16 @@ class FileOverwrite
   # Class methods
   ########################################################
 
+  # Class method for {FileOverwrite#initialize}.{#modify!}
+  #
+  # @see #initialize
+  # @see #modify
+  def self.modify!(*rest, **kwd, &bloc)
+    new(*rest, **kwd).modify!(**kwd, &bloc)
+  end
+  singleton_class.send(:alias_method, :open!, :modify!)
+
+
   # Shorthand of {FileOverwrite#initialize}.{#readlines}, taking parameters for both
   #
   # @param fname [String] Input and overwriting filename
@@ -844,6 +908,39 @@ class FileOverwrite
   end
 
 
+  # Class method for {FileOverwrite#initialize}.{#read}
+  #
+  # @see #initialize
+  # @see #read
+  def self.read(*rest, **kwd, &bloc)
+    new(*rest, **kwd).send(__method__, **kwd, &bloc)
+  end
+
+  # Class method for {FileOverwrite#initialize}.{#read!}
+  #
+  # @see #initialize
+  # @see #read!
+  def self.read!(*rest, **kwd, &bloc)
+    new(*rest, **kwd).send(__method__, **kwd, &bloc)
+  end
+
+  # Class method for {FileOverwrite#initialize}.{#each_line}
+  #
+  # @see #initialize
+  # @see #each_line
+  def self.each_line(fname, *rest, **kwd, &bloc)
+    new(fname, **kwd).send(__method__, *rest, **kwd, &bloc)
+  end
+
+  # Class method for {FileOverwrite#initialize}.{#each_line!}
+  #
+  # @see #initialize
+  # @see #each_line!
+  def self.each_line!(fname, *rest, **kwd, &bloc)
+    new(fname, **kwd).send(__method__, *rest, **kwd, &bloc)
+  end
+
+
   ########################################################
   private
   ########################################################
@@ -1018,13 +1115,14 @@ class FileOverwrite
     return if 1 == rest.size
 
     method = caller_locations()[0].label
-    if (max != 1 && 'sub' == method) ||  (max != 0 && 'gsub' == method)
-      msg = sprintf "WARNING: max option (%s) is given and not 1, but ignored in %s().  Give a block to take it into account..", max, method
+    if !@verbose.nil? && ((max != 1 && 'sub' == method) ||  (max != 0 && 'gsub' == method))
+      msg = sprintf "WARNING: max option (%s) of neither 0 nor 1 is given. It is ignored in %s(). Give a block (instead of just arguments) for the max option to be taken into account.", max, method
       warn msg
     end
 
     # Note: When 2 arguments are given, the block is simply ignored in default (in Ruby 2.5).
     @outstr.send(method+'!', *rest) # sub! or gsub! => String|nil
+    @last_match = Regexp.last_match # $~
     @outstr
   end
   private :sub_gsub_args_only

data/test/test_file_overwrite.rb

@@ -5,7 +5,7 @@
 
 # require 'tempfile'
 # require 'fileutils'
-require 'file_overwrite/file_overwrite'
+require 'file_overwrite'
 
 $stdout.sync=true
 $stderr.sync=true
@@ -13,6 +13,11 @@ $stderr.sync=true
 
 #################################################
 # Unit Test
+#
+# Note: $VERBOSE is set true in default in Testing.
+#   Then, the VERBOSE option in FileOverwite.new is
+#   also set TRUE in the tests in default, being different
+#   from the Ruby default environment ($VERBOSE==false).
 #################################################
 
 #if $0 == __FILE__
@@ -33,7 +38,7 @@ $stderr.sync=true
 
       @orig_path  = @tmpioin.path
       @orig_content = "1 line A\n2 line B\n3 line C\n"
-      @orig_mtime = Time.now - 86400  # A day earlier
+      @orig_mtime = Time.now.round - 86400  # A day earlier
 
       @tmpioin.print @orig_content
       reset_mtime
@@ -77,6 +82,7 @@ $stderr.sync=true
       assert_equal @tmpioin.path, m[1]
     end
 
+    # Testing backup file names
     def test_backup
       file1 = create_template_file
       fpath = file1.path
@@ -91,12 +97,16 @@ $stderr.sync=true
       assert_equal fpath+suffix1, f1.backup  # Reverted back
     end
 
-    def test_open  # modify
+    # FileOverwrite#modify (or #open as an alias)
+    def test_open
       file1 = create_template_file
       fpath = file1.path
       f1 = FO.new(fpath)
       s = 'tekito'
 
+      # Testing non-block
+      assert_raises(ArgumentError){ f1.modify }
+
       # Testing open 
       f1.open{|ior, iow|
         # Line 1
@@ -143,10 +153,33 @@ $stderr.sync=true
       assert_nil f1.temporary_filename
     end
 
+
+    # FileOverwrite.#open! (an alias of #modify!)
+    def test_open_classmethod
+      file1 = create_template_file
+      fpath = file1.path
+      s = 'tekito'
+
+      # Testing FileOverwrite.open!
+      f1 = nil
+      assert_output('', /File.+updated/){
+        f1 = FO.open!(fpath){|ior, iow|
+          line = ior.gets
+          ior.gets  line
+          iow.print s+s
+        }
+      }
+      assert_equal fpath, f1.path
+      assert_equal s+s, f1.dump  # Testing dump after completed.
+      assert_equal s+s, File.read(f1.path)
+    end
+
+
+    # Tests of read, read!, replace_with
     def test_read
       file1 = create_template_file
       fpath = file1.path
-      f1 = FO.new(fpath)
+      f1 = FO.new(fpath, verbose: true)
 
       s = 'tekito'
       f1.read{|i| s}
@@ -167,6 +200,20 @@ $stderr.sync=true
       assert_output('', / not opened,/){ f1.run!(verbose: true) }
       assert_equal @orig_content, File.read(fpath)
       assert_in_delta(@orig_mtime, File.mtime(fpath), 1)  # 1 sec allowance
+      
+      # Test of invalid returns from the block
+      f1.reset
+      assert_raises(FileOverwriteError){ f1.read{} }
+      f1.reset
+      assert_raises(FileOverwriteError){ f1.read{nil} }
+      f1.reset
+      assert_raises(FileOverwriteError){ f1.read{5} }
+      f1.reset
+      assert_output('', /Empty string[^\n]*\n.*File .+updated.+Size.* => 0 bytes/im){ f1.read!(){''} }
+      # Warning is issued if an empty string is returned, but it is saved nonetheless.
+      assert_equal 0, f1.sizes[:new]  # The new size is zero.
+
+      assert_raises(FrozenError){ f1.reset }  # Prohibited to reset, once saved.
     end
 
     def test_open_run_noop  # modify
@@ -289,13 +336,30 @@ $stderr.sync=true
       assert_equal @orig_content+s, File.read(fpath)
       assert_nil f1.sizes
     end
-      
+
+    # FileOverwrite.#read!
+    def test_read_classmethod
+      file1 = create_template_file
+      fpath = file1.path
+      s = 'tekito'
+
+      # Testing FileOverwrite.read!
+      f1 = nil
+      assert_output('', /File.+updated/){
+        f1 = FO.read!(fpath){|i| s+s}
+      }
+      assert_equal fpath, f1.path
+      assert_equal s+s, f1.dump  # Testing dump after completed.
+      assert_equal s+s, File.read(f1.path)
+    end
+
     def test_sub
       file1 = create_template_file
       fpath = file1.path
       f1 = FO.new(fpath, suffix: nil, verbose: true)
 
       f1.sub(/line/, 'xyz')
+      assert_equal 'line', f1.last_match[0]
       assert_match(/xyz/, f1.dump.split(/\n/)[0])
       refute_match(/xyz/, f1.dump.split(/\n/)[1])
       f1.reset
@@ -308,6 +372,9 @@ $stderr.sync=true
       refute_match(/xyz/, f1.dump.split(/\n/)[0])
       
       f1.sub(/(li)(n)/, '\1' + 'k')
+      assert_equal 'lin',  f1.last_match[0]
+      assert_equal 'li',   f1.last_match[1]
+      assert_equal 'n',    f1.last_match[2]
       assert_match(/like/, f1.dump.split(/\n/)[0])
       refute_match(/like/, f1.dump.split(/\n/)[1])
       f1.reset
@@ -315,16 +382,17 @@ $stderr.sync=true
 
       # Failed-match case
       f1.sub(/naiyo(li)(n)/, '\1' + 'k')
+      assert_nil  f1.last_match
       assert_match(/line/, f1.dump.split(/\n/)[0])
       assert_equal @orig_content, f1.instance_eval{@outstr}
       f1.reset
 
-      ### The following does NOT work!
-      # f1.sub(/(li)(ne)/){printf "and=(%s)(%s)", $&, $1; 'LIne'} # $1.upcase + $2
-
-      ### MatchData extension in this method!
-      f1.sub(/(li)(n)/){|_,m| m[1].upcase+m[2]} # $1.upcase + $2
-
+      # With a block
+      f1.sub(/(li)(n)/){$1.upcase+$2}
+      # f1.sub(/(li)(n)/){|_,m| m[1].upcase+m[2]} # $1.upcase + $2  # Old version
+      assert_equal 'lin',  f1.last_match[0]
+      assert_equal 'li',   f1.last_match[1]
+      assert_equal 'n',    f1.last_match[2]
       assert_match(/LIne/, f1.dump.split(/\n/)[0], "DEBUG: "+f1.dump)
       refute_match(/LIne/, f1.dump.split(/\n/)[1])
       f1.sub(/I/){nil}   # nil.to_s (as in String#sub)
@@ -335,8 +403,19 @@ $stderr.sync=true
       refute_match(/LI?ne/, f1.dump.split(/\n/)[0])
       assert_nil  f1.instance_eval{@outstr}
 
+      # With a block with an argument
+      f1.sub(/(li)(n)/){|ms| ms.upcase} # ms == $&
+      assert_equal 'lin',  f1.last_match[0]
+      assert_equal 'li',   f1.last_match[1]
+      assert_equal 'n',    f1.last_match[2]
+      assert_match(/LINe/, f1.dump.split(/\n/)[0], "DEBUG: "+f1.dump)
+      f1.reset
+      refute_match(/LI?ne/, f1.dump.split(/\n/)[0])
+      assert_nil  f1.instance_eval{@outstr}
+
       # Failed-match case
       f1.sub(/naiyo(li)(n)/){|_,m| m[1].upcase+m[2]} # $1.upcase + $2
+      assert_nil  f1.last_match
       assert_match(/line/, f1.dump.split(/\n/)[0], "DEBUG: "+f1.dump)
       f1.reset
     end
@@ -347,7 +426,10 @@ $stderr.sync=true
       fpath = file1.path
       f1 = FO.new(fpath, suffix: nil, verbose: true)
 
+      f1.gsub(/naiyo/, 'xyz')  # Failed match
+      assert_nil  f1.last_match
       assert_output('', ''){ f1.gsub(/line/, 'xyz') }
+      assert_equal 'line', f1.last_match[0]
       assert_match(/xyz/, f1.dump.split(/\n/)[0])
       assert_match(/xyz/, f1.dump.split(/\n/)[1])
       assert_match(/xyz/, f1.dump.split(/\n/)[2])
@@ -355,6 +437,7 @@ $stderr.sync=true
       refute_match(/xyz/, f1.dump.split(/\n/)[0])
 
       assert_output('', ''){ f1.gsub(/line/, 'xyz', max: 1) }
+      assert_equal 'line', f1.last_match[0]
       assert_match(/xyz/, f1.dump.split(/\n/)[0])
       refute_match(/xyz/, f1.dump.split(/\n/)[1])
       f1.reset
@@ -364,6 +447,7 @@ $stderr.sync=true
       assert_output('', /WARNING\b.+\bmax/i){ f1.gsub(/line/, 'xyz', max: 2) }
       f1.reset
 
+      # With a block
       assert_output(nil){ f1.gsub(/line/){ 'xyz' } }
       assert_match(/xyz/, f1.dump.split(/\n/)[0])
       assert_match(/xyz/, f1.dump.split(/\n/)[1])
@@ -371,12 +455,44 @@ $stderr.sync=true
       f1.reset
       refute_match(/xyz/, f1.dump.split(/\n/)[0])
 
+      # With a block with an argument and $1 etc
+      mat=nil
+      f1.gsub(/lin(e)/){ |ms| ms+$1.upcase } # lineE
+      mat=$~
+      assert_equal mat, f1.last_match
+      assert_match(/lineE/, f1.dump.split(/\n/)[0])
+      assert_match(/lineE/, f1.dump.split(/\n/)[1])
+      assert_match(/lineE/, f1.dump.split(/\n/)[2])
+      assert_equal 'e', mat[1]
+      assert_equal 2, mat.pre_match.scan(/\bline\b/).size  # "1 line A\n2 line B\n3 "
+      assert_match(/[^\n]+\n$/m, mat.post_match)           # " C\n"
+      f1.reset
+      refute_match(/lineE/, f1.dump.split(/\n/)[0])
+
+      # With a block with max option
       assert_output('', ''){ f1.gsub(/line/, max: 2){ 'xyz' } }
+      assert_equal 'line', f1.last_match[0]
       assert_match(/xyz/, f1.dump.split(/\n/)[0])
       assert_match(/xyz/, f1.dump.split(/\n/)[1])
       refute_match(/xyz/, f1.dump.split(/\n/)[2])
       f1.reset
       refute_match(/xyz/, f1.dump.split(/\n/)[0])
+
+      # With a block with an argument and $1 etc
+      # assert_output(nil){ f1.gsub(/lin(e)/){ |ms| ms+$1.upcase } } # lineE
+      mat=nil
+      f1.gsub(/lin(e)/, max: 2){ |ms| ms+$1.upcase } # lineE
+      mat=$~
+      assert_equal mat, f1.last_match
+      assert_match(/lineE/, f1.dump.split(/\n/)[0])
+      assert_match(/lineE/, f1.dump.split(/\n/)[1])
+      refute_match(/lineE/, f1.dump.split(/\n/)[2])
+      assert_equal 'e', mat[1]
+      assert_equal 1, mat.pre_match.scan(/\bline\b/).size  # "1 line A\n2 "
+      assert_equal " B\n3 line C\n",     mat.post_match
+      assert_match(/[^\n]+\n[^\n]+\n$/m, mat.post_match)   # " B\n3 line C\n"
+      f1.reset
+      refute_match(/lineE/, f1.dump.split(/\n/)[0])
     end
 
 
@@ -437,6 +553,25 @@ $stderr.sync=true
     end
 
 
+    # FileOverwrite.#each_line
+    def test_each_line_classmethod
+      file1 = create_template_file
+      fpath = file1.path
+      s = 'tekito'
+      nlines = File.read(fpath).count("\n")  # == 3
+
+      # Testing FileOverwrite.each_line
+      f1 = nil
+      f1 = FO.each_line(fpath){|i| s}
+      assert_equal fpath, f1.path
+      assert_equal s*nlines, f1.dump  # Testing dump after completed.
+      refute_equal s*nlines, File.read(f1.path)
+      assert_output('', /File.+updated/){
+        f1.save
+      }
+      assert_equal s*nlines, File.read(f1.path)
+    end
+
     def test_readlines
       file1 = create_template_file
       fpath = file1.path
@@ -462,6 +597,24 @@ $stderr.sync=true
       assert_equal s.size,             sizes[:new]
     end
 
+    def test_touch
+      file1 = create_template_file
+      fpath = file1.path
+      f1 = FO.new(fpath, suffix: nil, verbose: true, touch: true)
+
+      assert_equal fpath, f1.path
+      assert_equal @orig_mtime.to_s, File.mtime(f1.path).to_s
+      f1.path.replace('naiyo')
+      assert_equal fpath, f1.path
+      Time.stub :now, Time.now do
+        assert_output('', /^(\s*warning:?\s*)?No change\b.+timestamp is updated/i){ f1.read!{|i| i} }
+        assert_equal fpath, f1.path
+
+        refute_equal @orig_mtime.to_s, File.mtime(f1.path).to_s # b/c touched
+        assert_equal Time.now.to_s,    File.mtime(f1.path).to_s # nb., Time#round would add a second.
+      end
+    end
+
   end	# class TestUnitFileOverwrite < MiniTest::Test
 
 #end	# if $0 == __FILE__

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: file_overwrite
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '1.0'
 platform: ruby
 authors:
 - Masa Sakano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-19 00:00:00.000000000 Z
+date: 2018-10-13 00:00:00.000000000 Z
 dependencies: []
 description: 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
@@ -27,7 +27,7 @@ files:
 - README.en.rdoc
 - Rakefile
 - file_overwrite.gemspec
-- lib/file_overwrite/file_overwrite.rb
+- lib/file_overwrite.rb
 - lib/file_overwrite/file_overwrite_error.rb
 - test/test_file_overwrite.rb
 homepage: https://www.wisebabel.com