00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2004 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 * @since New in 1.1. 00063 * 00064 * Get libsvn_diff version information. 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 @c svn_diff_diff(), 00073 * @c svn_diff_diff3() and @c 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 svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token, 00115 void *diff_baton, 00116 svn_diff_datasource_e datasource); 00117 00118 /** A function for ordering the tokens, resembling 'strcmp' in functionality. 00119 * @a compare should contain the return value of the comparison: 00120 * If @a ltoken and @a rtoken are "equal", return 0. If @a ltoken is 00121 * "less than" @a rtoken, return a number < 0. If @a ltoken is 00122 * "greater than" @a rtoken, return a number > 0. 00123 */ 00124 svn_error_t *(*token_compare)(void *diff_baton, 00125 void *ltoken, 00126 void *rtoken, 00127 int *compare); 00128 00129 /** Free @a token from memory, the diff algorithm is done with it. */ 00130 void (*token_discard)(void *diff_baton, 00131 void *token); 00132 00133 /** Free *all* tokens from memory, they're no longer needed. */ 00134 void (*token_discard_all)(void *diff_baton); 00135 } svn_diff_fns_t; 00136 00137 00138 /* The Main Events */ 00139 00140 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00141 * return a diff object in @a *diff that represents a difference between 00142 * an "original" and "modified" datasource. Do all allocation in @a pool. 00143 */ 00144 svn_error_t *svn_diff_diff(svn_diff_t **diff, 00145 void *diff_baton, 00146 const svn_diff_fns_t *diff_fns, 00147 apr_pool_t *pool); 00148 00149 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00150 * return a diff object in @a *diff that represents a difference between 00151 * three datasources: "original", "modified", and "latest". Do all 00152 * allocation in @a pool. 00153 */ 00154 svn_error_t *svn_diff_diff3(svn_diff_t **diff, 00155 void *diff_baton, 00156 const svn_diff_fns_t *diff_fns, 00157 apr_pool_t *pool); 00158 00159 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00160 * return a diff object in @a *diff that represents a difference between 00161 * two datasources: "original" and "latest", adjusted to become a full 00162 * difference between "original", "modified" and "latest" using "ancestor". 00163 * Do all allocation in @a pool. 00164 */ 00165 svn_error_t *svn_diff_diff4(svn_diff_t **diff, 00166 void *diff_baton, 00167 const svn_diff_fns_t *diff_fns, 00168 apr_pool_t *pool); 00169 00170 00171 /* Utility functions */ 00172 00173 /** Determine if a diff object contains conflicts. If it does, return 00174 * @c TRUE, else return @c FALSE. 00175 */ 00176 svn_boolean_t 00177 svn_diff_contains_conflicts(svn_diff_t *diff); 00178 00179 00180 /** Determine if a diff object contains actual differences between the 00181 * datasources. If so, return @c TRUE, else return @c FALSE. 00182 */ 00183 svn_boolean_t 00184 svn_diff_contains_diffs(svn_diff_t *diff); 00185 00186 00187 00188 00189 /* Displaying Diffs */ 00190 00191 /** A vtable for displaying (or consuming) differences between datasources. 00192 * 00193 * Differences, similarities, and conflicts are described by lining up 00194 * "ranges" of data. 00195 * 00196 * Note: these callbacks describe data ranges in units of "tokens". 00197 * A "token" is whatever you've defined it to be in your datasource 00198 * @c svn_diff_fns_t vtable. 00199 */ 00200 typedef struct svn_diff_output_fns_t 00201 { 00202 /* Two-way and three-way diffs both call the first two output functions: */ 00203 00204 /** 00205 * If doing a two-way diff, then an *identical* data range was found 00206 * between the "original" and "modified" datasources. Specifically, 00207 * the match starts at @a original_start and goes for @a original_length 00208 * tokens in the original data, and at @a modified_start for 00209 * @a modified_length tokens in the modified data. 00210 * 00211 * If doing a three-way diff, then all three datasources have 00212 * matching data ranges. The range @a latest_start, @a latest_length in 00213 * the "latest" datasource is identical to the range @a original_start, 00214 * @a original_length in the original data, and is also identical to 00215 * the range @a modified_start, @a modified_length in the modified data. 00216 */ 00217 svn_error_t *(*output_common)(void *output_baton, 00218 apr_off_t original_start, 00219 apr_off_t original_length, 00220 apr_off_t modified_start, 00221 apr_off_t modified_length, 00222 apr_off_t latest_start, 00223 apr_off_t latest_length); 00224 00225 /** 00226 * If doing a two-way diff, then an *conflicting* data range was found 00227 * between the "original" and "modified" datasources. Specifically, 00228 * the conflict starts at @a original_start and goes for @a original_length 00229 * tokens in the original data, and at @a modified_start for 00230 * @a modified_length tokens in the modified data. 00231 * 00232 * If doing a three-way diff, then an identical data range was discovered 00233 * between the "original" and "latest" datasources, but this conflicts with 00234 * a range in the "modified" datasource. 00235 */ 00236 svn_error_t *(*output_diff_modified)(void *output_baton, 00237 apr_off_t original_start, 00238 apr_off_t original_length, 00239 apr_off_t modified_start, 00240 apr_off_t modified_length, 00241 apr_off_t latest_start, 00242 apr_off_t latest_length); 00243 00244 /* ------ The following callbacks are used by three-way diffs only --- */ 00245 00246 /** An identical data range was discovered between the "original" and 00247 * "modified" datasources, but this conflicts with a range in the 00248 * "latest" datasource. 00249 */ 00250 svn_error_t *(*output_diff_latest)(void *output_baton, 00251 apr_off_t original_start, 00252 apr_off_t original_length, 00253 apr_off_t modified_start, 00254 apr_off_t modified_length, 00255 apr_off_t latest_start, 00256 apr_off_t latest_length); 00257 00258 /** An identical data range was discovered between the "modified" and 00259 * "latest" datasources, but this conflicts with a range in the 00260 * "original" datasource. 00261 */ 00262 svn_error_t *(*output_diff_common)(void *output_baton, 00263 apr_off_t original_start, 00264 apr_off_t original_length, 00265 apr_off_t modified_start, 00266 apr_off_t modified_length, 00267 apr_off_t latest_start, 00268 apr_off_t latest_length); 00269 00270 /** All three datasources have conflicting data ranges. The range 00271 * @a latest_start, @a latest_length in the "latest" datasource conflicts 00272 * with the range @a original_start, @a original_length in the "original" 00273 * datasource, and also conflicts with the range @a modified_start, 00274 * @a modified_length in the "modified" datasource. 00275 * If there are common ranges in the "modified" and "latest" datasources 00276 * in this conflicting range, @a resolved_diff will contain a diff 00277 * which can be used to retrieve the common and conflicting ranges. 00278 */ 00279 svn_error_t *(*output_conflict)(void *output_baton, 00280 apr_off_t original_start, 00281 apr_off_t original_length, 00282 apr_off_t modified_start, 00283 apr_off_t modified_length, 00284 apr_off_t latest_start, 00285 apr_off_t latest_length, 00286 svn_diff_t *resolved_diff); 00287 } svn_diff_output_fns_t; 00288 00289 00290 /** Given a vtable of @a output_fns/@a output_baton for consuming 00291 * differences, output the differences in @a diff. 00292 */ 00293 svn_error_t * 00294 svn_diff_output(svn_diff_t *diff, 00295 void *output_baton, 00296 const svn_diff_output_fns_t *output_fns); 00297 00298 00299 00300 /* Diffs on files */ 00301 00302 /** A convenience function to produce a diff between two files. 00303 * 00304 * Return a diff object in @a *diff (allocated from @a pool) that represents 00305 * the difference between an @a original file and @a modified file. 00306 * (The file arguments must be full paths to the files.) 00307 */ 00308 svn_error_t * 00309 svn_diff_file_diff(svn_diff_t **diff, 00310 const char *original, 00311 const char *modified, 00312 apr_pool_t *pool); 00313 00314 00315 /** A convenience function to produce a diff between three files. 00316 * 00317 * Return a diff object in @a *diff (allocated from @a pool) that represents 00318 * the difference between an @a original file, @a modified file, and @a latest 00319 * file. (The file arguments must be full paths to the files.) 00320 */ 00321 svn_error_t * 00322 svn_diff_file_diff3(svn_diff_t **diff, 00323 const char *original, 00324 const char *modified, 00325 const char *latest, 00326 apr_pool_t *pool); 00327 00328 /** A convenience function to produce a diff between four files. 00329 * 00330 * Return a diff object in @a *diff (allocated from @a pool) that represents 00331 * the difference between an @a original file, @a modified file, @a latest 00332 * and @a ancestor file. (The file arguments must be full paths to the files.) 00333 */ 00334 svn_error_t * 00335 svn_diff_file_diff4(svn_diff_t **diff, 00336 const char *original, 00337 const char *modified, 00338 const char *latest, 00339 const char *ancestor, 00340 apr_pool_t *pool); 00341 00342 /** A convenience function to produce unified diff output from the 00343 * diff generated by @c svn_diff_file. 00344 * 00345 * Output a @a diff between @a original_path and @a modified_path in unified 00346 * context diff format to @a output_file. Optionally supply @a original_header 00347 * and/or @a modified_header to be displayed in the header of the output. 00348 * If @a original_header or @a modified_header is @c NULL, a default header 00349 * will be displayed, consisting of path and last modified time. 00350 */ 00351 svn_error_t * 00352 svn_diff_file_output_unified(svn_stream_t *output_stream, 00353 svn_diff_t *diff, 00354 const char *original_path, 00355 const char *modified_path, 00356 const char *original_header, 00357 const char *modified_header, 00358 apr_pool_t *pool); 00359 00360 00361 /** A convenience function to produce diff3 output from the 00362 * diff generated by @c svn_diff3_file. 00363 * 00364 * Output a @a diff between @a original_path, @a modified_path and 00365 * @a latest_path in merged format to @a output_file. Optionally supply 00366 * @a conflict_modified, @a conflict_original, @a conflict_separator and/or 00367 * @a conflict_latest to be displayed as conflict markers in the output. 00368 * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or 00369 * @a conflict_separator is @c NULL, a default marker will be displayed. 00370 * Set @a display_original_in_conflict and @a display_resolved_conflicts 00371 * as desired. Note that these options are mutually exclusive. 00372 */ 00373 svn_error_t * 00374 svn_diff_file_output_merge(svn_stream_t *output_stream, 00375 svn_diff_t *diff, 00376 const char *original_path, 00377 const char *modified_path, 00378 const char *latest_path, 00379 const char *conflict_original, 00380 const char *conflict_modified, 00381 const char *conflict_latest, 00382 const char *conflict_separator, 00383 svn_boolean_t display_original_in_conflict, 00384 svn_boolean_t display_resolved_conflicts, 00385 apr_pool_t *pool); 00386 00387 00388 #ifdef __cplusplus 00389 } 00390 #endif /* __cplusplus */ 00391 00392 #endif /* SVN_DIFF_H */