NAME

Mail::Reporter - manage errors and traces for various Mail::* modules

SYNOPSIS

$folder->log(WARNING => 'go away');
print $folder->trace;        # current level
$folder->trace('PROGRESS');  # set level
print $folder->errors;
print $folder->report('PROGRESS');

DESCRIPTION

Read Mail::Box-Overview first. There are a few objects which produce error messages, but which will not break the program. For instance, an erroneous message doesn't break a whole folder.

The Mail::Reporter class is the base class for each object which can produce errors, and can be configured for each mailbox, mail message, and mail manager separately.

METHOD INDEX

The general methods for Mail::Reporter objects:

errors                               report [LEVEL]
log [LEVEL [,STRINGS]]               reportAll [LEVEL]
new OPTIONS                          trace [LEVEL]

The extra methods for extension writers:

AUTOLOAD                             logPriority LEVEL
DESTROY                              logSettings
inGlobalDestruction                  notImplemented

METHODS

The Mail::Reporter class is the base for nearly all other objects. It can store and report problems, and contains the general constructor new().

new OPTIONS

This error container is also the base constructor for all modules, (as long as there is no need for an other base object) The constructor accepts the following arguments related to the errors:

OPTION         DEFINED BY             DEFAULT
log            Mail::Reporter         'WARNINGS'
trace          Mail::Reporter         'WARNINGS'

• log => LEVEL

  Log messages which have a priority higher or equal to the specified level are stored internally and can be retrieved later. The default log level is WARNINGS,

  Known levels are 'INTERNAL', 'ERRORS', 'WARNINGS', 'PROGRESS', 'NOTICES' 'DEBUG', and 'NONE'. The PROGRESS level relates to the reading and writing of folders. NONE only will cause only INTERNAL errors to be logged.

  By the way: ERROR is an alias for ERRORS, as WARNING is an alias for WARNINGS, and NOTICE for NOTICES.

• trace => LEVEL

  Trace messages which have a level higher or equal to the specified level are directly printed using warn. The default trace-level is WARNINGS.

trace [LEVEL]

Change the trace level of the object. It returns the number which is internally used to represent the level.

log [LEVEL [,STRINGS]]

This method has three uses. Without any argument, it returns the name of the current log level. With one argument, a new level of logging detail is set. With more arguments, it is a report which may need to be logged or traced.

Each log-entry has a LEVEL (see above), and a text string which will be constructed by joining the STRINGS. If there is no newline, it will be added.

Examples:

print $message->log;      # may print   NOTICE
$message->log('ERRORS');  # sets a new level

$message->log(WARNING => "This message is too large.");
$folder ->log(NOTICE  => "Cannot read from file $filename.");
$manager->log(DEBUG   => "Hi there!", reverse sort @l);

report [LEVEL]

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.

Examples:

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";
}

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.

Example:

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";
    }
}

errors

warnings

Equivalent to

$folder->report('ERRORS');     # and
$folder->report('WARNINGS');

METHODS for extension writers

notImplemented

A special case of the above log(), which logs a INTERNAL-error and then croaks. This is used by extension writers.

logPriority LEVEL

(Class and instance method) Returns the priority of the named level as numeric value. The higher the number, the more important the message. Only messages about INTERNAL problems are more important than NONE.

logSettings

Returns a list of (key => value) pairs which can be used to initiate a new object with the same log-settings as this one.

Example:

$head->new($folder->logSettings);

inGlobalDestruction

Returns whether the program is breaking down. This is used in DESTROY, where during global destructions references cannot be used.

DESTROY

Cleanup.

AUTOLOAD

produce a nice warning if the sub-classes cannot resolve a method.

SEE ALSO

Mail::Box-Overview

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version 2.003.

Copyright (c) 2001 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.