Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
Menu
Open sidebar
Roman Lacko
gitlab_api
Commits
cd3cf661
Commit
cd3cf661
authored
Oct 05, 2016
by
Roman Lacko
Browse files
added POD for GitLab::API::Iterator
parent
552b1f72
Changes
2
Hide whitespace changes
Inline
Side-by-side
GitLab/API.pm
View file @
cd3cf661
...
...
@@ -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
View file @
cd3cf661
...
...
@@ -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
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment