perlmeditation
liz
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://begin|CPAN mirror] near you (or available from my [http://www.liz.nl/CPAN|own CPAN modules] site).
<P>
However, I'm a bit in two minds about its name: <B>[http://www.liz.nl/CPAN/begin-0.02.tar.gz|begin]</b>. 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.
<P>
Anyway, I wonder what my fellow monks would want to say about it.
<P>
<READMORE>
Here is an excerpt from the pod:
<DL>
<DT>NAME
<DD>begin - conditionally enable code within =begin pod sections
<P>
<DT>SYNOPSIS
<DD>
<CODE>
export DEBUGGING=1
perl -Mbegin yourscript.pl
</CODE>
or:
<CODE>
perl -Mbegin=VERBOSE yourscript.pl
</CODE>
or:
<CODE>
perl -Mbegin=all yourscript.pl
</CODE>
with:
<CODE>
======= 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
========================================
</CODE>
<P>
<DT>DESCRIPTION
<DD>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).
<P>
To prevent interference with other pod handlers, the name of the pod
handler must be in uppercase.
<P>
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:
<CODE>
my $foo = 2;
=begin DEBUGGING
my $foo = 1;
warn "debug foo = $foo\n";
=cut
warn "normal foo = $foo\n";
</CODE>
is converted on the fly (before Perl compiles it) to:
<CODE>
my $foo = 2;
{
my $foo = 1;
warn "foo = $foo\n";
}
warn "normal foo = $foo\n";
</CODE>
<P>
But of course, this happens only if the "begin" pragma is loaded and the environment variable DEBUGGING is set.
</DL>
<P>
All other feedback is of course always appreciated!
</READMORE>
<P>
Liz
<P>
<B>Update</B>:<BR>
I've decided to change the name of the pragma (as seen by the outside world) to "<B>[cpan://ifdef]</B>". 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 [http://www.liz.nl/CPAN|my own CPAN modules site].