Add INCLUDE_TREES, DONT_AUTOEXPAND iterator flags

This standardizes iterator behavior across all three iterators
(index, tree, and working directory).  Previously the working
directory iterator behaved differently from the other two.

Each iterator can now operate in one of three modes:

1. *No tree results, auto expand trees* means that only non-
   tree items will be returned and when a tree/directory is
   encountered, we will automatically descend into it.
2. *Tree results, auto expand trees* means that results will
   be given for every item found, including trees, but you
   only need to call normal git_iterator_advance to yield
   every item (i.e. trees returned with pre-order iteration).
3. *Tree results, no auto expand* means that calling the
   normal git_iterator_advance when looking at a tree will
   not descend into the tree, but will skip over it to the
   next entry in the parent.

Previously, behavior 1 was the only option for index and tree
iterators, and behavior 3 was the only option for workdir.

The main public API implications of this are that the
`git_iterator_advance_into()` call is now valid for all
iterators, not just working directory iterators, and all the
existing uses of working directory iterators explicitly use
the GIT_ITERATOR_DONT_AUTOEXPAND (for now).

Interestingly, the majority of the implementation was in the
index iterator, since there are no tree entries there and now
have to fake them.  The tree and working directory iterators
only required small modifications.

1 files changed, 35 insertions, 22 deletions

diff --git a/src/iterator.h b/src/iterator.h
index 24c7b7765..4a4e6a9d8 100644
--- a/src/iterator.h
+++ b/src/iterator.h
@@ -26,11 +26,16 @@ typedef enum {
 	GIT_ITERATOR_IGNORE_CASE = (1 << 0),
 	/** force case sensitivity for entry sort order */
 	GIT_ITERATOR_DONT_IGNORE_CASE = (1 << 1),
+	/** 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),
 } git_iterator_flag_t;
 
 typedef struct {
 	int (*current)(const git_index_entry **, git_iterator *);
 	int (*advance)(const git_index_entry **, git_iterator *);
+	int (*advance_into)(const git_index_entry **, git_iterator *);
 	int (*seek)(git_iterator *, const char *prefix);
 	int (*reset)(git_iterator *, const char *start, const char *end);
 	int (*at_end)(git_iterator *);
@@ -102,12 +107,40 @@ GIT_INLINE(int) git_iterator_current(
 	return iter->cb->current(entry, iter);
 }
 
+/**
+ * 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.
+ */
 GIT_INLINE(int) git_iterator_advance(
 	const git_index_entry **entry, git_iterator *iter)
 {
 	return iter->cb->advance(entry, iter);
 }
 
+/**
+ * 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.
+ *
+ * For working directory iterators only, 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.
+ */
+GIT_INLINE(int) git_iterator_advance_into(
+	const git_index_entry **entry, git_iterator *iter)
+{
+	return iter->cb->advance_into(entry, iter);
+}
+
 GIT_INLINE(int) git_iterator_seek(
 	git_iterator *iter, const char *prefix)
 {
@@ -148,33 +181,13 @@ GIT_INLINE(bool) git_iterator_ignore_case(git_iterator *iter)
 extern int git_iterator_set_ignore_case(git_iterator *iter, bool ignore_case);
 
 extern int git_iterator_current_tree_entry(
-	const git_tree_entry **tree_entry, git_iterator *iter);
+	const git_tree_entry **entry_out, git_iterator *iter);
 
 extern int git_iterator_current_parent_tree(
-	const git_tree **tree_ptr, git_iterator *iter, const char *parent_path);
+	const git_tree **tree_out, git_iterator *iter, const char *parent_path);
 
 extern bool git_iterator_current_is_ignored(git_iterator *iter);
 
-/**
- * Iterate into a directory.
- *
- * Workdir iterators do not automatically descend into directories (so that
- * when comparing two iterator entries you can detect a newly created
- * directory in the workdir).  As a result, you may get S_ISDIR items from
- * a workdir iterator.  If you wish to iterate over the contents of the
- * directories you encounter, then call this function when you encounter
- * a directory.
- *
- * If there are no files in the directory, this will end up acting like a
- * regular advance and will skip past the directory, so you should be
- * prepared for that case.
- *
- * On non-workdir iterators or if not pointing at a directory, this is a
- * no-op and will not advance the iterator.
- */
-extern int git_iterator_advance_into(
-	const git_index_entry **entry, git_iterator *iter);
-
 extern int git_iterator_cmp(
 	git_iterator *iter, const char *path_prefix);