NAME
   HTML::Location - Working with disk to URI file mappings (deprecated: see
   URI::ToDisk)

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

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 $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";

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 <File::Spec::Unix>.

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

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.

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

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

 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
   Add more File::Spec-y methods as needed. Ask if you need one.

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

AUTHORS
   Adam Kennedy <http://ali.as/>, [email protected]

COPYRIGHT
   Copyright (c) 2003 - 2005 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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.