Mail::Box::Search::Grep(3pm)

1Mail::Box::Search::GrepU(s3e)r Contributed Perl DocumentaMtaiioln::Box::Search::Grep(3)
2
3
4

NAME

6       Mail::Box::Search::Grep - select messages within a mail box like grep
7       does
8

INHERITANCE

10        Mail::Box::Search::Grep
11          is a Mail::Box::Search
12          is a Mail::Reporter
13

SYNOPSIS

15        use Mail::Box::Manager;
16        my $mgr    = Mail::Box::Manager->new;
17        my $folder = $mgr->open('Inbox');
18
19        my $filter = Mail::Box::Search::Grep->new
20           ( label => 'selected'
21           , in => 'BODY', match => qr/abc?d*e/
22           );
23
24        my @msgs   = $filter->search($folder);
25
26        my $filter = Mail::Box::Search::Grep->new
27          ( field => 'To'
28          , match => $my_email
29          );
30
31        if($filter->search($message)) {...}
32

DESCRIPTION

34       Try to find some text strings in the header and footer of messages.
35       Various ways to limit the search to certain header fields, the whole
36       header, only the body, the whole message, but even binary multiparts,
37       are provided for.
38
39       The name grep is derived from the UNIX tool grep, which means: "Get
40       Regular Expression and Print".  Although you can search using regular
41       expressions (the Perl way of them), you do not have to print those as
42       result.
43

METHODS

