.\" 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::Reporter 3pm"
.TH Mail::Reporter 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::Reporter \- base\-class and error reporter for Mail::Box
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 10
\& Mail::Reporter is extended by
\&   Mail::Box
\&   Mail::Box::Collection
\&   Mail::Box::Identity
\&   Mail::Box::Locker
\&   Mail::Box::MH::Index
\&   Mail::Box::MH::Labels
\&   Mail::Box::Manager
\&   Mail::Box::Parser
\&   Mail::Box::Search
\&   Mail::Box::Thread::Manager
\&   Mail::Box::Thread::Node
\&   Mail::Message
\&   Mail::Message::Body
\&   Mail::Message::Body::Delayed
\&   Mail::Message::Convert
\&   Mail::Message::Field
\&   Mail::Message::Field::Attribute
\&   Mail::Message::Head
\&   Mail::Message::Head::FieldGroup
\&   Mail::Message::TransferEnc
\&   Mail::Server
\&   Mail::Transport
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& $folder\->log(WARNING => \*(Aqgo away\*(Aq);
\& print $folder\->trace;        # current level
\& $folder\->trace(\*(AqPROGRESS\*(Aq);  # set level
\& print $folder\->errors;
\& print $folder\->report(\*(AqPROGRESS\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Mail::Reporter\*(C'\fR class is the base class for all classes, except
Mail::Message::Field::Fast because it would become slow...  This
base class is used during initiation of the objects, and for configuring
and logging error messages.
.SH "METHODS"
.IX Header "METHODS"
The \f(CW\*(C`Mail::Reporter\*(C'\fR class is the base for nearly all other
objects.  It can store and report problems, and contains the general
constructor \fInew()\fR.
.SS "Constructors"
.IX Subsection "Constructors"
.IP "Mail::Reporter\->\fBnew\fR(%options)" 4
.IX Item "Mail::Reporter->new(%options)"
This error container is also the base constructor for all modules, (as long
as there is no need for another base object)  The constructor always accepts
the following \f(CW%options\fR related to error reports.
.Sp
.Vb 3
\& \-Option\-\-Default
\&  log     \*(AqWARNINGS\*(Aq
\&  trace   \*(AqWARNINGS\*(Aq
.Ve
.RS 4
.IP "log => \s-1LEVEL\s0" 2
.IX Item "log => LEVEL"
Log messages which have a priority higher or equal to the specified
level are stored internally and can be retrieved later.  The global
default for this option can be changed with \fIdefaultTrace()\fR.
.Sp
Known levels are \f(CW\*(C`INTERNAL\*(C'\fR, \f(CW\*(C`ERRORS\*(C'\fR, \f(CW\*(C`WARNINGS\*(C'\fR, \f(CW\*(C`PROGRESS\*(C'\fR,
\&\f(CW\*(C`NOTICES\*(C'\fR \f(CW\*(C`DEBUG\*(C'\fR, and \f(CW\*(C`NONE\*(C'\fR.  The \f(CW\*(C`PROGRESS\*(C'\fR level relates to
the reading and writing of folders.  \f(CW\*(C`NONE\*(C'\fR will cause only \f(CW\*(C`INTERNAL\*(C'\fR
errors to be logged.
By the way: \f(CW\*(C`ERROR\*(C'\fR is an alias for \f(CW\*(C`ERRORS\*(C'\fR, as \f(CW\*(C`WARNING\*(C'\fR is an alias
for \f(CW\*(C`WARNINGS\*(C'\fR, and \f(CW\*(C`NOTICE\*(C'\fR for \f(CW\*(C`NOTICES\*(C'\fR.
.IP "trace => \s-1LEVEL\s0" 2
.IX Item "trace => LEVEL"
Trace messages which have a level higher or equal to the specified level
are directly printed using warn.  The global default for this option can
be changed with \fIdefaultTrace()\fR.
.RE
.RS 4
.RE
.SS "Error handling"
.IX Subsection "Error handling"
.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()"
By default, produce a nice warning if the sub-classes cannot resolve
a method.
.ie n .IP "$obj\->\fBaddReport\fR($object)" 4
.el .IP "\f(CW$obj\fR\->\fBaddReport\fR($object)" 4
.IX Item "$obj->addReport($object)"
Add the report from other \f(CW$object\fR to the report of this object. This is
useful when complex actions use temporary objects which are not returned
to the main application but where the main application would like to know
about any problems.
.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::Reporter\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "Mail::Reporter\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "Mail::Reporter->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD
Reports the default log and trace level which is used for object as list
of two elements.  When not explicitly set, both are set to \f(CW\*(C`WARNINGS\*(C'\fR.
.Sp
This method has three different uses. When one argument is specified, that
\&\f(CW$level\fR is set for both loglevel as tracelevel.
.Sp
With two arguments, the second determines which configuration you like.  If
the second argument is a \s-1CODE\s0 reference, you install a \f(CW$callback\fR.  The loglevel
will be set to \s-1NONE,\s0 and all warnings produced in your program will get
passed to the \f(CW$callback\fR function.  That function will get the problem level,
the object or class which reports the problem, and the problem text passed
as arguments.
.Sp
In any case two values are returned: the first is the log level, the
second represents the trace level.  Both are special variables: in numeric
context they deliver a value (the internally used value), and in string
context the string name.  Be warned that the string is always in singular
form!
.Sp
example: setting loglevels
.Sp
.Vb 2
\& my ($loglevel, $tracelevel) = Mail::Reporter\->defaultTrace;
\& Mail::Reporter\->defaultTrace(\*(AqNOTICES\*(Aq);
\&
\& my ($l, $t) = Mail::Reporter\->defaultTrace(\*(AqWARNINGS\*(Aq, \*(AqDEBUG\*(Aq);
\& print $l;     # prints "WARNING"  (no S!)
\& print $l+0;   # prints "4"
\& print "Auch" if $l >= $self\->logPriority(\*(AqERROR\*(Aq);
\&
\& Mail::Reporter\->defaultTrace(\*(AqNONE\*(Aq);  # silence all reports
\&
\& $folder\->defaultTrace(\*(AqDEBUG\*(Aq);   # Still set as global default!
\& $folder\->trace(\*(AqDEBUG\*(Aq);          # local default
.Ve
.Sp
example: installing a callback
.Sp
.Vb 1
\& Mail::Reporter\->defaultTrace
.Ve
.ie n .IP "$obj\->\fBerrors\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBerrors\fR()" 4
.IX Item "$obj->errors()"
Equivalent to
.Sp
.Vb 1
\& $folder\->report(\*(AqERRORS\*(Aq)
.Ve
.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::Reporter\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "Mail::Reporter->log( [$level, [$strings]] )"
.PD
As instance method this function has three different purposes.  Without
any argument, it returns one scalar containing the number which is internally
used to represent the current log level, and the textual representation of
the string at the same time. See Scalar::Util method \f(CW\*(C`dualvar\*(C'\fR for
an explanation.
.Sp
With one argument, a new level of logging detail is set (specify a number
of one of the predefined strings).  With more arguments, it is a report
which may need to be logged or traced.
.Sp
As class method, only a message can be passed.  The global configuration
value set with \fIdefaultTrace()\fR is used to decide whether the message is
shown or ignored.
.Sp
Each log-entry has a \f(CW$level\fR and a text string which will
be constructed by joining the \f(CW$strings\fR.  If there is no newline, it will
be added.
.Sp
example:
.Sp
.Vb 3
\& print $message\->log;      # may print "NOTICE"
\& print $message\->log +0;   # may print "3"
\& $message\->log(\*(AqERRORS\*(Aq);  # sets a new level, returns the numeric value
\&
\& $message\->log(WARNING => "This message is too large.");
\& $folder \->log(NOTICE  => "Cannot read from file $filename.");
\& $manager\->log(DEBUG   => "Hi there!", reverse sort @l);
\&
\& Mail::Message\->log(ERROR => \*(AqUnknown\*(Aq);
.Ve
.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::Reporter\->\fBlogPriority\fR($level)" 4
.IX Item "Mail::Reporter->logPriority($level)"
.PD
One error level (log or trace) has more than one representation: a
numeric value and one or more strings.  For instance, \f(CW4\fR, \f(CW\*(AqWARNING\*(Aq\fR,
and \f(CW\*(AqWARNINGS\*(Aq\fR are all the same.  You can specify any of these,
and in return you get a dualvar (see Scalar::Util method \f(CW\*(C`dualvar\*(C'\fR)
back, which contains the number and the singular form.
.Sp
The higher the number, the more important the message.
Only messages about \f(CW\*(C`INTERNAL\*(C'\fR problems are more important than \f(CW\*(C`NONE\*(C'\fR.
.Sp
example:
.Sp
.Vb 6
\& my $r = Mail::Reporter\->logPriority(\*(AqWARNINGS\*(Aq);
\& my $r = Mail::Reporter\->logPriority(\*(AqWARNING\*(Aq);    # same
\& my $r = Mail::Reporter\->logPriority(4);            # same, deprecated
\& print $r;      # prints \*(AqWARNING\*(Aq  (no S!)
\& print $r + 0;  # prints 4
\& if($r < Mail::Reporter\->logPriority(\*(AqERROR\*(Aq)) {..} # true
.Ve
.ie n .IP "$obj\->\fBlogSettings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlogSettings\fR()" 4
.IX Item "$obj->logSettings()"
Returns a list of \f(CW\*(C`(key =\*(C'\fR value)> pairs which can be used to initiate
a new object with the same log-settings as this one.
.Sp
example:
.Sp
.Vb 1
\& $head\->new($folder\->logSettings);
.Ve
.ie n .IP "$obj\->\fBnotImplemented\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnotImplemented\fR()" 4
.IX Item "$obj->notImplemented()"
A special case of \fIlog()\fR, which logs a \f(CW\*(C`INTERNAL\*(C'\fR\-error
and then croaks.  This is used by extension writers.
.ie n .IP "$obj\->\fBreport\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreport\fR( [$level] )" 4
.IX Item "$obj->report( [$level] )"
Get logged reports, as list of strings.  If a \f(CW$level\fR is specified, the log
for that level is returned.
.Sp
In case no \f(CW$level\fR is specified, you get all messages each as reference
to a tuple with level and message.
.Sp
example:
.Sp
.Vb 3
\& my @warns = $message\->report(\*(AqWARNINGS\*(Aq);
\&   # previous indirectly callable with
\&   my @warns = $msg\->warnings;
\&
\& print $folder\->report(\*(AqERRORS\*(Aq);
\&
\& if($folder\->report(\*(AqDEBUG\*(Aq)) {...}
\&
\& my @reports = $folder\->report;
\& foreach (@reports) {
\&    my ($level, $text) = @$_;
\&    print "$level report: $text";
\& }
.Ve
.ie n .IP "$obj\->\fBreportAll\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreportAll\fR( [$level] )" 4
.IX Item "$obj->reportAll( [$level] )"
Report all messages which were produced by this object and all the objects
which are maintained by this object.  This will return a list of triplets,
each containing a reference to the object which caught the report, the
level of the report, and the message.
.Sp
example:
.Sp
.Vb 4
\& my $folder = Mail::Box::Manager\->new\->open(folder => \*(Aqinbox\*(Aq);
\& my @reports = $folder\->reportAll;
\& foreach (@reports) {
\&    my ($object, $level, $text) = @$_;
\&
\&    if($object\->isa(\*(AqMail::Box\*(Aq)) {
\&       print "Folder $object: $level: $message";
\&    } elsif($object\->isa(\*(AqMail::Message\*(Aq) {
\&       print "Message ".$object\->seqnr.": $level: $message";
\&    }
\& }
.Ve
.ie n .IP "$obj\->\fBtrace\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBtrace\fR( [$level] )" 4
.IX Item "$obj->trace( [$level] )"
Change the trace \f(CW$level\fR of the object. When no arguments are specified, the
current level is returned only.  It will be returned in one scalar which
contains both the number which is internally used to represent the level,
and the string which represents it.  See \fIlogPriority()\fR.
.ie n .IP "$obj\->\fBwarnings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBwarnings\fR()" 4
.IX Item "$obj->warnings()"
Equivalent to
.Sp
.Vb 1
\& $folder\->report(\*(AqWARNINGS\*(Aq)
.Ve
.SS "Cleanup"
.IX Subsection "Cleanup"
.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()"
Cleanup the object.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.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.
.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