.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::Box::Search 3pm"
.TH Mail::Box::Search 3pm "2014-08-24" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Box::Search \- select messages within a mail box
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& 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
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use Mail::Box::Manager;
\& my $mgr    = Mail::Box::Manager\->new;
\& my $folder = $mgr\->open(\*(AqInbox\*(Aq);
\&
\& my $filter = Mail::Box::Search::[something]\->new;
\& my @msgs   = $filter\->search($folder, ...);
\& if($filter\->search($message)) {...}
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This \f(CW\*(C`Mail::Box::Search\*(C'\fR class is the base class for various message scan
algorithms.  The selected messages can be labeled.  Boolean operations on
messages are supported.
.PP
Currently implemented searches:
.IP "Mail::Box::Search::Grep" 4
.IX Item "Mail::Box::Search::Grep"
Match header or body against a regular expression in a \s-1UNIX \s0\f(CW\*(C`grep\*(C'\fR like
fashion.
.IP "Mail::Box::Search::SpamAssassin" 4
.IX Item "Mail::Box::Search::SpamAssassin"
Try to detect spam, using Mail::SpamAssassin.
.IP "Mail::Box::Search::IMAP" 4
.IX Item "Mail::Box::Search::IMAP"
Search an \s-1IMAP\s0 folder for special interface \s-1IMAP\s0 folders provide for it.
\&\s-1UNDER CONSTRUCTION\s0 till Mail::Transport::IMAP4 is complete.
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Mail::Reporter.
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Mail::Reporter.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Mail::Reporter.
.IP "Mail::Box::Search\->\fBnew\fR(%options)" 4
.IX Item "Mail::Box::Search->new(%options)"
Create a filter.
.Sp
.Vb 10
\& \-Option    \-\-Defined in     \-\-Default
\&  binaries                     <false>
\&  decode                       <true>
\&  delayed                      <true>
\&  deleted                      <false>
\&  deliver                      undef
\&  in                           \*(AqBODY\*(Aq
\&  label                        undef
\&  limit                        0
\&  log         Mail::Reporter   \*(AqWARNINGS\*(Aq
\&  logical                      \*(AqREPLACE\*(Aq
\&  multiparts                   <true>
\&  trace       Mail::Reporter   \*(AqWARNINGS\*(Aq
.Ve
.RS 4
.IP "binaries => \s-1BOOLEAN\s0" 2
.IX Item "binaries => BOOLEAN"
Whether to include binary bodies in the search.
.IP "decode => \s-1BOOLEAN\s0" 2
.IX Item "decode => BOOLEAN"
Decode the messages before the search takes place.  Even plain text messages
can be encoded, for instance as \f(CW\*(C`quoted\-printable\*(C'\fR, which may disturb the
results.  However, decoding will slow-down the search.
.IP "delayed => \s-1BOOLEAN\s0" 2
.IX Item "delayed => BOOLEAN"
Include the delayed messages (which will be parsed) in the search.  If you
set this to false, you may find fewer hits.
.IP "deleted => \s-1BOOLEAN\s0" 2
.IX Item "deleted => BOOLEAN"
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.
.IP "deliver => undef|CODE|'\s-1DELETE\s0'" 2
.IX Item "deliver => undef|CODE|'DELETE'"
The exact functionality of this parameter differs per search method, so
read the applicable man-page.  In any case \f(CW\*(C`undef\*(C'\fR means that details
are not collected for this search, which is the fastest search.
.Sp
\&\f(CW\*(C`DELETE\*(C'\fR will flag the message to be flagged for deletion.
You may also specify your own \s-1CODE\s0 reference.  With an reference
to an array, the information about the matches is collected as a list
of hashes, one hash per match.
.IP "in => '\s-1HEAD\s0'|'\s-1BODY\s0'|'\s-1MESSAGE\s0'" 2
.IX Item "in => 'HEAD'|'BODY'|'MESSAGE'"
Where to look for the match.
.IP "label => \s-1STRING\s0" 2
.IX Item "label => STRING"
Mark all selected messages with the specified \s-1STRING. \s0 If this field is
not specified, the message will not get a label; \fIsearch()\fR also returns
a list of selected messages.
.IP "limit => \s-1NUMBER\s0" 2
.IX Item "limit => NUMBER"
Limit the search to the specified \s-1NUMBER\s0 of messages.  When the \s-1NUMBER\s0
is positive, the search starts at the first message in the folder or
thread.  A negative \s-1NUMBER\s0 starts at the end of the folder.  If the limit
is set to zero, there is no limit.
.IP "log => \s-1LEVEL\s0" 2
.IX Item "log => LEVEL"
.PD 0
.IP "logical => '\s-1REPLACE\s0'|'\s-1AND\s0'|'\s-1OR\s0'|'\s-1NOT\s0'|'\s-1AND NOT\s0'|'\s-1OR NOT\s0'" 2
.IX Item "logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'"
.PD
Only applicable in combination with a \f(CW\*(C`label\*(C'\fR.
How to handle the existing labels.  In case of \f(CW\*(C`REPLACE\*(C'\fR, messages
which already are carrying the label are stripped from their
selection (unless they match again).  With \f(CW\*(C`AND\*(C'\fR, the message must
be selected by this search and already carry the label, otherwise the
label will not be set.  Specify \f(CW\*(C`OR\*(C'\fR to have newly selected messages
added to the set of already selected messages.
.Sp
\&\f(CW\*(C`NOT\*(C'\fR 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.
.IP "multiparts => \s-1BOOLEAN\s0" 2
.IX Item "multiparts => BOOLEAN"
Are multiparts to be included in the search results?  Some \s-1MUA\s0 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.
.IP "trace => \s-1LEVEL\s0" 2
.IX Item "trace => LEVEL"
.RE
.RS 4
.RE
.SS "Searching"
.IX Subsection "Searching"
.PD 0
.ie n .IP "$obj\->\fBinBody\fR($part, $body)" 4
.el .IP "\f(CW$obj\fR\->\fBinBody\fR($part, \f(CW$body\fR)" 4
.IX Item "$obj->inBody($part, $body)"
.PD
Tests whether body contains the requesting information.  See the
specific search module for its parameters.
.ie n .IP "$obj\->\fBinHead\fR($part, $head)" 4
.el .IP "\f(CW$obj\fR\->\fBinHead\fR($part, \f(CW$head\fR)" 4
.IX Item "$obj->inHead($part, $head)"
Tests whether header contains the requesting information.  See the
specific search module for its parameters.
.ie n .IP "$obj\->\fBsearch\fR($folder|$thread|$message|ARRAY)" 4
.el .IP "\f(CW$obj\fR\->\fBsearch\fR($folder|$thread|$message|ARRAY)" 4
.IX Item "$obj->search($folder|$thread|$message|ARRAY)"
Check which messages from the \f(CW$folder\fR (Mail::Box) match the
search parameters.  The matched messages are returned as list.  You
can also specify a \f(CW$thread\fR (a Mail::Box::Thread::Node), one single
\&\f(CW$message\fR (a Mail::Message), or an \s-1ARRAY\s0 of messages.
.Sp
Sometimes we know how only one match is needed.  In this case, this
searching will stop at the first match.  For instance, when \f(CW\*(C`limit\*(C'\fR is \f(CW\*(C`\-1\*(C'\fR
or \f(CW1\fR, or when the search in done in scalar context.
.Sp
example:
.Sp
.Vb 4
\& my $grep = Mail::Box::Search::Grep\->new
\&  ( match   => \*(AqMy Name Is Nobody\*(Aq
\&  , deliver => \*(AqPRINT\*(Aq
\&  );
\&
\& $grep\->search($folder);
\&
\& my $message = $folder\->message(3);
\& $grep\->search($message);
\&
\& my $thread  = $message\->threadStart;
\& $grep\->search($thread);
.Ve
.ie n .IP "$obj\->\fBsearchPart\fR($part)" 4
.el .IP "\f(CW$obj\fR\->\fBsearchPart\fR($part)" 4
.IX Item "$obj->searchPart($part)"
Search this message \f(CW$part\fR for matches.
.SS "The Results"
.IX Subsection "The Results"
.ie n .IP "$obj\->\fBprintMatch\fR( [$fh], \s-1HASH \s0)" 4
.el .IP "\f(CW$obj\fR\->\fBprintMatch\fR( [$fh], \s-1HASH \s0)" 4
.IX Item "$obj->printMatch( [$fh], HASH )"
Print the information about the match (see new(deliver)) in
some understandable way.  If no file handle
is specified, the output will go to the selected filehandle (see
\&\f(CW\*(C`perldoc \-f select\*(C'\fR).
.SS "Error handling"
.IX Subsection "Error handling"
Extends \*(L"Error handling\*(R" in Mail::Reporter.
.ie n .IP "$obj\->\fB\s-1AUTOLOAD\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1AUTOLOAD\s0\fR()" 4
.IX Item "$obj->AUTOLOAD()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBaddReport\fR($object)" 4
.el .IP "\f(CW$obj\fR\->\fBaddReport\fR($object)" 4
.IX Item "$obj->addReport($object)"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "\f(CW$obj\fR\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD 0
.ie n .IP "Mail::Box::Search\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "Mail::Box::Search\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "Mail::Box::Search->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBerrors\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBerrors\fR()" 4
.IX Item "$obj->errors()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlog\fR( [$level, [$strings]] )" 4
.el .IP "\f(CW$obj\fR\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "$obj->log( [$level, [$strings]] )"
.PD 0
.IP "Mail::Box::Search\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "Mail::Box::Search->log( [$level, [$strings]] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlogPriority\fR($level)" 4
.el .IP "\f(CW$obj\fR\->\fBlogPriority\fR($level)" 4
.IX Item "$obj->logPriority($level)"
.PD 0
.IP "Mail::Box::Search\->\fBlogPriority\fR($level)" 4
.IX Item "Mail::Box::Search->logPriority($level)"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlogSettings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlogSettings\fR()" 4
.IX Item "$obj->logSettings()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBnotImplemented\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnotImplemented\fR()" 4
.IX Item "$obj->notImplemented()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBreport\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreport\fR( [$level] )" 4
.IX Item "$obj->report( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBreportAll\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreportAll\fR( [$level] )" 4
.IX Item "$obj->reportAll( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBtrace\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBtrace\fR( [$level] )" 4
.IX Item "$obj->trace( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBwarnings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBwarnings\fR()" 4
.IX Item "$obj->warnings()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.SS "Cleanup"
.IX Subsection "Cleanup"
Extends \*(L"Cleanup\*(R" in Mail::Reporter.
.ie n .IP "$obj\->\fB\s-1DESTROY\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1DESTROY\s0\fR()" 4
.IX Item "$obj->DESTROY()"
Inherited, see \*(L"Cleanup\*(R" in Mail::Reporter
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "Error: Cannot search in body." 4
.IX Item "Error: Cannot search in body."
Th search object does not implement \fIinBody()\fR, and can therefore
not search a message body.
.IP "Error: Cannot search in header." 4
.IX Item "Error: Cannot search in header."
Th search object does not implement \fIinHead()\fR, and can therefore
not search a message header.
.ie n .IP "Error: Don't know how to deliver via results in $way." 4
.el .IP "Error: Don't know how to deliver via results in \f(CW$way\fR." 4
.IX Item "Error: Don't know how to deliver via results in $way."
The search results cannot be delivered in the specific way, because that is
not a defined alternative.
.ie n .IP "Error: Package $package does not implement $method." 4
.el .IP "Error: Package \f(CW$package\fR does not implement \f(CW$method\fR." 4
.IX Item "Error: Package $package does not implement $method."
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.
.ie n .IP "Error: Search in \s-1BODY, HEAD\s0 or \s-1MESSAGE\s0 not $in." 4
.el .IP "Error: Search in \s-1BODY, HEAD\s0 or \s-1MESSAGE\s0 not \f(CW$in\fR." 4
.IX Item "Error: Search in BODY, HEAD or MESSAGE not $in."
The \f(CW\*(C`in\*(C'\fR option defines only three names.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Mail-Box distribution version 2.117,
built on August 24, 2014. Website: \fIhttp://perl.overmeer.net/mailbox/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2001\-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR