00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2006 CollabNet. All rights reserved. 00005 * 00006 * This software is licensed as described in the file COPYING, which 00007 * you should have received as part of this distribution. The terms 00008 * are also available at http://subversion.tigris.org/license-1.html. 00009 * If newer versions of this license are posted there, you may use a 00010 * newer version instead, at your option. 00011 * 00012 * This software consists of voluntary contributions made by many 00013 * individuals. For exact contribution history, see the revision 00014 * history and logs, available at http://subversion.tigris.org/. 00015 * ==================================================================== 00016 * @endcopyright 00017 * 00018 * @file svn_diff.h 00019 * @brief Contextual diffing. 00020 * 00021 * This is an internalized library for performing contextual diffs 00022 * between sources of data. 00023 * 00024 * @note This is different than Subversion's binary-diffing engine. 00025 * That API lives in @c svn_delta.h -- see the "text deltas" section. A 00026 * "text delta" is way of representing precise binary diffs between 00027 * strings of data. The Subversion client and server send text deltas 00028 * to one another during updates and commits. 00029 * 00030 * This API, however, is (or will be) used for performing *contextual* 00031 * merges between files in the working copy. During an update or 00032 * merge, 3-way file merging is needed. And 'svn diff' needs to show 00033 * the differences between 2 files. 00034 * 00035 * The nice thing about this API is that it's very general. It 00036 * operates on any source of data (a "datasource") and calculates 00037 * contextual differences on "tokens" within the data. In our 00038 * particular usage, the datasources are files and the tokens are 00039 * lines. But the possibilities are endless. 00040 */ 00041 00042 00043 #ifndef SVN_DIFF_H 00044 #define SVN_DIFF_H 00045 00046 #include <apr.h> 00047 #include <apr_pools.h> 00048 #include <apr_file_io.h> 00049 00050 #include "svn_types.h" 00051 #include "svn_error.h" 00052 #include "svn_io.h" 00053 #include "svn_version.h" 00054 00055 #ifdef __cplusplus 00056 extern "C" { 00057 #endif /* __cplusplus */ 00058 00059 00060 00061 /** 00062 * Get libsvn_diff version information. 00063 * 00064 * @since New in 1.1. 00065 */ 00066 const svn_version_t *svn_diff_version(void); 00067 00068 00069 /* Diffs. */ 00070 00071 /** An opaque type that represents a difference between either two or 00072 * three datasources. This object is returned by svn_diff_diff(), 00073 * svn_diff_diff3() and svn_diff_diff4(), and consumed by a number of 00074 * other routines. 00075 */ 00076 typedef struct svn_diff_t svn_diff_t; 00077 00078 /** 00079 * There are four types of datasources. In GNU diff3 terminology, 00080 * the first three types correspond to the phrases "older", "mine", 00081 * and "yours". 00082 */ 00083 typedef enum svn_diff_datasource_e 00084 { 00085 /** The oldest form of the data. */ 00086 svn_diff_datasource_original, 00087 00088 /** The same data, but potentially changed by the user. */ 00089 svn_diff_datasource_modified, 00090 00091 /** The latest version of the data, possibly different than the 00092 * user's modified version. 00093 */ 00094 svn_diff_datasource_latest, 00095 00096 /** The common ancestor of original and modified. */ 00097 svn_diff_datasource_ancestor 00098 00099 } svn_diff_datasource_e; 00100 00101 00102 /** A vtable for reading data from the three datasources. */ 00103 typedef struct svn_diff_fns_t 00104 { 00105 /** Open the datasource of type @a datasource. */ 00106 svn_error_t *(*datasource_open)(void *diff_baton, 00107 svn_diff_datasource_e datasource); 00108 00109 /** Close the datasource of type @a datasource. */ 00110 svn_error_t *(*datasource_close)(void *diff_baton, 00111 svn_diff_datasource_e datasource); 00112 00113 /** Get the next "token" from the datasource of type @a datasource. 00114 * Return a "token" in @a *token. Return a hash of "token" in @a *hash. 00115 * Leave @a token and @a hash untouched when the datasource is exhausted. 00116 */ 00117 svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token, 00118 void *diff_baton, 00119 svn_diff_datasource_e datasource); 00120 00121 /** A function for ordering the tokens, resembling 'strcmp' in functionality. 00122 * @a compare should contain the return value of the comparison: 00123 * If @a ltoken and @a rtoken are "equal", return 0. If @a ltoken is 00124 * "less than" @a rtoken, return a number < 0. If @a ltoken is 00125 * "greater than" @a rtoken, return a number > 0. 00126 */ 00127 svn_error_t *(*token_compare)(void *diff_baton, 00128 void *ltoken, 00129 void *rtoken, 00130 int *compare); 00131 00132 /** Free @a token from memory, the diff algorithm is done with it. */ 00133 void (*token_discard)(void *diff_baton, 00134 void *token); 00135 00136 /** Free *all* tokens from memory, they're no longer needed. */ 00137 void (*token_discard_all)(void *diff_baton); 00138 } svn_diff_fns_t; 00139 00140 00141 /* The Main Events */ 00142 00143 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00144 * return a diff object in @a *diff that represents a difference between 00145 * an "original" and "modified" datasource. Do all allocation in @a pool. 00146 */ 00147 svn_error_t *svn_diff_diff(svn_diff_t **diff, 00148 void *diff_baton, 00149 const svn_diff_fns_t *diff_fns, 00150 apr_pool_t *pool); 00151 00152 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00153 * return a diff object in @a *diff that represents a difference between 00154 * three datasources: "original", "modified", and "latest". Do all 00155 * allocation in @a pool. 00156 */ 00157 svn_error_t *svn_diff_diff3(svn_diff_t **diff, 00158 void *diff_baton, 00159 const svn_diff_fns_t *diff_fns, 00160 apr_pool_t *pool); 00161 00162 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00163 * return a diff object in @a *diff that represents a difference between 00164 * two datasources: "original" and "latest", adjusted to become a full 00165 * difference between "original", "modified" and "latest" using "ancestor". 00166 * Do all allocation in @a pool. 00167 */ 00168 svn_error_t *svn_diff_diff4(svn_diff_t **diff, 00169 void *diff_baton, 00170 const svn_diff_fns_t *diff_fns, 00171 apr_pool_t *pool); 00172 00173 00174 /* Utility functions */ 00175 00176 /** Determine if a diff object contains conflicts. If it does, return 00177 * @c TRUE, else return @c FALSE. 00178 */ 00179 svn_boolean_t 00180 svn_diff_contains_conflicts(svn_diff_t *diff); 00181 00182 00183 /** Determine if a diff object contains actual differences between the 00184 * datasources. If so, return @c TRUE, else return @c FALSE. 00185 */ 00186 svn_boolean_t 00187 svn_diff_contains_diffs(svn_diff_t *diff); 00188 00189 00190 00191 00192 /* Displaying Diffs */ 00193 00194 /** A vtable for displaying (or consuming) differences between datasources. 00195 * 00196 * Differences, similarities, and conflicts are described by lining up 00197 * "ranges" of data. 00198 * 00199 * @note These callbacks describe data ranges in units of "tokens". 00200 * A "token" is whatever you've defined it to be in your datasource 00201 * @c svn_diff_fns_t vtable. 00202 */ 00203 typedef struct svn_diff_output_fns_t 00204 { 00205 /* Two-way and three-way diffs both call the first two output functions: */ 00206 00207 /** 00208 * If doing a two-way diff, then an *identical* data range was found 00209 * between the "original" and "modified" datasources. Specifically, 00210 * the match starts at @a original_start and goes for @a original_length 00211 * tokens in the original data, and at @a modified_start for 00212 * @a modified_length tokens in the modified data. 00213 * 00214 * If doing a three-way diff, then all three datasources have 00215 * matching data ranges. The range @a latest_start, @a latest_length in 00216 * the "latest" datasource is identical to the range @a original_start, 00217 * @a original_length in the original data, and is also identical to 00218 * the range @a modified_start, @a modified_length in the modified data. 00219 */ 00220 svn_error_t *(*output_common)(void *output_baton, 00221 apr_off_t original_start, 00222 apr_off_t original_length, 00223 apr_off_t modified_start, 00224 apr_off_t modified_length, 00225 apr_off_t latest_start, 00226 apr_off_t latest_length); 00227 00228 /** 00229 * If doing a two-way diff, then an *conflicting* data range was found 00230 * between the "original" and "modified" datasources. Specifically, 00231 * the conflict starts at @a original_start and goes for @a original_length 00232 * tokens in the original data, and at @a modified_start for 00233 * @a modified_length tokens in the modified data. 00234 * 00235 * If doing a three-way diff, then an identical data range was discovered 00236 * between the "original" and "latest" datasources, but this conflicts with 00237 * a range in the "modified" datasource. 00238 */ 00239 svn_error_t *(*output_diff_modified)(void *output_baton, 00240 apr_off_t original_start, 00241 apr_off_t original_length, 00242 apr_off_t modified_start, 00243 apr_off_t modified_length, 00244 apr_off_t latest_start, 00245 apr_off_t latest_length); 00246 00247 /* ------ The following callbacks are used by three-way diffs only --- */ 00248 00249 /** An identical data range was discovered between the "original" and 00250 * "modified" datasources, but this conflicts with a range in the 00251 * "latest" datasource. 00252 */ 00253 svn_error_t *(*output_diff_latest)(void *output_baton, 00254 apr_off_t original_start, 00255 apr_off_t original_length, 00256 apr_off_t modified_start, 00257 apr_off_t modified_length, 00258 apr_off_t latest_start, 00259 apr_off_t latest_length); 00260 00261 /** An identical data range was discovered between the "modified" and 00262 * "latest" datasources, but this conflicts with a range in the 00263 * "original" datasource. 00264 */ 00265 svn_error_t *(*output_diff_common)(void *output_baton, 00266 apr_off_t original_start, 00267 apr_off_t original_length, 00268 apr_off_t modified_start, 00269 apr_off_t modified_length, 00270 apr_off_t latest_start, 00271 apr_off_t latest_length); 00272 00273 /** All three datasources have conflicting data ranges. The range 00274 * @a latest_start, @a latest_length in the "latest" datasource conflicts 00275 * with the range @a original_start, @a original_length in the "original" 00276 * datasource, and also conflicts with the range @a modified_start, 00277 * @a modified_length in the "modified" datasource. 00278 * If there are common ranges in the "modified" and "latest" datasources 00279 * in this conflicting range, @a resolved_diff will contain a diff 00280 * which can be used to retrieve the common and conflicting ranges. 00281 */ 00282 svn_error_t *(*output_conflict)(void *output_baton, 00283 apr_off_t original_start, 00284 apr_off_t original_length, 00285 apr_off_t modified_start, 00286 apr_off_t modified_length, 00287 apr_off_t latest_start, 00288 apr_off_t latest_length, 00289 svn_diff_t *resolved_diff); 00290 } svn_diff_output_fns_t; 00291 00292 00293 /** Given a vtable of @a output_fns/@a output_baton for consuming 00294 * differences, output the differences in @a diff. 00295 */ 00296 svn_error_t * 00297 svn_diff_output(svn_diff_t *diff, 00298 void *output_baton, 00299 const svn_diff_output_fns_t *output_fns); 00300 00301 00302 00303 /* Diffs on files */ 00304 00305 /** To what extent whitespace should be ignored when comparing lines. 00306 * 00307 * @since New in 1.4. 00308 */ 00309 typedef enum svn_diff_file_ignore_space_t 00310 { 00311 /** Ignore no whitespace. */ 00312 svn_diff_file_ignore_space_none, 00313 00314 /** Ignore changes in sequences of whitespace characters, treating each 00315 * sequence of whitespace characters as a single space. */ 00316 svn_diff_file_ignore_space_change, 00317 00318 /** Ignore all whitespace characters. */ 00319 svn_diff_file_ignore_space_all 00320 } svn_diff_file_ignore_space_t; 00321 00322 /** Options to control the behaviour of the file diff routines. 00323 * 00324 * @since New in 1.4. 00325 * 00326 * @note This structure may be extended in the future, so to preserve binary 00327 * compatibility, users must not allocate structs of this type themselves. 00328 * @see svn_diff_file_options_create(). 00329 */ 00330 typedef struct svn_diff_file_options_t 00331 { 00332 /** To what extent whitespace should be ignored when comparing lines. 00333 * The default is @c svn_diff_file_ignore_space_none. */ 00334 svn_diff_file_ignore_space_t ignore_space; 00335 /** Whether to treat all end-of-line markers the same when comparing lines. 00336 * The default is @c FALSE. */ 00337 svn_boolean_t ignore_eol_style; 00338 } svn_diff_file_options_t; 00339 00340 /** Allocate a @c svn_diff_file_options_t structure in @a pool, initializing 00341 * it with default values. 00342 * 00343 * @since New in 1.4. 00344 */ 00345 svn_diff_file_options_t * 00346 svn_diff_file_options_create(apr_pool_t *pool); 00347 00348 /** 00349 * Parse @a args, an array of <tt>const char *</tt> command line switches 00350 * and adjust @a options accordingly. @a options is assumed to be initialized 00351 * with default values. @a pool is used for temporary allocation. 00352 * 00353 * @since New in 1.4. 00354 * 00355 * The following options are supported: 00356 * - --ignore-space-change, -b 00357 * - --ignore-all-space, -w 00358 * - --ignore-eol-style 00359 * - --unified, -u (for compatibility, does nothing). 00360 */ 00361 svn_error_t * 00362 svn_diff_file_options_parse(svn_diff_file_options_t *options, 00363 const apr_array_header_t *args, 00364 apr_pool_t *pool); 00365 00366 00367 /** A convenience function to produce a diff between two files. 00368 * 00369 * @since New in 1.4. 00370 * 00371 * Return a diff object in @a *diff (allocated from @a pool) that represents 00372 * the difference between an @a original file and @a modified file. 00373 * (The file arguments must be full paths to the files.) 00374 * 00375 * Compare lines according to the relevant fields of @a options. 00376 */ 00377 svn_error_t * 00378 svn_diff_file_diff_2(svn_diff_t **diff, 00379 const char *original, 00380 const char *modified, 00381 const svn_diff_file_options_t *options, 00382 apr_pool_t *pool); 00383 00384 /** Similar to svn_file_diff_2(), but with @a options set to a struct with 00385 * default options. 00386 * 00387 * @deprecated Provided for backwards compatibility with the 1.3 API. 00388 */ 00389 svn_error_t * 00390 svn_diff_file_diff(svn_diff_t **diff, 00391 const char *original, 00392 const char *modified, 00393 apr_pool_t *pool); 00394 00395 /** A convenience function to produce a diff between three files. 00396 * 00397 * @since New in 1.4. 00398 * 00399 * Return a diff object in @a *diff (allocated from @a pool) that represents 00400 * the difference between an @a original file, @a modified file, and @a latest 00401 * file. (The file arguments must be full paths to the files.) 00402 * 00403 * Compare lines according to the relevant fields of @a options. 00404 */ 00405 svn_error_t * 00406 svn_diff_file_diff3_2(svn_diff_t **diff, 00407 const char *original, 00408 const char *modified, 00409 const char *latest, 00410 const svn_diff_file_options_t *options, 00411 apr_pool_t *pool); 00412 00413 /** Similar to svn_diff_file_diff3_2(), but with @a options set to a struct 00414 * with default options. 00415 * 00416 * @deprecated Provided for backwards compatibility with the 1.3 API. 00417 */ 00418 svn_error_t * 00419 svn_diff_file_diff3(svn_diff_t **diff, 00420 const char *original, 00421 const char *modified, 00422 const char *latest, 00423 apr_pool_t *pool); 00424 00425 /** A convenience function to produce a diff between four files. 00426 * 00427 * @since New in 1.4. 00428 * 00429 * Return a diff object in @a *diff (allocated from @a pool) that represents 00430 * the difference between an @a original file, @a modified file, @a latest 00431 * and @a ancestor file. (The file arguments must be full paths to the files.) 00432 * 00433 * Compare lines according to the relevant fields of @a options. 00434 */ 00435 svn_error_t * 00436 svn_diff_file_diff4_2(svn_diff_t **diff, 00437 const char *original, 00438 const char *modified, 00439 const char *latest, 00440 const char *ancestor, 00441 const svn_diff_file_options_t *options, 00442 apr_pool_t *pool); 00443 00444 /** Simliar to svn_file_diff4_2(), but with @a options set to a struct with 00445 * default options. 00446 * 00447 * @deprecated Provided for backwards compatibility with the 1.3 API. 00448 */ 00449 svn_error_t * 00450 svn_diff_file_diff4(svn_diff_t **diff, 00451 const char *original, 00452 const char *modified, 00453 const char *latest, 00454 const char *ancestor, 00455 apr_pool_t *pool); 00456 00457 /** A convenience function to produce unified diff output from the 00458 * diff generated by svn_diff_file_diff(). 00459 * 00460 * @since New in 1.3. 00461 * 00462 * Output a @a diff between @a original_path and @a modified_path in unified 00463 * context diff format to @a output_file. Optionally supply @a original_header 00464 * and/or @a modified_header to be displayed in the header of the output. 00465 * If @a original_header or @a modified_header is @c NULL, a default header 00466 * will be displayed, consisting of path and last modified time. Output 00467 * all headers and markers in @a header_encoding. 00468 */ 00469 svn_error_t * 00470 svn_diff_file_output_unified2(svn_stream_t *output_stream, 00471 svn_diff_t *diff, 00472 const char *original_path, 00473 const char *modified_path, 00474 const char *original_header, 00475 const char *modified_header, 00476 const char *header_encoding, 00477 apr_pool_t *pool); 00478 00479 /** Similar to svn_diff_file_output_unified2(), but with @a header_encoding 00480 * set to @c APR_LOCALE_CHARSET. 00481 * 00482 * @deprecated Provided for backward compatibility with the 1.2 API. 00483 */ 00484 svn_error_t * 00485 svn_diff_file_output_unified(svn_stream_t *output_stream, 00486 svn_diff_t *diff, 00487 const char *original_path, 00488 const char *modified_path, 00489 const char *original_header, 00490 const char *modified_header, 00491 apr_pool_t *pool); 00492 00493 00494 /** A convenience function to produce diff3 output from the 00495 * diff generated by svn_diff_file_diff3(). 00496 * 00497 * Output a @a diff between @a original_path, @a modified_path and 00498 * @a latest_path in merged format to @a output_file. Optionally supply 00499 * @a conflict_modified, @a conflict_original, @a conflict_separator and/or 00500 * @a conflict_latest to be displayed as conflict markers in the output. 00501 * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or 00502 * @a conflict_separator is @c NULL, a default marker will be displayed. 00503 * Set @a display_original_in_conflict and @a display_resolved_conflicts 00504 * as desired. Note that these options are mutually exclusive. 00505 */ 00506 svn_error_t * 00507 svn_diff_file_output_merge(svn_stream_t *output_stream, 00508 svn_diff_t *diff, 00509 const char *original_path, 00510 const char *modified_path, 00511 const char *latest_path, 00512 const char *conflict_original, 00513 const char *conflict_modified, 00514 const char *conflict_latest, 00515 const char *conflict_separator, 00516 svn_boolean_t display_original_in_conflict, 00517 svn_boolean_t display_resolved_conflicts, 00518 apr_pool_t *pool); 00519 00520 00521 #ifdef __cplusplus 00522 } 00523 #endif /* __cplusplus */ 00524 00525 #endif /* SVN_DIFF_H */