NAME
File::Util::Test - Utilities related mostly to testing/checking for files in directories
VERSION
This document describes version 0.632 of File::Util::Test (from Perl distribution File-Util-Test), released on 2024-07-17.
SYNOPSIS
file_existsl_abs_pathdir_emptydir_has_filesdir_has_dot_filesdir_has_non_dot_filesdir_has_subdirsdir_has_non_subdirsdir_has_dot_subdirsdir_has_non_dot_subdirsdir_only_has_filesdir_only_has_dot_filesdir_only_has_non_dot_filesdir_only_has_subdirsdir_only_has_dot_subdirsdir_only_has_non_dot_subdirsget_dir_entriesget_dir_dot_entriesget_dir_subdirsget_dir_non_subdirsget_dir_dot_subdirsget_dir_non_dot_subdirsget_dir_filesget_dir_dot_filesget_dir_non_dot_filesget_dir_only_fileget_dir_only_subdirget_dir_only_symlink);"file exists"iffile_exists("/path/to/file/or/dir");"absolute path = ", l_abs_path("foo");"dir exists and is empty"ifdir_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:
saygetcwd();# /home/steven# s is a symlink to /tmp/foosayabs_path("s");# /tmp/foosayl_abs_path("s");# /home/steven/s# s2 is a symlink to /tmpsayabs_path("s2/foo");# /tmp/foosayl_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.
Basically a shortcut for something like:
my@entries=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'}readdir$dh};
get_dir_dot_entries
Usage:
my@dot_entries= get_dir_dot_entries([ \%opts, ] [$dir]);
Get all "dot" entries of a directory specified by $dir (or the current dir if unspecified), excluding "." and "..". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@dot_entries=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'&& /\A\./ }readdir$dh};
get_dir_files
Usage:
my@filenames= get_dir_files([ \%opts, ] [$dir]);
Get all plain filename entries of a directory specified by $dir (or the current dir if unspecified), including dotfiles but excluding "." and "..". See "dir_has_files" for definition of "plain files". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@filenames=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'&& -f }readdir$dh};
get_dir_dot_files
Usage:
my@dot_filenames= get_dir_dot_files([ \%opts, ] [$dir]);
Get all "dot" plain filename entries of a directory specified by $dir (or the current dir if unspecified). See "dir_has_files" for definition of "plain files". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@dot_filenames=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'&& /\A\./ && -f }readdir$dh};
get_dir_non_dot_files
Usage:
my@non_dot_filenames= get_dir_non_dot_files([ \%opts, ] [$dir]);
Get all non-"dot" plain filename entries of a directory specified by $dir (or the current dir if unspecified). See "dir_has_files" for definition of "plain files". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@non_dot_filenames=do{opendirmy$dh,$dir;grep{ !/\A\./ && -f }readdir$dh};
get_dir_subdirs
Usage:
my@subdirnames= get_dir_subdirs([ \%opts, ] [$dir]);
Get all subdirectory entries of a directory specified by $dir (or the current dir if unspecified), including dotsubdirs but excluding "." and "..". See "dir_has_subdirs" for definition of "subdirectories". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@subdirnames=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'&& !(-l) && (-d _) }readdir$dh};
get_dir_non_subdirs
Usage:
my@nonsubdirnames= get_dir_non_subdirs([ \%opts, ] [$dir]);
Get all non-subdirectory entries of a directory specified by $dir (or the current dir if unspecified). See "dir_has_subdirs" for definition of "subdirectories". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@nonsubdirnames=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'&& !(-l) && !(-d) }readdir$dh};
get_dir_dot_subdirs
Usage:
my@dot_subdirnames= get_dir_dot_subdirs([ \%opts, ] [$dir]);
Get all "dot" subdirectory entries of a directory specified by $dir (or the current dir if unspecified). See "dir_has_subdirs" for definition of "subdirectories". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@dot_subdirnames=do{opendirmy$dh,$dir;grep{$_ne'.'&&$_ne'..'&& /\A\./ && -d }readdir$dh};
get_dir_non_dot_subdirs
Usage:
my@non_dot_subdirnames= get_dir_non_dot_subdirs([ \%opts, ] [$dir]);
Get all non-"dot" subdirectory entries of a directory specified by $dir (or the current dir if unspecified). See "dir_has_subdirs" for definition of "subdirectories". Dies if directory does not exist or cannot be read.
Basically a shortcut for something like:
my@non_dot_subdirnames=do{opendirmy$dh,$dir;grep{ !/\A\./ && -d }readdir$dh};
get_dir_only_file
Usage:
my$filename= get_dir_only_file([ \%opts, ] [$dir]);
Return filename inside directory $dir (or current directory if unspecified) only if $dir has a single plain file and nothing else.
Known options:
ignore_dir
Boolean. If set to true, then ignore subdirectories.
get_dir_only_subdir
Usage:
my$subdirname= get_dir_only_subdir([ \%opts, ] [$dir]);
Return subdirectory name inside directory $dir (or current directory if unspecified) only if $dir has a single subdirectory and nothing else.
Known options:
ignore_file
Boolean. If set to true, then ignore files.
get_dir_only_symlink
Usage:
my$filename= get_dir_only_symlink([ \%opts, ] [$dir]);
Return symlink name inside directory $dir (or current directory if unspecified) only if $dir has a single symlink and nothing else.
FAQ
Where is file_empty()?
For checking if some path exists, is a plain file, and is empty (content is zero-length), you can simply use the -s or -z filetest operator.
Where is get_dir_non_dot_entries()?
That would be a regular glob("*").
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/File-Util-Test.
SOURCE
Source repository is at https://github.com/perlancar/perl-File-Util-Test.
SEE ALSO
App::FileTestUtils includes CLI's for functions like "dir_empty", etc.
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTOR
Steven Haryanto <stevenharyanto@gmail.com>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2024, 2023, 2021, 2020, 2019, 2017, 2015, 2014, 2013 by perlancar <perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=File-Util-Test
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.