NAME

File::MoreUtil - File-related utilities

VERSION

This document describes version 0.624 of File::MoreUtil (from Perl distribution File-MoreUtil), released on 2020-05-30.

SYNOPSIS

 use File::MoreUtil 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

     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
 );

 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 _)

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.

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.

get_dir_entries

Usage:

 my @entries = get_dir_entries([ $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([ $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([ $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([ $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([ $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([ $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([ $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([ $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([ $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 };

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

SOURCE

Source repository is at https://github.com/perlancar/perl-SHARYANTO-File-Util.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=File-MoreUtil

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.

SEE ALSO

App::FileTestUtils includes CLI's for functions like "dir_empty", etc.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020, 2019, 2017, 2015, 2014, 2013 by 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.