375 lines
9.1 KiB
HTML
375 lines
9.1 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Merge</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Merge</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2015-11-21<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Algorithm::Merge - Three-way merge and diff
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use Algorithm::Merge qw(merge diff3 traverse_sequences3);
|
|
|
|
@merged = merge(\@ancestor, \@a, \@b, {
|
|
CONFLICT => sub { }
|
|
});
|
|
|
|
@merged = merge(\@ancestor, \@a, \@b, {
|
|
CONFLICT => sub { }
|
|
}, $key_generation_function);
|
|
|
|
$merged = merge(\@ancestor, \@a, \@b, {
|
|
CONFLICT => sub { }
|
|
});
|
|
|
|
$merged = merge(\@ancestor, \@a, \@b, {
|
|
CONFLICT => sub { }
|
|
}, $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);
|
|
|
|
@trav = traverse_sequences3(\@ancestor, \@a, \@b, {
|
|
# callbacks
|
|
});
|
|
|
|
@trav = traverse_sequences3(\@ancestor, \@a, \@b, {
|
|
# callbacks
|
|
}, $key_generation_function);
|
|
|
|
$trav = traverse_sequences3(\@ancestor, \@a, \@b, {
|
|
# callbacks
|
|
});
|
|
|
|
$trav = traverse_sequences3(\@ancestor, \@a, \@b, {
|
|
# callbacks
|
|
}, $key_generation_function);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>USAGE</H2>
|
|
|
|
|
|
|
|
This module complements Algorithm::Diff by
|
|
providing three-way merge and diff functions.
|
|
<P>
|
|
|
|
In this documentation, the first list to <TT>"diff3"</TT>, <TT>"merge"</TT>, and
|
|
<TT>"traverse_sequences3"</TT> is
|
|
called the `original' list. The second list is the `left' list. The
|
|
third list is the `right' list.
|
|
<P>
|
|
|
|
The optional key generation arguments are the same as in
|
|
Algorithm::Diff. See Algorithm::Diff for more
|
|
information.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>diff3</H3>
|
|
|
|
|
|
|
|
Given references to three lists of items, <TT>"diff3"</TT> performs a
|
|
three-way difference.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Perhaps an example would be useful.
|
|
<P>
|
|
|
|
Given the following three lists,
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
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
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
we have the following result from diff3:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
[ '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' ]
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The first element in each row is the array with the difference:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
c - conflict (no two are the same)
|
|
l - left is different
|
|
o - original is different
|
|
r - right is different
|
|
u - unchanged
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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 <TT>@ancestor</TT>, <TT>@a</TT>, and <TT>@b</TT>, respectively).
|
|
<A NAME="lbAF"> </A>
|
|
<H3>merge</H3>
|
|
|
|
|
|
|
|
Given references to three lists of items, <TT>"merge"</TT> performs a three-way
|
|
merge. The <TT>"merge"</TT> function uses the <TT>"diff3"</TT> function to do most of
|
|
the work.
|
|
<P>
|
|
|
|
The only callback currently used is <TT>"CONFLICT"</TT> 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.
|
|
<P>
|
|
|
|
The default <TT>"CONFLICT"</TT> callback returns the following:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
q{<!-- ------ START CONFLICT ------ -->},
|
|
(@left),
|
|
q{<!-- ---------------------------- -->},
|
|
(@right),
|
|
q{<!-- ------ END CONFLICT ------ -->},
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>traverse_sequences3</H3>
|
|
|
|
|
|
|
|
This is the workhorse function that goes through the three sequences
|
|
and calls the callback functions.
|
|
<P>
|
|
|
|
The following callbacks are supported.
|
|
<DL COMPACT>
|
|
<DT id="1"><FONT SIZE="-1">NO_CHANGE</FONT><DD>
|
|
|
|
|
|
This is called if all three sequences have the same element at the
|
|
current position. The arguments are the current positions within each
|
|
sequence, the first argument being the current position within the
|
|
first sequence.
|
|
<DT id="2">A_DIFF<DD>
|
|
|
|
|
|
This is called if the first sequence is different than the other two
|
|
sequences at the current position.
|
|
This callback will be called with one, two, or three arguments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If one argument, then only the element at the given position from the
|
|
first sequence is not in either of the other two sequences.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If two arguments, then there is no element in the first sequence that
|
|
corresponds to the elements at the given positions in the second and
|
|
third sequences.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If three arguments, then the element at the given position in the first
|
|
sequence is different than the corresponding element in the other two
|
|
sequences, but the other two sequences have corresponding elements.
|
|
<DT id="3">B_DIFF<DD>
|
|
|
|
|
|
This is called if the second sequence is different than the other two
|
|
sequences at the current position.
|
|
This callback will be called with one, two, or three arguments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If one argument, then only the element at the given position from the
|
|
second sequence is not in either of the other two sequences.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If two arguments, then there is no element in the second sequence that
|
|
corresponds to the elements at the given positions in the first and
|
|
third sequences.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If three arguments, then the element at the given position in the second
|
|
sequence is different than the corresponding element in the other two
|
|
sequences, but the other two sequences have corresponding elements.
|
|
<DT id="4">C_DIFF<DD>
|
|
|
|
|
|
This is called if the third sequence is different than the other two
|
|
sequences at the current position.
|
|
This callback will be called with one, two, or three arguments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If one argument, then only the element at the given position from the
|
|
third sequence is not in either of the other two sequences.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If two arguments, then there is no element in the third sequence that
|
|
corresponds to the elements at the given positions in the first and
|
|
second sequences.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If three arguments, then the element at the given position in the third
|
|
sequence is different than the corresponding element in the other two
|
|
sequences, but the other two sequences have corresponding elements.
|
|
<DT id="5"><FONT SIZE="-1">CONFLICT</FONT><DD>
|
|
|
|
|
|
This is called if all three sequences have different elements at the
|
|
current position. The three arguments are the current positions within
|
|
each sequence.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
Most assuredly there are bugs. If a pattern similar to the above
|
|
example does not work, send it to <<A HREF="mailto:jsmith@cpan.org">jsmith@cpan.org</A>> or report it on
|
|
<<A HREF="http://rt.cpan.org/">http://rt.cpan.org/</A>>, the <FONT SIZE="-1">CPAN</FONT> bug tracker.
|
|
<P>
|
|
|
|
Algorithm::Diff's implementation of
|
|
<TT>"traverse_sequences"</TT> may not be symmetric with respect to the input
|
|
sequences if the second and third sequence are of different lengths.
|
|
Because of this, <TT>"traverse_sequences3"</TT> will calculate the diffs of
|
|
the second and third sequences as passed and swapped. If the differences
|
|
are not the same, it will issue an `Algorithm::Diff::diff is not symmetric
|
|
for second and third sequences...' warning. It will try to handle
|
|
this, but there may be some cases where it can't.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
Algorithm::Diff.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
James G. Smith, <<A HREF="mailto:jsmith@cpan.org">jsmith@cpan.org</A>>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright (C) 2003, 2007 Texas A&M University. All Rights Reserved.
|
|
<P>
|
|
|
|
This module is free software; you may redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="6"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="7"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="8"><A HREF="#lbAD">USAGE</A><DD>
|
|
<DL>
|
|
<DT id="9"><A HREF="#lbAE">diff3</A><DD>
|
|
<DT id="10"><A HREF="#lbAF">merge</A><DD>
|
|
<DT id="11"><A HREF="#lbAG">traverse_sequences3</A><DD>
|
|
</DL>
|
|
<DT id="12"><A HREF="#lbAH">BUGS</A><DD>
|
|
<DT id="13"><A HREF="#lbAI">SEE ALSO</A><DD>
|
|
<DT id="14"><A HREF="#lbAJ">AUTHOR</A><DD>
|
|
<DT id="15"><A HREF="#lbAK">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:35 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|