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,
        }
      );

      $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).

        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.

        wanted_sub
            Reference to a subroutine which will process message data.
            Usually set via set_functions(). The routine will be passed 4
            values: class (scalar), filename (scalar), received date
            (scalar), and message content (array reference, one message line
            per element).

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

    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

        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; assumes "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.

SEE ALSO
    "Mail::SpamAssassin" "spamassassin" "mass-check"