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
29       operations 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
43           complete.
44
45       Extends "DESCRIPTION" in Mail::Reporter.
46

METHODS

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

DIAGNOSTICS

230       Error: Cannot search in body.
231           Th search object does not implement inBody(), and can therefore not
232           search a message body.
233
234       Error: Cannot search in header.
235           Th search object does not implement inHead(), and can therefore not
236           search a message header.
237
238       Error: Don't know how to deliver via results in $way.
239           The search results cannot be delivered in the specific way, because
240           that is not a defined alternative.
241
242       Error: Package $package does not implement $method.
243           Fatal error: the specific package (or one of its superclasses) does
244           not implement this method where it should. This message means that
245           some other related classes do implement this method however the
246           class at hand does not.  Probably you should investigate this and
247           probably inform the author of the package.
248
249       Error: Search in BODY, HEAD or MESSAGE not $in.
250           The "in" option defines only three names.
251

SEE ALSO

253       This module is part of Mail-Box distribution version 3.010, built on
254       July 18, 2023. Website: http://perl.overmeer.net/CPAN/
255

LICENSE

257       Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
258       ChangeLog.
259
260       This program is free software; you can redistribute it and/or modify it
261       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
262
263
264
265perl v5.38.0                      2023-07-24              Mail::Box::Search(3)
Impressum