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       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

DIAGNOSTICS

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

LICENSE

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)