NAME

URI::ToDisk - An object for mapping a URI to an on-disk storage directory

SYNOPSIS

  # We have a directory on disk that is accessible via a web server
  my $authors = URI::ToDisk->new( '/var/www/AUTHORS', 'http://ali.as/AUTHORS' );
  
  # We know where a particular generated file needs to go
  my $about = $authors->catfile( 'A', 'AD', 'ADAMK', 'about.html' );
  
  # Save the file to disk
  my $file = $about->path;
  open( FILE, ">$file" ) or die "open: $!";
  print FILE, $content;
  close FILE;
  
  # Show the user where to see the file
  my $uri = $about->uri;
  print "Author information is at $uri\n";

DESCRIPTION

In several process relating to working with the web, we may need to keep track of an area of disk that maps to a particular URL. From this location, we should be able to derived both a filesystem path and URL for any given directory or file under this location that we might need to work with.

Implementation

Internally each "URI::ToDisk" object contains both a filesystem path, which is altered using File::Spec, and a URI object. When making a change, the path section of the URI is altered using <File::Spec::Unix>.

Method Calling Conventions

The main functional methods, such as "catdir" and "catfile", do not modify the original object, instead returning a new object containing the new location.

This means that it should be used in a somewhat similar way to File::Spec.

  # The File::Spec way
  my $path = '/some/path';
  $path = File::Spec->catfile( $path, 'some', 'file.txt' );
  
  # The URI::ToDisk way
  my $location = URI::ToDisk->new( '/some/path', 'http://foo.com/blah' );
  $location = $location->catfile( 'some', 'file.txt' );

OK, well it's not exactly THAT close, but you get the idea. It also allows you to do method chaining, which is basically

  URI::ToDisk->new( '/foo', 'http://foo.com/' )->catfile( 'bar.txt' )->uri

Which may seem a little trivial now, but I expect it to get more useful later. It also means you can do things like this.

  my $base = URI::ToDisk->new( '/my/cache', 'http://foo.com/' );
  foreach my $path ( @some_files ) {
        my $file = $base->catfile( $path );
        print $file->path . ': ' . $file->uri . "\n";
  }

In the above example, you don't have to be continuously cloning the location, because all that stuff happens internally as needed.

METHODS

new $path, $http_url

The "new" constructor takes as argument a filesystem path and a http(s) URL. Both are required, and the method will return "undef" is either is illegal. The URL is not required to have protocol, host or port sections, and as such allows for host-relative URL to be used.

Returns a new "URI::ToDisk" object on success, or "undef" on failure.

param $various

"param" is provided as a mechanism for higher order modules to flexibly accept URI::ToDisk's as parameters. In this case, it accepts either an existing URI::ToDisk object, two arguments ($path, $http_url), or a reference to an array containing the same two arguments.

Returns a URI::ToDisk if possible, or "undef" if one cannot be provided.

TO DO

Add more File::Spec-y methods as needed. Ask if you need one.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-ToDisk>

For other issues, or commercial enhancement or support, contact the author.

AUTHORS

Adam Kennedy <http://ali.as/>, cpan@ali.as

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.