Name

File::Replace::Inplace - Emulation of Perl's -i switch via File::Replace

Synopsis

 use File::Replace qw/inplace/;
 {
     my $inpl = inplace( backup=>'.bak' );
     local @ARGV = ("file1.txt", "file2.txt");
     while (<>) {
         chomp;
         s/[aeiou]/_/gi;
         print $_, "\n";
     }
 }

Same thing, but from the command line:

 perl -MFile::Replace=-i.bak -ple 's/[aeiou]/_/gi' file1.txt file2.txt

Description

This module provides a mechanism to replace Perl's in-place file editing (see the -i switch in perlrun) with in-place editing via File::Replace. It does so by using Tie::Handle::Argv to preserve as much of the behavior of Perl's magic <> operator and -i switch as possible.

When you create an object of the class File::Replace::Inplace, either by File::Replace::Inplace->new() or via inplace() from File::Replace (the two are identical), it acts as a scope guard: ARGV is tied when the object is created, and ARGV is untied when the object goes out of scope (except if you tie ARGV to another class in the meantime).

You can pass the aforementioned constructors the same arguments as File::Replace, with the exception of in_fh, and in addition to the options supported by the Tie::Handle::Argv constructor, files and filename.

Once ARGV is tied, you can use <> as you normally would, and the files in @ARGV will be edited in-place using File::Replace, for an example see the "Synopsis".

See also "inplace" in File::Replace for a description of the -i argument to File::Replace, which can be used for oneliners as shown in the "Synopsis".

This documentation describes version 0.18 of this module.

Experimental Status of this Module

Warning: As of 0.16, this module was split out of the distribution of File::Replace because a tied ARGV has proven to be very difficult to reliably test due to small changes in Perl's behavior across various Perl versions. For this reason, unfortunately, it may or may not work reliably on your system, independently of whether the test suite passes or not, and so I have had to declare this module experimental. Future breakages of this module may not be fixed/fixable.

Differences to Perl's -i

• Problems like not being able to open a file would normally only cause a warning when using Perl's -i option, in this module it depends on the setting of the create option, see "create" in File::Replace.

• See the documentation of the backup option at "backup" in File::Replace for differences to Perl's -i.

• If you use the close ARGV if eof; idiom to reset $., as documented in "eof" in perlfunc, then be aware that the close ARGV has the effect of calling finish on the underlying File::Replace object, which has the effect of closing the current output handle as well. (With Perl's -i switch, it is possible to continue writing to the output file even after the close ARGV. The equivalent to what this module does would be if (eof) { close ARGV; close select; }.)

Warning About Perls Older Than v5.16 and Windows

Please see "Warning About Perls Older Than v5.16 and Windows" in Tie::Handle::Argv. In addition, there is a known issue that eof may return unexpected values on Perls older than 5.12 when reading from STDIN via a tied ARGV.

It is strongly recommended to use this module on Perl 5.16 and up. On older versions, be aware of the aforementioned issues.

In addition, a significant portion of this module's tests must be skipped on Windows on Perl versions older than 5.28. I would therefore strongly suggest using the most recent version of Perl for Windows.

Author, Copyright, and License

Copyright (c) 2018-2023 Hauke Daempfling (haukex@zero-g.net) at the Leibniz Institute of Freshwater Ecology and Inland Fisheries (IGB), Berlin, Germany, http://www.igb-berlin.de/

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.