.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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 "Mail::SpamAssassin::PersistentAddrList 3"
.TH Mail::SpamAssassin::PersistentAddrList 3 "2015-04-29" "perl v5.16.3" "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"
Mail::SpamAssassin::PersistentAddrList \- persistent address list base class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  my $factory = PersistentAddrListSubclass\->new();
\&  $spamtest\->set_persistent_addr_list_factory ($factory);
\&  ... call into SpamAssassin classes...
.Ve
.PP
SpamAssassin will call:
.PP
.Vb 3
\&  my $addrlist = $factory\->new_checker($spamtest);
\&  $entry = $addrlist\->get_addr_entry ($addr);
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
All persistent address list implementations, used by the auto-whitelist
code to track known-good email addresses, use this as a base class.
.PP
See \f(CW\*(C`Mail::SpamAssassin::DBBasedAddrList\*(C'\fR for an example.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$factory = PersistentAddrListSubclass\->\fInew()\fR;" 4
.el .IP "\f(CW$factory\fR = PersistentAddrListSubclass\->\fInew()\fR;" 4
.IX Item "$factory = PersistentAddrListSubclass->new();"
This creates a factory object, which SpamAssassin will call to create
a new checker object for the persistent address list.
.ie n .IP "my $addrlist = $factory\->\fInew_checker()\fR;" 4
.el .IP "my \f(CW$addrlist\fR = \f(CW$factory\fR\->\fInew_checker()\fR;" 4
.IX Item "my $addrlist = $factory->new_checker();"
Create a new address-list checker object from the factory. Called by the
SpamAssassin classes.
.ie n .IP "$entry = $addrlist\->get_addr_entry ($addr);" 4
.el .IP "\f(CW$entry\fR = \f(CW$addrlist\fR\->get_addr_entry ($addr);" 4
.IX Item "$entry = $addrlist->get_addr_entry ($addr);"
Given an email address \f(CW$addr\fR, return an entry object with the details of
that address.
.Sp
The entry object is a reference to a hash, which must contain at least
two keys: \f(CW\*(C`count\*(C'\fR, which is the count of times that address has been
encountered before; and \f(CW\*(C`totscore\*(C'\fR, which is the total of all scores for
messages associated with that address.  From these two fields, an average
score will be calculated, and the score for the current message will be
regressed towards that mean message score.
.Sp
The hash can contain whatever other data your back-end needs to store,
under other keys.
.Sp
The method should never return \f(CW\*(C`undef\*(C'\fR, or a hash that does not contain
a \f(CW\*(C`count\*(C'\fR key and a \f(CW\*(C`totscore\*(C'\fR key.
.ie n .IP "$entry = $addrlist\->add_score($entry, $score);" 4
.el .IP "\f(CW$entry\fR = \f(CW$addrlist\fR\->add_score($entry, \f(CW$score\fR);" 4
.IX Item "$entry = $addrlist->add_score($entry, $score);"
This method should add the given score to the whitelist database for the
given entry, and then return the new entry.
.ie n .IP "$entry = $addrlist\->remove_entry ($entry);" 4
.el .IP "\f(CW$entry\fR = \f(CW$addrlist\fR\->remove_entry ($entry);" 4
.IX Item "$entry = $addrlist->remove_entry ($entry);"
This method should remove the given entry from the whitelist database.
.ie n .IP "$entry = $addrlist\->finish ();" 4
.el .IP "\f(CW$entry\fR = \f(CW$addrlist\fR\->finish ();" 4
.IX Item "$entry = $addrlist->finish ();"
Clean up, if necessary.  Called by SpamAssassin when it has finished
checking, or adding to, the auto-whitelist database.