home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / Log / Message / Handlers.pm < prev    next >
Encoding:
Perl POD Document  |  2009-06-26  |  3.6 KB  |  192 lines

  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:
  192.