Ubuntu Manpage: Courier::Filter::Module - Abstract Perl base class for filter modules used by the Courier::Filter

Provided by: courier-filter-perl_0.200+ds-4_all

NAME

       Courier::Filter::Module - Abstract Perl base class for filter modules used by the Courier::Filter
       framework

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

Sub-classes of Courier::Filter::Module are used by the Courier::Filter mail filtering framework to
determine the acceptability of messages. See Courier::Filter::Overview for an overview of how filter
modules are used and for how to write them.

When overriding a method in a derived class, do not forget calling the inherited method from your
overridden method.

Constructor
The following constructor is provided and may be overridden:

new(%options): returns Courier::Filter::Module
Creates a new filter module using the %options. Initializes the filter module, by 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 no logger is specified, Courier::Filter's
global logger will be used.

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
is negated by the "consider" method before returning it. For details on how Courier::Filter
translates match results into acceptability results, see "How filter modules work" in
Courier::Filter::Overview. Defaults to false.

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.

debugging
A boolean value controlling whether the filter module should log extra debugging information.
Defaults to false.

Derived classes may support additional options.

"Courier::Filter::Module::new()" creates a hashref as an object of the invoked class, and stores the
%options in it, but does nothing else.

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.

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.

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.

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.

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.

AUTHOR

       Julian Mehnle <julian@mehnle.net>

perl v5.20.2                                       2015-11-28                       Courier::Filter::Module(3pm)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR