Main Page   Modules   Data Structures   File List   Data Fields   Globals  

svn_diff.h

Go to the documentation of this file.
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 */

Generated on Wed Oct 20 01:47:45 2004 for Subversion by doxygen1.2.18