Reporter(3)

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                               reportAll [LEVEL]
      log [LEVEL [,STRINGS]]               trace [LEVEL]
      new OPTIONS                          warnings
      report [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

For support and additional documentation, see http://perl.overmeer.net/mailbox/

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.018.

Copyright (c) 2001-2002 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.