1Merge(3) User Contributed Perl Documentation Merge(3)
2
6 Algorithm::Merge - Three-way merge and diff
7
9 use Algorithm::Merge qw(merge diff3 traverse_sequences3);
10 @merged = merge(\@ancestor, \@a, \@b, {
12 CONFLICT => sub { }
13 });
14 @merged = merge(\@ancestor, \@a, \@b, {
16 CONFLICT => sub { }
17 }, $key_generation_function);
18 $merged = merge(\@ancestor, \@a, \@b, {
20 CONFLICT => sub { }
21 });
22 $merged = merge(\@ancestor, \@a, \@b, {
24 CONFLICT => sub { }
25 }, $key_generation_function);
26 @diff = diff3(\@ancestor, \@a, \@b);
28 @diff = diff3(\@ancestor, \@a, \@b, $key_generation_function);
30 $diff = diff3(\@ancestor, \@a, \@b);
32 $diff = diff3(\@ancestor, \@a, \@b, $key_generation_function);
34 @trav = traverse_sequences3(\@ancestor, \@a, \@b, {
36 # callbacks
37 });
38 @trav = traverse_sequences3(\@ancestor, \@a, \@b, {
40 # callbacks
41 }, $key_generation_function);
42 $trav = traverse_sequences3(\@ancestor, \@a, \@b, {
44 # callbacks
45 });
46 $trav = traverse_sequences3(\@ancestor, \@a, \@b, {
48 # callbacks
49 }, $key_generation_function);
50
52 This module complements Algorithm::Diff by providing three-way merge
53 and diff functions.
54 In this documentation, the first list to "diff3", "merge", and
56 "traverse_sequences3" is called the `original' list. The second list
57 is the `left' list. The third list is the `right' list.
58 The optional key generation arguments are the same as in
60 Algorithm::Diff. See Algorithm::Diff for more information.
61 diff3
63 Given references to three lists of items, "diff3" performs a three-way
64 difference.
65 This function returns an array of operations describing how the left
67 and right lists differ from the original list. In scalar context, this
68 function returns a reference to such an array.
69 Perhaps an example would be useful.
71 Given the following three lists,
73 original: a b c e f h i k
75 left: a b d e f g i j k
76 right: a b c d e h i j k
77 merge: a b d e g i j k
79 we have the following result from diff3:
81 [ 'u', 'a', 'a', 'a' ],
83 [ 'u', 'b', 'b', 'b' ],
84 [ 'l', 'c', undef, 'c' ],
85 [ 'o', undef, 'd', 'd' ],
86 [ 'u', 'e', 'e', 'e' ],
87 [ 'r', 'f', 'f', undef ],
88 [ 'o', 'h', 'g', 'h' ],
89 [ 'u', 'i', 'i', 'i' ],
90 [ 'o', undef, 'j', 'j' ],
91 [ 'u', 'k', 'k', 'k' ]
92 The first element in each row is the array with the difference:
94 c - conflict (no two are the same)
96 l - left is different
97 o - original is different
98 r - right is different
99 u - unchanged
100 The next three elements are the lists from the original, left, and
102 right arrays respectively that the row refers to (in the synopsis,
103 these are @ancestor, @a, and @b, respectively).
104 merge
106 Given references to three lists of items, "merge" performs a three-way
107 merge. The "merge" function uses the "diff3" function to do most of
108 the work.
109 The only callback currently used is "CONFLICT" which should be a
111 reference to a subroutine that accepts two array references. The first
112 array reference is to a list of elements from the left list. The
113 second array reference is to a list of elements from the right list.
114 This callback should return a list of elements to place in the merged
115 list in place of the conflict.
116 The default "CONFLICT" callback returns the following:
118 q{<!-- ------ START CONFLICT ------ -->},
120 (@left),
121 q{<!-- ---------------------------- -->},
122 (@right),
123 q{<!-- ------ END CONFLICT ------ -->},
124 traverse_sequences3
126 This is the workhorse function that goes through the three sequences
127 and calls the callback functions.
128 The following callbacks are supported.
130 NO_CHANGE
132 This is called if all three sequences have the same element at the
133 current position. The arguments are the current positions within
134 each sequence, the first argument being the current position within
135 the first sequence.
136 A_DIFF
138 This is called if the first sequence is different than the other
139 two sequences at the current position. This callback will be
140 called with one, two, or three arguments.
141 If one argument, then only the element at the given position from
143 the first sequence is not in either of the other two sequences.
144 If two arguments, then there is no element in the first sequence
146 that corresponds to the elements at the given positions in the
147 second and third sequences.
148 If three arguments, then the element at the given position in the
150 first sequence is different than the corresponding element in the
151 other two sequences, but the other two sequences have corresponding
152 elements.
153 B_DIFF
155 This is called if the second sequence is different than the other
156 two sequences at the current position. This callback will be
157 called with one, two, or three arguments.
158 If one argument, then only the element at the given position from
160 the second sequence is not in either of the other two sequences.
161 If two arguments, then there is no element in the second sequence
163 that corresponds to the elements at the given positions in the
164 first and third sequences.
165 If three arguments, then the element at the given position in the
167 second sequence is different than the corresponding element in the
168 other two sequences, but the other two sequences have corresponding
169 elements.
170 C_DIFF
172 This is called if the third sequence is different than the other
173 two sequences at the current position. This callback will be
174 called with one, two, or three arguments.
175 If one argument, then only the element at the given position from
177 the third sequence is not in either of the other two sequences.
178 If two arguments, then there is no element in the third sequence
180 that corresponds to the elements at the given positions in the
181 first and second sequences.
182 If three arguments, then the element at the given position in the
184 third sequence is different than the corresponding element in the
185 other two sequences, but the other two sequences have corresponding
186 elements.
187 CONFLICT
189 This is called if all three sequences have different elements at
190 the current position. The three arguments are the current
191 positions within each sequence.
192
194 Most assuredly there are bugs. If a pattern similar to the above
195 example does not work, send it to <jsmith@cpan.org> or report it on
196 <http://rt.cpan.org/>, the CPAN bug tracker.
197 Algorithm::Diff's implementation of "traverse_sequences" may not be
199 symmetric with respect to the input sequences if the second and third
200 sequence are of different lengths. Because of this,
201 "traverse_sequences3" will calculate the diffs of the second and third
202 sequences as passed and swapped. If the differences are not the same,
203 it will issue an `Algorithm::Diff::diff is not symmetric for second and
204 third sequences...' warning. It will try to handle this, but there may
205 be some cases where it can't.
206
208 Algorithm::Diff.
209
211 James G. Smith, <jsmith@cpan.org>
212
214 Copyright (C) 2003, 2007 Texas A&M University. All Rights Reserved.
215 This module is free software; you may redistribute it and/or modify it
217 under the same terms as Perl itself.
218
220 Hey! The above document had some coding errors, which are explained
221 below:
222 Around line 680:
224 =back doesn't take any parameters, but you said =back 4
225perl v5.38.0 2023-07-20 Merge(3)