NAME

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

VERSION

version 0.01002

DESCRIPTION

All "MODULES" in Pithub 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.

ATTRIBUTES

auto_pagination

See also: "auto_pagination" in Pithub::Result.

api_uri

Defaults to https://api.github.com.

Examples:

    $users = Pithub::Users->new( api_uri => 'https://api-foo.github.com' );

    $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:

    $p = Pithub->new( jsonp_callback => 'loadGithubData' );
    $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:

    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:

    $users = Pithub::Users->new( per_page => 100 );

    $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

repo

This can be set as a default repo to use for API calls that require the repo parameter to be set.

Examples:

    $c = Pithub::Repos::Collaborators->new( repo => 'Pithub' );
    $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/

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:

    $c = Pithub::Repos::Collaborators->new( user => 'plu' );
    $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 makes sense to use this together with the repo attribute:

    $c = Pithub::Repos::Commits->new( user => 'plu', repo => 'Pithub' );
    $result = $c->list;
    $result = $c->list_comments;
    $reuslt = $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 following parameters:

• $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::Any. This will be the HTTP request body.

• $options: optional hash reference to set additional options on the request. So far only prepare_uri is supported. See more about that in the examples below.

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 "get" in Pithub::Users:

      $p = Pithub->new;
      $result = $p->request( GET => '/users/plu' );

  Same as "create" in Pithub::Gists:

      $p      = Pithub->new;
      $method = 'POST';
      $path   = '/gists';
      $data   = {
          description => 'the description for this gist',
          public      => 1,
          files       => { 'file1.txt' => { content => 'String file content' } }
      };
      $result = $p->request( $method, $path, $data );

  Same as "get" in Pithub::GitData::Trees:

      $p       = Pithub->new;
      $method  = 'GET';
      $path    = '/repos/plu/Pithub/git/trees/aac667c5aaa6e49572894e8c722d0705bb00fab2';
      $data    = undef;
      $options = {
          prepare_uri => sub {
              my ($uri) = @_;
              my %query = ( $uri->query_form, recursive => 1 );
              $uri->query_form(%query);
          },
      };
      $result = $p->request( $method, $path, $data, $options );

  Always be careful using prepare_uri and query_form. If the option "per_page" is set, you might override the pagination parameter. That's the reason for this construct:

      my %query = ( $uri->query_form, recursive => 1 );
      $uri->query_form(%query);

  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.

cpanm Pithub

perl -MCPAN -e shell
install Pithub