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 separator.

               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"