Provided by: libpithub-perl_0.01040-1_all bug

NAME

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

VERSION

       version 0.01040

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.

       Attributes passed along from the parent can be changed in the method call.

           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

       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
       Off by default.

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

   api_uri
       Defaults to <https://api.github.com>.  For GitHub Enterprise, you'll likely need an URL
       like <https://github.yourdomain.com/api/v3/>.

       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
       Controls how many items are fetched per API call, aka "page".  See also:
       <http://developer.github.com/v3/#pagination> and "auto_pagination".

       To minimize the number of API 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.

       Examples:

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

           # ... is the same as ...

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

       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/>

   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.

   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');

   utf8
       This can set utf8 flag.

       Examples:

           my $p = Pithub->new(utf8 => 0); # disable utf8 en/decoding
           my $p = Pithub->new(utf8 => 1); # enable utf8 en/decoding (default)

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.

   rate_limit
       Query the rate limit for the current object and authentication method.

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.