Badger...g::File(3pm)

💖 Badger::Log::File(3pm) — the User Contributed Perl Documentation moment ✨

okay bestie, gather round, because this is the manual page for Badger::Log::File and it is genuinely so cute and useful. it's a Perl thing, it lives in the User Contributed Perl Documentation corner of your system, and it's here to help you write log messages to a file. slay. 💅

---

🌸 NAME 🌸

Badger::Log::File — writes log messages to a log file. that's it, that's the whole vibe. 📝

---

✨ SYNOPSIS ✨

here's the whole thing in action, bestie:

use Badger::Log::File;

my $log = Badger::Log::File->new({
    filename  => '/var/log/badger.log',
    keep_open => 1,
});

$log->log('a debug message');
$log->info('an info message');
$log->warn('a warning message');
$log->error('an error message');
$log->fatal('a fatal error message');

see how easy that is?? you make a log, you throw messages at it, it writes them to a file. iconic behaviour, no cap. 🔥

---

🦋 DESCRIPTION 🦋

so Badger::Log::File is a subclass of Badger::Log, and what it adds is a nice simple mechanism for logging messages to a file. that's the whole job. it uses Badger::Filesystem under the hood for literally all of the underlying file operations, so the file-handling heavy lifting is not its problem, and honestly? good for it. 💖

---

🎀 CONFIGURATION OPTIONS 🎀

these are the config options you get, on top of everything it inherits from the Badger::Log base class. base class options are still there, don't forget about them, they're doing main character work in the background. 💜

🌈 filename

the name of the log file you want messages appended to. either this one or the filename_format option must be provided — you can't have neither, bestie, the module needs to know where to put your words. 🫶

🍓 filename_format

a format that gets used to generate a filename to write messages to. it can include any of the strftime() character sequences, like %Y for the four digit year, %m for a two digit month number, %d for a two digit day of the month, etc.

my $log = Badger::Log::File->new({
    filename_format  => '/var/log/badger-%Y-%m-%d.log',
    keep_open => 1,
});

and okay, if you're like the author and you find it hard to remember the strftime() character sequences (real, honestly, who can), there's an alternate format where the elements of the date and/or time are encoded as upper case words embedded in angle brackets. e.g. "badger-<DATE>.log", or "badger-<YEAR>-<MONTH>.log". so much more readable, we love to see it. 😭

the words you can embed this way, plus their matching strftime() character sequences, are:

DATE    => '%Y-%m-%d'       # e.g. 2022-08-24
TIME    => '%H-%M-%S'       # e.g. 13:54:07
YEAR    => '%Y'             # e.g. 2022
MONTH   => '%m'             # e.g. 08
DAY     => '%d'             # e.g. 24
HOURS   => '%H'             # e.g. 13
MINUTES => '%M'             # e.g. 54
SECONDS => '%S'             # e.g. 07

and the module will automatically create a new logfile when the filename_format generates a filename that's different from any previous value. so if the day rolls over, boom, new file. automatic. obsessed. ✨

🧚 filesystem

an optional reference to a Badger::Filesystem object, or the name of a filesystem class that has a file() method similar to the one in Badger::Filesystem. this defaults to the Badger::Filesystem class. 🦋

👑 keep_open

a flag saying whether the log file should be kept open between calls to the logging methods. the default value is 0, which means the file gets opened for each message and closed again afterwards. set it to any true value and the file stays open. your call, bestie, both are valid. 💅

---

💜 METHODS 💜

these are the methods implemented on top of everything inherited from Badger::Log and its base classes.

⭐ log($level,$message)

this method redefines the log() method in Badger::Log so it writes logging messages to the log file. that's the whole glow-up right there. 🔥

---

🔮 INTERNAL METHODS 🔮

okay so these are the internal ones — you can look, but this is backstage, this is the green room, this is where the module does its own thing. 🙈

🌸 init(\%config)

a custom initialiser method that calls the base class init_log() method, and then follows up with the init_file() method. 📋

💖 init_file(\%config)

a custom initialiser method that handles the configuration and initialisation of the file-specific parts of the logger. the file-y bits, basically. 🗂️

🎀 expand_filename()

expands the format defined by the filename_format configuration option into an actual filename, using the current date and time. 🕰️

if filename_format hasn't been specified, then it just returns the value of the filename configuration option instead. easy. ✨

🦋 filename_changed()

calls expand_filename() to expand any filename_format, and compares it to the current filename (which may have been generated by a previous call to this very method).

if they're the same, it returns undef. otherwise it saves the new filename to the internal filename value and returns it. so like, it's the vibe check for "is this a new file or not". 💅

🍓 file()

returns a reference to a Badger::Filesystem::File object based on the filename — which can either be defined as a static configuration option, or will be generated by the expand_filename() method from the filename_format configuration option. either way, you get a file object. 🫶

🧚 filehandle()

returns a filehandle for the current logfile. if the filename has changed since the last call to this method — which it figures out by calling filename_changed() — then any existing filehandle gets closed (by calling release()) and the new file is opened so it can return a new filehandle (by calling acquire()). out with the old, in with the new. 🌈

👑 acquire()

this method acquires a file handle (an IO::File object) for the specified filename, opened up ready for appending log messages. 📎

💜 release()

this method releases a previously acquired file handle. i.e. it closes the log file. bye bestie, see you next log message. 👋

---

🌟 AUTHOR 🌟

Andy Wardley <http://wardley.org/> — legend behaviour, honestly. 💖

---

⭐ COPYRIGHT ⭐

Copyright (C) 2005-2022 Andy Wardley. All Rights Reserved.

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

---

🌈 SEE ALSO 🌈

• Badger::Log — the parent, the blueprint, the origin story. go read it, iykyk. 💜

---

and that's the whole page, bestie!! this one was shipped as part of perl v5.36.0, dated 2023-08-28, in the classic Badger...g::File(3pm) style. go forth and log your little heart out. 🎀✨🦋💅