NAME
Simple::Filter::Macro - Perl extension for expanding source code inline in a script or module.
SYNOPSIS
In script or module:
use ExamplePackage::Modules;In module Modules.pm of a package ExamplePackage:
package ExamplePackage::Modules;
# Set the VERSION number.
$VERSION = '0.01';
# Use the magic module.
use Simple::Filter::Macro; # <-- The magic is found here.
# The lines below will be expanded into the caller's code.
use strict;
use warnings;
use diagnostics;
use sigtrap;
use ExamplePackage::ReadFile;
use ExamplePackage::ModifyFile;
use ExamplePackage::WriteFile;
use re 'debug'
no utf8;
# Add as much use statements as you like.
# Package terminator 1; will not be written to caller's code.
1; DESCRIPTION
The module is expanding source code inline in a script or a module. This statement is valid, when the use statement is reachable while compilation. It will not work in a if statement or code block.
One use case can be find in the SYNOPSIS. It is common practice to load modules using the use statement while compilation. Subroutine imports of modules from ExamplePackage takes effect in that module but not in the calling script. The same thing is valid for Perl pragmas. They take effect in the script or in the module not in the calling script or module.
It's a kind of magic when it is possible to change the source code while compilation. That's happens here. The package defined module as well as the script of an user creates a compiled file with the extensions .pmc and .plc.
METHOD
None
EXPORT
None
PROGRAMMING BACKGROUND
A outer filter is applied. In this loop, the content of the given module is modified in a way, that comments are removed and the module terminator 1; is is stripped.
Then a inner filter is applied. In the inner filter the module content is concatenated to the content of the given script. Both is written to the file with the head created applying the filter procedure.
NOTES
Use
use Simple::Filter::MacroLight; # <-- The magic is found here.for a prefiltered .plc file. Simple::Filter::MacroLight is removing comments from the script content before the complete content is written to a file.
KNOWN ISSUES
Running a script using Simple::Filter::Macro
perl test_script.pl will create an error message on the second run. If the script runs using
./test_script.plno error occurs.
Nevertheless
perl test_script.plcis all the time working. This has to checked.
TO-DO
Improvement of the documentation.
MOTIVATION
I was looking for a module that would allow me to merge a number of use pragma declarations in the module and replace them with a single use pragma declaration. The module Filter::Macro that I found contains the right approaches for this, but is not executable under Perl v5.30 how I found out. After analysing the source code, I decided to create a new module based on the aforementioned approaches. The problem in the source code As I figured out is the use of the Perl command quotemeta. Since Perl v5.16 the use of quotemeta is obsolet as I suppose. The first attempts with basic changes in the source code were not without errors. In the meantime, the Perl code works as expected. The first two methods of this module are the result of my efforts.
EXPORT
None
SEE ALSO
CREDITS
Special thanks go to Audrey Tang, who wrote the Filter::Macro module, which contains the crucial approaches to implementing the present package and its modules and methods.
AUTHOR
Dr. Peter Netz, <ztenretep@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2022 by Dr. Peter Netz
This library is free software; you can redistribute it and/or modify it under the same terms of The MIT License. For more details, see the full text of the license in the attached file LICENSE in the main module folder. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.