/ 
Dev-Util-v2.19.8
/ Dev::Util::File

NAME

Dev::Util::File - General utility functions for files and directories.

VERSION

Version v2.19.8

SYNOPSIS

Dev::Util::File - provides functions to assist working with files and dirs, menus and prompts.

use Dev::Util::File;

my $fexists   = file_exists('/path/to/somefile');
my $canreadf  = file_readable('/path/to/somefile');
my $canwritef = file_writable('/path/to/somefile');
my $canexecf  = file_executable('/path/to/somefile');

my $isemptyfile = file_is_empty('/path/to/somefile');
my $fileissize = file_size_equals('/path/to/somefile', $number_of_bytes);

my $isplainfile = file_is_plain('/path/to/somefile');
my $issymlink = file_is_symbolic_link('/path/to/somefile');
...

my $dexists  = dir_exists('/path/to/somedir');
my $canreadd  = dir_readable('/path/to/somedir');
my $canwrited = dir_writable('/path/to/somedir');

my $slash_added_dir = dir_suffix_slash('/dir/path/no/slash');

my $td = mk_temp_dir();
my $tf = mk_temp_file($td);

my $file_date     = stat_date( $test_file, 0, 'daily' );    # 20240221
my $file_date     = stat_date( $test_file, 1, 'monthly' );  # 2024/02

my $mtime =  status_for($file)->{mtime}

my $scalar_list = read_list(FILE);
my @array_list  = read_list(FILE);

EXPORT_TAGS

:fattr
file_exists
file_readable
file_writable
file_executable
file_is_empty
file_size_equals
file_owner_effective
file_owner_real
file_is_setuid
file_is_setgid
file_is_sticky
file_is_ascii
file_is_binary
:ftypes
file_is_plain
file_is_pipe
file_is_socket
file_is_block
file_is_character
:dirs
dir_exists
dir_readable
dir_writable
dir_executable
dir_suffix_slash
:misc
mk_temp_dir
mk_temp_file
stat_date
status_for
read_list

SUBROUTINES

file_exists(FILE)

Tests for file existence. Returns true if the file exists, false if it does not.

All of the subroutines return 1 for true and 0 for false.

FILE a string or variable pointing to a file.

my $fexists  = file_exists('/path/to/somefile');

file_readable(FILE)

Tests for file existence and is readable. Returns true if file is readable, false if not.

my $canreadf  = file_readable('/path/to/somefile');

file_writable(FILE)

Tests for file existence and is writable. Returns true if file is writable, false if not.

my $canwritef = file_writable('/path/to/somefile');

file_executable(FILE)

Tests for file existence and is executable. Returns true if file is executable, false if not.

my $canexecf  = file_executable('/path/to/somefile');

file_is_empty(FILE)

Check if the file is zero sized. Returns true if file is zero bytes, false if not.

my $isemptyfile = file_is_empty('/path/to/somefile');

file_size_equals(FILE, BYTES)

Check if the file size equals given size. Returns true if file is the given number of bytes, false if not.

BYTES The number of bytes to test for.

my $fileissize = file_size_equals('/path/to/somefile', $number_of_bytes);

file_owner_effective(FILE)

Check if the file is owned by the effective uid. Returns true if file is owned by the effective user, false if not.

my $effectiveuserowns = file_owner_effective('/path/to/somefile');

file_owner_real(FILE)

Check if the file is owned by the real uid. Returns true if file is owned by the real user, false if not.

my $realuserowns = file_owner_real('/path/to/somefile');

file_is_setuid(FILE)

Check if the file has setuid bit set. Returns true if file is setuid, for example: .r-Sr--r--

my $isfilesuid = file_is_setuid('/path/to/somefile');

file_is_setgid(FILE)

Check if the file has setgid bit set. Returns true if file is setgid, for example: .r--r-Sr--

my $isfileguid = file_is_setgid('/path/to/somefile');

file_is_sticky(FILE)

Check if the file has sticky bit set. Returns true if file is sticky, for example: .r--r--r-T

my $isfilesticky = file_is_sticky('/path/to/somefile');

file_is_ascii(FILE)

Check if the file is an ASCII or UTF-8 text file (heuristic guess). Returns true if file is ascii, false if binary.

