NAME
begin - conditionally enable code within =begin pod sections
SYNOPSIS
export DEBUGGING=1
perl -Mbegin yourscript.pl
or:
perl -Mbegin=VERBOSE yourscript.pl
or:
perl -Mbegin=all yourscript.pl
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
======================================================================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";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";But of course, this happens only if the "begin" pragma is loaded and the environment variable DEBUGGING is set.
WHY?
One day, I finally had enough of always putting in and taking out debug statements from modules I was developing. I figured there had to be a better way to do this. Now, this module allows to leave debugging code inside your programs and only have them come alive when you want them to be alive. Without any run-time penalties when you're in production.
REQUIRED MODULES
Filter::Util::Call (any)
IO::File (any)IMPLEMENTATION
This version is completely written in Perl. It uses a source filter to provide its magic to the script being run and an @INC handler for all of the modules that are loaded otherwise. Because the =begin pod directive is ignored by Perl during normal compilation, the source filter is not needed for production use so there will be no performance penalty in that case.
CAVEATS
Overhead during development
Because the "begin" pragma uses a source filter for the invoked script, and an @INC handler for all further required files, there is an inherent overhead for compiling Perl source code. Not loading begin.pm at all, causes the normal =begin pod ignoring functionality of Perl to come in place (without any added overhead).
No nesting allowed
Out of performance reasons, the filters are kept as simple as possible. This is done by keeping only a single flag to mark whether the filter is inside a =begin section with code to be activated. For this reason, no nesting of =begin sections are supported. And there is also no check for it, so if you _do_ do this, then you'd better know what you're doing.
No changing of environment variables during execution
Since the "begin" pragma performs all of this magic at compile time, it generally does not make sense to change the values of applicable environment variables at execution, as there will be no compiled code available to activate.
Modules that use AutoLoader, SelfLoader, load, etc.
For the moment, these modules bypass the mechanism of this module. An interface with load.pm is on the TODO list. Patches for other autoloading modules are welcomed.
AUTHOR
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
COPYRIGHT
Copyright (c) 2004 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.