Today I finally bit the bullet. I created a pragma (lowercase name module) that allows you to add debug code to your programs that will only actually compile when you tell it to. And to boot, I wrote documentation and a test-suite for it and it's now on the way to a CPAN mirror near you (or available from my own CPAN modules site).

However, I'm a bit in two minds about its name: begin. The reason I chose "begin" as the name, is that it is based on the behaviour of the =begin pod directive. I'm also thinking that "debug" might be a good name. But that doesn't indicate how the magic is achieved.

Anyway, I wonder what my fellow monks would want to say about it.

Here is an excerpt from the pod:
NAME
begin - conditionally enable code within =begin pod sections

SYNOPSIS 
export DEBUGGING=1
perl -Mbegin yourscript.pl

[download]
or: 
perl -Mbegin=VERBOSE yourscript.pl

[download]
or: 
perl -Mbegin=all yourscript.pl

[download]
with: 
======= yourscript.pl ===================

# code that's always compiled and executed

=begin DEBUGGING

warn "Only compiled and executed when DEBUGGING or 'all' enabled\n"

=cut

# code that's always compiled and executed

=begin VERBOSE

warn "Only compiled and executed when VERBOSE or 'all' enabled\n"

=cut

# code that's always compiled and executed

========================================

[download]

DESCRIPTION
The "begin" pragma allows a developer to add sections of code that will be compiled and executed only when the "begin" pragma is specifically enabled. If the "begin" pragma is not enabled, then there is no overhead involved in either compilation of execution (other than the standard overhead of Perl skipping =pod sections).

To prevent interference with other pod handlers, the name of the pod handler must be in uppercase.

If a =begin pod section is considered for replacement, then a scope is created around that pod section so that there is no interference with any of the code around it. For example: 

my $foo = 2;

=begin DEBUGGING

my $foo = 1;
warn "debug foo = $foo\n";

=cut

warn "normal foo = $foo\n";

[download]
is converted on the fly (before Perl compiles it) to: 
my $foo = 2;

{

my $foo = 1;
warn "foo = $foo\n";

}

warn "normal foo = $foo\n";

[download]

But of course, this happens only if the "begin" pragma is loaded and the environment variable DEBUGGING is set.

All other feedback is of course always appreciated!

Liz

Update:
I've decided to change the name of the pragma (as seen by the outside world) to "ifdef". I've also fixed the problems found by "Mr. Muskrat" and dbwiz and added an API for AUTOLOADing modules that may want to do the same source code conversion. For the impatient ones, also available from my own CPAN modules site.

In reply to Debug code out of production systems by liz

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.