huschi.net

Mail::SpamAssassin::ArUsereContributed PMail::SpamAssassin::ArchiveIterator(3)
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(3) spamassassin(1) mass-check(1)
perl v5.26.3                      2021-0Mail::SpamAssassin::ArchiveIterator(3)