POE::Component::Github - A POE component for the Github API

POE-Component-Github documentation  | view source Contained in the POE-Component-Github distribution.

Index

NAME

Top

POE::Component::Github - A POE component for the Github API

SYNOPSIS

Top

   use strict;
   use warnings;
   use POE qw(Component::Github);

   my $user = 'bingos';

   my $github = POE::Component::Github->spawn();

   POE::Session->create(
     package_states => [
   	'main' => [qw(_start _github)],
     ],
   );

   $poe_kernel->run();
   exit 0;

   sub _start {
     $poe_kernel->post( $github->get_session_id, 'user', 'show', { event => '_github', user => $user }, );
     return;
   }

   sub _github {
     my ($kernel,$heap,$resp) = @_[KERNEL,HEAP,ARG0];
     use Data::Dumper;
     warn Dumper($resp);
     $github->yield( 'shutdown' );
     return;
   }

DESCRIPTION

Top

POE::Component::Github is a POE component that provides asynchronous access to the Github API http://develop.github.com/ to other POE sessions or components. It was inspired by Net::Github.

The component handles communicating with the Github API and will parse the JSON data returned into perl data structures for you.

The component also implements flood control to ensure that no more than 60 requests are made per minute ( which is the current limit ).

CONSTRUCTOR

Top

spawn

Spawns a new POE::Component::Github session and returns an object. Takes a number of optional parameters:

  'login', provide a default login name to use for authenticated requests;
  'token', provide a default Github API token to use for authenticated requests;

METHODS

Top

The following methods are available from the object returned by spawn.

get_session_id

Returns the POE session ID of the component's session.

yield

Send an event to the component's session.

INPUT EVENTS

Top

These are events that the component will accept. The format of all events is:

  $poe_kernel->post( POCO_GITHUB, EVENT, COMMAND, HASHREF_OF_OPTIONS );

or

  $github_object->yield( EVENT, COMMAND, HASHREF_OF_OPTIONS );

Where EVENT is either user, repositories, commits, object, issues or network.

Where authentication is required it will be indicated. This may be either provided during spawn or provided as arguments to each command. You may obtain the token for your Github account from https://github.com/account

Three options are common to all commands, event, session and postback.

It is possible to send arbitary data with your query. If you are using postback the best way to achieve this is using the normal postback mechanism. Otherwise you may provide underscore prefixed keys in the hashref that you send with requests. These will be sent back with the results of your request.

event

The name of the event in the requesting session to send the results. Mandatory unless postback is specified.

session

Specify that an alternative session receive the results event instead, purely optional, the default is to send to the requesting session.

postback

Instead of specifying an event, one may specify a POE::Session postback instead. See the docs for POE::Session for more details.

User API

http://develop.github.com/p/users.html

Searching users, getting user information and managing authenticated user account information.

Send the event user with one of the following commands:

search

Search for users. Provide the parameter user to search for.

  $poe_kernel->post( $github->get_session_id, 
	'user', 'search', { event => '_search', user => 'moocow' } );
show

Show extended information about a user. Provide the parameter user to query.

  $poe_kernel->post( $github->get_session_id, 
	'user', 'show', { event => '_show', user => 'moocow' } );

If authentication credentials are provided a show on your own user will have extra extended information regarding disk usage etc.

following

Obtain a list of the people a user is following. Provide the parameter user to query.

  $poe_kernel->post( $github->get_session_id, 
	'user', 'following', { event => '_following', user => 'moocow' } );
followers

Obtain a list of the people who are following a user. Provide the parameter user to query.

  $poe_kernel->post( $github->get_session_id, 
	'user', 'followers', { event => '_followers', user => 'moocow' } );

These following commands require authentication:

Where data values are required these should be passed via the values parameter which should be a hashref of key/value pairs.

update

Update your user information. Provide name, email, blog, company, location as keys to values.

  $poe_kernel->post( $github->get_session_id, 'user', 'update',
	  { 
	    event  => '_update', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    values => 
	    {
		name     => 'Mr. Cow',
		location => 'The Farm',
		email    => 'moocow@moo.cow',
	    },
          } 
  );
follow

Follow a particular user. Provide the parameter user to follow.

  $poe_kernel->post( $github->get_session_id, 'user', 'follow',
	  { 
	    event => '_follow', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user => 'pigdog' 
	  } 
  );
unfollow

Stop following a particular user. Provide the parameter user to unfollow.

  $poe_kernel->post( $github->get_session_id, 'user', 'unfollow',
	  { 
	    event => '_unfollow', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user => 'pigdog' 
	  } 
  );
