Merge pull request #1385 from carlosmn/refs-iter

Introduce a refs iterator

3 files changed, 77 insertions, 35 deletions

diff --git a/include/git2/refs.h b/include/git2/refs.h
index e78873408..754bda785 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -297,12 +297,6 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref);
 /**
  * Fill a list with all the references that can be found in a repository.
  *
- * Using the `list_flags` parameter, the listed references may be filtered
- * by type (`GIT_REF_OID` or `GIT_REF_SYMBOLIC`) or using a bitwise OR of
- * `git_ref_t` values.  To include packed refs, include `GIT_REF_PACKED`.
- * For convenience, use the value `GIT_REF_LISTALL` to obtain all
- * references, including packed ones.
- *
  * The string array will be filled with the names of all references; these
  * values are owned by the user and should be free'd manually when no
  * longer needed, using `git_strarray_free()`.
@@ -310,36 +304,27 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref);
  * @param array Pointer to a git_strarray structure where
  *		the reference names will be stored
  * @param repo Repository where to find the refs
- * @param list_flags Filtering flags for the reference listing
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, unsigned int list_flags);
+GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo);
 
 typedef int (*git_reference_foreach_cb)(const char *refname, void *payload);
 
 /**
  * Perform a callback on each reference in the repository.
  *
- * Using the `list_flags` parameter, the references may be filtered by
- * type (`GIT_REF_OID` or `GIT_REF_SYMBOLIC`) or using a bitwise OR of
- * `git_ref_t` values.  To include packed refs, include `GIT_REF_PACKED`.
- * For convenience, use the value `GIT_REF_LISTALL` to obtain all
- * references, including packed ones.
- *
  * The `callback` function will be called for each reference in the
  * repository, receiving the name of the reference and the `payload` value
  * passed to this method.  Returning a non-zero value from the callback
  * will terminate the iteration.
  *
  * @param repo Repository where to find the refs
- * @param list_flags Filtering flags for the reference listing.
  * @param callback Function which will be called for every listed ref
  * @param payload Additional data to pass to the callback
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_reference_foreach(
 	git_repository *repo,
-	unsigned int list_flags,
 	git_reference_foreach_cb callback,
 	void *payload);
 
@@ -360,6 +345,31 @@ GIT_EXTERN(void) git_reference_free(git_reference *ref);
 GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2);
 
 /**
+ * Create an iterator for the repo's references
+ *
+ * @param out pointer in which to store the iterator
+ * @param repo the repository
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_reference_iterator_new(git_reference_iterator **out, git_repository *repo);
+
+/**
+ * Get the next reference name
+ *
+ * @param out pointer in which to store the string
+ * @param iter the iterator
+ * @param 0, GIT_ITEROVER if there are no more; or an error code
+ */
+GIT_EXTERN(int) git_reference_next(const char **out, git_reference_iterator *iter);
+
+/**
+ * Free the iterator and its associated resources
+ *
+ * @param iter the iterator to free
+ */
+GIT_EXTERN(void) git_reference_iterator_free(git_reference_iterator *iter);
+
+/**
  * Perform a callback on each reference in the repository whose name
  * matches the given pattern.
  *
@@ -373,7 +383,6 @@ GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2);
  *
  * @param repo Repository where to find the refs
  * @param glob Pattern to match (fnmatch-style) against reference name.
- * @param list_flags Filtering flags for the reference listing.
  * @param callback Function which will be called for every listed ref
  * @param payload Additional data to pass to the callback
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
@@ -381,7 +390,6 @@ GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2);
 GIT_EXTERN(int) git_reference_foreach_glob(
 	git_repository *repo,
 	const char *glob,
-	unsigned int list_flags,
 	git_reference_foreach_cb callback,
 	void *payload);
 
diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h
index d5f599fec..8dbf38ca9 100644
--- a/include/git2/sys/refdb_backend.h
+++ b/include/git2/sys/refdb_backend.h
@@ -20,6 +20,23 @@
  */
 GIT_BEGIN_DECL
 
+
+/**
+ * Every backend's iterator must have a pointer to itself as the first
+ * element, so the API can talk to it. You'd define your iterator as
+ *
+ *     struct my_iterator {
+ *             git_reference_iterator parent;
+ *             ...
+ *     }
+ *
+ * and assign `iter->parent.backend` to your `git_refdb_backend`.
+ */
+struct git_reference_iterator {
+	git_refdb_backend *backend;
+	char *glob;
+};
+
 /** An instance for a custom backend */
 struct git_refdb_backend {
     unsigned int version;
@@ -43,29 +60,42 @@ struct git_refdb_backend {
 		const char *ref_name);
 
 	/**
-	 * Enumerates each reference in the refdb.  A refdb implementation must
-	 * provide this function.
+	 * Allocate an iterator object for the backend.
+	 *
+	 * A refdb implementation must provide this function.
 	 */
-	int (*foreach)(
-		git_refdb_backend *backend,
-		unsigned int list_flags,
-		git_reference_foreach_cb callback,
-		void *payload);
+	int (*iterator)(
+		git_reference_iterator **iter,
+		struct git_refdb_backend *backend);
 
 	/**
-	 * Enumerates each reference in the refdb that matches the given
-	 * glob string.  A refdb implementation may provide this function;
-	 * if it is not provided, foreach will be used and the results filtered
-	 * against the glob.
+	 * Allocate a glob-filtering iterator object for the backend.
+	 *
+	 * A refdb implementation may provide this function. If it's
+	 * not available, the glob matching will be done by the frontend.
 	 */
-	int (*foreach_glob)(
-		git_refdb_backend *backend,
-		const char *glob,
-		unsigned int list_flags,
-		git_reference_foreach_cb callback,
-		void *payload);
+	int (*iterator_glob)(
+		git_reference_iterator **iter,
+		struct git_refdb_backend *backend,
+		const char *glob);
+
+	/**
+	 * Return the current value and advance the iterator.
+	 *
+	 * A refdb implementation must provide this function.
+	 */
+	int (*next)(
+		const char **name,
+		git_reference_iterator *iter);
 
 	/**
+	 * Free the iterator
+	 *
+	 * A refdb implementation must provide this function.
+	 */
+	void (*iterator_free)(
+		git_reference_iterator *iter);
+	/*
 	 * Writes the given reference to the refdb.  A refdb implementation
 	 * must provide this function.
 	 */
diff --git a/include/git2/types.h b/include/git2/types.h
index aca9ed927..43751d3b0 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -165,6 +165,10 @@ typedef struct git_signature {
 /** In-memory representation of a reference. */
 typedef struct git_reference git_reference;
 
+/** Iterator for references */
+typedef struct git_reference_iterator  git_reference_iterator;
+
+
 /** Basic type of any Git reference. */
 typedef enum {
 	GIT_REF_INVALID = 0, /** Invalid reference */