=head1 NAME
Mail::Box::Search -
select
messages within a mail box
=head1 INHERITANCE
Mail::Box::Search
is a Mail::Reporter
Mail::Box::Search is extended by
Mail::Box::Search::Grep
Mail::Box::Search::SpamAssassin
Mail::Server::IMAP4::Search
=head1 SYNOPSIS
my
$mgr
= Mail::Box::Manager->new;
my
$folder
=
$mgr
->
open
(
'Inbox'
);
my
$filter
= Mail::Box::Search::[something]->new;
my
@msgs
=
$filter
->search(
$folder
, ...);
if
(
$filter
->search(
$message
)) {...}
=head1 DESCRIPTION
This C<Mail::Box::Search> class is the base class
for
various message scan
algorithms. The selected messages can be labeled. Boolean operations on
messages are supported.
Currently implemented searches:
=over 4
=item L<Mail::Box::Search::Grep|Mail::Box::Search::Grep>
Match header or body against a regular expression in a UNIX C<
grep
> like
fashion.
=item L<Mail::Box::Search::SpamAssassin|Mail::Box::Search::SpamAssassin>
Try to detect spam, using Mail::SpamAssassin.
=item Mail::Box::Search::IMAP
Search an IMAP folder
for
special interface IMAP folders provide
for
it.
UNDER CONSTRUCTION till L<Mail::Transport::IMAP4|Mail::Transport::IMAP4> is complete.
=back
=head1 METHODS
=head2 Constructors
Mail::Box::Search-E<gt>B<new>(OPTIONS)
=over 4
Create a filter.
Option --Defined in --Default
binaries <false>
decode <true>
delayed <true>
deleted <false>
deliver
undef
in
'BODY'
label
undef
limit 0
log
Mail::Reporter
'WARNINGS'
logical
'REPLACE'
multiparts <true>
trace Mail::Reporter
'WARNINGS'
.
binaries
=> BOOLEAN
=over 4
Whether to include binary bodies in the search.
=back
.
decode
=> BOOLEAN
=over 4
Decode the messages
before
the search takes place. Even plain text messages
can be encoded,
for
instance as C<quoted-printable>, which may disturb the
results. However, decoding will slow-down the search.
=back
.
delayed
=> BOOLEAN
=over 4
Include the delayed messages (which will be parsed) in the search. If you
set this to false, you may find fewer hits.
=back
.
deleted
=> BOOLEAN
=over 4
In most cases, you will not be interested in results which are
found in messages flagged to be deleted. However,
with
this option
you can specify you want them to be searched too.
=back
.
deliver
=>
undef
|CODE|
'DELETE'
=over 4
The exact functionality of this parameter differs per search method, so
read
the applicable man-page. In any case C<
undef
> means that details
are not collected
for
this search, which is the fastest search.
C<DELETE> will flag the message to be flagged
for
deletion.
You may also specify your own CODE reference. With an reference
to an array, the information about the matches is collected as a list
of hashes, one hash per match.
=back
.
in
=>
'HEAD'
|
'BODY'
|
'MESSAGE'
=over 4
Where to look
for
the match.
=back
.
label
=> STRING
=over 4
Mark all selected messages
with
the specified STRING. If this field is
not specified, the message will not get a label; search() also returns
a list of selected messages.
=back
.
limit
=> NUMBER
=over 4
Limit the search to the specified NUMBER of messages. When the NUMBER
is positive, the search starts at the first message in the folder or
thread. A negative NUMBER starts at the end of the folder. If the limit
is set to zero, there is
no
limit.
=back
.
log
=> LEVEL
.
logical
=>
'REPLACE'
|
'AND'
|
'OR'
|
'NOT'
|
'AND NOT'
|
'OR NOT'
=over 4
Only applicable in combination
with
a C<label>.
How to handle the existing labels. In case of C<REPLACE>, messages
which already are carrying the label are stripped from their
selection (
unless
they match again). With C<AND>, the message must
be selected by this search and already carry the label, otherwise the
label will not be set. Specify C<OR> to have newly selected messages
added to the set of already selected messages.
C<NOT> is true
for
messages which
do
not fulfil the search. The
details output will still contain the places where the match was
found, however those messages will complementary set of messages will
be labeled and returned.
=back
.
multiparts
=> BOOLEAN
=over 4
Are multiparts to be included in the search results? Some MUA have
problems handling details received from the search. When this flag
is turned off, the body of multiparts will be ignored. The parts
search will include the preamble and epilogue.
=back
.
trace
=> LEVEL
=back
=head2 Searching
$obj
-E<gt>B<inBody>(PART, BODY)
=over 4
Tests whether body contains the requesting information. See the
specific search module
for
its parameters.
=back
$obj
-E<gt>B<inHead>(PART, HEAD)
=over 4
Tests whether header contains the requesting information. See the
specific search module
for
its parameters.
=back
$obj
-E<gt>B<search>(FOLDER|THREAD|MESSAGE|ARRAY-OF-MESSAGES)
=over 4
Check which messages from the FOLDER (Mail::Box) match the
search parameters. The matched messages are returned as list. You
can also specify a THREAD (a L<Mail::Box::Thread::Node|Mail::Box::Thread::Node>), one single
MESSAGE (a L<Mail::Message|Mail::Message>), or an array of messages.
Sometimes we know how only one match is needed. In this case, this
searching will stop at the first match. For instance,
when
C<limit> is C<-1>
or C<1>, or
when
the search in done in
scalar
context.
example:
my
$grep
= Mail::Box::Search::Grep->new
(
match
=>
'My Name Is Nobody'
,
deliver
=>
'PRINT'
);
$grep
->search(
$folder
);
my
$message
=
$folder
->message(3);
$grep
->search(
$message
);
my
$thread
=
$message
->threadStart;
$grep
->search(
$thread
);
=back
$obj
-E<gt>B<searchPart>(PART)
=over 4
Search this message PART
for
matches.
=back
=head2 The Results
$obj
-E<gt>B<printMatch>([FILEHANDLE], HASH)
=over 4
Print the information about the match (see L<new(deliver)|Mail::Box::Search/
"METHODS"
>) in
some understandable way. If
no
file handle
is specified, the output will go to the selected filehandle (see
C<perldoc -f
select
>).
=back
=head2 Error handling
$obj
-E<gt>B<AUTOLOAD>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<addReport>(OBJECT)
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Box::Search-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<errors>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<
log
>([LEVEL [,STRINGS]])
Mail::Box::Search-E<gt>B<
log
>([LEVEL [,STRINGS]])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logPriority>(LEVEL)
Mail::Box::Search-E<gt>B<logPriority>(LEVEL)
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logSettings>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<notImplemented>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<report>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<reportAll>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<trace>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<warnings>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
=head2 Cleanup
$obj
-E<gt>B<DESTROY>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
$obj
-E<gt>B<inGlobalDestruction>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
=head1 DIAGNOSTICS
Error: Cannot search in body.
=over 4
Th search object does not implement L<inBody()|Mail::Box::Search/
"Searching"
>, and can therefore
not search a message body.
=back
Error: Cannot search in header.
=over 4
Th search object does not implement L<inHead()|Mail::Box::Search/
"Searching"
>, and can therefore
not search a message header.
=back
Error: Don't know how to deliver via results in
$way
.
=over 4
The search results cannot be delivered in the specific way, because that is
not a
defined
alternative.
=back
Error: Package
$package
does not implement
$method
.
=over 4
Fatal error: the specific
package
(or one of its superclasses) does not
implement this method where it should. This message means that some other
related classes
do
implement this method however the class at hand does
not. Probably you should investigate this and probably inform the author
of the
package
.
=back
Error: Search in BODY, HEAD or MESSAGE not
$in
.
=over 4
The C<in> option defines only three names.
=back
=head1 SEE ALSO
This module is part of Mail-Box distribution version 2.086,
=head1 LICENSE
Copyrights 2001-2008 by Mark Overmeer. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.