/ 
Template-Patch-0.03
River stage zero No dependents
++
 / metapatch

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

    # 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.

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:

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.