Oops!

NAME
    Log::ErrLogger - Log errors and error-like events

SYNOPSIS
      use Log::ErrLogger;

      # Send e-mail for ERROR or worse
      my $mail_logger = new Log::ErrLogger::Mail(
        SENSITIVITY => Log::ErrLogger::ERROR,
        HEADERS     => { To      => "who@where.com",
                                             Subject => "Errors occurred while running $0" });

      # Log INFORMATIONAL or worse to a file
      my $file_logger = new Log::ErrLogger::File(
        FILE        => "/home/who/what.err",
        SENSITIVITY => Log::ErrLogger::INFORMATIONAL );

      # Print a nice HTML error message
      my $sub_logger  = new Log::ErrLogger::Sub (
        SENSITIVITY => FATAL,
        SUB         => sub { print STDOUT "<TITLE>Oops!</TITLE><HTML><HEAD1>Please try again later.</HEAD1></HTML>\n";
                                                     exit(0); } );

      # Capture all output to STDERR as an UNEXPECTED error
      my $stderr_logger = Log::ErrLogger::Tie( Log::ErrLogger::UNEXPECTED );

      # But don't actually print to STDERR
      $stderr_logger->close;

      # Log a warning
      LogError( WARNING, "Danger, %s!", "Will Robinson" );

DESCRIPTION
    Log::ErrLogger provides a means of logging errors and error-like
    events (such as warnings and unexpected situations) when
    printing to STDERR just will not do.

    Error-like events are classified by a severity (see the section
    on "ERROR SEVERITIES" below). Programs instantiate error logging
    objects which can respond differently to events. The objects
    have a sensitivity -- they will respond to any event at least as
    severe as their sensitivity, and will ignore any events that are
    less severe.

    This module instantiates new __DIE__ and __WARN__ handlers that
    call LogError( FATAL, die-message) and LogError( WARNING, warn-
    message), respectively.

HISTORY
    $Id: ErrLogger.pm,v 1.4 1999/09/13 16:37:17 dcw Exp $

    $Log: ErrLogger.pm,v $ Revision 1.4 1999/09/13 16:37:17 dcw
    Documentation

    Revision 1.3 1999/09/01 14:28:28 dcw Backup file, export,
    autoflush

    Revision 1.2 1999/08/31 17:18:39 dcw Log::ErrLogger::Sub

    Revision 1.1 1999/08/30 21:28:43 dcw Initial

AUTHOR
    David C. Worenklein <dcw@gcm.com>

COPYRIGHT
    Copyright 1999 Greenwich Capital Markets

    This library is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.

ERROR SEVERITIES
    The predefined severities are

    DEBUGGING
    INFORMATIONAL
    UNEXPECTED
    WARNING
    ERROR
    FATAL
    They have numerical values from 1 to 6.

NON-METHOD SUBROUTINES
    LogError( $severity, $format [,@args] )
        Log an error of the specified severity. The text of the
        message is the output of sprintf $format, @args. A carriage-
        return (\n) will be appended if one is not supplied.

    my $stderr_logger = Tie( [$severity] );
        Tie the STDERR handle to the Log::ErrLogger module, so that
        any output to STDERR will call LogError( $severity, output
        ).

        If $severity is not specified, it will default to
        INFORMATIONAL.

METHODS
    my $sensitivity = $logger->Sensitivity;
        Returns the sensitivty of an error logger object. Objects
        respond to events that are at least as severe as their
        sensitivity.

    my $old_sensitivity = $logger->Sensitivity( $new_sensitivity );
        Sets the sensitivty of an error logger object. Objects
        respond to events that are at least as severe as their
        sensitivity.

        Returns what the sensitivity of the object used to be.

    my $fh = $logger->FileHandle;
        Returns the IO::Handle associated with the error logger
        object. Not all error loggers will have a file handle, but
        most will.

    $logger->SetFileHandle( $handle );
        Associates the error logger object with the given (opened)
        IO::Handle, and closes the old file handle that used to be
        associated with the object (if there was one.)

        The handle is set to autoflush, since buffering is usually a
        bad idea on error loggers.

    $logger->close;
        Decommission the error logging object. the LogError manpage
        will no longer invoke this object.

        Note that this does NOT close the associated file handle.
        However, if the error logging object has the only reference
        to the file handle, and the program does not have any
        references to the error logging object, the handle will have
        no references left and will be destroyed.

    $logger->Log( $message, $severity);
        This is the method called by the LogError manpage, above. It
        prints

        <time>: <message>

        to the associated file handle, where <time> is the output of
        the localtime manpage, evaluated in a scalar context.

        Additionally, if the object has a TRACE attribute that is at
        least as large as the error severity, this method will print
        a trace of where the error occurred:

        <spaces>: From <subroutine1>, at <filename1>:<line1>
        <spaces>: From <subroutine2>, at <filename2>:<line2>

        where <spaces> is the number of spaces needed to make all
        the colons line up.

CONSTRUCTORS
    The following erorr logging classes are provided by the module:

    my $logger = new Log::ErrLogger( [parameter-hash] );
        Creates a new error logging object that uses the default the
        Log manpage given above. The parameters that are understood
        are

    SENSITIVITY
            The sensitivity of the object. Defaults to INFORMATIONAL
            or, in the perl debugger, DEBUGGING.

    TRACE   Events that are at least as severe as the TRACE value will
            have their call stack printed.

    my $logger = new Log::ErrLogger::File( [parameter-hash] );
        Creates an error logging object that logs events to a file.
        In addition to the parameters that the Log::ErrLogger
        constructor takes, it also takes

    FILE    Name of the file that in which to log events. Defaults to
            /tmp/<program-base-name>.<pid>.err. See the the
            SetFileName manpage method, below, for details.

        Log::ErrLogger::File objects also provides the following
        methods:

    my $filename = $filelogger->FileName();
            Returns the name of the file to which events are logger.

    my $old_filename = $filelogger->SetFile( $new_filename)
            Opens the given file for output and sets its FILEHANDLE
            to that file. An ERROR event is generated if the file
            could not be opened.

            Note that the file is opened by putting a ">" at the
            beginning and creating a new IO::File object. This means
            that if the filename given already begins with a ">",
            the file will be opened for appending.

            If the file already exists, it is renamed by appending
            ".bak" to it. A WARNING event is generated if the file
            could not be backed up.

            Returns the old filename that errors used to be logged
            to.

    my $logger = new Log::ErrLogger::Mail( [parameter-hash] );
        Log events by sending email to interested parties. In
        addition to the parameters that the Log::ErrLogger
        constructor takes, it also takes

    HEADERS A reference to a hash containing the headers of the e-mail,
            such as To and Subject.

        If no sufficiently severe events occur, no email is sent.
        (In other words, you will not get a blank e-mail.)

    my $logger = new Log::ErrLogger::Sub( [parameter-hash] );
        Calls a user specified subroutine every time a sufficiently
        severe events occurs. In addition to the parameters that the
        Log::ErrLogger constructor takes, it also takes

    SUB     A reference (regular or symbolic) to the subroutine to be
            called. The subroutine will receive two parameters --
            the event message and the error severity. This parameter
            MUST be supplied to the constructor.

            Note that, within this subroutine, STDERR is what you
            would want it to be, even if the program has used Tie to
            capture STDERR. Thus, the subroutine does not have to
            worry that output to STDERR will cause infinite
            recursion.