Mail::SpamAssassin::ArchiveIterator(3ser Contributed Perl Documentatiil::SpamAssassin::ArchiveIterator(3)
NAME
Mail::SpamAssassin::ArchiveIterator - find and process messages one at a time
SYNOPSIS
my $iter = new Mail::SpamAssassin::ArchiveIterator(
{
'opt_all' => 1,
'opt_cache' => 1,
}
);
$iter->set_functions( \&wanted, sub { } );
eval { $iter->run(@ARGV); };
sub wanted {
my($class, $filename, $recv_date, $msg_array) = @_;
...
}
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
wanted and results functions appropriately per message.
METHODS
$item = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ] )
Constructs a new "Mail::SpamAssassin::ArchiveIterator" object. You may pass the following
attribute-value pairs to the constructor. The pairs are optional unless otherwise noted.
opt_all
Typically messages over 250k are skipped by ArchiveIterator. Use this option to keep from
skipping messages based on size.
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.
This setting can be specified separately for each target.
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')
This setting can be specified separately for each target.
opt_after
Same as opt_before, except the messages are only used if after the given time_t value.
This setting can be specified separately for each target.
opt_want_date
Set to 1 (default) if you want the received date to be filled in in the "wanted_sub" 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.
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 "opt_cachedir" also be set.
opt_cachedir
Set to the path of a directory where you wish to store cached information for "opt_cache", if
you don't want to mix them with the input files (as is the default). The directory must be
both readable and writable.
wanted_sub
Reference to a subroutine which will process message data. Usually set via set_functions().
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).
Note that if "opt_want_date" is set to 0, the received date scalar will be undefined.
result_sub
Reference to a subroutine which will process the results of the wanted_sub for each message
processed. Usually set via set_functions(). The routine will be passed 3 values: class
(scalar), result (scalar, returned from wanted_sub), and received date (scalar).
Note that if "opt_want_date" is set to 0, the received date scalar will be undefined.
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.
set_functions( \&wanted_sub, \&result_sub )
Sets the subroutines used for message processing (wanted_sub), and result reporting. For more
information, see new() above.
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 ".gz" or ".bz2" will be properly uncompressed via
call to "gzip -dc" and "bzip2 -dc" respectively.
The target_paths array is expected to be either one element per path in the following format:
"class:format:raw_location", or a hash reference containing key-value option pairs and a 'target'
key with a value in that format.
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.
run() returns 0 if there was an error (can't open a file, etc,) and 1 if there were no errors.
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.
format
Specifies the format of the raw_location. "dir" is a directory whose files are individual
messages, "file" a file with a single message, "mbox" an mbox formatted file, or "mbx" for an
mbx formatted directory.
"detect" can also be used. This assumes "mbox" for any file whose path contains the pattern
"/\.mbox/i", "file" anything that is not a directory, or "directory" otherwise.
raw_location
Path to file or directory. File globbing is allowed using the standard csh-style globbing
(see "perldoc -f glob"). "~" at the front of the value will be replaced by the "HOME"
environment variable. Escaped whitespace is protected as well.
NOTE: "~user" is not allowed.
NOTE 2: "-" is not allowed as a raw location. To have ArchiveIterator deal with STDIN,
generate a temp file.
SEE ALSO
"Mail::SpamAssassin" "spamassassin" "mass-check"
perl v5.8.8 2007-05-21 Mail::SpamAssassin::ArchiveIterator(3)
|