Basic debugging checklist

[toolic]

Are you new to Perl? Is your program misbehaving? Not sure where or how to begin debugging? Well, here is a concise checklist of tips and techniques to get you started.

This list is meant for debugging some of the most common Perl programming problems; it assumes no prior working experience with the Perl debugger (perldebtut). Think of it as a First Aid kit, rather than a fully-staffed state-of-the-art operating room.

These tips are meant to act as a guide to help you answer the following questions:

• Are you sure your data is what you think it is?
• Are you sure your code is what you think it is?
• Are you inadvertently ignoring error and warning messages?

1. Add the "stricture" pragmas (Use strict and warnings)

use strict;
use warnings;
use diagnostics;

2. Display the contents of variables using print or warn

warn "$var\n";
print "@things\n";   # array with spaces between elements

3. Check for unexpected whitespace
• a) chomp, then print with delimiters of your choice, such as colons or balanced brackets, for visibility

  chomp $var;
  print ">>>$var<<<\n";
  

• b) Check for unprintable characters by converting them into their ASCII hex codes using ord

  my $copy = $str;
  $copy =~ s/([^\x20-\x7E])/sprintf '\x{%02x}', ord $1/eg;
  print ":$copy:\n";
  

4. Dump arrays, hashes and arbitrarily complex data structures. You can get started using the core module Data::Dumper. Should the output prove to be unsuitable to you, other alternatives can be downloaded from CPAN, such as Data::Dump, YAML, or JSON. See also How can I visualize my complex data structure?

use Data::Dumper;
print Dumper(\%hash);
print Dumper($ref);

5. If you were expecting a reference, make sure it is the right kind (ARRAY, HASH, etc.)

print ref $ref, "\n";

6. Check to see if your code is what you thought it was: B::Deparse

$ perl -MO=Deparse -p program.pl

7. Check the return (error) status of your commands

• open with $!

  open my $fh, '<', 'foo.txt' or die "can not open foo.txt: $!";
  

• system and backticks (qx) with $?

  if (system $cmd) {
      print "Error: $? for command $cmd"
  }
  else {
      print "Command $cmd is OK"
  }
  $out = `$cmd`; print $? if $?;
  

• eval with $@

  eval { do_something() }; warn $@ if $@;
  

8. Use Carp to display variables with a stack trace of module names and function calls.

use Carp qw(cluck);
cluck("var is ($var)");

Better yet, install and use the Carp::Always CPAN module to make your existing warn/die complain with a stack trace:

$ perl -MCarp::Always program.pl

9. Demystify regular expressions by installing and using the CPAN module YAPE::Regex::Explain

# what the heck does /^\s+$/ mean?
use YAPE::Regex::Explain;
print YAPE::Regex::Explain->new('/^\s+$/')->explain();

10. Neaten up your code by installing and using the CPAN script perltidy. Poor indentation can often obscure problems.
11. Checklist for debugging when using CPAN modules:
• Check the Bug List by following the module's "View Bugs" link.
• Is your installed version the latest version? If not, check the change log by following the "Changes" link. Also follow the "Other Tools" link to "Diff" and "Grep" the release.
• If a module provides status methods, check them in your code as you would check return status of built-in functions:

  use WWW::Mechanize;
  if ($mech->success()) { ... }
  

What's next? If you are not already doing so, use an editor that understands Perl syntax (such as vim or emacs), a GUI debugger (such as Devel::ptkdb) or use a full-blown IDE. Lastly, use a version control system so that you can fearlessly make these temporary hacks to your code without trashing the real thing.

For more relevant discussions, refer to the initial Meditation post: RFC: Basic debugging checklist

Updated: Sep 8, 2009: Added CPAN Diff/Grep tip.
Updated: Jan 11, 2011: Added Carp::Always.

[Bloodnok]

Damned decent posting :D ... just a coupla suggestions tho'...
• Step 5 - Use a stringified ref. to provide straightforward visual comparison of 2, or more, ref.s - I've recently been using this to verify that a ref. in 2 different places is actually the same object.
• Step 7 - add use autodie; to provide default exception throwing on failure
• Step 7 & 8 - add use CGI::Carp; for CGI/WWW scripts
• Your final observation WRT IDEs etc. could, IMHO, suggest that the use of Eclipse, for perl dev't, isn't for the fainthearted...
Just a thought...

[hexcoder]

When debugging warnings from the perl core like Use of uninitialized value ... let the debugger pause right there. Then have a good look at the context that led to this situation and investigate variables and the callstack.

To let the debugger do this automatically I use a debugger customization script:

sub afterinit 
{
    $::SIG{'__WARN__'} = sub {
        my $warning = shift;
        if ( $warning =~ m{\s at \s \S+ \s line \s \d+ \. $}xms ) {
            $DB::single = 1;    # debugger stops here automatically
        }
        warn $warning;
    };
    print "sigwarn handler installed!\n";
    return;
}

