# NOTE: CBOR will call the THAW method with the stored classname as first argument, the constant string CBOR as second argument, and all values returned by FREEZE as remaining arguments.
# NOTE: Storable calls it with a blessed object it created followed with $cloning and any other arguments initially provided by STORABLE_freeze
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;
=head1 VERSION
v0.4.0
=head1 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.
=head1 METHODS
=head2 new
This instantiate an object that is used to access other key methods. It takes a file path.:
=head2 atime
Returns the file last access time as a L<Module::Generic::DateTime> object, which stringifies to its value in second since epoch. L<Module::Generic::DateTime> is just a thin wrapper around L<DateTime> to allow a L<DateTime> to be used in comparison with another non L<DateTime> value.
For example:
if( $finfo->atime > time() + 86400 )
{
print( "You are traveling in the future\n" );
}
=head2 blksize
Returns the preferred I/O size in bytes for interacting with the file.
You can also use C<block_size>.
=head2 block_size
Alias for L</blksize>
=head2 blocks
Returns the actual number of system-specific blocks allocated on disk (often, but not always, 512 bytes each).
=head2 can_read
Returns true if the the effective user can read the file.
=head2 can_write
Returns true if the the effective user can write to the file.
=head2 can_exec
Returns true if the the effective user can execute the file. Same as L</execute>
=head2 can_execute
Returns true if the the effective user can execute the file. Same as L</exec>
=head2 csize
Returns the total size of file, in bytes. Same as L</size>
=head2 ctime
Returns the file inode change time as a L<Module::Generic::DateTime> object, which stringifies to its value in second since epoch. L<Module::Generic::DateTime> is just a thin wrapper around L<DateTime> to allow a L<DateTime> to be used in comparison with another non L<DateTime> value.
=head2 dev
Returns the device number of filesystem. Same as L</dev>
=head2 device
Returns the device number of filesystem. Same as L</device>
=head2 exists
Returns true if the filetype is not L</FILETYPE_NOFILE>
=head2 filepath
Returns the file path as a string. Same as L</fname>
=head2 filetype
Returns the file type which is one of the L</CONSTANTS> below.
=head2 fname
Returns the file path as a string. Same as L</filepath>
=head2 gid
Returns the numeric group ID of file's owner. Same as L</group>
=head2 group
Returns the numeric group ID of file's owner. Same as L</gid>
=head2 ino
Alias for L</ino>
=head2 inode
Returns the inode number.
=head2 is_block
Returns true if this is a block file, false otherwise.
=head2 is_char
Returns true if this is a character file, false otherwise.
=head2 is_dir
Returns true if this is a directory, false otherwise.
=head2 is_file
Returns true if this is a regular file, false otherwise.
=head2 is_link
Returns true if this is a symbolic link, false otherwise.
=head2 is_pipe
Returns true if this is a pipe, false otherwise.
=head2 is_socket
Returns true if this is a socket, false otherwise.
=head2 mime_type
This guesses the file mime type and returns it as a L<scalar object|Module::Generic::Scalar>
If L<File::MMagic::XS> is installed, it will use it, otherwise, it will use L<File::MMagic>
=head2 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" );
}
=head2 mode_n2s
Returns the file or directory mode as human readable string
=head2 mode_s2n
Takes a string and convert it into octal mode.
=head2 mtime
Returns the file last modify time as a L<Module::Generic::DateTime> object, which stringifies to its value in second since epoch. L<Module::Generic::DateTime> is just a wrapper around L<DateTime> to allow a L<DateTime> to be used in comparison with another non L<DateTime> value.
=head2 name
Returns the file base name. So if the file is C</home/john/www/some/file.html> this would return C<file.html>
Interesting to note that L<APR::Finfo/name> 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 L<File::Basename/basename> on the value returned by L</fname>
=head2 nlink
Returns the number of (hard) links to the file.
=head2 protection
=head2 rdev
Returns the device identifier (special files only).
=head2 reset
Force L<Module::Generic::Finfo> to reload the filesystem information of the underlying file or directory
=head2 size
Returns the total size of file, in bytes. Same as L</csize>
=head2 stat
Provided with a file path and this returns a new L<Module::Generic::Finfo> object.
=head2 user
Returns the numeric user ID of file's owner. Same as L</uid>
=head2 uid
Returns the numeric user ID of file's owner. Same as L</user>
=head1 CONSTANTS
=head2 FILETYPE_NOFILE
File type constant to indicate the file does not exist.
=head2 FILETYPE_REG
Regular file
=head2 FILETYPE_DIR
The element is a directory
=head2 FILETYPE_CHR
The element is a character block
=head2 FILETYPE_BLK
A block device
=head2 FILETYPE_PIPE
The file is a FIFO or a pipe
=head2 FILETYPE_LNK
The file is a symbolic link
=head2 FILETYPE_SOCK
The file is a (unix domain) socket
=head2 FILETYPE_UNKFILE
The file is of some other unknown type or the type cannot be determined
=head1 SERIALISATION
=for Pod::Coverage FREEZE
=for Pod::Coverage STORABLE_freeze
=for Pod::Coverage STORABLE_thaw
=for Pod::Coverage THAW
=for Pod::Coverage TO_JSON
Serialisation by L<CBOR|CBOR::XS>, L<Sereal> and L<Storable::Improved> (or the legacy L<Storable>) is supported by this package. To that effect, the following subroutines are implemented: C<FREEZE>, C<THAW>, C<STORABLE_freeze> and C<STORABLE_thaw>