Add item-per-item iteration so that users don't need to manage "pages" of results

lib/Net/GitHub/V3.pm

@@ -222,7 +222,7 @@ from the API. By switching B<RaiseError> on you can make the be turned into
 exceptions instead, so that you don't have to check for error response after
 every call.
 
-=head3 next_url, last_url, prev_url, first_url, per_page
+=head3 Iterating over pages: next_url, last_url, prev_url, first_url, per_page
 
 Any methods which return multiple results I<may> be paginated. After performing
 a query you should check to see if there are more results. These attributes will
@@ -242,6 +242,47 @@ See Github's documentation: L<http://developer.github.com/v3/#pagination>
       push @issues, $gh->issue->next_page;
   }
 
+
+=head3 Iterating over individual items: next_xxx and close_xxx
+
+The queries which can return paginated results can also be evaluated one by
+one, like this:
+
+  while (my $issue = $gh->issue->next_repos_issue( @args )) {
+    # do something with $issue
+  }
+
+The arguments to next_repos_issue are the same as for repos_issues,
+and is also applicable to all other interfaces which offer a next_xxx
+method.  All available next_xxx methods are listed in the
+documentation of the corresponding modules, see the list below.
+
+If you loop over the next_xxx interfaces, new API calls will be
+performed automatically, but only when needed to fetch more items.  An
+undefined return value means there are no more items.
+
+To start over with the first item, you need to close the iteration.
+Every next_xxx method has a corresponding close_xxx method which must
+be called with exactly the same parameters as the next_xxx method to
+take effect:
+
+  $gh->issue->close_repos_issue(@args);
+
+If you use Net::GitHub::V3 in a command line program, there is no need
+to call the close_xxx methods at all.  As soon as the Net::GitHub::V3
+object $gh goes out of scope, everything is neatly cleaned up.
+
+However, if you have a long-lived Net::GitHub::V3 object, e.g. in a
+persistent service process which provides an own interface to its
+users and talks to GitHub under the hood, then it is advisable to
+close the iterations when you're done with them.
+
+For brevity and because they usually are not needed, the close_xxx
+methods are not listed with their modules.  It is guaranteed that
+I<every> next_xxx method has a corresponding close_xxx method.
+
+
+
 =head3 ua
 
 To set the proxy for ua, you can do something like following
@@ -304,7 +345,7 @@ L<Net::GitHub::V3::Repos>
 =head3 issue
 
     my @issues = $gh->issue->issues();
-    my $issue  = $gh->issue->issue($issue_id);
+    my $issue  = $gh->issue->issue($issue_number);
 
 L<Net::GitHub::V3::Issues>
 

lib/Net/GitHub/V3/Events.pm

@@ -12,19 +12,19 @@ with 'Net::GitHub::V3::Query';
 ## build methods on fly
 my %__methods = (
 
-    events => { url => '/events' },
-    repos_events => { url => "/repos/%s/%s/events" },
-    issues_events => { url => "/repos/%s/%s/issues/events" },
-    networks_events => { url => "/networks/%s/%s/events" },
-    orgs_events => { url => "/orgs/%s/events" },
+    events => { url => '/events', paginate => 1 },
+    repos_events => { url => "/repos/%s/%s/events", paginate => 1 },
+    issues_events => { url => "/repos/%s/%s/issues/events", paginate => 1 },
+    networks_events => { url => "/networks/%s/%s/events", paginate => 1 },
+    orgs_events => { url => "/orgs/%s/events", paginate => 1 },
 
-    user_received_events => { url => "/users/%s/received_events" },
-    user_public_received_events => { url => "/users/%s/received_events/public" },
+    user_received_events => { url => "/users/%s/received_events", paginate => 1 },
+    user_public_received_events => { url => "/users/%s/received_events/public", paginate => 1 },
 
-    user_events => { url => "/users/%s/events" },
-    user_public_events => { url => "/users/%s/events/public" },
+    user_events => { url => "/users/%s/events", paginate => 1 },
+    user_public_events => { url => "/users/%s/events/public", paginate => 1 },
 
-    user_orgs_events => { url => "/users/%s/events/orgs/%s" },
+    user_orgs_events => { url => "/users/%s/events/orgs/%s", paginate => 1 },
 
 );
 __build_methods(__PACKAGE__, %__methods);
