NAME
Simple::Filter::Macro - Perl extension for expanding source code inline in a script or module.
SYNOPSIS
In script e.g. TestScript.pl or module e.g. TestModule.pm:
use ExamplePackage::Modules;In module e.g. Modules.pm of a package e.g 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 e.g. a if statement or code block.
It is common practice to load modules using the use statement while compilation. Import of a subroutine imports of modules from e.g. 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 calling module.
It's a kind of magic when it is possible to change the source code while compiling as it can be shown here. The package defined module as well as the script of any user e.g. TestScript.pl creates a compiled file with the file extension .plc. This is in our case TestScript.plc.
Line numbers in error messages as well as warning messages are unaffected by this module. They will still point to the correct file names and line numbers.
METHOD
None
EXPORT
None
EXAMPLE
A TestScript.pl can look like
#!/usr/bin/perl
use ExamplePackage::Modules;
sub modfile {
my $filename = "testfile.txt";
my $old_text = read_file($filename);
my $new_text = modify_file($old_text);
my $retcode = write_file($filename, $new_text);
return $retcode;
};
my $return_code = modfile();will expand based on Modules.pm to
# Generated by ExamplePackage::Modules 0.01 (Module::Compile 0.38) - do not edit!
######################((( 32-bit Checksum Validator III )))######################
#line 1
BEGIN { use 5.006; local (*F, $/); ($F = __FILE__) =~ s!c$!!; open(F)
or die "Cannot open $F: $!"; binmode(F, ':crlf'); if (unpack('%32N*',
$F=readline(*F)) != 0x163B501C) { use Filter::Util::Call; my $f = $F;
filter_add(sub { filter_del(); 1 while &filter_read; $_ = $f; 1; })}}
#line 1
# 8667e12ea286715fb3e93c82b3356305890112f1
# 62f18508099e8285ab8f0df2ec70f446214f5586
#line 10 /usr/local/share/perl/5.30.0/ExamplePackage/Modules.pm
use ExamplePackage::Modules;
use strict;
use warnings;
use diagnostics;
use sigtrap;
use ExamplePackage::ReadFile;
use ExamplePackage::ModifyFile;
use ExamplePackage::WriteFile;
use re 'debug'
no utf8;
#line 14 TestScript.pl
sub modfile {
my $filename = "testfile.txt";
my $old_text = read_file($filename);
my $new_text = modify_file($old_text);
my $retcode = write_file($filename, $new_text);
return $retcode;
};
my $return_code = modfile();By using the method SanitiseCompiled from the module Simple::Filter::SanitiseCompiled the previous code can be cleaned up in a way that comments as well as the BEGIN block is removed. The remaining code is as compact as possible and runable.
PROGRAMMING BACKGROUND
A outer filter is applied. In the outer filter section, the content of the given module is modified in a way, that comments in general are removed and that the module terminator 1; is stripped. The content for the export is beginning after the use statement.
Then a inner filter is applied. In the inner filter section the module content is concatenated to the content of the given script. Both are written to the file with the head created applying the filtering procedure.
NOTES
Use
use Simple::Filter::MacroLite;for a prefiltered .plc file. Simple::Filter::MacroLite 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 like perl test_script.pl might create an error message on the second run. If the script is running using ./test_script.pl no error occurs. Nevertheless running perl test_script.plc seems to be 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
Simple::Filter::MacroLite
Simple::Filter::SanitiseCompiled
ACKNOWLEDGMENT
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.