.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Merge 3"
.TH Merge 3 "2007-03-21" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Algorithm::Merge \- Three\-way merge and diff
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Algorithm::Merge qw(merge diff3 traverse_sequences3);
\&
\& @merged = merge(\e@ancestor, \e@a, \e@b, {
\& CONFLICT => sub { }
\& });
\&
\& @merged = merge(\e@ancestor, \e@a, \e@b, {
\& CONFLICT => sub { }
\& }, $key_generation_function);
\&
\& $merged = merge(\e@ancestor, \e@a, \e@b, {
\& CONFLICT => sub { }
\& });
\&
\& $merged = merge(\e@ancestor, \e@a, \e@b, {
\& CONFLICT => sub { }
\& }, $key_generation_function);
\&
\& @diff = diff3(\e@ancestor, \e@a, \e@b);
\&
\& @diff = diff3(\e@ancestor, \e@a, \e@b, $key_generation_function);
\&
\& $diff = diff3(\e@ancestor, \e@a, \e@b);
\&
\& $diff = diff3(\e@ancestor, \e@a, \e@b, $key_generation_function);
\&
\& @trav = traverse_sequences3(\e@ancestor, \e@a, \e@b, {
\& # callbacks
\& });
\&
\& @trav = traverse_sequences3(\e@ancestor, \e@a, \e@b, {
\& # callbacks
\& }, $key_generation_function);
\&
\& $trav = traverse_sequences3(\e@ancestor, \e@a, \e@b, {
\& # callbacks
\& });
\&
\& $trav = traverse_sequences3(\e@ancestor, \e@a, \e@b, {
\& # callbacks
\& }, $key_generation_function);
.Ve
.SH "USAGE"
.IX Header "USAGE"
This module complements Algorithm::Diff by
providing three-way merge and diff functions.
.PP
In this documentation, the first list to \f(CW\*(C`diff3\*(C'\fR, \f(CW\*(C`merge\*(C'\fR, and
\&\f(CW\*(C`traverse_sequences3\*(C'\fR is
called the `original' list. The second list is the `left' list. The
third list is the `right' list.
.PP
The optional key generation arguments are the same as in
Algorithm::Diff. See Algorithm::Diff for more
information.
.SS "diff3"
.IX Subsection "diff3"
Given references to three lists of items, \f(CW\*(C`diff3\*(C'\fR performs a
three-way difference.
.PP
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.
.PP
Perhaps an example would be useful.
.PP
Given the following three lists,
.PP
.Vb 3
\& 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
.Ve
.PP
we have the following result from diff3:
.PP
.Vb 10
\& [ \*(Aqu\*(Aq, \*(Aqa\*(Aq, \*(Aqa\*(Aq, \*(Aqa\*(Aq ],
\& [ \*(Aqu\*(Aq, \*(Aqb\*(Aq, \*(Aqb\*(Aq, \*(Aqb\*(Aq ],
\& [ \*(Aql\*(Aq, \*(Aqc\*(Aq, undef, \*(Aqc\*(Aq ],
\& [ \*(Aqo\*(Aq, undef, \*(Aqd\*(Aq, \*(Aqd\*(Aq ],
\& [ \*(Aqu\*(Aq, \*(Aqe\*(Aq, \*(Aqe\*(Aq, \*(Aqe\*(Aq ],
\& [ \*(Aqr\*(Aq, \*(Aqf\*(Aq, \*(Aqf\*(Aq, undef ],
\& [ \*(Aqo\*(Aq, \*(Aqh\*(Aq, \*(Aqg\*(Aq, \*(Aqh\*(Aq ],
\& [ \*(Aqu\*(Aq, \*(Aqi\*(Aq, \*(Aqi\*(Aq, \*(Aqi\*(Aq ],
\& [ \*(Aqo\*(Aq, undef, \*(Aqj\*(Aq, \*(Aqj\*(Aq ],
\& [ \*(Aqu\*(Aq, \*(Aqk\*(Aq, \*(Aqk\*(Aq, \*(Aqk\*(Aq ]
.Ve
.PP
The first element in each row is the array with the difference:
.PP
.Vb 5
\& c \- conflict (no two are the same)
\& l \- left is different
\& o \- original is different
\& r \- right is different
\& u \- unchanged
.Ve
.PP
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 \f(CW@ancestor\fR, \f(CW@a\fR, and \f(CW@b\fR, respectively).
.SS "merge"
.IX Subsection "merge"
Given references to three lists of items, \f(CW\*(C`merge\*(C'\fR performs a three-way
merge. The \f(CW\*(C`merge\*(C'\fR function uses the \f(CW\*(C`diff3\*(C'\fR function to do most of
the work.
.PP
The only callback currently used is \f(CW\*(C`CONFLICT\*(C'\fR 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.
.PP
The default \f(CW\*(C`CONFLICT\*(C'\fR callback returns the following:
.PP
.Vb 5
\& q{<!\-\- \-\-\-\-\-\- START CONFLICT \-\-\-\-\-\- \-\->},
\& (@left),
\& q{<!\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\->},
\& (@right),
\& q{<!\-\- \-\-\-\-\-\- END CONFLICT \-\-\-\-\-\- \-\->},
.Ve
.SS "traverse_sequences3"
.IX Subsection "traverse_sequences3"
This is the workhorse function that goes through the three sequences
and calls the callback functions.
.PP
The following callbacks are supported.
.IP "\s-1NO_CHANGE\s0" 4
.IX Item "NO_CHANGE"
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.
.IP "A_DIFF" 4
.IX Item "A_DIFF"
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.
.Sp
If one argument, then only the element at the given position from the
first sequence is not in either of the other two sequences.
.Sp
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.
.Sp
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.
.IP "B_DIFF" 4
.IX Item "B_DIFF"
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.
.Sp
If one argument, then only the element at the given position from the
second sequence is not in either of the other two sequences.
.Sp
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.
.Sp
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.
.IP "C_DIFF" 4
.IX Item "C_DIFF"
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.
.Sp
If one argument, then only the element at the given position from the
third sequence is not in either of the other two sequences.
.Sp
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.
.Sp
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.
.IP "\s-1CONFLICT\s0" 4
.IX Item "CONFLICT"
This is called if all three sequences have different elements at the
current position. The three arguments are the current positions within
each sequence.
.SH "BUGS"
.IX Header "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 \s-1CPAN\s0 bug tracker.
.PP
Algorithm::Diff's implementation of
\&\f(CW\*(C`traverse_sequences\*(C'\fR may not be symmetric with respect to the input
sequences if the second and third sequence are of different lengths.
Because of this, \f(CW\*(C`traverse_sequences3\*(C'\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Algorithm::Diff.
.SH "AUTHOR"
.IX Header "AUTHOR"
James G. Smith, <jsmith@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2003, 2007 Texas A&M University. All Rights Reserved.
.PP
This module is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 680:" 4
.IX Item "Around line 680:"
=back doesn't take any parameters, but you said =back 4