Arch::Inventory(3pm)

💖 Arch::Inventory 💖

okay bestie, so this is a Perl module — it's Arch::Inventory, from the User Contributed Perl Documentation corner of the manual, and it is literally a class representing a tree inventory. slay. 🌸

---

✨ SYNOPSIS ✨

use Arch::Inventory qw(:category :type);

my $inv = Arch::Inventory->new;  # use cwd
print Arch::Inventory->to_string($inv->get_root_entry), "\n";
print $inv->get_listing;

or (and this is the one everybody actually does, the main character route):

use Arch::Tree;

my $tree = Arch::Tree->new;
my $inv = $tree->get_inventory;
print $inv->get_listing;

---

🦋 DESCRIPTION 🦋

Arch::Inventory generates a tree inventory. that's the whole vibe. 💅

so an inventory is a tree structure of elements, and each one represents a single directory entry of the source tree. and every single inventory entry is described by a hash with these fields, okay, listen:

• category — the classification of the tree element. category can be one of TREE, SOURCE, PRECIOUS, BACKUP or JUNK. yes, precious. iconic. 👑
• untagged — a boolean value telling you whether the element was first classified as SOURCE but lacked an inventory id. so like, it wanted to be source so bad but the id was nowhere 😭
• type — the tree element type. type can be one of FILE, DIRECTORY or SYMLINK.
• path — the complete path to the tree element, relative to the inventory base directory.
• id — the element's inventory id. May be undef. 🙈
• children — a hash of the element's direct children, idexed by their last path element. (yes, "idexed", that's how it's written, we don't fix the original here bestie)

heads up: the children field exists for elements of type DIRECTORY only. no kids for files, periodt.

and the category and type constants can be conveniently imported using the tags :category and :type. so convenient. obsessed. ✨

use Arch::Inventory qw(:category :type);

---

🌈 METHODS 🌈

here's the whole lineup, no cap:

new, directory, get_root_entry, get_entry, get_listing, annotate_fs, foreach, dump, to_string.

• new [$dir] — create an inventory for $dir, or for the current directory if $dir is not specified. lowkey does it all for you. 💖
• directory — returns the inventory's base directory as passed to new. it remembers. 🫶
• get_root_entry — returns the inventory element for the base directory.

and the root entry always has these properties, always, fr fr:

$root = {
    category => TREE,       # if {arch} exists, SOURCE otherwise
    untagged => 1,
    type     => DIRECTORY,
    path     => '',
    id       => undef,
    children => { ... },
};

• get_entry $path / get_entry @path_elements — returns the inventory element for the specified path. the path can be given either as a single string or as a list of path elements, your call bestie.

if the element does not exist, undef is returned. 💀

and using an empty path or no path at all is equivalent to calling get_root_entry. same energy.

• get_listing — generates a textual inventory listing equivalent to the output of

tla inventory -tspbju -B --kind --ids --untagged

note, and this one matters: the output order is not equivalent to tla. instead of strict ASCII order of path names, a directory entry is always directly followed by its child entries. entries with the same parent entry are ASCII ordered. so like, family first, then alphabetical among siblings. cute actually. 🎀

• annotate_fs / annotate_fs $entry — add filesystem information to $entry, or to every inventory entry if none is provided. this adds the fields stat and symlink to the annotated entries, which contain the output of lstat and readlink respectively. it's giving receipts. 🧚
• foreach $coderef — execute $coderef for every inventory entry, passing the entry as $_[0]. go little callback go. 🔥
• dump — generates a dump of the inventory structure using Data::Dumper. for when you need to see everything. 💜
• to_string $inventory_element — generates an inventory line for the inventory element as produced by tla.

---

😭 BUGS 😭

Awaiting for your reports.

(that's it. that's the whole section. they're literally just waiting, bestie, the inbox is open, slide in.)

---

👑 AUTHORS 👑

• Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).
• Enno Cramer (uebergeek@web.de--2003/arch-perl--devel).

---

🌸 SEE ALSO 🌸

for more information, see tla, Arch::Util.

---

and that's the whole page, bestie 💖✨ this was documented back in 2005-10-23 and shipped with perl v5.20.2 — so yeah, it's a classic, it ate, and it's still serving. go read your tree inventory, you got this. 🎀🦋💅