# File lib/file_overwrite.rb, line 930
def self.each_line(fname, *rest, **kwd, &bloc)
  new(fname, **kwd).send(__method__, *rest, **kwd, &bloc)
end

# File lib/file_overwrite.rb, line 938
def self.each_line!(fname, *rest, **kwd, &bloc)
  new(fname, **kwd).send(__method__, *rest, **kwd, &bloc)
end

# File lib/file_overwrite.rb, line 880
def self.modify!(*rest, **kwd, &bloc)
  new(*rest, **kwd).modify!(**kwd, &bloc)
end

# File lib/file_overwrite.rb, line 126
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)
  @noop  = noop
  @verbose = $DEBUG || verbose
  @clobber = clobber
  @touch   = touch
  @last_match = last_match

  @ext_enc_old = nil
  @ext_enc_new = nil
  @int_enc     = nil

  @outstr = nil  # String to write.  This is nil if the temporary file was already created with modify().
  @outary = nil  # or Array to write
  @iotmp  = nil  # Temporary file IO to replace the original
  @is_edit_finished = false  # true if the file modification is finished.
  @is_completed = false      # true after all the process has been completed.
  @sizes = nil
end

# File lib/file_overwrite.rb, line 914
def self.read(*rest, **kwd, &bloc)
  new(*rest, **kwd).send(__method__, **kwd, &bloc)
end

# File lib/file_overwrite.rb, line 922
def self.read!(*rest, **kwd, &bloc)
  new(*rest, **kwd).send(__method__, **kwd, &bloc)
end

# File lib/file_overwrite.rb, line 894
def self.readlines(fname, *rest, **kwd, &bloc)
  new(fname, *rest, **kwd).send(__method__, *rest, **kwd, &bloc)
end

# File lib/file_overwrite.rb, line 905
def self.readlines!(*rest, **kwd, &bloc)
  readlines(*rest, **kwd, &bloc).run!(**kwd)
end

# File lib/file_overwrite.rb, line 161
def backup(suffix=nil, backupfile: nil)
  return backup_from_suffix(suffix)  if suffix   # non-nil suffix explicitly given
  return backupfile                  if backupfile
  return @backup                     if @backup
  return backup_from_suffix(@suffix) if @suffix
  nil
end

# File lib/file_overwrite.rb, line 176
def chainable?
  return nil if fresh?
  return false if completed?
  return !@is_edit_finished   # ie., (@outary || @outstr) b/c one of the three must be non-false after the 2 clauses above.
end

# File lib/file_overwrite.rb, line 184
def completed?
  @is_completed
end

# File lib/file_overwrite.rb, line 199
def dump
  return @outstr.dup   if @outstr
  return join_outary() if @outary
  return File.read(@iotmp.path) if @is_edit_finished && !completed?
  File.read(@fname)
end

# File lib/file_overwrite.rb, line 573
def each_line(*rest, **kwd, &bloc)
  raise ArgumentError, 'Block must be given.' if !block_given?
  read(**kwd){ |outstr|
    outstr.each_line(*rest).map{|i| yield(i).to_s}.join('')
  }
end

# File lib/file_overwrite.rb, line 586
def each_line!(*rest, **kwd, &bloc)
  send(__method__.to_s.chop, *rest, **kwd, &bloc).run!(**kwd)
end

# File lib/file_overwrite.rb, line 210
def empty?
  dump.empty?
end

# File lib/file_overwrite.rb, line 232
def encode(*rest, **kwd)
  enc = (rest[0] || Encoding.default_internal)
  @int_enc = enc  # raises an Exception if called after "completed"
  return enc if @is_edit_finished || fresh?
  return @outstr.encode(*rest, **kwd) if @outstr
  if @outary
    @outary.map!{|i| i.encode(*rest, **kwd)}
    return enc
  end
  raise 'Should not happen.  Contact the code developer.'
end

# File lib/file_overwrite.rb, line 250
def end_with?(*rest)
  dump.end_with?(*rest)
end

