URI::ToDisk - An object for mapping a URI to an on-disk storage directory
# 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 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.
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>.
URI::ToDisk
The main functional methods, such as catdir and catfile, do not modify the original object, instead returning a new object containing the new location.
catdir
catfile
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.
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.
new
undef
Returns a new URI::ToDisk object on success, or undef on failure.
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.
param
Returns a URI::ToDisk if possible, or undef if one cannot be provided.
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.
URI
The path method returns the filesystem path componant of the location.
path
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.
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.
Add more File::Spec-y methods as needed. Ask if you need one.
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.
Adam Kennedy http://ali.as/, cpan@ali.as
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.
To install URI::ToDisk, copy and paste the appropriate command in to your terminal.
cpanm
cpanm URI::ToDisk
CPAN shell
perl -MCPAN -e shell install URI::ToDisk
For more information on module installation, please visit the detailed CPAN module installation guide.