This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move Log::Message from ext/ to cpan/
[perl5.git] / cpan / Log-Message / lib / Log / Message / Handlers.pm
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: