Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses

Basic debugging checklist

by toolic (Bishop)
on Feb 23, 2009 at 00:06 UTC ( [id://745674]=perltutorial: print w/replies, xml ) Need Help??

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)
  2. use strict; use warnings; use diagnostics;
  3. Display the contents of variables using print or warn
  4. warn "$var\n"; print "@things\n"; # array with spaces between elements
  5. 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";
  6. 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?
  7. use Data::Dumper; print Dumper(\%hash); print Dumper($ref);
  8. If you were expecting a reference, make sure it is the right kind (ARRAY, HASH, etc.)
  9. print ref $ref, "\n";
  10. Check to see if your code is what you thought it was: B::Deparse

  11. $ perl -MO=Deparse -p
  12. 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 $@;
  13. Use Carp to display variables with a stack trace of module names and function calls.
  14. 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
  15. Demystify regular expressions by installing and using the CPAN module YAPE::Regex::Explain
  16. # what the heck does /^\s+$/ mean? use YAPE::Regex::Explain; print YAPE::Regex::Explain->new('/^\s+$/')->explain();
  17. Neaten up your code by installing and using the CPAN script perltidy. Poor indentation can often obscure problems.
  18. 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.

Replies are listed 'Best First'.
Re: Basic debugging checklist
by Bloodnok (Vicar) on Feb 23, 2009 at 01:19 UTC
    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...

    A user level that continues to overstate my experience :-))
Re: Basic debugging checklist
by hexcoder (Curate) on Jun 21, 2014 at 11:07 UTC
    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.
Re: Basic debugging checklist
by LanX (Saint) on Dec 03, 2017 at 13:54 UTC
    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.


    C:\>perl $var = "abc\n"; # trailing newline warn "$var\n"; warn "<$var>"; warn "$var"; __END__ abc <abc > at - line 4. abc

    Cheers Rolf
    (addicted to the Perl Programming Language and ☆☆☆☆ :)
    Wikisyntax for the Monastery


    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.

      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.


      John Davies

        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.


        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.

        Cheers Rolf
        (addicted to the Perl Programming Language :)
        Wikisyntax for the Monastery

      I think the "\n" stems from (originally) just replacing print with warn.
        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.

        Quantum Mechanics: The dreams stuff is made of

Re: Basic debugging checklist
by choroba (Cardinal) on Feb 28, 2020 at 17:33 UTC
    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

    map{substr$_->[0],$_->[1]||0,1}[\*||{},3],[[]],[ref qr-1,-,-1],[{}],[sub{}^*ARGV,3]
Re: Basic debugging checklist
by Anonymous Monk on Mar 14, 2013 at 00:17 UTC

    Not sure if your perl version is too old?

    Use Perl::MinimumVersion/perlver

    $ perlver -------------------------------------- | file | explicit | syntax | external | | -------------------------------------- | | | ~ | v5.10.0 | n/a | | -------------------------------------- | | Minimum explicit version : ~ | | Minimum syntax version : v5.10.0 | | Minimum version of perl : v5.10.0 | -------------------------------------- $ perlver --blame ------------------------------------------------------------ File : Line : 3 Char : 17 Rule : _perl_5010_operators Version : 5.010 ------------------------------------------------------------ ~~ ------------------------------------------------------------ $ cat 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, and perl will do the version check

Re: Basic debugging checklist
by Anonymous Monk on Oct 03, 2014 at 02:58 UTC
    perl -Mre=debug can help you see how perl interprets your regex, much in the way O=Deparse does for perl code
      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

Re: Basic debugging checklist
by umasuresh (Hermit) on Jan 28, 2010 at 16:33 UTC
    Thanks a lot toolic, very useful post!

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perltutorial [id://745674]
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (3)
As of 2024-06-15 08:35 GMT
Find Nodes?
    Voting Booth?

    No recent polls found

    erzuuli‥ 🛈The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.