added POD for GitLab::API::Iterator

GitLab/API.pm

@@ -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;
     utf8::decode($data);
@@ -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|http://doc.gitlab.com/ce/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) {
+        # ...
+    }
 
 =head1 DESCRIPTION
 
@@ -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.
 
 =back
 

GitLab/API/Iterator.pm

@@ -161,3 +161,133 @@ sub next_block {
     $log->debug("block read successful");
     return 1;
 }
+
+1;
+
+#===============================================================================
+#   DOCUMENTATION
+#===============================================================================
+
+__END__
+
+=head1 NAME
+
+GitLab::API::Iterator - iterator for paginated responses
+
+=head1 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()) {
+        # ...
+    }
+
+=head1 DESCRIPTION
+
+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.
+
+=over
+
+=item new()
+
+    $iterator = GitLab::API::Iterator->new($api, $url, %extra)
+
+Constructor.
+Not intended to be called directly, L<GitLab::API/exec_request> constructs the instance itself.
+
+Arguments:
+
+=over
+
+=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.
+
+=back
+
+=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()
+
+    $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.
+
+=item rewind()
+
+    $iterator->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.
+
+=back
+
+=head2 Internal methods
+
+=over
+
+=item next_block()
+
+Tries to download the next page from the GitLab API.
+Returns false if no page left or an error occured.
+
+=back
+
+=head1 AUTHOR
+
+Roman Lacko <L<xlacko1@fi.muni.cz>>
+
+=head1 SEE ALSO
+
+=over
+
+=item L<GitLab::API>
+
+Lightweight GitLab API client.
+
+=item L<GitLab>
+
+    use GitLab;
+
+Wrapper around L<GitLab::API> and other modules.
+
+=back