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 arguments 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 following 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 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.

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 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:

    #__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!\n";
    #__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 preprocessor from a shell with the following options

    perl -s Devel/PreProcessor.pm -StripComments -StripPods \
    -StripBlankLines foo.pl | wc -l

BUGS AND SUPPORT

Release Status

This is a maintenance release of Devel::PreProcessor.

This module has been tested in several environments and no major problems have been discovered, but those tests have been somewhat limited and you are advised to try it in your environment to confirm it works as expected.

Known Problems

To Do: Improved Test Suite

The current test suite is quite limited, and only addresses the Includes functionality. Additional tests that exercise the other capabilities would be nice.

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.

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.

Support

If you have questions or feedback about this module, please feel free to contact the author at the below address. Although there is no formal support program, I do attempt to answer email promptly.

Bug reports that contain a failing test case are greatly appreciated, and suggested patches will be promptly considered for inclusion in future releases.

To report bugs via the CPAN web tracking system, go to http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-PreProcessor or send mail to Dist=Devel-PreProcessor#rt.cpan.org, replacing # with @.

Community

If you've found this module useful or have feedback about your experience with it, consider sharing your opinion with other Perl users by posting your comment to CPAN's ratings system:

• http://cpanratings.perl.org/rate/?distribution=Devel-PreProcessor

For more general discussion, you may wish to post a message on PerlMonks or the comp.lang.perl.misc newsgroup:

• http://www.perlmonks.org/index.pl?node=Seekers%20of%20Perl%20Wisdom

• http://groups.google.com/groups?group=comp.lang.perl.misc

DISTRIBUTION AND INSTALLATION

Version

This is Devel::PreProcessor version 2003.1128.

This module's CPAN registration should read:

  Name            DSLIP  Description
  --------------  -----  ---------------------------------------------
  Devel::
  ::PreProcessor  rdpfp  Module inlining and other Perl source manipulations

Prerequisites

In general, this module should work with Perl 5.003 or later, without requring any modules beyond the core Perl distribution.

Installation

You should be able to install this module using the CPAN shell interface:

  perl -MCPAN -e 'install Devel::PreProcessor'

Alternately, you may retrieve this package from CPAN or from the author's site:

• http://search.cpan.org/~evo/

• http://www.cpan.org/modules/by-authors/id/E/EV/EVO

• http://www.evoscript.org/Devel-PreProcessor/dist/

After downloading the distribution, follow the normal procedure to unpack and install it, using the commands shown below or their local equivalents on your system:

  tar -xzf Devel-PreProcessor-*.tar.gz
  cd Devel-PreProcessor-*
  perl Makefile.PL
  make test && sudo make install

Tested Platforms

This release has been tested succesfully on the following platforms:

  5.6.1 on darwin

You may also review the current test results from CPAN-Testers:

• http://testers.cpan.org/show/Devel-PreProcessor.html

CREDITS AND COPYRIGHT

Developed By

Developed by Matthew Simon Cavalletto at Evolution Softworks. You may contact the author directly at simonm@cavalletto.org. More free Perl software is available at www.evoscript.org.

Contributors

  Del Merritt
  Randy Roy, Win32 debugging assistance

Copyright

Copyright 2003 Matthew Cavalletto.

Portions copyright 1998, 1999 Evolution Online Systems, Inc.

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

License

You may use, modify, and distribute this software under the same terms as Perl.

cpanm Devel::PreProcessor

perl -MCPAN -e shell
install Devel::PreProcessor