# File lib/file_overwrite.rb, line 262
def force_encoding(enc)
  @ext_enc_old = enc  # raises an Exception if called after "completed"
  return enc if @is_edit_finished || fresh?
  return @outstr.force_encoding(enc) if @outstr
  if @outary
    @outary.map!{|i| i.force_encoding(enc)}
    return enc
  end
  raise 'Should not happen.  Contact the code developer.'
end

# File lib/file_overwrite.rb, line 275
def fresh?
  !state
end

# File lib/file_overwrite.rb, line 770
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)

  if !block_given?
    raise ArgumentError, full_method_name+' does not support the format to return an enumerator.'
  end

  max = 5.0/0 if max.to_i <= 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.
  prematch = ''
  ret = ''
  imatch = 0  # Number of matches
  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

    # 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

# File lib/file_overwrite.rb, line 826
def gsub!(*rest, **kwd, &bloc)
  gsub(*rest, &bloc).run!(**kwd)
end

# File lib/file_overwrite.rb, line 482
def modify(**kwd)
  raise ArgumentError, 'Block must be given.' if !block_given?
  normalize_status(:@is_edit_finished)

  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_open) { |ioin|
      @iotmp = tempfile_io
      yield(ioin, @iotmp)
    }
  rescue FileOverwriteError => err
    warn err.message if @verbose
    reset
  end
  self
end

# File lib/file_overwrite.rb, line 517
def modify!(**kwd, &bloc)
  modify(&bloc).run!(**kwd)
end

# File lib/file_overwrite.rb, line 286
def path
  @fname.dup
end

# File lib/file_overwrite.rb, line 624
def read(**kwd, &bloc)
  if :first == normalize_status(:@outstr)
    adjust_input_encoding(**kwd){ |f|  # @fname
      @outstr = File.read f
    }
  end
    
  @outstr = yield(@outstr) if block_given?
  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

# File lib/file_overwrite.rb, line 643
def read!(**kwd, &bloc)
  read(**kwd, &bloc).run!(**kwd)
end

# File lib/file_overwrite.rb, line 541
def readlines(*rest, **kwd, &bloc)
  raise ArgumentError, 'Block must be given.' if !block_given?

  if :first == normalize_status(:@outary)
    adjust_input_encoding(**kwd){ |f|  # @fname
      @outary = IO.readlines(f, *rest)
    }
  end

  @outary = yield(@outary)
  self
end

# File lib/file_overwrite.rb, line 292
def ready?
  !fresh? && !completed?
end

# File lib/file_overwrite.rb, line 654
def replace_with(str)
  read
  @outstr = str.to_s
  self
end

# File lib/file_overwrite.rb, line 665
def replace_with!(str, **kwd)
  replace_with(str).run!(**kwd)
end

# File lib/file_overwrite.rb, line 301
def reset
  @outstr = nil
  @outary = nil
  @is_edit_finished = nil
  close_iotmp  # @iotmp=nil; immediate deletion of the temporary file
  warn "The modification process is reset." if $DEBUG
  nil
end

# File lib/file_overwrite.rb, line 405
def run!(backup: @backup, suffix: @suffix, noop: @noop, verbose: @verbose, clobber: @clobber, touch: @touch, setsize: true, **kwd)
  raise FileOverwriteError, 'The process has been already completed.' if completed?

  bkupname = get_bkupname(backup, suffix, noop, verbose, clobber)
  sizes = write_new(verbose, setsize)
  return nil if !sizes

  return self if run_identical?(noop, verbose, touch)

  if bkupname
    msg4bkup = ", Backup: " + bkupname if verbose
  else
    io2del = tempfile_io
    io2delname = io2del.path
  end

  fname_to = (bkupname || io2delname)
  mv(  @fname,    fname_to, noop: noop, verbose: $DEBUG) # defined in FileUtils
  begin
    mv(@iotmp.path, @fname, noop: noop, verbose: $DEBUG) # defined in FileUtils
  rescue
    msg = sprintf("Process halted! File system error in renaming the temporary file %s back to the original %s", @iotmp.path, @fname) 
    warn msg
    raise
  end

  # @iotmp.close(true)  # to immediate delete the temporary file
                        # If commented out, GC looks after it.

  File.unlink io2delname if io2delname && !noop
  # if noop, GC will delete it.

  if verbose
    msg = sprintf("%sFile %s updated (Size: %d => %d bytes%s)\n", prefix(noop), @fname, sizes[:old], sizes[:new], msg4bkup)
    fu_output_message msg
  end

  @is_completed = true
  self.freeze

  return self