Save the content to file .perldb (or perldb.ini on Windows) and place it in the current or in your HOME directory.
The subroutine will be called initially by the debugger and installs a signal handler for all warnings. If the format matches one from the perl core, execution in the debugger is paused by setting $DB::single = 1.

[LanX]

hexcoder++ :)

For further informations: afterinit , .perldb and other options are described in:

--> perldebug#Debugger Customization

[LanX]

Hi toolic

Nice work, but may I suggest that

> Display the contents of variables using print or warn

> warn "$var\n";

is changed to

warn "<$var>";

?

Two reasons:

• I don't see the point of disabling line and file information from warn by default by appending "\n".

  A beginner might get lost where the error originates.

• A missing chomp is very common, surrounding brackets <...> helps finding them.

  A beginner should be made aware if his variable ends on a newline.

see

C:\>perl
$var = "abc\n";    # trailing newline

warn "$var\n";
warn "<$var>";
warn "$var";

__END__
abc

<abc
> at - line 4.
abc

update

I just realized that your point 3 covers chomp and detecting whitespace, but I'm still not sure why you're disabling the line info in warn.

[Athanasius]

On the subject of detecting unexpected whitespace, mention should also be made of another node that regularly appears in Selected Best Nodes:

Unbelievably Obvious Debugging Tip by dreadpiratepeter

Cheers,

[davies]

I recently got bitten by doing this. The debugging messages were going to the web page. The code was misbehaving, but no debugging messages appeared. View Source explained why - because I had used < and >, they were being interpreted as HTML tags that made no sense & were ignored. Since then, I've been using square brackets.

Regards,

John Davies

[LanX]

yeah that's why CGI::Carp translates -> to -» and so on, which makes some dumps hard to read.

My preference to <...> over [...] stems from the fact that square brackets are easily confused as array syntax by the eye.

I'd suggest to either double or invert the angle brackets, I doubt that <<...>> or >...< are easily confused as HTML tags.

update

I was wrong with the simple doubling, this <<br>> would be a a break surrounded by angles.

Though this might help ->...<-

I'm open for other ASCII suggestions, i.e. avoiding unicode.

[soonix]

I think the "\n" stems from (originally) just replacing print with warn.

[QM]

It has always been well documented that warn or die, with a terminating newline, doesn't emit the line and file info. But warn with a newline is essentially the same as print STDERR, if a little more self-documenting.

[choroba]

Maybe it's time to update the eval line to

eval { do_something(); 1 } or warn $@;

Here's why: Bug in eval in pre-5.14

[Anonymous Monk]

Not sure if your perl version is too old?

Use Perl::MinimumVersion/perlver

$ perlver foo.pl


   --------------------------------------
 | file   | explicit | syntax  | external |
 | -------------------------------------- |
 | foo.pl | ~        | v5.10.0 | n/a      |
 | -------------------------------------- |
 | Minimum explicit version : ~                             |
 | Minimum syntax version   : v5.10.0                       |
 | Minimum version of perl  : v5.10.0                       |
   --------------------------------------

$ perlver --blame foo.pl

 ------------------------------------------------------------
 File    : foo.pl
 Line    : 3
 Char    : 17
 Rule    : _perl_5010_operators
 Version : 5.010
 ------------------------------------------------------------
 ~~
 ------------------------------------------------------------

$ cat foo.pl
my $foo = 6;
my @bar = ( 3,6, 9 );
print 1 if $foo ~~ @bar;

Then you can add use v5.10.0; or <c> use 5.01000; to your foo.pl, and perl will do the version check

[Anonymous Monk]

perl -Mre=debug foo.pl can help you see how perl interprets your regex, much in the way O=Deparse does for perl code

[Anonymous Monk]

If you don't quite understand what you're looking at (output of deparse, perl syntax), then ppi_dumper can help you look at the right part of the manual, an example

$ ppi_dumper 2
PPI::Document
  PPI::Statement::Include
    PPI::Token::Word    'use'
    PPI::Token::Whitespace      ' '
    PPI::Token::Word    'constant'
    PPI::Token::Whitespace      ' '
    PPI::Token::Word    'X'
    PPI::Token::Whitespace      ' '
    PPI::Token::Operator        '=>'
    PPI::Token::Whitespace      ' '
    PPI::Token::Number          '1'
    PPI::Token::Operator        '/'
    PPI::Token::Number          '3'
    PPI::Token::Structure       ';'
  PPI::Token::Whitespace        '\n'
  PPI::Token::Whitespace        '\n'

So PPI::Token::Operator tells you "=>" is an operator

If you read perl/"perltoc" then you'll know that operators are documented in perlop

App::PPI::Dumper / ppi_dumper

wxPPIxregexplain.pl

[umasuresh]

Thanks a lot toolic, very useful post!