pub_keys

List your public keys.

  $poe_kernel->post( $github->get_session_id, 'user', 'pub_keys',
	  { 
	    event => '_pubkeys', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	  } 
  );
add_key

Add a public key. Requires a name and the key passed as values.

  $poe_kernel->post( $github->get_session_id, 'user', 'add_key',
	  { 
	    event => '_addkey', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    values => 
	    {
		name     => 'My Public Key',
		'key'	 => $some_public_key,
	    },
	  } 
  );
remove_key

Removes a public key. Requires a key id passed as values.

  $poe_kernel->post( $github->get_session_id, 'user', 'remove_key',
	  { 
	    event => '_removekey', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    values => 
	    {
		id	 => $key_id,
	    },
	  } 
  );
emails

List your emails.

  $poe_kernel->post( $github->get_session_id, 'user', 'emails',
	  { 
	    event => '_emails', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	  } 
  );
add_email

Adds an email. Requires an email passed as values.

  $poe_kernel->post( $github->get_session_id, 'user', 'add_email',
	  { 
	    event => '_addemail', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    values => 
	    {
		email	 => 'moocow@thefarm.cow',
	    },
	  } 
  );
remove_email

Removes an existing email. Requires an email passed as values.

  $poe_kernel->post( $github->get_session_id, 'user', 'remove_email',
	  { 
	    event => '_removeemail', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    values => 
	    {
		email	 => 'moocow@thefarm.cow',
	    },
	  } 
  );

Repository API

http://develop.github.com/p/repo.html

Searching repositories, getting repository information and managing authenticated repository information.

Send the event repositories with one of the following commands:

search

Search for a repository. Provide the parameter repo to search for.

   $poe_kernel->post( $github->get_session_id,
         'repositories', 'search', { event => '_search', repo => 'the-barn' } );
show

To look at more in-depth information for a repository. Provide user and repo for the repository.

   $poe_kernel->post( $github->get_session_id,
         'repositories', 'show', { event => '_show', user => 'moocow', repo => 'the-barn' } );
list

List out all the repositories for a user. Provide the user to look at.

   $poe_kernel->post( $github->get_session_id,
         'repositories', 'list', { event => '_list', user => 'moocow' } );
network

Look at the full network for a repository. Provide the user and repo.

   $poe_kernel->post( $github->get_session_id,
         'repositories', 'network', { event => '_network', user => 'moocow', repo => 'the-barn' } );
tags

List the tags for a repository. Provide the user and repo.

   $poe_kernel->post( $github->get_session_id,
         'repositories', 'tags', { event => '_tags', user => 'moocow', repo => 'the-barn' } );
branches

List the branches for a repository. Provide the user and repo.

   $poe_kernel->post( $github->get_session_id,
         'repositories', 'branches', { event => '_branches', user => 'moocow', repo => 'the-barn' } );
collaborators

List the collaborators for a repository. Provide the user and repo.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'collaborators',
	  { 
	    event => '_collaborators', 
	    user  => 'moocow',
	    repo  => 'the-barn',
	  } 
  );

These following commands require authentication:

Where data values are required these should be passed via the values parameter which should be a hashref of key/value pairs.

watch

Start watching a repository. Provide the user and repo to watch.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'watch',
	  { 
	    event => '_watch', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-field',
	  } 
  );
unwatch

Stop watching a repository. Provide the user and repo to unwatch.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'unwatch',
	  { 
	    event => '_unwatch', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-field',
	  } 
  );
fork

Fork a repository. Provide the user and repo to fork.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'fork',
	  { 
	    event => '_fork', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-field',
	  } 
  );
create

Create a new repository. 

  $poe_kernel->post( $github->get_session_id, 'repositories', 'create',
	  { 
	    event => '_create', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    values => 
	    {
		name 		=> 'the-meadow',
		description 	=> 'The big meadow with the stream',
		homepage 	=> 'http://moo.cow/meadow/'
		public 		=> 1,	# Or 0 for private
	    },
	  } 
  );
delete

Delete one of your repositories. Provide repo. The first return from this will contain a delete_token. Submit the delete request again, passing the delete_token in values.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'delete',
	  { 
	    event => '_delete_token', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	  } 
  );

  $poe_kernel->post( $github->get_session_id, 'repositories', 'delete',
	  { 
	    event => '_delete', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	    values => 
	    {
		delete_token 	=> $delete_token,
	    },
	  } 
  );
set_private

