1 1dfba055 2020-10-07 stsp /* Generic infrastructure to implement various diff algorithms. */
  2 1dfba055 2020-10-07 stsp /*
  3 1dfba055 2020-10-07 stsp  * Copyright (c) 2020 Neels Hofmeyr <neels@hofmeyr.de>
  4 1dfba055 2020-10-07 stsp  *
  5 1dfba055 2020-10-07 stsp  * Permission to use, copy, modify, and distribute this software for any
  6 1dfba055 2020-10-07 stsp  * purpose with or without fee is hereby granted, provided that the above
  7 1dfba055 2020-10-07 stsp  * copyright notice and this permission notice appear in all copies.
  8 1dfba055 2020-10-07 stsp  *
  9 1dfba055 2020-10-07 stsp  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 10 1dfba055 2020-10-07 stsp  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 11 1dfba055 2020-10-07 stsp  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 12 1dfba055 2020-10-07 stsp  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 13 1dfba055 2020-10-07 stsp  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 14 1dfba055 2020-10-07 stsp  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 15 1dfba055 2020-10-07 stsp  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 16 1dfba055 2020-10-07 stsp  */
 17 1dfba055 2020-10-07 stsp 
 18 1dfba055 2020-10-07 stsp struct diff_range {
 19 1dfba055 2020-10-07 stsp 	int start;
 20 1dfba055 2020-10-07 stsp 	int end;
 21 1dfba055 2020-10-07 stsp };
 22 1dfba055 2020-10-07 stsp 
 23 1dfba055 2020-10-07 stsp /* List of all possible return codes of a diff invocation. */
 24 1dfba055 2020-10-07 stsp #define DIFF_RC_USE_DIFF_ALGO_FALLBACK	-1
 25 1dfba055 2020-10-07 stsp #define DIFF_RC_OK			0
 26 1dfba055 2020-10-07 stsp /* Any positive return values are errno values from sys/errno.h */
 27 1dfba055 2020-10-07 stsp 
 28 1dfba055 2020-10-07 stsp struct diff_atom;
 29 1dfba055 2020-10-07 stsp 
 30 1dfba055 2020-10-07 stsp /* For each file, there is a "root" struct diff_data referencing the entire
 31 1dfba055 2020-10-07 stsp  * file, which the atoms are parsed from. In recursion of diff algorithm, there
 32 1dfba055 2020-10-07 stsp  * may be "child" struct diff_data only referencing a subsection of the file,
 33 1dfba055 2020-10-07 stsp  * re-using the atoms parsing. For "root" structs, atoms_allocated will be
 34 1dfba055 2020-10-07 stsp  * nonzero, indicating that the array of atoms is owned by that struct. For
 35 1dfba055 2020-10-07 stsp  * "child" structs, atoms_allocated == 0, to indicate that the struct is
 36 1dfba055 2020-10-07 stsp  * referencing a subset of atoms. */
 37 1dfba055 2020-10-07 stsp struct diff_data {
 38 1dfba055 2020-10-07 stsp 	FILE *f;		/* if root diff_data and not memory-mapped */
 39 1dfba055 2020-10-07 stsp 	off_t pos;		/* if not memory-mapped */
 40 1dfba055 2020-10-07 stsp 	const uint8_t *data;	/* if memory-mapped */
 41 1dfba055 2020-10-07 stsp 	off_t len;
 42 1dfba055 2020-10-07 stsp 
 43 1dfba055 2020-10-07 stsp 	ARRAYLIST(struct diff_atom) atoms;
 44 1dfba055 2020-10-07 stsp 	struct diff_data *root;
 45 6c8c5d3f 2020-10-12 neels 	struct diff_data *current;
 46 6c8c5d3f 2020-10-12 neels 	void *algo_data;
 47 1dfba055 2020-10-07 stsp 
 48 1dfba055 2020-10-07 stsp 	int diff_flags;
 49 60b6e08b 2020-10-12 neels 
 50 60b6e08b 2020-10-12 neels 	int err;
 51 1dfba055 2020-10-07 stsp };
 52 1dfba055 2020-10-07 stsp 
 53 1dfba055 2020-10-07 stsp #define DIFF_FLAG_IGNORE_WHITESPACE	0x00000001
 54 13e2caa3 2020-10-17 stsp #define DIFF_FLAG_SHOW_PROTOTYPES	0x00000002
 55 1dfba055 2020-10-07 stsp 
 56 1dfba055 2020-10-07 stsp void diff_data_free(struct diff_data *diff_data);
 57 1dfba055 2020-10-07 stsp 
 58 1dfba055 2020-10-07 stsp struct diff_chunk;
 59 1dfba055 2020-10-07 stsp typedef ARRAYLIST(struct diff_chunk) diff_chunk_arraylist_t;
 60 1dfba055 2020-10-07 stsp 
 61 1dfba055 2020-10-07 stsp struct diff_result {
 62 1dfba055 2020-10-07 stsp 	int rc;
 63 c16dde50 2020-10-22 stsp 
 64 c16dde50 2020-10-22 stsp 	/*
 65 c16dde50 2020-10-22 stsp 	 * Pointers to diff data passed in via diff_main.
 66 c16dde50 2020-10-22 stsp 	 * Do not free these diff_data before freeing the diff_result struct.
 67 c16dde50 2020-10-22 stsp 	 */
 68 c16dde50 2020-10-22 stsp 	struct diff_data *left;
 69 c16dde50 2020-10-22 stsp 	struct diff_data *right;
 70 c16dde50 2020-10-22 stsp 
 71 1dfba055 2020-10-07 stsp 	diff_chunk_arraylist_t chunks;
 72 1dfba055 2020-10-07 stsp };
 73 1dfba055 2020-10-07 stsp 
 74 1dfba055 2020-10-07 stsp struct diff_state;
 75 1dfba055 2020-10-07 stsp 
 76 c16dde50 2020-10-22 stsp /* Signature of a utility function to divide a file into diff atoms.
 77 1dfba055 2020-10-07 stsp  * An example is diff_atomize_text_by_line() in diff_atomize_text.c.
 78 1dfba055 2020-10-07 stsp  *
 79 1dfba055 2020-10-07 stsp  * func_data: context pointer (free to be used by implementation).
 80 c16dde50 2020-10-22 stsp  * d: struct diff_data with d->data and d->len already set up, and
 81 c16dde50 2020-10-22 stsp  * d->atoms to be created.
 82 1dfba055 2020-10-07 stsp  */
 83 c16dde50 2020-10-22 stsp typedef int (*diff_atomize_func_t)(void *func_data, struct diff_data *d);
 84 1dfba055 2020-10-07 stsp 
 85 c16dde50 2020-10-22 stsp extern int diff_atomize_text_by_line(void *func_data, struct diff_data *d);
 86 1dfba055 2020-10-07 stsp 
 87 1dfba055 2020-10-07 stsp struct diff_algo_config;
 88 1dfba055 2020-10-07 stsp typedef int (*diff_algo_impl_t)(
 89 1dfba055 2020-10-07 stsp 	const struct diff_algo_config *algo_config, struct diff_state *state);
 90 1dfba055 2020-10-07 stsp 
 91 1dfba055 2020-10-07 stsp /* Form a result with all left-side removed and all right-side added, i.e. no
 92 1dfba055 2020-10-07 stsp  * actual diff algorithm involved. */
 93 1dfba055 2020-10-07 stsp int diff_algo_none(const struct diff_algo_config *algo_config,
 94 0c70b22b 2020-10-11 neels 	struct diff_state *state);
 95 1dfba055 2020-10-07 stsp 
 96 1dfba055 2020-10-07 stsp /* Myers Diff tracing from the start all the way through to the end, requiring
 97 1dfba055 2020-10-07 stsp  * quadratic amounts of memory. This can fail if the required space surpasses
 98 1dfba055 2020-10-07 stsp  * algo_config->permitted_state_size. */
 99 1dfba055 2020-10-07 stsp extern int diff_algo_myers(const struct diff_algo_config *algo_config,
100 0c70b22b 2020-10-11 neels 	struct diff_state *state);
101 1dfba055 2020-10-07 stsp 
102 1dfba055 2020-10-07 stsp /* Myers "Divide et Impera": tracing forwards from the start and backwards from
103 1dfba055 2020-10-07 stsp  * the end to find a midpoint that divides the problem into smaller chunks.
104 1dfba055 2020-10-07 stsp  * Requires only linear amounts of memory. */
105 1dfba055 2020-10-07 stsp extern int diff_algo_myers_divide(
106 1dfba055 2020-10-07 stsp 	const struct diff_algo_config *algo_config, struct diff_state *state);
107 1dfba055 2020-10-07 stsp 
108 1dfba055 2020-10-07 stsp /* Patience Diff algorithm, which divides a larger diff into smaller chunks. For
109 1dfba055 2020-10-07 stsp  * very specific scenarios, it may lead to a complete diff result by itself, but
110 1dfba055 2020-10-07 stsp  * needs a fallback algo to solve chunks that don't have common-unique atoms. */
111 1dfba055 2020-10-07 stsp extern int diff_algo_patience(
112 1dfba055 2020-10-07 stsp 	const struct diff_algo_config *algo_config, struct diff_state *state);
113 1dfba055 2020-10-07 stsp 
114 1dfba055 2020-10-07 stsp /* Diff algorithms to use, possibly nested. For example:
115 1dfba055 2020-10-07 stsp  *
116 1dfba055 2020-10-07 stsp  * struct diff_algo_config myers, patience, myers_divide;
117 1dfba055 2020-10-07 stsp  *
118 1dfba055 2020-10-07 stsp  * myers = (struct diff_algo_config){
119 1dfba055 2020-10-07 stsp  *         .impl = diff_algo_myers,
120 1dfba055 2020-10-07 stsp  *         .permitted_state_size = 32 * 1024 * 1024,
121 1dfba055 2020-10-07 stsp  *         // When too large, do diff_algo_patience:
122 1dfba055 2020-10-07 stsp  *         .fallback_algo = &patience,
123 1dfba055 2020-10-07 stsp  * };
124 1dfba055 2020-10-07 stsp  *
125 1dfba055 2020-10-07 stsp  * const struct diff_algo_config patience = (struct diff_algo_config){
126 1dfba055 2020-10-07 stsp  * 	.impl = diff_algo_patience,
127 1dfba055 2020-10-07 stsp  * 	// After subdivision, do Patience again:
128 1dfba055 2020-10-07 stsp  * 	.inner_algo = &patience,
129 1dfba055 2020-10-07 stsp  * 	// If subdivision failed, do Myers Divide et Impera:
130 1dfba055 2020-10-07 stsp  * 	.fallback_algo = &myers_then_myers_divide,
131 1dfba055 2020-10-07 stsp  * };
132 1dfba055 2020-10-07 stsp  * 
133 1dfba055 2020-10-07 stsp  * const struct diff_algo_config myers_divide = (struct diff_algo_config){
134 1dfba055 2020-10-07 stsp  * 	.impl = diff_algo_myers_divide,
135 1dfba055 2020-10-07 stsp  * 	// When division succeeded, start from the top:
136 1dfba055 2020-10-07 stsp  * 	.inner_algo = &myers_then_myers_divide,
137 1dfba055 2020-10-07 stsp  * 	// (fallback_algo = NULL implies diff_algo_none).
138 1dfba055 2020-10-07 stsp  * };
139 1dfba055 2020-10-07 stsp  * struct diff_config config = {
140 1dfba055 2020-10-07 stsp  *         .algo = &myers,
141 1dfba055 2020-10-07 stsp  *         ...
142 1dfba055 2020-10-07 stsp  * };
143 1dfba055 2020-10-07 stsp  * diff_main(&config, ...);
144 1dfba055 2020-10-07 stsp  */
145 1dfba055 2020-10-07 stsp struct diff_algo_config {
146 1dfba055 2020-10-07 stsp 	diff_algo_impl_t impl;
147 1dfba055 2020-10-07 stsp 
148 1dfba055 2020-10-07 stsp 	/* Fail this algo if it would use more than this amount of memory, and
149 1dfba055 2020-10-07 stsp 	 * instead use fallback_algo (diff_algo_myers). permitted_state_size ==
150 1dfba055 2020-10-07 stsp 	 * 0 means no limitation. */
151 1dfba055 2020-10-07 stsp 	size_t permitted_state_size;
152 1dfba055 2020-10-07 stsp 
153 1dfba055 2020-10-07 stsp 	/* For algorithms that divide into smaller chunks, use this algorithm to
154 1dfba055 2020-10-07 stsp 	 * solve the divided chunks. */
155 1dfba055 2020-10-07 stsp 	const struct diff_algo_config *inner_algo;
156 1dfba055 2020-10-07 stsp 
157 1dfba055 2020-10-07 stsp 	/* If the algorithm fails (e.g. diff_algo_myers_if_small needs too large
158 1dfba055 2020-10-07 stsp 	 * state, or diff_algo_patience can't find any common-unique atoms),
159 1dfba055 2020-10-07 stsp 	 * then use this algorithm instead. */
160 1dfba055 2020-10-07 stsp 	const struct diff_algo_config *fallback_algo;
161 1dfba055 2020-10-07 stsp };
162 1dfba055 2020-10-07 stsp 
163 1dfba055 2020-10-07 stsp struct diff_config {
164 1dfba055 2020-10-07 stsp 	diff_atomize_func_t atomize_func;
165 1dfba055 2020-10-07 stsp 	void *atomize_func_data;
166 1dfba055 2020-10-07 stsp 
167 1dfba055 2020-10-07 stsp 	const struct diff_algo_config *algo;
168 1dfba055 2020-10-07 stsp 
169 1dfba055 2020-10-07 stsp 	/* How deep to step into subdivisions of a source file, a paranoia /
170 1dfba055 2020-10-07 stsp 	 * safety measure to guard against infinite loops through diff
171 1dfba055 2020-10-07 stsp 	 * algorithms. When the maximum recursion is reached, employ
172 1dfba055 2020-10-07 stsp 	 * diff_algo_none (i.e. remove all left atoms and add all right atoms).
173 1dfba055 2020-10-07 stsp 	 */
174 1dfba055 2020-10-07 stsp 	unsigned int max_recursion_depth;
175 1dfba055 2020-10-07 stsp };
176 1dfba055 2020-10-07 stsp 
177 c16dde50 2020-10-22 stsp int diff_atomize_file(struct diff_data *d, const struct diff_config *config,
178 c16dde50 2020-10-22 stsp 		      FILE *f, const uint8_t *data, off_t len, int diff_flags);
179 1dfba055 2020-10-07 stsp struct diff_result *diff_main(const struct diff_config *config,
180 c16dde50 2020-10-22 stsp 			      struct diff_data *left,
181 c16dde50 2020-10-22 stsp 			      struct diff_data *right);
182 1dfba055 2020-10-07 stsp void diff_result_free(struct diff_result *result);