end

# File lib/file_overwrite.rb, line 329
def state
  return true     if completed?
  return IO            if @is_edit_finished
  return @outstr.class if @outstr
  return @outary.class if @outary
  nil
end

# File lib/file_overwrite.rb, line 691
def sub(*rest, max: 1, **kwd, &bloc)
  return self if sub_gsub_args_only(*rest, max: max, **kwd)

  if !block_given?
    raise ArgumentError, full_method_name+' does not support the format to return an enumerator.'
  end

  if max.to_i != 1
    return gsub(*rest, max: max, **kwd, &bloc)
  end

  @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

# File lib/file_overwrite.rb, line 725
def sub!(*rest, **kwd, &bloc)
  sub(*rest, &bloc).run!(**kwd)
end

# File lib/file_overwrite.rb, line 316
def temporary_filename
  @iotmp ? @iotmp.path : nil
end

# File lib/file_overwrite.rb, line 838
def tr(*rest, **kwd)
  read(**kwd){ |outstr|
    outstr.tr!(*rest) || outstr
  }
end

# File lib/file_overwrite.rb, line 847
def tr!(*rest, **kwd)
  tr(*rest, **kwd).run!(**kwd)
end

# File lib/file_overwrite.rb, line 858
def tr_s(*rest, **kwd)
  read(**kwd){ |outstr|
    outstr.tr_s!(*rest) || outstr
  }
end

# File lib/file_overwrite.rb, line 867
def tr_s!(*rest, **kwd)
  tr_s(*rest, **kwd).run!(**kwd)
end

# File lib/file_overwrite.rb, line 342
def valid_encoding?()
  return nil if completed?
  dump.valid_encoding?
end

# File lib/file_overwrite.rb, line 952
def adjust_input_encoding(**kwd, &bloc)
  raise ArgumentError, 'Block must be given.' if !block_given?
  obj = yield(@fname)

  kwd_enc = {}
  kwd_enc[:ext_enc] = @ext_enc_old  if @ext_enc_old
  kwd_enc[:ext_enc] = kwd[:ext_enc] if kwd[:ext_enc]
  kwd_enc[:int_enc] = @int_enc      if @int_enc
  kwd_enc[:int_enc] = kwd[:int_enc] if kwd[:int_enc]
  if kwd_enc[:ext_enc]
    force_encoding kwd_enc[:ext_enc]
  end
  if kwd_enc[:int_enc]
    if defined? obj.map!
      obj.map!{|i| i.encode(kwd_enc[:int_enc])}
    elsif defined? obj.encode
      obj.encode kwd_enc[:int_enc]
    else
      raise 'Should not happen. Contact the code developper.'
    end
  end
end

# File lib/file_overwrite.rb, line 981
def backup_from_suffix(suffix)
  raise 'Should not happen. Contact the code developper.' if !suffix

  @fname + ((suffix == true) ? Time.now.strftime(".%Y%m%d%H%M%S.bak") : suffix)
end

# File lib/file_overwrite.rb, line 992
def close_iotmp
  return if !@iotmp
  fn = @iotmp.path
  @iotmp.close(true) if @iotmp # immediate deletion of the temporary file
  @iotmp = nil
  fn
end

# File lib/file_overwrite.rb, line 1005
def full_method_name(nested_level=0)
  # Note: caller_locations() is equivalent to caller_locations(1).
  #       caller_locations(0) from this method would also contain the information of
  #       this method full_method_name() itself, which is totally irrelevant.
  sprintf("%s#%s", self.class.to_s, caller_locations()[nested_level].label)
end