45       Constructors
46
47       Mail::Box::Search::Grep->new(OPTIONS)
48
49           Create a UNIX-grep like search filter.
50
51            Option    --Defined in     --Default
52            binaries    Mail::Box::Search  <false>
53            decode      Mail::Box::Search  <true>
54            delayed     Mail::Box::Search  <true>
55            deleted     Mail::Box::Search  <false>
56            deliver                      undef
57            field                        undef
58            in          Mail::Box::Search  <$field ? 'HEAD' : C<'BODY'>>
59            label       Mail::Box::Search  undef
60            limit       Mail::Box::Search  0
61            log         Mail::Reporter   'WARNINGS'
62            logical     Mail::Box::Search  'REPLACE'
63            match                        <required>
64            multiparts  Mail::Box::Search  <true>
65            trace       Mail::Reporter   'WARNINGS'
66
67           . binaries BOOLEAN
68
69           . decode BOOLEAN
70
71           . delayed BOOLEAN
72
73           . deleted BOOLEAN
74
75           . deliver undef⎪CODE⎪'DELETE'⎪LABEL⎪'PRINT'⎪REF-ARRAY
76
77               Store the details about where the match was found.  The search
78               may take much longer when this feature is enabled.
79
80               When an ARRAY is specified it will contain a list of references
81               to hashes.  Each hash contains the information of one match.  A
82               match in a header line will result in a line with fields "mes‐
83               sage", "part", and "field", where the field is a Mail::Mes‐
84               sage::Field object.  When the match is in the body the hash
85               will contain a "message", "part", "linenr", and "line".
86
87               In case of a CODE reference, that routine is called for each
88               match. The first argument is this search object and the second
89               a reference to same hash as would be stored in the array.
90
91               The "PRINT" will call printMatchedHead() or printMatchedBody()
92               when any matching header resp body line was found.  The output
93               is minimized by not reprinting the message info on multiple
94               matches in the same message.
95
96               "DELETE" will flag the message to be deleted in case of a
97               match.  When a multipart's part is matched, the whole message
98               will be flagged for deletion.
99
100           . field undef⎪STRING⎪REGEX⎪CODE
101
102               Not valid in combination with "in" set to "BODY".  The STRING
103               is one full field name (case-insensitive).  Use a REGEX to
104               select more than one header line to be scanned. CODE is a rou‐
105               tine which is called for each field in the header.   The CODE
106               is called with the header as first, and the field as second
107               argument.  If the CODE returns true, the message is selected.
108
109           . in 'HEAD'⎪'BODY'⎪'MESSAGE'
110
111           . label STRING
112
113           . limit NUMBER
114
115           . log LEVEL
116
117           . logical 'REPLACE'⎪'AND'⎪'OR'⎪'NOT'⎪'AND NOT'⎪'OR NOT'
118
119           . match STRING⎪REGEX⎪CODE
120
121               The pattern to be search for can be a REGular EXpression, or a
122               STRING.  In both cases, the match succeeds if it is found any‐
123               where within the selected fields.
124
125               With a CODE reference, that function will be called each field
126               or body-line.  When the result is true, the details are deliv‐
127               ered.  The call formats are
128
129                $code->($head, $field);          # for HEAD searches
130                $code->($body, $linenr, $line);  # for BODY searches
131
132               The $head resp $body are one message's head resp. body object.
133               The $field is a header line which matches.  The $line and
134               $linenr tell the matching line in the body.
135
136               Be warned that when you search in "MESSAGE" the code must
137               accept both formats.
138
139           . multiparts BOOLEAN
140
141           . trace LEVEL
142
143       Searching
144
145       $obj->inBody(PART, BODY)
146
147           See "Searching" in Mail::Box::Search
148
149       $obj->inHead(PART, HEAD)
150
151           See "Searching" in Mail::Box::Search
152
153       $obj->search(FOLDER⎪THREAD⎪MESSAGE⎪ARRAY-OF-MESSAGES)
154
155           See "Searching" in Mail::Box::Search
156
157       $obj->searchPart(PART)
158
159           See "Searching" in Mail::Box::Search
160
161       The Results
162
163       $obj->printMatch([FILEHANDLE], HASH)
164
165           See "The Results" in Mail::Box::Search
166
167       $obj->printMatchedBody(FILEHANDLE, MATCH)
168
169       $obj->printMatchedHead(FILEHANDLE, MATCH)
170
171       Error handling
172
173       $obj->AUTOLOAD
174
175           See "Error handling" in Mail::Reporter
176
177       $obj->addReport(OBJECT)
178
179           See "Error handling" in Mail::Reporter
180
181       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
182
183       Mail::Box::Search::Grep->defaultTrace([LEVEL]⎪[LOGLEVEL,
184       TRACELEVEL]⎪[LEVEL, CALLBACK])
185
186           See "Error handling" in Mail::Reporter
187
188       $obj->errors
189
190           See "Error handling" in Mail::Reporter
191
192       $obj->log([LEVEL [,STRINGS]])
193
194       Mail::Box::Search::Grep->log([LEVEL [,STRINGS]])
195
196           See "Error handling" in Mail::Reporter
197
198       $obj->logPriority(LEVEL)
199
200       Mail::Box::Search::Grep->logPriority(LEVEL)
201
202           See "Error handling" in Mail::Reporter
203
204       $obj->logSettings
205
206           See "Error handling" in Mail::Reporter
207
208       $obj->notImplemented
209
210           See "Error handling" in Mail::Reporter
211
212       $obj->report([LEVEL])
213
214           See "Error handling" in Mail::Reporter
215
216       $obj->reportAll([LEVEL])
217
218           See "Error handling" in Mail::Reporter
219
220       $obj->trace([LEVEL])
221
222           See "Error handling" in Mail::Reporter
223
224       $obj->warnings
225
226           See "Error handling" in Mail::Reporter
227
228       Cleanup
229
230       $obj->DESTROY
231
232           See "Cleanup" in Mail::Reporter
233
234       $obj->inGlobalDestruction
235
236           See "Cleanup" in Mail::Reporter
237

DIAGNOSTICS

239       Error: Package $package does not implement $method.
240
241       Fatal error: the specific package (or one of its superclasses) does not
242       implement this method where it should. This message means that some
243       other related classes do implement this method however the class at
244       hand does not.  Probably you should investigate this and probably
245       inform the author of the package.
246

LICENSE

252       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
253       ChangeLog.
254
255       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
258
259
260
261perl v5.8.8                       2007-03-25        Mail::Box::Search::Grep(3)