NAME
Dir::ls - List the contents of a directory
SYNOPSIS
use Dir::ls;
print "$_\n" for ls; # defaults to current working directory
print "$_: ", -s "/foo/bar/$_", "\n" for ls '/foo/bar', {-a => 1, sort => 'size'};
DESCRIPTION
Provides the function "ls", which returns the contents of a directory
in a similar manner to the GNU coreutils command ls(1).
FUNCTIONS
ls
my @contents = ls $dir, \%options;
Takes a directory path and optional hashref of options, and returns a
list of items in the directory. Home directories represented by ~ will
be expanded by Path::ExpandTilde. If no directory path is passed, the
current working directory will be used. Like in ls(1), the returned
names are relative to the passed directory path, so if you want to use
a filename (such as passing it to open or stat), you must prefix it
with the directory path, with ~ expanded if present.
# Check the size of a file in current user's home directory
my @contents = ls '~';
say -s "$ENV{HOME}/$contents[0]";
By default, hidden files and directories (those starting with .) are
omitted, and the results are sorted by name according to the current
locale (see perllocale for more information).
Accepts the following options (any prefixed hyphens are ignored):
a
all
Include hidden files and directories.
A
almost-all
Include hidden files and directories, but not . or ...
B
ignore-backups
Omit files and directories ending in ~.
c
Sort by ctime (change time) in seconds since the epoch.
F
classify
Append classification indicators to the end of file and directory
names. Equivalent to 'indicator-style' => 'classify'.
f
Equivalent to passing all and setting sort to none.
file-type
Append file-type indicators to the end of file and directory names.
Equivalent to 'indicator-style' => 'file-type'.
group-directories-first
Return directories then files. The sort algorithm will be applied
within these groupings, but U or sort => 'none' will disable the
grouping.
hide
Omit files and directories matching given Text::Glob pattern.
Overriden by a/all or A/almost-all.
I
ignore
Omit files and directories matching given Text::Glob pattern.
indicator-style
Append indicators to the end of filenames according to the specified
style. Recognized styles are: none (default), slash (appends / to
directories), file-type (appends all of the below indicators except
*), and classify (appends all of the below indicators).
/ directory
@ symbolic link
= socket
| named pipe (FIFO)
* executable
Use of indicator types other than slash will render the resulting
filenames suitable only for display due to the extra characters.
p
Append / to the end of directory names. Equivalent to
'indicator-style' => 'slash'.
r
reverse
Reverse sort order (unless U or sort => 'none' specified).
sort
Specify sort algorithm other than the default sort-by-name. Valid
values are: none, extension, size, time, or version.
S
Sort by file size in bytes (descending). Equivalent to sort =>
'size'.
t
Sort by mtime (modification time) in seconds since the epoch.
Equivalent to sort => 'time'.
u
Sort by atime (access time) in seconds since the epoch.
U
Return entries in directory order (unsorted). Equivalent to sort =>
'none'.
v
Sort naturally by version numbers within the name. Uses
Sort::filevercmp for sorting. Equivalent to sort => 'version'.
X
Sort by (last) file extension, according to the current locale.
Equivalent to sort => 'extension'.
CAVEATS
This is only an approximation of ls(1). It makes an attempt to give the
same output under the supported options, but there may be differences
in edge cases. Weird things might happen with sorting of non-ASCII
filenames, or on non-Unixlike systems. Lots of options aren't supported
yet. Patches welcome.
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <
[email protected]>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2017 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
SEE ALSO
Path::Tiny, ls(1)
