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.

REQUIRED MODULES

Filter::Util::Call (any)
IO::File (any)

IMPLEMENTATION

This version is completely written in Perl. It uses a globally installed source filter to provide its magic. 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

Source filter

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 source filter is 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.

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.