Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_diff.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_diff.h
24  * @brief Contextual diffing.
25  *
26  * This is an internalized library for performing contextual diffs
27  * between sources of data.
28  *
29  * @note This is different than Subversion's binary-diffing engine.
30  * That API lives in @c svn_delta.h -- see the "text deltas" section. A
31  * "text delta" is way of representing precise binary diffs between
32  * strings of data. The Subversion client and server send text deltas
33  * to one another during updates and commits.
34  *
35  * This API, however, is (or will be) used for performing *contextual*
36  * merges between files in the working copy. During an update or
37  * merge, 3-way file merging is needed. And 'svn diff' needs to show
38  * the differences between 2 files.
39  *
40  * The nice thing about this API is that it's very general. It
41  * operates on any source of data (a "datasource") and calculates
42  * contextual differences on "tokens" within the data. In our
43  * particular usage, the datasources are files and the tokens are
44  * lines. But the possibilities are endless.
45  */
46 
47 
48 #ifndef SVN_DIFF_H
49 #define SVN_DIFF_H
50 
51 #include <apr.h>
52 #include <apr_pools.h>
53 #include <apr_tables.h> /* for apr_array_header_t */
54 
55 #include "svn_types.h"
56 #include "svn_io.h" /* for svn_stream_t */
57 #include "svn_string.h"
58 #include "svn_mergeinfo.h"
59 
60 #ifdef __cplusplus
61 extern "C" {
62 #endif /* __cplusplus */
63 
64 
65 
66 /**
67  * Get libsvn_diff version information.
68  *
69  * @since New in 1.1.
70  */
71 const svn_version_t *
72 svn_diff_version(void);
73 
74 
75 /* Diffs. */
76 
77 /** An opaque type that represents a difference between either two or
78  * three datasources. This object is returned by svn_diff_diff(),
79  * svn_diff_diff3() and svn_diff_diff4(), and consumed by a number of
80  * other routines.
81  */
82 typedef struct svn_diff_t svn_diff_t;
83 
84 /**
85  * There are four types of datasources. In GNU diff3 terminology,
86  * the first three types correspond to the phrases "older", "mine",
87  * and "yours".
88  */
90 {
91  /** The oldest form of the data. */
93 
94  /** The same data, but potentially changed by the user. */
96 
97  /** The latest version of the data, possibly different than the
98  * user's modified version.
99  */
101 
102  /** The common ancestor of original and modified. */
104 
106 
107 
108 /** A vtable for reading data from the three datasources.
109  * @since New in 1.7. */
110 typedef struct svn_diff_fns2_t
111 {
112  /** Open the datasources of type @a datasources. */
113  svn_error_t *(*datasources_open)(void *diff_baton,
114  apr_off_t *prefix_lines,
115  apr_off_t *suffix_lines,
116  const svn_diff_datasource_e *datasources,
117  apr_size_t datasources_len);
118 
119  /** Close the datasource of type @a datasource. */
120  svn_error_t *(*datasource_close)(void *diff_baton,
121  svn_diff_datasource_e datasource);
122 
123  /** Get the next "token" from the datasource of type @a datasource.
124  * Return a "token" in @a *token. Return a hash of "token" in @a *hash.
125  * Leave @a token and @a hash untouched when the datasource is exhausted.
126  */
127  svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token,
128  void *diff_baton,
129  svn_diff_datasource_e datasource);
130 
131  /** A function for ordering the tokens, resembling 'strcmp' in functionality.
132  * @a compare should contain the return value of the comparison:
133  * If @a ltoken and @a rtoken are "equal", return 0. If @a ltoken is
134  * "less than" @a rtoken, return a number < 0. If @a ltoken is
135  * "greater than" @a rtoken, return a number > 0.
136  */
137  svn_error_t *(*token_compare)(void *diff_baton,
138  void *ltoken,
139  void *rtoken,
140  int *compare);
141 
142  /** Free @a token from memory, the diff algorithm is done with it. */
143  void (*token_discard)(void *diff_baton,
144  void *token);
145 
146  /** Free *all* tokens from memory, they're no longer needed. */
147  void (*token_discard_all)(void *diff_baton);
149 
150 
151 /** Like #svn_diff_fns2_t except with datasource_open() instead of
152  * datasources_open().
153  *
154  * @deprecated Provided for backward compatibility with the 1.6 API.
155  */
156 typedef struct svn_diff_fns_t
157 {
158  svn_error_t *(*datasource_open)(void *diff_baton,
159  svn_diff_datasource_e datasource);
160 
161  svn_error_t *(*datasource_close)(void *diff_baton,
162  svn_diff_datasource_e datasource);
163 
164  svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token,
165  void *diff_baton,
166  svn_diff_datasource_e datasource);
167 
168  svn_error_t *(*token_compare)(void *diff_baton,
169  void *ltoken,
170  void *rtoken,
171  int *compare);
172 
173  void (*token_discard)(void *diff_baton,
174  void *token);
175 
176  void (*token_discard_all)(void *diff_baton);
178 
179 
180 /* The Main Events */
181 
182 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
183  * return a diff object in @a *diff that represents a difference between
184  * an "original" and "modified" datasource. Do all allocation in @a pool.
185  *
186  * @since New in 1.7.
187  */
188 svn_error_t *
190  void *diff_baton,
191  const svn_diff_fns2_t *diff_fns,
192  apr_pool_t *pool);
193 
194 /** Like svn_diff_diff_2() but using #svn_diff_fns_t instead of
195  * #svn_diff_fns2_t.
196  *
197  * @deprecated Provided for backward compatibility with the 1.6 API.
198  */
200 svn_error_t *
202  void *diff_baton,
203  const svn_diff_fns_t *diff_fns,
204  apr_pool_t *pool);
205 
206 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
207  * return a diff object in @a *diff that represents a difference between
208  * three datasources: "original", "modified", and "latest". Do all
209  * allocation in @a pool.
210  *
211  * @since New in 1.7.
212  */
213 svn_error_t *
215  void *diff_baton,
216  const svn_diff_fns2_t *diff_fns,
217  apr_pool_t *pool);
218 
219 /** Like svn_diff_diff3_2() but using #svn_diff_fns_t instead of
220  * #svn_diff_fns2_t.
221  *
222  * @deprecated Provided for backward compatibility with the 1.6 API.
223  */
225 svn_error_t *
227  void *diff_baton,
228  const svn_diff_fns_t *diff_fns,
229  apr_pool_t *pool);
230 
231 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
232  * return a diff object in @a *diff that represents a difference between
233  * two datasources: "original" and "latest", adjusted to become a full
234  * difference between "original", "modified" and "latest" using "ancestor".
235  * Do all allocation in @a pool.
236  *
237  * @since New in 1.7.
238  */
239 svn_error_t *
241  void *diff_baton,
242  const svn_diff_fns2_t *diff_fns,
243  apr_pool_t *pool);
244 
245 /** Like svn_diff_diff4_2() but using #svn_diff_fns_t instead of
246  * #svn_diff_fns2_t.
247  *
248  * @deprecated Provided for backward compatibility with the 1.6 API.
249  */
251 svn_error_t *
253  void *diff_baton,
254  const svn_diff_fns_t *diff_fns,
255  apr_pool_t *pool);
256 
257 
258 /* Utility functions */
259 
260 /** Determine if a diff object contains conflicts. If it does, return
261  * @c TRUE, else return @c FALSE.
262  */
265 
266 
267 /** Determine if a diff object contains actual differences between the
268  * datasources. If so, return @c TRUE, else return @c FALSE.
269  */
272 
273 
274 
275 
276 /* Displaying Diffs */
277 
278 /** A vtable for displaying (or consuming) differences between datasources.
279  *
280  * Differences, similarities, and conflicts are described by lining up
281  * "ranges" of data.
282  *
283  * Any of the function pointers in this vtable may be NULL to ignore the
284  * corresponding kinds of output.
285  *
286  * @note These callbacks describe data ranges in units of "tokens".
287  * A "token" is whatever you've defined it to be in your datasource
288  * @c svn_diff_fns_t vtable.
289  */
290 typedef struct svn_diff_output_fns_t
291 {
292  /* Two-way and three-way diffs both call the first two output functions: */
293 
294  /**
295  * If doing a two-way diff, then an *identical* data range was found
296  * between the "original" and "modified" datasources. Specifically,
297  * the match starts at @a original_start and goes for @a original_length
298  * tokens in the original data, and at @a modified_start for
299  * @a modified_length tokens in the modified data.
300  *
301  * If doing a three-way diff, then all three datasources have
302  * matching data ranges. The range @a latest_start, @a latest_length in
303  * the "latest" datasource is identical to the range @a original_start,
304  * @a original_length in the original data, and is also identical to
305  * the range @a modified_start, @a modified_length in the modified data.
306  */
307  svn_error_t *(*output_common)(void *output_baton,
308  apr_off_t original_start,
309  apr_off_t original_length,
310  apr_off_t modified_start,
311  apr_off_t modified_length,
312  apr_off_t latest_start,
313  apr_off_t latest_length);
314 
315  /**
316  * If doing a two-way diff, then an *conflicting* data range was found
317  * between the "original" and "modified" datasources. Specifically,
318  * the conflict starts at @a original_start and goes for @a original_length
319  * tokens in the original data, and at @a modified_start for
320  * @a modified_length tokens in the modified data.
321  *
322  * If doing a three-way diff, then an identical data range was discovered
323  * between the "original" and "latest" datasources, but this conflicts with
324  * a range in the "modified" datasource.
325  */
326  svn_error_t *(*output_diff_modified)(void *output_baton,
327  apr_off_t original_start,
328  apr_off_t original_length,
329  apr_off_t modified_start,
330  apr_off_t modified_length,
331  apr_off_t latest_start,
332  apr_off_t latest_length);
333 
334  /* ------ The following callbacks are used by three-way diffs only --- */
335 
336  /** An identical data range was discovered between the "original" and
337  * "modified" datasources, but this conflicts with a range in the
338  * "latest" datasource.
339  */
340  svn_error_t *(*output_diff_latest)(void *output_baton,
341  apr_off_t original_start,
342  apr_off_t original_length,
343  apr_off_t modified_start,
344  apr_off_t modified_length,
345  apr_off_t latest_start,
346  apr_off_t latest_length);
347 
348  /** An identical data range was discovered between the "modified" and
349  * "latest" datasources, but this conflicts with a range in the
350  * "original" datasource.
351  */
352  svn_error_t *(*output_diff_common)(void *output_baton,
353  apr_off_t original_start,
354  apr_off_t original_length,
355  apr_off_t modified_start,
356  apr_off_t modified_length,
357  apr_off_t latest_start,
358  apr_off_t latest_length);
359 
360  /** All three datasources have conflicting data ranges. The range
361  * @a latest_start, @a latest_length in the "latest" datasource conflicts
362  * with the range @a original_start, @a original_length in the "original"
363  * datasource, and also conflicts with the range @a modified_start,
364  * @a modified_length in the "modified" datasource.
365  * If there are common ranges in the "modified" and "latest" datasources
366  * in this conflicting range, @a resolved_diff will contain a diff
367  * which can be used to retrieve the common and conflicting ranges.
368  */
369  svn_error_t *(*output_conflict)(void *output_baton,
370  apr_off_t original_start,
371  apr_off_t original_length,
372  apr_off_t modified_start,
373  apr_off_t modified_length,
374  apr_off_t latest_start,
375  apr_off_t latest_length,
376  svn_diff_t *resolved_diff);
378 
379 /** Style for displaying conflicts during diff3 output.
380  *
381  * @since New in 1.6.
382  */
384 {
385  /** Display modified and latest, with conflict markers. */
387 
388  /** Like svn_diff_conflict_display_modified_latest, but with an
389  extra effort to identify common sequences between modified and
390  latest. */
392 
393  /** Display modified, original, and latest, with conflict
394  markers. */
396 
397  /** Just display modified, with no markers. */
399 
400  /** Just display latest, with no markers. */
402 
403  /** Like svn_diff_conflict_display_modified_original_latest, but
404  *only* showing conflicts. */
406 
407  /* IMPORTANT: If you extend this enum note that it is mapped in
408  tools/diff/diff3.c. */
410 
411 
412 /** Given a vtable of @a output_fns/@a output_baton for consuming
413  * differences, output the differences in @a diff.
414  *
415  * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
416  * times while processing larger diffs.
417  *
418  * @since New in 1.9.
419  */
420 svn_error_t *
422  void *output_baton,
423  const svn_diff_output_fns_t *output_fns,
424  svn_cancel_func_t cancel_func,
425  void *cancel_baton);
426 
427 /** Similar to svn_diff_output2(), but without cancel support.
428  *
429  * @deprecated Provided for backwards compatibility with the 1.8 API.
430  */
432 svn_error_t *
434  void *output_baton,
435  const svn_diff_output_fns_t *output_fns);
436 
437 
438 
439 /* Diffs on files */
440 
441 /** To what extent whitespace should be ignored when comparing lines.
442  *
443  * @since New in 1.4.
444  */
446 {
447  /** Ignore no whitespace. */
449 
450  /** Ignore changes in sequences of whitespace characters, treating each
451  * sequence of whitespace characters as a single space. */
453 
454  /** Ignore all whitespace characters. */
457 
458 /** Options to control the behaviour of the file diff routines.
459  *
460  * @since New in 1.4.
461  *
462  * @note This structure may be extended in the future, so to preserve binary
463  * compatibility, users must not allocate structs of this type themselves.
464  * @see svn_diff_file_options_create().
465  *
466  * @note Although its name suggests otherwise, this structure is used to
467  * pass options to file as well as in-memory diff functions.
468  */
470 {
471  /** To what extent whitespace should be ignored when comparing lines.
472  * The default is @c svn_diff_file_ignore_space_none. */
474  /** Whether to treat all end-of-line markers the same when comparing lines.
475  * The default is @c FALSE. */
477  /** Whether the "@@" lines of the unified diff output should include a prefix
478  * of the nearest preceding line that starts with a character that might be
479  * the initial character of a C language identifier. The default is
480  * @c FALSE.
481  * @since New in 1.5.
482  */
484 
485  /** The number of context lines produced above and below modifications, if
486  * available. The number of context lines must be >= 0.
487  *
488  * @since New in 1.9 */
491 
492 /** Allocate a @c svn_diff_file_options_t structure in @a pool, initializing
493  * it with default values.
494  *
495  * @since New in 1.4.
496  */
498 svn_diff_file_options_create(apr_pool_t *pool);
499 
500 /**
501  * Parse @a args, an array of <tt>const char *</tt> command line switches
502  * and adjust @a options accordingly. @a options is assumed to be initialized
503  * with default values. @a pool is used for temporary allocation.
504  *
505  * @since New in 1.4.
506  *
507  * The following options are supported:
508  * - --ignore-space-change, -b
509  * - --ignore-all-space, -w
510  * - --ignore-eol-style
511  * - --show-c-function, -p @since New in 1.5.
512  * - --context, -U ARG @since New in 1.9.
513  * - --unified, -u (for compatibility, does nothing).
514  */
515 svn_error_t *
517  const apr_array_header_t *args,
518  apr_pool_t *pool);
519 
520 
521 /** A convenience function to produce a diff between two files.
522  *
523  * @since New in 1.4.
524  *
525  * Return a diff object in @a *diff (allocated from @a pool) that represents
526  * the difference between an @a original file and @a modified file.
527  * (The file arguments must be full paths to the files.)
528  *
529  * Compare lines according to the relevant fields of @a options.
530  */
531 svn_error_t *
533  const char *original,
534  const char *modified,
535  const svn_diff_file_options_t *options,
536  apr_pool_t *pool);
537 
538 /** Similar to svn_file_diff_2(), but with @a options set to a struct with
539  * default options.
540  *
541  * @deprecated Provided for backwards compatibility with the 1.3 API.
542  */
544 svn_error_t *
546  const char *original,
547  const char *modified,
548  apr_pool_t *pool);
549 
550 /** A convenience function to produce a diff between three files.
551  *
552  * @since New in 1.4.
553  *
554  * Return a diff object in @a *diff (allocated from @a pool) that represents
555  * the difference between an @a original file, @a modified file, and @a latest
556  * file.
557  *
558  * Compare lines according to the relevant fields of @a options.
559  */
560 svn_error_t *
562  const char *original,
563  const char *modified,
564  const char *latest,
565  const svn_diff_file_options_t *options,
566  apr_pool_t *pool);
567 
568 /** Similar to svn_diff_file_diff3_2(), but with @a options set to a struct
569  * with default options.
570  *
571  * @deprecated Provided for backwards compatibility with the 1.3 API.
572  */
574 svn_error_t *
576  const char *original,
577  const char *modified,
578  const char *latest,
579  apr_pool_t *pool);
580 
581 /** A convenience function to produce a diff between four files.
582  *
583  * @since New in 1.4.
584  *
585  * Return a diff object in @a *diff (allocated from @a pool) that represents
586  * the difference between an @a original file, @a modified file, @a latest
587  * and @a ancestor file. (The file arguments must be full paths to the files.)
588  *
589  * Compare lines according to the relevant fields of @a options.
590  */
591 svn_error_t *
593  const char *original,
594  const char *modified,
595  const char *latest,
596  const char *ancestor,
597  const svn_diff_file_options_t *options,
598  apr_pool_t *pool);
599 
600 /** Similar to svn_file_diff4_2(), but with @a options set to a struct with
601  * default options.
602  *
603  * @deprecated Provided for backwards compatibility with the 1.3 API.
604  */
606 svn_error_t *
608  const char *original,
609  const char *modified,
610  const char *latest,
611  const char *ancestor,
612  apr_pool_t *pool);
613 
614 /** A convenience function to produce unified diff output from the
615  * diff generated by svn_diff_file_diff().
616  *
617  * Output a @a diff between @a original_path and @a modified_path in unified
618  * context diff format to @a output_stream. Optionally supply
619  * @a original_header and/or @a modified_header to be displayed in the header
620  * of the output. If @a original_header or @a modified_header is @c NULL, a
621  * default header will be displayed, consisting of path and last modified time.
622  * Output all headers and markers in @a header_encoding. If @a relative_to_dir
623  * is not @c NULL, the @a original_path and @a modified_path will have the
624  * @a relative_to_dir stripped from the front of the respective paths. If
625  * @a relative_to_dir is @c NULL, paths will be not be modified. If
626  * @a relative_to_dir is not @c NULL but @a relative_to_dir is not a parent
627  * path of the target, an error is returned. Finally, if @a relative_to_dir
628  * is a URL, an error will be returned.
629  *
630  * If @a context_size is not negative, then this number of context lines
631  * will be used in the generated diff output. Otherwise the legacy compile
632  * time default will be used.
633  *
634  * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
635  * times while processing larger diffs.
636  *
637  * @since New in 1.9.
638  */
639 svn_error_t *
641  svn_diff_t *diff,
642  const char *original_path,
643  const char *modified_path,
644  const char *original_header,
645  const char *modified_header,
646  const char *header_encoding,
647  const char *relative_to_dir,
648  svn_boolean_t show_c_function,
649  int context_size,
650  svn_cancel_func_t cancel_func,
651  void *cancel_baton,
652  apr_pool_t *scratch_pool);
653 
654 /** Similar to svn_diff_file_output_unified4(), but without cancel
655  * support and with @a context_size set to -1.
656  *
657  * @since New in 1.5.
658  * @deprecated Provided for backwards compatibility with the 1.8 API.
659  */
661 svn_error_t *
663  svn_diff_t *diff,
664  const char *original_path,
665  const char *modified_path,
666  const char *original_header,
667  const char *modified_header,
668  const char *header_encoding,
669  const char *relative_to_dir,
670  svn_boolean_t show_c_function,
671  apr_pool_t *pool);
672 
673 /** Similar to svn_diff_file_output_unified3(), but with @a relative_to_dir
674  * set to NULL and @a show_c_function to false.
675  *
676  * @deprecated Provided for backwards compatibility with the 1.4 API.
677  */
679 svn_error_t *
681  svn_diff_t *diff,
682  const char *original_path,
683  const char *modified_path,
684  const char *original_header,
685  const char *modified_header,
686  const char *header_encoding,
687  apr_pool_t *pool);
688 
689 /** Similar to svn_diff_file_output_unified2(), but with @a header_encoding
690  * set to @c APR_LOCALE_CHARSET.
691  *
692  * @deprecated Provided for backward compatibility with the 1.2 API.
693  */
695 svn_error_t *
697  svn_diff_t *diff,
698  const char *original_path,
699  const char *modified_path,
700  const char *original_header,
701  const char *modified_header,
702  apr_pool_t *pool);
703 
704 
705 /** A convenience function to produce diff3 output from the
706  * diff generated by svn_diff_file_diff3().
707  *
708  * Output a @a diff between @a original_path, @a modified_path and
709  * @a latest_path in merged format to @a output_stream. Optionally supply
710  * @a conflict_modified, @a conflict_original, @a conflict_separator and/or
711  * @a conflict_latest to be displayed as conflict markers in the output.
712  * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or
713  * @a conflict_separator is @c NULL, a default marker will be displayed.
714  * @a conflict_style dictates how conflicts are displayed.
715  * Uses @a scratch_pool for temporary allocations.
716  *
717  * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
718  * times while processing larger diffs.
719  *
720  * @since New in 1.9.
721  */
722 svn_error_t *
724  svn_diff_t *diff,
725  const char *original_path,
726  const char *modified_path,
727  const char *latest_path,
728  const char *conflict_original,
729  const char *conflict_modified,
730  const char *conflict_latest,
731  const char *conflict_separator,
732  svn_diff_conflict_display_style_t conflict_style,
733  svn_cancel_func_t cancel_func,
734  void *cancel_baton,
735  apr_pool_t *scratch_pool);
736 
737 /** Similar to svn_diff_file_output_merge3, but without cancel support.
738  *
739  * @since New in 1.6.
740  *
741  * @deprecated Provided for backward compatibility with the 1.8 API.
742  */
744 svn_error_t *
746  svn_diff_t *diff,
747  const char *original_path,
748  const char *modified_path,
749  const char *latest_path,
750  const char *conflict_original,
751  const char *conflict_modified,
752  const char *conflict_latest,
753  const char *conflict_separator,
754  svn_diff_conflict_display_style_t conflict_style,
755  apr_pool_t *pool);
756 
757 
758 /** Similar to svn_diff_file_output_merge2, but with @a
759  * display_original_in_conflict and @a display_resolved_conflicts
760  * booleans instead of the @a conflict_style enum.
761  *
762  * If both booleans are false, acts like
763  * svn_diff_conflict_display_modified_latest; if @a
764  * display_original_in_conflict is true, acts like
765  * svn_diff_conflict_display_modified_original_latest; if @a
766  * display_resolved_conflicts is true, acts like
767  * svn_diff_conflict_display_resolved_modified_latest. The booleans
768  * may not both be true.
769  *
770  * @deprecated Provided for backward compatibility with the 1.5 API.
771  */
773 svn_error_t *
775  svn_diff_t *diff,
776  const char *original_path,
777  const char *modified_path,
778  const char *latest_path,
779  const char *conflict_original,
780  const char *conflict_modified,
781  const char *conflict_latest,
782  const char *conflict_separator,
783  svn_boolean_t display_original_in_conflict,
784  svn_boolean_t display_resolved_conflicts,
785  apr_pool_t *pool);
786 
787 /** Creates a git-like binary diff hunk describing the differences between
788  * @a original and @a latest. It does this by either producing either the
789  * literal content of both versions in a compressed format, or by describing
790  * one way transforms.
791  *
792  * Either @a original or @a latest may be NULL to describe that the version
793  * didn't exist.
794  *
795  * Writes the output to @a output_stream.
796  *
797  * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
798  * times while processing larger diffs.
799  *
800  * @since New in 1.9.
801  */
802 svn_error_t *
803 svn_diff_output_binary(svn_stream_t *output_stream,
804  svn_stream_t *original,
805  svn_stream_t *latest,
806  svn_cancel_func_t cancel_func,
807  void *cancel_baton,
808  apr_pool_t *scratch_pool);
809 
810 /* Diffs on in-memory structures */
811 
812 /** Generate @a diff output from the @a original and @a modified
813  * in-memory strings. @a diff will be allocated from @a pool.
814  *
815  * @since New in 1.5.
816  */
817 svn_error_t *
819  const svn_string_t *original,
820  const svn_string_t *modified,
821  const svn_diff_file_options_t *options,
822  apr_pool_t *pool);
823 
824 
825 /** Generate @a diff output from the @a original, @a modified and @a latest
826  * in-memory strings. @a diff will be allocated in @a pool.
827  *
828  * @since New in 1.5.
829  */
830 svn_error_t *
832  const svn_string_t *original,
833  const svn_string_t *modified,
834  const svn_string_t *latest,
835  const svn_diff_file_options_t *options,
836  apr_pool_t *pool);
837 
838 
839 /** Generate @a diff output from the @a original, @a modified and @a latest
840  * in-memory strings, using @a ancestor. @a diff will be allocated in @a pool.
841  *
842  * @since New in 1.5.
843  */
844 svn_error_t *
846  const svn_string_t *original,
847  const svn_string_t *modified,
848  const svn_string_t *latest,
849  const svn_string_t *ancestor,
850  const svn_diff_file_options_t *options,
851  apr_pool_t *pool);
852 
853 /** Outputs the @a diff object generated by svn_diff_mem_string_diff()
854  * in unified diff format on @a output_stream, using @a original
855  * and @a modified for the text in the output.
856  *
857  * If @a with_diff_header is TRUE, write a diff header ("---" and "+++"
858  * lines), using @a original_header and @a modified_header to fill the field
859  * after the "---" and "+++" markers; otherwise @a original_header and
860  * @a modified_header are ignored and may be NULL.
861  *
862  * Outputs the header and hunk delimiters in @a header_encoding.
863  * A @a hunk_delimiter can optionally be specified.
864  * If @a hunk_delimiter is NULL, use the default hunk delimiter "@@".
865  *
866  * As a special case, if the hunk delimiter is "##", then for an incomplete
867  * final line use the text "\ No newline at end of property" instead of
868  * "\ No newline at end of file".
869  *
870  * If @a context_size is not negative, then this number of context lines
871  * will be used in the generated diff output. Otherwise the legacy compile
872  * time default will be used.
873  *
874  * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
875  * times while processing larger diffs.
876  *
877  * Uses @a scratch_pool for temporary allocations.
878  *
879  * @since New in 1.9
880  */
881 svn_error_t *
883  svn_diff_t *diff,
884  svn_boolean_t with_diff_header,
885  const char *hunk_delimiter,
886  const char *original_header,
887  const char *modified_header,
888  const char *header_encoding,
889  const svn_string_t *original,
890  const svn_string_t *modified,
891  int context_size,
892  svn_cancel_func_t cancel_func,
893  void *cancel_baton,
894  apr_pool_t *scratch_pool);
895 
896 /** Similar to svn_diff_mem_string_output_unified3() but without
897  * cancel support and with @a context_size set to -1.
898  *
899  * @since New in 1.7. Hunk delimiter "##" has the special meaning since 1.8.
900  *
901  * @deprecated Provided for backwards compatibility with the 1.8 API.
902  */
904 svn_error_t *
906  svn_diff_t *diff,
907  svn_boolean_t with_diff_header,
908  const char *hunk_delimiter,
909  const char *original_header,
910  const char *modified_header,
911  const char *header_encoding,
912  const svn_string_t *original,
913  const svn_string_t *modified,
914  apr_pool_t *pool);
915 
916 /** Similar to svn_diff_mem_string_output_unified2() but with
917  * @a with_diff_header always set to TRUE and @a hunk_delimiter always
918  * set to NULL.
919  *
920  * @since New in 1.5.
921  *
922  * @deprecated Provided for backwards compatibility with the 1.8 API.
923  */
925 svn_error_t *
927  svn_diff_t *diff,
928  const char *original_header,
929  const char *modified_header,
930  const char *header_encoding,
931  const svn_string_t *original,
932  const svn_string_t *modified,
933  apr_pool_t *pool);
934 
935 /** Output the @a diff generated by svn_diff_mem_string_diff3() in diff3
936  * format on @a output_stream, using @a original, @a modified and @a latest
937  * for content changes.
938  *
939  * Use the conflict markers @a conflict_original, @a conflict_modified,
940  * @a conflict_latest and @a conflict_separator or the default one for
941  * each of these if @c NULL is passed.
942  *
943  * @a conflict_style dictates how conflicts are displayed.
944  *
945  * If not @c NULL, call @a cancel_func with @a cancel_baton once or multiple
946  * times while processing larger diffs.
947  *
948  * Uses @a scratch_pool for temporary allocations.
949  *
950  * @since New in 1.9.
951  */
952 svn_error_t *
954  svn_diff_t *diff,
955  const svn_string_t *original,
956  const svn_string_t *modified,
957  const svn_string_t *latest,
958  const char *conflict_original,
959  const char *conflict_modified,
960  const char *conflict_latest,
961  const char *conflict_separator,
963  svn_cancel_func_t cancel_func,
964  void *cancel_baton,
965  apr_pool_t *scratch_pool);
966 
967 /** Similar to svn_diff_mem_string_output_merge2(), but without cancel support.
968  *
969  * @since New in 1.6.
970  *
971  * @deprecated Provided for backwards compatibility with the 1.8 API.
972  */
974 svn_error_t *
976  svn_diff_t *diff,
977  const svn_string_t *original,
978  const svn_string_t *modified,
979  const svn_string_t *latest,
980  const char *conflict_original,
981  const char *conflict_modified,
982  const char *conflict_latest,
983  const char *conflict_separator,
985  apr_pool_t *pool);
986 
987 /** Similar to svn_diff_mem_string_output_merge2, but with @a
988  * display_original_in_conflict and @a display_resolved_conflicts
989  * booleans instead of the @a conflict_style enum.
990  *
991  * If both booleans are false, acts like
992  * svn_diff_conflict_display_modified_latest; if @a
993  * display_original_in_conflict is true, acts like
994  * svn_diff_conflict_display_modified_original_latest; if @a
995  * display_resolved_conflicts is true, acts like
996  * svn_diff_conflict_display_resolved_modified_latest. The booleans
997  * may not both be true.
998  *
999  * @deprecated Provided for backward compatibility with the 1.5 API.
1000  */
1002 svn_error_t *
1004  svn_diff_t *diff,
1005  const svn_string_t *original,
1006  const svn_string_t *modified,
1007  const svn_string_t *latest,
1008  const char *conflict_original,
1009  const char *conflict_modified,
1010  const char *conflict_latest,
1011  const char *conflict_separator,
1012  svn_boolean_t display_original_in_conflict,
1013  svn_boolean_t display_resolved_conflicts,
1014  apr_pool_t *pool);
1015 
1016 
1017 
1018 /* Diff parsing. If you want to apply a patch to a working copy
1019  * rather than parse it, see svn_client_patch(). */
1020 
1021 /**
1022  * Describes what operation has been performed on a file.
1023  *
1024  * @since New in 1.7.
1025  */
1027 {
1028  svn_diff_op_unchanged,
1029  svn_diff_op_added,
1030  svn_diff_op_deleted,
1031  svn_diff_op_copied,
1032  svn_diff_op_moved,
1033  /* There's no tree changes, just text modifications. */
1034  svn_diff_op_modified
1036 
1037 /**
1038  * A single hunk inside a patch.
1039  *
1040  * The lines of text comprising the hunk can be interpreted in three ways:
1041  * - diff text The hunk as it appears in the unidiff patch file,
1042  * including the hunk header line ("@@ ... @@")
1043  * - original text The text the patch was based on.
1044  * - modified text The result of patching the original text.
1045  *
1046  * For example, consider a hunk with the following diff text:
1047  *
1048  * @verbatim
1049  @@ -1,5 +1,5 @@
1050  #include <stdio.h>
1051  int main(int argc, char *argv[]) {
1052  - printf("Hello World!\n");
1053  + printf("I like Subversion!\n");
1054  } @endverbatim
1055  *
1056  * The original text of this hunk is:
1057  *
1058  * @verbatim
1059  #include <stdio.h>
1060  int main(int argc, char *argv[]) {
1061  printf("Hello World!\n");
1062  } @endverbatim
1063  *
1064  * And the modified text is:
1065  *
1066  * @verbatim
1067  #include <stdio.h>
1068  int main(int argc, char *argv[]) {
1069  printf("I like Subversion!\n");
1070  } @endverbatim
1071  *
1072  * @see svn_diff_hunk_readline_diff_text()
1073  * @see svn_diff_hunk_readline_original_text()
1074  * @see svn_diff_hunk_readline_modified_text()
1075  *
1076  * @since New in 1.7. */
1078 
1079 /**
1080  * Allocate @a *stringbuf in @a result_pool, and read into it one line
1081  * of the diff text of @a hunk. The hunk header is not returned only the
1082  * unidiff data lines (starting with '+', '-', or ' ') are returned.
1083  * If the @a hunk is being interpreted in reverse (i.e. the reverse
1084  * parameter of svn_diff_parse_next_patch() was @c TRUE), the diff
1085  * text will be returned in reversed form.
1086  * The line-terminator is detected automatically and stored in @a *eol
1087  * if @a eol is not NULL.
1088  * If EOF is reached, set @a *eof to TRUE, and set @a *eol to NULL if the
1089  * hunk does not end with a newline character and @a eol is not NULL.
1090  * Temporary allocations will be performed in @a scratch_pool.
1091  *
1092  * @note The hunk header information can be retrieved with the following
1093  * functions:
1094  * @see svn_diff_hunk_get_original_start()
1095  * @see svn_diff_hunk_get_original_length()
1096  * @see svn_diff_hunk_get_modified_start()
1097  * @see svn_diff_hunk_get_modified_length()
1098  *
1099  * @since New in 1.7.
1100  */
1101 svn_error_t *
1103  svn_stringbuf_t **stringbuf,
1104  const char **eol,
1105  svn_boolean_t *eof,
1106  apr_pool_t *result_pool,
1107  apr_pool_t *scratch_pool);
1108 
1109 /**
1110  * Allocate @a *stringbuf in @a result_pool, and read into it one line
1111  * of the original text of @a hunk.
1112  * The line-terminator is detected automatically and stored in @a *eol
1113  * if @a eol is not NULL.
1114  * If EOF is reached, set @a *eof to TRUE, and set @a *eol to NULL if the
1115  * hunk text does not end with a newline character and @a eol is not NULL.
1116  * Temporary allocations will be performed in @a scratch_pool.
1117  *
1118  * @see svn_diff_hunk_t
1119  * @since New in 1.7.
1120  */
1121 svn_error_t *
1123  svn_stringbuf_t **stringbuf,
1124  const char **eol,
1125  svn_boolean_t *eof,
1126  apr_pool_t *result_pool,
1127  apr_pool_t *scratch_pool);
1128 
1129 /**
1130  * Like svn_diff_hunk_readline_original_text(), but it returns lines from
1131  * the modified text of the hunk.
1132  *
1133  * @see svn_diff_hunk_t
1134  * @since New in 1.7.
1135  */
1136 svn_error_t *
1138  svn_stringbuf_t **stringbuf,
1139  const char **eol,
1140  svn_boolean_t *eof,
1141  apr_pool_t *result_pool,
1142  apr_pool_t *scratch_pool);
1143 
1144 /** Reset the diff text of @a hunk so it can be read again from the start.
1145  * @since New in 1.7. */
1146 void
1148 
1149 /** Reset the original text of @a hunk so it can be read again from the start.
1150  * @since New in 1.7. */
1151 void
1153 
1154 /** Reset the modified text of @a hunk so it can be read again from the start.
1155  * @since New in 1.7. */
1156 void
1158 
1159 /** Return the line offset of the original hunk text,
1160  * as parsed from the hunk header.
1161  * @since New in 1.7. */
1164 
1165 /** Return the number of lines in the original @a hunk text,
1166  * as parsed from the hunk header.
1167  * @since New in 1.7. */
1170 
1171 /** Return the line offset of the modified @a hunk text,
1172  * as parsed from the hunk header.
1173  * @since New in 1.7. */
1176 
1177 /** Return the number of lines in the modified @a hunk text,
1178  * as parsed from the hunk header.
1179  * @since New in 1.7. */
1182 
1183 /** Return the number of lines of leading context of @a hunk,
1184  * i.e. the number of lines starting with ' ' before the first line
1185  * that starts with a '+' or '-'.
1186  * @since New in 1.7. */
1189 
1190 /** Return the number of lines of trailing context of @a hunk,
1191  * i.e. the number of lines starting with ' ' after the last line
1192  * that starts with a '+' or '-'.
1193  * @since New in 1.7. */
1196 
1197 /**
1198  * Data type to manage parsing of properties in patches.
1199  * API users should not allocate structures of this type directly.
1200  *
1201  * @since New in 1.7. */
1202 typedef struct svn_prop_patch_t {
1203  const char *name;
1204 
1205  /** Represents the operation performed on the property */
1207 
1208  /**
1209  * An array containing an svn_diff_hunk_t object for each hunk parsed
1210  * from the patch associated with our property name */
1211  apr_array_header_t *hunks;
1213 
1214 /**
1215  * Data type to manage parsing of patches.
1216  * API users should not allocate structures of this type directly.
1217  *
1218  * @since New in 1.7. */
1219 typedef struct svn_patch_t {
1220  /**
1221  * The old and new file names as retrieved from the patch file.
1222  * These paths are UTF-8 encoded and canonicalized, but otherwise
1223  * left unchanged from how they appeared in the patch file. */
1224  const char *old_filename;
1225  const char *new_filename;
1226 
1227  /**
1228  * An array containing an svn_diff_hunk_t * for each hunk parsed
1229  * from the patch. */
1230  apr_array_header_t *hunks;
1231 
1232  /**
1233  * A hash table keyed by property names containing svn_prop_patch_t
1234  * object for each property parsed from the patch. */
1235  apr_hash_t *prop_patches;
1236 
1237  /**
1238  * Represents the operation performed on the file. */
1240 
1241  /**
1242  * Indicates whether the patch is being interpreted in reverse. */
1244 
1245  /**
1246  * Mergeinfo parsed from svn:mergeinfo diff data, with one entry for
1247  * forward merges and one for reverse merges.
1248  * Either entry can be @c NULL if no such merges are part of the diff.
1249  * @since New in 1.9. */
1251  svn_mergeinfo_t reverse_mergeinfo;
1252 } svn_patch_t;
1253 
1254 /** An opaque type representing an open patch file.
1255  *
1256  * @since New in 1.7. */
1258 
1259 /** Open @a patch_file at @a local_abspath.
1260  * Allocate @a patch_file in @a result_pool.
1261  *
1262  * @since New in 1.7. */
1263 svn_error_t *
1265  const char *local_abspath,
1266  apr_pool_t *result_pool);
1267 
1268 /**
1269  * Return the next @a *patch in @a patch_file.
1270  * If no patch can be found, set @a *patch to NULL.
1271  * If @a reverse is TRUE, invert the patch while parsing it.
1272  * If @a ignore_whitespace is TRUE, allow patches with no leading
1273  * whitespace to be parsed.
1274  * Allocate results in @a result_pool.
1275  * Use @a scratch_pool for all other allocations.
1276  *
1277  * @since New in 1.7. */
1278 svn_error_t *
1280  svn_patch_file_t *patch_file,
1281  svn_boolean_t reverse,
1282  svn_boolean_t ignore_whitespace,
1283  apr_pool_t *result_pool,
1284  apr_pool_t *scratch_pool);
1285 
1286 /**
1287  * Dispose of @a patch_file.
1288  * Use @a scratch_pool for all temporary allocations.
1289  *
1290  * @since New in 1.7.
1291  */
1292 svn_error_t *
1294  apr_pool_t *scratch_pool);
1295 
1296 #ifdef __cplusplus
1297 }
1298 #endif /* __cplusplus */
1299 
1300 #endif /* SVN_DIFF_H */