This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix IPC-Cmd test failure on Win32: check current directory as well
[perl5.git] / lib / Log / Message / Handlers.pm
CommitLineData
f0ac4cdb
JB
1package Log::Message::Handlers;\r
2use strict;\r
3\r
4=pod\r
5\r
6=head1 NAME\r
7\r
8Log::Message::Handlers - Message handlers for Log::Message\r
9\r
10=head1 SYNOPSIS\r
11\r
12 # Implicitly used by Log::Message to serve as handlers for\r
13 # Log::Message::Item objects\r
14\r
15 # Create your own file with a package called\r
16 # Log::Message::Handlers to add to the existing ones, or to even\r
17 # overwrite them\r
18\r
19 $item->carp;\r
20\r
21 $item->trace;\r
22\r
23\r
24=head1 DESCRIPTION\r
25\r
26Log::Message::Handlers provides handlers for Log::Message::Item objects.\r
27The handler corresponding to the level (see Log::Message::Item manpage\r
28for an explanation about levels) will be called automatically upon\r
29storing the error.\r
30\r
31Handlers may also explicitly be called on an Log::Message::Item object\r
32if one so desires (see the Log::Message manpage on how to retrieve the\r
33Item objects).\r
34\r
35=head1 Default Handlers\r
36\r
37=head2 log\r
38\r
39Will simply log the error on the stack, and do nothing special\r
40\r
41=cut\r
42\r
43sub log { 1 }\r
44\r
45=head2 carp\r
46\r
47Will carp (see the Carp manpage) with the error, and add the timestamp\r
48of when it occurred.\r
49\r
50=cut\r
51\r
52sub carp {\r
53 my $self = shift;\r
54 warn join " ", $self->message, $self->shortmess, 'at', $self->when, "\n";\r
55}\r
56\r
57=head2 croak\r
58\r
59Will croak (see the Carp manpage) with the error, and add the\r
60timestamp of when it occurred.\r
61\r
62=cut\r
63\r
64sub croak {\r
65 my $self = shift;\r
66 die join " ", $self->message, $self->shortmess, 'at', $self->when, "\n";\r
67}\r
68\r
69=head2 cluck\r
70\r
71Will cluck (see the Carp manpage) with the error, and add the\r
72timestamp of when it occurred.\r
73\r
74=cut\r
75\r
76sub cluck {\r
77 my $self = shift;\r
78 warn join " ", $self->message, $self->longmess, 'at', $self->when, "\n";\r
79}\r
80\r
81=head2 confess\r
82\r
83Will confess (see the Carp manpage) with the error, and add the\r
84timestamp of when it occurred\r
85\r
86=cut\r
87\r
88sub confess {\r
89 my $self = shift;\r
90 die join " ", $self->message, $self->longmess, 'at', $self->when, "\n";\r
91}\r
92\r
93=head2 die\r
94\r
95Will simply die with the error message of the item\r
96\r
97=cut\r
98\r
99sub die { die shift->message; }\r
100\r
101\r
102=head2 warn\r
103\r
104Will simply warn with the error message of the item\r
105\r
106=cut\r
107\r
108sub warn { warn shift->message; }\r
109\r
110\r
111=head2 trace\r
112\r
113Will provide a traceback of this error item back to the first one that\r
114occurrent, clucking with every item as it comes across it.\r
115\r
116=cut\r
117\r
118sub trace {\r
119 my $self = shift;\r
120\r
121 for my $item( $self->parent->retrieve( chrono => 0 ) ) {\r
122 $item->cluck;\r
123 }\r
124}\r
125\r
126=head1 Custom Handlers\r
127\r
128If you wish to provide your own handlers, you can simply do the\r
129following:\r
130\r
131=over 4\r
132\r
133=item *\r
134\r
135Create a file that holds a package by the name of\r
136C<Log::Message::Handlers>\r
137\r
138=item *\r
139\r
140Create subroutines with the same name as the levels you wish to\r
141handle in the Log::Message module (see the Log::Message manpage for\r
142explanation on levels)\r
143\r
144=item *\r
145\r
146Require that file in your program, or add it in your configuration\r
147(see the Log::Message::Config manpage for explanation on how to use a\r
148config file)\r
149\r
150=back\r
151\r
152And that is it, the handler will now be available to handle messages\r
153for you.\r
154\r
155The arguments a handler may receive are those specified by the\r
156C<extra> key, when storing the message.\r
157See the Log::Message manpage for details on the arguments.\r
158\r
159=head1 SEE ALSO\r
160\r
161L<Log::Message>, L<Log::Message::Item>, L<Log::Message::Config>\r
162\r
163=head1 AUTHOR\r
164\r
165This module by\r
166Jos Boumans E<lt>kane@cpan.orgE<gt>.\r
167\r
168=head1 Acknowledgements\r
169\r
170Thanks to Ann Barcomb for her suggestions.\r
171\r
172=head1 COPYRIGHT\r
173\r
174This module is\r
175copyright (c) 2002 Jos Boumans E<lt>kane@cpan.orgE<gt>.\r
176All rights reserved.\r
177\r
178This library is free software;\r
179you may redistribute and/or modify it under the same\r
180terms as Perl itself.\r
181\r
182=cut\r
183\r
1841;\r
185\r
186# Local variables:\r
187# c-indentation-style: bsd\r
188# c-basic-offset: 4\r
189# indent-tabs-mode: nil\r
190# End:\r
191# vim: expandtab shiftwidth=4:\r