Commit | Line | Data |
e3f7a951 |
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: |