/ 
File-HTTP-1.11
River stage zero No dependents
/ File::HTTP

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 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)};

DESCRIPTION

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

open [MODE] FILE
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 open_stream when servers do not allow range queries.

opendir DIR
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.

opendir_slash DIR

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

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);
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
my ($request_headers, $response_headers, $body) = get($url);

If set to follow redirections, $request_headers and $response_headers will correspond to the last emitted request.

post URL TYPE BODY

Similar to get but with a post request, with a content-type,and a body. Always ignore redirections.

open_at URL OFFSET

Similar to to open, but with an offset. It is more efficient than using open and seek when the offset is already known, as it saves an HTTP request.

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

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.