NAME¶
Mail::SpamAssassin::ArchiveIterator - find and process messages one at a time
SYNOPSIS¶
my $iter = new Mail::SpamAssassin::ArchiveIterator(
{
'opt_max_size' => 256 * 1024, # 0 implies no limit
'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_sub" and
"result_sub" 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_max_size
- A value of option opt_max_size determines a limit
(number of bytes) beyond which a message is considered large and is
skipped by ArchiveIterator.
A value 0 implies no size limit, all messages are examined. An undefined
value implies a default limit of 256 KiB.
- opt_all
- Setting this option to true implicitly sets
opt_max_size 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 opt_max_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_skip_empty_messages
- Set to 1 if you want to skip corrupt, 0-byte messages. The
default is 0.
- 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.
- opt_from_regex
- This setting allows for flexibility in specifying the mbox
format From seperator.
It defaults to the regular expression:
/^From \S+ ?(\S\S\S \S\S\S .\d .\d:\d\d:\d\d
\d{4}|.\d-\d\d-\d{4}_\d\d:\d\d:\d\d_)/
Some SpamAssassin programs such as sa-learn will use the configuration
option 'mbox_format_from_regex' to override the default regular
expression.
- 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"