1Text::Diff(3) User Contributed Perl Documentation Text::Diff(3)
2
6 Text::Diff - Perform diffs on files and record sets
7
9 use Text::Diff;
10 ## Mix and match filenames, strings, file handles, producer subs,
12 ## or arrays of records; returns diff in a string.
13 ## WARNING: can return B<large> diffs for large files.
14 my $diff = diff "file1.txt", "file2.txt", { STYLE => "Context" };
15 my $diff = diff \$string1, \$string2, \%options;
16 my $diff = diff \*FH1, \*FH2;
17 my $diff = diff \&reader1, \&reader2;
18 my $diff = diff \@records1, \@records2;
19 ## May also mix input types:
21 my $diff = diff \@records1, "file_B.txt";
22
24 "diff()" provides a basic set of services akin to the GNU "diff"
25 utility. It is not anywhere near as feature complete as GNU "diff",
26 but it is better integrated with Perl and available on all platforms.
27 It is often faster than shelling out to a system's "diff" executable
28 for small files, and generally slower on larger files.
29 Relies on Algorithm::Diff for, well, the algorithm. This may not
31 produce the same exact diff as a system's local "diff" executable, but
32 it will be a valid diff and comprehensible by "patch". We haven't seen
33 any differences between Algorithm::Diff's logic and GNU "diff"'s, but
34 we have not examined them to make sure they are indeed identical.
35 Note: If you don't want to import the "diff" function, do one of the
37 following:
38 use Text::Diff ();
40 require Text::Diff;
42 That's a pretty rare occurrence, so "diff()" is exported by default.
44 If you pass a filename, but the file can't be read, then "diff()" will
46 "croak".
47
49 "diff()" takes two parameters from which to draw input and a set of
50 options to control its output. The options are:
51 FILENAME_A, MTIME_A, FILENAME_B, MTIME_B
53 The name of the file and the modification time "files".
54 These are filled in automatically for each file when "diff()" is
56 passed a filename, unless a defined value is passed in.
57 If a filename is not passed in and FILENAME_A and FILENAME_B are
59 not provided or are "undef", the header will not be printed.
60 Unused on "OldStyle" diffs.
62 OFFSET_A, OFFSET_B
64 The index of the first line / element. These default to 1 for all
65 parameter types except ARRAY references, for which the default is
66 0. This is because ARRAY references are presumed to be data
67 structures, while the others are line-oriented text.
68 STYLE
70 "Unified", "Context", "OldStyle", or an object or class reference
71 for a class providing "file_header()", "hunk_header()", "hunk()",
72 "hunk_footer()" and "file_footer()" methods. The two footer()
73 methods are provided for overloading only; none of the formats
74 provide them.
75 Defaults to "Unified" (unlike standard "diff", but Unified is
77 what's most often used in submitting patches and is the most human
78 readable of the three.
79 If the package indicated by the STYLE has no "hunk()" method,
81 "diff()" will load it automatically (lazy loading). Since all such
82 packages should inherit from "Text::Diff::Base", this should be
83 marvy.
84 Styles may be specified as class names ("STYLE => 'Foo'"), in which
86 case they will be "new()"ed with no parameters, or as objects
87 ("STYLE => Foo->new").
88 CONTEXT
90 How many lines before and after each diff to display. Ignored on
91 old-style diffs. Defaults to 3.
92 OUTPUT
94 Examples and their equivalent subroutines:
95 OUTPUT => \*FOOHANDLE, # like: sub { print FOOHANDLE shift() }
97 OUTPUT => \$output, # like: sub { $output .= shift }
98 OUTPUT => \@output, # like: sub { push @output, shift }
99 OUTPUT => sub { $output .= shift },
100 If no "OUTPUT" is supplied, returns the diffs in a string. If
102 "OUTPUT" is a "CODE" ref, it will be called once with the
103 (optional) file header, and once for each hunk body with the text
104 to emit. If "OUTPUT" is an IO::Handle, output will be emitted to
105 that handle.
106 FILENAME_PREFIX_A, FILENAME_PREFIX_B
108 The string to print before the filename in the header. Unused on
109 "OldStyle" diffs. Defaults are "---", "+++" for Unified and "***",
110 "+++" for Context.
111 KEYGEN, KEYGEN_ARGS
113 These are passed to "traverse_sequences" in Algorithm::Diff.
114 Note: if neither "FILENAME_" option is defined, the header will not be
116 printed. If at least one is present, the other and both "MTIME_"
117 options must be present or "Use of undefined variable" warnings will be
118 generated (except on "OldStyle" diffs, which ignores these options).
119
121 These functions implement the output formats. They are grouped in to
122 classes so "diff()" can use class names to call the correct set of
123 output routines and so that you may inherit from them easily. There
124 are no constructors or instance methods for these classes, though
125 subclasses may provide them if need be.
126 Each class has "file_header()", "hunk_header()", "hunk()", and
128 "footer()" methods identical to those documented in the
129 "Text::Diff::Unified" section. "header()" is called before the
130 "hunk()" is first called, "footer()" afterwards. The default footer
131 function is an empty method provided for overloading:
132 sub footer { return "End of patch\n" }
134 Some output formats are provided by external modules (which are loaded
136 automatically), such as Text::Diff::Table. These are are documented
137 here to keep the documentation simple.
138 Text::Diff::Base
140 Returns "" for all methods (other than "new()").
141 Text::Diff::Unified
143 --- A Mon Nov 12 23:49:30 2001
144 +++ B Mon Nov 12 23:49:30 2001
145 @@ -2,13 +2,13 @@
146 2
147 3
148 4
149 -5d
150 +5a
151 6
152 7
153 8
154 9
155 +9a
156 10
157 11
158 -11d
159 12
160 13
161 Text::Diff::Unified::file_header
163 $s = Text::Diff::Unified->file_header( $options );
164 Returns a string containing a unified header. The sole parameter
166 is the "options" hash passed in to "diff()", containing at least:
167 FILENAME_A => $fn1,
169 MTIME_A => $mtime1,
170 FILENAME_B => $fn2,
171 MTIME_B => $mtime2
172 May also contain
174 FILENAME_PREFIX_A => "---",
176 FILENAME_PREFIX_B => "+++",
177 to override the default prefixes (default values shown).
179 Text::Diff::Unified::hunk_header
181 Text::Diff::Unified->hunk_header( \@ops, $options );
182 Returns a string containing the heading of one hunk of unified
184 diff.
185 Text::Diff::Unified::hunk
187 Text::Diff::Unified->hunk( \@seq_a, \@seq_b, \@ops, $options );
188 Returns a string containing the output of one hunk of unified diff.
190 Text::Diff::Table
192 +--+----------------------------------+--+------------------------------+
193 | |../Test-Differences-0.2/MANIFEST | |../Test-Differences/MANIFEST |
194 | |Thu Dec 13 15:38:49 2001 | |Sat Dec 15 02:09:44 2001 |
195 +--+----------------------------------+--+------------------------------+
196 | | * 1|Changes *
197 | 1|Differences.pm | 2|Differences.pm |
198 | 2|MANIFEST | 3|MANIFEST |
199 | | * 4|MANIFEST.SKIP *
200 | 3|Makefile.PL | 5|Makefile.PL |
201 | | * 6|t/00escape.t *
202 | 4|t/00flatten.t | 7|t/00flatten.t |
203 | 5|t/01text_vs_data.t | 8|t/01text_vs_data.t |
204 | 6|t/10test.t | 9|t/10test.t |
205 +--+----------------------------------+--+------------------------------+
206 This format also goes to some pains to highlight "invisible" characters
208 on differing elements by selectively escaping whitespace:
209 +--+--------------------------+--------------------------+
211 | |demo_ws_A.txt |demo_ws_B.txt |
212 | |Fri Dec 21 08:36:32 2001 |Fri Dec 21 08:36:50 2001 |
213 +--+--------------------------+--------------------------+
214 | 1|identical |identical |
215 * 2| spaced in | also spaced in *
216 * 3|embedded space |embedded tab *
217 | 4|identical |identical |
218 * 5| spaced in |\ttabbed in *
219 * 6|trailing spaces\s\s\n |trailing tabs\t\t\n *
220 | 7|identical |identical |
221 * 8|lf line\n |crlf line\r\n *
222 * 9|embedded ws |embedded\tws *
223 +--+--------------------------+--------------------------+
224 See Text::Diff::Table for more details, including how the whitespace
226 escaping works.
227 Text::Diff::Context
229 *** A Mon Nov 12 23:49:30 2001
230 --- B Mon Nov 12 23:49:30 2001
231 ***************
232 *** 2,14 ****
233 2
234 3
235 4
236 ! 5d
237 6
238 7
239 8
240 9
241 10
242 11
243 - 11d
244 12
245 13
246 --- 2,14 ----
247 2
248 3
249 4
250 ! 5a
251 6
252 7
253 8
254 9
255 + 9a
256 10
257 11
258 12
259 13
260 Note: "hunk_header()" returns only "***************\n".
262 Text::Diff::OldStyle
264 5c5
265 < 5d
266 ---
267 > 5a
268 9a10
269 > 9a
270 12d12
271 < 11d
272 Note: no "file_header()".
274
276 Must suck both input files entirely in to memory and store them with a
277 normal amount of Perlish overhead (one array location) per record.
278 This is implied by the implementation of Algorithm::Diff, which takes
279 two arrays. If Algorithm::Diff ever offers an incremental mode, this
280 can be changed (contact the maintainers of Algorithm::Diff and
281 "Text::Diff" if you need this; it shouldn't be too terribly hard to tie
282 arrays in this fashion).
283 Does not provide most of the more refined GNU "diff" options: recursive
285 directory tree scanning, ignoring blank lines / whitespace, etc., etc.
286 These can all be added as time permits and need arises, many are rather
287 easy; patches quite welcome.
288 Uses closures internally, this may lead to leaks on Perl versions 5.6.1
290 and prior if used many times over a process' life time.
291
293 Algorithm::Diff - the underlying implementation of the diff algorithm
294 used by "Text::Diff".
295 YAML::Diff - find difference between two YAML documents.
297 HTML::Differences - find difference between two HTML documents. This
299 uses a more sane approach than HTML::Diff.
300 XML::Diff - find difference between two XML documents.
302 Array::Diff - find the differences between two Perl arrays.
304 Hash::Diff - find the differences between two Perl hashes.
306 Data::Diff - find difference between two arbitrary data structures.
308
310 <https://github.com/neilbowers/Text-Diff>
311
313 Adam Kennedy <adamk@cpan.org>
314 Barrie Slaymaker <barries@slaysys.com>
316
318 Some parts copyright 2009 Adam Kennedy.
319 Copyright 2001 Barrie Slaymaker. All Rights Reserved.
321 You may use this under the terms of either the Artistic License or GNU
323 Public License v 2.0 or greater.
324perl v5.34.0 2022-01-21 Text::Diff(3)