NAME Mail::SpamAssassin::ArchiveIterator - find and process messages one at a time SYNOPSIS my $iter = new Mail::SpamAssassin::ArchiveIterator( { 'opt_j' => 0, 'opt_n' => 1, '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_j (required) Specifies how many messages should be run at the same time, as well as the method with which to scan for the messages. If the value is 0, the list of messages to process will be kept in memory, and only 1 message at a time will be processed by the wanted subroutine. Restarting is not allowed. If the value is 1, the list of messages to process will be kept in a temporary file, and only 1 message at a time will be processed by the wanted subroutine. Restarting is not allowed. If the value is 2 or higher, the list of messages to process will be kept in a temporary file, and the process will split into a parent/child mode. The option value number of children will be forked off and each child will process messages via the wanted subroutine in parallel. Restarting is allowed. NOTE: For "opt_j" >= 1, an extra child process will be created to determine the list of messages, sort the list, everything as appropriate. This will keep the list in memory (possibly multiple copies) before writing the final list to a temporary file which will be used for processing. The list generation child will exit, freeing up the memory. opt_n ArchiveIterator is typically used to simulate ham and spam moving through SpamAssassin. By default, the list of messages is sorted by received date so that the mails can be passed through in order. If opt_n is true, the sorting will not occur. This is useful if you don't care about the order of the messages. opt_restart If set to a positive integer value, children processes (see opt_j w/ value 2 or higher above) will restart after the option value number of messages, in total, have been processed. opt_head Only use the first N ham and N spam (or if the value is -N, only use the first N total messages regardless of class). opt_tail Only use the last N ham and N spam (or if the value is -N, only use the last N total messages regardless of class). If both "opt_head" and "opt_tail" are specified, then the "opt_head" value specifies a subset of the "opt_tail" selection to use; in other words, the "opt_tail" splice is applied first. 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') opt_after Same as opt_before, except the messages are only used if after the given time_t value. 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. 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 one element per path in the following format: class:format:raw_location 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" for STDIN and anything that is not a directory, or "directory" otherwise. raw_location Path to file or directory. Can be "-" for STDIN. 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. SEE ALSO "Mail::SpamAssassin" "spamassassin" "mass-check"