Devel::PreProcessor - Module inlining and other Perl source manipulations
From a command line,
sh> perl Devel/PreProcessor.pm -Flags sourcefile > targetfile
Or in a Perl script,
use Devel::PreProcessor qw( Flags );
Devel::PreProcessor::parse_file( $source_pathname );
This package processes Perl source files and outputs a modified version acording to several user-setable option flags, as detailed below.
Each of the flag names listed below can be used as above, with a hyphen on the command line, or as one of the arguments in an import statement. Each of these flags are mapped to the scalar package variable of the same name.
If true, parse_file will attempt to replace require, use and no statements with inline declarations containg the source of the relevant library found in the current @INC. The resulting script should operate identically and no longer be dependant on external libraries (but see compatibility note below).
If the corresponding file can not be located, the statements are left unchanged in the source; numeric perl version requirements are handled the same way.
If a use libs ... statement is encountered in the source, the library path arguments are evaluated and pushed onto @INC at run-time to enable inclusion of libraries from these paths.
use libs ...
Unless the file explicitly use's or require's AutoLoader, information after __END__ is not included in the resultant file. Information after __DATA__ is also discarded, except for the first, outermost source file.
If true, comment lines will be inserted delimiting the start and end of each inlined file.
If true, parse_file will not include POD from the source files. All groups of lines resembling the following will be discarded:
If true, parse_file will skip lines that are empty, or that contain only whitespace.
If true, parse_file will not include full-line comments from the source files. Only lines that start with a pound sign are discarded; this behaviour might not match Perl's parsing rules in some cases, such as multiline strings.
If true, parse_file will utilize a simple conditional inclusion scheme, as follows.
#__CONDITIONAL__ if expr
The provided Perl expression is evaluated, and unless it is true, everything up to the next endif declaration is replaced with empty lines. In order to allow the default behavour to be provided when running the raw files, comment out lines in non-default branches with the following:
Empty lines are used in place of skipped blocks to make line numbers come out evenly, but conditional use or require statements will throw the count off, as we don't pad by the size of the file that would have been in-lined.
The conditional functionality can be combined with Perl's -s switch, which allows you to set flags on the command line, such as:
perl -s Devel/PreProcessor.pm -Conditionals -Switch filter.test
You can use any name for your switch, and the matching scalar variable will be set true; the following code will only be used if you supply the argument as shown below.
#__CONDITIONAL__ if $Switch
#__CONDITIONAL__ print "you hit the switch!\n";
To inline all used modules:
perl -s Devel/PreProcessor.pm -Includes foo.pl > foo_complete.pl
To count the lines of Perl source in a file, run the preprocessor from a shell with the following options
perl -s Devel/PreProcessor.pm -StripComments -StripPods \
-StripBlankLines foo.pl | wc -l
Libraries inlined with Includes may not be appropriate on another system; for example, if Config is inlined, the script may fail if run on a platform other than that on which it was built. This problem can be minimized by adjusting the search path to not include modules in the version- or architecture-specific library trees, but you will then need to ensure that those modules are available on the execution platform.
While some pragmas are known to work, including use vars, problems may pop up with others. In particular, use strict and no strict pragmas are removed from the resulting source, because their scoping changes in a single-file context, usually with fatal results.
Should support newline in import blocks for multiline use statements.
Few modules place anything other than POD in a __DATA__ section, much less ever try to read from it, so this hasn't been a priority to fix.
There's not much we can do about XSub/SO/PLL files.
This package should run on any standard Perl 5 installation.
You may retrieve this package from the below URL: http://www.evoscript.com/dist/
To install this package, download and unpack the distribution archive, then:
This release of Devel::PreProcessor is intended primarily for public review and feedback, but is stable enough for production use. It has been tested in several environments and no major problems have been discovered, but it should be considered "beta" pending further feedback.
Name DSLI Description
-------------- ---- ---------------------------------------------
::PreProcessor bdpf Module inlining and other Perl source manipulations
Further information and support for this module is available at <www.evoscript.com>.
Please report bugs or other problems to <firstname.lastname@example.org>.
Copyright 1998, 1999 Evolution Online Systems, Inc. <www.evolution.com>
You may use this software for free under the terms of the Artistic License.
Contributors: M. Simon Cavalletto <email@example.com> and Del Merritt <firstname.lastname@example.org>, with Win32 debugging assistance from Randy Roy.
Derived from filter.pl, as provided by ActiveWare <www.activestate.com>
To install Devel::PreProcessor, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.