Commit cd3cf661 authored by Roman Lacko's avatar Roman Lacko
Browse files

added POD for GitLab::API::Iterator

parent 552b1f72
......@@ -179,7 +179,7 @@ sub clean_data {
croak "GitLab sent '", $response->header("Content-Type"), "' instead of 'application/json'";
return unless $response->is_success;
return ($response, undef) unless $response->is_success;
my $data = $response->decoded_content;
......@@ -217,9 +217,11 @@ sub exec_request {
my $response;
my $data = [];
if ($rtargs->{-iterator} && defined $rtargs->{-page}) {
carp "Cannot specify both -iterator and -page in method call";
croak "Cannot request -iterator if -page is specified as well"
if $rtargs->{-iterator} && defined $rtargs->{-page};
croak "Requested iterator for a non-paginated method"
if $rtargs->{-iterator} && !$tmpl->{paginated};
$log->debug("$tmpl->{method} $uri");
......@@ -351,17 +353,26 @@ See L<GitLab API|> for details.
use GitLab::API;
use GitLab::Users;
use GitLab::Groups;
use GitLab::Projects;
my $gitlab = GitLab::API->new(AuthToken => $token);
# simple result
my $groups = $gitlab->groups(search => "awesome-group");
die("Failed to get groups") unless defined $groups;
# result with response
my ($users, $response) = $gitlab->users(-response => 1);
die("Request failed: " . $response->message) unless $response->is_success;
# do something with users or groups
# iterator for paginated responses
my $projects = $gitlab->projects(-iterator => 1);
while (my $project = $projects->next) {
# ...
......@@ -505,10 +516,22 @@ Recommended with C<-response> option so that the status code can be inspected di
=item C<< -page => N >>
When used with paginated requests, returns only entries from the given page.
The number of entities in each page is always I<100> except (of course) the last one.
The number of entities in each page is by default I<50> except (of course) the last one.
It is possible to change the default page size with the C<<-per_page>> option.
The API returns an empty response for invalid page numbers.
The method carps if used with a template without C<< $tmpl->{paginated} >> attribute.
The method I<croaks> if used with a template without C<< $tmpl->{paginated} >> attribute or if combined with C<< -iterator >>.
=item C<< -per_page => N >>
Change the page size for C<<-page>> or C<<-iterator>> option.
The maximum allowed value by GitLab is currently C<100>.
=item C<< -iterator >>
When non-zero, returns an instance of L<GitLab::API::Iterator> that will sequentially request pages when needed.
The method I<croaks> if combined with C<<-page>> or used for non-paginated request.
......@@ -161,3 +161,133 @@ sub next_block {
$log->debug("block read successful");
return 1;
=head1 NAME
GitLab::API::Iterator - iterator for paginated responses
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";
# ...
while (my $user = $users->next()) {
# ...
The iterator provides methods C<next> and C<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 B<not> cause it to request pages again.
Use B<reset> for this kind of behaviour.
=item new()
$iterator = GitLab::API::Iterator->new($api, $url, %extra)
Not intended to be called directly, L<GitLab::API/exec_request> constructs the instance itself.
=item C<$api>
The L<GitLab::API> instance that will be used to issue calls.
=item C<$url>
L<URI> instance for the call.
=item C<%extra>
Extra arguments.
Currently only C<per_page> is used, which controls how many entities in a page can the iterator request.
=item next()
Returns the next element or C<undef> if there are no elements left.
Automatically downloads next page from API if required.
=item 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.
=item rewind()
Resets the iterator to the position before the first element, so that the call to C<next> will return the first element.
Note that this will B<not> cause the iterator to re-download all pages.
Use C<reset> for this purpose.
=item all()
my @items = @{ $iterator->all };
Downloads all pages and returns an arrayref of all elements.
=head2 Internal methods
=item next_block()
Tries to download the next page from the GitLab API.
Returns false if no page left or an error occured.
=head1 AUTHOR
Roman Lacko <L<>>
=head1 SEE ALSO
=item L<GitLab::API>
Lightweight GitLab API client.
=item L<GitLab>
use GitLab;
Wrapper around L<GitLab::API> and other modules.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment