NAME

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

SYNOPSIS

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

DESCRIPTION

GitHub::Extract is a simple light weight interface to 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 Archive::Extract. Any existing tooling code which uses Archive::Extract to work with release tarballs should be trivially upgradable to work with projects directly from GitHub instead.

METHODS

new

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

                # 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
                ),
        );

The 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.

username

The GitHub username identifying the owner of the repository.

repository

The name of the repository within the account or organisation.

branch

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

http

GitHub::Extract will create a HTTP::Tiny object with default settings to download the zipball from GitHub.

This parameter allows you to use your own custom HTTP::Tiny client with alternative settings.

Returns a new GitHub::Extract object, or false on error.

username

The username method returns the GitHub username for the request.

repository

The repository method returns the GitHub repository name for the request.

branch

The branch method returns the name of the branch to be fetched.

url

The url method returns the full download URL used to fetch the zipball.

http

The http method returns the HTTP client that will be used for the request.

archive

The archive method will return the absolute path to the downloaded zip file on disk, if the download was successful.

Returns undef if the download was not completed successfully.

archive_extract

The archive_extract method will return the Archive::Extract object used to extract the files from the zipball, whether or not it extracted successfully.

Returns undef if the download was not completed successfully.

extract

        $project->extract( to => '/output/path' );

Extracts the archive represented by the GitHub::Extract object to the path of your choice as specified by the to argument. Defaults to cwd().

In the case that you did not specify a to argument, the output file will be the name of the archive file, stripped from its .gz suffix, in the current working directory.

It will return true on success, and false on failure.

pushd

        my $guard = $project->pushd( to => '/output/path' );

The pushd method downloads and extracts the project from GitHub, and then temporarily changes the current working directory into the extract path of the project.

Returns a File::pushd guard object which will return the current working directory to the original location when it is deleted, or false if the archive was not extracted.

extract_path

        # Prints '/output/path/myproject-0.01-af41bc'
        if ( $project->extract( to => '/output/path' ) ) {
                print $project->extract_path;
        }

The extract_path method returns the absolute path of the logical root directory of the zipball, once it has been extracted.

Since some archives will contain a single root directory within the zip file with which the content is placed (and some will not) this compensates for the different, detecting the logical root automatically.

See "extract" in Archive::Extract for more details.

files

The files method returns an array ref with the paths of all the files in the archive, relative to the to argument you specified.

To get the full path to an extracted file, you would use:

    File::Spec->catfile( $to, $ae->files->[0] );

See "extract" in Archive::Extract for more details.

error

        my $simple  = $project->error;
        my $verbose = $project->error(1);

The error method returns the last encountered error as string.

Pass it a true value to get the detailed output instead, as produced by "longmess" in Carp.

GLOBAL VARIABLES

All global variables share the names and behaviour of the equivalent variables in Archive::Extract. Their value will be propogated down to the equivalent variables in Archive::Extract whenever it is being used.

$GitHub::Extract::DEBUG

Set this variable to true to have all calls to command line tools be printed out, including all their output.

This also enables Carp::longmess errors, instead of the regular carp errors.

Good for tracking down why things don't work with your particular setup.

Defaults to false.

$GitHub::Extract::WARN

This variable controls whether errors encountered internally by GitHub::Extract should be carp'd or not.

Set to false to silence warnings. Inspect the output of the error() method manually to see what went wrong.

Defaults to true.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=GitHub-Extract

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>

SEE ALSO

Archive::Extract

http://github.com/

COPYRIGHT

Copyright 2012 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

cpanm GitHub::Extract

perl -MCPAN -e shell
install GitHub::Extract