NAME

File::Util::Test - Utilities related mostly to testing/checking for files in directories

VERSION

This document describes version 0.631 of File::Util::Test (from Perl distribution File-Util-Test), released on 2023-11-24.

SYNOPSIS

use File::Util::Test qw(
    file_exists
    l_abs_path
    dir_empty
    dir_has_files
    dir_has_dot_files
    dir_has_non_dot_files
    dir_has_subdirs
    dir_has_non_subdirs
    dir_has_dot_subdirs
    dir_has_non_dot_subdirs
    dir_only_has_files
    dir_only_has_dot_files
    dir_only_has_non_dot_files
    dir_only_has_subdirs
    dir_only_has_dot_subdirs
    dir_only_has_non_dot_subdirs

    get_dir_entries
    get_dir_dot_entries
    get_dir_subdirs
    get_dir_non_subdirs
    get_dir_dot_subdirs
    get_dir_non_dot_subdirs
    get_dir_files
    get_dir_dot_files
    get_dir_non_dot_files
    get_dir_only_file
    get_dir_only_subdir
    get_dir_only_symlink
);

print "file exists" if file_exists("/path/to/file/or/dir");
print "absolute path = ", l_abs_path("foo");
print "dir exists and is empty" if dir_empty("/path/to/dir");

DESCRIPTION

FUNCTIONS

None are exported by default, but they are exportable.

file_exists

Usage:

file_exists($path) => BOOL

This routine is just like the -e test, except that it assume symlinks with non-existent target as existing. If sym is a symlink to a non-existing target:

-e "sym"             # false, Perl performs stat() which follows symlink

but:

-l "sym"             # true, Perl performs lstat()
-e _                 # false

This function performs the following test:

!(-l "sym") && (-e _) || (-l _)

Which one should you use: -e or file_exists? It depends on whether you want to consider a broken symlink as "existing" or not. Sometimes one is more appropriate than the other. If you use -e, your application might overwrite a (temporarily) broken symlink; on the other hand if you use file_exists, your application will see a file as existing but gets confused when it cannot open it.

l_abs_path

Usage:

l_abs_path($path) => STR

Just like Cwd::abs_path(), except that it will not follow symlink if $path is symlink (but it will follow symlinks for the parent paths).

Example:

use Cwd qw(getcwd abs_path);

say getcwd();              # /home/steven
# s is a symlink to /tmp/foo
say abs_path("s");         # /tmp/foo
say l_abs_path("s");       # /home/steven/s
# s2 is a symlink to /tmp
say abs_path("s2/foo");    # /tmp/foo
say l_abs_path("s2/foo");  # /tmp/foo

Mnemonic: l_abs_path -> abs_path is analogous to lstat -> stat.

Note: currently uses hardcoded / as path separator.

dir_empty

Usage:

dir_empty($dir) => BOOL

Will return true if $dir exists and is empty.

This should be trivial but alas it is not. -s always returns true (in other words, -z always returns false) for a directory.

To test that a directory is not empty, use "dir_not_empty" (or its alias "dir_has_entries").

dir_not_empty

Usage:

dir_not_empty($dir) => BOOL

Will return true if $dir exists and is not empty (has entries other than . and ..).

To test that a directory is empty, use "dir_empty".

dir_has_entries

Alias for "dir_not_empty".

dir_has_files

Usage:

dir_has_files($dir) => BOOL

Will return true if $dir exists and has one or more plain files in it. A plain file is one that passes Perl's -f operator. A symlink to a plain file counts as a plain file. Non-plain files include named pipes, Unix sockets, and block/character special files.

dir_has_dot_files

Usage:

dir_has_dot_files($dir) => BOOL

Will return true if $dir exists and has one or more plain dot files in it. See "dir_has_files" for the definition of plain files. Dot files a.k.a. hidden files are files with names beginning with a dot.

dir_has_non_dot_files

Usage:

dir_has_non_dot_files($dir) => BOOL

Will return true if $dir exists and has one or more plain non-dot files in it. See "dir_has_dot_files" for the definitions. =head2 dir_has_subdirs

dir_has_subdirs

Usage:

dir_has_subdirs($dir) => BOOL

Will return true if $dir exists and has one or more subdirectories in it. A symlink to a directory does NOT count as subdirectory.

dir_has_non_subdirs

Usage:

dir_has_non_subdirs($dir) => BOOL

Will return true if $dir exists and has one or more non-subdirectories in it. A symlink to a directory does NOT count as subdirectory and thus counts as a non-subdirectory.

dir_has_dot_subdirs

Usage:

dir_has_dot_subdirs($dir) => BOOL

Will return true if $dir exists and has one or more dot subdirectories (i.e. subdirectories with names beginning with a dot) in it. A symlink to a directory does NOT count as subdirectory.

dir_has_non_dot_subdirs

Usage:

dir_has_non_dot_subdirs($dir) => BOOL

Will return true if $dir exists and has one or more non-dot subdirectories (i.e. subdirectories with names not beginning with a dot) in it. A symlink to a directory does NOT count as subdirectory.

dir_only_has_files

Usage:

dir_only_has_files($dir) => BOOL

Will return true if $dir exists and has one or more plain files in it *and* does not have anything else. See "dir_has_files" for the definition of plain files.

dir_only_has_dot_files

Usage:

dir_only_has_dot_files($dir) => BOOL

Will return true if $dir exists and has one or more plain dot files in it *and* does not have anything else. See "dir_has_files" for the definition of plain files.

dir_only_has_non_dot_files

Usage:

dir_only_has_non_dot_files($dir) => BOOL

Will return true if $dir exists and has one or more plain non-dot files in it *and* does not have anything else. See "dir_has_files" for the definition of plain files.

dir_only_has_subdirs

Usage:

dir_only_has_subdirs([ \%opts, ] $dir) => BOOL

Will return true if $dir exists and has one or more subdirectories in it *and* does not have anything else.

dir_only_has_dot_subdirs

Usage:

dir_only_has_dot_subdirs([ \%opts, ] $dir) => BOOL

Will return true if $dir exists and has one or more dot subdirectories in it *and* does not have anything else.

dir_only_has_non_dot_subdirs

Usage:

dir_only_has_non_dot_subdirs([ \%opts, ] $dir) => BOOL

Will return true if $dir exists and has one or more plain non-dot subdirectories in it *and* does not have anything else.

get_dir_entries

Usage:

my @entries = get_dir_entries([ \%opts, ] [ $dir ]);

Get all entries of a directory specified by $dir (or the current dir if unspecified), including dotfiles but excluding "." and "..". Dies if directory does not exist or cannot be read.