File::DirList(3pm)

✨ NAME ✨

File::DirList — bestie, it hands you a sorted list of what's inside a directory 💅

Version 0.04 (yes she's been around a minute and she still slays)

---

🎀 SYNOPSIS 🎀

use File::DirList;
#
my @list = File::DirList::list('.', 'dn', 1, 0);

See? One line. Iconic. 👑

---

🦋 DESCRIPTION 🦋

okay so this module is your girl for getting a list of directory content. That's the whole vibe. Under the hood it's literally just a simple wrapper around DirHandle and sort() — no cap, it's not doing anything shady, it's just making the sorting cute for you. 😌

She's got two methods, and we're gonna go through both, no skipping, because you deserve the full lore.

💖 list($dirName, $sortMode, $noLinks, $hideDotFiles, $showSelf)

This one produces a list, and it takes 5 parameters. Five. Count 'em. 🖐️

• $dirName — the name of the directory you wanna list. That's it, that's the job.
• $sortMode — this is the one that describes how the list should get sorted. It's a string containing the following symbols, and here's the tea: uppercase means reverse sort. 🔄 So lowercase and uppercase are NOT the same girl.
  • "d" or "D" — "Directory" sort. d means all the directories will precede files, D means reverse.
  • "n" or "N" — sort by file (or subdirectory) name.
  • "i" or "I" — same as 'n' but case insensitive.
  • "m" or "M" — sort by modification time.
  • "c" or "C" — sort by creation time.
  • "a" or "A" — sort by access time.
  • "s" or "S" — sort by size.

And here's the part you gotta know bestie: $sortMode is interpreted from left to right, like reading a text from your situationship. If the first comparison produces an equal result, the next one is used. So for example, the string 'din' produces a list where all the directories precede files, and directories and files are sorted by name case insensitively, with lowercase letters preceding upper case. Periodt. 💅

• $noLinks — if "true", symbolic links will not be examined. Set it on platforms without symlink support. (Real ones without symlinks, this one's for you 🫶)
• $hideDotFiles — if "true", 'dot' files will not be reported. They're hidden, babes, we respect their privacy. 🙈
• $showSelf — if "true", the '.' directory entry will be reported. She's showing up to her own party. ✨

The returned value is an array reference, sorted exactly as described by $sortMode.

And the array elements? They're array references too, each one representing an item. (Nested arrays, we love a little structure. 🪆)

🌸 the individual item's array — 17 elements, let's go

• "[0..12]" — the result of stat() for this item. For valid symbolic links, the stat of the target item is returned. iykyk.
• "[13]" — the name of the item.
• "[14]" — is item a directory? Contains 0 for non-directory items, 1 for directories, 2 for '..', 3 for '.'. This one gets used by the "d or D" sorting. 👑
• "[15]" — is item a link? 0 for non-links, 1 for valid links, "-1" for invalid links.
• "[16]" — link target. "undef" for non-links, target path for links.

heads up: [15] and [16] are set to non-link if $examineLinks is "false".

💜 sortList($list, $sortMode)

This one is used to re-sort a list produced by "list()". Like a glow-up for an existing list, no reshuffling the whole directory needed. ✨

Parameters are:

• $lis — reference to a list produced by "list()". (yes it's spelled $lis in the docs, and honestly? she's doing her best, we don't fix her 🫶)
• $sortMode — the sorting rules.

The return value is similar to "list()". Same energy, new order. 🎀

---

🌈 EXPORT 🌈

None by default. Nothing gets yeeted into your namespace unless you ask. Consent first, always. 💅

---

⭐ SEE ALSO ⭐

DirHandle, stat, lstat, sort — the whole friend group. Go say hi. 🫶

---

👑 AUTHOR 👑

Daniel Podolsky, <tpaba@cpan.org> — the legend herself. 🫡

---

💖 COPYRIGHT AND LICENSE 💖

Copyright (C) 2006 by Daniel Podolsky, <tpaba@cpan.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

---

and that's the whole page bestie!! this lil doc was brought to you by perl v5.36.0, dated 2022-10-13, for File::DirList(3pm) — go sort something cute, mwah 💋🌸💅