.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Filter 3"
.TH Filter 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Log::Log4perl::Filter \- Log4perl Custom Filter Base Class
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Log::Log4perl;
\&
\&  Log::Log4perl\->init(\e <<\*(AqEOT\*(Aq);
\&    log4perl.logger = INFO, Screen
\&    log4perl.filter.MyFilter        = sub { /let this through/ }
\&    log4perl.appender.Screen        = Log::Log4perl::Appender::Screen
\&    log4perl.appender.Screen.Filter = MyFilter
\&    log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
\&  EOT
\&
\&      # Define a logger
\&  my $logger = Log::Log4perl\->get_logger("Some");
\&
\&      # Let this through
\&  $logger\->info("Here\*(Aqs the info, let this through!");
\&
\&      # Suppress this
\&  $logger\->info("Here\*(Aqs the info, suppress this!");
\&
\&  #################################################################
\&  # StringMatch Filter:
\&  #################################################################
\&  log4perl.filter.M1               = Log::Log4perl::Filter::StringMatch
\&  log4perl.filter.M1.StringToMatch = let this through
\&  log4perl.filter.M1.AcceptOnMatch = true
\&
\&  #################################################################
\&  # LevelMatch Filter:
\&  #################################################################
\&  log4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch
\&  log4perl.filter.M1.LevelToMatch  = INFO
\&  log4perl.filter.M1.AcceptOnMatch = true
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Log4perl allows the use of customized filters in its appenders
to control the output of messages. These filters might grep for
certain text chunks in a message, verify that its priority
matches or exceeds a certain level or that this is the 10th
time the same message has been submitted \-\- and come to a log/no log 
decision based upon these circumstantial facts.
.PP
Filters have names and can be specified in two different ways in the Log4perl
configuration file: As subroutines or as filter classes. Here's a 
simple filter named \f(CW\*(C`MyFilter\*(C'\fR which just verifies that the 
oncoming message matches the regular expression \f(CW\*(C`/let this through/i\*(C'\fR:
.PP
.Vb 1
\&    log4perl.filter.MyFilter        = sub { /let this through/i }
.Ve
.PP
It exploits the fact that when the subroutine defined
above is called on a message,
Perl's special \f(CW$_\fR variable will be set to the message text (prerendered,
i.e. concatenated but not layouted) to be logged. 
The subroutine is expected to return a true value 
if it wants the message to be logged or a false value if doesn't.
.PP
Also, Log::Log4perl will pass a hash to the subroutine,
containing all key/value pairs that it would pass to the corresponding 
appender, as specified in Log::Log4perl::Appender. Here's an
example of a filter checking the priority of the oncoming message:
.PP
.Vb 8
\&  log4perl.filter.MyFilter        = sub {    \e
\&       my %p = @_;                           \e
\&       if($p{log4p_level} eq "WARN" or       \e
\&          $p{log4p_level} eq "INFO") {       \e
\&           return 1;                         \e
\&       }                                     \e
\&       return 0;                             \e
\&  }
.Ve
.PP
If the message priority equals \f(CW\*(C`WARN\*(C'\fR or \f(CW\*(C`INFO\*(C'\fR, 
it returns a true value, causing
the message to be logged.
.SS "Predefined Filters"
.IX Subsection "Predefined Filters"
For common tasks like verifying that the message priority matches
a certain priority, there's already a 
set of predefined filters available. To perform an exact level match, it's
much cleaner to use Log4perl's \f(CW\*(C`LevelMatch\*(C'\fR filter instead:
.PP
.Vb 3
\&  log4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch
\&  log4perl.filter.M1.LevelToMatch  = INFO
\&  log4perl.filter.M1.AcceptOnMatch = true
.Ve
.PP
This will let the message through if its priority is INFO and suppress
it otherwise. The statement can be negated by saying
.PP
.Vb 1
\&  log4perl.filter.M1.AcceptOnMatch = false
.Ve
.PP
instead. This way, the message will be logged if its priority is
anything but INFO.
.PP
On a similar note, Log4perl's \f(CW\*(C`StringMatch\*(C'\fR filter will check the 
oncoming message for strings or regular expressions:
.PP
.Vb 3
\&  log4perl.filter.M1               = Log::Log4perl::Filter::StringMatch
\&  log4perl.filter.M1.StringToMatch = bl.. bl..
\&  log4perl.filter.M1.AcceptOnMatch = true
.Ve
.PP
This will open the gate for messages like \f(CW\*(C`blah blah\*(C'\fR because the 
regular expression in the \f(CW\*(C`StringToMatch\*(C'\fR matches them. Again,
the setting of \f(CW\*(C`AcceptOnMatch\*(C'\fR determines if the filter is defined
in a positive or negative way.
.PP
All class filter entries in the configuration file
have to adhere to the following rule:
Only after a filter has been defined by name and class/subroutine,
its attribute values can be
assigned, just like the \f(CW\*(C`true\*(C'\fR value above gets assigned to the
\&\f(CW\*(C`AcceptOnMatch\*(C'\fR attribute \fIafter\fR the
filter \f(CW\*(C`M1\*(C'\fR has been defined.
.SS "Attaching a filter to an appender"
.IX Subsection "Attaching a filter to an appender"
Attaching a filter to an appender is as easy as assigning its name to
the appender's \f(CW\*(C`Filter\*(C'\fR attribute:
.PP
.Vb 1
\&    log4perl.appender.MyAppender.Filter = MyFilter
.Ve
.PP
This will cause \f(CW\*(C`Log::Log4perl\*(C'\fR to call the filter subroutine/method
every time a message is supposed to be passed to the appender. Depending
on the filter's return value, \f(CW\*(C`Log::Log4perl\*(C'\fR will either continue as
planned or withdraw immediately.
.SS "Combining filters with Log::Log4perl::Filter::Boolean"
.IX Subsection "Combining filters with Log::Log4perl::Filter::Boolean"
Sometimes, it's useful to combine the output of various filters to
arrive at a log/no log decision. While Log4j, Log4perl's mother ship,
has chosen to implement this feature as a filter chain, similar to Linux' IP chains,
Log4perl tries a different approach.
.PP
Typically, filter results will not need to be bumped along chains but 
combined in a programmatic manner using boolean logic. "Log if
this filter says 'yes' and that filter says 'no'" 
is a fairly common requirement, but hard to implement as a chain.
.PP
\&\f(CW\*(C`Log::Log4perl::Filter::Boolean\*(C'\fR is a specially predefined custom filter
for Log4perl. It combines the results of other custom filters 
in arbitrary ways, using boolean expressions:
.PP
.Vb 1
\&    log4perl.logger = WARN, AppWarn, AppError
\&
\&    log4perl.filter.Match1       = sub { /let this through/ }
\&    log4perl.filter.Match2       = sub { /and that, too/ }
\&    log4perl.filter.MyBoolean       = Log::Log4perl::Filter::Boolean
\&    log4perl.filter.MyBoolean.logic = Match1 || Match2
\&
\&    log4perl.appender.Screen        = Log::Log4perl::Appender::Screen
\&    log4perl.appender.Screen.Filter = MyBoolean
\&    log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
.Ve
.PP
\&\f(CW\*(C`Log::Log4perl::Filter::Boolean\*(C'\fR's boolean expressions allow for combining
different appenders by name using AND (&& or &), OR (|| or |) and NOT (!) as
logical expressions. Also, parentheses can be used for defining precedences. 
Operator precedence follows standard Perl conventions. Here's a bunch of examples:
.PP
.Vb 3
\&    Match1 && !Match2            # Match1 and not Match2
\&    !(Match1 || Match2)          # Neither Match1 nor Match2
\&    (Match1 && Match2) || Match3 # Both Match1 and Match2 or Match3
.Ve
.SS "Writing your own filter classes"
.IX Subsection "Writing your own filter classes"
If none of Log::Log4perl's predefined filter classes fits your needs,
you can easily roll your own: Just define a new class,
derive it from the baseclass \f(CW\*(C`Log::Log4perl::Filter\*(C'\fR,
and define its \f(CW\*(C`new\*(C'\fR and \f(CW\*(C`ok\*(C'\fR methods like this:
.PP
.Vb 1
\&    package Log::Log4perl::Filter::MyFilter;
\&
\&    use base Log::Log4perl::Filter;
\&
\&    sub new {
\&        my ($class, %options) = @_;
\&
\&        my $self = { %options,
\&                   };
\&     
\&        bless $self, $class;
\&
\&        return $self;
\&    }
\&
\&    sub ok {
\&         my ($self, %p) = @_;
\&
\&         # ... decide and return 1 or 0
\&    }
\&
\&    1;
.Ve
.PP
Log4perl will call the \fBok()\fR method to determine if the filter
should let the message pass or not. A true return value indicates
the message will be logged by the appender, a false value blocks it.
.PP
Values you've defined for its attributes in Log4perl's configuration file,
will be received through its \f(CW\*(C`new\*(C'\fR method:
.PP
.Vb 2
\&    log4perl.filter.MyFilter       = Log::Log4perl::Filter::MyFilter
\&    log4perl.filter.MyFilter.color = red
.Ve
.PP
will cause \f(CW\*(C`Log::Log4perl::Filter::MyFilter\*(C'\fR's constructor to be called
like this:
.PP
.Vb 2
\&    Log::Log4perl::Filter::MyFilter\->new( name  => "MyFilter",
\&                                          color => "red" );
.Ve
.PP
The custom filter class should use this to set the object's attributes, 
to have them available later to base log/nolog decisions on it.
.PP
\&\f(CWok()\fR is the filter's method to tell if it agrees or disagrees with logging
the message. It will be called by Log::Log4perl whenever it needs the
filter to decide. A false value returned by \f(CWok()\fR will block messages,
a true value will let them through.
.SS "A Practical Example: Level Matching"
.IX Subsection "A Practical Example: Level Matching"
See Log::Log4perl::FAQ for this.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Log4perl::Filter::LevelMatch,
Log::Log4perl::Filter::LevelRange,
Log::Log4perl::Filter::StringRange,
Log::Log4perl::Filter::Boolean
.SH LICENSE
.IX Header "LICENSE"
Copyright 2002\-2013 by Mike Schilli <m@perlmeister.com> 
and Kevin Goess <cpan@goess.org>.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH AUTHOR
.IX Header "AUTHOR"
Please contribute patches to the project on Github:
.PP
.Vb 1
\&    http://github.com/mschilli/log4perl
.Ve
.PP
Send bug reports or requests for enhancements to the authors via our
.PP
MAILING LIST (questions, bug reports, suggestions/patches): 
log4perl\-devel@lists.sourceforge.net
.PP
Authors (please contact them via the list above, not directly):
Mike Schilli <m@perlmeister.com>,
Kevin Goess <cpan@goess.org>
.PP
Contributors (in alphabetical order):
Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp, Hutton
Davidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, Anthony
Foiani, James FitzGibbon, Carl Franks, Dennis Gregorovic, Andy
Grundman, Paul Harrington, Alexander Hartmaier  David Hull, 
Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, 
Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, 
Lars Thegler, David Viner, Mac Yang.