Mail::Box::Search(3pm)					User Contributed Perl Documentation				    Mail::Box::Search(3pm)

NAME

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

INHERITANCE

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

	Mail::Box::Search is extended by
	  Mail::Box::Search::Grep
	  Mail::Box::Search::SpamAssassin
	  Mail::Server::IMAP4::Search

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

   Constructors
       Mail::Box::Search->new(OPTIONS)
	   Create a filter.

	    -Option    --Defined in	--Default
	     binaries			  <false>
	     decode			  <true>
	     delayed			  <true>
	     deleted			  <false>
	     deliver			  undef
	     in 			  'BODY'
	     label			  undef
	     limit			  0
	     log	 Mail::Reporter   'WARNINGS'
	     logical			  'REPLACE'
	     multiparts 		  <true>
	     trace	 Mail::Reporter   '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
	   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 fulfil the search.  The details output will still contain the places where 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

   Searching
       $obj->inBody(PART, BODY)
	   Tests whether body contains the requesting information.  See the specific search module for its parameters.

       $obj->inHead(PART, HEAD)
	   Tests whether header contains the requesting information.  See the specific search module for its parameters.

       $obj->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 (a Mail::Box::Thread::Node), one single MESSAGE (a 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.

	   example:

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

       $obj->searchPart(PART)
	   Search this message PART for matches.

   The Results
       $obj->printMatch([FILEHANDLE], HASH)
	   Print the information about the match (see new(deliver)) in some understandable way.  If no file handle is specified, the output will
	   go to the selected filehandle (see "perldoc -f select").

   Error handling
       $obj->AUTOLOAD()
	   See "Error handling" in Mail::Reporter

       $obj->addReport(OBJECT)
	   See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
       Mail::Box::Search->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
	   See "Error handling" in Mail::Reporter

       $obj->errors()
	   See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])
       Mail::Box::Search->log([LEVEL [,STRINGS]])
	   See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Box::Search->logPriority(LEVEL)
	   See "Error handling" in Mail::Reporter

       $obj->logSettings()
	   See "Error handling" in Mail::Reporter

       $obj->notImplemented()
	   See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])
	   See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])
	   See "Error handling" in Mail::Reporter

       $obj->trace([LEVEL])
	   See "Error handling" in Mail::Reporter

       $obj->warnings()
	   See "Error handling" in Mail::Reporter

   Cleanup
       $obj->DESTROY()
	   See "Cleanup" in Mail::Reporter

       $obj->inGlobalDestruction()
	   See "Cleanup" in Mail::Reporter

DIAGNOSTICS

       Error: Cannot search in body.
	   Th search object does not implement inBody(), and can therefore not search a message body.

       Error: Cannot search in header.
	   Th search object does not implement inHead(), and can therefore not search a message header.

       Error: Don't know how to deliver via results in $way.
	   The search results cannot be delivered in the specific way, because that is not a defined alternative.

       Error: Package $package does not implement $method.
	   Fatal error: the specific package (or one of its superclasses) does not implement this method where it should. This message means that
	   some other related classes do implement this method however the class at hand does not.  Probably you should investigate this and
	   probably inform the author of the package.

       Error: Search in BODY, HEAD or MESSAGE not $in.
	   The "in" option defines only three names.

SEE ALSO

       This module is part of Mail-Box distribution version 2.105, built on May 07, 2012. Website: http://perl.overmeer.net/mailbox/

LICENSE

       Copyrights 2001-2012 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.14.2							    2012-05-07						    Mail::Box::Search(3pm)