Johannes Plunien > Pithub-0.01012 > Pithub::Base

Download:
Pithub-0.01012.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.01012   Source   Latest Release: Pithub-0.01025

NAME ^

Pithub::Base - Github v3 base class for all Pithub modules

VERSION ^

version 0.01012

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 ^

auto_pagination

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:

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:

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:

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/

ua

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:

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:

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:

This method always returns a Pithub::Result object.

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.

syntax highlighting: