1Mail::Box::Search(3) User Contributed Perl Documentation Mail::Box::Search(3)
2
6 Mail::Box::Search - select messages within a mail box
7
9 Mail::Box::Search
10 is a Mail::Reporter
11 Mail::Box::Search is extended by
13 Mail::Box::Search::Grep
14 Mail::Box::Search::SpamAssassin
15 Mail::Server::IMAP4::Search
16
18 use Mail::Box::Manager;
19 my $mgr = Mail::Box::Manager->new;
20 my $folder = $mgr->open('Inbox');
21 my $filter = Mail::Box::Search::[something]->new;
23 my @msgs = $filter->search($folder, ...);
24 if($filter->search($message)) {...}
25
27 This "Mail::Box::Search" class is the base class for various message
28 scan algorithms. The selected messages can be labeled. Boolean
29 operations on messages are supported.
30 Currently implemented searches:
32 Mail::Box::Search::Grep
34 Match header or body against a regular expression in a UNIX "grep"
35 like fashion.
36 Mail::Box::Search::SpamAssassin
38 Try to detect spam, using Mail::SpamAssassin.
39 Mail::Box::Search::IMAP
41 Search an IMAP folder for special interface IMAP folders provide
42 for it. UNDER CONSTRUCTION till Mail::Transport::IMAP4 is
43 complete.
44 Extends "DESCRIPTION" in Mail::Reporter.
46
48 Extends "METHODS" in Mail::Reporter.
49 Constructors
51 Extends "Constructors" in Mail::Reporter.
52 Mail::Box::Search->new(%options)
54 Create a filter.
55 -Option --Defined in --Default
57 binaries <false>
58 decode <true>
59 delayed <true>
60 deleted <false>
61 deliver undef
62 in 'BODY'
63 label undef
64 limit 0
65 log Mail::Reporter 'WARNINGS'
66 logical 'REPLACE'
67 multiparts <true>
68 trace Mail::Reporter 'WARNINGS'
69 binaries => BOOLEAN
71 Whether to include binary bodies in the search.
72 decode => BOOLEAN
74 Decode the messages before the search takes place. Even plain
75 text messages can be encoded, for instance as "quoted-printable",
76 which may disturb the results. However, decoding will slow-down
77 the search.
78 delayed => BOOLEAN
80 Include the delayed messages (which will be parsed) in the
81 search. If you set this to false, you may find fewer hits.
82 deleted => BOOLEAN
84 In most cases, you will not be interested in results which are
85 found in messages flagged to be deleted. However, with this
86 option you can specify you want them to be searched too.
87 deliver => undef|CODE|'DELETE'
89 The exact functionality of this parameter differs per search
90 method, so read the applicable man-page. In any case "undef"
91 means that details are not collected for this search, which is
92 the fastest search.
93 "DELETE" will flag the message to be flagged for deletion. You
95 may also specify your own CODE reference. With an reference to
96 an array, the information about the matches is collected as a
97 list of hashes, one hash per match.
98 in => 'HEAD'|'BODY'|'MESSAGE'
100 Where to look for the match.
101 label => STRING
103 Mark all selected messages with the specified STRING. If this
104 field is not specified, the message will not get a label;
105 search() also returns a list of selected messages.
106 limit => NUMBER
108 Limit the search to the specified NUMBER of messages. When the
109 NUMBER is positive, the search starts at the first message in the
110 folder or thread. A negative NUMBER starts at the end of the
111 folder. If the limit is set to zero, there is no limit.
112 log => LEVEL
114 logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'
115 Only applicable in combination with a "label". How to handle the
116 existing labels. In case of "REPLACE", messages which already
117 are carrying the label are stripped from their selection (unless
118 they match again). With "AND", the message must be selected by
119 this search and already carry the label, otherwise the label will
120 not be set. Specify "OR" to have newly selected messages added
121 to the set of already selected messages.
122 "NOT" is true for messages which do not fulfil the search. The
124 details output will still contain the places where the match was
125 found, however those messages will complementary set of messages
126 will be labeled and returned.
127 multiparts => BOOLEAN
129 Are multiparts to be included in the search results? Some MUA
130 have problems handling details received from the search. When
131 this flag is turned off, the body of multiparts will be ignored.
132 The parts search will include the preamble and epilogue.
133 trace => LEVEL
135 Searching
137 $obj->inBody($part, $body)
138 Tests whether body contains the requesting information. See the
139 specific search module for its parameters.
140 $obj->inHead($part, $head)
142 Tests whether header contains the requesting information. See the
143 specific search module for its parameters.
144 $obj->search($folder|$thread|$message|ARRAY)
146 Check which messages from the $folder (Mail::Box) match the search
147 parameters. The matched messages are returned as list. You can
148 also specify a $thread (a Mail::Box::Thread::Node), one single
149 $message (a Mail::Message), or an ARRAY of messages.
150 Sometimes we know how only one match is needed. In this case, this
152 searching will stop at the first match. For instance, when "limit"
153 is -1 or 1, or when the search in done in scalar context.
154 example:
156 my $grep = Mail::Box::Search::Grep->new
158 ( match => 'My Name Is Nobody'
159 , deliver => 'PRINT'
160 );
161 $grep->search($folder);
163 my $message = $folder->message(3);
165 $grep->search($message);
166 my $thread = $message->threadStart;
168 $grep->search($thread);
169 $obj->searchPart($part)
171 Search this message $part for matches.
172 The Results
174 $obj->printMatch( [$fh], HASH )
175 Print the information about the match (see new(deliver)) in some
176 understandable way. If no file handle is specified, the output
177 will go to the selected filehandle (see "perldoc -f select").
178 Error handling
180 Extends "Error handling" in Mail::Reporter.
181 $obj->AUTOLOAD()
183 Inherited, see "Error handling" in Mail::Reporter
184 $obj->addReport($object)
186 Inherited, see "Error handling" in Mail::Reporter
187 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
189 $callback] )
190 Mail::Box::Search->defaultTrace( [$level]|[$loglevel,
191 $tracelevel]|[$level, $callback] )
192 Inherited, see "Error handling" in Mail::Reporter
193 $obj->errors()
195 Inherited, see "Error handling" in Mail::Reporter
196 $obj->log( [$level, [$strings]] )
198 Mail::Box::Search->log( [$level, [$strings]] )
199 Inherited, see "Error handling" in Mail::Reporter
200 $obj->logPriority($level)
202 Mail::Box::Search->logPriority($level)
203 Inherited, see "Error handling" in Mail::Reporter
204 $obj->logSettings()
206 Inherited, see "Error handling" in Mail::Reporter
207 $obj->notImplemented()
209 Inherited, see "Error handling" in Mail::Reporter
210 $obj->report( [$level] )
212 Inherited, see "Error handling" in Mail::Reporter
213 $obj->reportAll( [$level] )
215 Inherited, see "Error handling" in Mail::Reporter
216 $obj->trace( [$level] )
218 Inherited, see "Error handling" in Mail::Reporter
219 $obj->warnings()
221 Inherited, see "Error handling" in Mail::Reporter
222 Cleanup
224 Extends "Cleanup" in Mail::Reporter.
225 $obj->DESTROY()
227 Inherited, see "Cleanup" in Mail::Reporter
228
230 Error: Cannot search in body.
231 Th search object does not implement inBody(), and can therefore not
232 search a message body.
233 Error: Cannot search in header.
235 Th search object does not implement inHead(), and can therefore not
236 search a message header.
237 Error: Don't know how to deliver via results in $way.
239 The search results cannot be delivered in the specific way, because
240 that is not a defined alternative.
241 Error: Package $package does not implement $method.
243 Fatal error: the specific package (or one of its superclasses) does
244 not implement this method where it should. This message means that
245 some other related classes do implement this method however the
246 class at hand does not. Probably you should investigate this and
247 probably inform the author of the package.
248 Error: Search in BODY, HEAD or MESSAGE not $in.
250 The "in" option defines only three names.
251
253 This module is part of Mail-Box distribution version 3.010, built on
254 July 18, 2023. Website: http://perl.overmeer.net/CPAN/
255
257 Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
258 ChangeLog.
259 This program is free software; you can redistribute it and/or modify it
261 under the same terms as Perl itself. See http://dev.perl.org/licenses/
262perl v5.38.0 2023-07-24 Mail::Box::Search(3)