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" utility.
25 It is not anywhere near as feature complete as GNU "diff", but it is
26 better integrated with Perl and available on all platforms. It is
27 often faster than shelling out to a system's "diff" executable for
28 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() methods
73 are provided for overloading only; none of the formats provide
74 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, diff()
81 will load it automatically (lazy loading). Since all such packages
82 should inherit from "Text::Diff::Base", this should be marvy.
83 Styles may be specified as class names ("STYLE => 'Foo'"), in which
85 case they will be new()ed with no parameters, or as objects ("STYLE
86 => Foo->new").
87 CONTEXT
89 How many lines before and after each diff to display. Ignored on
90 old-style diffs. Defaults to 3.
91 OUTPUT
93 Examples and their equivalent subroutines:
94 OUTPUT => \*FOOHANDLE, # like: sub { print FOOHANDLE shift() }
96 OUTPUT => \$output, # like: sub { $output .= shift }
97 OUTPUT => \@output, # like: sub { push @output, shift }
98 OUTPUT => sub { $output .= shift },
99 If no "OUTPUT" is supplied, returns the diffs in a string. If
101 "OUTPUT" is a "CODE" ref, it will be called once with the
102 (optional) file header, and once for each hunk body with the text
103 to emit. If "OUTPUT" is an IO::Handle, output will be emitted to
104 that handle.
105 FILENAME_PREFIX_A, FILENAME_PREFIX_B
107 The string to print before the filename in the header. Unused on
108 "OldStyle" diffs. Defaults are "---", "+++" for Unified and "***",
109 "+++" for Context.
110 KEYGEN, KEYGEN_ARGS
112 These are passed to "traverse_sequences" in Algorithm::Diff.
113 Note: if neither "FILENAME_" option is defined, the header will not be
115 printed. If at least one is present, the other and both "MTIME_"
116 options must be present or "Use of undefined variable" warnings will be
117 generated (except on "OldStyle" diffs, which ignores these options).
118
120 These functions implement the output formats. They are grouped in to
121 classes so diff() can use class names to call the correct set of output
122 routines and so that you may inherit from them easily. There are no
123 constructors or instance methods for these classes, though subclasses
124 may provide them if need be.
125 Each class has file_header(), hunk_header(), hunk(), and footer()
127 methods identical to those documented in the "Text::Diff::Unified"
128 section. header() is called before the hunk() is first called,
129 footer() afterwards. The default footer function is an empty method
130 provided for overloading:
131 sub footer { return "End of patch\n" }
133 Some output formats are provided by external modules (which are loaded
135 automatically), such as Text::Diff::Table. These are are documented
136 here to keep the documentation simple.
137 Text::Diff::Base
139 Returns "" for all methods (other than new()).
140 Text::Diff::Unified
142 --- A Mon Nov 12 23:49:30 2001
143 +++ B Mon Nov 12 23:49:30 2001
144 @@ -2,13 +2,13 @@
145 2
146 3
147 4
148 -5d
149 +5a
150 6
151 7
152 8
153 9
154 +9a
155 10
156 11
157 -11d
158 12
159 13
160 Text::Diff::Unified::file_header
162 $s = Text::Diff::Unified->file_header( $options );
163 Returns a string containing a unified header. The sole parameter
165 is the "options" hash passed in to diff(), containing at least:
166 FILENAME_A => $fn1,
168 MTIME_A => $mtime1,
169 FILENAME_B => $fn2,
170 MTIME_B => $mtime2
171 May also contain
173 FILENAME_PREFIX_A => "---",
175 FILENAME_PREFIX_B => "+++",
176 to override the default prefixes (default values shown).
178 Text::Diff::Unified::hunk_header
180 Text::Diff::Unified->hunk_header( \@ops, $options );
181 Returns a string containing the heading of one hunk of unified
183 diff.
184 Text::Diff::Unified::hunk
186 Text::Diff::Unified->hunk( \@seq_a, \@seq_b, \@ops, $options );
187 Returns a string containing the output of one hunk of unified diff.
189 Text::Diff::Table
191 +--+----------------------------------+--+------------------------------+
192 | |../Test-Differences-0.2/MANIFEST | |../Test-Differences/MANIFEST |
193 | |Thu Dec 13 15:38:49 2001 | |Sat Dec 15 02:09:44 2001 |
194 +--+----------------------------------+--+------------------------------+
195 | | * 1|Changes *
196 | 1|Differences.pm | 2|Differences.pm |
197 | 2|MANIFEST | 3|MANIFEST |
198 | | * 4|MANIFEST.SKIP *
199 | 3|Makefile.PL | 5|Makefile.PL |
200 | | * 6|t/00escape.t *
201 | 4|t/00flatten.t | 7|t/00flatten.t |
202 | 5|t/01text_vs_data.t | 8|t/01text_vs_data.t |
203 | 6|t/10test.t | 9|t/10test.t |
204 +--+----------------------------------+--+------------------------------+
205 This format also goes to some pains to highlight "invisible" characters
207 on differing elements by selectively escaping whitespace:
208 +--+--------------------------+--------------------------+
210 | |demo_ws_A.txt |demo_ws_B.txt |
211 | |Fri Dec 21 08:36:32 2001 |Fri Dec 21 08:36:50 2001 |
212 +--+--------------------------+--------------------------+
213 | 1|identical |identical |
214 * 2| spaced in | also spaced in *
215 * 3|embedded space |embedded tab *
216 | 4|identical |identical |
217 * 5| spaced in |\ttabbed in *
218 * 6|trailing spaces\s\s\n |trailing tabs\t\t\n *
219 | 7|identical |identical |
220 * 8|lf line\n |crlf line\r\n *
221 * 9|embedded ws |embedded\tws *
222 +--+--------------------------+--------------------------+
223 See Text::Diff::Table for more details, including how the whitespace
225 escaping works.
226 Text::Diff::Context
228 *** A Mon Nov 12 23:49:30 2001
229 --- B Mon Nov 12 23:49:30 2001
230 ***************
231 *** 2,14 ****
232 2
233 3
234 4
235 ! 5d
236 6
237 7
238 8
239 9
240 10
241 11
242 - 11d
243 12
244 13
245 --- 2,14 ----
246 2
247 3
248 4
249 ! 5a
250 6
251 7
252 8
253 9
254 + 9a
255 10
256 11
257 12
258 13
259 Note: hunk_header() returns only "***************\n".
261 Text::Diff::OldStyle
263 5c5
264 < 5d
265 ---
266 > 5a
267 9a10
268 > 9a
269 12d12
270 < 11d
271 Note: no file_header().
273
275 Must suck both input files entirely in to memory and store them with a
276 normal amount of Perlish overhead (one array location) per record.
277 This is implied by the implementation of Algorithm::Diff, which takes
278 two arrays. If Algorithm::Diff ever offers an incremental mode, this
279 can be changed (contact the maintainers of Algorithm::Diff and
280 "Text::Diff" if you need this; it shouldn't be too terribly hard to tie
281 arrays in this fashion).
282 Does not provide most of the more refined GNU "diff" options: recursive
284 directory tree scanning, ignoring blank lines / whitespace, etc., etc.
285 These can all be added as time permits and need arises, many are rather
286 easy; patches quite welcome.
287 Uses closures internally, this may lead to leaks on Perl versions 5.6.1
289 and prior if used many times over a process' life time.
290
292 Algorithm::Diff - the underlying implementation of the diff algorithm
293 used by "Text::Diff".
294 YAML::Diff - find difference between two YAML documents.
296 HTML::Differences - find difference between two HTML documents. This
298 uses a more sane approach than HTML::Diff.
299 XML::Diff - find difference between two XML documents.
301 Array::Diff - find the differences between two Perl arrays.
303 Hash::Diff - find the differences between two Perl hashes.
305 Data::Diff - find difference between two arbitrary data structures.
307
309 <https://github.com/neilbowers/Text-Diff>
310
312 Adam Kennedy <adamk@cpan.org>
313 Barrie Slaymaker <barries@slaysys.com>
315
317 Some parts copyright 2009 Adam Kennedy.
318 Copyright 2001 Barrie Slaymaker. All Rights Reserved.
320 You may use this under the terms of either the Artistic License or GNU
322 Public License v 2.0 or greater.
323perl v5.36.0 2023-01-20 Text::Diff(3)