Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mail::Box::Search(3)  User Contributed Perl Documentation Mail::Box::Search(3)

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.

       Extends "DESCRIPTION" in	Mail::Reporter.

METHODS
       Extends "METHODS" in Mail::Reporter.

   Constructors
       Extends "Constructors" in Mail::Reporter.

       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)
	   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( [$fh],	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
       Extends "Error handling"	in Mail::Reporter.

       $obj->AUTOLOAD()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->addReport($object)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->defaultTrace( [$level]|[$loglevel,	$tracelevel]|[$level,
       $callback] )
       Mail::Box::Search->defaultTrace(	[$level]|[$loglevel,
       $tracelevel]|[$level, $callback]	)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->errors()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->log( [$level, [$strings]] )
       Mail::Box::Search->log( [$level,	[$strings]] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->logPriority($level)
       Mail::Box::Search->logPriority($level)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->logSettings()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->notImplemented()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->report( [$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->reportAll(	[$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->trace( [$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->warnings()
	   Inherited, see "Error handling" in Mail::Reporter

   Cleanup
       Extends "Cleanup" in Mail::Reporter.

       $obj->DESTROY()
	   Inherited, 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 3.009, built on
       August 18, 2020.	Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2001-2020 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://dev.perl.org/licenses/

perl v5.32.0			  2020-08-18		  Mail::Box::Search(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DIAGNOSTICS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Box::Search&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help