Path::Class::File(3) | User Contributed Perl Documentation | Path::Class::File(3) |
Path::Class::File - Objects representing files
version 0.37
use Path::Class; # Exports file() by default my $file = file('foo', 'bar.txt'); # Path::Class::File object my $file = Path::Class::File->new('foo', 'bar.txt'); # Same thing # Stringifies to 'foo/bar.txt' on Unix, 'foo\bar.txt' on Windows, etc. print "file: $file\n"; if ($file->is_absolute) { ... } if ($file->is_relative) { ... } my $v = $file->volume; # Could be 'C:' on Windows, empty string # on Unix, 'Macintosh HD:' on Mac OS $file->cleanup; # Perform logical cleanup of pathname $file->resolve; # Perform physical cleanup of pathname my $dir = $file->dir; # A Path::Class::Dir object my $abs = $file->absolute; # Transform to absolute path my $rel = $file->relative; # Transform to relative path
The "Path::Class::File" class contains functionality for manipulating file names in a cross-platform way.
my $file = file( 'foo', 'bar', 'baz.txt' );
or platform-native syntax:
my $file = file( 'foo/bar/baz.txt' );
or a mixture of the two:
my $file = file( 'foo/bar', 'baz.txt' );
All three of the above examples create relative paths. To create an absolute path, either use the platform native syntax for doing so:
my $file = file( '/var/tmp/foo.txt' );
or use an empty string as the first argument:
my $file = file( '', 'var', 'tmp', 'foo.txt' );
If the second form seems awkward, that's somewhat intentional - paths like "/var/tmp" or "\Windows" aren't cross-platform concepts in the first place, so they probably shouldn't appear in your code if you're trying to be cross-platform. The first form is perfectly fine, because paths like this may come from config files, user input, or whatever.
$string = $file->stringify; $string = "$file";
Note: unlike "$dir->components", this method currently does not accept any arguments to select which elements of the list will be returned. It may do so in the future. Currently it throws an exception if such arguments are present.
my $file = file('/foo//baz/./foo.txt')->cleanup; # $file now represents '/foo/baz/foo.txt';
my $file = file('/foo/baz/../foo.txt')->resolve; # $file now represents '/foo/foo.txt', assuming no symlinks
This actually consults the filesystem to verify the validity of the path.
Any generated objects (subdirectories, files, parents, etc.) will also retain this type.
The arguments in @args are the same as they would be specified in "new()".
$fh = $file->open('r') or croak "Can't read $file: $!";
$fh = $file->open('w') or croak "Can't write to $file: $!";
$fh = $file->open('a') or croak "Can't append to $file: $!";
If you want "chomp()" run on each line of the file, pass a true value for the "chomp" or "chomped" parameters:
my @lines = $file->slurp(chomp => 1);
You may also use the "iomode" parameter to pass in an IO mode to use when opening the file, usually IO layers (though anything accepted by the MODE argument of "open()" is accepted here). Just make sure it's a reading mode.
my @lines = $file->slurp(iomode => ':crlf'); my $lines = $file->slurp(iomode => '<:encoding(UTF-8)');
The default "iomode" is "r".
Lines can also be automatically split, mimicking the perl command-line option "-a" by using the "split" parameter. If this parameter is used, each line will be returned as an array ref.
my @lines = $file->slurp( chomp => 1, split => qr/\s*,\s*/ );
The "split" parameter can only be used in a list context.
The content to be written can be either an array ref or a plain scalar. If the content is an array ref then each entry in the array will be written to the file.
You may use the "iomode" parameter to pass in an IO mode to use when opening the file, just like "slurp" supports.
$file->spew(iomode => '>:raw', $content);
The default "iomode" is "w".
Can also take an "iomode" parameter like "spew". Again, the default "iomode" is "w".
"remove()" is better than simply calling Perl's "unlink()" function, because on some platforms (notably VMS) you actually may need to call "unlink()" several times before all versions of the file are gone - the "remove()" method handles this process for you.
Generally overridden whenever this class is subclassed.
It returns $file is successful, "undef" otherwise.
Ken Williams, kwilliams@cpan.org
Path::Class, Path::Class::Dir, File::Spec
2024-04-13 | perl v5.34.0 |