HTML::Location - Working with disk to URI file mappings (deprecated: see
URI::ToDisk)
As correctly noted by several users, "HTML::Location" is a really
stupid name for this module. I apologise, I was new to the whole CPAN game at
the time I first wrote it.
This module has been relocated to URI::ToDisk. This module will remain
indefinately for back-compatibility, but should otherwise be
considered
deprecated.
Please convert your code to the otherwise identical URI::ToDisk at your leisure.
# We have a directory on disk that is accessible via a web server
my $authors = HTML::Location->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 "HTML::Location" 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>.
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 HTML::Location way
my $location = HTML::Location->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
HTML::Location->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 = HTML::Location->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.
Returns a new "HTML::Location" object on success, or "undef"
on failure.
"param" is provided as a mechanism for higher order modules to
flexibly accept HTML::Location's as parameters. In this case, it accepts
either an existing HTML::Location object, two arguments ($path, $http_url), or
a reference to an array containing the same two arguments.
Returns a HTML::Location if possible, or "undef" if one cannot be
provided.
The "uri" method gets and returns the current URI of the location, in
string form.
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.
The "path" method returns the filesystem path componant of the
location.
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 HTML::Location 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 HTML::Location 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=HTML-Location>
For other issues, or commercial enhancement or support, contact the author.
Adam Kennedy <adamk@cpan.org>
Copyright 2003 - 2008 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.