Mail::Box::Search(3pm)

1Mail::Box::Search(3)  User Contributed Perl Documentation Mail::Box::Search(3)
2
3
4

NAME

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

INHERITANCE

9        Mail::Box::Search
10          is a Mail::Reporter
11
12        Mail::Box::Search is extended by
13          Mail::Box::Search::Grep
14          Mail::Box::Search::SpamAssassin
15          Mail::Server::IMAP4::Search
16

SYNOPSIS

18        use Mail::Box::Manager;
19        my $mgr    = Mail::Box::Manager->new;
20        my $folder = $mgr->open('Inbox');
21
22        my $filter = Mail::Box::Search::[something]->new;
23        my @msgs   = $filter->search($folder, ...);
24        if($filter->search($message)) {...}
25

DESCRIPTION

27       This "Mail::Box::Search" class is the base class for various message
28       scan algorithms.  The selected messages can be labeled.  Boolean opera‐
29       tions on messages are supported.
30
31       Currently implemented searches:
32
33       Mail::Box::Search::Grep
34           Match header or body against a regular expression in a UNIX "grep"
35           like fashion.
36
37       Mail::Box::Search::SpamAssassin
38           Try to detect spam, using Mail::SpamAssassin.
39
40       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 com‐
43           plete.
44

METHODS

