lib/Log/Message/Handlers.pm

   1 package Log::Message::Handlers;
   2 use strict;
   3
   4 =pod
   5
   6 =head1 NAME
   7
   8 Log::Message::Handlers - Message handlers for Log::Message
   9
  10 =head1 SYNOPSIS
  11
  12     # Implicitly used by Log::Message to serve as handlers for
  13     # Log::Message::Item objects
  14
  15     # Create your own file with a package called
  16     # Log::Message::Handlers to add to the existing ones, or to even
  17     # overwrite them
  18
  19     $item->carp;
  20
  21     $item->trace;
  22
  23
  24 =head1 DESCRIPTION
  25
  26 Log::Message::Handlers provides handlers for Log::Message::Item objects.
  27 The handler corresponding to the level (see Log::Message::Item manpage
  28 for an explanation about levels) will be called automatically upon
  29 storing the error.
  30
  31 Handlers may also explicitly be called on an Log::Message::Item object
  32 if one so desires (see the Log::Message manpage on how to retrieve the
  33 Item objects).
  34
  35 =head1 Default Handlers
  36
  37 =head2 log
  38
  39 Will simply log the error on the stack, and do nothing special
  40
  41 =cut
  42
  43 sub log { 1 }
  44
  45 =head2 carp
  46
  47 Will carp (see the Carp manpage) with the error, and add the timestamp
  48 of when it occurred.
  49
  50 =cut
  51
  52 sub carp {
  53     my $self = shift;
  54     warn join " ", $self->message, $self->shortmess, 'at', $self->when, "\n";
  55 }
  56
  57 =head2 croak
  58
  59 Will croak (see the Carp manpage) with the error, and add the
  60 timestamp of when it occurred.
  61
  62 =cut
  63
  64 sub croak {
  65     my $self = shift;
  66     die join " ", $self->message, $self->shortmess, 'at', $self->when, "\n";
  67 }
  68
  69 =head2 cluck
  70
  71 Will cluck (see the Carp manpage) with the error, and add the
  72 timestamp of when it occurred.
  73
  74 =cut
  75
  76 sub cluck {
  77     my $self = shift;
  78     warn join " ", $self->message, $self->longmess, 'at', $self->when, "\n";
  79 }
  80
  81 =head2 confess
  82
  83 Will confess (see the Carp manpage) with the error, and add the
  84 timestamp of when it occurred
  85
  86 =cut
  87
  88 sub confess {
  89     my $self = shift;
  90     die join " ", $self->message, $self->longmess, 'at', $self->when, "\n";
  91 }
  92
  93 =head2 die
  94
  95 Will simply die with the error message of the item
  96
  97 =cut
  98
  99 sub die  { die  shift->message; }
 100
 101
 102 =head2 warn
 103
 104 Will simply warn with the error message of the item
 105
 106 =cut
 107
 108 sub warn { warn shift->message; }
 109
 110
 111 =head2 trace
 112
 113 Will provide a traceback of this error item back to the first one that
 114 occurrent, clucking with every item as it comes across it.
 115
 116 =cut
 117
 118 sub trace {
 119     my $self = shift;
 120
 121     for my $item( $self->parent->retrieve( chrono => 0 ) ) {
 122         $item->cluck;
 123     }
 124 }
 125
 126 =head1 Custom Handlers
 127
 128 If you wish to provide your own handlers, you can simply do the
 129 following:
 130
 131 =over 4
 132
 133 =item *
 134
 135 Create a file that holds a package by the name of
 136 C<Log::Message::Handlers>
 137
 138 =item *
 139
 140 Create subroutines with the same name as the levels you wish to
 141 handle in the Log::Message module (see the Log::Message manpage for
 142 explanation on levels)
 143
 144 =item *
 145
 146 Require that file in your program, or add it in your configuration
 147 (see the Log::Message::Config manpage for explanation on how to use a
 148 config file)
 149
 150 =back
 151
 152 And that is it, the handler will now be available to handle messages
 153 for you.
 154
 155 The arguments a handler may receive are those specified by the
 156 C<extra> key, when storing the message.
 157 See the Log::Message manpage for details on the arguments.
 158
 159 =head1 SEE ALSO
 160
 161 L<Log::Message>, L<Log::Message::Item>, L<Log::Message::Config>
 162
 163 =head1 AUTHOR
 164
 165 This module by
 166 Jos Boumans E<lt>kane@cpan.orgE<gt>.
 167
 168 =head1 Acknowledgements
 169
 170 Thanks to Ann Barcomb for her suggestions.
 171
 172 =head1 COPYRIGHT
 173
 174 This module is
 175 copyright (c) 2002 Jos Boumans E<lt>kane@cpan.orgE<gt>.
 176 All rights reserved.
 177
 178 This library is free software;
 179 you may redistribute and/or modify it under the same
 180 terms as Perl itself.
 181
 182 =cut
 183
 184 1;
 185
 186 # Local variables:
 187 # c-indentation-style: bsd
 188 # c-basic-offset: 4
 189 # indent-tabs-mode: nil
 190 # End:
 191 # vim: expandtab shiftwidth=4: