/ 
Algorithm-Merge-0.00_01
River stage one • 3 direct dependents • 4 total dependents
/ Algorithm::Merge

NAME

Algorithm::Merge - Three-way merge and diff

SYNOPSIS

use Algorithm::Merge qw(merge diff3);

@merged = merge(\@ancestor, \@a, \@b);

@merged = merge(\@ancestor, \@a, \@b, $key_generation_function);

$merged = merge(\@ancestor, \@a, \@b);

$merged = merge(\@ancestor, \@a, \@b, $key_generation_function);

@diff   = diff3(\@ancestor, \@a, \@b);

@diff   = diff3(\@ancestor, \@a, \@b, $key_generation_function);

$diff   = diff3(\@ancestor, \@a, \@b);

$diff   = diff3(\@ancestor, \@a, \@b, $key_generation_function);

USAGE

This module complements Algorithm::Diff by providing three-way merge and diff functions.

In this documentation, the first list to diff3 and merge is called the `original' list. The second list is the `left' list. The third list is the `right' list.

The optional key generation arguments are the same as in Algorithm::Diff. See Algorithm::Diff for more information.

diff3

Given references to three lists of items, diff3 performs a three-way difference.

This function returns an array of operations describing how the left and right lists differ from the original list. In scalar context, this function returns a reference to such an array.

Perhaps an example would be useful.

Given the following three lists,

original: a b c   e f   h i   k
    left: a b   d e f g   i j k
   right: a b c d e     h i j k

   merge: a b   d e   g   i j k

we have the following result from diff3:

[ 'u', 'a',   'a',   'a' ],
[ 'u', 'b',   'b',   'b' ],
[ 'l', 'c',   undef, 'c' ],
[ 'o', undef, 'd',   'd' ],
[ 'u', 'e',   'e',   'e' ],
[ 'r', 'f',   'f',   undef ], 
[ 'o', 'h',   'g',   'h' ],
[ 'u', 'i',   'i',   'i' ],
[ 'o', undef, 'j',   'j' ],
[ 'u', 'k',   'k',   'k' ]

The first element in each row is the array with the difference:

c - conflict (no two are the same)
l - left is different 
o - original is different
r - right is different
u - unchanged

The next three elements are the lists from the original, left, and right arrays respectively that the row refers to (in the synopsis, these are @ancestor, @a, and @b, respectively).

merge

Given references to three lists of items, merge performs a three-way merge. The merge function uses the diff3 function to do most of the work.

The only callback currently used is CONFLICT which should be a reference to a subroutine that accepts two array references. The first array reference is to a list of elements from the left list. The second array reference is to a list of elements from the right list. This callback should return a list of elements to place in the merged list in place of the conflict.

The default CONFLICT callback returns the following:

q{<!-- ------ START CONFLICT ------ -->},
(@left),
q{<!-- ---------------------------- -->},
(@right),
q{<!-- ------  END  CONFLICT ------ -->},

BUGS

Most assuredly there are bugs. If a pattern similar to the above example does not work, send it to <jsmith@cpan.org> or report it on <http://rt.cpan.org/>, the CPAN bug tracker.

SEE ALSO

Algorithm::Diff.

AUTHOR

James G. Smith, <jsmith@cpan.org>

COPYRIGHT

Copyright (C) 2003 Texas A&M University. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.