lib/Log/Message/Item.pm

   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: