.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Mail::Box::Search 3" .TH Mail::Box::Search 3 2026-04-11 "perl v5.42.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Mail::Box::Search \- select messages within a mail box .SH INHERITANCE .IX Header "INHERITANCE" .Vb 2 \& Mail::Box::Search \& is a Mail::Reporter \& \& Mail::Box::Search is extended by \& Mail::Box::Search::Grep \& Mail::Server::IMAP4::Search .Ve .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 3 \& use Mail::Box::Manager; \& my $mgr = Mail::Box::Manager\->new; \& my $folder = $mgr\->open(\*(AqInbox\*(Aq); \& \& my $filter = Mail::Box::Search::[something]\->new; \& my @msgs = $filter\->search($folder, ...); \& if($filter\->search($message)) {...} .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This \f(CW\*(C`Mail::Box::Search\*(C'\fR class is the base class for various message scan algorithms. The selected messages can be labeled. Boolean operations on messages are supported. .PP Currently implemented searches: .IP Mail::Box::Search::Grep 4 .IX Item "Mail::Box::Search::Grep" Match header or body against a regular expression in a UNIX \f(CW\*(C`grep\*(C'\fR like fashion. .ie n .IP """Mail::Box::Search::SpamAssassin""" 4 .el .IP \f(CWMail::Box::Search::SpamAssassin\fR 4 .IX Item "Mail::Box::Search::SpamAssassin" The original implementation supported only SpamAssassin 2.x, and therefore this implementation was removed for Mail::Box 4. .ie n .IP """Mail::Box::Search::IMAP""" 4 .el .IP \f(CWMail::Box::Search::IMAP\fR 4 .IX Item "Mail::Box::Search::IMAP" Search an IMAP folder for special interface IMAP folders provide for it. Implementation not completed. .PP Extends "DESCRIPTION" in Mail::Reporter. .SH METHODS .IX Header "METHODS" Extends "METHODS" in Mail::Reporter. .SS Constructors .IX Subsection "Constructors" Extends "Constructors" in Mail::Reporter. .ie n .IP $class\->\fBnew\fR(%options) 4 .el .IP \f(CW$class\fR\->\fBnew\fR(%options) 4 .IX Item "$class->new(%options)" Create a filter. Improves base, see "Constructors" in Mail::Reporter .Sp .Vb 11 \& \-Option \-\-Default \& binaries > \& decode > \& delayed true \& deleted false \& deliver undef \& in \*(AqBODY\*(Aq \& label undef \& limit 0 \& logical \*(AqREPLACE\*(Aq \& multiparts true .Ve .RS 4 .IP "binaries => BOOLEAN" 2 .IX Item "binaries => BOOLEAN" Whether to include binary bodies in the search. .IP "decode => BOOLEAN" 2 .IX Item "decode => BOOLEAN" Decode the messages before the search takes place. Even plain text messages can be encoded, for instance as \f(CW\*(C`quoted\-printable\*(C'\fR, which may disturb the results. However, decoding will slow\-down the search. .IP "delayed => BOOLEAN" 2 .IX Item "delayed => BOOLEAN" Include the delayed messages (which will be parsed) in the search. If you set this to \f(CW\*(C`false\*(C'\fR, you may find fewer hits. .IP "deleted => BOOLEAN" 2 .IX Item "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. .IP "deliver => undef|CODE|\*(AqDELETE\*(Aq" 2 .IX Item "deliver => undef|CODE|'DELETE'" The exact functionality of this parameter differs per search method, so read the applicable man\-page. In any case \f(CW\*(C`undef\*(C'\fR means that details are not collected for this search, which is the fastest search. .Sp \&\f(CW\*(C`DELETE\*(C'\fR 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. .IP "in => \*(AqHEAD\*(Aq|\*(AqBODY\*(Aq|\*(AqMESSAGE\*(Aq" 2 .IX Item "in => 'HEAD'|'BODY'|'MESSAGE'" Where to look for the match. .ie n .IP "label => $label" 2 .el .IP "label => \f(CW$label\fR" 2 .IX Item "label => $label" Mark all selected messages with the specified label. If this field is not specified, the message will not get a label; \f(CWsearch()\fR also returns a LIST of selected messages. .ie n .IP "limit => $number" 2 .el .IP "limit => \f(CW$number\fR" 2 .IX Item "limit => $number" Limit the search to the specified \f(CW$number\fR of messages. When the \f(CW$number\fR is positive, the search starts at the first message in the folder or thread. A negative \f(CW$number\fR starts at the end of the folder. If the limit is set to zero, there is no limit. .IP "logical => \*(AqREPLACE\*(Aq|\*(AqAND\*(Aq|\*(AqOR\*(Aq|\*(AqNOT\*(Aq|\*(AqAND NOT\*(Aq|\*(AqOR NOT\*(Aq" 2 .IX Item "logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'" Only applicable in combination with a \f(CW\*(C`label\*(C'\fR. How to handle the existing labels. In case of \f(CW\*(C`REPLACE\*(C'\fR, messages which already are carrying the label are stripped from their selection (unless they match again). With \f(CW\*(C`AND\*(C'\fR, the message must be selected by this search and already carry the label, otherwise the label will not be set. Specify \f(CW\*(C`OR\*(C'\fR to have newly selected messages added to the set of already selected messages. .Sp \&\f(CW\*(C`NOT\*(C'\fR is \f(CW\*(C`true\*(C'\fR 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. .IP "multiparts => BOOLEAN" 2 .IX Item "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. .RE .RS 4 .RE .SS Attributes .IX Subsection "Attributes" Extends "Attributes" in Mail::Reporter. .ie n .IP $obj\->\fBdeliver\fR() 4 .el .IP \f(CW$obj\fR\->\fBdeliver\fR() 4 .IX Item "$obj->deliver()" .ie n .IP $obj\->\fBdoMultiparts\fR() 4 .el .IP \f(CW$obj\fR\->\fBdoMultiparts\fR() 4 .IX Item "$obj->doMultiparts()" .ie n .IP $obj\->\fBparseDelayed\fR() 4 .el .IP \f(CW$obj\fR\->\fBparseDelayed\fR() 4 .IX Item "$obj->parseDelayed()" .ie n .IP $obj\->\fBskipDeleted\fR() 4 .el .IP \f(CW$obj\fR\->\fBskipDeleted\fR() 4 .IX Item "$obj->skipDeleted()" .SS "Error handling" .IX Subsection "Error handling" Extends "Error handling" in Mail::Reporter. .ie n .IP $obj\->\fBAUTOLOAD\fR() 4 .el .IP \f(CW$obj\fR\->\fBAUTOLOAD\fR() 4 .IX Item "$obj->AUTOLOAD()" Inherited, see "Error handling" in Mail::Reporter .ie n .IP $obj\->\fBnotImplemented\fR() 4 .el .IP \f(CW$obj\fR\->\fBnotImplemented\fR() 4 .IX Item "$obj->notImplemented()" Inherited, see "Error handling" in Mail::Reporter .SS Cleanup .IX Subsection "Cleanup" Extends "Cleanup" in Mail::Reporter. .ie n .IP $obj\->\fBDESTROY\fR() 4 .el .IP \f(CW$obj\fR\->\fBDESTROY\fR() 4 .IX Item "$obj->DESTROY()" Inherited, see "Cleanup" in Mail::Reporter .SS Searching .IX Subsection "Searching" .ie n .IP "$obj\->\fBinBody\fR($part, $body)" 4 .el .IP "\f(CW$obj\fR\->\fBinBody\fR($part, \f(CW$body\fR)" 4 .IX Item "$obj->inBody($part, $body)" Tests whether body contains the requesting information. See the specific search module for its parameters. .ie n .IP "$obj\->\fBinHead\fR($part, $head)" 4 .el .IP "\f(CW$obj\fR\->\fBinHead\fR($part, \f(CW$head\fR)" 4 .IX Item "$obj->inHead($part, $head)" Tests whether header contains the requesting information. See the specific search module for its parameters. .ie n .IP $obj\->\fBsearch\fR($folder|$thread|$message|ARRAY) 4 .el .IP \f(CW$obj\fR\->\fBsearch\fR($folder|$thread|$message|ARRAY) 4 .IX Item "$obj->search($folder|$thread|$message|ARRAY)" Check which messages from the \f(CW$folder\fR (Mail::Box) match the search parameters. The matched messages are returned as list. You can also specify a \f(CW$thread\fR (a Mail::Box::Thread::Node), one single \&\f(CW$message\fR (a Mail::Message), or an \f(CW\*(C`ARRAY\*(C'\fR of messages. .Sp Sometimes we know how only one match is needed. In this case, this searching will stop at the first match. For instance, when \f(CW\*(C`limit\*(C'\fR is \f(CW\-1\fR or \f(CW1\fR, or when the search in done in scalar context. .Sp ยป example: .Sp .Vb 4 \& my $grep = Mail::Box::Search::Grep\->new( \& match => \*(AqMy Name Is Nobody\*(Aq, \& deliver => \*(AqPRINT\*(Aq \& ); \& \& $grep\->search($folder); \& \& my $message = $folder\->message(3); \& $grep\->search($message); \& \& my $thread = $message\->threadStart; \& $grep\->search($thread); .Ve .ie n .IP $obj\->\fBsearchPart\fR($part) 4 .el .IP \f(CW$obj\fR\->\fBsearchPart\fR($part) 4 .IX Item "$obj->searchPart($part)" Search this message \f(CW$part\fR for matches. .SS "The Results" .IX Subsection "The Results" .ie n .IP "$obj\->\fBprintMatch\fR( [$fh], HASH )" 4 .el .IP "\f(CW$obj\fR\->\fBprintMatch\fR( [$fh], HASH )" 4 .IX Item "$obj->printMatch( [$fh], HASH )" Print the information about the match (see new(deliver)) in some understandable way. If no file handle \f(CW$fh\fR is specified, the output will go to the selected filehandle (see \f(CW\*(C`perldoc \-f select\*(C'\fR). .SH DIAGNOSTICS .IX Header "DIAGNOSTICS" .IP "Error: cannot search in body." 4 .IX Item "Error: cannot search in body." The search object does not implement \fBinBody()\fR, and can therefore not search a message body. Cast by \f(CWnew()\fR .IP "Error: cannot search in header." 4 .IX Item "Error: cannot search in header." The search object does not implement \fBinHead()\fR, and can therefore not search a message header. Cast by \f(CWnew()\fR .ie n .IP "Error: class $package does not implement method $method." 4 .el .IP "Error: class \f(CW$package\fR does not implement method \f(CW$method\fR." 4 .IX Item "Error: class $package does not implement method $method." Fatal error: the specific \f(CW$package\fR (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. Cast by \f(CWnotImplemented()\fR .ie n .IP "Error: don\*(Aqt know how to deliver results in $what." 4 .el .IP "Error: don\*(Aqt know how to deliver results in \f(CW$what\fR." 4 .IX Item "Error: don't know how to deliver results in $what." The search results cannot be delivered in the specific way, because that is not a defined alternative. Cast by \f(CWnew()\fR .ie n .IP "Error: expect messages to search, not $what." 4 .el .IP "Error: expect messages to search, not \f(CW$what\fR." 4 .IX Item "Error: expect messages to search, not $what." Cast by \f(CWsearch()\fR .ie n .IP "Error: search in BODY, HEAD or MESSAGE, not $what." 4 .el .IP "Error: search in BODY, HEAD or MESSAGE, not \f(CW$what\fR." 4 .IX Item "Error: search in BODY, HEAD or MESSAGE, not $what." The \f(CW\*(C`in\*(C'\fR option offers only three alternatives. Cast by \f(CWnew()\fR .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of Mail\-Box version 4.02, built on April 10, 2026. Website: \fIhttp://perl.overmeer.net/CPAN/\fR .SH LICENSE .IX Header "LICENSE" For contributors see file ChangeLog. .PP This software is copyright (c) 2001\-2026 by Mark Overmeer. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.