Followup to r29625: fix getopt tests.
[svn.git] / subversion / include / svn_diff.h
blob962a81b875b3f5e0d1cde141c5968a1ce0a4c407
1 /**
2 * @copyright
3 * ====================================================================
4 * Copyright (c) 2000-2007 CollabNet. All rights reserved.
6 * This software is licensed as described in the file COPYING, which
7 * you should have received as part of this distribution. The terms
8 * are also available at http://subversion.tigris.org/license-1.html.
9 * If newer versions of this license are posted there, you may use a
10 * newer version instead, at your option.
12 * This software consists of voluntary contributions made by many
13 * individuals. For exact contribution history, see the revision
14 * history and logs, available at http://subversion.tigris.org/.
15 * ====================================================================
16 * @endcopyright
18 * @file svn_diff.h
19 * @brief Contextual diffing.
21 * This is an internalized library for performing contextual diffs
22 * between sources of data.
24 * @note This is different than Subversion's binary-diffing engine.
25 * That API lives in @c svn_delta.h -- see the "text deltas" section. A
26 * "text delta" is way of representing precise binary diffs between
27 * strings of data. The Subversion client and server send text deltas
28 * to one another during updates and commits.
30 * This API, however, is (or will be) used for performing *contextual*
31 * merges between files in the working copy. During an update or
32 * merge, 3-way file merging is needed. And 'svn diff' needs to show
33 * the differences between 2 files.
35 * The nice thing about this API is that it's very general. It
36 * operates on any source of data (a "datasource") and calculates
37 * contextual differences on "tokens" within the data. In our
38 * particular usage, the datasources are files and the tokens are
39 * lines. But the possibilities are endless.
43 #ifndef SVN_DIFF_H
44 #define SVN_DIFF_H
46 #include <apr.h>
47 #include <apr_pools.h>
48 #include <apr_file_io.h>
50 #include "svn_types.h"
51 #include "svn_error.h"
52 #include "svn_io.h"
53 #include "svn_version.h"
55 #ifdef __cplusplus
56 extern "C" {
57 #endif /* __cplusplus */
61 /**
62 * Get libsvn_diff version information.
64 * @since New in 1.1.
66 const svn_version_t *svn_diff_version(void);
69 /* Diffs. */
71 /** An opaque type that represents a difference between either two or
72 * three datasources. This object is returned by svn_diff_diff(),
73 * svn_diff_diff3() and svn_diff_diff4(), and consumed by a number of
74 * other routines.
76 typedef struct svn_diff_t svn_diff_t;
78 /**
79 * There are four types of datasources. In GNU diff3 terminology,
80 * the first three types correspond to the phrases "older", "mine",
81 * and "yours".
83 typedef enum svn_diff_datasource_e
85 /** The oldest form of the data. */
86 svn_diff_datasource_original,
88 /** The same data, but potentially changed by the user. */
89 svn_diff_datasource_modified,
91 /** The latest version of the data, possibly different than the
92 * user's modified version.
94 svn_diff_datasource_latest,
96 /** The common ancestor of original and modified. */
97 svn_diff_datasource_ancestor
99 } svn_diff_datasource_e;
102 /** A vtable for reading data from the three datasources. */
103 typedef struct svn_diff_fns_t
105 /** Open the datasource of type @a datasource. */
106 svn_error_t *(*datasource_open)(void *diff_baton,
107 svn_diff_datasource_e datasource);
109 /** Close the datasource of type @a datasource. */
110 svn_error_t *(*datasource_close)(void *diff_baton,
111 svn_diff_datasource_e datasource);
113 /** Get the next "token" from the datasource of type @a datasource.
114 * Return a "token" in @a *token. Return a hash of "token" in @a *hash.
115 * Leave @a token and @a hash untouched when the datasource is exhausted.
117 svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token,
118 void *diff_baton,
119 svn_diff_datasource_e datasource);
121 /** A function for ordering the tokens, resembling 'strcmp' in functionality.
122 * @a compare should contain the return value of the comparison:
123 * If @a ltoken and @a rtoken are "equal", return 0. If @a ltoken is
124 * "less than" @a rtoken, return a number < 0. If @a ltoken is
125 * "greater than" @a rtoken, return a number > 0.
127 svn_error_t *(*token_compare)(void *diff_baton,
128 void *ltoken,
129 void *rtoken,
130 int *compare);
132 /** Free @a token from memory, the diff algorithm is done with it. */
133 void (*token_discard)(void *diff_baton,
134 void *token);
136 /** Free *all* tokens from memory, they're no longer needed. */
137 void (*token_discard_all)(void *diff_baton);
138 } svn_diff_fns_t;
141 /* The Main Events */
143 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
144 * return a diff object in @a *diff that represents a difference between
145 * an "original" and "modified" datasource. Do all allocation in @a pool.
147 svn_error_t *svn_diff_diff(svn_diff_t **diff,
148 void *diff_baton,
149 const svn_diff_fns_t *diff_fns,
150 apr_pool_t *pool);
152 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
153 * return a diff object in @a *diff that represents a difference between
154 * three datasources: "original", "modified", and "latest". Do all
155 * allocation in @a pool.
157 svn_error_t *svn_diff_diff3(svn_diff_t **diff,
158 void *diff_baton,
159 const svn_diff_fns_t *diff_fns,
160 apr_pool_t *pool);
162 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources,
163 * return a diff object in @a *diff that represents a difference between
164 * two datasources: "original" and "latest", adjusted to become a full
165 * difference between "original", "modified" and "latest" using "ancestor".
166 * Do all allocation in @a pool.
168 svn_error_t *svn_diff_diff4(svn_diff_t **diff,
169 void *diff_baton,
170 const svn_diff_fns_t *diff_fns,
171 apr_pool_t *pool);
174 /* Utility functions */
176 /** Determine if a diff object contains conflicts. If it does, return
177 * @c TRUE, else return @c FALSE.
179 svn_boolean_t
180 svn_diff_contains_conflicts(svn_diff_t *diff);
183 /** Determine if a diff object contains actual differences between the
184 * datasources. If so, return @c TRUE, else return @c FALSE.
186 svn_boolean_t
187 svn_diff_contains_diffs(svn_diff_t *diff);
192 /* Displaying Diffs */
194 /** A vtable for displaying (or consuming) differences between datasources.
196 * Differences, similarities, and conflicts are described by lining up
197 * "ranges" of data.
199 * @note These callbacks describe data ranges in units of "tokens".
200 * A "token" is whatever you've defined it to be in your datasource
201 * @c svn_diff_fns_t vtable.
203 typedef struct svn_diff_output_fns_t
205 /* Two-way and three-way diffs both call the first two output functions: */
208 * If doing a two-way diff, then an *identical* data range was found
209 * between the "original" and "modified" datasources. Specifically,
210 * the match starts at @a original_start and goes for @a original_length
211 * tokens in the original data, and at @a modified_start for
212 * @a modified_length tokens in the modified data.
214 * If doing a three-way diff, then all three datasources have
215 * matching data ranges. The range @a latest_start, @a latest_length in
216 * the "latest" datasource is identical to the range @a original_start,
217 * @a original_length in the original data, and is also identical to
218 * the range @a modified_start, @a modified_length in the modified data.
220 svn_error_t *(*output_common)(void *output_baton,
221 apr_off_t original_start,
222 apr_off_t original_length,
223 apr_off_t modified_start,
224 apr_off_t modified_length,
225 apr_off_t latest_start,
226 apr_off_t latest_length);
229 * If doing a two-way diff, then an *conflicting* data range was found
230 * between the "original" and "modified" datasources. Specifically,
231 * the conflict starts at @a original_start and goes for @a original_length
232 * tokens in the original data, and at @a modified_start for
233 * @a modified_length tokens in the modified data.
235 * If doing a three-way diff, then an identical data range was discovered
236 * between the "original" and "latest" datasources, but this conflicts with
237 * a range in the "modified" datasource.
239 svn_error_t *(*output_diff_modified)(void *output_baton,
240 apr_off_t original_start,
241 apr_off_t original_length,
242 apr_off_t modified_start,
243 apr_off_t modified_length,
244 apr_off_t latest_start,
245 apr_off_t latest_length);
247 /* ------ The following callbacks are used by three-way diffs only --- */
249 /** An identical data range was discovered between the "original" and
250 * "modified" datasources, but this conflicts with a range in the
251 * "latest" datasource.
253 svn_error_t *(*output_diff_latest)(void *output_baton,
254 apr_off_t original_start,
255 apr_off_t original_length,
256 apr_off_t modified_start,
257 apr_off_t modified_length,
258 apr_off_t latest_start,
259 apr_off_t latest_length);
261 /** An identical data range was discovered between the "modified" and
262 * "latest" datasources, but this conflicts with a range in the
263 * "original" datasource.
265 svn_error_t *(*output_diff_common)(void *output_baton,
266 apr_off_t original_start,
267 apr_off_t original_length,
268 apr_off_t modified_start,
269 apr_off_t modified_length,
270 apr_off_t latest_start,
271 apr_off_t latest_length);
273 /** All three datasources have conflicting data ranges. The range
274 * @a latest_start, @a latest_length in the "latest" datasource conflicts
275 * with the range @a original_start, @a original_length in the "original"
276 * datasource, and also conflicts with the range @a modified_start,
277 * @a modified_length in the "modified" datasource.
278 * If there are common ranges in the "modified" and "latest" datasources
279 * in this conflicting range, @a resolved_diff will contain a diff
280 * which can be used to retrieve the common and conflicting ranges.
282 svn_error_t *(*output_conflict)(void *output_baton,
283 apr_off_t original_start,
284 apr_off_t original_length,
285 apr_off_t modified_start,
286 apr_off_t modified_length,
287 apr_off_t latest_start,
288 apr_off_t latest_length,
289 svn_diff_t *resolved_diff);
290 } svn_diff_output_fns_t;
293 /** Given a vtable of @a output_fns/@a output_baton for consuming
294 * differences, output the differences in @a diff.
296 svn_error_t *
297 svn_diff_output(svn_diff_t *diff,
298 void *output_baton,
299 const svn_diff_output_fns_t *output_fns);
303 /* Diffs on files */
305 /** To what extent whitespace should be ignored when comparing lines.
307 * @since New in 1.4.
309 typedef enum svn_diff_file_ignore_space_t
311 /** Ignore no whitespace. */
312 svn_diff_file_ignore_space_none,
314 /** Ignore changes in sequences of whitespace characters, treating each
315 * sequence of whitespace characters as a single space. */
316 svn_diff_file_ignore_space_change,
318 /** Ignore all whitespace characters. */
319 svn_diff_file_ignore_space_all
320 } svn_diff_file_ignore_space_t;
322 /** Options to control the behaviour of the file diff routines.
324 * @since New in 1.4.
326 * @note This structure may be extended in the future, so to preserve binary
327 * compatibility, users must not allocate structs of this type themselves.
328 * @see svn_diff_file_options_create().
330 * @note Although its name suggests otherwise, this structure is used to
331 * pass options to file as well as in-memory diff functions.
333 typedef struct svn_diff_file_options_t
335 /** To what extent whitespace should be ignored when comparing lines.
336 * The default is @c svn_diff_file_ignore_space_none. */
337 svn_diff_file_ignore_space_t ignore_space;
338 /** Whether to treat all end-of-line markers the same when comparing lines.
339 * The default is @c FALSE. */
340 svn_boolean_t ignore_eol_style;
341 /** Whether the '@@' lines of the unified diff output should include a prefix
342 * of the nearest preceding line that starts with a character that might be
343 * the initial character of a C language identifier. The default is
344 * @c FALSE.
346 svn_boolean_t show_c_function;
347 } svn_diff_file_options_t;
349 /** Allocate a @c svn_diff_file_options_t structure in @a pool, initializing
350 * it with default values.
352 * @since New in 1.4.
354 svn_diff_file_options_t *
355 svn_diff_file_options_create(apr_pool_t *pool);
358 * Parse @a args, an array of <tt>const char *</tt> command line switches
359 * and adjust @a options accordingly. @a options is assumed to be initialized
360 * with default values. @a pool is used for temporary allocation.
362 * @since New in 1.4.
364 * The following options are supported:
365 * - --ignore-space-change, -b
366 * - --ignore-all-space, -w
367 * - --ignore-eol-style
368 * - --unified, -u (for compatibility, does nothing).
370 svn_error_t *
371 svn_diff_file_options_parse(svn_diff_file_options_t *options,
372 const apr_array_header_t *args,
373 apr_pool_t *pool);
376 /** A convenience function to produce a diff between two files.
378 * @since New in 1.4.
380 * Return a diff object in @a *diff (allocated from @a pool) that represents
381 * the difference between an @a original file and @a modified file.
382 * (The file arguments must be full paths to the files.)
384 * Compare lines according to the relevant fields of @a options.
386 svn_error_t *
387 svn_diff_file_diff_2(svn_diff_t **diff,
388 const char *original,
389 const char *modified,
390 const svn_diff_file_options_t *options,
391 apr_pool_t *pool);
393 /** Similar to svn_file_diff_2(), but with @a options set to a struct with
394 * default options.
396 * @deprecated Provided for backwards compatibility with the 1.3 API.
398 svn_error_t *
399 svn_diff_file_diff(svn_diff_t **diff,
400 const char *original,
401 const char *modified,
402 apr_pool_t *pool);
404 /** A convenience function to produce a diff between three files.
406 * @since New in 1.4.
408 * Return a diff object in @a *diff (allocated from @a pool) that represents
409 * the difference between an @a original file, @a modified file, and @a latest
410 * file.
412 * Compare lines according to the relevant fields of @a options.
414 svn_error_t *
415 svn_diff_file_diff3_2(svn_diff_t **diff,
416 const char *original,
417 const char *modified,
418 const char *latest,
419 const svn_diff_file_options_t *options,
420 apr_pool_t *pool);
422 /** Similar to svn_diff_file_diff3_2(), but with @a options set to a struct
423 * with default options.
425 * @deprecated Provided for backwards compatibility with the 1.3 API.
427 svn_error_t *
428 svn_diff_file_diff3(svn_diff_t **diff,
429 const char *original,
430 const char *modified,
431 const char *latest,
432 apr_pool_t *pool);
434 /** A convenience function to produce a diff between four files.
436 * @since New in 1.4.
438 * Return a diff object in @a *diff (allocated from @a pool) that represents
439 * the difference between an @a original file, @a modified file, @a latest
440 * and @a ancestor file. (The file arguments must be full paths to the files.)
442 * Compare lines according to the relevant fields of @a options.
444 svn_error_t *
445 svn_diff_file_diff4_2(svn_diff_t **diff,
446 const char *original,
447 const char *modified,
448 const char *latest,
449 const char *ancestor,
450 const svn_diff_file_options_t *options,
451 apr_pool_t *pool);
453 /** Simliar to svn_file_diff4_2(), but with @a options set to a struct with
454 * default options.
456 * @deprecated Provided for backwards compatibility with the 1.3 API.
458 svn_error_t *
459 svn_diff_file_diff4(svn_diff_t **diff,
460 const char *original,
461 const char *modified,
462 const char *latest,
463 const char *ancestor,
464 apr_pool_t *pool);
466 /** A convenience function to produce unified diff output from the
467 * diff generated by svn_diff_file_diff().
469 * @since New in 1.5.
471 * Output a @a diff between @a original_path and @a modified_path in unified
472 * context diff format to @a output_stream. Optionally supply
473 * @a original_header and/or @a modified_header to be displayed in the header
474 * of the output. If @a original_header or @a modified_header is @c NULL, a
475 * default header will be displayed, consisting of path and last modified time.
476 * Output all headers and markers in @a header_encoding. If @a relative_to_dir
477 * is not @c NULL, the @a original_path and @a modified_path will have the
478 * @a relative_to_dir stripped from the front of the respective paths. If
479 * @a relative_to_dir is @c NULL, paths will be not be modified. If
480 * @a relative_to_dir is not @c NULL but @a relative_to_dir is not a parent
481 * path of the target, an error is returned. Finally, if @a relative_to_dir
482 * is a URL, an error will be returned.
484 svn_error_t *
485 svn_diff_file_output_unified3(svn_stream_t *output_stream,
486 svn_diff_t *diff,
487 const char *original_path,
488 const char *modified_path,
489 const char *original_header,
490 const char *modified_header,
491 const char *header_encoding,
492 const char *relative_to_dir,
493 svn_boolean_t show_c_function,
494 apr_pool_t *pool);
496 /** Similar to svn_diff_file_output_unified3(), but with @a relative_to_dir
497 * set to NULL and @a show_c_function to false.
499 * @deprecated Provided for backwards compatibility with the 1.3 API.
501 svn_error_t *
502 svn_diff_file_output_unified2(svn_stream_t *output_stream,
503 svn_diff_t *diff,
504 const char *original_path,
505 const char *modified_path,
506 const char *original_header,
507 const char *modified_header,
508 const char *header_encoding,
509 apr_pool_t *pool);
511 /** Similar to svn_diff_file_output_unified2(), but with @a header_encoding
512 * set to @c APR_LOCALE_CHARSET.
514 * @deprecated Provided for backward compatibility with the 1.2 API.
516 svn_error_t *
517 svn_diff_file_output_unified(svn_stream_t *output_stream,
518 svn_diff_t *diff,
519 const char *original_path,
520 const char *modified_path,
521 const char *original_header,
522 const char *modified_header,
523 apr_pool_t *pool);
526 /** A convenience function to produce diff3 output from the
527 * diff generated by svn_diff_file_diff3().
529 * Output a @a diff between @a original_path, @a modified_path and
530 * @a latest_path in merged format to @a output_stream. Optionally supply
531 * @a conflict_modified, @a conflict_original, @a conflict_separator and/or
532 * @a conflict_latest to be displayed as conflict markers in the output.
533 * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or
534 * @a conflict_separator is @c NULL, a default marker will be displayed.
535 * Set @a display_original_in_conflict and @a display_resolved_conflicts
536 * as desired. Note that these options are mutually exclusive.
538 svn_error_t *
539 svn_diff_file_output_merge(svn_stream_t *output_stream,
540 svn_diff_t *diff,
541 const char *original_path,
542 const char *modified_path,
543 const char *latest_path,
544 const char *conflict_original,
545 const char *conflict_modified,
546 const char *conflict_latest,
547 const char *conflict_separator,
548 svn_boolean_t display_original_in_conflict,
549 svn_boolean_t display_resolved_conflicts,
550 apr_pool_t *pool);
554 /* Diffs on in-memory structures */
556 /** Generate @a diff output from the @a original and @a modified
557 * in-memory strings. @a diff will be allocated from @a pool.
559 * @since New in 1.5.
561 svn_error_t *
562 svn_diff_mem_string_diff(svn_diff_t **diff,
563 const svn_string_t *original,
564 const svn_string_t *modified,
565 const svn_diff_file_options_t *options,
566 apr_pool_t *pool);
569 /** Generate @a diff output from the @a orginal, @a modified and @a latest
570 * in-memory strings. @a diff will be allocated in @a pool.
572 * @since New in 1.5.
574 svn_error_t *
575 svn_diff_mem_string_diff3(svn_diff_t **diff,
576 const svn_string_t *original,
577 const svn_string_t *modified,
578 const svn_string_t *latest,
579 const svn_diff_file_options_t *options,
580 apr_pool_t *pool);
583 /** Generate @a diff output from the @a original, @a modified and @a latest
584 * in-memory strings, using @a ancestor. @a diff will be allocated in @a pool.
586 * @since New in 1.5.
588 svn_error_t *
589 svn_diff_mem_string_diff4(svn_diff_t **diff,
590 const svn_string_t *original,
591 const svn_string_t *modified,
592 const svn_string_t *latest,
593 const svn_string_t *ancestor,
594 const svn_diff_file_options_t *options,
595 apr_pool_t *pool);
598 /** Outputs the @a diff object generated by svn_diff_mem_string_diff()
599 * in unified diff format on @a output_stream, using @a original
600 * and @a modified for the text in the output.
601 * Outputs the header and markers in @a header_encoding.
603 * @a original_header and @a modified header are
604 * used to fill the field after the "---" and "+++" header markers.
606 * @since New in 1.5.
608 svn_error_t *
609 svn_diff_mem_string_output_unified(svn_stream_t *output_stream,
610 svn_diff_t *diff,
611 const char *original_header,
612 const char *modified_header,
613 const char *header_encoding,
614 const svn_string_t *original,
615 const svn_string_t *modified,
616 apr_pool_t *pool);
618 /** Output the @a diff generated by svn_diff_mem_string_diff3() in diff3
619 * format on @a output_stream, using @a original, @a modified and @a latest
620 * for content changes.
622 * Use the conflict markers @a conflict_original, @a conflict_modified,
623 * @a conflict_latest and @a conflict_separator or the default one for
624 * each of these if @c NULL is passed.
626 * Insert the original in the output if @a display_original_in_conflict
627 * is @c TRUE.
629 * @note @a display_original_in_conflict and @a display_resolved_conflicts
630 * are mutually exclusive.
632 svn_error_t *
633 svn_diff_mem_string_output_merge(svn_stream_t *output_stream,
634 svn_diff_t *diff,
635 const svn_string_t *original,
636 const svn_string_t *modified,
637 const svn_string_t *latest,
638 const char *conflict_original,
639 const char *conflict_modified,
640 const char *conflict_latest,
641 const char *conflict_separator,
642 svn_boolean_t display_original_in_conflict,
643 svn_boolean_t display_resolved_conflicts,
644 apr_pool_t *pool);
647 #ifdef __cplusplus
649 #endif /* __cplusplus */
651 #endif /* SVN_DIFF_H */