[patch@29297] perl5db.pl detecting forked debugger on VMS.

[p5sagit/p5-mst-13.2.git] / lib / Log / Message / Handlers.pm

package Log::Message::Handlers;\r
use strict;\r
\r
=pod\r
\r
=head1 NAME\r
\r
Log::Message::Handlers - Message handlers for Log::Message\r
\r
=head1 SYNOPSIS\r
\r
    # Implicitly used by Log::Message to serve as handlers for\r
    # Log::Message::Item objects\r
\r
    # Create your own file with a package called\r
    # Log::Message::Handlers to add to the existing ones, or to even\r
    # overwrite them\r
\r
    $item->carp;\r
\r
    $item->trace;\r
\r
\r
=head1 DESCRIPTION\r
\r
Log::Message::Handlers provides handlers for Log::Message::Item objects.\r
The handler corresponding to the level (see Log::Message::Item manpage\r
for an explanation about levels) will be called automatically upon\r
storing the error.\r
\r
Handlers may also explicitly be called on an Log::Message::Item object\r
if one so desires (see the Log::Message manpage on how to retrieve the\r
Item objects).\r
\r
=head1 Default Handlers\r
\r
=head2 log\r
\r
Will simply log the error on the stack, and do nothing special\r
\r
=cut\r
\r
sub log { 1 }\r
\r
=head2 carp\r
\r
Will carp (see the Carp manpage) with the error, and add the timestamp\r
of when it occurred.\r
\r
=cut\r
\r
sub carp {\r
    my $self = shift;\r
    warn join " ", $self->message, $self->shortmess, 'at', $self->when, "\n";\r
}\r
\r
=head2 croak\r
\r
Will croak (see the Carp manpage) with the error, and add the\r
timestamp of when it occurred.\r
\r
=cut\r
\r
sub croak {\r
    my $self = shift;\r
    die join " ", $self->message, $self->shortmess, 'at', $self->when, "\n";\r
}\r
\r
=head2 cluck\r
\r
Will cluck (see the Carp manpage) with the error, and add the\r
timestamp of when it occurred.\r
\r
=cut\r
\r
sub cluck {\r
    my $self = shift;\r
    warn join " ", $self->message, $self->longmess, 'at', $self->when, "\n";\r
}\r
\r
=head2 confess\r
\r
Will confess (see the Carp manpage) with the error, and add the\r
timestamp of when it occurred\r
\r
=cut\r
\r
sub confess {\r
    my $self = shift;\r
    die join " ", $self->message, $self->longmess, 'at', $self->when, "\n";\r
}\r
\r
=head2 die\r
\r
Will simply die with the error message of the item\r
\r
=cut\r
\r
sub die  { die  shift->message; }\r
\r
\r
=head2 warn\r
\r
Will simply warn with the error message of the item\r
\r
=cut\r
\r
sub warn { warn shift->message; }\r
\r
\r
=head2 trace\r
\r
Will provide a traceback of this error item back to the first one that\r
occurrent, clucking with every item as it comes across it.\r
\r
=cut\r
\r
sub trace {\r
    my $self = shift;\r
\r
    for my $item( $self->parent->retrieve( chrono => 0 ) ) {\r
        $item->cluck;\r
    }\r
}\r
\r
=head1 Custom Handlers\r
\r
If you wish to provide your own handlers, you can simply do the\r
following:\r
\r
=over 4\r
\r
=item *\r
\r
Create a file that holds a package by the name of\r
C<Log::Message::Handlers>\r
\r
=item *\r
\r
Create subroutines with the same name as the levels you wish to\r
handle in the Log::Message module (see the Log::Message manpage for\r
explanation on levels)\r
\r
=item *\r
\r
Require that file in your program, or add it in your configuration\r
(see the Log::Message::Config manpage for explanation on how to use a\r
config file)\r
\r
=back\r
\r
And that is it, the handler will now be available to handle messages\r
for you.\r
\r
The arguments a handler may receive are those specified by the\r
C<extra> key, when storing the message.\r
See the Log::Message manpage for details on the arguments.\r
\r
=head1 SEE ALSO\r
\r
L<Log::Message>, L<Log::Message::Item>, L<Log::Message::Config>\r
\r
=head1 AUTHOR\r
\r
This module by\r
Jos Boumans E<lt>kane@cpan.orgE<gt>.\r
\r
=head1 Acknowledgements\r
\r
Thanks to Ann Barcomb for her suggestions.\r
\r
=head1 COPYRIGHT\r
\r
This module is\r
copyright (c) 2002 Jos Boumans E<lt>kane@cpan.orgE<gt>.\r
All rights reserved.\r
\r
This library is free software;\r
you may redistribute and/or modify it under the same\r
terms as Perl itself.\r
\r
=cut\r
\r
1;\r
\r
# Local variables:\r
# c-indentation-style: bsd\r
# c-basic-offset: 4\r
# indent-tabs-mode: nil\r
# End:\r
# vim: expandtab shiftwidth=4:\r