1Mail::Box::Search::GrepU(s3e)r Contributed Perl DocumentaMtaiioln::Box::Search::Grep(3)
2
3
4
6 Mail::Box::Search::Grep - select messages within a mail box like grep
7 does
8
10 Mail::Box::Search::Grep
11 is a Mail::Box::Search
12 is a Mail::Reporter
13
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
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
45 Constructors
46 Mail::Box::Search::Grep->new(OPTIONS)
47 Create a UNIX-grep like search filter.
48
49 -Option --Defined in --Default
50 binaries Mail::Box::Search <false>
51 decode Mail::Box::Search <true>
52 delayed Mail::Box::Search <true>
53 deleted Mail::Box::Search <false>
54 deliver undef
55 field undef
56 in Mail::Box::Search <$field ? 'HEAD' : C<'BODY'>>
57 label Mail::Box::Search undef
58 limit Mail::Box::Search 0
59 log Mail::Reporter 'WARNINGS'
60 logical Mail::Box::Search 'REPLACE'
61 match <required>
62 multiparts Mail::Box::Search <true>
63 trace Mail::Reporter 'WARNINGS'
64
65 binaries => BOOLEAN
66 decode => BOOLEAN
67 delayed => BOOLEAN
68 deleted => BOOLEAN
69 deliver => undef|CODE|'DELETE'|LABEL|'PRINT'|REF-ARRAY
70 Store the details about where the match was found. The search
71 may take much longer when this feature is enabled.
72
73 When an ARRAY is specified it will contain a list of references
74 to hashes. Each hash contains the information of one match. A
75 match in a header line will result in a line with fields
76 "message", "part", and "field", where the field is a
77 Mail::Message::Field object. When the match is in the body the
78 hash will contain a "message", "part", "linenr", and "line".
79
80 In case of a CODE reference, that routine is called for each
81 match. The first argument is this search object and the second a
82 reference to same hash as would be stored in the array.
83
84 The "PRINT" will call printMatchedHead() or printMatchedBody()
85 when any matching header resp body line was found. The output is
86 minimized by not reprinting the message info on multiple matches
87 in the same message.
88
89 "DELETE" will flag the message to be deleted in case of a match.
90 When a multipart's part is matched, the whole message will be
91 flagged for deletion.
92
93 field => undef|STRING|REGEX|CODE
94 Not valid in combination with "in" set to "BODY". The STRING is
95 one full field name (case-insensitive). Use a REGEX to select
96 more than one header line to be scanned. CODE is a routine which
97 is called for each field in the header. The CODE is called with
98 the header as first, and the field as second argument. If the
99 CODE returns true, the message is selected.
100
101 in => 'HEAD'|'BODY'|'MESSAGE'
102 label => STRING
103 limit => NUMBER
104 log => LEVEL
105 logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'
106 match => STRING|REGEX|CODE
107 The pattern to be search for can be a REGular EXpression, or a
108 STRING. In both cases, the match succeeds if it is found
109 anywhere within the selected fields.
110
111 With a CODE reference, that function will be called each field or
112 body-line. When the result is true, the details are delivered.
113 The call formats are
114
115 $code->($head, $field); # for HEAD searches
116 $code->($body, $linenr, $line); # for BODY searches
117
118 The $head resp $body are one message's head resp. body object.
119 The $field is a header line which matches. The $line and $linenr
120 tell the matching line in the body.
121
122 Be warned that when you search in "MESSAGE" the code must accept
123 both formats.
124
125 multiparts => BOOLEAN
126 trace => LEVEL
127
128 Searching
129 $obj->inBody(PART, BODY)
130 See "Searching" in Mail::Box::Search
131
132 $obj->inHead(PART, HEAD)
133 See "Searching" in Mail::Box::Search
134
135 $obj->search(FOLDER|THREAD|MESSAGE|ARRAY-OF-MESSAGES)
136 See "Searching" in Mail::Box::Search
137
138 $obj->searchPart(PART)
139 See "Searching" in Mail::Box::Search
140
141 The Results
142 $obj->printMatch([FILEHANDLE], HASH)
143 See "The Results" in Mail::Box::Search
144
145 $obj->printMatchedBody(FILEHANDLE, MATCH)
146 $obj->printMatchedHead(FILEHANDLE, MATCH)
147
148 Error handling
149 $obj->AUTOLOAD
150 See "Error handling" in Mail::Reporter
151
152 $obj->addReport(OBJECT)
153 See "Error handling" in Mail::Reporter
154
155 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
156 Mail::Box::Search::Grep->defaultTrace([LEVEL]|[LOGLEVEL,
157 TRACELEVEL]|[LEVEL, CALLBACK])
158
159 See "Error handling" in Mail::Reporter
160
161 $obj->errors
162 See "Error handling" in Mail::Reporter
163
164 $obj->log([LEVEL [,STRINGS]])
165 Mail::Box::Search::Grep->log([LEVEL [,STRINGS]])
166
167 See "Error handling" in Mail::Reporter
168
169 $obj->logPriority(LEVEL)
170 Mail::Box::Search::Grep->logPriority(LEVEL)
171
172 See "Error handling" in Mail::Reporter
173
174 $obj->logSettings
175 See "Error handling" in Mail::Reporter
176
177 $obj->notImplemented
178 See "Error handling" in Mail::Reporter
179
180 $obj->report([LEVEL])
181 See "Error handling" in Mail::Reporter
182
183 $obj->reportAll([LEVEL])
184 See "Error handling" in Mail::Reporter
185
186 $obj->trace([LEVEL])
187 See "Error handling" in Mail::Reporter
188
189 $obj->warnings
190 See "Error handling" in Mail::Reporter
191
192 Cleanup
193 $obj->DESTROY
194 See "Cleanup" in Mail::Reporter
195
196 $obj->inGlobalDestruction
197 See "Cleanup" in Mail::Reporter
198
200 Error: Package $package does not implement $method.
201 Fatal error: the specific package (or one of its superclasses) does
202 not implement this method where it should. This message means that
203 some other related classes do implement this method however the
204 class at hand does not. Probably you should investigate this and
205 probably inform the author of the package.
206
208 This module is part of Mail-Box distribution version 2.097, built on
209 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
210
212 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
213 ChangeLog.
214
215 This program is free software; you can redistribute it and/or modify it
216 under the same terms as Perl itself. See
217 http://www.perl.com/perl/misc/Artistic.html
218
219
220
221perl v5.12.3 2011-01-26 Mail::Box::Search::Grep(3)