my $isfileascii = file_is_ascii('/path/to/somefile');

file_is_binary(FILE)

Check if the file is a "binary" file (opposite of file_is_ascii). Returns true if file is binary, false if ascii.

my $isfilebinary = file_is_binary('/path/to/somefile');

file_is_plain(FILE)

Tests that file is a regular file. Returns true if file is a plain file, false if not.

my $isplainfile = file_is_plain('/path/to/somefile');

file_is_symbolic_link(FILE)

Tests that file is a symbolic link. Returns true if file is a symbolic link, for example: lr--r--r--

my $issymlink = file_is_symbolic_link('/path/to/somefile');

file_is_pipe(FILE)

Tests that file is a named pipe. Returns true if file is a pipe, for example: |rw-rw-rw-

my $ispipe = file_is_pipe('/path/to/somefile');

file_is_socket(FILE)

Tests that file is a socket. Returns true if file is a socket, for example: srw-------

my $issocket = file_is_socket('/path/to/somefile');

file_is_block(FILE)

Tests that file is a block special file. Returns true if file is a block file, for example: brw-r-----

my $isblock = file_is_block('/path/to/somefile');

file_is_character(FILE)

Tests that file is a block character file. Returns true if file is a block character file, for example: crw-r-----

my $ischarf = file_is_character('/path/to/somefile');

dir_exists(DIR)

Tests for dir existence. Returns true if the directory exists, false if not.

DIR a string or variable pointing to a directory.

my $dexists  = dir_exists('/path/to/somedir');

dir_readable(DIR)

Tests for dir existence and is readable. Returns true if the directory is readable, false if not.

my $canreadd  = dir_readable('/path/to/somedir');

dir_writable(DIR)

Tests for dir existence and is writable. Returns true if the directory is writable, false if not.

my $canwrited = dir_writable('/path/to/somedir');

dir_executable(DIR)

Tests for dir existence and is executable. Returns true if the directory is executable, false if not.

my $canenterdir = dir_executable('/path/to/somedir');

dir_suffix_slash(DIR)

Ensures a dir ends in a slash by adding one if necessary.

my $slash_added_dir = dir_suffix_slash('/dir/path/no/slash');

mk_temp_dir(DIR)

Create a temporary directory in the supplied parent dir. /tmp is the default if no dir given.

DIR a string or variable pointing to a directory.

my $td = mk_temp_dir();

mk_temp_file(DIR)

Create a temporary file in the supplied dir. /tmp is the default if no dir given.

my $tf = mk_temp_file($td);

stat_date(FILE, DIR_FORMAT, DATE_FORMAT)

Return the stat date of a file

DIR_FORMAT Style of date, include slashes? 0: YYYYMMDD, 1: YYYY/MM/DD

DATE_FORMAT Granularity of date: daily: YYYYMMDD, monthly: YYYY/MM

my $file_date     = stat_date( $test_file, 0, 'daily' );    # 20240221
my $file_date     = stat_date( $test_file, 1, 'monthly' );  # 2024/02

   format: YYYYMMDD,
or format: YYYY/MM/DD if dir_format is true
or format: YYYYMM or YYYY/MM if date_type is monthly

status_for

Return hash_ref of file stat info.

my $stat_info_ref = status_for($file);
my $mtime = $stat_info_ref->{mtime};

Available keys:

dev ino mode nlink uid gid rdev size atime mtime ctime blksize blocks

read_list

Read a list from an input file return an array of lines if called in list context. If called by scalar context it will slurp the whole file and return it as a scalar. Comments (begins with #) and blank lines are skipped.

my $scalar_list = read_list(FILE);
my @array_list  = read_list(FILE);

Note: The API for this function is maintained to support the existing code base that uses it. It would probably be better to use Perl6::Slurp for new code.

AUTHOR

Matt Martini, <matt at imaginarywave.com>

BUGS

Please report any bugs or feature requests to bug-dev-util at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dev-Util. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dev::Util::File

You can also look for information at:

ACKNOWLEDGMENTS

LICENSE AND COPYRIGHT

This software is Copyright © 2019-2025 by Matt Martini.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007