Main Page   Modules   Data Structures   File List   Data Fields  

svn_diff.h

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  * 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   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 svn_diff_file_diff().
00344  *
00345  * @since New in 1.3.
00346  *
00347  * Output a @a diff between @a original_path and @a modified_path in unified
00348  * context diff format to @a output_file.  Optionally supply @a original_header
00349  * and/or @a modified_header to be displayed in the header of the output.
00350  * If @a original_header or @a modified_header is @c NULL, a default header 
00351  * will be displayed, consisting of path and last modified time.  Output
00352  * all headers and markers in @a header_encoding.
00353  */
00354 svn_error_t *
00355 svn_diff_file_output_unified2(svn_stream_t *output_stream,
00356                               svn_diff_t *diff,
00357                               const char *original_path,
00358                               const char *modified_path,
00359                               const char *original_header,
00360                               const char *modified_header,
00361                               const char *header_encoding,
00362                               apr_pool_t *pool);
00363 
00364 /** Similar to svn_diff_file_output_unified2(), but with @a header_encoding
00365  * set to @c APR_LOCALE_CHARSET.
00366  *
00367  * @deprecated Provided for backward compatibility with the 1.2 API.
00368  */
00369 svn_error_t *
00370 svn_diff_file_output_unified(svn_stream_t *output_stream,
00371                              svn_diff_t *diff,
00372                              const char *original_path,
00373                              const char *modified_path,
00374                              const char *original_header,
00375                              const char *modified_header,
00376                              apr_pool_t *pool);
00377 
00378 
00379 /** A convenience function to produce diff3 output from the
00380  * diff generated by svn_diff_file_diff3().
00381  *
00382  * Output a @a diff between @a original_path, @a modified_path and
00383  * @a latest_path in merged format to @a output_file.  Optionally supply
00384  * @a conflict_modified, @a conflict_original, @a conflict_separator and/or
00385  * @a conflict_latest to be displayed as conflict markers in the output.
00386  * If @a conflict_original, @a conflict_modified, @a conflict_latest and/or
00387  * @a conflict_separator is @c NULL, a default marker will be displayed.
00388  * Set @a display_original_in_conflict and @a display_resolved_conflicts
00389  * as desired.  Note that these options are mutually exclusive.
00390  */
00391 svn_error_t *
00392 svn_diff_file_output_merge(svn_stream_t *output_stream,
00393                            svn_diff_t *diff,
00394                            const char *original_path,
00395                            const char *modified_path,
00396                            const char *latest_path,
00397                            const char *conflict_original,
00398                            const char *conflict_modified,
00399                            const char *conflict_latest,
00400                            const char *conflict_separator,
00401                            svn_boolean_t display_original_in_conflict,
00402                            svn_boolean_t display_resolved_conflicts,
00403                            apr_pool_t *pool);
00404 
00405 
00406 #ifdef __cplusplus
00407 }
00408 #endif /* __cplusplus */
00409 
00410 #endif /* SVN_DIFF_H */

Generated on Wed Jun 7 14:05:12 2006 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002