iterator.h 8.77 KB
Newer Older
1
/*
Edward Thomson committed
2
 * Copyright (C) the libgit2 contributors. All rights reserved.
3 4 5 6 7 8 9 10
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
 */
#ifndef INCLUDE_iterator_h__
#define INCLUDE_iterator_h__

#include "common.h"
11

12
#include "git2/index.h"
13
#include "vector.h"
14
#include "buffer.h"
15
#include "ignore.h"
16

17 18 19
typedef struct git_iterator git_iterator;

typedef enum {
20 21 22 23
	GIT_ITERATOR_TYPE_EMPTY = 0,
	GIT_ITERATOR_TYPE_TREE = 1,
	GIT_ITERATOR_TYPE_INDEX = 2,
	GIT_ITERATOR_TYPE_WORKDIR = 3,
24
	GIT_ITERATOR_TYPE_FS = 4,
25 26
} git_iterator_type_t;

27
typedef enum {
28
	/** ignore case for entry sort order */
29
	GIT_ITERATOR_IGNORE_CASE = (1u << 0),
30
	/** force case sensitivity for entry sort order */
31
	GIT_ITERATOR_DONT_IGNORE_CASE = (1u << 1),
32
	/** return tree items in addition to blob items */
33
	GIT_ITERATOR_INCLUDE_TREES    = (1u << 2),
34
	/** don't flatten trees, requiring advance_into (implies INCLUDE_TREES) */
35 36 37
	GIT_ITERATOR_DONT_AUTOEXPAND  = (1u << 3),
	/** convert precomposed unicode to decomposed unicode */
	GIT_ITERATOR_PRECOMPOSE_UNICODE = (1u << 4),
38 39
	/** never convert precomposed unicode to decomposed unicode */
	GIT_ITERATOR_DONT_PRECOMPOSE_UNICODE = (1u << 5),
40
	/** include conflicts */
41
	GIT_ITERATOR_INCLUDE_CONFLICTS = (1u << 6),
42 43
} git_iterator_flag_t;

44 45 46 47 48 49 50
typedef enum {
	GIT_ITERATOR_STATUS_NORMAL = 0,
	GIT_ITERATOR_STATUS_IGNORED = 1,
	GIT_ITERATOR_STATUS_EMPTY = 2,
	GIT_ITERATOR_STATUS_FILTERED = 3
} git_iterator_status_t;

51 52 53 54
typedef struct {
	const char *start;
	const char *end;

55 56
	/* paths to include in the iterator (literal).  if set, any paths not
	 * listed here will be excluded from iteration.
57
	 */
58
	git_strarray pathlist;
59

60 61 62 63 64 65
	/* flags, from above */
	unsigned int flags;
} git_iterator_options;

#define GIT_ITERATOR_OPTIONS_INIT {0}

66
typedef struct {
67 68
	int (*current)(const git_index_entry **, git_iterator *);
	int (*advance)(const git_index_entry **, git_iterator *);
69
	int (*advance_into)(const git_index_entry **, git_iterator *);
70 71
	int (*advance_over)(
		const git_index_entry **, git_iterator_status_t *, git_iterator *);
72
	int (*reset)(git_iterator *);
73
	void (*free)(git_iterator *);
74 75 76 77 78
} git_iterator_callbacks;

struct git_iterator {
	git_iterator_type_t type;
	git_iterator_callbacks *cb;
79

80
	git_repository *repo;
81
	git_index *index;
82

83
	char *start;
84 85
	size_t start_len;

86
	char *end;
87 88
	size_t end_len;

89 90
	bool started;
	bool ended;
91
	git_vector pathlist;
92
	size_t pathlist_walk_idx;
93 94
	int (*strcomp)(const char *a, const char *b);
	int (*strncomp)(const char *a, const char *b, size_t n);
95
	int (*prefixcomp)(const char *str, const char *prefix);
96
	int (*entry_srch)(const void *key, const void *array_member);
97
	size_t stat_calls;
98
	unsigned int flags;
99 100
};

101
extern int git_iterator_for_nothing(
102
	git_iterator **out,
103
	git_iterator_options *options);
104

105 106 107
/* tree iterators will match the ignore_case value from the index of the
 * repository, unless you override with a non-zero flag value
 */
108
extern int git_iterator_for_tree(
109 110
	git_iterator **out,
	git_tree *tree,
111
	git_iterator_options *options);
112

113 114 115
/* index iterators will take the ignore_case value from the index; the
 * ignore_case flags are not used
 */
116
extern int git_iterator_for_index(
117
	git_iterator **out,
118
	git_repository *repo,
119
	git_index *index,
120
	git_iterator_options *options);
121

122 123 124 125
extern int git_iterator_for_workdir_ext(
	git_iterator **out,
	git_repository *repo,
	const char *repo_workdir,
126 127
	git_index *index,
	git_tree *tree,
128
	git_iterator_options *options);
129

130 131 132
/* workdir iterators will match the ignore_case value from the index of the
 * repository, unless you override with a non-zero flag value
 */
133
GIT_INLINE(int) git_iterator_for_workdir(
134 135
	git_iterator **out,
	git_repository *repo,
136 137
	git_index *index,
	git_tree *tree,
138
	git_iterator_options *options)
139
{
140
	return git_iterator_for_workdir_ext(out, repo, NULL, index, tree, options);
141
}
142

143 144 145 146 147 148
/* for filesystem iterators, you have to explicitly pass in the ignore_case
 * behavior that you desire
 */
extern int git_iterator_for_filesystem(
	git_iterator **out,
	const char *root,
149
	git_iterator_options *options);
150

151 152
extern void git_iterator_free(git_iterator *iter);

