Box::Search(3)

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

CLASS HIERARCHY
 Mail::Box::Search
 is a Mail::Reporter

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

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

DESCRIPTION
Read Mail::Box-Overview first. This "Mail::Box::Search" method 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 "grep" like fashion.

A "Mail::Box::Search::Spam" is on the wishlist.

METHOD INDEX
Methods prefixed with an abbreviation are described in Mail::Reporter (MR).

The general methods for "Mail::Box::Search" objects:

   MR errors                            MR reportAll [LEVEL]
   MR log [LEVEL [,STRINGS]]               search FOLDER|THREAD|MESSAG...
      new OPTIONS                       MR trace [LEVEL]
      printMatch [FILEHANDLE], HASH     MR warnings
   MR report [LEVEL]

The extra methods for extension writers:

   MR AUTOLOAD                          MR logPriority LEVEL
   MR DESTROY                           MR logSettings
      inBody PART, BODY                 MR notImplemented
   MR inGlobalDestruction                  searchPart PART
      inHead PART, HEAD

METHODS

new OPTIONS
    Create a filter.

     OPTION     DEFINED BY         DEFAULT
     binaries   Mail::Box::Search  0
     details    Mail::Box::Search  undef
     decode     Mail::Box::Search  1
     in         Mail::Box::Search  'BODY'
     delayed    Mail::Box::Search  1
     deleted    Mail::Box::Search  0
     label      Mail::Box::Search  undef
     limit      Mail::Box::Search  0
     log        Mail::Reporter     'WARNINGS'
     logical    Mail::Box::Search  'REPLACE'
     multiparts Mail::Box::Search  1
     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.

    * details => undef|'PRINT'|'DELETE'|REF-ARRAY|CODE
        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.

        "PRINT" will cause a call to a standard printing routine per line found. "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.

    * 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.

    * 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.

    * 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 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.

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.

    Example:

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

     $grep->search($folder);

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

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

printMatch [FILEHANDLE], HASH
    Print the information about the match (see "details" option in the "search" method above) in some understandable way. If no file handle is specified, the output will go to the selected filehandle (see "perldoc -f select").

METHODS for extension writers

searchPart PART
    Search this message PART for matches.

inHead PART, HEAD
    Tests whether header contains the requesting information. See the specific search module for its parameters.

inBody PART, BODY
    Tests whether body contains the requesting information. See the specific search module for its parameters.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

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