devel::preprocessor(3)

NAME

Devel::PreProcessor - Module inlining and other Perl
source manipulations

SYNOPSIS

From a command line,
    sh> perl  Devel/PreProcessor.pm  -Flags  sourcefile  >
targetfile
Or in a Perl script,
    use Devel::PreProcessor qw( Flags );
    select(OUTPUTFH);
    Devel::PreProcessor::parse_file( $source_pathname );

DESCRIPTION

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 argu
ments in an import statement. Each of these flags are
mapped to the scalar package variable of the same name.

Includes: 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.; 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.
ShowFileBoundaries: If true, comment lines will be inserted delimiting the
start and end of each inlined file.
StripPods: If true, parse_file will not include POD from the
source files. All groups of lines resembling the fol
lowing will be discarded:

=(pod|head1|head2)
...
=cut
StripBlankLines: If true, parse_file will skip lines that are empty, or
that contain only whitespace.
StripComments: If true, parse_file will not include full-line com
ments 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.
Conditionals: If true, parse_file will utilize a simple conditional
inclusion scheme, as follows.

#__CONDITIONAL__ if expr
...
#__CONDITIONAL__ endif; The provided Perl expression is evaluated, and unless
it is true, everything up to the next endif declara
tion 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:

#__CONDITIONAL__ ...; 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!0;
#__CONDITIONAL__ endif

EXAMPLES

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 pre processor from a shell with the following options: perl -s Devel/PreProcessor.pm -StripComments -Strip; Pods -StripBlankLines foo.pl | wc -l

BUGS AND CAVEATS

Compatibility: Includes: 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.
Limitation: Pragmas: 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.
Bug: Multi-line use statements not handled: Should support newline in import blocks for multiline
use statements.
Limitation: Module __DATA__ contents lost: 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.
Limitation: binary files not included: There's not much we can do about XSub/SO/PLL files.

PREREQUISITES AND INSTALLATION

This package should run on any standard Perl 5 installa
tion.

You may retrieve this package from the below URL:: http://www.evoscript.com/dist/
To install this package, download and unpack the distribu tion archive, then:
� "perl Makefile.PL" � "make test" � "make install"

STATUS AND SUPPORT

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
-------------- ---; --------------------------------------------Devel::
::PreProcessor bdpf Module inlining and other Perl; source manipulations
Further information and support for this module is avail able at <www.evoscript.com>.
Please report bugs or other problems to <bugs@evo script.com>.

AUTHORS AND COPYRIGHT

You may use this software for free under the terms of the
Artistic License.

Contributors: M. Simon Cavalletto <simonm@evolution.com>
and Del Merritt <dmerritt@intranetics.com>, with Win32
debugging assistance from Randy Roy.

Derived from filter.pl, as provided by ActiveWare
<www.activestate.com>

docs.sk

comprehensive documentation repository

Most Viewed