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.16 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 tie
d 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**. Use at your own risk.
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 thecreate
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 theclose ARGV
has the effect of callingfinish
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 theclose ARGV
. The equivalent to what this module does would beif (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/.