view release on metacpan or  search on metacpan

lib/File/HTTP.pod  view on Meta::CPAN

=head1 NAME

File::HTTP - open, read and seek into remote files and directories transparently

=head1 SYNOPSIS
    
    use File::HTTP qw(:open);
    
    # open and read a remote file (server must allow range queries)
    open(my $fh, '<', 'http://example.com/robots.txt') or die $!;
    
    while (<$fh>) {
        chomp;
        ...
    }
    
    # remote file is seekable in all directions
    seek($fh, 500, 0);
    read($fh, my $buf, 40);
    
    seek($fh, -40, 1);
    read($fh, my $buf2, 40);   

    # $/ behaves as with regular files
    local $/ = \52;
    $buf = <$fh>;
    
    # also works with https addresses if IO::Socket::SSL is available
    open(my $fh, '<', 'https://example.com/robots.txt') or die $!;
    
    # open() still works as expected with local files
    open(my $fh, '<', "local_file") or die $!;
    
    # directory (when servers allow directory listing)
    
    use File::HTTP qw(:opendir);
    
    opendir(my $dirh, 'http://example.com/files/') or die $!;
    
    while (my $file = readdir($dirh)) {
        next if $file =~ /^\.\.?$/;
        open(my $fh, '<', "http://example.com/files/$file") or die $!;
        ...
    }
    
    # open remote file, but not seekable
    # works with all web servers, and faster (real filehandler)
    
    use File::HTTP qw(open_stream);
    
    my $fh = open_stream('http://example.com/file') or die $!;
    while (<$fh>) {
        chomp;
	...
    }

    # make your module HTTP compatible when File::HTTP is installed.
    # on top of module:
    eval {use File::HTTP qw(:open)};
    
=head1 DESCRIPTION

C<File::HTTP> open, read and seek into remote files and directories transparently

=over 4

=item open [MODE] FILE

=item stat FH or FILE

Imported with the :open tag.

Act exaclty as CORE::open and CORE::stat, but also work with remote HTTP files.

Falls back to CORE::open and CORE::stat when the path looks like a local file.

Returns a Tied filehanlder when opening a remote file.

Only works with Web servers that allow range queries (see CAVEATS).

You should use C<open_stream> when servers do not allow range queries.

=item opendir DIR

=item readdir / rewinddir / telldir / seekdir / closedir DIRH

Imported with the :opendir tag.

Act exaclty as CORE::opendir and associated CORE functions, but also work with
remote HTTP directories.

Falls back to CORE::opendir when the path looks like a local directory.

Returns a Tied filehanlder when opening a remote directory.

Only works with Web servers that allow directory listing.

=item opendir_slash DIR

Similar to C<opendir>, but preserve final slash when present to make it easier
to differenciate directories and files.
(This was what C<opendir> did up to version 0.91, but was removed as it was
not in line with CORE::opendir's behavior)

=item open_stream URL

open a readable but not seekable filehandle to the specified URL

=item slurp_stream URL

context dependent slurping of an url

    my $content = slurp_stream($url);
    my @lines = slurp_stream($url);

=item get URL [follow redirections]

slurps an url into a string, also also returning request and response
headers strings in list context.
Contrary to slrup_stream, default behavior is to ignore redirections

    my $body = get($url);
    my $body = get($url, 1); # follow redirections