NAME

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

CLASS INHERITANCE

Mail::Reporter

Mail::Reporter is extended by Mail::Box 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::Head Mail::Message::Head::ResentGroup Mail::Message::TransferEnc Mail::Transport

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.

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().

Initiation

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 always accepts the following OPTIONS related to error reports.

 OPTION               DEFAULT
 log                  'WARNINGS'
 trace                '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 global default for this option can be changed with defaultTrace().

Known levels are 'INTERNAL', 'ERRORS', 'WARNINGS', 'PROGRESS', 'NOTICES' 'DEBUG', and 'NONE'. The PROGRESS level relates to the reading and writing of folders. NONE 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 global default for this option can be changed with defaultTrace().

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

(Class method) Reports the default trace and log level which is used for object as list of two elements. When not explicitly set, both are set to WARNINGS.

You may specify one or two arguments. In case of one argument, the default log and trace levels will both be set to that value. When two levels are specified, the first represent the default log-level and the second the default trace level.

Examples:

 my ($loglevel, $tracelevel) = Mail::Reporter->defaultTrace;
 Mail::Reporter->defaultTrace('NOTICES');
 Mail::Reporter->defaultTrace('WARNINGS', 'INFO');

errors

Equivalent to $folder->report('ERRORS')

log [LEVEL [,STRINGS]]

(Class or Instance method) As instance method this function has three different purposes. 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.

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.

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);

 Mail::Message->log(ERROR => 'Unknown');

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.

Examples:

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

trace [LEVEL]

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

warnings

Equivalent to $folder->report('WARNINGS')

Other Methods

AUTOLOAD

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

DESTROY

Cleanup.

inGlobalDestruction

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

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.

Examples:

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

notImplemented

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

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Written by Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.027.

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