Algorithm-Diff-Apply

 view release on metacpan or  search on metacpan

ChangeLog  view on Meta::CPAN

0.2.3	2004-11-03

	* Corrected bug with one-line conflicts, new test cases.
	* Thanks to Douglas E. Miles <perlguy-x@eart-y-hlink.net.z> for
	  reporting this and supplying a patch.

0.2.2	2003-07-08

	* Added support for non-string data items via hashing callbacks.
	* Documentation updates.

0.2.1	2003-06-26

	* Added simple conflict "optimiser".
	* Updated docs.
	* Corrected synopsis, which was still using an old name.

0.1.1	2003-05-21

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

				    ? $opt{key_generator}->($data)
				    : undef);
			push @{$hhunk->{changes}}, [$op, $data, $hash];
		}
		push @hdiff, $hhunk;
	}
	return \@hdiff;
}


# Calls the specified optimisation callbacks, returning a list of discrete
# alternative blocks in a format that __apply_alternatives() can handle.

sub __optimise_conflicts
{
	my %args = @_;
	my %diffset = %{$args{diffset} || confess "\"diffset\" not specified"};
	my %opt = %{$args{opts} || confess "\"opts\" not specified"};

	my @optim;
	if ($opt{optimisers} or $opt{optimizers})

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

=head1 CALLBACK INTERFACES

A lot of the dirty work in C<apply_diffs()> is done by callback
subroutines, and users of C<Algorithm::Diff::Apply> can override its
default behaviour if they wish by passing appropriate options to
C<apply_diffs()> (see above).

=head2 Conflict Optimiser Callbacks

Optimiser callbacks are a way of making conflict cases easier for
humans to deal with. This can be done by combining diff hunks from
different sources that do the same thing, factoring out common
changes, and other devious bits of monkeywork. Doing this can even
factor away a conflict situation entirely.

These callbacks are called by C<apply_diffs()> when it detects a group
of hunks from different diff sequences that can't all be applied at
once without conflicting with each other.

For each block of conflicting diffs, the callback will be called with
every diff in the block in the following format:

    @ret = optimiser_callback (
          "conflict_block" => {
               "name_1" => [$hunk_1_1, $hunk_1_2, ..., $hunk_1_N],
               "name_2" => [$hunk_2_1, $hunk_2_2, ..., $hunk_2_N],

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

    {
        "start"   => N,
        "changes" => [[OP1, DATA1], ..., [OPn, DATAn]],
    }

Where "start" is a line number in the I<target> array, indicating
where this hunk is intended to be applied, and "changes" contains the
changes to apply.

Optimiser callbacks should return a I<permuted copy> of what they were
passed. Empty diffs will be discarded automatically. If only one diff
remains after processing, the conflict will have been optimised away
completely.

=head2 Conflict Resolver Callbacks

Resolver callbacks are invoked when conflicts have been detected, and
the optimisers weren't able to completely factor away the conflict
block.

The job of a resolver callback is to return some kind of resolution of
the conflicting sub-arrays. These subs are called a little like this:

     @ret = resolver_callback (
	   "alt_txts" => {
                "diff1_name" => ['m', 'n', 'o'],
	        "diff3_name" => [],

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

the "eq" operator by default. This is meaningless for many Perl
variables; for example object references stringify to a form that
doesn't capture the internals of the object, e.g.
"SomeClass=HASH(0x813aa8c)".

This also applies to plain ARRAY, HASH, SCALAR references, or other
types of ref. Ideally we'd like the internal state of any such object
pointed at by a scalar variable to be represented in a form that can
be compared against other varibales of the same type.

This is where key generation callbacks come in. A C<key_generator>
subroutine is a hashing routine; it takes as argument a scalar
variable, and returns a string that can be compared against other
strings returned by other calls to the key_generator. The return
values are cached inside a call to C<apply_diffs()> for efficiency.

The key generators used by C<Algorithm::Diff::Apply> have the same
semantics as the ones used by C<Algorithm::Diff>. See
L<Algorithm::Diff/KEY GENERATION FUNCTIONS>.

When you're dealing with objects, a simple wrapper around one of the