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
     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
    <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.