1Merge(3)              User Contributed Perl Documentation             Merge(3)
2
3
4

NAME

6       Algorithm::Merge - Three-way merge and diff
7

SYNOPSIS

9        use Algorithm::Merge qw(merge diff3 traverse_sequences3);
10
11        @merged = merge(\@ancestor, \@a, \@b, {
12                      CONFLICT => sub { }
13                  });
14
15        @merged = merge(\@ancestor, \@a, \@b, {
16                      CONFLICT => sub { }
17                  }, $key_generation_function);
18
19        $merged = merge(\@ancestor, \@a, \@b, {
20                      CONFLICT => sub { }
21                  });
22
23        $merged = merge(\@ancestor, \@a, \@b, {
24                      CONFLICT => sub { }
25                  }, $key_generation_function);
26
27        @diff   = diff3(\@ancestor, \@a, \@b);
28
29        @diff   = diff3(\@ancestor, \@a, \@b, $key_generation_function);
30
31        $diff   = diff3(\@ancestor, \@a, \@b);
32
33        $diff   = diff3(\@ancestor, \@a, \@b, $key_generation_function);
34
35        @trav   = traverse_sequences3(\@ancestor, \@a, \@b, {
36                      # callbacks
37                  });
38
39        @trav   = traverse_sequences3(\@ancestor, \@a, \@b, {
40                      # callbacks
41                  }, $key_generation_function);
42
43        $trav   = traverse_sequences3(\@ancestor, \@a, \@b, {
44                      # callbacks
45                  });
46
47        $trav   = traverse_sequences3(\@ancestor, \@a, \@b, {
48                      # callbacks
49                  }, $key_generation_function);
50

USAGE

52       This module complements Algorithm::Diff by providing three-way merge
53       and diff functions.
54
55       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
59       The optional key generation arguments are the same as in
60       Algorithm::Diff.  See Algorithm::Diff for more information.
61
62   diff3
63       Given references to three lists of items, "diff3" performs a three-way
64       difference.
65
66       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
70       Perhaps an example would be useful.
71
72       Given the following three lists,
73
74         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
78            merge: a b   d e   g   i j k
79
80       we have the following result from diff3:
81
82        [ '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
93       The first element in each row is the array with the difference:
94
95        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
101       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
105   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
110       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
117       The default "CONFLICT" callback returns the following:
118
119        q{<!-- ------ START CONFLICT ------ -->},
120        (@left),
121        q{<!-- ---------------------------- -->},
122        (@right),
123        q{<!-- ------  END  CONFLICT ------ -->},
124
125   traverse_sequences3
126       This is the workhorse function that goes through the three sequences
127       and calls the callback functions.
128
129       The following callbacks are supported.
130
131       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
137       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
142           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
145           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
149           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
154       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
159           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
162           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
166           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
171       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
176           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
179           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
183           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
188       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

BUGS

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
198       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

SEE ALSO

208       Algorithm::Diff.
209

AUTHOR

211       James G. Smith, <jsmith@cpan.org>
212
214       Copyright (C) 2003, 2007  Texas A&M University.  All Rights Reserved.
215
216       This module is free software; you may redistribute it and/or modify it
217       under the same terms as Perl itself.
218

POD ERRORS

220       Hey! The above document had some coding errors, which are explained
221       below:
222
223       Around line 680:
224           =back doesn't take any parameters, but you said =back 4
225
226
227
228perl v5.32.0                      2020-07-28                          Merge(3)
Impressum