.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "SVN::Web::DiffParser 3pm"
.TH SVN::Web::DiffParser 3pm "2016-11-12" "perl v5.24.1" "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"
SVN::Web::DiffParser \- Parse patch files containing unified and standard diffs
.SH "NOTE"
.IX Header "NOTE"
This is Text::Diff::Parser, plus some local bug fixes that were exposed
by use with SVN::Web.  For more details about Text::Diff::Parser please
see \s-1CPAN.\s0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use SVN::Web::DiffParser;
\&
\&    # create the object
\&    my $parser = SVN::Web::DiffParser\->new();
\&
\&    # With options
\&    $parser = SVN::Web::DiffParser\->new( Simplify=>1, # simplify the diff
\&                                       Strip=>2 );  # strip 2 directories
\&
\&    # Create object.  Parse $file
\&    $parser = SVN::Web::DiffParser\->new( $file );
\&    $parser = SVN::Web::DiffParser\->new( File=>$file );
\&
\&    # Create object.  Parse text
\&    my $parser = SVN::Web::DiffParser\->new( $text );
\&    $parser = SVN::Web::DiffParser\->new( Diff=>$text );
\&
\&    # parse a file
\&    $parser\->parse_file( $filename );
\&
\&    # parse a string
\&    $parser\->parse( $text );
\&    
\&    # Remove no\-change lines.  Combine line substitutions
\&    $parser\->simplify;
\&
\&    # Find results
\&    foreach my $change ( $parser\->changes ) {
\&        print "File1: ", $change\->filename1;
\&        print "Line1: ", $change\->line1;
\&        print "File2: ", $change\->filename2;
\&        print "Line2: ", $change\->line2;
\&        print "Type: ", $change\->type;
\&        my $size = $change\->size;
\&        foreach my $line ( 0..($size\-1) ) {
\&            print "Line: ", $change\->line( $size );
\&        }
\&    }
\&
\&    # In scalar context, returns the number of changes
\&    my $n = $parser\->changes;
\&    print "There are $n changes", 
\&
\&    # Get the changes to a given file
\&    my @changes = $parser\->changes( \*(AqMakefile.PL\*(Aq );
\&
\&    # Get list of files changed by the diff
\&    my @files = $parser\->files;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`SVN::Web::DiffParser\*(C'\fR parses diff files and patches.  It allows you to
access the changes to a file in a standardized way, even if multiple patch
formats are used.
.PP
A diff may be viewed a series of operations on a file, either adding,
removing or modifying lines of one file (the \f(CW\*(C`from\-file\*(C'\fR) to produce
another file (the \f(CW\*(C`to\-file\*(C'\fR).  Diffs are generally produced either by hand
with diff, or by your version control system (\f(CW\*(C`cvs diff\*(C'\fR, \f(CW\*(C`svn diff\*(C'\fR,
\&...).  Some diff formats, notably unified diffs, also contain null
operations, that is lines that
.PP
\&\f(CW\*(C`SVN::Web::DiffParser\*(C'\fR currently parses unified diff format and standard diff
format.
.PP
Unified diffs look like the following.
.PP
.Vb 10
\&    \-\-\- Filename1 2006\-04\-12 18:47:22.000000000 \-0400
\&    +++ Filename2 2006\-04\-12 19:21:16.000000000 \-0400
\&    @@ \-1,4 +1,6 @@
\&     ONE
\&     TWO
\&    \-THREE
\&    +honk
\&     FOUR
\&    +honk
\&    +honk
.Ve
.PP
Standard diffs look like the following.
.PP
.Vb 8
\&    diff something something.4
\&    3c3
\&    < THREE
\&    \-\-\-
\&    > honk
\&    4a5,6
\&    > honk
\&    > honk
.Ve
.PP
The diff line isn't in fact part of the format but is necessary to find
which files the chunks deal with.  It is output by \f(CW\*(C`cvs diff\*(C'\fR and \f(CW\*(C`svn
diff\*(C'\fR so that isn't a problem.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 5
\&    $parser = SVN::Web::DiffParser\->new;
\&    $parser = SVN::Web::DiffParser\->new( $file );
\&    $parser = SVN::Web::DiffParser\->new( $handle );
\&    $parser = SVN::Web::DiffParser\->new( %params );
\&    $parser = SVN::Web::DiffParser\->new( \e%params );
.Ve
.PP
Object constructor.
.IP "Diff" 4
.IX Item "Diff"
String that contains a diff.  This diff will be parse before \f(CW\*(C`new\*(C'\fR returns.
.IP "File" 4
.IX Item "File"
File name or file handle that is parsed before \f(CW\*(C`new\*(C'\fR returns.
.IP "Simplify" 4
.IX Item "Simplify"
Simplifying a patch involves dropping all null-operations and converting and
remove operation followed by an add operation (or an add followed by a
remove) of the same size on the same lines into a modify operation.
.IP "Strip" 4
.IX Item "Strip"
Strip N leading directories from all filenames.  Less then useful for
standard diffs produced by \f(CW\*(C`cvs diff\*(C'\fR, because they don't contain directory
information.
.IP "Verbose" 4
.IX Item "Verbose"
If true, print copious details of what is going on.
.SS "parse_file"
.IX Subsection "parse_file"
.Vb 2
\&    $parser\->parse_file( $file );
\&    $parser\->parse_file( $handle );
.Ve
.PP
Read and parse the file or file handle specified.  Will \f(CW\*(C`die\*(C'\fR if it fails, 
returns true on success.  Contents of the file may then be accessed with
\&\f(CW\*(C`changes\*(C'\fR and \f(CW\*(C`files\*(C'\fR.
.SS "parse"
.IX Subsection "parse"
.Vb 1
\&    $parser\->parse( $string );
.Ve
.PP
Parses the diff present in \f(CW$string\fR.  Will \f(CW\*(C`die\*(C'\fR if it fails, returns true
on success.  Contents of the file may then be accessed with \f(CW\*(C`changes\*(C'\fR and
\&\f(CW\*(C`files\*(C'\fR.
.SS "files"
.IX Subsection "files"
.Vb 1
\&    %files = $parser\->files;
.Ve
.PP
Fetch a list of all the files that were referenced in the patch.  The keys
are original files (\f(CW\*(C`from\-file\*(C'\fR) and the values are the modified files
(\f(CW\*(C`to\-file\*(C'\fR).
.SS "changes"
.IX Subsection "changes"
.Vb 4
\&    @changes = $parser\->changes;
\&    $n = $parser\->changes;
\&    @changes = $parser\->changes( $file );
\&    $n = $parser\->changes( $file );
.Ve
.PP
Return all the operations (array context) or the number of operations in the
patch file.  If \f(CW$file\fR is specified, only returns changes to that file
(\f(CW\*(C`from\-file\*(C'\fR or \f(CW\*(C`to\-file\*(C'\fR).
.PP
Elements of the returned array are change objects, as described in 
\&\f(CW\*(C`CHANGE METHODS\*(C'\fR below.
.SH "CHANGE METHODS"
.IX Header "CHANGE METHODS"
The \f(CW\*(C`changes\*(C'\fR method returns an array of objects that describe each
operation.  You may use the following methods to find out details of the
operation.
.SS "type"
.IX Subsection "type"
Returns the type of operation, either \f(CW\*(AqADD\*(Aq\fR, \f(CW\*(AqREMOVE\*(Aq\fR, \f(CW\*(AqMODIFY\*(Aq\fR or
\&\f(CW\*(Aq\*(Aq\fR (null operation).
.SS "filename1"
.IX Subsection "filename1"
Filename of the \f(CW\*(C`from\-file\*(C'\fR.
.SS "filename2"
.IX Subsection "filename2"
Filename of the \f(CW\*(C`to\-file\*(C'\fR.
.SS "line1"
.IX Subsection "line1"
Line in the \f(CW\*(C`from\-file\*(C'\fR the operation starts at.
.SS "line2"
.IX Subsection "line2"
Line in the \f(CW\*(C`to\-file\*(C'\fR the operation starts at.
.SS "size"
.IX Subsection "size"
Number of lines affected by this operation.
.SS "text"
.IX Subsection "text"
.Vb 2
\&    @lines = $ch\->text;
\&    $line  = $ch\->text( $N );
.Ve
.PP
Fetch the text of the line \f(CW$N\fR if present or all lines of affected by this
operation.  For \f(CW\*(Aq\*(Aq\fR (null) and \f(CW\*(AqREMOVE\*(Aq\fR operations, these are the lines
present before the operation was done (\f(CW\*(Aqfrom\-file\*(Aq\fR.  For \f(CW\*(AqADD\*(Aq\fR and
\&\f(CW\*(AqMODIFY\*(Aq\fR operations, these are the lines present after the operation was
done (\f(CW\*(Aqto\-file\*(Aq\fR.
.SH "BUGS"
.IX Header "BUGS"
I'm not 100% sure of standard diff handling.
.PP
Missing support for context diffs.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::Diff, Arch, diff.
.SH "AUTHOR"
.IX Header "AUTHOR"
Philip Gwyn, <gwyn\-at\-cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Philip Gwyn
.PP
Copyright (C) 2012 by Dean Hamstead
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.