--- name: "SVN::Web::DiffParser" section: "3pm" platform: "linux" package: "libsvn-web-perl" version: "0.63-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SVN::Web::DiffParser" --- # SVN::Web::DiffParser(3pm) Parse patch files containing unified and standard diffs ## 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, \ ## 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.