[Summary view] [Print] [Text view]

   1  package Log::Message::Item;
   2  
   3  use strict;
   4  use Params::Check qw[check];
   5  use Log::Message::Handlers;
   6  
   7  ### for the messages to store ###
   8  use Carp ();
   9  
  10  BEGIN {
  11      use vars qw[$AUTOLOAD $VERSION];
  12  
  13      $VERSION    =   $Log::Message::VERSION;
  14  }
  15  
  16  ### create a new item.
  17  ### note that only an id (position on the stack), message and a reference
  18  ### to its parent are required. all the other things it can fill in itself
  19  sub new {
  20      my $class   = shift;
  21      my %hash    = @_;
  22  
  23      my $tmpl = {
  24          when        => { no_override    => 1,   default    => scalar localtime },
  25          id          => { required       => 1    },
  26          message     => { required       => 1    },
  27          parent      => { required        => 1    },
  28          level       => { default        => ''   },      # default may be conf dependant
  29          tag         => { default        => ''   },      # default may be conf dependant
  30          longmess    => { default        => _clean(Carp::longmess()) },
  31          shortmess   => { default        => _clean(Carp::shortmess())},
  32      };
  33  
  34      my $args = check($tmpl, \%hash) or return undef;
  35  
  36      return bless $args, $class;
  37  }
  38  
  39  sub _clean { map { s/\s*//; chomp; $_ } shift; }
  40  
  41  sub remove {
  42      my $item = shift;
  43      my $self = $item->parent;
  44  
  45      return splice( @{$self->{STACK}}, $item->id, 1, undef );
  46  }
  47  
  48  sub AUTOLOAD {
  49      my $self = $_[0];
  50  
  51      $AUTOLOAD =~ s/.+:://;
  52  
  53      return $self->{$AUTOLOAD} if exists $self->{$AUTOLOAD};
  54  
  55      local $Carp::CarpLevel = $Carp::CarpLevel + 3;
  56  
  57      {   no strict 'refs';
  58          return *{"Log::Message::Handlers::$AUTOLOAD}"}->(@_);
  59      }
  60  }
  61  
  62  sub DESTROY { 1 }
  63  
  64  1;
  65  
  66  __END__
  67  
  68  =pod
  69  
  70  =head1 NAME
  71  
  72  Log::Message::Item  - Message objects for Log::Message
  73  
  74  =head1 SYNOPSIS
  75  
  76      # Implicitly used by Log::Message to create Log::Message::Item objects
  77  
  78      print "this is the message's id: ",     $item->id;
  79  
  80      print "this is the message stored: ",   $item->message;
  81  
  82      print "this is when it happened: ",     $item->when;
  83  
  84      print "the message was tagged: ",       $item->tag;
  85  
  86      print "this was the severity level: ",  $item->level;
  87  
  88      $item->remove;  # delete the item from the stack it was on
  89  
  90      # Besides these methods, you can also call the handlers on
  91      # the object specificallly.
  92      # See the Log::Message::Handlers manpage for documentation on what
  93      # handlers are available by default and how to add your own
  94  
  95  
  96  =head1 DESCRIPTION
  97  
  98  Log::Message::Item is a class that generates generic Log items.
  99  These items are stored on a Log::Message stack, so see the Log::Message
 100  manpage about details how to retrieve them.
 101  
 102  You should probably not create new items by yourself, but use the
 103  storing mechanism provided by Log::Message.
 104  
 105  However, the accessors and handlers are of interest if you want to do
 106  fine tuning of how your messages are handled.
 107  
 108  The accessors and methods are described below, the handlers are
 109  documented in the Log::Message::Handlers manpage.
 110  
 111  =head1 Methods and Accessors
 112  
 113  =head2 remove
 114  
 115  Calling remove will remove the object from the stack it was on, so it
 116  will not show up any more in subsequent fetches of messages.
 117  
 118  You can still call accessors and handlers on it however, to handle it
 119  as you will.
 120  
 121  =head2 id
 122  
 123  Returns the internal ID of the item. This may be useful for comparing
 124  since the ID is incremented each time a new item is created.
 125  Therefore, an item with ID 4 must have been logged before an item with
 126  ID 9.
 127  
 128  =head2 when
 129  
 130  Returns the timestamp of when the message was logged
 131  
 132  =head2 message
 133  
 134  The actual message that was stored
 135  
 136  =head2 level
 137  
 138  The severity type of this message, as well as the name of the handler
 139  that was called upon storing it.
 140  
 141  =head2 tag
 142  
 143  Returns the identification tag that was put on the message.
 144  
 145  =head2 shortmess
 146  
 147  Returns the equivalent of a C<Carp::shortmess> for this item.
 148  See the C<Carp> manpage for details.
 149  
 150  =head2 longmess
 151  
 152  Returns the equivalent of a C<Carp::longmess> for this item, which
 153  is essentially a stack trace.
 154  See the C<Carp> manpage for details.
 155  
 156  =head2 parent
 157  
 158  Returns a reference to the Log::Message object that stored this item.
 159  This is useful if you want to have access to the full stack in a
 160  handler.
 161  
 162  =head1 SEE ALSO
 163  
 164  L<Log::Message>, L<Log::Message::Handlers>, L<Log::Message::Config>
 165  
 166  =head1 AUTHOR
 167  
 168  This module by
 169  Jos Boumans E<lt>kane@cpan.orgE<gt>.
 170  
 171  =head1 Acknowledgements
 172  
 173  Thanks to Ann Barcomb for her suggestions.
 174  
 175  =head1 COPYRIGHT
 176  
 177  This module is
 178  copyright (c) 2002 Jos Boumans E<lt>kane@cpan.orgE<gt>.
 179  All rights reserved.
 180  
 181  This library is free software;
 182  you may redistribute and/or modify it under the same
 183  terms as Perl itself.
 184  
 185  =cut
 186  
 187  # Local variables:
 188  # c-indentation-style: bsd
 189  # c-basic-offset: 4
 190  # indent-tabs-mode: nil
 191  # End:
 192  # vim: expandtab shiftwidth=4: