SVN::Web::DiffParser(3pm)				User Contributed Perl Documentation				 SVN::Web::DiffParser(3pm)

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

       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.

perl v5.14.2							    2012-06-11						 SVN::Web::DiffParser(3pm)