initial import of Template::Patch 0.01 from CPAN

git-cpan-module: Template::Patch
git-cpan-version: 0.01

Build.PL

@@ -0,0 +1,23 @@
+use strict;
+use warnings;
+use Module::Build;
+
+my $builder = Module::Build->new(
+    module_name         => 'Template::Patch',
+    license             => 'perl',
+    dist_author         => 'Gaal Yahas <[email protected]>',
+    dist_version_from   => 'lib/Template/Patch.pm',
+    build_requires => {
+        'Test::More' => 0,
+        'Test::Exception' => 0,
+    },
+    requires => {
+        'Template' => 0,
+        'Template::Extract' => 0,
+    },
+    script_files        => [ qw< bin/metapatch/ > ],
+    sign                => 1,
+    add_to_cleanup      => [ 'Template-Patch-*' ],
+);
+
+$builder->create_build_script();

Changes

@@ -0,0 +1,5 @@
+Revision history for Template-Patch
+
+0.01    2006-03-20
+        First version, released on an unsuspecting world.
+

MANIFEST.SKIP

@@ -0,0 +1,8 @@
+\.vim$
+\.cvsignore
+\.swp$
+^_build
+^blib
+^Build$
+Template-Patch-.*\.tar\.gz
+\.bak$

README

@@ -0,0 +1,42 @@
+Template-Patch
+
+Parameterized patch tool.
+
+Install like many CPAN modules. metapatch is the tool you should be looking at.
+
+INSTALLATION
+
+To install this module, run the following commands:
+
+    perl Build.PL
+    ./Build
+    ./Build test
+    ./Build install
+
+
+SUPPORT AND DOCUMENTATION
+
+After installing, you can find documentation for this module with the perldoc command.
+
+    perldoc Template::Patch
+
+You can also look for information at:
+
+    Search CPAN
+        http://search.cpan.org/dist/Template-Patch
+
+    CPAN Request Tracker:
+        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Patch
+
+    AnnoCPAN, annotated CPAN documentation:
+        http://annocpan.org/dist/Template-Patch
+
+    CPAN Ratings:
+        http://cpanratings.perl.org/d/Template-Patch
+
+COPYRIGHT AND LICENCE
+
+Copyright (C) 2006 Gaal Yahas
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.

bin/metapatch

@@ -0,0 +1,212 @@
+#!/usr/bin/perl -w
+
+use strict;
+use warnings;
+
+use Getopt::Long;
+
+use Template::Patch;
+
+GetOptions \our %Conf, qw(patch|p=s);
+
+my $p = Template::Patch->new_from_file($Conf{patch});
+
+my $input = slurp_in();
+$p->extract($input);
+$p->patch;
+
+$p->print;
+
+exit 0;
+
+sub slurp_in { local $/; <> }
+
+# vim: ts=4 et :
+
+__END__
+
+=head1 NAME
+
+metapatch - Apply parameterized patches
+
+=head1 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;
+
+=head1 DESCRIPTION
+
+C<diff> and C<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 C<info>
+calls to C<debug>. You don't want to blindly C<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 C<info("init called");> to use
+C<trace>, because the text of the log message isn't identical. You I<could>
+write a simple parser that looks for the first log message after an C<init>
+call, but that's coding; and you I<could> do this with a regexp, but that's
+not very nice to maintain.
+
+C<Template::Patch> lets you write I<metapatches> describing your intended
+change. It uses L<Template::Toolkit> and L<Template::Extract> to describe
+what an interesting change would be. Because the input is first processed
+with L<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 %]
+
+=head1 METAPATCH FORMAT
+
+A I<metapatch file> (typically with the extension C<.mp>) has three
+sections.  Two separators (of twenty C<< < >>s and twenty C<< > >>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 C<< < >> separator) contains
+a TT2 template of expected text in the input file. It is fed to
+L<Template::Extract>, and variables extracted are kept around.
+
+The third ("OUT") section (after the C<< > >> 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.
+
+=head2 Configuration
+
+Configuration directives are optional. If they appear, they must be in
+C<key : value> format, one per line. Blanks and lines starting with C<#>
+are ignored.
+
+By default, the metapatch is not anchored. This means that implicitly,
+it is surrounded by C<[% pre %] ... [% post %]> variables, which are
+then emitted as-is in the output.
+
+To force your template to the beginning of the text, set the
+C<anchor-start> configuration parameter.
+
+To force your template to the end of the text, set the C<anchor-end>
+configuration parameter.
+
+=head1 TODO
+
+All these need more design.
+
+=over 4
+
+=item * Repeat matches in IN
+
+=item * Can several unrelated and order-indifferent chunks of mp live together in one file?
+
+=item * The metapatch format is silly
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Template::Patch>
+
+=item * L<Template::Toolkit>
+
+=item * L<Template::Extract>
+
+=back
+
+=head1 AUTHOR
+
+Gaal Yahas, C<< <gaal at forum2.org> >>
+
+=head1 CAVEATS
+
+This tool and the included L<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.
+
+=head1 BUGS
+
+Please report any bugs or feature requests to
+C<bug-template-patch at rt.cpan.org>, or through the web interface at
+L<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.
+
+=head1 SUPPORT
+
+You can find documentation for this module with the perldoc command.
+
+    perldoc Template::Patch
+
+You can also look for information at:
+
+=over 4
+
+=item * AnnoCPAN: Annotated CPAN documentation
+
+L<http://annocpan.org/dist/Template-Patch>
+
+=item * CPAN Ratings
+
+L<http://cpanratings.perl.org/d/Template-Patch>
+
+=item * RT: CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Patch>
+
+=item * Search CPAN
+
+L<http://search.cpan.org/dist/Template-Patch>
+
+=back
+
+=head1 ACKNOWLEDGEMENTS
+
+Thanks to Audrey Tang for sausage machine (and general) havoc.
+
+=head1 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.
+
+=cut
+
+1; # End of Template::Patch