-
-
11 Sep 2009 11:30:16 UTC
- Distribution: Text-Diff-Parser
- Module version: 0.1001
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (2)
- Testers (1510 / 0 / 0)
- Kwalitee
Bus factor: 1- 92.94% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (20.1KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors- Philip Gwyn <gwyn-at-cpan.org>
- Dependencies
- Test::More
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Text::Diff::Parser - Parse patch files containing unified and standard diffs
SYNOPSIS
use Text::Diff::Parser; # create the object my $parser = Text::Diff::Parser->new(); # With options $parser = Text::Diff::Parser->new( Simplify=>1, # simplify the diff Strip=>2 ); # strip 2 directories # Create object. Parse $file $parser = Text::Diff::Parser->new( $file ); $parser = Text::Diff::Parser->new( File=>$file ); # Create object. Parse text my $parser = Text::Diff::Parser->new( $text ); $parser = Text::Diff::Parser->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->text( $line ); } } # 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
Text::Diff::Parser
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 (theto-file
). Diffs are generaly 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 thatText::Diff::Parser
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
andsvn diff
so that isn't a problem.METHODS
new
$parser = Text::Diff::Parser->new; $parser = Text::Diff::Parser->new( $file ); $parser = Text::Diff::Parser->new( $handle ); $parser = Text::Diff::Parser->new( %params ); $parser = Text::Diff::Parser->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. - TrustAtAt
-
In a unified diff, various chunks are introduced with @@. By default, we trust these to reference the right line count. If you set this to 0, the lines will not be trust and a chunk must end with another @@ line or --- (which introduces a new file). Note that not trusting @@ means you can not parse a diff that removes a line that begins with --, because that also start with '---'.
- 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 sucess. Contents of the file may then be accessed withchanges
andfiles
.parse
$parser->parse( $string );
Parses the diff present in $string. Will
die
if it fails, returns true on sucess. Contents of the file may then be accessed withchanges
andfiles
.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
orto-file
).Elements of the returned array are change objects, as described in
CHANGE METHODS
below.simplify
$parser->simplify;
Simplifies the diff. Removes no-change lines. Combine line substitutions. Automatically called if you supply Simplify to ->new().
source
my $file = $parser->source
Returns the filename of the last file that was parsed. Returns "user filehandle" if you supplied a file handle.
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
$line = $ch->text( $N ); @lines = $ch->text;
Fetch the text of the line
$N
if present or all lines 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.
Module Install Instructions
To install Text::Diff::Parser, copy and paste the appropriate command in to your terminal.
cpanm Text::Diff::Parser
perl -MCPAN -e shell install Text::Diff::Parser
For more information on module installation, please visit the detailed CPAN module installation guide.