unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Reporter(3pm)   User Contributed Perl Documentation  Mail::Reporter(3pm)



NAME
       Mail::Reporter - base-class and error reporter for Mail::Box

INHERITANCE
        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

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

DESCRIPTION
       The "Mail::Reporter" 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.

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

       Constructors

       Mail::Reporter->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().

       Error handling

       $obj->AUTOLOAD

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

       $obj->addReport(OBJECT)

           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.

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Reporter->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
       CALLBACK])

           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!

           example: setting loglevels

            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

           example: installing a callback

            Mail::Reporter->defaultTrace

       $obj->errors

           Equivalent to

            $folder->report('ERRORS')

       $obj->log([LEVEL [,STRINGS]])

       Mail::Reporter->log([LEVEL [,STRINGS]])

           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.

           example:

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

       $obj->logPriority(LEVEL)

       Mail::Reporter->logPriority(LEVEL)

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

           example:

            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

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

       $obj->notImplemented

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

       $obj->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.

           example:

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

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

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

       $obj->trace([LEVEL])

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

       $obj->warnings

           Equivalent to

            $folder->report('WARNINGS')

       Cleanup

       $obj->DESTROY

           Cleanup the object.

       $obj->inGlobalDestruction

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

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

SEE ALSO
       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 by Mark Overmeer. For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html



perl v5.10.0                      2008-04-28               Mail::Reporter(3pm)