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. Basically a shortcut for something like: my @entries = do { opendir my $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 { opendir my $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 { opendir my $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 { opendir my $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 { opendir my $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 { opendir my $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 { opendir my $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 { opendir my $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 { opendir my $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 . SOURCE Source repository is at . SEE ALSO App::FileTestUtils includes CLI's for functions like "dir_empty", etc. AUTHOR perlancar CONTRIBUTOR Steven Haryanto 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) 2023, 2021, 2020, 2019, 2017, 2015, 2014, 2013 by perlancar . 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 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.