NAME
Module::Generic::Finfo - File Info Object Class
SYNOPSIS
use Module::Generic::Finfo qw( :all );
my $finfo = Module::Generic::Finfo->new( '/some/file/path.html' );
# Get access time as a DateTime object
$finfo->atime;
# Block site
$finfo->blksize;
# Number of blocks
$finfo->blocks;
if( $finfo->can_read )
{
# Do something
}
# Can also use
$finfo->can_write;
$finfo->can_exec;
$finfo->csize;
# Inode change time as a DateTime object
$finfo->ctime;
$finfo->dev;
if( $finfo->exists )
{
# Do something
}
print "File path is: ", $finfo->filepath;
if( $finfo->filetype == FILETYPE_NOFILE )
{
# File does not exist
}
# Same as $finfo->filepath
print "File path is: ", $finfo->fname;
print "File group id is: ", $finfo->gid;
# Can also use $finfo->group which will yield the same result
$finfo->ino;
# or $finfo->inode;
if( $finfo->is_block )
{
# Do something
}
elsif( $finfo->is_char )
{
# Do something else
}
elsif( $finfo->is_dir )
{
# It's a directory
}
elsif( $finfo->is_file )
{
# It's a regular file
}
elsif( $finfo->is_link )
{
# A file alias
}
elsif( $info->is_pipe )
{
# A Unix pipe !
}
elsif( $finfo->is_socket )
{
# It's a socket
}
elsif( ( $info->mode & 0100 ) )
{
# Can execute
}
$finfo->mtime->strftime( '%A %d %B %Y %H:%m:%S' );
print "File base name is: ", $finfo->name;
printf "File has %d links\n", $finfo->nlink;
print "File permission in hexadecimal: ", $finfo->protection;
$finfo->rdev;
$finfo->size;
my $new_object = $finfo->stat( '/some/other/file.txt' );
# Get the user id
$finfo->uid;
# Or
$finfo->user;
VERSION
v0.4.0
DESCRIPTION
This class provides a file info object oriented api.
The other advantage is that even if a non-existing file is provided, an object is returned. Obviously many of this module's methods will return an empty value since the file does not actually exist.
METHODS
new
This instantiate an object that is used to access other key methods. It takes a file path.:
atime
Returns the file last access time as a Module::Generic::DateTime object, which stringifies to its value in second since epoch. Module::Generic::DateTime is just a thin wrapper around DateTime to allow a DateTime to be used in comparison with another non DateTime value.
For example:
if( $finfo->atime > time() + 86400 )
{
print( "You are traveling in the future\n" );
}
blksize
Returns the preferred I/O size in bytes for interacting with the file. You can also use block_size
.
block_size
Alias for "blksize"
blocks
Returns the actual number of system-specific blocks allocated on disk (often, but not always, 512 bytes each).
can_read
Returns true if the the effective user can read the file.
can_write
Returns true if the the effective user can write to the file.
can_exec
Returns true if the the effective user can execute the file. Same as "execute"
can_execute
Returns true if the the effective user can execute the file. Same as "exec"
csize
Returns the total size of file, in bytes. Same as "size"
ctime
Returns the file inode change time as a Module::Generic::DateTime object, which stringifies to its value in second since epoch. Module::Generic::DateTime is just a thin wrapper around DateTime to allow a DateTime to be used in comparison with another non DateTime value.
dev
Returns the device number of filesystem. Same as "dev"
device
Returns the device number of filesystem. Same as "device"
exists
Returns true if the filetype is not "FILETYPE_NOFILE"
filepath
Returns the file path as a string. Same as "fname"
filetype
Returns the file type which is one of the "CONSTANTS" below.
fname
Returns the file path as a string. Same as "filepath"
gid
Returns the numeric group ID of file's owner. Same as "group"
group
Returns the numeric group ID of file's owner. Same as "gid"
ino
Alias for "ino"
inode
Returns the inode number.
is_block
Returns true if this is a block file, false otherwise.
is_char
Returns true if this is a character file, false otherwise.
is_dir
Returns true if this is a directory, false otherwise.
is_file
Returns true if this is a regular file, false otherwise.
is_link
Returns true if this is a symbolic link, false otherwise.
is_pipe
Returns true if this is a pipe, false otherwise.
is_socket
Returns true if this is a socket, false otherwise.
mime_type
This guesses the file mime type and returns it as a scalar object
If File::MMagic::XS is installed, it will use it, otherwise, it will use File::MMagic
mode
Returns the file mode. This is equivalent to the mode & 07777, ie without the file type bit.
So you could do something like:
if( $finfo->mode & 0100 )
{
print( "Owner can execute\n" );
}
if( $finfo->mode & 0001 )
{
print( "Everyone can execute too!\n" );
}
mode_n2s
Returns the file or directory mode as human readable string
mode_s2n
Takes a string and convert it into octal mode.
mtime
Returns the file last modify time as a Module::Generic::DateTime object, which stringifies to its value in second since epoch. Module::Generic::DateTime is just a wrapper around DateTime to allow a DateTime to be used in comparison with another non DateTime value.
name
Returns the file base name. So if the file is /home/john/www/some/file.html
this would return file.html
Interesting to note that "name" in APR::Finfo which is advertised as returning the file base name, actually returns just an empty string. With this module, this uses a workaround to provide the proper value. It use "basename" in File::Basename on the value returned by "fname"
nlink
Returns the number of (hard) links to the file.
protection
rdev
Returns the device identifier (special files only).
reset
Force Module::Generic::Finfo to reload the filesystem information of the underlying file or directory
size
Returns the total size of file, in bytes. Same as "csize"
stat
Provided with a file path and this returns a new Module::Generic::Finfo object.
user
Returns the numeric user ID of file's owner. Same as "uid"
uid
Returns the numeric user ID of file's owner. Same as "user"
CONSTANTS
FILETYPE_NOFILE
File type constant to indicate the file does not exist.
FILETYPE_REG
Regular file
FILETYPE_DIR
The element is a directory
FILETYPE_CHR
The element is a character block
FILETYPE_BLK
A block device
FILETYPE_PIPE
The file is a FIFO or a pipe
FILETYPE_LNK
The file is a symbolic link
FILETYPE_SOCK
The file is a (unix domain) socket
FILETYPE_UNKFILE
The file is of some other unknown type or the type cannot be determined
SERIALISATION
Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE
, THAW
, STORABLE_freeze
and STORABLE_thaw
AUTHOR
Jacques Deguest <jack@deguest.jp>
CPAN ID: jdeguest
https://gitlab.com/jackdeguest/Module-Generic
SEE ALSO
Module::Generic::File, Module::Generic
COPYRIGHT & LICENSE
Copyright (c) 2021 DEGUEST Pte. Ltd.
You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.