This is part of the MIME-tools documentation.
See MIME::Tools for the full table of contents.
DESCRIPTION
This document describes how the toolkit reports unusual
situations, and how you can hear (or suppress) what it has to say.
Message logging
MIME-tools is a large and complex toolkit which tries to deal with
a wide variety of external input. It's sometimes helpful to see
what's really going on behind the scenes.
Version 6 funnels all message logging through a single
global object, $MIME::Tools::LOG. This object has methods
for dispatching messages of various types: debug, warning, and error.
When a MIME::Parser begins a parse it local'izes this global,
replacing it with an instance of MIME::Parser::Results.
This causes all MIME::Tools messages to be diverted into the
results trace-log, which can be examined for problems after the parse.
See MIME::Parser::Results for more details.
Kinds of messages
There are several kinds of messages logged by the toolkit
Debug messages
These are printed directly to the STDERR, with a prefix of
"MIME-tools: debug".
Debug message are only logged if you have turned
"debugging" on in the MIME::Tools configuration.
See ``debugging'' in MIME::Tools.
Warning messages
These are logged by the standard Perl warn() mechanism
to indicate an unusual situation.
They all have a prefix of "MIME-tools: warning".
Warning messages are only logged if $^W is set true
and MIME::Tools is not configured to be "quiet".
See ``quiet'' in MIME::Tools.
Error messages
These are logged by the standard Perl warn() mechanism
to indicate that something actually failed.
They all have a prefix of "MIME-tools: error".
Error messages are only logged if $^W is set true
and MIME::Tools is not configured to be "quiet".
See ``quiet'' in MIME::Tools.
Situational warnings
These are warnings about unexpected things which are nonfatal;
e.g., creating a directory which should be there but isn't.
They are logged in the simplest way possible:
warn "{description of the problem}\n"
Situational warnings are only logged if $^W is set true and
MIME::Tools is not configured to be ``quiet''.
Situational errors
These are exceptions thrown when something bad happens; e.g.,
failure to open a file.
They are thrown in the simplest way possible:
die "{description of the problem}\n"
Usage warnings
If you invoke a deprecated MIME-tools method, or construct
an instance of a deprecated MIME-tools class, or otherwise
ask for something that I think is unwise or will soon be
unsupported, it will result in a warning logged via "Carp::carp",
like this:
carp "MIME-tools: usage: {description of the problem}
See ``carp'' in Carp for more details.
Usage warnings are only logged if $^W is set true and
MIME::Tools is not configured to be ``quiet''.
Usage errors
If you invoke a MIME-tools method improperly, it will result
in an exception thrown via "Carp::croak", like this:
croak "MIME-tools: usage: {description of the problem}"
See ``croak'' in Carp for more details.
Note: such exceptions will be thrown from a MIME::Parser
even if that parser has been configured to ``ignore errors''.
The only ``errors'' ignored are errors in the message data...
not errors in the code itself.
Internal logic errors
If an internal logic error is discovered, it will always result
in an exception thrown via "Carp::confess", like this:
confess "MIME-tools: internal: {description of the problem}"
The stack backtrace will aid in the debugging and repair of MIME-tools.
See ``confess'' in Carp for more details.
Note: such exceptions will be thrown from a MIME::Parser
even if that parser has been configured to ``ignore errors''.
The only ``errors'' ignored are errors in the message data...
not errors in the code itself.
Component error handling
MIME-tools makes use of a number of externally-provided modules
(Mail::Internet, MIME::Base64, etc.), each of which may have its own
conventions for issuing warnings and throwing exceptions.
MIME-tools does not attempt to mask or interfere with these
mechanisms in any way.
SEE ALSO
See ``SYNOPSIS'' in MIME::Tools for the full table of contents.
