iterator.h 7.54 KB
Newer Older
1
/*
Edward Thomson committed
2
 * Copyright (C) the libgit2 contributors. All rights reserved.
3 4 5 6 7 8 9 10 11
 *
 * 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"
#include "git2/index.h"
12
#include "vector.h"
13
#include "buffer.h"
14

15 16 17
typedef struct git_iterator git_iterator;

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

25
typedef enum {
26 27 28 29
	/** ignore case for entry sort order */
	GIT_ITERATOR_IGNORE_CASE = (1 << 0),
	/** force case sensitivity for entry sort order */
	GIT_ITERATOR_DONT_IGNORE_CASE = (1 << 1),
30 31 32 33
	/** return tree items in addition to blob items */
	GIT_ITERATOR_INCLUDE_TREES    = (1 << 2),
	/** don't flatten trees, requiring advance_into (implies INCLUDE_TREES) */
	GIT_ITERATOR_DONT_AUTOEXPAND  = (1 << 3),
34 35
} git_iterator_flag_t;

36
typedef struct {
37 38
	int (*current)(const git_index_entry **, git_iterator *);
	int (*advance)(const git_index_entry **, git_iterator *);
39
	int (*advance_into)(const git_index_entry **, git_iterator *);
40
	int (*seek)(git_iterator *, const char *prefix);
41
	int (*reset)(git_iterator *, const char *start, const char *end);
42
	int (*at_end)(git_iterator *);
43
	void (*free)(git_iterator *);
44 45 46 47 48 49 50 51
} git_iterator_callbacks;

struct git_iterator {
	git_iterator_type_t type;
	git_iterator_callbacks *cb;
	git_repository *repo;
	char *start;
	char *end;
52
	int (*prefixcomp)(const char *str, const char *prefix);
53
	unsigned int flags;
54 55
};

56
extern int git_iterator_for_nothing(
57 58 59 60
	git_iterator **out,
	git_iterator_flag_t flags,
	const char *start,
	const char *end);
61

62 63 64
/* tree iterators will match the ignore_case value from the index of the
 * repository, unless you override with a non-zero flag value
 */
65
extern int git_iterator_for_tree(
66 67 68 69 70
	git_iterator **out,
	git_tree *tree,
	git_iterator_flag_t flags,
	const char *start,
	const char *end);
71

72 73 74
/* index iterators will take the ignore_case value from the index; the
 * ignore_case flags are not used
 */
75
extern int git_iterator_for_index(
76 77 78 79 80
	git_iterator **out,
	git_index *index,
	git_iterator_flag_t flags,
	const char *start,
	const char *end);
81

82 83 84 85 86 87 88 89
extern int git_iterator_for_workdir_ext(
	git_iterator **out,
	git_repository *repo,
	const char *repo_workdir,
	git_iterator_flag_t flags,
	const char *start,
	const char *end);

90 91 92
/* workdir iterators will match the ignore_case value from the index of the
 * repository, unless you override with a non-zero flag value
 */
93
GIT_INLINE(int) git_iterator_for_workdir(
94 95 96 97
	git_iterator **out,
	git_repository *repo,
	git_iterator_flag_t flags,
	const char *start,
98 99 100 101
	const char *end)
{
	return git_iterator_for_workdir_ext(out, repo, NULL, flags, start, end);
}
102

103 104 105 106 107 108 109 110 111 112
/* 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,
	git_iterator_flag_t flags,
	const char *start,
	const char *end);

113 114
extern void git_iterator_free(git_iterator *iter);

115 116 117 118 119 120
/* 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).
121 122
 *
 * You do not need to free the entry.  It is still "owned" by the iterator.
123 124
 * 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.
125 126
 */
GIT_INLINE(int) git_iterator_current(
127
	const git_index_entry **entry, git_iterator *iter)
128
{
129
	return iter->cb->current(entry, iter);
130 131
}

132 133 134 135 136 137 138
/**
 * 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.
 */
139
GIT_INLINE(int) git_iterator_advance(
140
	const git_index_entry **entry, git_iterator *iter)
141
{
142
	return iter->cb->advance(entry, iter);
143 144
}

145 146 147 148 149 150 151 152 153 154 155
/**
 * 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.
 *
156 157 158
 * 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.
159 160 161 162 163 164 165
 */
GIT_INLINE(int) git_iterator_advance_into(
	const git_index_entry **entry, git_iterator *iter)
{
	return iter->cb->advance_into(entry, iter);
}

166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
/**
 * Advance into a tree or skip over it if it is empty.
 *
 * Because `git_iterator_advance_into` may return GIT_ENOTFOUND if the
 * directory is empty (only with filesystem and working directory
 * iterators) and a common response is to just call `git_iterator_advance`
 * when that happens, this bundles the two into a single simple call.
 */
GIT_INLINE(int) git_iterator_advance_into_or_over(
	const git_index_entry **entry, git_iterator *iter)
{
	int error = iter->cb->advance_into(entry, iter);
	if (error == GIT_ENOTFOUND) {
		giterr_clear();
		error = iter->cb->advance(entry, iter);
	}
	return error;
}

/* Seek is currently unimplemented */
186 187 188
GIT_INLINE(int) git_iterator_seek(
	git_iterator *iter, const char *prefix)
{
189
	return iter->cb->seek(iter, prefix);
190 191
}

192 193 194 195 196 197 198
/**
 * Go back to the start of the iteration.
 *
 * This resets the iterator to the start of the iteration.  It also allows
 * you to reset the `start` and `end` pathname boundaries of the iteration
 * when doing so.
 */
199 200
GIT_INLINE(int) git_iterator_reset(
	git_iterator *iter, const char *start, const char *end)
201
{
202
	return iter->cb->reset(iter, start, end);
203 204
}

205 206 207 208 209
/**
 * Check if the iterator is at the end
 *
 * @return 0 if not at end, >0 if at end
 */
210 211 212 213 214
GIT_INLINE(int) git_iterator_at_end(git_iterator *iter)
{
	return iter->cb->at_end(iter);
}

215 216 217 218 219
GIT_INLINE(git_iterator_type_t) git_iterator_type(git_iterator *iter)
{
	return iter->type;
}

Russell Belfer committed
220 221 222 223 224
GIT_INLINE(git_repository *) git_iterator_owner(git_iterator *iter)
{
	return iter->repo;
}

225 226 227 228 229 230 231 232 233 234
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);
}

235 236
extern int git_iterator_set_ignore_case(git_iterator *iter, bool ignore_case);

237
extern int git_iterator_current_tree_entry(
238
	const git_tree_entry **entry_out, git_iterator *iter);
239

240
extern int git_iterator_current_parent_tree(
241
	const git_tree **tree_out, git_iterator *iter, const char *parent_path);
242

243
extern bool git_iterator_current_is_ignored(git_iterator *iter);
244

245 246 247
extern int git_iterator_cmp(
	git_iterator *iter, const char *path_prefix);

248
/**
249 250 251
 * 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.
252 253
 */
extern int git_iterator_current_workdir_path(
254
	git_buf **path, git_iterator *iter);
255

256 257
/* Return index pointer if index iterator, else NULL */
extern git_index *git_iterator_get_index(git_iterator *iter);
258

259
#endif