NAME¶
Pithub::Base - Github v3 base class for all Pithub modules
VERSION¶
version 0.01025
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.
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 "token" or the "user"
and "repo" attributes.
The "user" and "repo" attributes are special: They get even
set on method calls that require
both 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 "user" and "repo" attribute in the
constructor, this will also be set once you get to the Pithub::Repos::Keys
object via the "keys" method.
Examples:
# just to demonstrate the "magic"
print Pithub->new( user => 'plu' )->repos->user; # plu
print Pithub::Repos->new( user => 'plu' )->keys->user; # plu
# and now some real use cases
my $p = Pithub->new( user => 'plu', repo => 'Pithub' );
my $r = $p->repos;
print $r->user; # plu
print $r->repo; # pithub
# usually you would do
print $r->get( user => 'plu', repo => 'Pithub' )->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 => 'miyagawa', repo => 'Plack' )->content->{html_url};
# it even works on other objects
my $repo = Pithub::Repos->new( user => 'plu', repo => 'Pithub' );
print $repo->watching->list->first->{login};
ATTRIBUTES¶
See also: "auto_pagination" in Pithub::Result.
api_uri¶
Defaults to <
https://api.github.com>.
Examples:
my $users = Pithub::Users->new( api_uri => 'https://api-foo.github.com' );
# ... is the same as ...
my $users = Pithub::Users->new;
$users->api_uri('https://api-foo.github.com');
jsonp_callback¶
If you want to use the response directly in JavaScript for example, Github
supports setting a JSONP callback parameter.
See also: <
http://developer.github.com/v3/#json-p-callbacks>.
Examples:
my $p = Pithub->new( jsonp_callback => 'loadGithubData' );
my $result = $p->users->get( user => 'plu' );
print $result->raw_content;
The result will look like this:
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",
...
}
})
Be careful: The content method will try to decode the JSON into a Perl
data structure. This is not possible if the "jsonp_callback" is set:
# 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( ...
There are two helper methods:
- •
- clear_jsonp_callback: reset the jsonp_callback attribute
- •
- has_jsonp_callback: check if the jsonp_callback attribute is
set
per_page¶
By default undef, so it defaults to Github's default. See also:
<
http://developer.github.com/v3/#pagination>.
Examples:
my $users = Pithub::Users->new( per_page => 100 );
# ... is the same as ...
my $users = Pithub::Users->new;
$users->per_page(100);
There are two helper methods:
- •
- clear_per_page: reset the per_page attribute
- •
- has_per_page: check if the per_page attribute is set
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 API. It's useful for setting MIME
types for example. See also: <
http://developer.github.com/v3/mimes/>.
This is the right way to go if you want to modify the HTTP request of
all API calls. If you just want to change a few, consider sending the
"prepare_request" parameter on any method call.
Let's use this example from the Github docs:
Html
"application/vnd.github-issue.html+json"
Return html rendered from the body's markdown. Response will include body_html.
Examples:
my $p = Pithub::Issues->new(
prepare_request => sub {
my ($request) = @_;
$request->header( Accept => 'application/vnd.github-issue.html+json' );
}
);
my $result = $p->get(
user => 'miyagawa',
repo => 'Plack',
issue_id => 209,
);
print $result->content->{body_html};
Please compare to the solution where you set the custom HTTP header on the
method call, instead globally on the object:
my $p = Pithub::Issues->new;
my $result = $p->get(
user => 'miyagawa',
repo => 'Plack',
issue_id => 209,
options => {
prepare_request => sub {
my ($request) = @_;
$request->header( Accept => 'application/vnd.github-issue.html+json' );
},
}
);
print $result->content->{body_html};
repo¶
This can be set as a default repo to use for API 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.
Examples:
my $c = Pithub::Repos::Collaborators->new( repo => 'Pithub' );
my $result = $c->list( user => 'plu' );
There are two helper methods:
- •
- clear_repo: reset the repo attribute
- •
- has_repo: check if the repo attribute is set
token¶
If the OAuth token is set, Pithub will sent it via an HTTP header on each API
request. Currently the basic authentication method is not supported.
See also: <
http://developer.github.com/v3/oauth/>
By default a LWP::UserAgent object, but it can be anything that implements the
same interface.
user¶
This can be set as a default user to use for API calls that require the user
parameter to be set.
Examples:
my $c = Pithub::Repos::Collaborators->new( user => 'plu' );
my $result = $c->list( repo => 'Pithub' );
There are two helper methods:
- •
- clear_user: reset the user attribute
- •
- has_user: check if the user attribute is set
It might make sense to use this together with the repo attribute:
my $c = Pithub::Repos::Commits->new( user => 'plu', repo => 'Pithub' );
my $result = $c->list;
my $result = $c->list_comments;
my $result = $c->get('6b6127383666e8ecb41ec20a669e4f0552772363');
METHODS¶
request¶
This method is the central point: All Pithub are using this method for making
requests to the Github. If Github adds a new API call that is not yet
supported, this method can be used directly. It accepts an hash with following
keys:
- •
- method: mandatory string, one of the following:
- •
- DELETE
- •
- GET
- •
- PATCH
- •
- POST
- •
- PUT
- •
- path: mandatory string of the relative path used for making the API
call.
- •
- data: optional data reference, usually a reference to an array or
hash. It must be possible to serialize this using JSON. This will be the
HTTP request body.
- •
- options: optional hash reference to set additional options on the
request. So far "prepare_request" is supported. See more about
that in the examples below. So this can be used on every method
which maps directly to an API call.
- •
- params: optional hash reference to set additional "GET"
parameters. This could be achieved using the "prepare_request"
in the "options" hashref as well, but this is shorter. It's
being used in list method of Pithub::Issues for example.
Usually you should not end up using this method at all. It's only available if
Pithub is missing anything from the Github v3 API. Though here are some
examples how to use it:
- •
- Same as "list" in Pithub::Issues:
my $p = Pithub->new;
my $result = $p->request(
method => 'GET',
path => '/repos/plu/Pithub/issues',
params => {
state => 'closed',
direction => 'asc',
}
);
- •
- Same as "get" in Pithub::Users:
my $p = Pithub->new;
my $result = $p->request(
method => 'GET',
path => '/users/plu',
);
- •
- Same as "create" in Pithub::Gists:
my $p = Pithub->new;
my $method = 'POST';
my $path = '/gists';
my $data = {
description => 'the description for this gist',
public => 1,
files => { 'file1.txt' => { content => 'String file content' } }
};
my $result = $p->request(
method => $method,
path => $path,
data => $data,
);
- •
- Same as "get" in Pithub::GitData::Trees:
my $p = Pithub->new;
my $method = 'GET';
my $path = '/repos/miyagawa/Plack/issues/209';
my $data = undef;
my $options = {
prepare_request => sub {
my ($request) = @_;
$request->header( Accept => 'application/vnd.github-issue.html+json' );
},
};
my $result = $p->request(
method => $method,
path => $path,
data => $data,
options => $options,
);
This method always returns a Pithub::Result object.
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.
AUTHOR¶
Johannes Plunien <plu@cpan.org>
COPYRIGHT AND LICENSE¶
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.