1Text::Diff(3)         User Contributed Perl Documentation        Text::Diff(3)
2
3
4

NAME

6       Text::Diff - Perform diffs on files and record sets
7

SYNOPSIS

9           use Text::Diff;
10
11           ## 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
20           ## May also mix input types:
21           my $diff = diff \@records1,  "file_B.txt";
22

DESCRIPTION

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
30       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
36       Note: If you don't want to import the "diff" function, do one of the
37       following:
38
39          use Text::Diff ();
40
41          require Text::Diff;
42
43       That's a pretty rare occurrence, so "diff()" is exported by default.
44
45       If you pass a filename, but the file can't be read, then "diff()" will
46       "croak".
47

OPTIONS

49       "diff()" takes two parameters from which to draw input and a set of
50       options to control its output.  The options are:
51
52       FILENAME_A, MTIME_A, FILENAME_B, MTIME_B
53           The name of the file and the modification time "files".
54
55           These are filled in automatically for each file when "diff()" is
56           passed a filename, unless a defined value is passed in.
57
58           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
61           Unused on "OldStyle" diffs.
62
63       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
69       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
76           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
80           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
85           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
89       CONTEXT
90           How many lines before and after each diff to display.  Ignored on
91           old-style diffs.  Defaults to 3.
92
93       OUTPUT
94           Examples and their equivalent subroutines:
95
96               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
101           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
107       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
112       KEYGEN, KEYGEN_ARGS
113           These are passed to "traverse_sequences" in Algorithm::Diff.
114
115       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

Formatting Classes

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
127       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
133           sub footer { return "End of patch\n" }
134
135       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
139   Text::Diff::Base
140       Returns "" for all methods (other than "new()").
141
142   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
162       Text::Diff::Unified::file_header
163             $s = Text::Diff::Unified->file_header( $options );
164
165           Returns a string containing a unified header.  The sole parameter
166           is the "options" hash passed in to "diff()", containing at least:
167
168             FILENAME_A  => $fn1,
169             MTIME_A     => $mtime1,
170             FILENAME_B  => $fn2,
171             MTIME_B     => $mtime2
172
173           May also contain
174
175             FILENAME_PREFIX_A    => "---",
176             FILENAME_PREFIX_B    => "+++",
177
178           to override the default prefixes (default values shown).
179
180       Text::Diff::Unified::hunk_header
181             Text::Diff::Unified->hunk_header( \@ops, $options );
182
183           Returns a string containing the heading of one hunk of unified
184           diff.
185
186       Text::Diff::Unified::hunk
187             Text::Diff::Unified->hunk( \@seq_a, \@seq_b, \@ops, $options );
188
189           Returns a string containing the output of one hunk of unified diff.
190
191   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
207       This format also goes to some pains to highlight "invisible" characters
208       on differing elements by selectively escaping whitespace:
209
210         +--+--------------------------+--------------------------+
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
225       See Text::Diff::Table for more details, including how the whitespace
226       escaping works.
227
228   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
261       Note: "hunk_header()" returns only "***************\n".
262
263   Text::Diff::OldStyle
264           5c5
265           < 5d
266           ---
267           > 5a
268           9a10
269           > 9a
270           12d12
271           < 11d
272
273       Note: no "file_header()".
274

LIMITATIONS

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
284       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
289       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

SEE ALSO

293       Algorithm::Diff - the underlying implementation of the diff algorithm
294       used by "Text::Diff".
295
296       YAML::Diff - find difference between two YAML documents.
297
298       HTML::Differences - find difference between two HTML documents.  This
299       uses a more sane approach than HTML::Diff.
300
301       XML::Diff - find difference between two XML documents.
302
303       Array::Diff - find the differences between two Perl arrays.
304
305       Hash::Diff - find the differences between two Perl hashes.
306
307       Data::Diff - find difference between two arbitrary data structures.
308

REPOSITORY

310       <https://github.com/neilbowers/Text-Diff>
311

AUTHOR

313       Adam Kennedy <adamk@cpan.org>
314
315       Barrie Slaymaker <barries@slaysys.com>
316
318       Some parts copyright 2009 Adam Kennedy.
319
320       Copyright 2001 Barrie Slaymaker.  All Rights Reserved.
321
322       You may use this under the terms of either the Artistic License or GNU
323       Public License v 2.0 or greater.
324
325
326
327perl v5.34.0                      2022-01-21                     Text::Diff(3)
Impressum