--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" 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" ''
+'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.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Text::Diff 3"
+.TH Text::Diff 3 "2009-07-16" "perl v5.8.7" "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.
+=head1 \s-1OPTIONS\s0
+.PP
+\&\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\s0, \s-1MTIME_A\s0, \s-1FILENAME_B\s0, \s-1MTIME_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\s0, \s-1OFFSET_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 =\*(C'\fR \*(L"Foo\*(R"), in which case they
+will be \f(CW\*(C`new()\*(C'\fRed with no parameters, or as objects (\f(CW\*(C`STYLE =\*(C'\fR Foo\->new>).
+.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\s0, \s-1FILENAME_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\s0, \s-1KEYGEN_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 \*(L"Text::Diff::Table\*(R" 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 "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.
projects / catagits/Gitalist.git / blobdiff