lib/Log/Message/Handlers.pm

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