The Mail::Reporter
class is the base for nearly all other
objects. It can store and report problems, and contains the general
constructor new().
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 %options related to error reports.
Option | Default |
---|---|
log |
|
trace |
|
By default, produce a nice warning if the sub-classes cannot resolve a method.
Add the report from other $object 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.
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 WARNINGS
.
This method has three different uses. When one argument is specified, that $level is set for both loglevel as tracelevel.
With two arguments, the second determines which configuration you like. If the second argument is a CODE reference, you install a $callback. The loglevel will be set to NONE, and all warnings produced in your program will get passed to the $callback function. That function will get the problem level, the object or class which reports the problem, and the problem text passed as arguments.
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!
my ($loglevel, $tracelevel) = Mail::Reporter->defaultTrace; Mail::Reporter->defaultTrace('NOTICES'); my ($l, $t) = Mail::Reporter->defaultTrace('WARNINGS', 'DEBUG'); print $l; # prints "WARNING" (no S!) print $l+0; # prints "4" print "Auch" if $l >= $self->logPriority('ERROR'); Mail::Reporter->defaultTrace('NONE'); # silence all reports $folder->defaultTrace('DEBUG'); # Still set as global default! $folder->trace('DEBUG'); # local default
Mail::Reporter->defaultTrace
Equivalent to
$folder->report('ERRORS')
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 dualvar
for
an explanation.
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.
As class method, only a message can be passed. The global configuration value set with defaultTrace() is used to decide whether the message is shown or ignored.
Each log-entry has a $level and a text string which will be constructed by joining the $strings. If there is no newline, it will be added.
print $message->log; # may print "NOTICE" print $message->log +0; # may print "3" $message->log('ERRORS'); # 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 => 'Unknown');
One error level (log or trace) has more than one representation: a
numeric value and one or more strings. For instance, 4
, 'WARNING'
,
and 'WARNINGS'
are all the same. You can specify any of these,
and in return you get a dualvar (see Scalar::Util method dualvar
)
back, which contains the number and the singular form.
The higher the number, the more important the message.
Only messages about INTERNAL
problems are more important than NONE
.
my $r = Mail::Reporter->logPriority('WARNINGS'); my $r = Mail::Reporter->logPriority('WARNING'); # same my $r = Mail::Reporter->logPriority(4); # same, deprecated print $r; # prints 'WARNING' (no S!) print $r + 0; # prints 4 if($r < Mail::Reporter->logPriority('ERROR')) {..} # true
Returns a list of (key =
value)> pairs which can be used to initiate
a new object with the same log-settings as this one.
$head->new($folder->logSettings);
A special case of log(), which logs a INTERNAL
-error
and then croaks. This is used by extension writers.
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.
Get logged reports, as list of strings. If a $level is specified, the log for that level is returned.
In case no $level is specified, you get all messages each as reference to a tuple with level and message.
my @warns = $message->report('WARNINGS'); # previous indirectly callable with my @warns = $msg->warnings; print $folder->report('ERRORS'); if($folder->report('DEBUG')) {...} my @reports = $folder->report; foreach (@reports) { my ($level, $text) = @$_; print "$level report: $text"; }
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.
my $folder = Mail::Box::Manager->new->open(folder => 'inbox'); my @reports = $folder->reportAll; foreach (@reports) { my ($object, $level, $text) = @$_; if($object->isa('Mail::Box')) { print "Folder $object: $level: $message"; } elsif($object->isa('Mail::Message') { print "Message ".$object->seqnr.": $level: $message"; } }
Change the trace $level 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 logPriority().
Equivalent to
$folder->report('WARNINGS')
Cleanup the object.