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.

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>