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.

   uri
       The "uri" method gets and returns the current URI of the location, in string form.

   URI
       The capitalised "URI" method gets and returns a copy of the raw URI, 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 "path" method returns the filesystem path componant of the location.

   catdir 'dir', 'dir', ...
       A File::Spec workalike, the "catdir" method acts in the same way as for File::Spec,
       modifying both componants of the location. The "catdir" method returns a new URI::ToDisk
       object representing the new location, or "undef" on error.

   catfile [ 'dir', ..., ] $file
       Like "catdir", the "catfile" method acts in the same was as for File::Spec, and returns a
       new URI::ToDisk object representing the file, or "undef" on error.

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

       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 LICENSE file included with this module.