-
-
19 Jan 2009 19:11:56 UTC
- Distribution: Template-Patch
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (0)
- Testers (562 / 0 / 0)
- Kwalitee
Bus factor: 0- 80.85% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (7.21KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Template
- Template::Extract
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- METAPATCH FORMAT
- TODO
- SEE ALSO
- AUTHOR
- CAVEATS
- BUGS
- SUPPORT
- ACKNOWLEDGEMENTS
- COPYRIGHT & LICENSE
NAME
metapatch - Apply parameterized patches
SYNOPSIS
$ 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;
DESCRIPTION
diff
andpatch
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:# 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 todebug
. You don't want to blindlyperl -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 patchinfo("init called");
to usetrace
, because the text of the log message isn't identical. You could write a simple parser that looks for the first log message after aninit
call, but that's coding; and you could do this with a regexp, but that's not very nice to maintain.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.The metapatch for performing the change described above is:
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< sub init { info [% message %] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> sub init { debug [% message %]
METAPATCH FORMAT
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.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
Configuration directives are optional. If they appear, they must be in
key : value
format, one per line. Blanks and lines starting with#
are ignored.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.To force your template to the beginning of the text, set the
anchor-start
configuration parameter.To force your template to the end of the text, set the
anchor-end
configuration parameter.TODO
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
SEE ALSO
AUTHOR
Gaal Yahas,
<gaal at forum2.org>
CAVEATS
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.
BUGS
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.SUPPORT
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
CPAN Ratings
RT: CPAN's request tracker
Search CPAN
ACKNOWLEDGEMENTS
Thanks to Audrey Tang for sausage machine (and general) havoc.
COPYRIGHT & LICENSE
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.
Module Install Instructions
To install Template::Patch, copy and paste the appropriate command in to your terminal.
cpanm Template::Patch
perl -MCPAN -e shell install Template::Patch
For more information on module installation, please visit the detailed CPAN module installation guide.