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 Structures related to 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 00054 #ifdef __cplusplus 00055 extern "C" { 00056 #endif /* __cplusplus */ 00057 00058 00059 00060 /* Diffs. */ 00061 00062 /** An opaque type that represents a difference between either two or 00063 * three datasources. This object is returned by @c svn_diff_diff(), 00064 * @c svn_diff_diff3() and @c svn_diff_diff4 below, and consumed by a number of 00065 * other routines. 00066 */ 00067 typedef struct svn_diff_t svn_diff_t; 00068 00069 /** 00070 * There are four types of datasources. In GNU diff3 terminology, 00071 * the first three types correspond to the phrases "older", "mine", 00072 * and "yours". 00073 */ 00074 typedef enum svn_diff_datasource_e 00075 { 00076 /** The oldest form of the data. */ 00077 svn_diff_datasource_original, 00078 00079 /** The same data, but potentially changed by the user. */ 00080 svn_diff_datasource_modified, 00081 00082 /** The latest version of the data, possibly different than the 00083 * user's modified version. 00084 */ 00085 svn_diff_datasource_latest, 00086 00087 /** The common ancestor of original and modified. */ 00088 svn_diff_datasource_ancestor 00089 00090 } svn_diff_datasource_e; 00091 00092 00093 /** A vtable for reading data from the three datasources. */ 00094 typedef struct svn_diff_fns_t 00095 { 00096 /** Open the datasource of type @a datasource. */ 00097 svn_error_t *(*datasource_open)(void *diff_baton, 00098 svn_diff_datasource_e datasource); 00099 00100 /** Close the datasource of type @a datasource. */ 00101 svn_error_t *(*datasource_close)(void *diff_baton, 00102 svn_diff_datasource_e datasource); 00103 00104 /** Get the next "token" from the datasource of type @a datasource. */ 00105 svn_error_t *(*datasource_get_next_token)(apr_uint32_t *hash, void **token, 00106 void *diff_baton, 00107 svn_diff_datasource_e datasource); 00108 00109 /** A function for ordering the tokens, resembling 'strcmp' in functionality. 00110 * @a compare should contain the return value of the comparison: 00111 * If @a ltoken and @a rtoken are "equal", return 0. If @a ltoken is 00112 * "less than" @a rtoken, return a number < 0. If @a ltoken is 00113 * "greater than" @a rtoken, return a number > 0. 00114 */ 00115 svn_error_t *(*token_compare)(void *diff_baton, 00116 void *ltoken, 00117 void *rtoken, 00118 int *compare); 00119 00120 /** Free @a token from memory, the diff algorithm is done with it. */ 00121 void (*token_discard)(void *diff_baton, 00122 void *token); 00123 00124 /** Free *all* tokens from memory, they're no longer needed. */ 00125 void (*token_discard_all)(void *diff_baton); 00126 } svn_diff_fns_t; 00127 00128 00129 /* The Main Events */ 00130 00131 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00132 * return a diff object in @a *diff that represents a difference between 00133 * an "original" and "modified" datasource. Do all allocation in @a pool. 00134 */ 00135 svn_error_t *svn_diff_diff(svn_diff_t **diff, 00136 void *diff_baton, 00137 const svn_diff_fns_t *diff_fns, 00138 apr_pool_t *pool); 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 * three datasources: "original", "modified", and "latest". Do all 00143 * allocation in @a pool. 00144 */ 00145 svn_error_t *svn_diff_diff3(svn_diff_t **diff, 00146 void *diff_baton, 00147 const svn_diff_fns_t *diff_fns, 00148 apr_pool_t *pool); 00149 00150 /** Given a vtable of @a diff_fns/@a diff_baton for reading datasources, 00151 * return a diff object in @a *diff that represents a difference between 00152 * two datasources: "original" and "latest", adjusted to become a full 00153 * difference between "original", "modified" and "latest" using "ancestor". 00154 * Do all allocation in @a pool. 00155 */ 00156 svn_error_t *svn_diff_diff4(svn_diff_t **diff, 00157 void *diff_baton, 00158 const svn_diff_fns_t *diff_fns, 00159 apr_pool_t *pool); 00160 00161 00162 /* Utility functions */ 00163 00164 /** Determine if a diff object contains conflicts. If it does, return 00165 * @c TRUE, else return @c FALSE. 00166 */ 00167 svn_boolean_t 00168 svn_diff_contains_conflicts(svn_diff_t *diff); 00169 00170 00171 /** Determine if a diff object contains actual differences between the 00172 * datasources. If so, return @c TRUE, else return @c FALSE. 00173 */ 00174 svn_boolean_t 00175 svn_diff_contains_diffs(svn_diff_t *diff); 00176 00177 00178 00179 00180 /* Displaying Diffs */ 00181 00182 /** A vtable for displaying (or consuming) differences between datasources. 00183 * 00184 * Differences, similarities, and conflicts are described by lining up 00185 * "ranges" of data. 00186 * 00187 * Note: these callbacks describe data ranges in units of "tokens". 00188 * A "token" is whatever you've defined it to be in your datasource 00189 * @c svn_diff_fns_t vtable. 00190 */ 00191 typedef struct svn_diff_output_fns_t 00192 { 00193 /* Two-way and three-way diffs both call the first two output functions: */ 00194 00195 /** 00196 * If doing a two-way diff, then an *identical* data range was found 00197 * between the "original" and "modified" datasources. Specifically, 00198 * the match starts at @a original_start and goes for @a original_length 00199 * tokens in the original data, and at @a modified_start for 00200 * @a modified_length tokens in the modified data. 00201 * 00202 * If doing a three-way diff, then all three datasources have 00203 * matching data ranges. The range @a latest_start, @a latest_length in 00204 * the "latest" datasource is identical to the range @a original_start, 00205 * @a original_length in the original data, and is also identical to 00206 * the range @a modified_start, @a modified_length in the modified data. 00207 */ 00208 svn_error_t *(*output_common)(void *output_baton, 00209 apr_off_t original_start, 00210 apr_off_t original_length, 00211 apr_off_t modified_start, 00212 apr_off_t modified_length, 00213 apr_off_t latest_start, 00214 apr_off_t latest_length); 00215 00216 /** 00217 * If doing a two-way diff, then an *conflicting* data range was found 00218 * between the "original" and "modified" datasources. Specifically, 00219 * the conflict starts at @a original_start and goes for @a original_length 00220 * tokens in the original data, and at @a modified_start for 00221 * @a modified_length tokens in the modified data. 00222 * 00223 * If doing a three-way diff, then an identical data range was discovered 00224 * between the "original" and "latest" datasources, but this conflicts with 00225 * a range in the "modified" datasource. 00226 */ 00227 svn_error_t *(*output_diff_modified)(void *output_baton, 00228 apr_off_t original_start, 00229 apr_off_t original_length, 00230 apr_off_t modified_start, 00231 apr_off_t modified_length, 00232 apr_off_t latest_start, 00233 apr_off_t latest_length); 00234 00235 /* ------ The following callbacks are used by three-way diffs only --- */ 00236 00237 /** An identical data range was discovered between the "original" and 00238 * "modified" datasources, but this conflicts with a range in the 00239 * "latest" datasource. 00240 */ 00241 svn_error_t *(*output_diff_latest)(void *output_baton, 00242 apr_off_t original_start, 00243 apr_off_t original_length, 00244 apr_off_t modified_start, 00245 apr_off_t modified_length, 00246 apr_off_t latest_start, 00247 apr_off_t latest_length); 00248 00249 /** An identical data range was discovered between the "modified" and 00250 * "latest" datasources, but this conflicts with a range in the 00251 * "original" datasource. 00252 */ 00253 svn_error_t *(*output_diff_common)(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 /** All three datasources have conflicting data ranges. The range 00262 * @a latest_start, @a latest_length in the "latest" datasource conflicts 00263 * with the range @a original_start, @a original_length in the "original" 00264 * datasource, and also conflicts with the range @a modified_start, 00265 * @a modified_length in the "modified" datasource. 00266 * If there are common ranges in the "modified" and "latest" datasources 00267 * in this conflicting range, @a resolved_diff will contain a diff 00268 * which can be used to retrieve the common and conflicting ranges. 00269 */ 00270 svn_error_t *(*output_conflict)(void *output_baton, 00271 apr_off_t original_start, 00272 apr_off_t original_length, 00273 apr_off_t modified_start, 00274 apr_off_t modified_length, 00275 apr_off_t latest_start, 00276 apr_off_t latest_length, 00277 svn_diff_t *resolved_diff); 00278 } svn_diff_output_fns_t; 00279 00280 00281 /** Given a vtable of @a output_fns/@a output_baton for consuming 00282 * differences, output the differences in @a diff. 00283 */ 00284 svn_error_t * 00285 svn_diff_output(svn_diff_t *diff, 00286 void *output_baton, 00287 const svn_diff_output_fns_t *output_fns); 00288 00289 00290 00291 /* Diffs on files */ 00292 00293 /** A convenience function to produce a diff between two files. 00294 * 00295 * Return a diff object in @a *diff (allocated from @a pool) that represents 00296 * the difference between an @a original file and @a modified file. 00297 * (The file arguments must be full paths to the files.) 00298 */ 00299 svn_error_t * 00300 svn_diff_file_diff(svn_diff_t **diff, 00301 const char *original, 00302 const char *modified, 00303 apr_pool_t *pool); 00304 00305 00306 /** A convenience function to produce a diff between three files. 00307 * 00308 * Return a diff object in @a *diff (allocated from @a pool) that represents 00309 * the difference between an @a original file, @a modified file, and @a latest 00310 * file. (The file arguments must be full paths to the files.) 00311 */ 00312 svn_error_t * 00313 svn_diff_file_diff3(svn_diff_t **diff, 00314 const char *original, 00315 const char *modified, 00316 const char *latest, 00317 apr_pool_t *pool); 00318 00319 /** A convenience function to produce a diff between four files. 00320 * 00321 * Return a diff object in @a *diff (allocated from @a pool) that represents 00322 * the difference between an @a original file, @a modified file, @a latest 00323 * and @a ancestor file. (The file arguments must be full paths to the files.) 00324 */ 00325 svn_error_t * 00326 svn_diff_file_diff4(svn_diff_t **diff, 00327 const char *original, 00328 const char *modified, 00329 const char *latest, 00330 const char *ancestor, 00331 apr_pool_t *pool); 00332 00333 /** A convenience function to produce unified diff output from the 00334 * diff generated by @c svn_diff_file. 00335 * 00336 * Output a @a diff between @a original_path and @a modified_path in unified 00337 * context diff format to @a output_file. Optionally supply @a original_header 00338 * and/or @a modified_header to be displayed in the header of the output. 00339 * If @a original_header or @a modified_header is @c NULL, a default header 00340 * will be displayed, consisting of path and last modified time. 00341 */ 00342 svn_error_t * 00343 svn_diff_file_output_unified(svn_stream_t *output_stream, 00344 svn_diff_t *diff, 00345 const char *original_path, 00346 const char *modified_path, 00347 const char *original_header, 00348 const char *modified_header, 00349 apr_pool_t *pool); 00350 00351 00352 /** A convenience function to produce diff3 output from the 00353 * diff generated by @c svn_diff3_file. 00354 * 00355 * Output a @a diff between @a original_path, @a modified_path and 00356 * @a latest_path in merged format to @a output_file. Optionally supply 00357 * @a conflict_modified, @a conflict_original, @a conflict_separator and/or 00358 * @a conflict_latest to be displayed as conflict markers in the output. 00359 * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or 00360 * @a conflict_separator is @c NULL, a default marker will be displayed. 00361 * Set @a display_original_in_conflict and @a display_resolved_conflicts 00362 * as desired. Note that these options are mutually exclusive. 00363 */ 00364 svn_error_t * 00365 svn_diff_file_output_merge(svn_stream_t *output_stream, 00366 svn_diff_t *diff, 00367 const char *original_path, 00368 const char *modified_path, 00369 const char *latest_path, 00370 const char *conflict_original, 00371 const char *conflict_modified, 00372 const char *conflict_latest, 00373 const char *conflict_separator, 00374 svn_boolean_t display_original_in_conflict, 00375 svn_boolean_t display_resolved_conflicts, 00376 apr_pool_t *pool); 00377 00378 00379 #ifdef __cplusplus 00380 } 00381 #endif /* __cplusplus */ 00382 00383 #endif /* SVN_DIFF_H */