NAME
Carp::Diagnostics - Carp with a diagnostic message
SYNOPSIS
use Carp::Diagnostics qw(cluck carp croak confess) ;
CroakingSub() ;
#---------------------------------------------------------------------------
sub CroakingSub
{
=head2 CroakingSub
An example of how to use Carp::Diagnostics.
=head3 Diagnostics
=cut
my ($default_rule_name, $name) = ('c_objects', 'o_cs_meta') ;
confess
(
"Default rule '$default_rule_name', in rule '$name', doesn't exist.\n",
<<END_OF_POD,
=over
=item Default rule '$default_rule_name', in rule '$name', doesn't exist!
The default rule of a I<FirstAndOnlyOneOnDisk> B<META_RULE> must be registrated before
the B<META_RULE> definiton. Here is an example of declaration:
AddRule 'c_o', [ '*/*.o' => '*.c' ], \&C_Builder ;
AddRule 'cpp_o', [ '*/*.o' => '*.cpp' ], \&CPP_Builder ;
AddRule [META_RULE], 'o_cs_meta',
[\&FirstAndOnlyOneOnDisk, ['cpp_o', 'c_o' ], 'c_o'] ;
^- slave rules -^ ^-default
=back
=cut
END_OF_POD
) ;
}DESCRIPTION
This module overrides the subs defined in Carp to allow you to give informative diagnostic messages.
DOCUMENTATION
Perl Best Practices recommends to have a DIAGNOSTIC section, in your POD, where all your warnings and errors are explained in details. Although I like the principle, I dislike its proposed implementation. Why should we display cryptic messages at run time that the user have to lookup in the documentation? I also dislike to have the diagnostics grouped far from where the errors are generated, they never get updated.
This modules implements the four subs exported by the Carp module (carp, croak, cluck, confess). The new subs take zero, one or two arguments.
No argument
No message
One argument
A message
Two arguments
A short message
A diagnostic message
The long message is a diagnostic and is the one normally displayed.
You can direct Carp::Diagnostics to display the short message; this is useful when developing modules. You, the module author, understand short warnings. See UseLongMessage.
Having the possibility to pass one argument or two gives you the possibility to drop-in Car::Diagnostics in your module 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 second argument to, your already existing, carp call.
The podification functionality is always on.
Carp is used internally so you get an identical functionality.
POD: Eating your cake and having it too.
The good news is that you are going to do two things in one shot. You'll be giving better diagnostics to your users and you'll be documenting your modules too.
If the long message (diagnostic) is POD (the first non space character is an '=' at the start of the line), Carp::Diagnostics will convert the pod to text and pass it to Carp::.
$ perl cd_test.pl
Default rule 'c_objects', in rule 'o_cs_meta', doesn't exist!
The default rule of a *FirstAndOnlyOneOnDisk* META_RULE must be registrated before the
META_RULE definiton. Here is an example of declaration:
AddRule 'c_o', [ '*/*.o' => '*.c' ], \&C_Builder ;
AddRule 'cpp_o', [ '*/*.o' => '*.cpp' ], \&CPP_Builder ;
AddRule [META_RULE], 'o_cs_meta',
[\&FirstAndOnlyOneOnDisk, ['cpp_o', 'c_o' ], 'c_o'] ;
^- slave rules -^ ^-default
at cd_test.pl line 26
main::CroakingSub() called at cd_test.pl line 11 Since the diagnostic is valid pod, it will be extracted when you generate your documentation.
$ pod2text cd_test.pl
CroakingSub
An example of how to use Carp::Diagnostics.
Diagnostics
Default rule '$default_rule_name', in rule '$name', doesn't exist!
The default rule of a *FirstAndOnlyOneOnDisk* META_RULE must be
registrated before the META_RULE definiton. Here is an example of
declaration:
AddRule 'c_o', [ '*/*.o' => '*.c' ], \&C_Builder ;
AddRule 'cpp_o', [ '*/*.o' => '*.cpp' ], \&CPP_Builder ;
AddRule [META_RULE], 'o_cs_meta',
[\&FirstAndOnlyOneOnDisk, ['cpp_o', 'c_o' ], 'c_o'] ;
^- slave rules -^ ^-defaultSUBROUTINES/METHODS
UseLongMessage
Give 0 as argument if you want to display the short message. The only reason to use this is when developing modules which use Carp::Diagnostics. Even then it's not a very good reason for not displaying a complete diagnostic.
This setting is global.
croak
arguments
if the diagnostic is POD, it will be converted to text.
Calls Carp::croak to display the message.
confess
arguments
if the diagnostic is POD, it will be converted to text.
Calls Carp::confess to display the message.
carp
arguments
if the diagnostic is POD, it will be converted to text.
Calls Carp::carp to display the message.
cluck
arguments
if the diagnostic is POD, it will be converted to text.
Calls Carp::cluck to display the message.
Podify
Transforms the passed string from POD to text if it looks like POD. Returns the string. Transformed or not.
This is used internally by this module.
GetTerminalWidth
Return the terminal width or 78 if it can't compute the width (IE: redirected to a file).
This is used internally by this module.
BUGS AND LIMITATIONS
None so far.
AUTHOR
Khemir Nadim ibn Hamouda
CPAN ID: NKH
mailto:nadim@khemir.netLICENSE AND COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Carp::DiagnosticsYou can also look for information at:
AnnoCPAN: Annotated CPAN documentation
RT: CPAN's request tracker
Please report any bugs or feature requests to L <bug-carp-diagnostics@rt.cpan.org>.
We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN
SEE ALSO
Perl Best Practice by Damian Conway ISBN: 0-596-00173-8, a tremendous job.