.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >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 "Mail::SpamAssassin::ArchiveIterator 3pm"
.TH Mail::SpamAssassin::ArchiveIterator 3pm "2021-03-26" "perl v5.28.1" "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::ArchiveIterator \- find and process messages one at a time
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  my $iter = new Mail::SpamAssassin::ArchiveIterator(
\&    { 
\&      \*(Aqopt_max_size\*(Aq => 256 * 1024,  # 0 implies no limit
\&      \*(Aqopt_cache\*(Aq => 1,
\&    }
\&  );
\&
\&  $iter\->set_functions( \e&wanted, sub { } );
\&
\&  eval { $iter\->run(@ARGV); };
\&
\&  sub wanted {
\&    my($class, $filename, $recv_date, $msg_array) = @_;
\&
\&
\&    ...
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Mail::SpamAssassin::ArchiveIterator module will go through a set
of mbox files, mbx files, and directories (with a single message per
file) and generate a list of messages.  It will then call the \f(CW\*(C`wanted_sub\*(C'\fR
and \f(CW\*(C`result_sub\*(C'\fR functions appropriately per message.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$item = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ] )" 4
.el .IP "\f(CW$item\fR = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ] )" 4
.IX Item "$item = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ] )"
Constructs a new \f(CW\*(C`Mail::SpamAssassin::ArchiveIterator\*(C'\fR object.  You may
pass the following attribute-value pairs to the constructor.  The pairs are
optional unless otherwise noted.
.RS 4
.IP "opt_max_size" 4
.IX Item "opt_max_size"
A value of option \fIopt_max_size\fR determines a limit (number of bytes)
beyond which a message is considered large and is skipped by ArchiveIterator.
.Sp
A value 0 implies no size limit, all messages are examined. An undefined
value implies a default limit of 256 KiB.
.IP "opt_all" 4
.IX Item "opt_all"
Setting this option to true implicitly sets \fIopt_max_size\fR to 0, i.e.
no limit of a message size, all messages are processes by ArchiveIterator.
For compatibility with SpamAssassin versions older than 3.4.0 which
lacked option \fIopt_max_size\fR.
.IP "opt_scanprob" 4
.IX Item "opt_scanprob"
Randomly select messages to scan, with a probability of N, where N ranges
from 0.0 (no messages scanned) to 1.0 (all messages scanned).  Default
is 1.0.
.Sp
This setting can be specified separately for each target.
.IP "opt_before" 4
.IX Item "opt_before"
Only use messages which are received after the given time_t value.
Negative values are an offset from the current time, e.g. \-86400 =
last 24 hours; or as parsed by Time::ParseDate (e.g. '\-6 months')
.Sp
This setting can be specified separately for each target.
.IP "opt_after" 4
.IX Item "opt_after"
Same as opt_before, except the messages are only used if after the given
time_t value.
.Sp
This setting can be specified separately for each target.
.IP "opt_want_date" 4
.IX Item "opt_want_date"
Set to 1 (default) if you want the received date to be filled in
in the \f(CW\*(C`wanted_sub\*(C'\fR callback below.  Set this to 0 to avoid this;
it's a good idea to set this to 0 if you can, as it imposes a performance
hit.
.IP "opt_skip_empty_messages" 4
.IX Item "opt_skip_empty_messages"
Set to 1 if you want to skip corrupt, 0\-byte messages.  The default is 0.
.IP "opt_cache" 4
.IX Item "opt_cache"
Set to 0 (default) if you don't want to use cached information to help speed
up ArchiveIterator.  Set to 1 to enable.  This setting requires \f(CW\*(C`opt_cachedir\*(C'\fR
also be set.
.IP "opt_cachedir" 4
.IX Item "opt_cachedir"
Set to the path of a directory where you wish to store cached information for
\&\f(CW\*(C`opt_cache\*(C'\fR, if you don't want to mix them with the input files (as is the
default).  The directory must be both readable and writable.
.IP "wanted_sub" 4
.IX Item "wanted_sub"
Reference to a subroutine which will process message data.  Usually
set via \fBset_functions()\fR.  The routine will be passed 5 values: class
(scalar), filename (scalar), received date (scalar), message content
(array reference, one message line per element), and the message format
key ('f' for file, 'm' for mbox, 'b' for mbx).
.Sp
Note that if \f(CW\*(C`opt_want_date\*(C'\fR is set to 0, the received date scalar will be
undefined.
.IP "result_sub" 4
.IX Item "result_sub"
Reference to a subroutine which will process the results of the wanted_sub
for each message processed.  Usually set via \fBset_functions()\fR.
The routine will be passed 3 values: class (scalar), result (scalar, returned
from wanted_sub), and received date (scalar).
.Sp
Note that if \f(CW\*(C`opt_want_date\*(C'\fR is set to 0, the received date scalar will be
undefined.
.IP "scan_progress_sub" 4
.IX Item "scan_progress_sub"
Reference to a subroutine which will be called intermittently during
the 'scan' phase of the mass-check.  No guarantees are made as to
how frequently this may happen, mind you.
.IP "opt_from_regex" 4
.IX Item "opt_from_regex"
This setting allows for flexibility in specifying the mbox format From separator.
.Sp
It defaults to the regular expression:
.Sp
/^From \eS+  ?(\eS\eS\eS \eS\eS\eS .?\ed .?\ed:\ed\ed:\ed\ed \ed{4}|.?\ed\-\ed\ed\-\ed{4}_\ed\ed:\ed\ed:\ed\ed_)/
.Sp
Some SpamAssassin programs such as sa-learn will use the configuration option 
\&'mbox_format_from_regex' to override the default regular expression.
.RE
.RS 4
.RE
.IP "set_functions( \e&wanted_sub, \e&result_sub )" 4
.IX Item "set_functions( &wanted_sub, &result_sub )"
Sets the subroutines used for message processing (wanted_sub), and result
reporting.  For more information, see \fI\f(BInew()\fI\fR above.
.ie n .IP "run ( @target_paths )" 4
.el .IP "run ( \f(CW@target_paths\fR )" 4
.IX Item "run ( @target_paths )"
Generates the list of messages to process, then runs each message through the
configured wanted subroutine.  Files which have a name ending in \f(CW\*(C`.gz\*(C'\fR or
\&\f(CW\*(C`.bz2\*(C'\fR will be properly uncompressed via call to \f(CW\*(C`gzip \-dc\*(C'\fR and \f(CW\*(C`bzip2 \-dc\*(C'\fR
respectively.
.Sp
The target_paths array is expected to be either one element per path in the
following format: \f(CW\*(C`class:format:raw_location\*(C'\fR, or a hash reference containing
key-value option pairs and a 'target' key with a value in that format.
.Sp
The key-value option pairs that can be used are: opt_scanprob, opt_after,
opt_before.  See the constructor method's documentation for more information
on their effects.
.Sp
\&\fBrun()\fR returns 0 if there was an error (can't open a file, etc,) and 1 if there
were no errors.
.RS 4
.IP "class" 4
.IX Item "class"
Either 'h' for ham or 's' for spam.  If the class is longer than 1 character,
it will be truncated.  If blank, 'h' is default.
.IP "format" 4
.IX Item "format"
Specifies the format of the raw_location.  \f(CW\*(C`dir\*(C'\fR is a directory whose
files are individual messages, \f(CW\*(C`file\*(C'\fR a file with a single message,
\&\f(CW\*(C`mbox\*(C'\fR an mbox formatted file, or \f(CW\*(C`mbx\*(C'\fR for an mbx formatted directory.
.Sp
\&\f(CW\*(C`detect\*(C'\fR can also be used.  This assumes \f(CW\*(C`mbox\*(C'\fR for any file whose path
contains the pattern \f(CW\*(C`/\e.mbox/i\*(C'\fR, \f(CW\*(C`file\*(C'\fR anything that is not a
directory, or \f(CW\*(C`directory\*(C'\fR otherwise.
.IP "raw_location" 4
.IX Item "raw_location"
Path to file or directory.  File globbing is allowed using the
standard csh-style globbing (see \f(CW\*(C`perldoc \-f glob\*(C'\fR).  \f(CW\*(C`~\*(C'\fR at the
front of the value will be replaced by the \f(CW\*(C`HOME\*(C'\fR environment
variable.  Escaped whitespace is protected as well.
.Sp
\&\fB\s-1NOTE:\s0\fR \f(CW\*(C`~user\*(C'\fR is not allowed.
.Sp
\&\fB\s-1NOTE 2:\s0\fR \f(CW\*(C`\-\*(C'\fR is not allowed as a raw location.  To have
ArchiveIterator deal with \s-1STDIN,\s0 generate a temp file.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CW\*(C`Mail::SpamAssassin\*(C'\fR
\&\f(CW\*(C`spamassassin\*(C'\fR
\&\f(CW\*(C`mass\-check\*(C'\fR