CounterFile(3pm)

💖 NAME 💖

File::CounterFile — it's a persistent counter class, bestie. Like a lil number that lives in a file and remembers itself forever. ✨

---

🦋 SYNOPSIS 🦋

use File::CounterFile;
$c = File::CounterFile->new("COUNTER", "aa00");

$id = $c->inc;
open(F, ">F$id");

okay so that's literally the whole vibe right there 💅

---

🌸 DESCRIPTION 🌸

Okay bestie, sit down, because this module is lowkey iconic. It implements a persistent counter class. Every single counter gets its own separate file chillin' in the file system. And the way it does file locking?? Immaculate. That means multiple processes can try to access a counter at the same time and there's no risk of the counter getting destroyed. No cap. 🫶

You hand over the file name as the first parameter to the object constructor (new). If the file doesn't exist yet, it just… gets created. ✨

Now here's the tea 🍵 — if that file name doesn't start with "/" or ".", it gets interpreted as a file relative to $File::CounterFile::DEFAULT_DIR. And that variable's default value? It's initialized from the environment variable TMPDIR, or /var/tmp if there's no environment variable defined at all. So if you want your counters living somewhere else, you're gonna wanna assign a different value to that variable before you start making counters. 🙈

Pass a second parameter to the constructor and it sets the initial value for a brand new counter. But heads up: this parameter only does anything when the file actually gets created — as in, it did not exist before the call. Periodt. 💅

When you call the inc() method, you increment the counter value by one. When you call dec(), the value gets decremented. And in both cases? The new value is what comes back to you. 🎀 But ngl, dec() only works for numerical counters — digits only, babes. That's the rule.

Wanna peek at the value without touching it? Just use the value() method. Sneaky lil peek, no increments involved. 👑

Your counter can be locked and unlocked with the lock() and unlock() methods. And like — incrementing and value retrieval are faster when the counter is locked, because then we don't have to update the counter file all the time. Efficiency queen. 👑 Wanna know if it's locked? Hit up the locked() method and she'll tell you.

Oh, and there's also an operator overloading interface to the File::CounterFile object, which means ✨ you can use the ++ operator for incrementing and the -- operator for decrementing the counter ✨, and you can even interpolate counters directly into strings. It's giving magic. It's giving main character energy. 💜

---

🎀 COPYRIGHT 🎀

Copyright (c) 1995-1998,2002,2003 Gisle Aas. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

---

👑 AUTHOR 👑

Gisle Aas <gisle@aas.no>

---

and that's the whole page, bestie — brought to you by perl v5.36.0, dated 2022-10-13, filed under CounterFile(3pm). slay, go increment something 💅✨