POE::Component::Github - A POE component for the Github API
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; }
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 ).
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;
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.
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.
EVENT
user
repositories
commits
object
issues
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.
event
session
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.
underscore
The name of the event in the requesting session to send the results. Mandatory unless postback is specified.
Specify that an alternative session receive the results event instead, purely optional, the default is to send to the requesting session.
Instead of specifying an event, one may specify a POE::Session postback instead. See the docs for POE::Session for more details.
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.
values
update
Update your user information. Provide name, email, blog, company, location as keys to values.
name
email
blog
company
$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.
key
$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.
id
$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', }, } );
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 for a repository. Provide the parameter repo to search for.
repo
$poe_kernel->post( $github->get_session_id, 'repositories', 'search', { event => '_search', repo => 'the-barn' } );
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' } );
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', } );
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.
delete_token
$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.
title
$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', } );
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.
master
$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', } );
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.
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.
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
sha
$poe_kernel->post( $github->get_session_id, 'object', 'raw', { event => '_raw', user => 'moocow', repo => 'the-barn', tree_sha => 'f7a5de2e224ec94182a3c2c081f4e7f4df70da4', } );
http://develop.github.com/p/issues.html
The API for GitHub Issues
Send the event issues with one of the following commands:
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.
state
$poe_kernel->post( $github->get_session_id, 'issues', 'search', { event => '_search', user => 'moocow', repo => 'the-barn', state => 'open', search => 'broken door', } );
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, } );
open
Open a new issue on a project. Provide user and repo and title and body as values.
body
$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
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', }, } );
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.
nethash
start
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, } );
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 ).
ARG0
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
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 } } }
Chris BinGOs Williams <chris@bingosnet.co.uk>
BinGOs
Fayland for Net::Github and doing the dog-work of translating the Github API.
Chris perigrin Prather for MooseX::POE
perigrin
Github http://github.com/
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.
http://develop.github.com/
Net::Github
MooseX::POE
To install POE::Component::Github, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::Github
CPAN shell
perl -MCPAN -e shell install POE::Component::Github
For more information on module installation, please visit the detailed CPAN module installation guide.