X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FText%3A%3ADiff.3pm;fp=local-lib5%2Fman%2Fman3%2FText%3A%3ADiff.3pm;h=ac4d6f4b1dd84974ab30f6a8e2722936fe3395c6;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e diff --git a/local-lib5/man/man3/Text::Diff.3pm b/local-lib5/man/man3/Text::Diff.3pm new file mode 100644 index 0000000..ac4d6f4 --- /dev/null +++ b/local-lib5/man/man3/Text::Diff.3pm @@ -0,0 +1,446 @@ +.\" 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 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 +.PP +Barrie Slaymaker +.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.