GitLab-API-Iterator.md

+# NAME
+
+`GitLab::API::Iterator` - iterator for paginated responses
+
+# SYNOPSIS
+
+```{.pl}
+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()`
+
+    ```{.pl}
+    $iterator = GitLab::API::Iterator->new($api, $url, %extra)
+    ```
+
+    Constructor.
+    Not intended to be called directly, [`exec_request` in GitLab::API](GitLab-API.md#exec_request) constructs the instance itself.
+
+    Arguments:
+
+    - `$api`
+
+        The [`GitLab::API`](GitLab-API.md) 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()`
+
+    ```{.pl}
+    $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()`
+
+    ```{.pl}
+    $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()`
+
+    ```{.pl}    
+    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`](mailto:xlacko1@fi.muni.cz)>
+
+# SEE ALSO
+
+- [`GitLab::API`](GitLab-API.md)
+
+    Lightweight GitLab API client.
+
+- [`GitLab`](GitLab.md)
+
+    Wrapper around [`GitLab::API`](GitLab-API.md) and other modules.