/ 
Carp-Diagnostics-0.05.3
River stage one • 1 direct dependent • 1 total dependent
/ Carp::Diagnostics

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 -^    ^-default

SUBROUTINES/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

short_message
diagnostic (long message)

if the diagnostic is POD, it will be converted to text.

Calls Carp::croak to display the message.

confess

arguments

short_message
diagnostic (long message)

if the diagnostic is POD, it will be converted to text.

Calls Carp::confess to display the message.

carp

arguments

short_message
diagnostic (long message)

if the diagnostic is POD, it will be converted to text.

Calls Carp::carp to display the message.

cluck

arguments

short_message
diagnostic (long message)

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.net

LICENSE 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::Diagnostics

You can also look for information at:

SEE ALSO

Perl Best Practice by Damian Conway ISBN: 0-596-00173-8, a tremendous job.