نديم ابن ﺤﻣﻮﺪﺓ الخمير - Nadim Khemir > Carp-Diagnostics-0.05.3 > Carp::Diagnostics

Download:
Carp-Diagnostics-0.05.3.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.05   Source  

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

One argument

Two arguments

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.

syntax highlighting: