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

FreeBSD Manual Pages


home | help
URI::ToDisk(3)	      User Contributed Perl Documentation	URI::ToDisk(3)

       URI::ToDisk - An	object for mapping a URI to an on-disk storage

	 # We have a directory on disk that is accessible via a	web server
	 my $authors = URI::ToDisk->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 "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

   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 URI::ToDisk way
	 my $location =	URI::ToDisk->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

	 URI::ToDisk->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 = URI::ToDisk->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 "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

       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 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.

       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 (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.

perl v5.32.1			  2007-11-12			URI::ToDisk(3)


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

home | help