Provided by: libsvn-web-perl_0.63-2_all bug

NAME

       SVN::Web::DiffParser - Parse patch files containing unified and standard diffs

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 CPAN.

SYNOPSIS

           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( 'Makefile.PL' );

           # Get list of files changed by the diff
           my @files = $parser->files;

DESCRIPTION

       "SVN::Web::DiffParser" 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.

       A diff may be viewed a series of operations on a file, either adding, removing or
       modifying lines of one file (the "from-file") to produce another file (the "to-file").
       Diffs are generally produced either by hand with diff, or by your version control system
       ("cvs diff", "svn diff", ...).  Some diff formats, notably unified diffs, also contain
       null operations, that is lines that

       "SVN::Web::DiffParser" currently parses unified diff format and standard diff format.

       Unified diffs look like the following.

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

       Standard diffs look like the following.

           diff something something.4
           3c3
           < THREE
           ---
           > honk
           4a5,6
           > honk
           > honk

       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 "cvs diff" and "svn diff" so that isn't a problem.

METHODS

   new
           $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( \%params );

       Object constructor.

       Diff
           String that contains a diff.  This diff will be parse before "new" returns.

       File
           File name or file handle that is parsed before "new" returns.

       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.

       Strip
           Strip N leading directories from all filenames.  Less then useful for standard diffs
           produced by "cvs diff", because they don't contain directory information.

       Verbose
           If true, print copious details of what is going on.

   parse_file
           $parser->parse_file( $file );
           $parser->parse_file( $handle );

       Read and parse the file or file handle specified.  Will "die" if it fails, returns true on
       success.  Contents of the file may then be accessed with "changes" and "files".

   parse
           $parser->parse( $string );

       Parses the diff present in $string.  Will "die" if it fails, returns true on success.
       Contents of the file may then be accessed with "changes" and "files".

   files
           %files = $parser->files;

       Fetch a list of all the files that were referenced in the patch.  The keys are original
       files ("from-file") and the values are the modified files ("to-file").

   changes
           @changes = $parser->changes;
           $n = $parser->changes;
           @changes = $parser->changes( $file );
           $n = $parser->changes( $file );

       Return all the operations (array context) or the number of operations in the patch file.
       If $file is specified, only returns changes to that file ("from-file" or "to-file").

       Elements of the returned array are change objects, as described in "CHANGE METHODS" below.

CHANGE METHODS

       The "changes" method returns an array of objects that describe each operation.  You may
       use the following methods to find out details of the operation.

   type
       Returns the type of operation, either 'ADD', 'REMOVE', 'MODIFY' or '' (null operation).

   filename1
       Filename of the "from-file".

   filename2
       Filename of the "to-file".

   line1
       Line in the "from-file" the operation starts at.

   line2
       Line in the "to-file" the operation starts at.

   size
       Number of lines affected by this operation.

   text
           @lines = $ch->text;
           $line  = $ch->text( $N );

       Fetch the text of the line $N if present or all lines of affected by this operation.  For
       '' (null) and 'REMOVE' operations, these are the lines present before the operation was
       done ('from-file'.  For 'ADD' and 'MODIFY' operations, these are the lines present after
       the operation was done ('to-file'.

BUGS

       I'm not 100% sure of standard diff handling.

       Missing support for context diffs.

SEE ALSO

       Text::Diff, Arch, diff.

AUTHOR

       Philip Gwyn, <gwyn-at-cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2006 by Philip Gwyn

       Copyright (C) 2012 by Dean Hamstead

       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.