1Text::Diff::Parser(3) User Contributed Perl DocumentationText::Diff::Parser(3)
2
6 Text::Diff::Parser - Parse patch files containing unified and standard
7 diffs
8
10 use Text::Diff::Parser;
11 # create the object
13 my $parser = Text::Diff::Parser->new();
14 # With options
16 $parser = Text::Diff::Parser->new( Simplify=>1, # simplify the diff
17 Strip=>2 ); # strip 2 directories
18 # Create object. Parse $file
20 $parser = Text::Diff::Parser->new( $file );
21 $parser = Text::Diff::Parser->new( File=>$file );
22 # Create object. Parse text
24 my $parser = Text::Diff::Parser->new( $text );
25 $parser = Text::Diff::Parser->new( Diff=>$text );
26 # parse a file
28 $parser->parse_file( $filename );
29 # parse a string
31 $parser->parse( $text );
32 # Remove no-change lines. Combine line substitutions
34 $parser->simplify;
35 # Find results
37 foreach my $change ( $parser->changes ) {
38 print "File1: ", $change->filename1;
39 print "Line1: ", $change->line1;
40 print "File2: ", $change->filename2;
41 print "Line2: ", $change->line2;
42 print "Type: ", $change->type;
43 my $size = $change->size;
44 foreach my $line ( 0..($size-1) ) {
45 print "Line: ", $change->text( $line );
46 }
47 }
48 # In scalar context, returns the number of changes
50 my $n = $parser->changes;
51 print "There are $n changes",
52 # Get the changes to a given file
54 my @changes = $parser->changes( 'Makefile.PL' );
55 # Get list of files changed by the diff
57 my @files = $parser->files;
58
60 "Text::Diff::Parser" parses diff files and patches. It allows you to
61 access the changes to a file in a standardized way, even if multiple
62 patch formats are used.
63 A diff may be viewed a series of operations on a file, either adding,
65 removing or modifying lines of one file (the "from-file") to produce
66 another file (the "to-file"). Diffs are generaly produced either by
67 hand with diff, or by your version control system ("cvs diff", "svn
68 diff", ...). Some diff formats, notably unified diffs, also contain
69 null operations, that is lines that
70 "Text::Diff::Parser" currently parses unified diff format and standard
72 diff format.
73 Unified diffs look like the following.
75 --- Filename1 2006-04-12 18:47:22.000000000 -0400
77 +++ Filename2 2006-04-12 19:21:16.000000000 -0400
78 @@ -1,4 +1,6 @@
79 ONE
80 TWO
81 -THREE
82 +honk
83 FOUR
84 +honk
85 +honk
86 Standard diffs look like the following.
88 diff something something.4
90 3c3
91 < THREE
92 ---
93 > honk
94 4a5,6
95 > honk
96 > honk
97 The diff line isn't in fact part of the format but is necessary to find
99 which files the chunks deal with. It is output by "cvs diff" and "svn
100 diff" so that isn't a problem.
101
103 new
104 $parser = Text::Diff::Parser->new;
105 $parser = Text::Diff::Parser->new( $file );
106 $parser = Text::Diff::Parser->new( $handle );
107 $parser = Text::Diff::Parser->new( %params );
108 $parser = Text::Diff::Parser->new( \%params );
109 Object constructor.
111 Diff
113 String that contains a diff. This diff will be parse before "new"
114 returns.
115 File
117 File name or file handle that is parsed before "new" returns.
118 Simplify
120 Simplifying a patch involves dropping all null-operations and
121 converting and remove operation followed by an add operation (or an
122 add followed by a remove) of the same size on the same lines into a
123 modify operation.
124 Strip
126 Strip N leading directories from all filenames. Less then useful
127 for standard diffs produced by "cvs diff", because they don't
128 contain directory information.
129 TrustAtAt
131 In a unified diff, various chunks are introduced with @@. By
132 default, we trust these to reference the right line count. If you
133 set this to 0, the lines will not be trust and a chunk must end
134 with another @@ line or --- (which introduces a new file). Note
135 that not trusting @@ means you can not parse a diff that removes a
136 line that begins with --, because that also start with '---'.
137 Verbose
139 If true, print copious details of what is going on.
140 parse_file
142 $parser->parse_file( $file );
143 $parser->parse_file( $handle );
144 Read and parse the file or file handle specified. Will "die" if it
146 fails, returns true on sucess. Contents of the file may then be
147 accessed with "changes" and "files".
148 parse
150 $parser->parse( $string );
151 Parses the diff present in $string. Will "die" if it fails, returns
153 true on sucess. Contents of the file may then be accessed with
154 "changes" and "files".
155 files
157 %files = $parser->files;
158 Fetch a list of all the files that were referenced in the patch. The
160 keys are original files ("from-file") and the values are the modified
161 files ("to-file").
162 changes
164 @changes = $parser->changes;
165 $n = $parser->changes;
166 @changes = $parser->changes( $file );
167 $n = $parser->changes( $file );
168 Return all the operations (array context) or the number of operations
170 in the patch file. If $file is specified, only returns changes to that
171 file ("from-file" or "to-file").
172 Elements of the returned array are change objects, as described in
174 "CHANGE METHODS" below.
175 simplify
177 $parser->simplify;
178 Simplifies the diff. Removes no-change lines. Combine line
180 substitutions. Automatically called if you supply Simplify to ->new().
181 source
183 my $file = $parser->source
184 Returns the filename of the last file that was parsed. Returns "user
186 filehandle" if you supplied a file handle.
187
189 The "changes" method returns an array of objects that describe each
190 operation. You may use the following methods to find out details of
191 the operation.
192 type
194 Returns the type of operation, either 'ADD', 'REMOVE', 'MODIFY' or ''
195 (null operation).
196 filename1
198 Filename of the "from-file".
199 filename2
201 Filename of the "to-file".
202 line1
204 Line in the "from-file" the operation starts at.
205 line2
207 Line in the "to-file" the operation starts at.
208 size
210 Number of lines affected by this operation.
211 text
213 $line = $ch->text( $N );
214 @lines = $ch->text;
215 Fetch the text of the line $N if present or all lines affected by this
217 operation. For '' (null) and 'REMOVE' operations, these are the lines
218 present before the operation was done ('from-file'. For 'ADD' and
219 'MODIFY' operations, these are the lines present after the operation
220 was done ('to-file'.
221
223 I'm not 100% sure of standard diff handling.
224 Missing support for context diffs.
226
228 Text::Diff, Arch, diff.
229
231 Philip Gwyn, <gwyn-at-cpan.org>
232
234 Copyright (C) 2006 by Philip Gwyn
235 This library is free software; you can redistribute it and/or modify it
237 under the same terms as Perl itself, either Perl version 5.8.8 or, at
238 your option, any later version of Perl 5 you may have available.
239perl v5.36.0 2023-01-20 Text::Diff::Parser(3)