MIME::Tools::diag - diagnostics for MIME-tools
This is part of the MIME-tools documentation. See MIME::Tools for the full table of contents.
This document describes how the toolkit reports unusual situations, and how you can hear (or suppress) what it has to say.
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.
There are several kinds of messages logged by the toolkit
These are printed directly to the STDERR, with a prefix of "MIME-tools: debug".
"MIME-tools: debug"
Debug message are only logged if you have turned debugging on in the MIME::Tools configuration. See "debugging" in MIME::Tools.
debugging
These are logged by the standard Perl warn() mechanism to indicate an unusual situation. They all have a prefix of "MIME-tools: warning".
"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.
$^W
quiet
These are logged by the standard Perl warn() mechanism to indicate that something actually failed. They all have a prefix of "MIME-tools: error".
"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.
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".
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"
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::carp
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".
If you invoke a MIME-tools method improperly, it will result in an exception thrown via Carp::croak, like this:
Carp::croak
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.
If an internal logic error is discovered, it will always result in an exception thrown via Carp::confess, like this:
Carp::confess
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.
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 "SYNOPSIS" in MIME::Tools for the full table of contents.
To install MIME::Head, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MIME::Head
CPAN shell
perl -MCPAN -e shell install MIME::Head
For more information on module installation, please visit the detailed CPAN module installation guide.