Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTML::Location(3)     User Contributed Perl Documentation    HTML::Location(3)

       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

       Please convert your code	to the otherwise identical URI::ToDisk at your

	 # We have a directory on disk that is accessible via a	web server
	 my $authors = HTML::Location->new( '/var/www/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

   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

	 # 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', '' );
	 $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', ''	)->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', ''	);
	 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.

   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

   param $various
       "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

       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

       The "path" method returns the filesystem	path componant of the

   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.

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

       Bugs should be reported via the CPAN bug	tracker	at


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

       Adam Kennedy <>

       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.

perl v5.32.0			  2008-07-09		     HTML::Location(3)


Want to link to this manual page? Use this URL:

home | help