.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Diff 3"
.TH Text::Diff 3 "2016-02-27" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Diff \- Perform diffs on files and record sets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Text::Diff;
\&
\&    ## Mix and match filenames, strings, file handles, producer subs,
\&    ## or arrays of records; returns diff in a string.
\&    ## WARNING: can return B<large> diffs for large files.
\&    my $diff = diff "file1.txt", "file2.txt", { STYLE => "Context" };
\&    my $diff = diff \e$string1,   \e$string2,   \e%options;
\&    my $diff = diff \e*FH1,       \e*FH2;
\&    my $diff = diff \e&reader1,   \e&reader2;
\&    my $diff = diff \e@records1,  \e@records2;
\&
\&    ## May also mix input types:
\&    my $diff = diff \e@records1,  "file_B.txt";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`diff()\*(C'\fR provides a basic set of services akin to the \s-1GNU \s0\f(CW\*(C`diff\*(C'\fR utility.  It
is not anywhere near as feature complete as \s-1GNU \s0\f(CW\*(C`diff\*(C'\fR, but it is better
integrated with Perl and available on all platforms.  It is often faster than
shelling out to a system's \f(CW\*(C`diff\*(C'\fR executable for small files, and generally
slower on larger files.
.PP
Relies on Algorithm::Diff for, well, the algorithm.  This may not produce
the same exact diff as a system's local \f(CW\*(C`diff\*(C'\fR executable, but it will be a
valid diff and comprehensible by \f(CW\*(C`patch\*(C'\fR.  We haven't seen any differences
between Algorithm::Diff's logic and \s-1GNU\s0 diff's, but we have not examined them
to make sure they are indeed identical.
.PP
\&\fBNote\fR: If you don't want to import the \f(CW\*(C`diff\*(C'\fR function, do one of the
following:
.PP
.Vb 1
\&   use Text::Diff ();
\&
\&   require Text::Diff;
.Ve
.PP
That's a pretty rare occurence, so \f(CW\*(C`diff()\*(C'\fR is exported by default.
.PP
If you pass a filename, but the file can't be read,
then \f(CW\*(C`diff()\*(C'\fR will \f(CW\*(C`croak\*(C'\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fIdiff()\fR takes two parameters from which to draw input and a set of
options to control it's output.  The options are:
.IP "\s-1FILENAME_A, MTIME_A, FILENAME_B, MTIME_B\s0" 4
.IX Item "FILENAME_A, MTIME_A, FILENAME_B, MTIME_B"
The name of the file and the modification time \*(L"files\*(R"
.Sp
These are filled in automatically for each file when \fIdiff()\fR is passed a
filename, unless a defined value is passed in.
.Sp
If a filename is not passed in and \s-1FILENAME_A\s0 and \s-1FILENAME_B\s0 are not provided
or \f(CW\*(C`undef\*(C'\fR, the header will not be printed.
.Sp
Unused on \f(CW\*(C`OldStyle\*(C'\fR diffs.
.IP "\s-1OFFSET_A, OFFSET_B\s0" 4
.IX Item "OFFSET_A, OFFSET_B"
The index of the first line / element.  These default to 1 for all
parameter types except \s-1ARRAY\s0 references, for which the default is 0.  This
is because \s-1ARRAY\s0 references are presumed to be data structures, while the
others are line oriented text.
.IP "\s-1STYLE\s0" 4
.IX Item "STYLE"
\&\*(L"Unified\*(R", \*(L"Context\*(R", \*(L"OldStyle\*(R", or an object or class reference for a class
providing \f(CW\*(C`file_header()\*(C'\fR, \f(CW\*(C`hunk_header()\*(C'\fR, \f(CW\*(C`hunk()\*(C'\fR, \f(CW\*(C`hunk_footer()\*(C'\fR and
\&\f(CW\*(C`file_footer()\*(C'\fR methods.  The two \fIfooter()\fR methods are provided for
overloading only; none of the formats provide them.
.Sp
Defaults to \*(L"Unified\*(R" (unlike standard \f(CW\*(C`diff\*(C'\fR, but Unified is what's most
often used in submitting patches and is the most human readable of the three.
.Sp
If the package indicated by the \s-1STYLE\s0 has no \fIhunk()\fR method, c<\fIdiff()\fR> will
load it automatically (lazy loading).  Since all such packages should inherit
from Text::Diff::Base, this should be marvy.
.Sp
Styles may be specified as class names (\f(CW\*(C`STYLE => \*(AqFoo\*(Aq\*(C'\fR),
in which case they will be \f(CW\*(C`new()\*(C'\fRed with no parameters,
or as objects (\f(CW\*(C`STYLE => Foo\->new\*(C'\fR).
.IP "\s-1CONTEXT\s0" 4
.IX Item "CONTEXT"
How many lines before and after each diff to display.  Ignored on old-style
diffs.  Defaults to 3.
.IP "\s-1OUTPUT\s0" 4
.IX Item "OUTPUT"
Examples and their equivalent subroutines:
.Sp
.Vb 4
\&    OUTPUT   => \e*FOOHANDLE,   # like: sub { print FOOHANDLE shift() }
\&    OUTPUT   => \e$output,      # like: sub { $output .= shift }
\&    OUTPUT   => \e@output,      # like: sub { push @output, shift }
\&    OUTPUT   => sub { $output .= shift },
.Ve
.Sp
If no \f(CW\*(C`OUTPUT\*(C'\fR is supplied, returns the diffs in a string.  If
\&\f(CW\*(C`OUTPUT\*(C'\fR is a \f(CW\*(C`CODE\*(C'\fR ref, it will be called once with the (optional)
file header, and once for each hunk body with the text to emit.  If
\&\f(CW\*(C`OUTPUT\*(C'\fR is an IO::Handle, output will be emitted to that handle.
.IP "\s-1FILENAME_PREFIX_A, FILENAME_PREFIX_B\s0" 4
.IX Item "FILENAME_PREFIX_A, FILENAME_PREFIX_B"
The string to print before the filename in the header. Unused on \f(CW\*(C`OldStyle\*(C'\fR
diffs.  Defaults are \f(CW"\-\-\-"\fR, \f(CW"+++"\fR for Unified and \f(CW"***"\fR, \f(CW"+++"\fR for
Context.
.IP "\s-1KEYGEN, KEYGEN_ARGS\s0" 4
.IX Item "KEYGEN, KEYGEN_ARGS"
These are passed to \*(L"traverse_sequences\*(R" in Algorithm::Diff.
.PP
\&\fBNote\fR: if neither \f(CW\*(C`FILENAME_\*(C'\fR option is defined, the header will not be
printed.  If at one is present, the other and both \s-1MTIME_\s0 options must be
present or \*(L"Use of undefined variable\*(R" warnings will be generated (except
on \f(CW\*(C`OldStyle\*(C'\fR diffs, which ignores these options).
.SH "Formatting Classes"
.IX Header "Formatting Classes"
These functions implement the output formats.  They are grouped in to classes
so \fIdiff()\fR can use class names to call the correct set of output routines and so
that you may inherit from them easily.  There are no constructors or instance
methods for these classes, though subclasses may provide them if need be.
.PP
Each class has \fIfile_header()\fR, \fIhunk_header()\fR, \fIhunk()\fR, and \fIfooter()\fR methods
identical to those documented in the Text::Diff::Unified section.  \fIheader()\fR is
called before the \fIhunk()\fR is first called, \fIfooter()\fR afterwards.  The default
footer function is an empty method provided for overloading:
.PP
.Vb 1
\&    sub footer { return "End of patch\en" }
.Ve
.PP
Some output formats are provided by external modules (which are loaded
automatically), such as Text::Diff::Table.  These are
are documented here to keep the documentation simple.
.SS "Text::Diff::Base"
.IX Subsection "Text::Diff::Base"
Returns "" for all methods (other than \f(CW\*(C`new()\*(C'\fR).
.SS "Text::Diff::Unified"
.IX Subsection "Text::Diff::Unified"
.Vb 10
\&  \-\-\- A   Mon Nov 12 23:49:30 2001
\&  +++ B   Mon Nov 12 23:49:30 2001
\&  @@ \-2,13 +2,13 @@
\&   2
\&   3
\&   4
\&  \-5d
\&  +5a
\&   6
\&   7
\&   8
\&   9
\&  +9a
\&   10
\&   11
\&  \-11d
\&   12
\&   13
.Ve
.IP "file_header" 4
.IX Item "file_header"
.Vb 1
\&  $s = Text::Diff::Unified\->file_header( $options );
.Ve
.Sp
Returns a string containing a unified header.  The sole parameter is the
options hash passed in to \fIdiff()\fR, containing at least:
.Sp
.Vb 4
\&  FILENAME_A  => $fn1,
\&  MTIME_A     => $mtime1,
\&  FILENAME_B  => $fn2,
\&  MTIME_B     => $mtime2
.Ve
.Sp
May also contain
.Sp
.Vb 2
\&  FILENAME_PREFIX_A    => "\-\-\-",
\&  FILENAME_PREFIX_B    => "+++",
.Ve
.Sp
to override the default prefixes (default values shown).
.IP "hunk_header" 4
.IX Item "hunk_header"
.Vb 1
\&  Text::Diff::Unified\->hunk_header( \e@ops, $options );
.Ve
.Sp
Returns a string containing the output of one hunk of unified diff.
.IP "Text::Diff::Unified::hunk" 4
.IX Item "Text::Diff::Unified::hunk"
.Vb 1
\&  Text::Diff::Unified\->hunk( \e@seq_a, \e@seq_b, \e@ops, $options );
.Ve
.Sp
Returns a string containing the output of one hunk of unified diff.
.SS "Text::Diff::Table"
.IX Subsection "Text::Diff::Table"
.Vb 10
\&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&  |  |../Test\-Differences\-0.2/MANIFEST  |  |../Test\-Differences/MANIFEST  |
\&  |  |Thu Dec 13 15:38:49 2001          |  |Sat Dec 15 02:09:44 2001      |
\&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&  |  |                                  * 1|Changes                       *
\&  | 1|Differences.pm                    | 2|Differences.pm                |
\&  | 2|MANIFEST                          | 3|MANIFEST                      |
\&  |  |                                  * 4|MANIFEST.SKIP                 *
\&  | 3|Makefile.PL                       | 5|Makefile.PL                   |
\&  |  |                                  * 6|t/00escape.t                  *
\&  | 4|t/00flatten.t                     | 7|t/00flatten.t                 |
\&  | 5|t/01text_vs_data.t                | 8|t/01text_vs_data.t            |
\&  | 6|t/10test.t                        | 9|t/10test.t                    |
\&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
This format also goes to some pains to highlight \*(L"invisible\*(R" characters on
differing elements by selectively escaping whitespace:
.PP
.Vb 10
\&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&  |  |demo_ws_A.txt             |demo_ws_B.txt             |
\&  |  |Fri Dec 21 08:36:32 2001  |Fri Dec 21 08:36:50 2001  |
\&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&  | 1|identical                 |identical                 |
\&  * 2|        spaced in         |        also spaced in    *
\&  * 3|embedded space            |embedded        tab       *
\&  | 4|identical                 |identical                 |
\&  * 5|        spaced in         |\ettabbed in               *
\&  * 6|trailing spaces\es\es\en     |trailing tabs\et\et\en       *
\&  | 7|identical                 |identical                 |
\&  * 8|lf line\en                 |crlf line\er\en             *
\&  * 9|embedded ws               |embedded\etws              *
\&  +\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
See Text::Diff::Table for more details, including how the whitespace
escaping works.
.SS "Text::Diff::Context"
.IX Subsection "Text::Diff::Context"
.Vb 10
\&    *** A   Mon Nov 12 23:49:30 2001
\&    \-\-\- B   Mon Nov 12 23:49:30 2001
\&    ***************
\&    *** 2,14 ****
\&      2
\&      3
\&      4
\&    ! 5d
\&      6
\&      7
\&      8
\&      9
\&      10
\&      11
\&    \- 11d
\&      12
\&      13
\&    \-\-\- 2,14 \-\-\-\-
\&      2
\&      3
\&      4
\&    ! 5a
\&      6
\&      7
\&      8
\&      9
\&    + 9a
\&      10
\&      11
\&      12
\&      13
.Ve
.PP
Note: \fIhunk_header()\fR returns only \*(L"***************\en\*(R".
.SS "Text::Diff::OldStyle"
.IX Subsection "Text::Diff::OldStyle"
.Vb 8
\&    5c5
\&    < 5d
\&    \-\-\-
\&    > 5a
\&    9a10
\&    > 9a
\&    12d12
\&    < 11d
.Ve
.PP
Note: no \fIfile_header()\fR.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Must suck both input files entirely in to memory and store them with a normal
amount of Perlish overhead (one array location) per record.  This is implied by
the implementation of Algorithm::Diff, which takes two arrays.  If
Algorithm::Diff ever offers an incremental mode, this can be changed (contact
the maintainers of Algorithm::Diff and Text::Diff if you need this; it
shouldn't be too terribly hard to tie arrays in this fashion).
.PP
Does not provide most of the more refined \s-1GNU\s0 diff options: recursive directory
tree scanning, ignoring blank lines / whitespace, etc., etc.  These can all be
added as time permits and need arises, many are rather easy; patches quite
welcome.
.PP
Uses closures internally, this may lead to leaks on \f(CW\*(C`perl\*(C'\fR versions 5.6.1 and
prior if used many times over a process' life time.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Algorithm::Diff \- the underlying implementation of the diff algorithm
used by \f(CW\*(C`Text::Diff\*(C'\fR.
.PP
YAML::Diff \- find difference between two \s-1YAML\s0 documents.
.PP
HTML::Differences \- find difference between two \s-1HTML\s0 documents.
This uses a more sane approach than HTML::Diff.
.PP
XML::Diff \- find difference between two \s-1XML\s0 documents.
.PP
Array::Diff \- find the differences between two Perl arrays.
.PP
Hash::Diff \- find the differences between two Perl hashes.
.PP
Data::Diff \- find difference between two arbitrary data structures.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilbowers/Text\-Diff>
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.PP
Barrie Slaymaker <barries@slaysys.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Some parts copyright 2009 Adam Kennedy.
.PP
Copyright 2001 Barrie Slaymaker.  All Rights Reserved.
.PP
You may use this under the terms of either the Artistic License or \s-1GNU\s0 Public
License v 2.0 or greater.