NAME

WebFS::FileCopy - Get, put, move, copy, and delete files located by URLs

SYNOPSIS

use WebFS::FileCopy;

my @res = get_urls('ftp://www.perl.com', 'http://www.netscape.com');
print $res[0]->content if $res[0]->is_success;

put_urls('put this text', 'ftp://ftp/incoming/new', 'file:/tmp/NEW');
move_url('file:/tmp/NEW', 'ftp://ftp/incoming/NEW.1');
delete_urls('ftp://ftp/incoming/NEW.1', 'file:/tmp/NEW');

copy_url('http://www.perl.com/index.html', 'ftp://ftp.host/outgoing/SIG');

copy_urls(['file:/tmp/file1', 'http://www.perl.com/index.html],
          ['file:/tmp/DIR1/', 'file:/tmp/DIR2', 'ftp://ftp/incoming/']);

my @list1 = list_url('file:/tmp');
my @list2 = list_url('ftp://ftp/outgoing/');

DESCRIPTION

This package provides some simple routines to read, move, copy, and delete files as references by URLs.

The distinction between files and directories in a URL is tested by looking for a trailing / in the path. If a trailing / exists, then the URL is considered to point to a directory, otherwise it is a file.

All of the following subroutines are exported to the users namespace automatically. If you do not want this, then require this package instead of useing it.

SUBROUTINES

get_urls url [url [url ...]]

The get_urls function will fetch the documents identified by the given URLs and returns a list of HTTP::Responses. You can test if the GET succeeded by using the HTTP::Response is_success method. If is_success returns 1, then use the content method to get the contents of the GET.

Geturls performs the GETs in parallel to speed execution and should be faster than performing individual gets.

Example printing the success and the content from each URL:

my @urls = ('http://perl.com/', 'file:/home/me/.sig');
my @response = get_urls(@urls);
foreach my $res (@response) {
  print "FOR URL ", $res->request->url;
  if ($res->is_success) {
    print "SUCCESS.  CONTENT IS\n", $res->content, "\n";
  }
  else {
    print "FAILED BECAUSE ", $res->message, "\n";
  }
}

put_urls string url [url [url ...]]

put_urls coderef url [url [url ...]]

Put the contents of string or the return from &coderef() into the listed urls. The destination urls must be either ftp: or file: and must specify a complete file; no directories are allowed. If the first form is used with string then the contents of string will be sent. If the second form is used, then coderef is a reference to a subroutine or anonymous CODE and &coderef() will be called repeatedly until it returns '' or undef and all of the text it returns will be stored in the urls.

Upon return, put_urls returns an array, where each element contains a HTTP::Response object corresponding to the success or failure of transferring the data to the i-th url. This object can be tested for the success or failure of the PUT by using the is_success method on the element. If the PUT was not successful, then the message method may be used to gather an error message explaining why the PUT failed. If there is invalid input to put_urls then put_urls returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context, and $@ contains a message containing explaining the invalid input.

For example, the following code, prints either YES or NO and a failure message if the put failed.

@a = put_urls('text',
              'http://www.perl.com/test.html',
              'file://some.other.host/test',
              'ftp://ftp.gps.caltech.edu/test');
foreach $put_res (@a) {
  print $put_res->request->url, ' ';
  if ($put_res->is_success) {
    print "YES\n";
  }
  else {
    print "NO ", $put_res->message, "\n";
  }
}

copy_url url_from url_to [base]

Copy the content contained in the URL url_from to the location specified by the URL url_to. url_from must contain the complete path to a file; no directories are allowed. url_to must be a file: or ftp: URL and may either be a directory or a file.

If supplied, base may be used to convert url_from and rurl_to from relative URLs to absolute URLs.

On return, copy_url returns 1 on success, 0 on otherwise. On failure $@ contains a message explaining the failure. See copy_urls if you want to quickly copy a single file to multiple places or copy multiple files to one directory or both. copy_urls provides simultaneous file transfers and will do the task much faster than calling copy_url many times over. If invalid input is given to copy_url, then it returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and $@ contains a message explaining the invalid input.

copy_urls url_file_from url_file_to [base]

copy_urls url_file_from url_dir_to [base]

Copy the content contained at the specified URLs to other locations also specified by URLs. The first argument to copy_urls is either a single URL or a reference to an array of URLs to copy. All of these URLs must contain the complete path to a file; no directories are allowed. The second argument may be a single URL or a reference to an array of URLS. If any of the destination URLs are a location of a file and not a directory, then only one URL can be passed as the first argument. If a reference to an array of URLs is passed as the second argument, then all URLs must point to directories, not files. Only file: and ftp: URLs may be used as the destination of the copy.

If supplied, base may be used to convert relative URLs to absolute URLs for all URLs supplied to copy_urls.

The copy operations of the multiple URLs are done in parallel to speed execution.

On return copy_urls returns a list of the LWP::Response from each GET performed on the from URLs. If there is invalid input to copy_urls then copy_urls returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and contains $@ a message explaining the error. The success or failure of each GET may be tested by using is_success method on each element of the list. If the GET succeeded (is_success returns TRUE), then hash element 'put_requests' exists and is a reference to a list of LWP::Responses containing the response to the PUT. For example, the following code prints a message containing the results from copy_urls:

  my @get_res = copy_urls(......);
  foreach my $get_res (@get_res) {
    my $url = $get_res->request->url;
    print "GET from $url ";
    unless ($get_res->is_success) {
      print "FAILED\n";
      next;
    }

    print "SUCCEEDED\n";
    foreach my $c (@{$get_res->{put_requests}}) {
      $url = $c->request->url;
      if ($c->is_success) {
        print "    to $url succeeded\n"
      }
      else {
        print "    to $url failed: ", $c->message, "\n";
      }
    }
  }

delete_urls url [url [url ...]]

Delete the files located by the urls and return a HTTP::Response for each url. If the url was successfully deleted, then the is_success method returns 1, otherwise it returns 0 and the message method contains the reason for the failure.

move_url from to [base]

Move the contents of the from URL to the to URL. If base is supplied, then the from and to URLs are converted from relative URLs to absolute URLs using base. If the move was successful, then move_url returns 1, otherwise it returns 0 and $@ contains a message explaining why the move failed. If invalid input was given to move_url then it returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and $@ contains a message explaining the invalid input.

list_url url

Return a list containing the filenames in the directory located at url. Only file and FTP directory URLs currently work. If for any reason the list can not be obtained, then list_url returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and $@ contains a message why list_url failed.

SEE ALSO

See also the HTTP::Response, HTTP::Request, and LWP::Simple manual pages.

AUTHOR

Blair Zajac <blair@gps.caltech.edu>

COPYRIGHT

Copyright (c) 1998 by Blair Zajac. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.