[Summary view] [Print] [Text view]

   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: