URI::ToDisk (3pm)

  # 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";

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 \s-1URL\s0. From this location, we should be able to derived both a filesystem path and \s-1URL\s0 for any given directory or file under this location that we might need to work with.

Implementation

Internally each \*(C`URI::ToDisk\*(C' object contains both a filesystem path, which is altered using File::Spec, and a \s-1URI\s0 object. When making a change, the path section of the \s-1URI\s0 is altered using <File::Spec::Unix>.

Method Calling Conventions

The main functional methods, such as \*(C`catdir\*(C' and \*(C`catfile\*(C', 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' );

\s-1OK\s0, well it's not exactly \s-1THAT\s0 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.

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

Returns a new \*(C`URI::ToDisk\*(C' object on success, or \*(C`undef\*(C' on failure. \*(C`param\*(C' 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 \*(C`undef\*(C' if one cannot be provided.

uri

The \*(C`uri\*(C' method gets and returns the current \s-1URI\s0 of the location, in string form.

\s-1URI\s0

The capitalised \*(C`URI\*(C' method gets and returns a copy of the raw \s-1URI\s0, held internally by the location. Note that only a copy is returned, and as such as safe to further modify yourself without effecting the location.

path

The \*(C`path\*(C' method returns the filesystem path componant of the location.

catdir 'dir', 'dir', ...

A File::Spec workalike, the \*(C`catdir\*(C' method acts in the same way as for File::Spec, modifying both componants of the location. The \*(C`catdir\*(C' method returns a new URI::ToDisk object representing the new location, or \*(C`undef\*(C' on error. Like \*(C`catdir\*(C', the \*(C`catfile\*(C' method acts in the same was as for File::Spec, and returns a new URI::ToDisk object representing the file, or \*(C`undef\*(C' on error.

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

Bugs should be reported via the \s-1CPAN\s0 bug tracker at

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

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

Adam Kennedy <http://ali.as/>, [email protected]

Copyright (c) 2003 - 2006 Adam Kennedy.

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 \s-1LICENSE\s0 file included with this module.