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