Courie...:Logger(3pm)

💖 Courier::Filter::Logger — the vibe 💖

okay bestie, so you found the manpage for Courier::Filter::Logger, and this one is from the Perl world, running as a 3pm page (that's just how Perl module docs roll). She's the abstract base class for loggers used by the Courier::Filter framework. Abstract means you don't text her directly — you text her kids. Let's get into it. 🦋

---

✨ NAME ✨

Courier::Filter::Logger — the abstract base class for loggers used by the Courier::Filter framework. lowkey the momager of the whole logger family. 👑

---

🌸 SYNOPSIS 🌸

💅 Courier::Filter logging

use Courier::Filter::Logger::My;  # Need to use a non-abstract sub-class.

my $logger = Courier::Filter::Logger::My->new(%options);

# For use in an individual filter module:
my $module = Courier::Filter::Module::My->new(
    ...
    logger => $logger,
    ...
);

# For use as a global Courier::Filter logger object:
my $filter = Courier::Filter->new(
    ...
    logger => $logger,
    ...
);

Not me pointing out you have to use a non-abstract sub-class — the base class itself literally cannot be instantiated, so Courier::Filter::Logger::My or whoever is doing the actual work. 💀 You can hand your logger to one individual filter module (logger => $logger in Courier::Filter::Module::My->new(...)), or make it the global Courier::Filter logger object (logger => $logger in Courier::Filter->new(...)). Either way, same $logger. slay.

🧚 Deriving new logger classes

package Courier::Filter::Logger::My;
use base qw(Courier::Filter::Logger);

That's it, that's the whole inheritance ritual. use base and you're good. ✨

---

💜 DESCRIPTION 💜

So here's the tea: sub-classes of Courier::Filter::Logger get used by the Courier::Filter mail filtering framework and its filter modules, and their whole job is logging errors and message rejections to arbitrary targets — think file handles, databases, wherever. it's giving "flexible logging destination" energy. 🌈

super important bestie: when you override a method in a derived class, do not forget to call the inherited method from your overridden one. no cap. do not skip this.

---

🎀 Constructor

The following constructor is provided, and yeah, you can override it:

• new(%options): returns Courier::Filter::Logger — creates a new logger using the %options you pass as a list of key/value pairs. It initializes said logger by doing the setup stuff: creating/opening I/O handles, connecting to databases, etc. 🫶

Worth knowing: Courier::Filter::Logger::new() creates a hash-ref as an object of the invoked class and stores the %options in it, but does nothing else. that's the whole base-class personality.

---

🌸 Destructor

The following destructor is provided, and yep, overridable:

• destroy — uninitializes the logger: closing I/O handles, disconnecting from databases, etc. 🧹

Courier::Filter::Logger::destroy() does nothing. Sub-classes may override this method and define clean-up behavior. so if you need cleanup, that's on you, bestie.

---

⭐ Instance methods

The following instance methods are provided, and — you guessed it — may be overridden:

• log_error($text) — logs the error message given as $text, a string which may contain newlines. 📝

Courier::Filter::Logger::log_error() does nothing and should be overridden. like, please override it. it's doing nothing on purpose.

• log_rejected_message($message, $reason) — logs the Courier::Message given as $message as having been rejected due to $reason (a string which may contain newlines). 🙈

Courier::Filter::Logger::log_rejected_message() does nothing and should be overridden. same deal. base class is just a silhouette, the sub-class is the main character.

---

🦋 SEE ALSO 🦋

• Courier::Filter
• Courier::Filter::Module

For a list of prepared loggers that come with Courier::Filter, see "Bundled Courier::Filter loggers" in Courier::Filter::Overview.

For AVAILABILITY, SUPPORT, and LICENSE information, see Courier::Filter::Overview.

---

👑 AUTHOR 👑

Julian Mehnle <julian@mehnle.net> — thank you for your service, king. 💖

---

aaaand that's the whole page, bestie! this one shipped with perl v5.34.0 and is dated 2022-10-21. go forth and log responsibly. 🎀✨