The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
URL-Checkout-1.05
River stage zero No dependents
++
/ URL::Checkout

NAME

URL::Checkout - Get one or multiple files from a remote location

VERSION

Version 1.05

SYNOPSIS

Retrieve contents from a URL, no matter if the URL specifies a simple file via ftp or http, or a Repository of one of the well known VCS systems, cvs, svn, git, hg, Unlike LWP, this module makes no attempts to be perlish. We liberally call shell commands to do the real work. The author especially likes to call wget.

    use URL::Checkout;

    my $f = URL::Checkout->new(dest => '/tmp/outdir', verbose => 1);
    $f->auth($user, $pass);
    $f->dest($outdir);
    $f->method('*');

    #       obs://api.opensuse.org/source/home:jnweiger/fate?rev=19
    #       https://svn.suse.de/svn/inttools/trunk/features/fate
    $url = "ssh://user:pass@scm.somewhere.org/git/repo.git"; 
    $f->get($url);

    $m = $f->find_method($url);
    $cmd = $f->fmt_cmd($m, $url);
    chdir($f->dest());
    system $cmd;

SUBROUTINES/METHODS

new

Create a checkout object. It can be configured through several parameters to new, or through similarly named methods. If no destination directory is specified via dest, File::Temp is consulted to create a temporary directory.

auth($user, $pass)

An alternative to specifying user, pass with new. Provide authentication credentials for the remote access.

dest($directory)

dest()

Set and/or get the destination directory. The directory need not be created ahead of time.

list_methods()

Return a hash with method names as keys, detection patterns and retrieval commands. The values in this hash are aliases to the internal values. You can change them to e.g. add a -q flag if you find a command to be too noisy.

describe()

Returns a verbal description of the matching rules.

add_method(name, qr{url-match-pattern}, cmd_fmt_string, "Some descriptive text")

Multiple commands can be specified for each name. Commands should be written in bourne shell syntax, with the following named sprintf templates: %(user)s, %(pass)s, %(url)s, %(dest)s. Commands that contain %(user)s and/or %(pass)s are ignored, if username and/or password credentials are not given. Example:

  add_method('git', qr{^(git://.*|\.git/?)$}, "git clone --depth 1 %(url)s");

The destination directory is the current working directory while the command runs. The templates are expanded using String::ShellQuote and Text::Sprintf::Named.

If an array-ref of patterns is specified instead of a pattern, the patterns should be ordered by decreasing reliability. Methods are tested breadth-first.

If a subroutine reference is specified as third parameter, it is called with the URL and the return value of find_method(), and is expected to return a command or an array of commands.

method('*')

Limit the method by name. The default '*' means no limitation. An array of method names can be specified, which denotes a first match choice. This is helpful for URLs that do not match anything specific. This is harmless, as it still allows other methods if the URL matches there.

find_method($url)

Tests $url against the regexp patterns stored with each method. The first match is returned. If multiple patterns are specified per method, all other methods are tested, before the next set of patterns is tested.

Unless a method name was specified with method(), we return undef, if no pattern matches. With one or multiple method names specified, the first available method by that name is returned, when there is no pattern match.

fmt_cmd($meth_hash, $url)

Use a method hash as returned by find_method and prepare all possible commands from it with the given url. One or multiple commands are returned suitable for use with system or backticks.

get($url)

Similar to this code:

    $m = $f->find_method($url);
    system "".$f->fmt_cmd($m, $url);

Except that it tries further commands from fmt_cmd() if if the first fails. It also assures that the current working directory is $f->dest() while executing a command. Command names are printed to stdout, if verbose is set.

pre_cmd($method)

Helper function run by get(). This prepares temporary files if the method has a 'fake_home' and at least a username credential was given to auth(). This also creates the destination directory and changes into it.

post_cmd()

Cleanup handler run by get(). This removes any temporary files and restores the current working directory.

AUTHOR

Juergen Weigert, <jnw at cpan.org>

BUGS

Please report any bugs or feature requests to bug-file-checkout at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URL-Checkout. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc URL::Checkout

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2010 Juergen Weigert.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.