NAME

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

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
    seek($fh, 500, 0);
    read(my $fh, my $buf, 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)};
    

DESCRIPTION

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

open [MODE] FILE

stat FH or FILE

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 open_stream when servers do not allow range queries.

opendir DIR

readdir/rewinddir/telldir/seekdir/closedir DIRH

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

open_stream URL

open a readable but not seekable filehandle to the specified URL

slurp_stream URL

context dependent slurping of an url

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

open_at URL

EXPORTS

Nothing by default. Functions can be imported explicitely

use File::HTTP qw(open open_stream opendir readdir);

:open and :opendir tags are much prefered as they will ensure all needed functions are exported

use File::HTTP qw(:open);
# same as:
use File::HTTP qw(open stat);

use File::HTTP qw(:opendir);
# same as:
use File::HTTP qw(opendir readdir rewinddir telldir seekdir closedir);

You can use the :all tag to import all functions

use File::HTTP qw(:all);

You can also use the -everywhere tag to export emulation function into all namespaces (dangerous!)

use File::HTTP qw(-everywhere);

# now all modules shall magicaly work with remote files (or not)

CAVEATS

open only works with remote web server and ressources that allow range queries. Dynamic ressources such as PHP or CGI typically do not work with range queries. open_stream does not have such limitations, but does not allow seeks.

opendir only works with remote web servers and ressources that allow directory listing, and list files as a simple <a href> links.

OPTIONAL MODULES

• IO::Socket::SSL is required for HTTPS URLs

• Either Time::y2038 or Time::Local will be used to set the modification date in state

TODO

• better $! error mapping

• auto adaptation of seek vs read based on time

• buffering

• tests...

SEE ALSO

Tie::Handle::HTTP

AUTHOR

Thomas Drugeon, <tdrugeon@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Thomas Drugeon

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

cpanm File::HTTP

perl -MCPAN -e shell
install File::HTTP