Provided by: libmail-box-perl_3.004-1_all bug

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.004, built on December 22, 2017.

       Do not forget to read Mail::Box-Overview, Mail::Box-Cookbook, and Mail::Box-Index.
       Examples are included in the Mail-Box distribution, directories 'examples' and 'scripts'.

       Browseable manuals, papers, and other released material van be found at  Website:
       http://perl.overmeer.net/mailbox/

       The central modules (in separate distributions) in the MailBox suite are: Mail::Message,
       Mail::Box, Mail::Box::IMAP4, Mail::Box::POP3, Mail::Box::Parser::C, Mail::Box::Dbx
       (unpublished), Mail::Transport, Object::Realize::Later, and User::Identity.

       Please post questions or ideas to the author markov@cpan.org.

LICENSE

       Copyrights 2001-2017 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/