Make a public repository private. Provide the repo to make private.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'set_private',
	  { 
	    event => '_set_private', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	  } 
  );
set_public

Make a private repository public. Provide the repo to make public.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'set_public',
	  { 
	    event => '_set_public', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	  } 
  );
deploy_keys

List the deploy keys for a repository. Provide the repo.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'deploy_keys',
	  { 
	    event => '_deploy_keys', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	  } 
  );
add_deploy_key

Add a deploy key. Provide the repo and the title and key as values.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'add_deploy_key',
	  { 
	    event => '_add_deploy_key', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	    values => 
	    {
		title => $title,
		key   => $key,
	    },
	  } 
  );
remove_deploy_key

Remove a deploy key. Provide the repo and the key id id as values.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'remove_deploy_key',
	  { 
	    event => '_remove_deploy_key', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	    values => 
	    {
		id => $key_id,
	    },
	  } 
  );
add_collaborator

Add a collaborator to one of your repositories. Provide repo and the user to add.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'add_collaborator',
	  { 
	    event => '_add_collaborator', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	    user   => 'pigdog',
	  } 
  );
remove_collaborator

Remove a collaborator from one of your repositories. Provide repo and the user to remove.

  $poe_kernel->post( $github->get_session_id, 'repositories', 'remove_collaborator',
	  { 
	    event => '_remove_collaborator', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    repo   => 'the-meadow',
	    user   => 'pigdog',
	  } 
  );

Commit API

http://develop.github.com/p/commits.html

Query commits on repositories

Send the event commits with one of the following commands:

branch

List commits on a branch. Provide user, repo and branch. The default for branch is master if not supplied.

  $poe_kernel->post( $github->get_session_id, 'commits', 'branch',
	  { 
	    event => '_branch', 
	    user  => 'moocow',
	    repo  => 'the-barn',
	    branch => 'master', # default is 'master' if not supplied.
	  } 
  );
file

List commits for a file on a branch. Provide user, repo and branch. The default for branch is master if not supplied.

  $poe_kernel->post( $github->get_session_id, 'commits', 'file',
	  { 
	    event => '_file', 
	    user  => 'moocow',
	    repo  => 'the-barn',
	    branch => 'master', # default is 'master' if not supplied.
	    file => 'herd.txt',
	  } 
  );
commit

Show a specific commit. Provide user, repo and commit.

  $poe_kernel->post( $github->get_session_id, 'commits', 'commit',
	  { 
	    event => '_commit', 
	    user  => 'moocow',
	    repo  => 'the-barn',
	    commit => '5071bf9fbfb81778c456d62e111440fdc776f76c',
	  } 
  );

Object API

http://develop.github.com/p/object.html

Query objects on repositories

Send the event object with one of the following commands:

tree

Get the contents of a tree by tree sha. Provide user, repo and tree_sha.

  $poe_kernel->post( $github->get_session_id, 'object', 'tree',
	  { 
	    event => '_tree', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	    tree_sha => 'f7a5de2e224ec94182a3c2c081f4e7f4df70da4',
	  } 
  );
blob

Can get the data about a blob by tree sha and path. Provide user, repo, tree_sha and path.

  $poe_kernel->post( $github->get_session_id, 'object', 'blob',
	  { 
	    event => '_blob', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	    tree_sha => 'f7a5de2e224ec94182a3c2c081f4e7f4df70da4',
	    path     => 'herd.txt',
	  } 
  );
raw

Get the contents of a blob (can be tree, file or commits). Provide user, repo and tree_sha or sha

  $poe_kernel->post( $github->get_session_id, 'object', 'raw',
	  { 
	    event => '_raw', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	    tree_sha => 'f7a5de2e224ec94182a3c2c081f4e7f4df70da4',
	  } 
  );

Issues API

http://develop.github.com/p/issues.html

The API for GitHub Issues

Send the event issues with one of the following commands:

search

Search for issues in a repo. Provide user and repo, the state of issue to look for (open|closed) and the search term to look for.

  $poe_kernel->post( $github->get_session_id, 'issues', 'search',
	  { 
	    event => '_search', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	    state    => 'open',
	    search   => 'broken door',
	  } 
  );
list

Get a list of issues for a project. Provide user and repo.

  $poe_kernel->post( $github->get_session_id, 'issues', 'list',
	  { 
	    event => '_list', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	  } 
  );
view

Get data on an individual issue by number. Provide user and repo and id of the issue.

  $poe_kernel->post( $github->get_session_id, 'issues', 'view',
	  { 
	    event => '_view', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	    id	     => $id,
	  } 
  );