@@ -51,13 +51,14 @@ Net::GitHub::V3::Events - GitHub Events API
 
 =head3 Events
 
-L<http://developer.github.com/v3/events/>
+L<http://developer.github.com/v3/activity/events/>
 
 =over 4
 
 =item events
 
     my @events = $event->events();
+    while (my $ne = $event->next_event) { ...; }
 
 =item repos_events
 
@@ -68,10 +69,14 @@ L<http://developer.github.com/v3/events/>
     my @events = $event->repos_events($user, $repo);
     my @events = $event->issues_events($user, $repo);
     my @events = $event->networks_events($user, $repo);
+    while (my $ur_event = next_repos_event($user,$repo) { ...; }
+    while (my $ur_event = next_issues_event($user,$repo) { ...; }
+    while (my $ur_event = next_networks_event($user,$repo) { ...; }
 
 =item orgs_events
 
     my @events = $event->orgs_events($org);
+    while (my $org_event = $event->next_orgs_event) { ...; }
 
 =item user_received_events
 
@@ -85,10 +90,15 @@ L<http://developer.github.com/v3/events/>
     my @events = $event->user_public_received_events($user);
     my @events = $event->user_events($user);
     my @events = $event->user_public_events($user);
+    while (my $u_event = $event->next_user_received_event) { ...; }
+    while (my $u_event = $event->next_user_public_received_event) { ...; }
+    while (my $u_event = $event->next_user_event) { ...; }
+    while (my $u_event = $event->next_user_public_event) { ...; }
 
 =item user_orgs_events
 
     my @events = $event->user_orgs_events($user, $org);
+    while (my $o_event = $event->next_org_event) { ...; }
 
 =back
 

lib/Net/GitHub/V3/Gists.pm

@@ -16,10 +16,24 @@ sub gists {
     return $self->query($u);
 }
 
+sub next_gist {
+    my ( $self, $user ) = @_;
+
+    my $u = $user ? "/users/" . uri_escape($user) . '/gists' : '/gists';
+    return $self->next($u);
+}
+
+sub close_gist {
+    my ( $self, $user ) = @_;
+
+    my $u = $user ? "/users/" . uri_escape($user) . '/gists' : '/gists';
+    return $self->close($u);
+}
+
 ## build methods on fly
 my %__methods = (
-    public_gists  => { url => "/gists/public" },
-    starred_gists => { url => "/gists/starred" },
+    public_gists  => { url => "/gists/public", paginate => 1 },
+    starred_gists => { url => "/gists/starred", paginate => 1 },
     gist => { url => "/gists/%s" },
     create => { url => "/gists", method => "POST", args => 1 },
     update => { url => "/gists/%s", method => "PATCH", args => 1 },
@@ -30,7 +44,7 @@ my %__methods = (
     delete => { url => "/gists/%s", method => "DELETE", check_status => 204 },
 
     # http://developer.github.com/v3/gists/comments/
-    comments => { url => "/gists/%s/comments" },
+    comments => { url => "/gists/%s/comments", paginate => 1 },
     comment  => { url => "/gists/%s/comments/%s" },
     create_comment => { url => "/gists/%s/comments", method => 'POST',  args => 1 },
     update_comment => { url => "/gists/%s/comments/%s", method => 'PATCH', args => 1 },
@@ -68,13 +82,16 @@ L<http://developer.github.com/v3/gists/>
 
     my @gists = $gist->gists;
     my @gists = $gist->gists('nothingmuch');
+    while (my $g = $gist->next_gist) { ...; }
 
 =item public_gists
 
 =item starred_gists
 
     my @gists = $gist->public_gists;
     my @gists = $gist->starred_gists;
+    while (my $g = $gist->next_public_gist) { ...; }
+    while (my $g = $gist->next_starred_gist) { ...; }
 
 =item gist
 
@@ -134,6 +151,7 @@ L<http://developer.github.com/v3/gists/comments/>
 =item delete_comment
 
     my @comments = $gist->comments();
+    while (my $c = $gist->next_comment) { ...; }
     my $comment  = $gist->comment($comment_id);
     my $comment  = $gist->create_comment($gist_id, {
         "body" => "a new comment"