NAME
HTML::Location - Working with disk to URI file mappings
SYNOPSIS
# 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 $file = $authors->catfile( 'A', 'AD', 'ADAMK', 'about.html' );
# Save the file to disk
my $filesystempath = $Location->path;
open( FILE, ">$filesystem" ) or die "open: $!";
print FILE, $content;
close FILE;
# Show the user where to see the file
my $url = $Location->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 "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 .
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 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 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 conmtinuously 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 "HTML::Location" object on success, or "undef" on failure.
uri
The "uri" method gets and returns the current URL 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 HTML::Location 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 HTML::Location object representing the
file, or "undef" on error.
TO DO
This package currently contains only minimum of methods required to be
useful, and is primily a convenience at this point.
Additional methods will be added over time, and additional checks to
catch cases such as catching cases where we may produce a valid
filesystem path, but the URL would become incorrect.
For now, it is not recommended to use HTML::Location to move upwards
through the path.
SUPPORT
Bugs should be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML%3A%3ALocation
For other issues, contact the author
AUTHORS
Adam Kennedy ( maintainer )
cpan@ali.as
http://ali.as/
COPYRIGHT
Copyright (c) 2003 Adam Kennedy. All rights reserved. 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.