Index for Section 3

Alphabetical listing for M

Bottom of page

Mail::SpamAssassin::ArUcsheirveCIotnetraitbourt(e3d)PeMralilD:o:cSupmaemnAtsastaisosnin::ArchiveIterator(3)
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"

Index for Section 3

Alphabetical listing for M

Top of page