metapatch - Apply parameterized patches
$ metapatch --patch mychanges.mp < oldfile > newfile # or, programmatically: use Template::Patch; my $tp = Template::Patch->parse_patch_file($metapatch_file); $tp->extract($source); $tp->patch; $tp->print;
diff and patch are fine tools for applying changes to files. But sometimes you need to apply a change that cannot be expressed with one diff, for example, you have some parts that differ among files but which you wish to preserve:
diff
patch
# file1 sub init { info "init called"; # ... # file2 sub init { info "init called (and oh, this is file2)"; # ...
Suppose you want to go over all your init functions, and change the info calls to debug. You don't want to blindly perl -pi -e 's/info/trace/' because you may have legitimate info prints elsewhere in the files that you wish to leave alone. You can't blindly patch info("init called"); to use trace, because the text of the log message isn't identical. You could write a simple parser that looks for the first log message after an init call, but that's coding; and you could do this with a regexp, but that's not very nice to maintain.
info
debug
perl -pi -e 's/info/trace/'
info("init called");
trace
init
Template::Patch lets you write metapatches describing your intended change. It uses Template::Toolkit and Template::Extract to describe what an interesting change would be. Because the input is first processed with Template::Extract, you can access a dictionary of extracted values by name when describing your output. This can improve readability of your patch by giving names to data you rearrange or just pass through. It can also be used for fancy templating stuff like repeating an interesting line from the input several times in the output.
Template::Patch
The metapatch for performing the change described above is:
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< sub init { info [% message %] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> sub init { debug [% message %]
A metapatch file (typically with the extension .mp) has three sections. Two separators (of twenty <s and twenty >s in turn) keep them apart. (The separator lines may have more than twenty characters, everything after the first 20 is ignored until the line end.) XXX: this is stupid. If you have a better idea, please let me know.
.mp
<
>
The first section (which may be empty) contains metapatch configuration directives. See the Configuration section for details.
The second ("IN") section (after the < separator) contains a TT2 template of expected text in the input file. It is fed to Template::Extract, and variables extracted are kept around.
The third ("OUT") section (after the > separator) contains a TT2 template of replacement text that goes in the output. Any TT2 directives are allowed. In particular, you may use variables extracted in the "IN" section.
Configuration directives are optional. If they appear, they must be in key : value format, one per line. Blanks and lines starting with # are ignored.
key : value
#
By default, the metapatch is not anchored. This means that implicitly, it is surrounded by [% pre %] ... [% post %] variables, which are then emitted as-is in the output.
[% pre %] ... [% post %]
To force your template to the beginning of the text, set the anchor-start configuration parameter.
anchor-start
To force your template to the end of the text, set the anchor-end configuration parameter.
anchor-end
All these need more design.
Repeat matches in IN
Can several unrelated and order-indifferent chunks of mp live together in one file?
The metapatch format is silly
Template::Toolkit
Template::Extract
Gaal Yahas, <gaal at forum2.org>
<gaal at forum2.org>
This tool and the included Template::Patch module are in early stages of gathering ideas and coming up with a good interface. They work (and have saved me time), but expect change in the interfaces.
Please report any bugs or feature requests to bug-template-patch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Patch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-template-patch at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Template::Patch
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Template-Patch
CPAN Ratings
http://cpanratings.perl.org/d/Template-Patch
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Patch
Search CPAN
http://search.cpan.org/dist/Template-Patch
Thanks to Audrey Tang for sausage machine (and general) havoc.
Copyright 2006 Gaal Yahas, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Template::Patch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template::Patch
CPAN shell
perl -MCPAN -e shell install Template::Patch
For more information on module installation, please visit the detailed CPAN module installation guide.