1Text::Diff::Parser(3) User Contributed Perl DocumentationText::Diff::Parser(3)
2
3
4

NAME

6       Text::Diff::Parser - Parse patch files containing unified and standard
7       diffs
8

SYNOPSIS

10           use Text::Diff::Parser;
11
12           # create the object
13           my $parser = Text::Diff::Parser->new();
14
15           # With options
16           $parser = Text::Diff::Parser->new( Simplify=>1, # simplify the diff
17                                              Strip=>2 );  # strip 2 directories
18
19           # Create object.  Parse $file
20           $parser = Text::Diff::Parser->new( $file );
21           $parser = Text::Diff::Parser->new( File=>$file );
22
23           # Create object.  Parse text
24           my $parser = Text::Diff::Parser->new( $text );
25           $parser = Text::Diff::Parser->new( Diff=>$text );
26
27           # parse a file
28           $parser->parse_file( $filename );
29
30           # parse a string
31           $parser->parse( $text );
32
33           # Remove no-change lines.  Combine line substitutions
34           $parser->simplify;
35
36           # 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
49           # In scalar context, returns the number of changes
50           my $n = $parser->changes;
51           print "There are $n changes",
52
53           # Get the changes to a given file
54           my @changes = $parser->changes( 'Makefile.PL' );
55
56           # Get list of files changed by the diff
57           my @files = $parser->files;
58

DESCRIPTION

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
64       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
71       "Text::Diff::Parser" currently parses unified diff format and standard
72       diff format.
73
74       Unified diffs look like the following.
75
76           --- 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
87       Standard diffs look like the following.
88
89           diff something something.4
90           3c3
91           < THREE
92           ---
93           > honk
94           4a5,6
95           > honk
96           > honk
97
98       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

METHODS

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
110       Object constructor.
111
112       Diff
113           String that contains a diff.  This diff will be parse before "new"
114           returns.
115
116       File
117           File name or file handle that is parsed before "new" returns.
118
119       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
125       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
130       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
138       Verbose
139           If true, print copious details of what is going on.
140
141   parse_file
142           $parser->parse_file( $file );
143           $parser->parse_file( $handle );
144
145       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
149   parse
150           $parser->parse( $string );
151
152       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
156   files
157           %files = $parser->files;
158
159       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
163   changes
164           @changes = $parser->changes;
165           $n = $parser->changes;
166           @changes = $parser->changes( $file );
167           $n = $parser->changes( $file );
168
169       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
173       Elements of the returned array are change objects, as described in
174       "CHANGE METHODS" below.
175
176   simplify
177           $parser->simplify;
178
179       Simplifies the diff.  Removes no-change lines.  Combine line
180       substitutions.  Automatically called if you supply Simplify to ->new().
181
182   source
183           my $file = $parser->source
184
185       Returns the filename of the last file that was parsed.  Returns "user
186       filehandle" if you supplied a file handle.
187

CHANGE METHODS

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
193   type
194       Returns the type of operation, either 'ADD', 'REMOVE', 'MODIFY' or ''
195       (null operation).
196
197   filename1
198       Filename of the "from-file".
199
200   filename2
201       Filename of the "to-file".
202
203   line1
204       Line in the "from-file" the operation starts at.
205
206   line2
207       Line in the "to-file" the operation starts at.
208
209   size
210       Number of lines affected by this operation.
211
212   text
213           $line  = $ch->text( $N );
214           @lines = $ch->text;
215
216       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

BUGS

223       I'm not 100% sure of standard diff handling.
224
225       Missing support for context diffs.
226

SEE ALSO

228       Text::Diff, Arch, diff.
229

AUTHOR

231       Philip Gwyn, <gwyn-at-cpan.org>
232
234       Copyright (C) 2006 by Philip Gwyn
235
236       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.
239
240
241
242perl v5.36.0                      2023-01-20             Text::Diff::Parser(3)
Impressum