Update: The updated version of this Meditation is at Re: RFC: Basic debugging checklist (updated) and the Tutorial version is now at Basic debugging checklist. Here is the untouched original:

Before I post this as a Tutorial, please help me to improve this by offering constructive feedback.

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:

  1. Add the "stricture" pragmas (Use strict and warnings)
    2. use strict;
use warnings;
use diagnostics;

    [download]
  2. Print the contents of variables
    3. print "$var\n";
print "@things\n";   # array with spaces between elements

    [download]
  3. Check for unexpected whitespace
    • chomp, then print with colon delimiters for visibility 
      chomp $var;
print ":$var:\n";

      [download]
    • Check for unprintable characters and identify them by their ASCII codes using ord 
      print ":$_:", ord($_), "\n" for (split //, $str)

      [download]
  4. Dump arrays, hashes and arbitrarily complex data structures 
    5. use Data::Dumper;
print Dumper(\%hash);
print Dumper($ref);

    [download]
  5. If you were expecting a reference, make sure it is the right kind (ARRAY, HASH, etc.) 
    6. print ref $ref, "\n";

    [download]

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

    7. $ perl -MO=Deparse program.pl

    [download]

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

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

      [download]
    • system and backticks (qx) with $? 
      if (system $cmd) {
    print "Error: $? for command $cmd"
}
else {
    print "Command $cmd is OK"
}
$out = `$cmd`; print $? if $?;

      [download]
    • eval with $@ 
      eval { do_something() }; warn $@ if $@;

      [download]
  8. Demystify regular expressions using the CPAN module YAPE::Regex::Explain 
    9. # what the heck does /^\s+$/ mean?
use YAPE::Regex::Explain;
print YAPE::Regex::Explain->new('/^\s+$/')->explain();

    [download]
  9. 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.
    • 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()) { ... }

      [download]

In reply to RFC: Basic debugging checklist by toolic

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.