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