.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pithub::Base 3pm"
.TH Pithub::Base 3pm "2023-09-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pithub::Base \- Github v3 base class for all Pithub modules
.SH "VERSION"
.IX Header "VERSION"
version 0.01041
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
All Pithub modules inherit from
Pithub::Base, even Pithub itself. So all
attributes listed here can either be set in the
constructor or via the setter on the objects.
.PP
If any attribute is set on a Pithub object it gets
automatically set on objects that get created by a method call on
the Pithub object. This is very convenient for attributes like
the \*(L"token\*(R" or the \*(L"user\*(R" and \*(L"repo\*(R" attributes.
.PP
The \*(L"user\*(R" and \*(L"repo\*(R" attributes are special: They get even
set on method calls that require \fBboth\fR of them. This is to reduce
verbosity, especially if you want to do a lot of things on the
same repo. This also works for other objects: If you create an
object of Pithub::Repos where you set the \*(L"user\*(R" and \*(L"repo\*(R"
attribute in the constructor, this will also be set once you
get to the Pithub::Repos::Keys object via the \f(CW\*(C`keys\*(C'\fR method.
.PP
Attributes passed along from the parent can be changed in the method
call.
.PP
.Vb 3
\&    my $p = Pithub\->new( per_page => 50 );
\&    my $r1 = $p\->repos;                         # $r\->per_page == 50
\&    my $r2 = $p\->repos( per_page => 100 );      # $r\->per_page == 100
.Ve
.PP
Examples:
.PP
.Vb 3
\&    # just to demonstrate the "magic"
\&    print Pithub\->new( user => \*(Aqplu\*(Aq )\->repos\->user;          # plu
\&    print Pithub::Repos\->new( user => \*(Aqplu\*(Aq )\->keys\->user;    # plu
\&
\&    # and now some real use cases
\&    my $p = Pithub\->new( user => \*(Aqplu\*(Aq, repo => \*(AqPithub\*(Aq );
\&    my $r = $p\->repos;
\&
\&    print $r\->user;    # plu
\&    print $r\->repo;    # pithub
\&
\&    # usually you would do
\&    print $r\->get( user => \*(Aqplu\*(Aq, repo => \*(AqPithub\*(Aq )\->content\->{html_url};
\&
\&    # but since user + repo has been set already
\&    print $r\->get\->content\->{html_url};
\&
\&    # of course parameters to the method take precedence
\&    print $r\->get( user => \*(Aqmiyagawa\*(Aq, repo => \*(AqPlack\*(Aq )\->content\->{html_url};
\&
\&    # it even works on other objects
\&    my $repo = Pithub::Repos\->new( user => \*(Aqplu\*(Aq, repo => \*(AqPithub\*(Aq );
\&    print $repo\->watching\->list\->first\->{login};
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "auto_pagination"
.IX Subsection "auto_pagination"
Off by default.
.PP
See also: \*(L"auto_pagination\*(R" in Pithub::Result.
.SS "api_uri"
.IX Subsection "api_uri"
Defaults to <https://api.github.com>.  For GitHub Enterprise, you'll likely
need an \s-1URL\s0 like <https://github.yourdomain.com/api/v3/>.
.PP
Examples:
.PP
.Vb 1
\&    my $users = Pithub::Users\->new( api_uri => \*(Aqhttps://api\-foo.github.com\*(Aq );
\&
\&    # ... is the same as ...
\&
\&    my $users = Pithub::Users\->new;
\&    $users\->api_uri(\*(Aqhttps://api\-foo.github.com\*(Aq);
.Ve
.SS "jsonp_callback"
.IX Subsection "jsonp_callback"
If you want to use the response directly in JavaScript for example,
Github supports setting a \s-1JSONP\s0 callback parameter.
.PP
See also: <http://developer.github.com/v3/#json\-p\-callbacks>.
.PP
Examples:
.PP
.Vb 3
\&    my $p = Pithub\->new( jsonp_callback => \*(AqloadGithubData\*(Aq );
\&    my $result = $p\->users\->get( user => \*(Aqplu\*(Aq );
\&    print $result\->raw_content;
.Ve
.PP
The result will look like this:
.PP
.Vb 10
\&    loadGithubData({
\&        "meta": {
\&            "status": 200,
\&            "X\-RateLimit\-Limit": "5000",
\&            "X\-RateLimit\-Remaining": "4661"
\&        },
\&        "data": {
\&            "type": "User",
\&            "location": "Dubai",
\&            "url": "https://api.github.com/users/plu",
\&            "login": "plu",
\&            "name": "Johannes Plunien",
\&            ...
\&        }
\&    })
.Ve
.PP
\&\fBBe careful:\fR The content method will
try to decode the \s-1JSON\s0 into a Perl data structure. This is not
possible if the \f(CW\*(C`jsonp_callback\*(C'\fR is set:
.PP
.Vb 2
\&    # calling this ...
\&    print $result\->content;
\&
\&    # ... will throw an exception like this ...
\&    Runtime error: malformed JSON string, neither array, object, number, string or atom,
\&    at character offset 0 (before "loadGithubData( ...
.Ve
.PP
There are two helper methods:
.IP "\(bu" 4
\&\fBclear_jsonp_callback\fR: reset the jsonp_callback attribute
.IP "\(bu" 4

.Sp
\&\fBhas_jsonp_callback\fR: check if the jsonp_callback attribute is set
.SS "per_page"
.IX Subsection "per_page"
Controls how many items are fetched per \s-1API\s0 call, aka \*(L"page\*(R".  See
also: <http://developer.github.com/v3/#pagination> and
\&\*(L"auto_pagination\*(R".
.PP
To minimize the number of \s-1API\s0 calls to get a complete listing, this
defaults to the maximum allowed by Github, which is currently 100.
This may change in the future if Github changes their maximum.
.PP
Examples:
.PP
.Vb 1
\&    my $users = Pithub::Users\->new( per_page => 30 );
\&
\&    # ... is the same as ...
\&
\&    my $users = Pithub::Users\->new;
\&    $users\->per_page(30);
.Ve
.PP
There are two helper methods:
.IP "\(bu" 4
\&\fBclear_per_page\fR: reset the per_page attribute
.IP "\(bu" 4

.Sp
\&\fBhas_per_page\fR: check if the per_page attribute is set
.SS "prepare_request"
.IX Subsection "prepare_request"
This is a CodeRef and can be used to modify the HTTP::Request
object on a global basis, before it's being sent to the Github
\&\s-1API.\s0 It's useful for setting \s-1MIME\s0 types for example. See also:
<http://developer.github.com/v3/mimes/>. This is the right way
to go if you want to modify the \s-1HTTP\s0 request of \fBall\fR \s-1API\s0
calls. If you just want to change a few, consider sending the
\&\f(CW\*(C`prepare_request\*(C'\fR parameter on any method call.
.PP
Let's use this example from the Github docs:
.PP
\&\fBHtml\fR
.PP
\&\f(CW\*(C`application/vnd.github\-issue.html+json\*(C'\fR
.PP
Return html rendered from the body's markdown. Response will
include body_html.
.PP
Examples:
.PP
.Vb 6
\&    my $p = Pithub::Issues\->new(
\&        prepare_request => sub {
\&            my ($request) = @_;
\&            $request\->header( Accept => \*(Aqapplication/vnd.github\-issue.html+json\*(Aq );
\&        }
\&    );
\&
\&    my $result = $p\->get(
\&        user     => \*(Aqmiyagawa\*(Aq,
\&        repo     => \*(AqPlack\*(Aq,
\&        issue_id => 209,
\&    );
\&
\&    print $result\->content\->{body_html};
.Ve
.PP
Please compare to the solution where you set the custom \s-1HTTP\s0 header
on the method call, instead globally on the object:
.PP
.Vb 1
\&    my $p = Pithub::Issues\->new;
\&
\&    my $result = $p\->get(
\&        user     => \*(Aqmiyagawa\*(Aq,
\&        repo     => \*(AqPlack\*(Aq,
\&        issue_id => 209,
\&        options  => {
\&            prepare_request => sub {
\&                my ($request) = @_;
\&                $request\->header( Accept => \*(Aqapplication/vnd.github\-issue.html+json\*(Aq );
\&            },
\&        }
\&    );
\&
\&    print $result\->content\->{body_html};
.Ve
.SS "repo"
.IX Subsection "repo"
This can be set as a default repo to use for \s-1API\s0 calls that require
the repo parameter to be set. There are many of them and it can get
kind of verbose to include the repo and the user for all of the
calls, especially if you want to do many operations on the same
user/repo.
.PP
Examples:
.PP
.Vb 2
\&    my $c = Pithub::Repos::Collaborators\->new( repo => \*(AqPithub\*(Aq );
\&    my $result = $c\->list( user => \*(Aqplu\*(Aq );
.Ve
.PP
There are two helper methods:
.IP "\(bu" 4
\&\fBclear_repo\fR: reset the repo attribute
.IP "\(bu" 4

.Sp
\&\fBhas_repo\fR: check if the repo attribute is set
.SS "token"
.IX Subsection "token"
If the OAuth token is set, Pithub will sent it via an \s-1HTTP\s0 header
on each \s-1API\s0 request. Currently the basic authentication method is
not supported.
.PP
See also: <http://developer.github.com/v3/oauth/>
.SS "ua"
.IX Subsection "ua"
By default a LWP::UserAgent object, but it can be anything that implements
the same interface. For example, you could also use WWW::Mechanize::Cached
to cache requests on disk, so that subsequent runs of your app can run faster
and be less likely to exceed rate limits.
.SS "user"
.IX Subsection "user"
This can be set as a default user to use for \s-1API\s0 calls that require
the user parameter to be set.
.PP
Examples:
.PP
.Vb 2
\&    my $c = Pithub::Repos::Collaborators\->new( user => \*(Aqplu\*(Aq );
\&    my $result = $c\->list( repo => \*(AqPithub\*(Aq );
.Ve
.PP
There are two helper methods:
.IP "\(bu" 4
\&\fBclear_user\fR: reset the user attribute
.IP "\(bu" 4

.Sp
\&\fBhas_user\fR: check if the user attribute is set
.PP
It might make sense to use this together with the repo attribute:
.PP
.Vb 4
\&    my $c = Pithub::Repos::Commits\->new( user => \*(Aqplu\*(Aq, repo => \*(AqPithub\*(Aq );
\&    my $result = $c\->list;
\&    my $result = $c\->list_comments;
\&    my $result = $c\->get(\*(Aq6b6127383666e8ecb41ec20a669e4f0552772363\*(Aq);
.Ve
.SS "utf8"
.IX Subsection "utf8"
This can set utf8 flag.
.PP
Examples:
.PP
.Vb 2
\&    my $p = Pithub\->new(utf8 => 0); # disable utf8 en/decoding
\&    my $p = Pithub\->new(utf8 => 1); # enable utf8 en/decoding (default)
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "request"
.IX Subsection "request"
This method is the central point: All Pithub are using this method
for making requests to the Github. If Github adds a new \s-1API\s0 call that
is not yet supported, this method can be used directly. It accepts
an hash with following keys:
.IP "\(bu" 4
\&\fBmethod\fR: mandatory string, one of the following:
.RS 4
.IP "\(bu" 4
\&\s-1DELETE\s0
.IP "\(bu" 4
\&\s-1GET\s0
.IP "\(bu" 4
\&\s-1PATCH\s0
.IP "\(bu" 4
\&\s-1POST\s0
.IP "\(bu" 4
\&\s-1PUT\s0
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\fBpath\fR: mandatory string of the relative path used for making the
\&\s-1API\s0 call.
.IP "\(bu" 4
\&\fBdata\fR: optional data reference, usually a reference to an array
or hash. It must be possible to serialize this using \s-1JSON\s0.
This will be the \s-1HTTP\s0 request body.
.IP "\(bu" 4
\&\fBoptions\fR: optional hash reference to set additional options on
the request. So far \f(CW\*(C`prepare_request\*(C'\fR is supported. See
more about that in the examples below. So this can be used on
\&\fBevery\fR method which maps directly to an \s-1API\s0 call.
.IP "\(bu" 4
\&\fBparams\fR: optional hash reference to set additional \f(CW\*(C`GET\*(C'\fR
parameters. This could be achieved using the \f(CW\*(C`prepare_request\*(C'\fR
in the \f(CW\*(C`options\*(C'\fR hashref as well, but this is shorter. It's
being used in list method of Pithub::Issues
for example.
.PP
Usually you should not end up using this method at all. It's only
available if Pithub is missing anything from the Github v3 \s-1API.\s0
Though here are some examples how to use it:
.IP "\(bu" 4
Same as \*(L"list\*(R" in Pithub::Issues:
.Sp
.Vb 9
\&    my $p      = Pithub\->new;
\&    my $result = $p\->request(
\&        method => \*(AqGET\*(Aq,
\&        path   => \*(Aq/repos/plu/Pithub/issues\*(Aq,
\&        params => {
\&            state     => \*(Aqclosed\*(Aq,
\&            direction => \*(Aqasc\*(Aq,
\&        }
\&    );
.Ve
.IP "\(bu" 4
Same as \*(L"get\*(R" in Pithub::Users:
.Sp
.Vb 5
\&    my $p = Pithub\->new;
\&    my $result = $p\->request(
\&        method => \*(AqGET\*(Aq,
\&        path   => \*(Aq/users/plu\*(Aq,
\&    );
.Ve
.IP "\(bu" 4
Same as \*(L"create\*(R" in Pithub::Gists:
.Sp
.Vb 10
\&    my $p      = Pithub\->new;
\&    my $method = \*(AqPOST\*(Aq;
\&    my $path   = \*(Aq/gists\*(Aq;
\&    my $data   = {
\&        description => \*(Aqthe description for this gist\*(Aq,
\&        public      => 1,
\&        files       => { \*(Aqfile1.txt\*(Aq => { content => \*(AqString file content\*(Aq } }
\&    };
\&    my $result = $p\->request(
\&        method => $method,
\&        path   => $path,
\&        data   => $data,
\&    );
.Ve
.IP "\(bu" 4
Same as \*(L"get\*(R" in Pithub::GitData::Trees:
.Sp
.Vb 10
\&    my $p       = Pithub\->new;
\&    my $method  = \*(AqGET\*(Aq;
\&    my $path    = \*(Aq/repos/miyagawa/Plack/issues/209\*(Aq;
\&    my $data    = undef;
\&    my $options = {
\&        prepare_request => sub {
\&            my ($request) = @_;
\&            $request\->header( Accept => \*(Aqapplication/vnd.github\-issue.html+json\*(Aq );
\&        },
\&    };
\&    my $result = $p\->request(
\&        method  => $method,
\&        path    => $path,
\&        data    => $data,
\&        options => $options,
\&    );
.Ve
.PP
This method always returns a Pithub::Result object.
.SS "has_token (?$request)"
.IX Subsection "has_token (?$request)"
This method checks if a token has been specified, or if not, and a request
object is passed, then it looks for an Authorization header in the request.
.SS "rate_limit"
.IX Subsection "rate_limit"
Query the rate limit for the current object and authentication method.
.SH "AUTHOR"
.IX Header "AUTHOR"
Johannes Plunien <plu@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011 by Johannes Plunien.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.