# File lib/file_overwrite.rb, line 1022
def get_bkupname(backup_l, suffix, noop, verbose, clobber)
  bkupname = backup(suffix, backupfile: backup_l)
  return nil if !bkupname

  if File.exist?(bkupname)
    raise "File(#{@fname}) exists." if !clobber
    fu_output_message sprintf("%Backup File %s is overwritten.", prefix(noop), bkupname) if verbose
  end

  bkupname
end

# File lib/file_overwrite.rb, line 1039
def join_outary(ary=@outary)
  ary.join ''
end

# File lib/file_overwrite.rb, line 1052
def normalize_status(inst_var)
  errmsg = "WARNING: The file (#{@fname}) is reread from the beginning."

  case inst_var
  when :@is_edit_finished, '@is_edit_finished'
    warn errmsg if @outstr || @outary
    reset
    @is_edit_finished = true
    return :first

  when :@outary, '@outary'
    warn errmsg if @outstr || @is_edit_finished
    @is_edit_finished = false
    close_iotmp  # @iotmp=nil; immediate deletion of the temporary file
    @outstr = nil
    return :continuation if @outary 
    @outary ||= []
    return :first

  when :@outstr, '@outstr'
    # For String-type processing, it is allowed if the previous processing
    # is not String-type but Array-type.
    warn errmsg if @is_edit_finished || (@outstr && @outary)
    @is_edit_finished = false
    close_iotmp  # @iotmp=nil; immediate deletion of the temporary file
    if @outary
      @outstr = join_outary()
      @outary = nil
      return :continuation
    else
      return :continuation if @outstr
      @outstr ||= ''
      return :first
    end
  else
    raise
  end
end

# File lib/file_overwrite.rb, line 1097
def prefix(noop=@noop)
  (noop ? '[Dryrun]' : '')
end

# File lib/file_overwrite.rb, line 358
def run_identical?(noop, verbose, touch)
  if !identical?(@iotmp.path, @fname) # defined in FileUtils
    return false
  end

  @iotmp.close(true)  # immediate deletion of the temporary file

  msg = sprintf("%sNo change in (%s).", prefix(noop), @fname)
  if touch
    touch(@fname, noop: noop)          # defined in FileUtils
    msg.chop!  # chop a full stop.
    msg << " but timestamp is updated to " << File.mtime(@fname).to_s << '.'
  end
  fu_output_message msg if verbose

  @is_completed = true
  self.freeze
  true
end

# File lib/file_overwrite.rb, line 1112
def sub_gsub_args_only(*rest, max: 1, **kwd)
  read(**kwd) 
  return if 1 == rest.size

  method = caller_locations()[0].label
  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

# File lib/file_overwrite.rb, line 1133
def tempfile_io(**kwd)
  kwd_def = {}
  kwd_def[:ext_enc] = @ext_enc_new if @ext_enc_new
  kwd_def[:int_enc] = @int_enc     if @int_enc
  kwd = kwd_def.merge kwd

  iot = Tempfile.open(File.basename(@fname) + '.' + self.class.to_s, File.dirname(@fname), **kwd)
  iot.sync=true    # Essential!
  iot
end

# File lib/file_overwrite.rb, line 1149
def warn_for_sub_gsub(err)
  return if !err.message.include?('for nil:NilClass')  # and raise-d
  warn 'WARNING: The variables $1, $2, etc (and $& and Regexp.last_match) are NOT passed to the block in '+full_method_name(1)+' (if that is the cause of this Exception). Use the second block parameter instead, which is the MatchData.'
  nil
end

# File lib/file_overwrite.rb, line 1168
def write_new(verbose, setsize=true)
  if @outstr || @outary
    @iotmp.close(true) if @iotmp  # should be redundant, but to play safe
    @iotmp = tempfile_io
    @iotmp.print (@outstr || join_outary())
    @outstr = nil
    @outary = nil
  elsif !@is_edit_finished
    warn "Input file (#{@fname}) is not opened, and hence is not modified." if !verbose.nil?
    return
  end

  return Hash.new if !verbose && !setsize

  @sizes = {
    :old => File.size(@fname),
    :new => File.size(@iotmp.path),
  }
  if @sizes[:new] == 0
    warn "The revised file (#{@fname}) is empty." if !verbose.nil?
  end
  @sizes
end