File::stat::Extra - An extension of the File::stat module, provides additional methods.
version 0.002
use File::stat::Extra; $st = lstat($file) or die "No $file: $!"; if ($st->isLink) { print "$file is a symbolic link"; } if (-x $st) { print "$file is executable"; } use Fcntl 'S_IRUSR'; if ( $st->cando(S_IRUSR, 1) ) { print "My effective uid can read $file"; } if ($st == stat($file)) { printf "%s and $file are the same", $st->file; }
This module's default exports override the core stat() and lstat() functions, replacing them with versions that return File::stat::Extra objects when called in scalar context. In list context the same 13 item list is returned as with the original stat and lstat functions.
File::stat::Extra
stat
lstat
File::stat::Extra is an extension of the File::stat module.
Returns non-object result in list context.
You can now pass in bare file handles to stat and lstat under use strict.
use strict
File tests -t -T, and -B have been implemented too.
-t
-T
-B
Convenience functions filetype and permissions for direct access to filetype and permission parts of the mode field.
filetype
permissions
Named access to common file tests (isRegular / isFile, isDir, isLink, isBlock, isChar, isFIFO / isPipe, isSocket).
isRegular
isFile
isDir
isLink
isBlock
isChar
isFIFO
isPipe
isSocket
Access to the name of the file / file handle used for the stat (file, abs_file / target).
file
abs_file
target
When called in list context, these functions behave as the original stat and lstat functions, returning the 13 element stat list. When called in scalar context, a File::stat::Extra object is returned with the methods as outlined below.
These methods provide named acced to the same fields in the original stat result. Just like the original File::stat.
Interprets the mode, uid and gid fields, and returns whether or not the current process would be allowed the specified access.
mode
uid
gid
ACCESS is one of S_IRUSR, S_IWUSR or S_IXUSR from the Fcntl module, and EFFECTIVE indicates whether to use effective (true) or real (false) ids.
S_IRUSR
S_IWUSR
S_IXUSR
Returns the full path to the original file (or the filehandle) on which stat or lstat was called.
Note: Symlinks are not resolved. And, like rel2abs, neither are x/../y constructs. Use the abs_file / target methods to resolve these too.
rel2abs
x/../y
Returns the absolute path of the file. In case of a file handle, this is returned unaltered.
Returns just the permissions (including setuid/setgid/sticky bits) of the mode stat field.
Returns just the filetype of the mode stat field.
Returns true if the file is a regular file (same as -f file test).
Returns true if the file is a directory (same as -d file test).
Returns true if the file is a symbolic link (same as -l file test).
Note: Only relevant when lstat was used!
Returns true if the file is a block special file (same as -b file test).
Returns true if the file is a character special file (same as -c file test).
Returns true if the file is a FIFO file or, in case of a file handle, a pipe (same as -p file test).
Returns true if the file is a socket file (same as -S file test).
You can use the file test operators on the File::stat::Extra object just as you would on a file (handle). However, instead of querying the file system, these operators will use the information from the object itself.
Note: in case of the special file tests -t, -T, and -B, the file (handle) is tested the first time the operator is used. After the first time, the initial result is re-used.
The unary "" operator is overloaded to return the the device and inode numbers separated by a . (dev.ino). This yields a uniqe file identifier.
.
dev.ino
All other operators are automagically generated based on this representation, meaning you can easily compare two File::stat::Extra objects to see if they are the same (hardlinked) file.
When a file (handle) can not be (l)stat-ed, a warning Unable to stat: %s. To disable this warning, specify
Unable to stat: %s
no warnings "File::stat::Extra";
The following warnings are inhereted from File::stat, these can all be disabled with
File::stat
no warnings "File::stat";
You have tried to use one of the -rwxRWX filetests with use filetest 'access' in effect. File::stat will ignore the pragma, and just use the information in the mode member as usual.
-rwxRWX
use filetest 'access'
VMS systems have a permissions structure that cannot be completely represented in a stat buffer, and unlike on other systems the builtin filetest operators respect this. The File::stat overloads, however, do not, since the information required is not available.
Please report any bugs or feature requests on the bugtracker website https://github.com/HayoBaan/File-stat-Extra/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
As with File::stat, you can no longer use the implicit $_ or the special filehandle _ with this module's versions of stat and lstat.
$_
_
Currently File::stat::Extra only provides an object interface, the File::stat $st_* variables and st_cando funtion are not available. This may change in a future version of this module.
$st_*
st_cando
File::stat for the module for which File::stat::Extra is the extension.
stat and lstat for the original stat and lstat functions.
Hayo Baan <info@hayobaan.nl>
This software is copyright (c) 2015 by Hayo Baan.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install File::stat::Extra, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::stat::Extra
CPAN shell
perl -MCPAN -e shell install File::stat::Extra
For more information on module installation, please visit the detailed CPAN module installation guide.