Dir::Purge(3pm)

💖 Dir::Purge 💖

okay so bestie, welcome to Dir::Purge(3pm) — that's the User Contributed Perl Documentation part of your man pages, and it's literally the "pls stop hoarding files in this one folder" module. slay. 🦋

---

🌸 NAME 🌸

Dir::Purge — purge directories to a given number of files. that's it. that's the whole mission statement. 💅

---

✨ SYNOPSIS ✨

here's how you roll up on it, three ways:

perl -MDir::Purge -e 'purgedir (5, @ARGV)' /spare/backups

use Dir::Purge;
purgedir ({keep => 5, strategy => "by_age", verbose => 1}, "/spare/backups");

use Dir::Purge qw(purgedir_by_age);
purgedir_by_age (5, "/spare/backups");

one-liner, options-hash era, or the pre-baked shortcut. pick your fighter. 🥊

---

🔥 DESCRIPTION 🔥

Dir::Purge implements functions to reduce the number of files in a directory according to a strategy. right now there's exactly one strategy on the menu: removal of files by age. that's the whole roster, no cap.

by default, the module exports one user subroutine: purgedir.

the first argument of purgedir should either be an integer — meaning the number of files to keep in each of the directories — or a reference to a hash with options. either way, bestie, a value for the number of files to keep is mandatory. no keep value, no purge.

the other arguments are the names of the directories that must be purged. and listen, important detail: this process is not recursive, she stays on the surface. also hidden files (name starts with a .) and non-plain files (e.g., directories, symbolic links) are not taken into account. she does not see them. she does not care about them.

all directory arguments and options are checked before anything else is done. in particular, all arguments should point to existing directories and the program must have read, write, and search (execute) access to the directories. vibe check first, deletion second. 🫶

one additional function, purgedir_by_age, can be exported on demand, or called by its fully qualified name. purgedir_by_age calls purgedir with the "by age" purge strategy preselected. and since that happens to be the default strategy for purgedir anyway, calling purgedir_by_age is roughly equivalent to calling purgedir. same energy, cuter name. 💜

---

⚠️ WARNING ⚠️

removing files is a quite destructive operation. supply the test option, described below, to dry-run before production. no cap, please actually do this. 😭

---

💅 OPTIONS 💅

options are supplied by providing a hash reference as the first argument. these three calls are equivalent, bestie, all roads lead to the same purge:

purgedir ({keep => 3, test => 1}, "/spare/backups");
purgedir_by_age ({keep => 3, test => 1}, "/spare/backups");
purgedir ({strategy => "by_age", keep => 3, test => 1}, "/spare/backups");

all subroutines take the same arguments. here they are, one by one:

• keep — the number of files to keep. a negative number will reverse the strategy. see option reverse below. 👑
• strategy — specifies the purge strategy. default (and only allowed) value is "by_age".

this option is for purgedir only. the other subroutines should not be provided with a strategy option. 🙈

• include — if this is a reference to a subroutine, this subroutine is called with arguments ($file,$dir) and must return true for the file to be included in the list of candidates.

if this is a regular expression, the file will be included only if the expression matches the file name. 🎯

• reverse — if true, the strategy will be reversed. for example, if the strategy is "by_age", the oldest files will be kept instead of the newest files.

another way to reverse the strategy is using a negative keep value. this is not unlike Perl's array subscripts, which count from the end if negative. iykyk. ✨

a negative keep value can be combined with reverse to reverse the reversed strategy again. yes, really. strategy-ception.

• verbose — verbosity of messages. default value is 1, which will report the names of the files being removed. a value greater than 1 will produce more messages about what's going on. a value of 0 (zero) will suppress messages. 🤫
• debug — for internal debugging only. not your business, bestie. 💀
• test — if true, no files will be removed. for testing. the icon, the moment, the safety net. 🛟

---

🎀 EXPORT 🎀

subroutine purgedir is exported by default. she's just there, living her life.

subroutine purgedir_by_age may be exported on demand.

calling purgedir_by_age() is roughly equivalent to calling purgedir() with an options hash that includes — and the docs literally print it like this: strategy = "by_age". it's giving typo energy but the meaning is clear. 🫠

the variable $Dir::Purge::VERSION may be used to inspect the version of the module. ⭐

---

👑 AUTHOR 👑

Johan Vromans (jvromans@squirrel.nl) wrote this module. absolute legend behaviour, we love to see it. 💖

---

📜 COPYRIGHT AND DISCLAIMER 📜

this program is Copyright 2000 by Squirrel Consultancy. all rights reserved.

this program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see either the GNU General Public License or the Artistic License for more details. dramatic but correct. 💅

---

and that's the whole page, bestie — this one shipped in perl v5.36.0, dated 2022-10-13, and it's filed under Dir::Purge(3pm). go forth and purge responsibly, use test first, mwah. 🎀✨🦋