46       Constructors
47
48       Mail::Box::Search->new(OPTIONS)
49
50           Create a filter.
51
52            Option    --Defined in     --Default
53            binaries                     <false>
54            decode                       <true>
55            delayed                      <true>
56            deleted                      <false>
57            deliver                      undef
58            in                           'BODY'
59            label                        undef
60            limit                        0
61            log         Mail::Reporter   'WARNINGS'
62            logical                      'REPLACE'
63            multiparts                   <true>
64            trace       Mail::Reporter   'WARNINGS'
65
66           . binaries BOOLEAN
67
68               Whether to include binary bodies in the search.
69
70           . decode BOOLEAN
71
72               Decode the messages before the search takes place.  Even plain
73               text messages can be encoded, for instance as "quoted-print‐
74               able", which may disturb the results.  However, decoding will
75               slow-down the search.
76
77           . delayed BOOLEAN
78
79               Include the delayed messages (which will be parsed) in the
80               search.  If you set this to false, you may find fewer hits.
81
82           . deleted BOOLEAN
83
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
88           . deliver undef⎪CODE⎪'DELETE'
89
90               The exact functionality of this parameter differs per search
91               method, so read the applicable man-page.  In any case "undef"
92               means that details are not collected for this search, which is
93               the fastest search.
94
95               "DELETE" will flag the message to be flagged for deletion.  You
96               may also specify your own CODE reference.  With an reference to
97               an array, the information about the matches is collected as a
98               list of hashes, one hash per match.
99
100           . in 'HEAD'⎪'BODY'⎪'MESSAGE'
101
102               Where to look for the match.
103
104           . label STRING
105
106               Mark all selected messages with the specified STRING.  If this
107               field is not specified, the message will not get a label;
108               search() also returns a list of selected messages.
109
110           . limit NUMBER
111
112               Limit the search to the specified NUMBER of messages.  When the
113               NUMBER is positive, the search starts at the first message in
114               the folder or thread.  A negative NUMBER starts at the end of
115               the folder.  If the limit is set to zero, there is no limit.
116
117           . log LEVEL
118
119           . logical 'REPLACE'⎪'AND'⎪'OR'⎪'NOT'⎪'AND NOT'⎪'OR NOT'
120
121               Only applicable in combination with a "label".  How to handle
122               the existing labels.  In case of "REPLACE", messages which
123               already are carrying the label are stripped from their selec‐
124               tion (unless they match again).  With "AND", the message must
125               be selected by this search and already carry the label, other‐
126               wise the label will not be set.  Specify "OR" to have newly
127               selected messages added to the set of already selected mes‐
128               sages.
129
130               "NOT" is true for messages which do not fulfil the search.  The
131               details output will still contain the places where the match
132               was found, however those messages will complementary set of
133               messages will be labeled and returned.
134
135           . multiparts BOOLEAN
136
137               Are multiparts to be included in the search results?  Some MUA
138               have problems handling details received from the search.  When
139               this flag is turned off, the body of multiparts will be
140               ignored.  The parts search will include the preamble and epi‐
141               logue.
142
143           . trace LEVEL
144
145       Searching
146
147       $obj->inBody(PART, BODY)
148
149           Tests whether body contains the requesting information.  See the
150           specific search module for its parameters.
151
152       $obj->inHead(PART, HEAD)
153
154           Tests whether header contains the requesting information.  See the
155           specific search module for its parameters.
156
157       $obj->search(FOLDER⎪THREAD⎪MESSAGE⎪ARRAY-OF-MESSAGES)
158
159           Check which messages from the FOLDER (Mail::Box) match the search
160           parameters.  The matched messages are returned as list.  You can
161           also specify a THREAD (a Mail::Box::Thread::Node), one single MES‐
162           SAGE (a Mail::Message), or an array of messages.
163
164           Sometimes we know how only one match is needed.  In this case, this
165           searching will stop at the first match.  For instance, when "limit"
166           is "-1" or 1, or when the search in done in scalar context.
167
168           Example:
169
170            my $grep = Mail::Box::Search::Grep->new
171             ( match   => 'My Name Is Nobody'
172             , deliver => 'PRINT'
173             );
174
175            $grep->search($folder);
176
177            my $message = $folder->message(3);
178            $grep->search($message);
179
180            my $thread  = $message->threadStart;
181            $grep->search($thread);
182
183       $obj->searchPart(PART)
184
185           Search this message PART for matches.
186
187       The Results
188
189       $obj->printMatch([FILEHANDLE], HASH)
190
191           Print the information about the match (see new(deliver)) in some
192           understandable way.  If no file handle is specified, the output
193           will go to the selected filehandle (see "perldoc -f select").
194
195       Error handling
196
197       $obj->AUTOLOAD
198
199           See "Error handling" in Mail::Reporter
200
201       $obj->addReport(OBJECT)
202
203           See "Error handling" in Mail::Reporter
204
205       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
206
207       Mail::Box::Search->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
208       CALLBACK])
209
210           See "Error handling" in Mail::Reporter
211
212       $obj->errors
213
214           See "Error handling" in Mail::Reporter
215
216       $obj->log([LEVEL [,STRINGS]])
217
218       Mail::Box::Search->log([LEVEL [,STRINGS]])
219
220           See "Error handling" in Mail::Reporter
221
222       $obj->logPriority(LEVEL)
223
224       Mail::Box::Search->logPriority(LEVEL)
225
226           See "Error handling" in Mail::Reporter
227
228       $obj->logSettings
229
230           See "Error handling" in Mail::Reporter
231
232       $obj->notImplemented
233
234           See "Error handling" in Mail::Reporter
235
236       $obj->report([LEVEL])
237
238           See "Error handling" in Mail::Reporter
239
240       $obj->reportAll([LEVEL])
241
242           See "Error handling" in Mail::Reporter
243
244       $obj->trace([LEVEL])
245
246           See "Error handling" in Mail::Reporter
247
248       $obj->warnings
249
250           See "Error handling" in Mail::Reporter
251
252       Cleanup
253
254       $obj->DESTROY
255
256           See "Cleanup" in Mail::Reporter
257
258       $obj->inGlobalDestruction
259
260           See "Cleanup" in Mail::Reporter
261

DIAGNOSTICS

263       Error: Cannot search in body.
264
265       Th search object does not implement inBody(), and can therefore not
266       search a message body.
267
268       Error: Cannot search in header.
269
270       Th search object does not implement inHead(), and can therefore not
271       search a message header.
272
273       Error: Don't know how to deliver via results in $way.
274
275       The search results cannot be delivered in the specific way, because
276       that is not a defined alternative.
277
278       Error: Package $package does not implement $method.
279
280       Fatal error: the specific package (or one of its superclasses) does not
281       implement this method where it should. This message means that some
282       other related classes do implement this method however the class at
283       hand does not.  Probably you should investigate this and probably
284       inform the author of the package.
285
286       Error: Search in BODY, HEAD or MESSAGE not $in.
287
288       The "in" option defines only three names.
289

LICENSE

295       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
296       ChangeLog.
297
298       This program is free software; you can redistribute it and/or modify it
299       under the same terms as Perl itself.  See
300       http://www.perl.com/perl/misc/Artistic.html
301
302
303
304perl v5.8.8                       2007-03-25              Mail::Box::Search(3)