view release on metacpan or  search on metacpan

lib/Algorithm/Diff/Apply.pod  view on Meta::CPAN

=head1 NAME

Algorithm::Diff::Apply -- apply one or more Algorithm::Diff diffs

=head1 SYNOPSIS

	## Single-diff form:
	use Algorithm::Diff::Apply qw{apply_diff};
	my @ary = ...;
	my @diff = ...;   # some call to Algorithm::Diff::diff()

	my @changed_ary = apply_diff(\@ary, \@diff);
	my $changed_ary = apply_diff(\@ary, \@diff);

	
	## To apply >1 diff at once, use the plural form:
	use Algorithm::Diff::Apply qw{apply_diffs};

        @newary = apply_diffs(\@ary,
                              diff1_name => \@diff1,
                              diff2_name => \@diff2,
	                      ...
                              diffN_name => \@diffN);

        # Alternatively:
        @newary = apply_diffs(\@ary, %named_diffs);

        # Scalar context:
        $newary = apply_diffs(\@ary, %named_diffs);

        # Extension argument syntax:
        $newary = apply_diffs(\@ary, {
                                  resolver => \&some_sub,
	                          optimisers => [\&foo, \&bar],
                                  key_generator => \&anothersub,
	                          opt4 => ...,
	                          opt5 => ...,
                              }, %named_diffs);

=head1 DESCRIPTION

    At worst, the user is made to feel superior to the computer.
      -- R. E. Mullen [1]

This module contains subroutines for applying diffs generated by
C<Algorithm::Diff> to a target array in the hope of regenerating a new
array incorporating all the changes described in the diffs into a new
merged array.

If two hunks from different diffs happen to affect the same line,
conflicts are detected and can be optionally handed off to helper
subroutines for resolution.

=over 4

=item apply_diff ARRAY,DIFF

Applies the changes described by a diff to a copy of I<ARRAY>, which
is then returned. I<DIFF> is a diff generated by
C<Algorithm::Diff::diff()>, and I<ARRAY> must be an array of an
appropriate length. Both parameters are passed in as references.
Neither argument is modified.

In a scalar context, C<apply_diff()> returns a reference to the
permuted copy that's generated. In an array context, the permuted copy
is returned as an array value.

This version of the algorithm is simpler and quicker than the
full-blown plural form, and should be used if you're only ever going
to be applying one diff at once.

=item apply_diffs ARRAY,HASH

=item apply_diffs ARRAY,OPTIONS,HASH

Applies more than one diff to a copy of an array at once, manages
conflicts, and returns the permuted copy as either a reference or an
array depending on context.

I<ARRAY> must be a reference to an array value of an appropriate
length. The array behind the passed reference is not permuted.

The I<HASH> parameter contains diffs from different sources, as
generated by C<Algorithm::Diff::diff()>. The diffs are keyed by
arbitrary strings which should reflect their source.
See L<DIFF LABELS> for details of what these strings might reflect.

I<OPTIONS>, if specified, must be a hash reference of option keywords
and the corresponding parameters. The following options are
recognised:

=over 8

=item Option "optimisers" (a.k.a. "optimizers")

Reference to an array of conflict optimiser subroutines. Normally
C<apply_diffs()> performs all the optimisations documented in this
module; this option can be used to change that. Pass in an empty array
to turn off optimisations altogether. See L<Conflict Optimiser
Callbacks> for details of how these subs are called.

=item Option "resolver"

This option can be used to supply a subroutine which will be called
when a conflict is detected. See L<Conflict Resolver Callbacks>
details of how resolver routines are called.

=item Option "key_generator"

If the elements in the target arrays and all the diffs cannot be
meaningfully compared with plain "C<eq>" - e.g. reference types - then
a hashing function can be supplied using this option. See C<Key
Generation Callbacks> below for details.

=back

=item mark_conflicts HASH

This is the default resolver callback; see L<Conflict Optimiser
Callbacks> for details of its interface. It causes C<apply_diffs()> to
return arrays looking a bit like:

   [ @part_before_conflict,
     ">>>>>> diff1_name\n",
     @lines_1,              # Lines permuted by diff1 (only)
     ">>>>>> diff2_name\n"
     @lines_2,              # The same lines, as permuted by diff2
     "<<<<<<\n",
     @part_after_conflict,
   ]

Which is probably the right thing to do if your array is going to be
printed out one item per line.

=item optimise_remove_duplicates HASH

Conflict optimiser: detects identical diff hunks in the conflict
block, and removes all but one of each duplicated hunk.

=back