Markdown documentation for GitLab::API::Iterator

pod/GitLab-API-Iterator.md

+# NAME
+
+GitLab::API::Iterator - iterator for paginated responses
+
+# SYNOPSIS
+
+    use GitLab::API;
+    use GitLab::Users;
+
+    my $gitlab = GitLab::API->new(...);
+
+    my $users = $gitlab->users(-iterator => 1);
+
+    while (my $user = $users->next) {
+        # ...
+    }
+
+    print "Total users: ", $users->count, "\n";
+
+    # ...
+    $users->rewind;
+
+    while (my $user = $users->next()) {
+        # ...
+    }
+
+# DESCRIPTION
+
+The iterator provides methods `next` and `rewind`.
+It also remembers pages that have already been downloaded.
+When the iterator reaches the end of data, it tries to download the next page.
+
+Note that all entities are memoized, so rewinding the iterator will **not** cause it to request pages again.
+Use **reset** for this kind of behaviour.
+
+- new()
+
+        $iterator = GitLab::API::Iterator->new($api, $url, %extra)
+
+    Constructor.
+    Not intended to be called directly, ["exec\_request" in GitLab::API](https://metacpan.org/pod/GitLab::API#exec_request) constructs the instance itself.
+
+    Arguments:
+
+    - `$api`
+
+        The [GitLab::API](https://metacpan.org/pod/GitLab::API) instance that will be used to issue calls.
+
+    - `$url`
+
+        [URI](https://metacpan.org/pod/URI) instance for the call.
+
+    - `%extra`
+
+        Extra arguments.
+        Currently only `per_page` is used, which controls how many entities in a page can the iterator request.
+
+- next()
+
+    Returns the next element or `undef` if there are no elements left.
+    Automatically downloads next page from API if required.
+
+- reset()
+
+        $iterator->reset
+
+    Resets the iterator to the original state that can be reused.
+    Clears all data and error flags, so that the requests can be issued again.
+
+- rewind()
+
+        $iterator->rewind
+
+    Resets the iterator to the position before the first element, so that the call to `next` will return the first element.
+    Note that this will **not** cause the iterator to re-download all pages.
+    Use `reset` for this purpose.
+
+- all()
+
+        my @items = @{ $iterator->all };
+
+    Downloads all pages and returns an arrayref of all elements.
+
+## Internal methods
+
+- next\_block()
+
+    Tries to download the next page from the GitLab API.
+    Returns false if no page left or an error occured.
+
+# AUTHOR
+
+Roman Lacko <[xlacko1@fi.muni.cz](https://metacpan.org/pod/xlacko1@fi.muni.cz)>
+
+# SEE ALSO
+
+- [GitLab::API](https://metacpan.org/pod/GitLab::API)
+
+    Lightweight GitLab API client.
+
+- [GitLab](https://metacpan.org/pod/GitLab)
+
+        use GitLab;
+
+    Wrapper around [GitLab::API](https://metacpan.org/pod/GitLab::API) and other modules.