153 154 155 156 157 158
/* Return a git_index_entry structure for the current value the iterator
 * is looking at or NULL if the iterator is at the end.
 *
 * The entry may noy be fully populated.  Tree iterators will only have a
 * value mode, OID, and path.  Workdir iterators will not have an OID (but
 * you can use `git_iterator_current_oid()` to calculate it on demand).
159 160
 *
 * You do not need to free the entry.  It is still "owned" by the iterator.
161 162
 * Once you call `git_iterator_advance()` then the old entry is no longer
 * guaranteed to be valid - it may be freed or just overwritten in place.
163 164
 */
GIT_INLINE(int) git_iterator_current(
165
	const git_index_entry **entry, git_iterator *iter)
166
{
167
	return iter->cb->current(entry, iter);
168 169
}

170 171 172 173 174 175 176
/**
 * Advance to the next item for the iterator.
 *
 * If GIT_ITERATOR_INCLUDE_TREES is set, this may be a tree item.  If
 * GIT_ITERATOR_DONT_AUTOEXPAND is set, calling this again when on a tree
 * item will skip over all the items under that tree.
 */
177
GIT_INLINE(int) git_iterator_advance(
178
	const git_index_entry **entry, git_iterator *iter)
179
{
180
	return iter->cb->advance(entry, iter);
181 182
}

183 184 185 186 187 188 189 190 191 192 193
/**
 * Iterate into a tree item (when GIT_ITERATOR_DONT_AUTOEXPAND is set).
 *
 * git_iterator_advance() steps through all items being iterated over
 * (either with or without trees, depending on GIT_ITERATOR_INCLUDE_TREES),
 * but if GIT_ITERATOR_DONT_AUTOEXPAND is set, it will skip to the next
 * sibling of a tree instead of going to the first child of the tree.  In
 * that case, use this function to advance to the first child of the tree.
 *
 * If the current item is not a tree, this is a no-op.
 *
194 195 196
 * For filesystem and working directory iterators, a tree (i.e. directory)
 * can be empty.  In that case, this function returns GIT_ENOTFOUND and
 * does not advance.  That can't happen for tree and index iterators.
197 198 199 200 201 202 203
 */
GIT_INLINE(int) git_iterator_advance_into(
	const git_index_entry **entry, git_iterator *iter)
{
	return iter->cb->advance_into(entry, iter);
}

204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
/* Advance over a directory and check if it contains no files or just
 * ignored files.
 *
 * In a tree or the index, all directories will contain files, but in the
 * working directory it is possible to have an empty directory tree or a
 * tree that only contains ignored files.  Many Git operations treat these
 * cases specially.  This advances over a directory (presumably an
 * untracked directory) but checks during the scan if there are any files
 * and any non-ignored files.
 */
GIT_INLINE(int) git_iterator_advance_over(
	const git_index_entry **entry,
	git_iterator_status_t *status,
	git_iterator *iter)
{
219
	return iter->cb->advance_over(entry, status, iter);
220 221
}

222 223 224
/**
 * Go back to the start of the iteration.
 */
225 226 227 228 229 230 231 232 233
GIT_INLINE(int) git_iterator_reset(git_iterator *iter)
{
	return iter->cb->reset(iter);
}

/**
 * Go back to the start of the iteration after updating the `start` and
 * `end` pathname boundaries of the iteration.
 */
Edward Thomson committed
234 235
extern int git_iterator_reset_range(
	git_iterator *iter, const char *start, const char *end);
236

237 238 239 240 241
GIT_INLINE(git_iterator_type_t) git_iterator_type(git_iterator *iter)
{
	return iter->type;
}

Russell Belfer committed
242 243 244 245 246
GIT_INLINE(git_repository *) git_iterator_owner(git_iterator *iter)
{
	return iter->repo;
}

247 248 249 250 251
GIT_INLINE(git_index *) git_iterator_index(git_iterator *iter)
{
	return iter->index;
}

252 253 254 255 256 257 258 259 260 261
GIT_INLINE(git_iterator_flag_t) git_iterator_flags(git_iterator *iter)
{
	return iter->flags;
}

GIT_INLINE(bool) git_iterator_ignore_case(git_iterator *iter)
{
	return ((iter->flags & GIT_ITERATOR_IGNORE_CASE) != 0);
}

Edward Thomson committed
262 263
extern void git_iterator_set_ignore_case(
	git_iterator *iter, bool ignore_case);
264

265
extern int git_iterator_current_tree_entry(
266
	const git_tree_entry **entry_out, git_iterator *iter);
267

268
extern int git_iterator_current_parent_tree(
269
	const git_tree **tree_out, git_iterator *iter, size_t depth);
270

271
extern bool git_iterator_current_is_ignored(git_iterator *iter);
272

273 274
extern bool git_iterator_current_tree_is_ignored(git_iterator *iter);

275
/**
276 277 278
 * Get full path of the current item from a workdir iterator.  This will
 * return NULL for a non-workdir iterator.  The git_buf is still owned by
 * the iterator; this is exposed just for efficiency.
279 280
 */
extern int git_iterator_current_workdir_path(
281
	git_buf **path, git_iterator *iter);
282

283 284 285
/**
 * Retrieve the index stored in the iterator.
 *
286
 * Only implemented for the workdir and index iterators.
287
 */
288
extern git_index *git_iterator_index(git_iterator *iter);
289

290 291 292 293 294 295 296 297 298 299 300 301 302 303 304
typedef int (*git_iterator_walk_cb)(
	const git_index_entry **entries,
	void *data);

/**
 * Walk the given iterators in lock-step.  The given callback will be
 * called for each unique path, with the index entry in each iterator
 * (or NULL if the given iterator does not contain that path).
 */
extern int git_iterator_walk(
	git_iterator **iterators,
	size_t cnt,
	git_iterator_walk_cb cb,
	void *data);

305
#endif