view release on metacpan or  search on metacpan

lib/GitHub/Extract.pm  view on Meta::CPAN

package GitHub::Extract;

=pod

=head1 NAME

GitHub::Extract - Extract an exported copy of a GitHub project

=head1 SYNOPSIS

	my $project = GitHub::Extract->new(
		username => 'adamkennedy',
		project  => 'PPI',
	);
	
	$project->extract( to => '/my/directory' );

=head1 DESCRIPTION

L<GitHub::Extract> is a simple light weight interface to
L<http://github.com/> for the sole purpose of retrieving and extracting
a "zipball" of a public (and likely open source) project.

It makes use of the plain route used by the user interface "zip" button,
and as a result it avoids the need to use the full GitHub API and client.

This module shares extends (and emulates where needed) the API of
L<Archive::Extract>. Any existing tooling code which uses L<Archive::Extract>
to work with release tarballs should be trivially upgradable to work with
projects directly from GitHub instead.

=head1 METHODS

=cut

use 5.008;
use strict;
use warnings;
use Carp                  ();
use File::Spec       3.30 ();
use File::Temp       0.21 ();
use File::pushd      1.00 ();
use HTTP::Tiny      0.019 ();
use Params::Util     1.00 ();
use Archive::Extract 0.56 ();
use IO::Socket::SSL  1.56 (); # Needed for HTTP::Tiny SSL

our $VERSION = '0.02';
our $WARN    = 1;
our $DEBUG   = 0;

use Object::Tiny 1.01 qw{
	username
	repository
	branch
	url
	http
	archive
	archive_extract
};






######################################################################
# Constructor

=pod

=head2 new

	my $branch = GitHub::Extract->new(
		username   => 'adamkennedy',
		repository => 'PPI',

		# Fetch a branch other than master
		branch     => 'mybranch',

		# A custom HTTP client can be provided to any constructor
		http       => HTTP::Tiny->new(
			# Custom HTTP setup goes here
		),
	);

The C<new> constructor identifies a project to download (but does not take any
immediate action to do the download).

It takes a number of simple parameters to control where to download from.

=over 4

=item username

The GitHub username identifying the owner of the repository.

=item repository

The name of the repository within the account or organisation.

=item branch

An optional parameter identifying a particular branch to download. If not
specificied, the 'master' branch will be fetched.