Pithub::Result(3pm)

📦
version 0.01043 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Pithub::Result — the manual page, but make it a group chat 💖

okay bestie, so this is Pithub::Result(3pm), from the User Contributed Perl Documentation crew. Version? version 0.01043. She's a Github v3 result object and she is, frankly, the main character of every single API call you're about to make. 🎀

✨ NAME ✨

Pithub::Result — a Github v3 result object. that's her. that's the whole vibe. 💅

🌸 VERSION 🌸

version 0.01043. write it down, she said what she said. ⭐

🦋 DESCRIPTION 🦋

so here's the tea: every method call that maps directly to a Github API call hands you back a Pithub::Result object. every single one. no exceptions, no cap. 🫶

and once you've got that result object in your hands? you can set attributes on it, or you can call methods on it. that's it. that's the whole relationship. you're in charge now. 👑

🎀 ATTRIBUTES 🎀

🌈 auto_pagination

set this bad boy to true and then use the next method to iterate over the result rows — it'll call next_page for you, automatically, until you've got all the results. so convenient. so slay. ✨

⚠️ but bestie, be careful with this feature. if there are 100 pages, this will make 100 API calls. that's a lot of calls. that's a lot of rate limit. protect yourself. 💀

by default it's off. and psst — instead of setting it per Pithub::Result, you can also set it directly on any of the Pithub API objects. flexible queen. 💅

Examples:

my $r = Pithub::Repos->new;
my $result = $r->list( user => 'rjbs' );

# This would just show the first 30 by default
while ( my $row = $result->next ) {
    printf "%s: %s\n", $row->{name}, $row->{description};
}

# Let's do the same thing using auto_pagination to fetch all
$result = $r->list( user => 'rjbs' );
$result->auto_pagination(1);
while ( my $row = $result->next ) {
    printf "%s: %s\n", $row->{name}, $row->{description};
}

# Turn auto_pagination on for all L<Pithub::Result> objects
my $p = Pithub::Repos->new( auto_pagination => 1 );
my $result = $p->list( user => 'rjbs' );
while ( my $row = $result->next ) {
    printf "%s: %s\n", $row->{name}, $row->{description};
}

🍓 content

the decoded JSON response, babes. 🧚 it might be an arrayref or a hashref, depending on which API call you made — she's versatile like that. and for some calls? there's literally no content at all. empty. nothing. the void. 😭

💜 first_page_uri

the extracted value from the Link header, for the first page. this can return undef. 🫠

💜 last_page_uri

the extracted value from the Link header, for the last page. this can return undef. 🫠

💜 next_page_uri

the extracted value from the Link header, for the next page. this can return undef. 🫠

💜 prev_page_uri

the extracted value from the Link header, for the previous page. this can return undef. 🫠

🌟 response

the HTTP::Response object. that's it, that's the attribute. iconic. ✨

🌟 utf8

this one can set the utf8 flag. do with that what you will, bestie. 💖

🔥 METHODS 🔥

🌈 raw_content

returns the content of the API response as a string. and yeah, it'll probably be JSON. no promises, but like, probably. 💅

🌈 request

returns the HTTP::Request object that was used to make the API call. the receipts, basically. 🧾

🌈 code

returns the HTTP code from the API call. 200? 404? she'll tell you. 👀

🌈 success

returns whether the API call was successful. vibe check passed or not, fr fr. ✅

🌈 count

returns the count of the elements in content. and here's the lil quirk: if the result isn't an arrayref but a hashref, it will still return 1. but some calls return an empty hashref — for those calls, it returns 0. so there's nuance, okay? respect the nuance. 🎀

🌈 first

returns the first element from content if content is an arrayref. if it's a hashref? it just returns that hashref. she's not gonna make it weird. 🫶

🌈 first_page

get the Pithub::Result of the first page. returns undef if there's no first page — so like, if you're already on the first page, or if there are no pages at all. 🫠

🌈 get_page

get the Pithub::Result for a specific page. heads up: the parameter is not validated — if you hit a page that doesn't exist, the Github API itself will tell you so. 😭

and if there's only one page? this method returns undef, no matter which page you ask for. even for page 1. yes, even that one. sorry bestie. 💀

🌈 last_page

get the Pithub::Result of the last page. returns undef if there's no last page — if you're already on the last page, or if there's only one page, or no pages at all. the undef is coming from inside the house. 🫠

🌈 next

so most of the results the Github API hands back are arrayrefs of hashrefs. you can grab those data structures directly by calling content. but besides that, you can also just iterate over the results using this method. choose your fighter. 💅

Examples:

my $r = Pithub::Repos->new;
my $result = $r->list( user => 'rjbs' );

while ( my $row = $result->next ) {
    printf "%s: %s\n", $row->{name}, $row->{description};
}

🌈 next_page

get the Pithub::Result of the next page. returns undef if there's no next page — which happens when there's only one page at all. 🥲

Examples:

  • list all followers in order, from the first one on the first page all the way to the last one on the last page. see also auto_pagination. 🌸
my $followers = Pithub->new->users->followers;
my $result = $followers->list( user => 'rjbs' );
do {
    if ( $result->success ) {
        while ( my $row = $result->next ) {
            printf "%s\n", $row->{login};
        }
    }
} while $result = $result->next_page;

the nature of the implementation requires you to do a do { ... } while ... loop here. and ngl, if you're planning to fetch all the results of all the pages, I suggest you use the auto_pagination feature instead — it's much more convenient. trust. 🫶

🌈 prev_page

get the Pithub::Result of the previous page. returns undef if there's no previous page — which means you're on the first page already. 🥲

Examples:

  • list all followers in reverse order, from the last one on the last page all the way back to the first one on the first page. see also auto_pagination. 🌸
my $followers = Pithub->new->users->followers;
my $result = $followers->list( user => 'rjbs' )->last_page;    # this makes two requests!
do {
    if ( $result->success ) {
        while ( my $row = $result->next ) {
            printf "%s\n", $row->{login};
        }
    }
} while $result = $result->prev_page;
📌 not me pointing out that ->last_page there makes two requests! the comment in the code says it, I'm just saying it louder. 💀

🌈 etag

returns the value of the ETag http header. ✨

🌈 ratelimit

returns the value of the X-Ratelimit-Limit http header. know your limits, bestie. 🎀

🌈 ratelimit_remaining

returns the value of the X-Ratelimit-Remaining http header. 👑

💜 AUTHOR 💜

Johannes Plunien <plu@cpan.org> — give her her flowers. 🌷

This software is copyright (c) 2011 by Johannes Plunien.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💅

and that's the whole page, bestie!! 🎉 written up as part of the User Contributed Perl Documentation, running on perl v5.40.1, dated 2025-06-08, and honestly? she ate. go forth and paginate responsibly. 🦋✨💖

📦 where this page comes from