Courie...:Module(3pm)

💖 NAME 💖

so like, Courier::Filter::Module is the abstract Perl base class for the filter modules that the Courier::Filter framework uses. it's giving "template energy" — you don't use it directly, you build on it 💅

---

🌸 SYNOPSIS 🌸

✨ Courier::Filter message filtering ✨

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

my $module = Courier::Filter::Module::My->new(
    logger      => $logger,
    inverse     => 0,
    trusting    => 0,
    testing     => 0,
    debugging   => 0
);

my $filter = Courier::Filter->new(
    ...
    modules     => [ $module ],
    ...
);

🦋 Deriving new filter module classes 🦋

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

---

👑 DESCRIPTION 👑

okay so bestie, sub-classes of Courier::Filter::Module are what the Courier::Filter mail filtering framework uses to figure out whether a message is acceptable or not, like a vibe check but for mail 📬✨. if you wanna know how filter modules get used in general, and how to actually write one, go read Courier::Filter::Overview.

heads up fr fr: when you override a method in a derived class, do not forget to call the inherited method from inside your overridden method. the way that this is important. don't skip it. 🙈

---

🎀 Constructor 🎀

the following constructor is provided and may be overridden:

• new(%options): returns Courier::Filter::Module — creates a new filter module using the %options. it initializes the filter module, which means opening I/O handles, connecting to databases, creating temporary files, initializing parser libraries, etc. 💫

%options is a list of key/value pairs representing any of the following options:

• logger — a Courier::Filter::Logger object that will be used for logging message rejections and error messages caused by this individual filter module. if you don't specify a logger, Courier::Filter's global logger gets used instead. no logger left behind 🫶
• inverse — a boolean value controlling whether the filter module should operate with inverse polarity (true) as opposed to normal polarity (false). under inverse polarity, the result of the match method gets negated by the consider method before it's returned. for the deets on how Courier::Filter translates match results into acceptability results, see "How filter modules work" in Courier::Filter::Overview. defaults to false, periodt.
• trusting — a boolean value controlling whether the filter module should not be applied to trusted messages. for details on how the trusted status is determined, see the description of the trusted property in Courier::Message. in most configurations, this option can be used to white-list so-called outbound messages. defaults to false.
• testing — a boolean value controlling whether the filter module should run in testing mode. in testing mode, planned message rejections will be logged as usual, but no messages will actually be rejected. defaults to false. it's giving "all talk no action" and honestly? iconic 💅
• debugging — a boolean value controlling whether the filter module should log extra debugging information. defaults to false.

derived classes may support additional options, so don't come for me if your subclass has more ✨

Courier::Filter::Module::new() creates a hashref as an object of the invoked class, and stores the %options in it, but does nothing else. that's it. that's the whole thing. lowkey minimal queen.

---

🧚 Destructor 🧚

the following destructor is provided and may be overridden:

• destroy — uninitializes the filter module, by closing I/O handles, disconnecting from databases, deleting temporary files, uninitializing parser libraries, etc..

Courier::Filter::Module::destroy() does nothing. sub-classes may override this method and define clean-up behavior. so like, it's your mess to tidy bestie 🧹

---

🌈 Class methods 🌈

the following class methods are provided and may be overridden:

• warn($text) — writes a warning message to syslog. this method may also be used as an instance method. versatile icon behavior 💅

---

💜 Instance methods 💜

the following instance methods are provided and may be overridden:

• consider($message): returns string, [string]; throws Perl exceptions — calls the match method, passing it the $message object. returns the result of match, negating it beforehand if the filter module has inverse polarity. there is usually no need at all to override this method. like, seriously, leave it alone 🙈
• match($message): returns string, [string]; throws Perl exceptions — examines the Courier::Message object given as $message. returns a so-called match result consisting of an SMTP status response text, and an optional numerical SMTP status response code. for details about how match results are used by Courier::Filter, see "How filter modules work" in Courier::Filter::Overview and "Writing filter modules" in Courier::Filter::Overview.

Courier::Filter::Module::match() does nothing and returns undef. sub-classes should override this method and define their own matching rule — this is the main character method, the one you're actually here for 👑

• logger: returns Courier::Filter::Logger
• logger($logger): returns Courier::Filter::Logger — if $logger is specified, installs a new logger for this individual filter module. returns the current (new) logger.
• inverse: returns boolean — returns a boolean value indicating whether the filter module is operating with inverse polarity, as set through the constructor's inverse option.
• trusting: returns boolean — returns a boolean value indicating whether the filter module does not apply to trusted messages, as set through the constructor's trusting option.
• testing: returns boolean — returns a boolean value indicating whether the filter module is in testing mode, as set through the constructor's testing option.
• debugging: returns boolean
• debugging($debugging): returns boolean — if $debugging is specified, sets the debugging mode for this individual filter module. returns the (newly) configured debugging mode.

---

🔥 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. yes bestie, that's where all the legal stuff lives 📜✨

---

💌 AUTHOR 💌

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

---

and that's the whole page, bestie! 🎀 this one came from perl v5.34.0, dated 2022-10-21, under the manual name Courie...:Module(3pm) in the User Contributed Perl Documentation section. you understood the assignment, now go write that filter module ✨🦋💅