Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_diff.h

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

Generated on Sat Jun 30 13:41:55 2007 for Subversion by  doxygen 1.3.9.1