NAME

Mail::Box::Search - select messages within a mail box

CLASS INHERITANCE

 Mail::Box::Search
   is a Mail::Reporter

 Mail::Box::Search is extended by
   Mail::Box::Search::Grep
   Mail::Box::Search::IMAP
   Mail::Box::Search::SpamAssassin

SYNOPSIS

 use Mail::Box::Manager;
 my $mgr    = Mail::Box::Manager->new;
 my $folder = $mgr->open('Inbox');

 my $filter = Mail::Box::Search::[something]->new;
 my @msgs   = $filter->search($folder, ...);
 if($filter->search($message)) {...}

DESCRIPTION

This Mail::Box::Search class is the base class for various message scan algorithms. The selected messages can be labeled. Boolean operations on messages are supported.

Currently implemented searches:

Mail::Box::Search::Grep

Match header or body against a regular expression in a UNIX grep like fashion.

Mail::Box::Search::SpamAssassin

Try to detect spam, using Mail::SpamAssassin.

Mail::Box::Search::IMAP

Search an IMAP folder for special interface IMAP folders provide for it. UNDER CONSTRUCTION till Mail::Transport::IMAP4 is complete.

METHODS

Initiation

new OPTIONS

(Class method) Create a filter.

 OPTION               DEFAULT
 binaries             <false>
 decode               <true>
 delayed              <true>
 deleted              <false>
 deliver              undef
 in                   'BODY;
 label                undef
 limit                0
 log                  'WARNINGS'
 logical              'REPLACE'
 multiparts           <true>
 trace                'WARNINGS'

binaries => BOOLEAN

Whether to include binary bodies in the search.

decode => BOOLEAN

Decode the messages before the search takes place. Even plain text messages can be encoded, for instance as quoted-printable, which may disturb the results. However, decoding will slow-down the search.

delayed => BOOLEAN

Include the delayed messages (which will be parsed) in the search. If you set this to false, you may find fewer hits.

deleted => BOOLEAN

In most cases, you will not be interested in results which are found in messages flagged to be deleted. However, with this option you can specify you want them to be searched too.

deliver => undef|CODE|'DELETE'

The exact functionality of this parameter differs per search method, so read the applicable man-page. In any case undef means that details are not collected for this search, which is the fastest search.

DELETE will flag the message to be flagged for deletion. You may also specify your own CODE reference. With an reference to an array, the information about the matches is collected as a list of hashes, one hash per match.

in => 'HEAD'|'BODY'|'MESSAGE'

Where to look for the match.

label => STRING

Mark all selected messages with the specified STRING. If this field is not specified, the message will not get a label; search() also returns a list of selected messages.

limit => NUMBER

Limit the search to the specified NUMBER of messages. When the NUMBER is positive, the search starts at the first message in the folder or thread. A negative NUMBER starts at the end of the folder. If the limit is set to zero, there is no limit.

log => LEVEL

See Mail::Reporter::new(log)

logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'

Only applicable in combination with a label. How to handle the existing labels. In case of REPLACE, messages which already are carrying the label are stripped from their selection (unless they match again). With AND, the message must be selected by this search and already carry the label, otherwise the label will not be set. Specify OR to have newly selected messages added to the set of already selected messages.

NOT is true for messages which do not fulfill the search. The details output will still contain the places where the the match was found, however those messages will complementary set of messages will be labeled and returned.

multiparts => BOOLEAN

Are multiparts to be included in the search results? Some MUA have problems handling details received from the search. When this flag is turned off, the body of multiparts will be ignored. The parts search will include the preamble and epilogue.

trace => LEVEL

See Mail::Reporter::new(trace)

Searching

inBody PART, BODY

Tests whether body contains the requesting information. See the specific search module for its parameters.

inHead PART, HEAD

Tests whether header contains the requesting information. See the specific search module for its parameters.

search FOLDER|THREAD|MESSAGE|ARRAY-OF-MESSAGES

Check which messages from the FOLDER (Mail::Box) match the search parameters. The matched messages are returned as list. You can also specify a THREAD (Mail::Box::Thread::Node), one single MESSAGE (Mail::Message), or an array of messages.

Sometimes we know how only one match is needed. In this case, this searching will stop at the first match. For instance, when limit is -1 or 1, or when the search in done in scalar context.

Examples:

 my $grep = Mail::Box::Search::Grep->new
  ( match   => 'My Name Is Nobody'
  , deliver => 'PRINT'
  );

 $grep->search($folder);

 my $message = $folder->message(3);
 $grep->search($message);

 my $thread  = $message->threadStart;
 $grep->search($thread);

searchPart PART

Search this message PART for matches.

The Results

printMatch [FILEHANDLE], HASH

Print the information about the match (see search(deliver)) in some understandable way. If no file handle is specified, the output will go to the selected filehandle (see perldoc -f select).

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

DESTROY

See Mail::Reporter::DESTROY()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Written by Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.038.

Copyright (c) 2001-2003 by the authors. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.