These following commands require authentication:

Where data values are required these should be passed via the values parameter which should be a hashref of key/value pairs.

open

Open a new issue on a project. Provide user and repo and title and body as values.

  $poe_kernel->post( $github->get_session_id, 'issues', 'open',
	  { 
	    event => '_open', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    values => 
	    {
		title => 'There is no mud',
		body  => 'There is no mud in the sty, a sty requires mud',
	    },
	  } 
  );
close

Close an existing issue on a project. Provide user and repo and the issue id.

  $poe_kernel->post( $github->get_session_id, 'issues', 'close',
	  { 
	    event => '_close', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    id     => $issue_id,
	  } 
  );
reopen

Reopen a closed issue on a project. Provide user and repo and the issue id.

  $poe_kernel->post( $github->get_session_id, 'issues', 'reopen',
	  { 
	    event => '_reopen', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    id     => $issue_id,
	  } 
  );
edit

Edit an issue on a project. Provide user, repo and id, and title and body as values.

  $poe_kernel->post( $github->get_session_id, 'issues', 'edit',
	  { 
	    event => '_edit', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    id     => $issue_id,
	    values => 
	    {
		title => 'There is no mud',
		body  => 'There is no mud in the sty, a sty requires mud',
	    },
	  } 
  );
add_label

Add a label to an issue. Provide user, repo and id and label

  $poe_kernel->post( $github->get_session_id, 'issues', 'add_label',
	  { 
	    event => '_add_label', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    id     => $issue_id,
	    label  => $label,
	  } 
  );
remove_label

Remove a label from an issue. Provide user, repo and id and label

  $poe_kernel->post( $github->get_session_id, 'issues', 'remove_label',
	  { 
	    event => '_remove_label', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    id     => $issue_id,
	    label  => $label,
	  } 
  );
comment

Comment on an issue. Provide user, repo and id. Provide comment as values.

  $poe_kernel->post( $github->get_session_id, 'issues', 'comment',
	  { 
	    event => '_comment', 
	    login  => 'moocow',
	    token  => '54b5197d7f92f52abc5c7149b313cf51', # faked
	    user   => 'pigdog',
	    repo   => 'the-sty',
	    id     => $issue_id,
	    values => 
	    {
		comment => 'This is amazing',
	    },
	  } 
  );

Network API

http://develop.github.com/p/network.html

The ( Not So ) Secret Network API

Send the event network with one of the following commands:

network_meta

Provide user and repo.

  $poe_kernel->post( $github->get_session_id, 'network', 'network_meta',
	  { 
	    event => '_network', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	  } 
  );
network_data_chunk

Provide user and repo, and nethash, optionally start and end.

  $poe_kernel->post( $github->get_session_id, 'network', 'network_data_chunk',
	  { 
	    event => '_network', 
	    user     => 'moocow',
	    repo     => 'the-barn',
	    nethash  => $nethash,
	    start    => $start,
	    end      => $end,
	  } 
  );

OUTPUT EVENTS

Top

Events that the component sends back to your requesting session will have a HASHREF as ARG0 ( postback requests will have this as the first item in the ARRAYREF in ARG1 ).

Any arbitary data that you passed as underscore prefixed keys will exist along with the following:

  'data', contains the data that was returned from the API call, if successful.
  'error', if there was a problem, this will exist and contain some text relating to the error.

Example, this is returned by the SYNOPSIS

  {
     'cmd' => 'show',
     'user' => 'bingos',
     'data' => {
                'user' => {
                           'location' => undef,
                           'followers_count' => 37,
                           'name' => 'Chris Williams',
                           'blog' => 'http://use.perl.org/~bingos/journal/',
                           'public_repo_count' => 100,
                           'login' => 'bingos',
                           'email' => '',
                           'created_at' => '2009/03/10 08:13:36 -0700',
                           'public_gist_count' => 1,
                           'id' => 62011,
                           'company' => undef,
                           'following_count' => 129
                          }
               }
  }

AUTHOR

Top

Chris BinGOs Williams <chris@bingosnet.co.uk>

KUDOS

Top

Fayland for Net::Github and doing the dog-work of translating the Github API.

Chris perigrin Prather for MooseX::POE

Github http://github.com/

LICENSE

Top

Copyright © Chris Williams

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

SEE ALSO

Top

http://develop.github.com/

Net::Github

MooseX::POE

POE-Component-Github documentation  | view source Contained in the POE-Component-Github distribution.