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
      log_error( 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 "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
    log_error( FATAL, die-message) and log_error( WARNING, warn-message),
    respectively.

HISTORY
    $Id: ErrLogger.pm,v 1.6 1999/09/23 21:37:24 dcw Exp $

    $Log: ErrLogger.pm,v $ Revision 1.6 1999/09/23 21:37:24 dcw Incorporated
    Tim Ayers <tayers@bridge.com> suggestions

    Revision 1.5 1999/09/13 17:59:48 dcw Copyright

    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
    log_error( SEVERITY, FORMAT [,LIST] )
        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 log_error( $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. There are
        two special sensitivities. Objects with a sensitivity of NONE do not
        respond to any events. Objects with a sensitivity of ALL respond to
        all events.

    my $old_sensitivity = $logger->sensitivity( 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->file_handle;
        Returns the IO::Handle associated with the error logger object. Not
        all error loggers will have a file handle, but most will.

    $logger->set_file_handle( 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. log_error 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( SEVERITY, MESSAGE );
        This is the method called by log_error, above. It prints

        <time>: <message>

        to the associated file handle, where <time> is the output of
        localtime, 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 log 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 set_file 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->set_file( $new_filename [, mode [,
        perms]])
            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.