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
46 Constructors
47 Mail::Box::Search->new(OPTIONS)
48 Create a filter.
49 -Option --Defined in --Default
51 binaries <false>
52 decode <true>
53 delayed <true>
54 deleted <false>
55 deliver undef
56 in 'BODY'
57 label undef
58 limit 0
59 log Mail::Reporter 'WARNINGS'
60 logical 'REPLACE'
61 multiparts <true>
62 trace Mail::Reporter 'WARNINGS'
63 binaries => BOOLEAN
65 Whether to include binary bodies in the search.
66 decode => BOOLEAN
68 Decode the messages before the search takes place. Even plain
69 text messages can be encoded, for instance as "quoted-printable",
70 which may disturb the results. However, decoding will slow-down
71 the search.
72 delayed => BOOLEAN
74 Include the delayed messages (which will be parsed) in the
75 search. If you set this to false, you may find fewer hits.
76 deleted => BOOLEAN
78 In most cases, you will not be interested in results which are
79 found in messages flagged to be deleted. However, with this
80 option you can specify you want them to be searched too.
81 deliver => undef|CODE|'DELETE'
83 The exact functionality of this parameter differs per search
84 method, so read the applicable man-page. In any case "undef"
85 means that details are not collected for this search, which is
86 the fastest search.
87 "DELETE" will flag the message to be flagged for deletion. You
89 may also specify your own CODE reference. With an reference to
90 an array, the information about the matches is collected as a
91 list of hashes, one hash per match.
92 in => 'HEAD'|'BODY'|'MESSAGE'
94 Where to look for the match.
95 label => STRING
97 Mark all selected messages with the specified STRING. If this
98 field is not specified, the message will not get a label;
99 search() also returns a list of selected messages.
100 limit => NUMBER
102 Limit the search to the specified NUMBER of messages. When the
103 NUMBER is positive, the search starts at the first message in the
104 folder or thread. A negative NUMBER starts at the end of the
105 folder. If the limit is set to zero, there is no limit.
106 log => LEVEL
108 logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'
109 Only applicable in combination with a "label". How to handle the
110 existing labels. In case of "REPLACE", messages which already
111 are carrying the label are stripped from their selection (unless
112 they match again). With "AND", the message must be selected by
113 this search and already carry the label, otherwise the label will
114 not be set. Specify "OR" to have newly selected messages added
115 to the set of already selected messages.
116 "NOT" is true for messages which do not fulfil the search. The
118 details output will still contain the places where the match was
119 found, however those messages will complementary set of messages
120 will be labeled and returned.
121 multiparts => BOOLEAN
123 Are multiparts to be included in the search results? Some MUA
124 have problems handling details received from the search. When
125 this flag is turned off, the body of multiparts will be ignored.
126 The parts search will include the preamble and epilogue.
127 trace => LEVEL
129 Searching
131 $obj->inBody(PART, BODY)
132 Tests whether body contains the requesting information. See the
133 specific search module for its parameters.
134 $obj->inHead(PART, HEAD)
136 Tests whether header contains the requesting information. See the
137 specific search module for its parameters.
138 $obj->search(FOLDER|THREAD|MESSAGE|ARRAY-OF-MESSAGES)
140 Check which messages from the FOLDER (Mail::Box) match the search
141 parameters. The matched messages are returned as list. You can
142 also specify a THREAD (a Mail::Box::Thread::Node), one single
143 MESSAGE (a Mail::Message), or an array of messages.
144 Sometimes we know how only one match is needed. In this case, this
146 searching will stop at the first match. For instance, when "limit"
147 is "-1" or 1, or when the search in done in scalar context.
148 example:
150 my $grep = Mail::Box::Search::Grep->new
152 ( match => 'My Name Is Nobody'
153 , deliver => 'PRINT'
154 );
155 $grep->search($folder);
157 my $message = $folder->message(3);
159 $grep->search($message);
160 my $thread = $message->threadStart;
162 $grep->search($thread);
163 $obj->searchPart(PART)
165 Search this message PART for matches.
166 The Results
168 $obj->printMatch([FILEHANDLE], HASH)
169 Print the information about the match (see new(deliver)) in some
170 understandable way. If no file handle is specified, the output
171 will go to the selected filehandle (see "perldoc -f select").
172 Error handling
174 $obj->AUTOLOAD
175 See "Error handling" in Mail::Reporter
176 $obj->addReport(OBJECT)
178 See "Error handling" in Mail::Reporter
179 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
181 Mail::Box::Search->defaultTrace([LEVEL]|[LOGLEVEL,
182 TRACELEVEL]|[LEVEL, CALLBACK])
183 See "Error handling" in Mail::Reporter
185 $obj->errors
187 See "Error handling" in Mail::Reporter
188 $obj->log([LEVEL [,STRINGS]])
190 Mail::Box::Search->log([LEVEL [,STRINGS]])
191 See "Error handling" in Mail::Reporter
193 $obj->logPriority(LEVEL)
195 Mail::Box::Search->logPriority(LEVEL)
196 See "Error handling" in Mail::Reporter
198 $obj->logSettings
200 See "Error handling" in Mail::Reporter
201 $obj->notImplemented
203 See "Error handling" in Mail::Reporter
204 $obj->report([LEVEL])
206 See "Error handling" in Mail::Reporter
207 $obj->reportAll([LEVEL])
209 See "Error handling" in Mail::Reporter
210 $obj->trace([LEVEL])
212 See "Error handling" in Mail::Reporter
213 $obj->warnings
215 See "Error handling" in Mail::Reporter
216 Cleanup
218 $obj->DESTROY
219 See "Cleanup" in Mail::Reporter
220 $obj->inGlobalDestruction
222 See "Cleanup" in Mail::Reporter
223
225 Error: Cannot search in body.
226 Th search object does not implement inBody(), and can therefore not
227 search a message body.
228 Error: Cannot search in header.
230 Th search object does not implement inHead(), and can therefore not
231 search a message header.
232 Error: Don't know how to deliver via results in $way.
234 The search results cannot be delivered in the specific way, because
235 that is not a defined alternative.
236 Error: Package $package does not implement $method.
238 Fatal error: the specific package (or one of its superclasses) does
239 not implement this method where it should. This message means that
240 some other related classes do implement this method however the
241 class at hand does not. Probably you should investigate this and
242 probably inform the author of the package.
243 Error: Search in BODY, HEAD or MESSAGE not $in.
245 The "in" option defines only three names.
246
248 This module is part of Mail-Box distribution version 2.097, built on
249 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
250
252 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
253 ChangeLog.
254 This program is free software; you can redistribute it and/or modify it
256 under the same terms as Perl itself. See
257 http://www.perl.com/perl/misc/Artistic.html
258perl v5.12.3 2011-01-26 Mail::Box::Search(3)