Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Apropos / Subsearch:
optional field

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

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

          is a Mail::Reporter

        Mail::Box::Search is extended by

        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)) {...}

       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:

           Match header or body against a regular expression in a UNIX "grep"
           like fashion.

           Try to detect spam, using Mail::SpamAssassin.

           Search an IMAP folder for special interface IMAP folders provide
           for it.  UNDER CONSTRUCTION till Mail::Transport::IMAP4 is



           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

               "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

           . trace => LEVEL


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


           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.


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


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

            my $thread  = $message->threadStart;


           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


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Box::Search->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,

           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])

       Mail::Box::Search->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter



           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter


           See "Error handling" in Mail::Reporter



           See "Cleanup" in Mail::Reporter


           See "Cleanup" in Mail::Reporter

       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.

       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

       Copyrights 2001-2008 by Mark Overmeer. For other contributors see

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See

perl v5.10.0                      2008-04-28            Mail::Box::Search(3pm)