blib/lib/Carp/Diagnostics.pm

filter: Statementstmt 91.5% 65 / 71 Branchbran 75.0% 18 / 24 Conditioncond 100% 12 / 12 MC/DCmcdc 100% 8 / 8 Subroutinesub 100% 18 / 18 Podpod 100% 7 / 7 totaltotal 91.4% 128 / 140 CC 17 SCAR 9.3
CC
17
Cov
89%
BEGIN
4.4
GetTerminalWidth
3.2
confess
3.0
CRAP 2.5
↑ Summary
1  
2 package Carp::Diagnostics ;
3  
4 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 ▶use warnings ;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 3 my $WIN32_CONSOLE ;
8  
9 BEGIN
10 3 ▶{
Subroutine BEGIN: called CC=4 SCAR=14.7
11 3 ▶use English qw( -no_match_vars ) ;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 3 ▶use Sub::Exporter -setup => { exports => [ qw(carp cluck croak confess UseLongMessage) ] } ;
Subroutine BEGIN: called CC=1 SCAR=0.0
13
14 3 ▶use vars qw ($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 3 $VERSION = '0.05' ;
16  
17 #-------------------------------------------------------------------------------
18  
19 3 ▶if($OSNAME ne 'MSWin32')
Branch: 1 branch
BranchTrueFalseTotal
if ($Carp::Diagnostics::OSNAME ne 'MSWin32') { } 3 0 3
20 {
21 3 ▶ eval "use Term::Size;" ; ## no critic
Subroutine BEGIN: called CC=1 SCAR=0.0
22 3 ▶ Carp::croak $EVAL_ERROR if $EVAL_ERROR;
Branch: 1 branch
BranchTrueFalseTotal
if $Carp::Diagnostics::EVAL_ERROR 0 3 3
23 }
24 else
25 {
26 0 eval "use Win32::Console;" ; ## no critic
27 0 ▶ Carp::croak $EVAL_ERROR if $EVAL_ERROR ;
Branch: 1 branch
BranchTrueFalseTotal
if $Carp::Diagnostics::EVAL_ERROR 0 0 0
28
29 0 $WIN32_CONSOLE= new Win32::Console;
30 }
31 }
32  
33 #-------------------------------------------------------------------------------
34  
35 3 ▶use Readonly ;
Subroutine BEGIN: called CC=1 SCAR=0.0
36 3 Readonly my $EMPTY_STRING => q{} ;
37  
38 3 ▶use Carp qw() ;
Subroutine BEGIN: called CC=1 SCAR=0.0
39  
40 3 ▶use IO::String ;
Subroutine BEGIN: called CC=1 SCAR=0.0
41 3 ▶use Pod::Text ;
Subroutine BEGIN: called CC=1 SCAR=0.0
42  
43 =head1 NAME
44  
45 Carp::Diagnostics - Carp with a diagnostic message
46  
47 =head1 SYNOPSIS
48  
49 use Carp::Diagnostics qw(cluck carp croak confess) ;
50
51 CroakingSub() ;
52
53 #---------------------------------------------------------------------------
54
55 sub CroakingSub
56 {
57
58 =head2 CroakingSub
59
60 An example of how to use Carp::Diagnostics.
61
62 =head3 Diagnostics
63
64 =cut
65
66 my ($default_rule_name, $name) = ('c_objects', 'o_cs_meta') ;
67
68 confess
69 (
70 "Default rule '$default_rule_name', in rule '$name', doesn't exist.\n",
71
72 <<END_OF_POD,
73
74 =over
75
76 =item Default rule '$default_rule_name', in rule '$name', doesn't exist!
77
78 The default rule of a I<FirstAndOnlyOneOnDisk> B<META_RULE> must be registrated before
79 the B<META_RULE> definiton. Here is an example of declaration:
80
81 AddRule 'c_o', [ '*/*.o' => '*.c' ], \&C_Builder ;
82 AddRule 'cpp_o', [ '*/*.o' => '*.cpp' ], \&CPP_Builder ;
83
84 AddRule [META_RULE], 'o_cs_meta',
85 [\&FirstAndOnlyOneOnDisk, ['cpp_o', 'c_o' ], 'c_o'] ;
86 ^- slave rules -^ ^-default
87
88 =back
89
90 =cut
91
92 END_OF_POD
93 ) ;
94
95 }
96  
97 =head1 DESCRIPTION
98  
99 This module overrides the subs defined in L<Carp> to allow you to give informative diagnostic messages.
100  
101 =head1 DOCUMENTATION
102  
103 Perl Best Practices recommends to have a B<DIAGNOSTIC> section, in your B<POD>, where all your warnings and errors are
104 explained in details. Although I like the principle, I dislike its proposed implementation. Why should we display
105 cryptic messages at run time that the user have to lookup in the documentation? I also dislike to have the
106 diagnostics grouped far from where the errors are generated, they never get updated.
107  
108 This modules implements the four subs exported by the Carp module (carp, croak, cluck, confess). The new
109 subs take zero, one or two arguments.
110  
111 =head2 No argument
112  
113 =over 2
114  
115 =item * No message
116  
117 =back
118  
119 =head2 One argument
120  
121 =over 2
122  
123 =item * A message
124  
125 =back
126  
127 =head2 Two arguments
128  
129 =over 2
130  
131 =item * A short message
132  
133 =item * A diagnostic message
134  
135 The long message is a diagnostic and is the one normally displayed.
136  
137 You can direct B<Carp::Diagnostics> to display the short message; this is useful when developing modules.
138 You, the module author, understand short warnings. See L<UseLongMessage>.
139  
140 =back
141  
142 Having the possibility to pass one argument or two gives you the possibility to drop-in B<Car::Diagnostics> in your module
143 without having to modify all the call to the carping subs. if you decide to add Diagnostics to any of your subs, just add the
144 second argument to, your already existing, carp call.
145  
146 The I<podification> functionality is always on.
147  
148 B<Carp> is used internally so you get an identical functionality.
149  
150 =head2 POD: Eating your cake and having it too.
151  
152 The good news is that you are going to do two things in one shot. You'll be giving better diagnostics to your users
153 and you'll be documenting your modules too.
154  
155 If the long message (diagnostic) is B<POD> (the first non space character is an '=' at the start of the line), B<Carp::Diagnostics>
156 will convert the pod to text and pass it to B<Carp::>.
157  
158 $ perl cd_test.pl
159
160 Default rule 'c_objects', in rule 'o_cs_meta', doesn't exist!
161 The default rule of a *FirstAndOnlyOneOnDisk* META_RULE must be registrated before the
162 META_RULE definiton. Here is an example of declaration:
163
164 AddRule 'c_o', [ '*/*.o' => '*.c' ], \&C_Builder ;
165 AddRule 'cpp_o', [ '*/*.o' => '*.cpp' ], \&CPP_Builder ;
166
167 AddRule [META_RULE], 'o_cs_meta',
168 [\&FirstAndOnlyOneOnDisk, ['cpp_o', 'c_o' ], 'c_o'] ;
169 ^- slave rules -^ ^-default
170
171 at cd_test.pl line 26
172 main::CroakingSub() called at cd_test.pl line 11
173  
174 Since the diagnostic is valid pod, it will be extracted when you generate your documentation.
175  
176 $ pod2text cd_test.pl
177
178 CroakingSub
179 An example of how to use Carp::Diagnostics.
180
181 Diagnostics
182 Default rule '$default_rule_name', in rule '$name', doesn't exist!
183 The default rule of a *FirstAndOnlyOneOnDisk* META_RULE must be
184 registrated before the META_RULE definiton. Here is an example of
185 declaration:
186
187 AddRule 'c_o', [ '*/*.o' => '*.c' ], \&C_Builder ;
188 AddRule 'cpp_o', [ '*/*.o' => '*.cpp' ], \&CPP_Builder ;
189
190 AddRule [META_RULE], 'o_cs_meta',
191 [\&FirstAndOnlyOneOnDisk, ['cpp_o', 'c_o' ], 'c_o'] ;
192 ^- slave rules -^ ^-default
193  
194 =head1 SUBROUTINES/METHODS
195  
196 =cut
197  
198 {
199 3 my $use_long_message = 1 ;
200  
201 sub UseLongMessage
202 16 ▶{
Subroutine UseLongMessage: called CC=2 SCAR=6.9
Pod documented
203  
204 =head2 UseLongMessage
205  
206 Give I<0> as argument if you want to display the short message. The only reason to use this
207 is when developing modules which use B<Carp::Diagnostics>. Even then it's not a very good reason
208 for not displaying a complete diagnostic.
209  
210 This setting is global.
211  
212 =cut
213  
214 16 ▶$use_long_message = $_[0] if defined $_[0] ;
Branch: 1 branch
BranchTrueFalseTotal
if defined $_[0] 2 14 16
215 16 return($use_long_message) ;
216 }
217  
218 }
219  
220 #-------------------------------------------------------------------------------
221  
222 sub croak
223 3 ▶{
Subroutine croak: called CC=3 SCAR=11.0
Pod documented
224  
225 =head2 croak
226  
227 =head3 arguments
228  
229 =over 2
230  
231 =item short_message
232  
233 =item diagnostic (long message)
234  
235 =back
236  
237 if the diagnostic is POD, it will be converted to text.
238  
239 Calls Carp::croak to display the message.
240  
241 =cut
242  
243 8 local $Carp::CarpLevel = 1; ## no critic
244  
245 8 ▶Carp::croak
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 || !UseLongMessage() ? : 4 4 8
Condition100%3/3
@_ == 1 or not UseLongMessage()
l!l&&r!l&&!r
314
MC/DC100%2/2
@_ == 1 or not UseLongMessage()
@_ == 1 not UseLongMessage()
Truth table100%3/3
A or not(B)
A= @_ == 1B= not UseLongMessage()
ABresult
1X1
011
000
246 (
247 Podify
248 (
249 @_ == 1 || (! UseLongMessage())
250 ? $_[0] # user wants short message or there is only one message
251 : $_[1]
252 )
253 ) ;
254  
255  
256 0 return ;
257 }
258  
259 #-------------------------------------------------------------------------------
260  
261 sub confess
262 4 ▶{
Subroutine confess: called CC=3 SCAR=11.0
Pod documented
263  
264 =head2 confess
265  
266 =head3 arguments
267  
268 =over 2
269  
270 =item short_message
271  
272 =item diagnostic (long message)
273  
274 =back
275  
276 if the diagnostic is POD, it will be converted to text.
277  
278 Calls Carp::confess to display the message.
279  
280 =cut
281  
282 4 local $Carp::CarpLevel = 1; ## no critic
283 4 ▶Carp::confess
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 || !UseLongMessage() ? : 2 2 4
Condition100%3/3
@_ == 1 or not UseLongMessage()
l!l&&r!l&&!r
112
MC/DC100%2/2
@_ == 1 or not UseLongMessage()
@_ == 1 not UseLongMessage()
Truth table100%3/3
A or not(B)
A= @_ == 1B= not UseLongMessage()
ABresult
1X1
011
000
284 (
285 Podify
286 (
287 @_ == 1 || (! UseLongMessage())
288 ? $_[0] # user wants short message or there is only one message
289 : $_[1]
290 )
291 ) ;
292  
293 0 return ;
294 }
295  
296 #-------------------------------------------------------------------------------
297  
298 sub carp
299 4 ▶{
Subroutine carp: called CC=3 SCAR=11.0
Pod documented
300  
301 =head2 carp
302  
303 =head3 arguments
304  
305 =over 2
306  
307 =item short_message
308  
309 =item diagnostic (long message)
310  
311 =back
312  
313 if the diagnostic is POD, it will be converted to text.
314  
315 Calls Carp::carp to display the message.
316  
317 =cut
318  
319 4 local $Carp::CarpLevel = 1; ## no critic
320 4 ▶Carp::carp
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 || !UseLongMessage() ? : 2 2 4
Condition100%3/3
@_ == 1 or not UseLongMessage()
l!l&&r!l&&!r
112
MC/DC100%2/2
@_ == 1 or not UseLongMessage()
@_ == 1 not UseLongMessage()
Truth table100%3/3
A or not(B)
A= @_ == 1B= not UseLongMessage()
ABresult
1X1
011
000
321 (
322 Podify
323 (
324 @_ == 1 || (! UseLongMessage())
325 ? $_[0] # user wants short message or there is only one message
326 : $_[1]
327 )
328 ) ;
329  
330 4 return ;
331 }
332  
333 #-------------------------------------------------------------------------------
334  
335 sub cluck
336 4 ▶{
Subroutine cluck: called CC=3 SCAR=11.0
Pod documented
337  
338 =head2 cluck
339  
340 =head3 arguments
341  
342 =over 2
343  
344 =item short_message
345  
346 =item diagnostic (long message)
347  
348 =back
349  
350 if the diagnostic is POD, it will be converted to text.
351  
352 Calls Carp::cluck to display the message.
353  
354 =cut
355  
356 4 local $Carp::CarpLevel = 1; ## no critic
357 4 ▶Carp::cluck
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 || !UseLongMessage() ? : 2 2 4
Condition100%3/3
@_ == 1 or not UseLongMessage()
l!l&&r!l&&!r
112
MC/DC100%2/2
@_ == 1 or not UseLongMessage()
@_ == 1 not UseLongMessage()
Truth table100%3/3
A or not(B)
A= @_ == 1B= not UseLongMessage()
ABresult
1X1
011
000
358 (
359 Podify
360 (
361 @_ == 1 || (! UseLongMessage())
362 ? $_[0] # user wants short message or there is only one message
363 : $_[1]
364 )
365 ) ;
366  
367 4 return ;
368 }
369  
370 #-------------------------------------------------------------------------------
371  
372 sub Podify
373 20 ▶{
Subroutine Podify: called CC=3 SCAR=11.0
Pod documented
374  
375 =head2 Podify
376  
377 Transforms the passed string from B<POD> to text if it looks like POD. Returns the string. Transformed or not.
378  
379 This is used internally by this module.
380  
381 =cut
382  
383 20 my ($message) = @_ ;
384  
385 20 ▶if(defined $message)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $message) { } 16 4 20
386 {
387 16 ▶ if($message =~ /\A\s*^=/xsm)
Branch: 1 branch
BranchTrueFalseTotal
if ($message =~ /\A\s*^=/msx) { } 2 14 16
388 {
389 2 my ($in, $out) = (IO::String->new($message), IO::String->new());
390  
391 2 Pod::Text->new (width => GetTerminalWidth() - 2 )->parse_from_filehandle($in, $out) ;
392
393 2 return(${$out->string_ref()}) ;
394 }
395 else
396 {
397 14 return($message) ;
398 }
399 }
400 else
401 {
402 4 return ;
403 }
404 }
405  
406 #-------------------------------------------------------------------------------
407  
408 sub GetTerminalWidth
409 2 ▶{
Subroutine GetTerminalWidth: called CC=3 SCAR=11.8
Pod documented
410  
411 =head2 GetTerminalWidth
412  
413 Return the terminal width or 78 if it can't compute the width (IE: redirected to a file).
414  
415 This is used internally by this module.
416  
417 =cut
418  
419 2 my ($columns, $rows) ;
420  
421 2 ▶if($OSNAME ne 'MSWin32')
Branch: 1 branch
BranchTrueFalseTotal
if ($Carp::Diagnostics::OSNAME ne 'MSWin32') { } 2 0 2
422 {
423 2 eval "(\$columns, \$rows) = Term::Size::chars *STDOUT{IO} ;" ; ## no critic
424 }
425 else
426 {
427 0 ($columns, $rows) = $WIN32_CONSOLE->Size();
428 }
429  
430 2 ▶$columns = 78 if($columns eq $EMPTY_STRING) ;
Branch: 1 branch
BranchTrueFalseTotal
if $columns eq $EMPTY_STRING 2 0 2
431
432 2 return($columns) ;
433 }
434  
435 #-------------------------------------------------------------------------------
436  
437 3 1 ;
438  
439 =head1 BUGS AND LIMITATIONS
440  
441 None so far.
442  
443 =head1 AUTHOR
444  
445 Khemir Nadim ibn Hamouda
446 CPAN ID: NKH
447 mailto:nadim@khemir.net
448  
449 =head1 LICENSE AND COPYRIGHT
450  
451 This program is free software; you can redistribute
452 it and/or modify it under the same terms as Perl itself.
453  
454 =head1 SUPPORT
455  
456 You can find documentation for this module with the perldoc command.
457  
458 perldoc Carp::Diagnostics
459  
460 You can also look for information at:
461  
462 =over 4
463  
464 =item * AnnoCPAN: Annotated CPAN documentation
465  
466 L<http://annocpan.org/dist/Carp-Diagnostics>
467  
468 =item * RT: CPAN's request tracker
469  
470 Please report any bugs or feature requests to L <bug-carp-diagnostics@rt.cpan.org>.
471  
472 We will be notified, and then you'll automatically be notified of progress on
473 your bug as we make changes.
474  
475 =item * Search CPAN
476  
477 L<http://search.cpan.org/dist/Carp-Diagnostics>
478  
479 =back
480  
481 =head1 SEE ALSO
482  
483 Perl Best Practice by Damian Conway ISBN: 0-596-00173-8, a tremendous job.
484  
485 =cut
↑ Summary