phpman > perldoc > 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.

    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/