{
    "mode": "info",
    "parameter": "Mail::Box::Search",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/Mail%3A%3ABox%3A%3ASearch/json",
    "generated": "2026-07-05T13:42:24Z",
    "synopsis": "use Mail::Box::Manager;\nmy $mgr    = Mail::Box::Manager->new;\nmy $folder = $mgr->open('Inbox');\nmy $filter = Mail::Box::Search::[something]->new;\nmy @msgs   = $filter->search($folder, ...);\nif($filter->search($message)) {...}",
    "sections": {
        "Mail::Box::Search(3pm)User Contributed Perl DocumentatioMail::Box::Search(3pm)": {
            "content": "",
            "subsections": []
        },
        "NAME": {
            "content": "Mail::Box::Search - select messages within a mail box\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Box::Search\nis a Mail::Reporter\n\nMail::Box::Search is extended by\nMail::Box::Search::Grep\nMail::Box::Search::SpamAssassin\nMail::Server::IMAP4::Search\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Mail::Box::Manager;\nmy $mgr    = Mail::Box::Manager->new;\nmy $folder = $mgr->open('Inbox');\n\nmy $filter = Mail::Box::Search::[something]->new;\nmy @msgs   = $filter->search($folder, ...);\nif($filter->search($message)) {...}\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This \"Mail::Box::Search\" class is the base class for various message\nscan algorithms.  The selected messages can be labeled.  Boolean\noperations on messages are supported.\n\nCurrently implemented searches:\n\nMail::Box::Search::Grep\nMatch header or body against a regular expression in a UNIX \"grep\"\nlike fashion.\n\nMail::Box::Search::SpamAssassin\nTry to detect spam, using Mail::SpamAssassin.\n\nMail::Box::Search::IMAP\nSearch an IMAP folder for special interface IMAP folders provide\nfor it.  UNDER CONSTRUCTION till Mail::Transport::IMAP4 is\ncomplete.\n\nExtends \"DESCRIPTION\" in Mail::Reporter.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in Mail::Reporter.\n\nConstructors\nExtends \"Constructors\" in Mail::Reporter.\n\nMail::Box::Search->new(%options)\nCreate a filter.\n\n-Option    --Defined in     --Default\nbinaries                     <false>\ndecode                       <true>\ndelayed                      <true>\ndeleted                      <false>\ndeliver                      undef\nin                           'BODY'\nlabel                        undef\nlimit                        0\nlog         Mail::Reporter   'WARNINGS'\nlogical                      'REPLACE'\nmultiparts                   <true>\ntrace       Mail::Reporter   'WARNINGS'\n\nbinaries => BOOLEAN\nWhether to include binary bodies in the search.\n\ndecode => BOOLEAN\nDecode the messages before the search takes place.  Even plain\ntext messages can be encoded, for instance as \"quoted-printable\",\nwhich may disturb the results.  However, decoding will slow-down\nthe search.\n\ndelayed => BOOLEAN\nInclude the delayed messages (which will be parsed) in the\nsearch.  If you set this to false, you may find fewer hits.\n\ndeleted => BOOLEAN\nIn most cases, you will not be interested in results which are\nfound in messages flagged to be deleted.  However, with this\noption you can specify you want them to be searched too.\n\ndeliver => undef|CODE|'DELETE'\nThe exact functionality of this parameter differs per search\nmethod, so read the applicable man-page.  In any case \"undef\"\nmeans that details are not collected for this search, which is\nthe fastest search.\n\n\"DELETE\" will flag the message to be flagged for deletion.  You\nmay also specify your own CODE reference.  With an reference to\nan array, the information about the matches is collected as a\nlist of hashes, one hash per match.\n\nin => 'HEAD'|'BODY'|'MESSAGE'\nWhere to look for the match.\n\nlabel => STRING\nMark all selected messages with the specified STRING.  If this\nfield is not specified, the message will not get a label;\nsearch() also returns a list of selected messages.\n\nlimit => NUMBER\nLimit the search to the specified NUMBER of messages.  When the\nNUMBER is positive, the search starts at the first message in the\nfolder or thread.  A negative NUMBER starts at the end of the\nfolder.  If the limit is set to zero, there is no limit.\n\nlog => LEVEL\nlogical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'\nOnly applicable in combination with a \"label\".  How to handle the\nexisting labels.  In case of \"REPLACE\", messages which already\nare carrying the label are stripped from their selection (unless\nthey match again).  With \"AND\", the message must be selected by\nthis search and already carry the label, otherwise the label will\nnot be set.  Specify \"OR\" to have newly selected messages added\nto the set of already selected messages.\n\n\"NOT\" is true for messages which do not fulfil the search.  The\ndetails output will still contain the places where the match was\nfound, however those messages will complementary set of messages\nwill be labeled and returned.\n\nmultiparts => BOOLEAN\nAre multiparts to be included in the search results?  Some MUA\nhave problems handling details received from the search.  When\nthis flag is turned off, the body of multiparts will be ignored.\nThe parts search will include the preamble and epilogue.\n\ntrace => LEVEL\n\nSearching\n$obj->inBody($part, $body)\nTests whether body contains the requesting information.  See the\nspecific search module for its parameters.\n\n$obj->inHead($part, $head)\nTests whether header contains the requesting information.  See the\nspecific search module for its parameters.\n\n$obj->search($folder|$thread|$message|ARRAY)\nCheck which messages from the $folder (Mail::Box) match the search\nparameters.  The matched messages are returned as list.  You can\nalso specify a $thread (a Mail::Box::Thread::Node), one single\n$message (a Mail::Message), or an ARRAY of messages.\n\nSometimes we know how only one match is needed.  In this case, this\nsearching will stop at the first match.  For instance, when \"limit\"\nis \"-1\" or 1, or when the search in done in scalar context.\n\nexample:\n\nmy $grep = Mail::Box::Search::Grep->new\n( match   => 'My Name Is Nobody'\n, deliver => 'PRINT'\n);\n\n$grep->search($folder);\n\nmy $message = $folder->message(3);\n$grep->search($message);\n\nmy $thread  = $message->threadStart;\n$grep->search($thread);\n\n$obj->searchPart($part)\nSearch this message $part for matches.\n\nThe Results\n$obj->printMatch( [$fh], HASH )\nPrint the information about the match (see new(deliver)) in some\nunderstandable way.  If no file handle is specified, the output\nwill go to the selected filehandle (see \"perldoc -f select\").\n\nError handling\nExtends \"Error handling\" in Mail::Reporter.\n\n$obj->AUTOLOAD()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->addReport($object)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,\n$callback] )\nMail::Box::Search->defaultTrace( [$level]|[$loglevel,\n$tracelevel]|[$level, $callback] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->errors()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->log( [$level, [$strings]] )\nMail::Box::Search->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box::Search->logPriority($level)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logSettings()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->notImplemented()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->report( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->reportAll( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->trace( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->warnings()\nInherited, see \"Error handling\" in Mail::Reporter\n\nCleanup\nExtends \"Cleanup\" in Mail::Reporter.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Reporter\n",
            "subsections": []
        },
        "DIAGNOSTICS": {
            "content": "Error: Cannot search in body.\nTh search object does not implement inBody(), and can therefore not\nsearch a message body.\n\nError: Cannot search in header.\nTh search object does not implement inHead(), and can therefore not\nsearch a message header.\n\nError: Don't know how to deliver via results in $way.\nThe search results cannot be delivered in the specific way, because\nthat is not a defined alternative.\n\nError: Package $package does not implement $method.\nFatal error: the specific package (or one of its superclasses) does\nnot implement this method where it should. This message means that\nsome other related classes do implement this method however the\nclass at hand does not.  Probably you should investigate this and\nprobably inform the author of the package.\n\nError: Search in BODY, HEAD or MESSAGE not $in.\nThe \"in\" option defines only three names.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Box distribution version 3.009, built on\nAugust 18, 2020. Website: http://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see\nChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.  See http://dev.perl.org/licenses/\n\nperl v5.30.3                      2020-08-20            Mail::Box::Search(3pm)",
            "subsections": []
        }
    },
    "summary": "Mail::Box::Search - select messages within a mail box",
    "flags": [],
    "examples": [],
    "see_also": []
}